@forgeax/engine-rhi-webgpu 0.0.0-dev.8d955ade1c79

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +133 -0
  3. package/dist/.tsbuildinfo +1 -0
  4. package/dist/__tests__/__mocks__/gpu-device.d.ts +226 -0
  5. package/dist/__tests__/__mocks__/gpu-device.d.ts.map +1 -0
  6. package/dist/__tests__/dawn-real-gpu.dawn.test.d.ts +2 -0
  7. package/dist/__tests__/dawn-real-gpu.dawn.test.d.ts.map +1 -0
  8. package/dist/__tests__/rhi-webgpu.unit.test.d.ts +2 -0
  9. package/dist/__tests__/rhi-webgpu.unit.test.d.ts.map +1 -0
  10. package/dist/device.d.ts +62 -0
  11. package/dist/device.d.ts.map +1 -0
  12. package/dist/errors.d.ts +49 -0
  13. package/dist/errors.d.ts.map +1 -0
  14. package/dist/index.d.ts +183 -0
  15. package/dist/index.d.ts.map +1 -0
  16. package/dist/index.mjs +1745 -0
  17. package/dist/index.mjs.map +1 -0
  18. package/dist/internal/__tests__/timestamp-query.unit.test.d.ts +2 -0
  19. package/dist/internal/__tests__/timestamp-query.unit.test.d.ts.map +1 -0
  20. package/dist/internal/error-translation.d.ts +16 -0
  21. package/dist/internal/error-translation.d.ts.map +1 -0
  22. package/dist/internal/timestamp-query.d.ts +15 -0
  23. package/dist/internal/timestamp-query.d.ts.map +1 -0
  24. package/package.json +58 -0
  25. package/src/__tests__/__mocks__/gpu-device.ts +555 -0
  26. package/src/__tests__/dawn-real-gpu.dawn.test.ts +1445 -0
  27. package/src/__tests__/rhi-webgpu.unit.test.ts +2398 -0
  28. package/src/device.ts +2102 -0
  29. package/src/errors.ts +183 -0
  30. package/src/index.ts +597 -0
  31. package/src/internal/__tests__/timestamp-query.unit.test.ts +88 -0
  32. package/src/internal/error-translation.ts +187 -0
  33. package/src/internal/timestamp-query.ts +59 -0
