@forgeax/engine-rhi 0.1.2

package/src/__tests__/queue-writes.test-d.ts

@@ -0,0 +1,107 @@
+// AC-08 (Q5) — RhiQueue.writeTexture + copyExternalImageToTexture Pick<spec>
+// narrow type-layer assertions.
+//
+// D-P5 (plan-strategy §spec-rename) — the spec evolved field-info wrappers;
+// pre-rename names (authored Jan 2024, retired Apr 2026) are no longer
+// present in @webgpu/types 0.1.69 and the rhi interface now uses the
+// authoritative new names (GPUCopyExternalImageSourceInfo +
+// GPUCopyExternalImageDestInfo per W3C WebGPU CR Apr 2026); any regression
+// would surface as TS2304 at type lookup. Historical rename context lives
+// in .forgeax-harness/forgeax-loop/feat-20260511-asset-system-v1/research.md
+// D-P5 + requirements research Finding 1(a) + Finding 3(a); the pre-rename
+// names are deliberately NOT quoted here so the `GPUImg*` grep gate
+// (feat-20260511-asset-system-v1 / w32) returns 0 hits repo-wide.
+//
+// w17 contract:
+//   (a) writeTexture(destination, data, dataLayout, size) where:
+//       destination is Pick<GPUTexelCopyTextureInfo, ...> (NOT verbatim spec);
+//       dataLayout is Pick<GPUTexelCopyBufferLayout, ...>.
+//   (b) copyExternalImageToTexture(source, destination, copySize) where:
+//       source is Pick<GPUCopyExternalImageSourceInfo, ...> (spec rename);
+//       destination is Pick<GPUCopyExternalImageDestInfo, ...> (spec rename).
+//   (c) r12-lint Pick<GPU*Descriptor count >= 20 follow-on (verified by w22
+//       gate, not this test-d).
+//
+// Charter: proposition 4 (explicit failure - excess fields trip TS2375 at the
+// call site) + proposition 5 (consistent abstraction - dual backends mirror
+// the same Pick<> narrowing). Anchors: requirements AC-08; research R-04
+// §4.1-§4.3; plan-strategy D-P5 spec rename critical fact.
+
+/// <reference types="@webgpu/types" />
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type { Buffer, Result, RhiError, RhiQueue, Texture, TextureView } from '../index';
+
+/** Strict structural equality helper. */
+type Equals<X, Y> =
+  (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
+
+describe('AC-08 — RhiQueue.writeTexture Pick<spec> narrow', () => {
+  it('writeTexture method exists on RhiQueue', () => {
+    type Method = RhiQueue['writeTexture'];
+    expectTypeOf<Method>().toBeFunction();
+  });
+
+  it('writeTexture destination param strictly equals Pick<GPUTexelCopyTextureInfo, ...> (no extra fields)', () => {
+    type DestParam = Parameters<RhiQueue['writeTexture']>[0];
+    type ExpectedShape = Pick<
+      GPUTexelCopyTextureInfo,
+      'texture' | 'mipLevel' | 'origin' | 'aspect'
+    >;
+    // Strict equality — DestParam has EXACTLY the four spec fields. AI users
+    // passing extra forgeax-invented fields trip TS2375 at call site;
+    // missing required `texture` field trips TS2741.
+    type IsExact = Equals<DestParam, ExpectedShape>;
+    expectTypeOf<IsExact>().toEqualTypeOf<true>();
+  });
+
+  it('writeTexture dataLayout param strictly equals Pick<GPUTexelCopyBufferLayout, ...>', () => {
+    type LayoutParam = Parameters<RhiQueue['writeTexture']>[2];
+    type ExpectedShape = Pick<GPUTexelCopyBufferLayout, 'offset' | 'bytesPerRow' | 'rowsPerImage'>;
+    type IsExact = Equals<LayoutParam, ExpectedShape>;
+    expectTypeOf<IsExact>().toEqualTypeOf<true>();
+  });
+
+  it('writeTexture returns Result<void, RhiError>', () => {
+    type Ret = ReturnType<RhiQueue['writeTexture']>;
+    type IsResult = Equals<Ret, Result<void, RhiError>>;
+    expectTypeOf<IsResult>().toEqualTypeOf<true>();
+  });
+});
+
+describe('AC-08 — RhiQueue.copyExternalImageToTexture Pick<spec> narrow + spec rename', () => {
+  it('copyExternalImageToTexture method exists on RhiQueue', () => {
+    type Method = RhiQueue['copyExternalImageToTexture'];
+    expectTypeOf<Method>().toBeFunction();
+  });
+
+  it('source param strictly equals Pick<GPUCopyExternalImageSourceInfo, ...> (spec rename D-P5)', () => {
+    type SourceParam = Parameters<RhiQueue['copyExternalImageToTexture']>[0];
+    type ExpectedShape = Pick<GPUCopyExternalImageSourceInfo, 'source' | 'origin' | 'flipY'>;
+    type IsExact = Equals<SourceParam, ExpectedShape>;
+    expectTypeOf<IsExact>().toEqualTypeOf<true>();
+  });
+
+  it('destination param strictly equals Pick<GPUCopyExternalImageDestInfo, ...> (spec rename D-P5)', () => {
+    type DestParam = Parameters<RhiQueue['copyExternalImageToTexture']>[1];
+    type ExpectedShape = Pick<
+      GPUCopyExternalImageDestInfo,
+      'texture' | 'mipLevel' | 'origin' | 'aspect' | 'colorSpace' | 'premultipliedAlpha'
+    >;
+    type IsExact = Equals<DestParam, ExpectedShape>;
+    expectTypeOf<IsExact>().toEqualTypeOf<true>();
+  });
+
+  it('copyExternalImageToTexture returns Result<void, RhiError>', () => {
+    type Ret = ReturnType<RhiQueue['copyExternalImageToTexture']>;
+    type IsResult = Equals<Ret, Result<void, RhiError>>;
+    expectTypeOf<IsResult>().toEqualTypeOf<true>();
+  });
+});
+
+// Sanity peg — keep Buffer / Texture / TextureView in scope so they don't get
+// stripped by tree-shake import elision (the rhi entry rolls these up so
+// downstream consumers can grep on the forgeax handle names).
+type _Peg = { b: Buffer; t: Texture; tv: TextureView };
+declare const _peg: _Peg;
+void _peg;

package/src/__tests__/queue-writes.unit.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveBufferWriteRange } from '../queue-writes';
+
+describe('resolveBufferWriteRange', () => {
+  it('uses typed-array elements and preserves a non-zero view byteOffset', () => {
+    const source = new Float32Array([10, 20, 30, 40, 50]);
+    const view = source.subarray(1);
+    const range = resolveBufferWriteRange(view, 1, 2);
+
+    expect(range).toBeDefined();
+    expect(range?.byteOffset).toBe(4);
+    expect(range?.byteSize).toBe(8);
+    expect([...((range?.bytes ?? new Uint8Array()) as Uint8Array)]).toEqual([
+      ...new Uint8Array(view.buffer, view.byteOffset + 4, 8),
+    ]);
+  });
+
+  it('uses bytes for ArrayBuffer and DataView sources', () => {
+    const source = new ArrayBuffer(8);
+    const view = new DataView(source, 2, 4);
+    expect(resolveBufferWriteRange(source, 2, 3)?.byteSize).toBe(3);
+    expect(resolveBufferWriteRange(view, 1, 2)?.byteOffset).toBe(1);
+    expect(resolveBufferWriteRange(view, 1, 2)?.byteSize).toBe(2);
+  });
+
+  it('rejects an element range outside the source view', () => {
+    expect(resolveBufferWriteRange(new Float32Array(2), 1, 2)).toBeUndefined();
+  });
+});