@@ -0,0 +1,226 @@
1
+ /** Failure-injection switches consumed by the device path tests. */
2
+ export interface MockFailures {
3
+ /** `requestAdapter` returns null (research F-5 single null channel). */
4
+ adapterNull?: boolean;
5
+ /** `requestDevice` rejects with `OperationError` (spec behaviour for an
6
+ * unsupported feature). */
7
+ requestDeviceFeatureNotEnabled?: boolean;
8
+ /** `requestDevice` rejects with `OperationError` (spec behaviour for an
9
+ * out-of-range limit). */
10
+ requestDeviceLimitExceeded?: boolean;
11
+ /** `createShaderModule` returns a module whose `getCompilationInfo()`
12
+ * yields error-typed messages. */
13
+ shaderCompileMessages?: readonly GPUCompilationMessage[];
14
+ /** `createShaderModule` returns a module whose `getCompilationInfo()`
15
+ * rejects — models the GPU instance being dropped mid-await (device
16
+ * destroyed / page teardown while the async query is in flight). */
17
+ getCompilationInfoRejects?: boolean;
18
+ /** `createRenderPipeline` throws synchronously with this message. */
19
+ renderPipelineError?: string;
20
+ }
21
+ /** Mock-capture event union; consumed by passthrough assertions. */
22
+ export type MockCapture = {
23
+ kind: 'requestAdapter';
24
+ options: GPURequestAdapterOptions | undefined;
25
+ } | {
26
+ kind: 'requestDevice';
27
+ options: GPUDeviceDescriptor | undefined;
28
+ } | {
29
+ kind: 'createBuffer';
30
+ descriptor: GPUBufferDescriptor;
31
+ } | {
32
+ kind: 'createTexture';
33
+ descriptor: GPUTextureDescriptor;
34
+ } | {
35
+ kind: 'createSampler';
36
+ descriptor: GPUSamplerDescriptor | undefined;
37
+ } | {
38
+ kind: 'createBindGroupLayout';
39
+ descriptor: GPUBindGroupLayoutDescriptor;
40
+ } | {
41
+ kind: 'createBindGroup';
42
+ descriptor: GPUBindGroupDescriptor;
43
+ } | {
44
+ kind: 'createPipelineLayout';
45
+ descriptor: GPUPipelineLayoutDescriptor;
46
+ } | {
47
+ kind: 'createRenderPipeline';
48
+ descriptor: GPURenderPipelineDescriptor;
49
+ } | {
50
+ kind: 'createShaderModule';
51
+ descriptor: GPUShaderModuleDescriptor;
52
+ } | {
53
+ kind: 'createTextureView';
54
+ sourceDescriptor: GPUTextureDescriptor;
55
+ descriptor: GPUTextureViewDescriptor | undefined;
56
+ } | {
57
+ kind: 'createComputePipeline';
58
+ descriptor: GPUComputePipelineDescriptor;
59
+ } | {
60
+ kind: 'createQuerySet';
61
+ descriptor: GPUQuerySetDescriptor;
62
+ };
63
+ /** Unique brand symbol so captured handles cannot be confused with real GPU* objects. */
64
+ declare const MOCK_BRAND: unique symbol;
65
+ /**
66
+ * Mock texture handle: exposes spec readonly fields the shim consumes for
67
+ * createTextureView cross-resource validation (research §1.1: format must be
68
+ * in source.format ∪ source.viewFormats; usage must be a subset of
69
+ * source.usage). The shim retrieves these via its own WeakMap (filled at
70
+ * createTexture time), but the mock surfaces createView so the shim can
71
+ * forward and capture descriptors verbatim.
72
+ */
73
+ export interface MockTexture {
74
+ readonly [MOCK_BRAND]: 'texture';
75
+ readonly format: GPUTextureFormat;
76
+ readonly usage: GPUTextureUsageFlags;
77
+ readonly viewFormats: readonly GPUTextureFormat[];
78
+ createView(descriptor?: GPUTextureViewDescriptor | undefined): MockTextureView;
79
+ }
80
+ /** Mock texture view handle. */
81
+ export interface MockTextureView {
82
+ readonly [MOCK_BRAND]: 'texture-view';
83
+ }
84
+ /** Mock device exposed subset (covers only the surface the shim uses). */
85
+ export interface MockDevice {
86
+ readonly features: GPUSupportedFeatures;
87
+ readonly limits: GPUSupportedLimits;
88
+ readonly lost: Promise<GPUDeviceLostInfo>;
89
+ readonly queue: MockQueue;
90
+ createBuffer(descriptor: GPUBufferDescriptor): MockBuffer;
91
+ createTexture(descriptor: GPUTextureDescriptor): MockTexture;
92
+ createSampler(descriptor?: GPUSamplerDescriptor | undefined): {
93
+ readonly [MOCK_BRAND]: 'sampler';
94
+ };
95
+ createBindGroupLayout(descriptor: GPUBindGroupLayoutDescriptor): {
96
+ readonly [MOCK_BRAND]: 'bgl';
97
+ };
98
+ createBindGroup(descriptor: GPUBindGroupDescriptor): {
99
+ readonly [MOCK_BRAND]: 'bg';
100
+ };
101
+ createPipelineLayout(descriptor: GPUPipelineLayoutDescriptor): {
102
+ readonly [MOCK_BRAND]: 'pl';
103
+ };
104
+ createRenderPipeline(descriptor: GPURenderPipelineDescriptor): {
105
+ readonly [MOCK_BRAND]: 'render-pipeline';
106
+ };
107
+ createComputePipeline(descriptor: GPUComputePipelineDescriptor): {
108
+ readonly [MOCK_BRAND]: 'compute-pipeline';
109
+ };
110
+ createQuerySet(descriptor: GPUQuerySetDescriptor): {
111
+ readonly [MOCK_BRAND]: 'query-set';
112
+ };
113
+ createShaderModule(descriptor: GPUShaderModuleDescriptor): {
114
+ readonly [MOCK_BRAND]: 'shader';
115
+ getCompilationInfo(): Promise<GPUCompilationInfo>;
116
+ };
117
+ createCommandEncoder(descriptor?: GPUCommandEncoderDescriptor | undefined): MockCommandEncoder;
118
+ }
119
+ /** Mock queue: tracks submit / writeBuffer for assertions; M5 / w37 adds
120
+ * writeTexture / copyExternalImageToTexture / onSubmittedWorkDone. */
121
+ export interface MockQueue {
122
+ readonly [MOCK_BRAND]: 'queue';
123
+ submit(commandBuffers: Iterable<MockCommandBuffer>): void;
124
+ writeBuffer(buffer: MockBuffer, bufferOffset: number, data: ArrayBufferView | ArrayBuffer, dataOffset?: number, size?: number): void;
125
+ writeTexture(destination: unknown, data: ArrayBufferView | ArrayBuffer, dataLayout: unknown, size: unknown): void;
126
+ copyExternalImageToTexture(source: unknown, destination: unknown, copySize: unknown): void;
127
+ onSubmittedWorkDone(): Promise<undefined>;
128
+ }
129
+ /** Mock buffer; carries `size` so writeBuffer bounds-checking has a value.
130
+ * Extended in M5 / w35 with mapping surface (mapAsync / getMappedRange /
131
+ * unmap / mapState) so the shim Buffer wrapper can drive the validation
132
+ * paths (research §4.1 / §4.2 / §4.4). */
133
+ export interface MockBuffer {
134
+ readonly [MOCK_BRAND]: 'buffer';
135
+ readonly size: number;
136
+ mapState: 'unmapped' | 'pending' | 'mapped';
137
+ mapAsync(mode: number, offset?: number, size?: number): Promise<void>;
138
+ getMappedRange(offset?: number, size?: number): ArrayBuffer;
139
+ unmap(): void;
140
+ }
141
+ /** Mock command encoder: returned by device.createCommandEncoder. */
142
+ export interface MockCommandEncoder {
143
+ readonly [MOCK_BRAND]: 'command-encoder';
144
+ beginRenderPass(descriptor: GPURenderPassDescriptor): MockRenderPassEncoder;
145
+ beginComputePass(descriptor?: GPUComputePassDescriptor): MockComputePassEncoder;
146
+ copyBufferToBuffer(...args: unknown[]): void;
147
+ copyBufferToTexture(source: unknown, destination: unknown, copySize: unknown): void;
148
+ copyTextureToBuffer(source: unknown, destination: unknown, copySize: unknown): void;
149
+ copyTextureToTexture(source: unknown, destination: unknown, copySize: unknown): void;
150
+ clearBuffer(buffer: MockBuffer, offset?: number, size?: number): void;
151
+ resolveQuerySet(...args: unknown[]): void;
152
+ pushDebugGroup(label: string): void;
153
+ popDebugGroup(): void;
154
+ insertDebugMarker(label: string): void;
155
+ finish(descriptor?: GPUCommandBufferDescriptor): MockCommandBuffer;
156
+ }
157
+ /** Mock render pass encoder. */
158
+ export interface MockRenderPassEncoder {
159
+ readonly [MOCK_BRAND]: 'render-pass-encoder';
160
+ setPipeline(pipeline: unknown): void;
161
+ setBindGroup(...args: unknown[]): void;
162
+ setIndexBuffer(...args: unknown[]): void;
163
+ setVertexBuffer(...args: unknown[]): void;
164
+ draw(...args: unknown[]): void;
165
+ drawIndexed(...args: unknown[]): void;
166
+ drawIndirect(...args: unknown[]): void;
167
+ drawIndexedIndirect(...args: unknown[]): void;
168
+ setViewport(...args: unknown[]): void;
169
+ setScissorRect(...args: unknown[]): void;
170
+ setBlendConstant(...args: unknown[]): void;
171
+ setStencilReference(...args: unknown[]): void;
172
+ pushDebugGroup(label: string): void;
173
+ popDebugGroup(): void;
174
+ insertDebugMarker(label: string): void;
175
+ end(): void;
176
+ }
177
+ /** Mock compute pass encoder. */
178
+ export interface MockComputePassEncoder {
179
+ readonly [MOCK_BRAND]: 'compute-pass-encoder';
180
+ setPipeline(pipeline: unknown): void;
181
+ setBindGroup(...args: unknown[]): void;
182
+ dispatchWorkgroups(...args: unknown[]): void;
183
+ dispatchWorkgroupsIndirect(...args: unknown[]): void;
184
+ end(): void;
185
+ }
186
+ /** Mock command buffer (returned by encoder.finish). */
187
+ export interface MockCommandBuffer {
188
+ readonly [MOCK_BRAND]: 'command-buffer';
189
+ }
190
+ /**
191
+ * Minimal mock `GPU` provider injected via the shim's `gpu?: GPU` provider
192
+ * seam (research F-6 webgpu-utils + CTS consensus).
193
+ *
194
+ * `__captured` / `__failures` are observation points exclusive to the test
195
+ * side; the shim does not read them.
196
+ */
197
+ export interface MockGpu {
198
+ /** Test observation: createX / requestX call-site descriptors in order. */
199
+ readonly __captured: MockCapture[];
200
+ /** Failure-injection switches for the test side. */
201
+ readonly __failures: MockFailures;
202
+ requestAdapter(options?: GPURequestAdapterOptions | undefined): Promise<MockAdapter | null>;
203
+ }
204
+ /** Mock adapter subset. */
205
+ export interface MockAdapter {
206
+ readonly features: GPUSupportedFeatures;
207
+ readonly limits: GPUSupportedLimits;
208
+ requestDevice(descriptor?: GPUDeviceDescriptor | undefined): Promise<MockDevice>;
209
+ }
210
+ /**
211
+ * Create a MockGpu test entry point.
212
+ *
213
+ * @example
214
+ * const gpu = createMockGpu();
215
+ * gpu.__failures.adapterNull = true;
216
+ * const r = await rhiWebgpu.requestDevice({ gpu });
217
+ * expect(r.ok).toBe(false);
218
+ */
219
+ export declare function createMockGpu(failures?: MockFailures): MockGpu;
220
+ /**
221
+ * Build a 6-field GPUCompilationMessage (OQ-P2 locked field set).
222
+ * Used by shader-compile-failed path tests asserting detail.compilerMessages.
223
+ */
224
+ export declare function makeShaderError(partial?: Partial<GPUCompilationMessage>): GPUCompilationMessage;
225
+ export {};
226
+ //# sourceMappingURL=gpu-device.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"gpu-device.d.ts","sourceRoot":"","sources":["../../../src/__tests__/__mocks__/gpu-device.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=dawn-real-gpu.dawn.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"dawn-real-gpu.dawn.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/dawn-real-gpu.dawn.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=rhi-webgpu.unit.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"rhi-webgpu.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/rhi-webgpu.unit.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,62 @@
1
+ import type { RhiCanvasContext, RhiDevice } from '@forgeax/engine-rhi';
2
+ /**
3
+ * Get the underlying GPUDevice associated with a RhiDevice.
4
+ *
5
+ * @internal
6
+ *
7
+ * Single-point escape hatch (D-S1 / feat-20260508-rhi-surface-completion).
8
+ * The `_internal_` prefix + `@internal` JSDoc tag mark this as engine-internal
9
+ * plumbing; the only sanctioned consumer is
10
+ * `apps/hello/triangle/src/main.ts:96` which threads the raw GPUDevice into
11
+ * the host's internal canvas-device configuration slot so the canvas
12
+ * `GPUCanvasContext.configure({device})` slot keeps working
13
+ * (GPUCanvasContext is outside the RHI surface). Every other engine path
14
+ * goes through the RHI interface.
15
+ *
16
+ * Future: deprecated once `feat-future-rhi-adapter-surface` lands a
17
+ * `RhiCanvasContext` abstraction; this function will be removed at that
18
+ * closure. AC-08 grep gate keeps further callers out via word-boundary
19
+ * `\bgetRawDevice\b` allow-list (see apps/hello/triangle/scripts/ac-08-grep-gate.mjs).
20
+ */
21
+ export declare function _internal_getRawDevice(device: RhiDevice): GPUDevice | undefined;
22
+ /**
23
+ * Construct a RhiDevice shim wrapping GPUDevice.
24
+ *
25
+ * Does not cache or reclassify device.lost (single-source subscription +
26
+ * dual-form fan-out is the engine layer's job; this package only exposes the
27
+ * spec Promise). See plan-strategy 3 R2 mitigation.
28
+ */
29
+ export declare function makeRhiDevice(rawDevice: GPUDevice): {
30
+ device: RhiDevice;
31
+ /** Exposed for createShaderModule and other shim entry points that need to
32
+ * bypass the createX Result wrapper. */
33
+ raw: GPUDevice;
34
+ };
35
+ /** Stripped-down GPUCanvasContext shape the shim consumes. Real
36
+ * GPUCanvasContext satisfies this; the unit-test mock fixture only
37
+ * implements what is needed (charter proposition 1: progressive disclosure). */
38
+ export interface GpuCanvasContextLike {
39
+ configure(configuration: GPUCanvasConfiguration): void;
40
+ unconfigure(): void;
41
+ getConfiguration(): GPUCanvasConfiguration | null;
42
+ getCurrentTexture(): GPUTexture;
43
+ }
44
+ /**
45
+ * Build a RhiCanvasContext shim around a raw GPUCanvasContext (M3 / K-4 /
46
+ * w21).
47
+ *
48
+ * Pre-configure validation (research §3.3 mapping):
49
+ * - format gate: format must be in SUPPORTED_CONTEXT_FORMATS; otherwise
50
+ * fast-path returns `'webgpu-runtime-error'` with the spec-aligned
51
+ * `.expected` literal `'one of bgra8unorm/rgba8unorm/rgba16float'`.
52
+ *
53
+ * Post-configure semantics:
54
+ * - getCurrentTexture forwards each call to the raw context (NO cross-frame
55
+ * caching, research §3.3 [[Expire the current texture]]); spec
56
+ * InvalidStateError catches map to `'webgpu-runtime-error'`.
57
+ * - getConfiguration projects the spec record verbatim; missing fields
58
+ * remain missing (feature-detection idiom, research §3.2 toneMapping
59
+ * NOTE).
60
+ */
61
+ export declare function makeCanvasContext(rawContext: GpuCanvasContextLike): RhiCanvasContext;
62
+ //# sourceMappingURL=device.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAuBV,gBAAgB,EAIhB,SAAS,EAaV,MAAM,qBAAqB,CAAC;AA8L7B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAE/E;AAsrCD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG;IACnD,MAAM,EAAE,SAAS,CAAC;IAClB;6CACyC;IACzC,GAAG,EAAE,SAAS,CAAC;CAChB,CAicA;AA0BD;;iFAEiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,aAAa,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACvD,WAAW,IAAI,IAAI,CAAC;IACpB,gBAAgB,IAAI,sBAAsB,GAAG,IAAI,CAAC;IAClD,iBAAiB,IAAI,UAAU,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,oBAAoB,GAAG,gBAAgB,CAqGpF"}
@@ -0,0 +1,49 @@
1
+ import { type Result, RhiError } from '@forgeax/engine-rhi';
2
+ /** adapter null path (research F-5 single null channel). */
3
+ export declare function adapterUnavailable(): Result<never, RhiError>;
4
+ /** `GPU.requestAdapter()` rejected instead of reporting adapter absence with `null`. */
5
+ export declare function requestAdapterFailed(cause: unknown): Result<never, RhiError>;
6
+ /** feature not enabled path (boundary cases / requirements). */
7
+ export declare function featureNotEnabled(featureName?: string | undefined): Result<never, RhiError>;
8
+ /** limit exceeded path (boundary cases / requirements). */
9
+ export declare function limitExceeded(limitName?: string | undefined): Result<never, RhiError>;
10
+ /** shader compile failed path + detail.compilerMessages forwarding (OQ-P2 6 fields). */
11
+ export declare function shaderCompileFailed(compilerMessages: readonly GPUCompilationMessage[]): Result<never, RhiError>;
12
+ /**
13
+ * Command encoder reused after finish() (W3C WebGPU 22 GPUCommandEncoder lifecycle).
14
+ *
15
+ * Trigger: encoder.beginRenderPass / copyXxx / finish called after a prior finish().
16
+ * Distinct from 'rhi-not-available': this is a real-path validation failure,
17
+ * not a placeholder for unimplemented surface (plan-strategy D-S3 template 1).
18
+ */
19
+ export declare function commandEncoderFinished(): Result<never, RhiError>;
20
+ /**
21
+ * Render pass not ended before next pass / finish (W3C WebGPU 22.7 Render pass).
22
+ *
23
+ * Trigger: encoder.beginRenderPass while previous pass active, or encoder.finish
24
+ * with active pass still recording (plan-strategy D-S3 template 2).
25
+ */
26
+ export declare function renderPassNotEnded(): Result<never, RhiError>;
27
+ /**
28
+ * Queue.submit real-path failure (W3C WebGPU 23 Queue).
29
+ *
30
+ * Trigger: submit([cb]) with destroyed buffer/pipeline references, or GPU validation
31
+ * error fan-out via onuncapturederror. Explicitly distinct from 'rhi-not-available'
32
+ * (device-lost subclass) - submit-failed signals dynamic resource life-cycle issues
33
+ * the AI user can self-recover from (plan-strategy D-S3 template 3).
34
+ */
35
+ export declare function queueSubmitFailed(detailMessage?: string | undefined): Result<never, RhiError>;
36
+ /**
37
+ * Queue.writeBuffer offset/size out of bounds (W3C WebGPU 23.2 writeBuffer).
38
+ *
39
+ * Trigger: writeBuffer(buf, offset, data) where offset is not 4-byte aligned, or
40
+ * offset + data.byteLength exceeds buffer.size. Distinct from 'limit-exceeded'
41
+ * (static device.limits) - out-of-bounds is a dynamic per-buffer boundary
42
+ * (plan-strategy D-S3 template 4).
43
+ */
44
+ export declare function queueWriteBufferOutOfBounds(args: {
45
+ offset: number;
46
+ byteLength: number;
47
+ bufferSize: number;
48
+ }): Result<never, RhiError>;
49
+ //# sourceMappingURL=errors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAYA,OAAO,EAAO,KAAK,MAAM,EAAE,QAAQ,EAA+B,MAAM,qBAAqB,CAAC;AAE9F,4DAA4D;AAC5D,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAQ5D;AAED,wFAAwF;AACxF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAmC5E;AAED,gEAAgE;AAChE,wBAAgB,iBAAiB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAS3F;AAED,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CASrF;AAED,wFAAwF;AACxF,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,SAAS,qBAAqB,EAAE,GACjD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAUzB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAQhE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAS5D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAe7F;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAS1B"}
@@ -0,0 +1,183 @@
1
+ import type { RequestAdapterOptions, Result, RhiAdapter, RhiCanvasContext, RhiDevice, RhiError, RhiInstance, ShaderModule } from '@forgeax/engine-rhi';
2
+ /**
3
+ * The `GPU` subset accepted at the provider seam (research §F-6 webgpu-utils +
4
+ * CTS consensus).
5
+ *
6
+ * The shim only calls the two entries `gpu.requestAdapter()` →
7
+ * `adapter.requestDevice()`; accepting a structural subset rather than requiring
8
+ * a full GPU interface implementation lets the mock fixture
9
+ * (src/__tests__/__mocks__/gpu-device.ts) skip implementing
10
+ * `wgslLanguageFeatures` / `getPreferredCanvasFormat` and other fields this loop
11
+ * does not consume (charter proposition 1: progressive disclosure).
12
+ */
13
+ export interface GpuLike {
14
+ requestAdapter(options?: GPURequestAdapterOptions | undefined): Promise<GpuAdapterLike | null>;
15
+ }
16
+ /** The `GPUAdapter` subset accepted at the provider seam — only the `requestDevice` entry is consumed. */
17
+ export interface GpuAdapterLike {
18
+ requestDevice(descriptor?: GPUDeviceDescriptor | undefined): Promise<GpuDeviceLike>;
19
+ }
20
+ /**
21
+ * The `GPUDevice` subset accepted at the provider seam — exactly the fields the
22
+ * shim actually touches (the 5 descriptor `createX` calls + features / limits /
23
+ * lost + a `queue` placeholder).
24
+ *
25
+ * Differences from the full GPUDevice spec:
26
+ * - `onuncapturederror` / `pushErrorScope` / `createCommandEncoder` not required
27
+ * (only needed at M3).
28
+ * - `wgslLanguageFeatures` / `getPreferredCanvasFormat` not required (charter
29
+ * proposition 1: progressive disclosure).
30
+ *
31
+ * The coverage of `cast as GPUDevice` inside `makeRhiDevice` matches this
32
+ * interface exactly; both the mock and the real GPUDevice only need to satisfy
33
+ * this structural subset.
34
+ */
35
+ export interface GpuDeviceLike {
36
+ readonly features: GPUSupportedFeatures;
37
+ readonly limits: GPUSupportedLimits;
38
+ readonly lost: Promise<GPUDeviceLostInfo>;
39
+ readonly queue: unknown;
40
+ createBuffer(descriptor: GPUBufferDescriptor): unknown;
41
+ createTexture(descriptor: GPUTextureDescriptor): unknown;
42
+ createSampler(descriptor?: GPUSamplerDescriptor | undefined): unknown;
43
+ createBindGroupLayout(descriptor: GPUBindGroupLayoutDescriptor): unknown;
44
+ createBindGroup(descriptor: GPUBindGroupDescriptor): unknown;
45
+ createPipelineLayout(descriptor: GPUPipelineLayoutDescriptor): unknown;
46
+ createRenderPipeline(descriptor: GPURenderPipelineDescriptor): unknown;
47
+ createShaderModule(descriptor: GPUShaderModuleDescriptor): unknown;
48
+ }
49
+ /**
50
+ * Options for the `requestDevice` entry.
51
+ *
52
+ * `gpu?: GpuLike` is the provider seam (research §F-6 webgpu-utils + CTS
53
+ * consensus):
54
+ * - omitted → falls back to `globalThis.navigator.gpu` (real-device path).
55
+ * - explicitly provided → uses the caller-injected mock / real GPU object (mock
56
+ * unit-test path).
57
+ *
58
+ * `adapterOptions` / `deviceDescriptor` pass through to the corresponding spec
59
+ * entries.
60
+ */
61
+ export interface RequestDeviceOptions {
62
+ gpu?: GpuLike | undefined;
63
+ adapterOptions?: GPURequestAdapterOptions | undefined;
64
+ deviceDescriptor?: GPUDeviceDescriptor | undefined;
65
+ }
66
+ /**
67
+ * Internal `requestDevice` — single-step factory accepting an injected
68
+ * `gpu` mock provider. **Not part of the public RHI surface**: AI users go
69
+ * through the spec-aligned two-step path
70
+ * `rhi.requestAdapter() -> adapter.requestDevice()` (M3 break-point #2 + M6
71
+ * fix-up [w51]; AGENTS.md break-point list 2026-05-10 #2). This entry is
72
+ * retained as the unit-test seam (`packages/rhi-webgpu/src/__tests__/*`)
73
+ * for `gpu` mock injection; it is **not** re-exported through the `rhi`
74
+ * singleton and is **not** referenced by engine / apps / dawn paths
75
+ * (charter proposition 5 consistent abstraction red line + grep gate
76
+ * `m6-e: rhi.requestDevice( 0 hit`).
77
+ *
78
+ * Generates 3 of the 4 error paths here (research §F-5):
79
+ * - adapter null → `Result.err(RhiError { code: 'adapter-unavailable' })`
80
+ * - feature not enabled → `Result.err(RhiError { code: 'feature-not-enabled' })`
81
+ * - limit exceeded → `Result.err(RhiError { code: 'limit-exceeded' })`
82
+ *
83
+ * The 4th path (shader-compile-failed) is generated by the
84
+ * `createShaderModule` entry.
85
+ */
86
+ export declare function requestDevice(opts?: RequestDeviceOptions): Promise<Result<RhiDevice, RhiError>>;
87
+ /**
88
+ * Entry 2 - async `createShaderModule`. The shader-compile-failed path
89
+ * forwards every 6 fields of `GPUCompilationMessage` to
90
+ * `RhiError.detail.compilerMessages` (OQ-P2 / F-3 finding).
91
+ *
92
+ * Implementation (post fix-f3):
93
+ * 1) Look up the underlying `GPUDevice` via the in-package
94
+ * `_internal_getRawDevice` (RAW_DEVICE_MAP reverse lookup; same module).
95
+ * 2) `rawDevice.createShaderModule(desc)` calls the spec entry to obtain
96
+ * a `GPUShaderModule`.
97
+ * 3) `await module.getCompilationInfo()` retrieves compilation info.
98
+ * 4) If any message has `type === 'error'`, return
99
+ * `Result.err(RhiError { code: 'shader-compile-failed',
100
+ * detail: { compilerMessages } })`.
101
+ * 5) Otherwise return `Result.ok(module as ShaderModule)`.
102
+ *
103
+ * Note: this entry accepts a shim-wrapped RhiDevice (not a raw GPUDevice)
104
+ * to keep the public API single-source; the in-package
105
+ * `_internal_getRawDevice` is the only sanctioned reverse lookup.
106
+ *
107
+ * fix-f3: the synchronous `RhiDevice.createShaderModule` placeholder is
108
+ * removed; the shader-compile-failed path closes inside this async entry
109
+ * (charter proposition 5 consistent abstraction + proposition 4 explicit
110
+ * failure).
111
+ */
112
+ export declare function createShaderModule(device: RhiDevice, desc: {
113
+ label?: string | undefined;
114
+ code: string;
115
+ }): Promise<Result<ShaderModule, RhiError>>;
116
+ /**
117
+ * Entry — `requestAdapter` walks `navigator.gpu.requestAdapter(opts)` and
118
+ * wraps the result as a forgeax `RhiAdapter` (M3 break-point #2; K-5 + K-6).
119
+ *
120
+ * Strict two-step path mirrors wgpu / Dawn (research §6); the legacy
121
+ * `requestDevice(opts)` factory below is the deprecated single-step shortcut
122
+ * kept for backward compatibility while existing callers migrate.
123
+ *
124
+ * Optional `gpu` provider seam at the `RequestAdapterOptions`-side: this
125
+ * factory takes only the forgeax-spec `RequestAdapterOptions` (powerPreference
126
+ * / forceFallbackAdapter); when callers need the mock-injection seam they go
127
+ * through the legacy `requestDevice({ gpu })` form.
128
+ *
129
+ * @param opts — W3C-spec request adapter options.
130
+ * @param _compatibleSurface — accepted for dual-impl symmetry
131
+ * (plan-strategy D-5; AGENTS.md "Dual-impl ship-together" rule).
132
+ * The browser WebGPU backend does not use this parameter; it is
133
+ * ignored. rhi-wgpu routes it to `requestAdapterWithCanvas`.
134
+ */
135
+ export declare function requestAdapter(opts?: RequestAdapterOptions | undefined, _compatibleSurface?: HTMLCanvasElement | OffscreenCanvas | undefined): Promise<Result<RhiAdapter, RhiError>>;
136
+ /**
137
+ * Acquire a canvas rendering context from an HTMLCanvasElement (M3 / w15).
138
+ *
139
+ * Spec anchor: W3C WebGPU §3.3 GPUCanvasContext.
140
+ *
141
+ * Internally calls `canvas.getContext('webgpu')` and wraps the result as a
142
+ * branded RhiCanvasContext. Returns `Result<RhiCanvasContext, RhiError>` —
143
+ * canvas does not support WebGPU returns `RhiError { code: 'rhi-not-available' }`
144
+ * with a precise `.hint` so AI users can display a degradation banner (charter
145
+ * proposition 4 explicit failure).
146
+ *
147
+ * This replaces the legacy `createCanvasContext(rawCtx)` — AGENTS.md §Change stance
148
+ * authorizes the breaking rename (acquireCanvasContext, optimal > compatible).
149
+ *
150
+ * @example
151
+ * const ctxResult = acquireCanvasContext(canvas);
152
+ * if (!ctxResult.ok) {
153
+ * // canvas does not support WebGPU
154
+ * return;
155
+ * }
156
+ * const canvasContext = ctxResult.value;
157
+ * canvasContext.configure({ device, format: 'bgra8unorm', usage: 0x10 });
158
+ */
159
+ export declare function acquireCanvasContext(canvas: HTMLCanvasElement | OffscreenCanvas): Result<RhiCanvasContext, RhiError>;
160
+ /**
161
+ * The `rhi` singleton entry (charter proposition 1: progressive disclosure +
162
+ * plan-strategy §7.4 discoverability:
163
+ * 'import { rhi } from @forgeax/engine-rhi-webgpu' + 'Engine.create({ rhi, canvas })'
164
+ * injection shape).
165
+ *
166
+ * Strict two-step path (M3 break-point #2 + M6 fix-up [w51]; K-5 + K-6):
167
+ * `rhi.requestAdapter(opts) -> adapter.requestDevice(opts)`
168
+ *
169
+ * The legacy single-step `rhi.requestDevice(opts)` factory was retired here
170
+ * (AGENTS.md break-point list 2026-05-10 #2). AI users follow the spec
171
+ * idiom (charter proposition 5 consistent abstraction red line):
172
+ * const adapter = (await rhi.requestAdapter()).unwrap();
173
+ * const device = (await adapter.requestDevice(opts)).unwrap();
174
+ */
175
+ export declare const rhi: RhiInstance & {
176
+ createShaderModule: typeof createShaderModule;
177
+ acquireCanvasContext: typeof acquireCanvasContext;
178
+ };
179
+ export type { BindGroup, BindGroupDescriptor, BindGroupLayout, BindGroupLayoutDescriptor, Buffer, BufferDescriptor, CanvasConfiguration, CommandBuffer, CommandEncoderDescriptor, ComputePassDescriptor, ComputePassTimestampWrites, ComputePipeline, ComputePipelineDescriptor, Fence, PipelineLayout, PipelineLayoutDescriptor, QuerySet, QuerySetDescriptor, RenderPassColorAttachment, RenderPassDepthStencilAttachment, RenderPassDescriptor, RenderPipeline, RenderPipelineDescriptor, RequestAdapterOptions, RequestDeviceOptions as RhiRequestDeviceOptions, Result, ResultErr, ResultOk, RhiAdapter, RhiAssetNotRegisteredDetail, RhiCanvasContext, RhiCaps, RhiCommandEncoder, RhiComputePassEncoder, RhiDevice, RhiError, RhiErrorCode, RhiErrorDetail, RhiFeatures, RhiInstance, RhiLimits, RhiQueue, RhiRenderPassEncoder, RhiShaderCompileDetail, RhiSurface, RhiWebgpuRuntimeDetail, Sampler, SamplerDescriptor, ShaderModule, Texture, TextureDescriptor, TextureView, TextureViewDescriptor, } from '@forgeax/engine-rhi';
180
+ export { err, ok, RhiError as RhiErrorClass } from '@forgeax/engine-rhi';
181
+ export { _internal_getRawDevice } from './device';
182
+ export { translateErrorEventToRhiError } from './internal/error-translation';
183
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}