package/src/__tests__/render-pass-encoder-spec-alignment.test-d.ts

@@ -0,0 +1,202 @@
+// w4 type-level - RhiRenderPassEncoder spec method-set alignment (research F-2 /
+// plan-strategy D-S4: 17 spec stable + 1 setBindGroup overload + 3 placeholder).
+//
+// Asserts (RED until w5 lands the impl):
+//   - 17 spec stable methods exist on RhiRenderPassEncoder
+//   - setBindGroup has both overloads (a) array form (b) Uint32Array form
+//   - 3 placeholder methods (executeBundles / beginOcclusionQuery /
+//     endOcclusionQuery) are present in the interface and return
+//     Result<void, RhiError> (so AI users can route 'rhi-not-available' at
+//     runtime; charter proposition 4 explicit failure).
+//   - setImmediates (PROPOSED) is NOT exposed (per D-S4 explicit non-receipt;
+//     charter proposition 4: untested features hide behind caps, not surfaces).
+//
+// Method NAMES align byte-for-byte with `@webgpu/types`
+// GPURenderPassEncoder + GPURenderCommandsMixin + GPUBindingCommandsMixin +
+// GPUDebugCommandsMixin (research F-2).
+//
+// Charter mapping: proposition 1 (progressive disclosure: AI sees the full
+// spec surface in one read) + proposition 5 (consistent abstraction: spec
+// stable methods land here regardless of capability).
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  BindGroup,
+  Buffer,
+  RenderPassColorAttachment,
+  RenderPassDepthStencilAttachment,
+  Result,
+  RhiError,
+  RhiRenderPassEncoder,
+  Texture,
+  TextureView,
+} from '../index';
+
+describe('w4 - RhiRenderPassEncoder spec method set (17 stable + 1 overload + 3 placeholders)', () => {
+  // 7 already-shipped methods (Round 1 baseline; locked in this closure):
+  it('keeps existing setPipeline / setIndexBuffer / setVertexBuffer', () => {
+    expectTypeOf<RhiRenderPassEncoder['setPipeline']>().toBeFunction();
+    expectTypeOf<RhiRenderPassEncoder['setIndexBuffer']>().toBeFunction();
+    expectTypeOf<RhiRenderPassEncoder['setVertexBuffer']>().toBeFunction();
+  });
+
+  it('keeps existing draw / drawIndexed / end', () => {
+    expectTypeOf<RhiRenderPassEncoder['draw']>().toBeFunction();
+    expectTypeOf<RhiRenderPassEncoder['drawIndexed']>().toBeFunction();
+    expectTypeOf<RhiRenderPassEncoder['end']>().toBeFunction();
+  });
+
+  // 10 new spec stable methods (research F-2; D-S4 IN list):
+  it('exposes setViewport(x, y, w, h, minDepth, maxDepth)', () => {
+    expectTypeOf<RhiRenderPassEncoder['setViewport']>().toBeFunction();
+    type Expected = (
+      x: number,
+      y: number,
+      w: number,
+      h: number,
+      minDepth: number,
+      maxDepth: number,
+    ) => void;
+    expectTypeOf<Expected>().toMatchTypeOf<RhiRenderPassEncoder['setViewport']>();
+  });
+
+  it('exposes setScissorRect(x, y, w, h)', () => {
+    expectTypeOf<RhiRenderPassEncoder['setScissorRect']>().toBeFunction();
+  });
+
+  it('exposes setBlendConstant(color)', () => {
+    expectTypeOf<RhiRenderPassEncoder['setBlendConstant']>().toBeFunction();
+  });
+
+  it('exposes setStencilReference(reference)', () => {
+    expectTypeOf<RhiRenderPassEncoder['setStencilReference']>().toBeFunction();
+  });
+
+  it('exposes drawIndirect(buffer, offset)', () => {
+    expectTypeOf<RhiRenderPassEncoder['drawIndirect']>().toBeFunction();
+  });
+
+  it('exposes drawIndexedIndirect(buffer, offset)', () => {
+    expectTypeOf<RhiRenderPassEncoder['drawIndexedIndirect']>().toBeFunction();
+  });
+
+  it('exposes pushDebugGroup / popDebugGroup / insertDebugMarker (DebugCommandsMixin)', () => {
+    expectTypeOf<RhiRenderPassEncoder['pushDebugGroup']>().toBeFunction();
+    expectTypeOf<RhiRenderPassEncoder['popDebugGroup']>().toBeFunction();
+    expectTypeOf<RhiRenderPassEncoder['insertDebugMarker']>().toBeFunction();
+  });
+
+  // setBindGroup has 2 overloads per spec:
+  it('setBindGroup overload (a): array form (existing)', () => {
+    type ArrayForm = (
+      index: number,
+      bindGroup: BindGroup,
+      dynamicOffsets?: readonly number[] | undefined,
+    ) => void;
+    type HasArrayOverload = RhiRenderPassEncoder['setBindGroup'] extends ArrayForm ? true : false;
+    expectTypeOf<HasArrayOverload>().toEqualTypeOf<true>();
+  });
+
+  it('setBindGroup overload (b): Uint32Array slice form (new in this closure)', () => {
+    type SliceForm = (
+      index: number,
+      bindGroup: BindGroup,
+      dynamicOffsetsData: Uint32Array,
+      dynamicOffsetsDataStart: number,
+      dynamicOffsetsDataLength: number,
+    ) => void;
+    type HasSliceOverload = RhiRenderPassEncoder['setBindGroup'] extends SliceForm ? true : false;
+    expectTypeOf<HasSliceOverload>().toEqualTypeOf<true>();
+  });
+
+  // 3 placeholders: signature lives in the interface; shim returns Result.err
+  // ({ code: 'rhi-not-available' }) at runtime per D-S4.
+  it('exposes executeBundles (placeholder; capability-gated by RenderBundle)', () => {
+    type Method = RhiRenderPassEncoder['executeBundles'];
+    expectTypeOf<Method>().toBeFunction();
+    expectTypeOf<Method>().returns.toEqualTypeOf<Result<void, RhiError>>();
+  });
+
+  it('exposes beginOcclusionQuery (placeholder; capability-gated by QuerySet)', () => {
+    type Method = RhiRenderPassEncoder['beginOcclusionQuery'];
+    expectTypeOf<Method>().toBeFunction();
+    expectTypeOf<Method>().returns.toEqualTypeOf<Result<void, RhiError>>();
+  });
+
+  it('exposes endOcclusionQuery (placeholder; capability-gated by QuerySet)', () => {
+    type Method = RhiRenderPassEncoder['endOcclusionQuery'];
+    expectTypeOf<Method>().toBeFunction();
+    expectTypeOf<Method>().returns.toEqualTypeOf<Result<void, RhiError>>();
+  });
+
+  it('does NOT expose setImmediates (PROPOSED; D-S4 explicit non-receipt)', () => {
+    // Type-level guard: the field must NOT exist on the interface so that
+    // AI users see a tsc red signal if they attempt to call it.
+    type HasSetImmediates = 'setImmediates' extends keyof RhiRenderPassEncoder ? true : false;
+    expectTypeOf<HasSetImmediates>().toEqualTypeOf<false>();
+  });
+
+  // Buffer reference smoke (sanity: arg types use forgeax opaque handles).
+  it('drawIndirect uses forgeax Buffer (opaque handle, not raw GPUBuffer)', () => {
+    type Method = RhiRenderPassEncoder['drawIndirect'];
+    type Expected = (indirectBuffer: Buffer, indirectOffset: number) => void;
+    expectTypeOf<Expected>().toMatchTypeOf<Method>();
+  });
+});
+
+// w14 - view narrow Path X breakage point #1 (requirements IN-2 / AC-02 /
+// research 8.2): the 4 view fields move from `Texture` (D-S5 temporary
+// tightening) to `TextureView` (the spec-aligned target after M1 shipped
+// `device.createTextureView`).
+//
+// Field count breakdown (research 8.2 IMPORTANT box):
+//   - 1 direct: RenderPassColorAttachment.view
+//   - 1 direct: RenderPassColorAttachment.resolveTarget?
+//   - 1 direct: RenderPassDepthStencilAttachment.view
+//   - 1 indirect: RenderPassDescriptor.colorAttachments[N].view propagates
+//     through the element type of RenderPassColorAttachment (covered by the
+//     direct assertion on RenderPassColorAttachment.view).
+//
+// Red expected state: this block fails tsc -b before w15 lands the narrow
+//   (current types are `Texture`; `expectAssignable<TextureView>` fails because
+//   Texture and TextureView are disjoint brand types).
+// Green expected state (after w15 commit): all expectTypeOf assertions pass.
+//
+// Charter mapping: proposition 4 (explicit failure: AI users get a tsc red
+// signal at the call site instead of a runtime swap) + proposition 5
+// (consistent abstraction: the field type matches what `createTextureView`
+// returns).
+describe('w14 - view narrow Path X (breakage point #1): RenderPassColorAttachment.view / .resolveTarget / RenderPassDepthStencilAttachment.view = TextureView', () => {
+  it('RenderPassColorAttachment.view is TextureView (not Texture)', () => {
+    type ViewField = RenderPassColorAttachment['view'];
+    expectTypeOf<ViewField>().toEqualTypeOf<TextureView>();
+  });
+
+  it('RenderPassColorAttachment.view rejects Texture brand', () => {
+    type ViewField = RenderPassColorAttachment['view'];
+    type TextureAssignsToView = Texture extends ViewField ? true : false;
+    expectTypeOf<TextureAssignsToView>().toEqualTypeOf<false>();
+  });
+
+  it('RenderPassColorAttachment.resolveTarget is TextureView | undefined (not Texture | undefined)', () => {
+    type ResolveTargetField = RenderPassColorAttachment['resolveTarget'];
+    expectTypeOf<ResolveTargetField>().toEqualTypeOf<TextureView | undefined>();
+  });
+
+  it('RenderPassColorAttachment.resolveTarget rejects Texture brand', () => {
+    type ResolveTargetField = NonNullable<RenderPassColorAttachment['resolveTarget']>;
+    type TextureAssignsToResolveTarget = Texture extends ResolveTargetField ? true : false;
+    expectTypeOf<TextureAssignsToResolveTarget>().toEqualTypeOf<false>();
+  });
+
+  it('RenderPassDepthStencilAttachment.view is TextureView (not Texture)', () => {
+    type ViewField = RenderPassDepthStencilAttachment['view'];
+    expectTypeOf<ViewField>().toEqualTypeOf<TextureView>();
+  });
+
+  it('RenderPassDepthStencilAttachment.view rejects Texture brand', () => {
+    type ViewField = RenderPassDepthStencilAttachment['view'];
+    type TextureAssignsToView = Texture extends ViewField ? true : false;
+    expectTypeOf<TextureAssignsToView>().toEqualTypeOf<false>();
+  });
+});

package/src/__tests__/requestAdapter.test-d.ts

@@ -0,0 +1,123 @@
+// w17 - RhiInstance + RhiAdapter type-level contract test (TDD red).
+//
+// Locks M3 break-point #2 surface (plan-tasks w17 / requirements IN-4 / AC-04;
+// plan-strategy K-5 + K-6):
+//   RhiInstance.requestAdapter(opts?): Promise<Result<RhiAdapter, RhiError>>
+//   RhiAdapter.features: ReadonlySet<GPUFeatureName>  (Round 3 fix-up F-P1-2:
+//     was ReadonlyArray<string>; aligned with RhiDevice.features for cross-
+//     tier shape uniformity — AI users use `.has(name)` on both layers)
+//   RhiAdapter.limits: Readonly<Record<string, number>>
+//   RhiAdapter.requestDevice(opts?): Promise<Result<RhiDevice, RhiError>>
+//
+// Strict two-step path mirrors wgpu / Dawn source (research §6); break-point
+// #2 deprecates the top-level `rhi.requestDevice(opts)` factory in favour of
+// `rhi.requestAdapter() -> adapter.requestDevice(opts)`.
+//
+// Red expected: tsc -b fails with TS2305 / TS2339 (missing RhiInstance /
+// RhiAdapter / RequestAdapterOptions / RequestDeviceOptions). Turns green
+// after w18 ships.
+//
+// F-1 ai-user-review absorption: readonly REVERSE assertions ensure mutation
+// of `features[0]` / `limits['x']` is rejected at compile time (charter
+// proposition 4 explicit failure + proposition 5 consistent abstraction).
+//
+// Anchors: requirements §IN-4 / §AC-04 / break-point #2; research §6.1 + §6.2
+//          + §6.3 wgpu / Dawn strict two-step source; plan-strategy §2 K-5 +
+//          K-6 + §6 M3 + K-10.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  RequestAdapterOptions,
+  RequestDeviceOptions,
+  Result,
+  RhiAdapter,
+  RhiDevice,
+  RhiError,
+  RhiInstance,
+} from '../index';
+
+describe('w17 type-level - RhiInstance.requestAdapter signature (K-5 / break-point #2)', () => {
+  it('returns Promise<Result<RhiAdapter, RhiError>>', () => {
+    type Sig = RhiInstance['requestAdapter'];
+    type Ret = ReturnType<Sig>;
+    expectTypeOf<Ret>().toEqualTypeOf<Promise<Result<RhiAdapter, RhiError>>>();
+  });
+
+  it('takes optional RequestAdapterOptions + compatibleSurface parameters', () => {
+    type Sig = RhiInstance['requestAdapter'];
+    type Params = Parameters<Sig>;
+    expectTypeOf<Params>().toEqualTypeOf<
+      [
+        opts?: RequestAdapterOptions | undefined,
+        compatibleSurface?: HTMLCanvasElement | OffscreenCanvas | undefined,
+      ]
+    >();
+  });
+});
+
+describe('w17 type-level - RhiAdapter.features is ReadonlySet<GPUFeatureName> (K-5 / F-P1-2)', () => {
+  it('features field type is ReadonlySet<GPUFeatureName>', () => {
+    expectTypeOf<RhiAdapter['features']>().toEqualTypeOf<ReadonlySet<GPUFeatureName>>();
+  });
+
+  it('mutating features.add(...) is rejected at compile time (F-1 readonly REVERSE)', () => {
+    const adapter = {} as RhiAdapter;
+    // @ts-expect-error F-1 ai-user-review: ReadonlySet rejects .add()
+    adapter.features.add('timestamp-query');
+  });
+
+  it('mutating features.delete(...) is rejected at compile time (F-1)', () => {
+    const adapter = {} as RhiAdapter;
+    // @ts-expect-error F-1 ai-user-review: ReadonlySet rejects .delete()
+    adapter.features.delete('timestamp-query');
+  });
+
+  it('mutating features.clear() is rejected at compile time (F-1)', () => {
+    const adapter = {} as RhiAdapter;
+    // @ts-expect-error F-1 ai-user-review: ReadonlySet rejects .clear()
+    adapter.features.clear();
+  });
+
+  it('reassigning features whole set is rejected at compile time (F-1)', () => {
+    const adapter = {} as RhiAdapter;
+    // @ts-expect-error features is a readonly property
+    adapter.features = new Set();
+  });
+
+  it('.has(name) is the supported read API (cross-tier uniform with RhiDevice.features)', () => {
+    const adapter = {} as RhiAdapter;
+    expectTypeOf(adapter.features.has('timestamp-query')).toEqualTypeOf<boolean>();
+  });
+});
+
+describe('w17 type-level - RhiAdapter.limits is Readonly<Record<string, number>> (K-5)', () => {
+  it('limits field type is Readonly<Record<string, number>>', () => {
+    expectTypeOf<RhiAdapter['limits']>().toEqualTypeOf<Readonly<Record<string, number>>>();
+  });
+
+  it('mutating limits["x"] is rejected at compile time (F-1 readonly REVERSE)', () => {
+    const adapter = {} as RhiAdapter;
+    // @ts-expect-error F-1 ai-user-review: limits['x'] write is rejected by TS
+    adapter.limits.x = 0;
+  });
+
+  it('reassigning limits whole record is rejected at compile time (F-1)', () => {
+    const adapter = {} as RhiAdapter;
+    // @ts-expect-error limits is a readonly property
+    adapter.limits = { x: 0 };
+  });
+});
+
+describe('w17 type-level - RhiAdapter.requestDevice signature (K-6)', () => {
+  it('returns Promise<Result<RhiDevice, RhiError>> (NOT a tuple)', () => {
+    type Sig = RhiAdapter['requestDevice'];
+    type Ret = ReturnType<Sig>;
+    expectTypeOf<Ret>().toEqualTypeOf<Promise<Result<RhiDevice, RhiError>>>();
+  });
+
+  it('takes an optional RequestDeviceOptions parameter', () => {
+    type Sig = RhiAdapter['requestDevice'];
+    type Params = Parameters<Sig>;
+    expectTypeOf<Params>().toEqualTypeOf<[opts?: RequestDeviceOptions | undefined]>();
+  });
+});