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

package/dist/index.d.ts

@@ -0,0 +1,1758 @@
+import type { AddressMode, CompareFunction, FilterMode, TextureFormat } from '@forgeax/engine-types';
+import type { Result, RhiError } from './errors';
+declare const RhiBufferBrand: unique symbol;
+declare const RhiMappedBufferBrand: unique symbol;
+/**
+ * GPU buffer opaque handle (vertex / index / uniform / storage / indirect).
+ *
+ * Spec anchor: W3C WebGPU §4 Buffers / [@webgpu/types.GPUBuffer]; research
+ * §4.1 mapState 3-state enum + §4.2 mapAsync 8-item validation + §4.4 unmap
+ * detach semantics.
+ *
+ * The buffer mapping surface is added in feat-20260510-rhi-resource-creation
+ * M5 (K-1: raw GPUMapMode bitmask; K-2: alignment / mode-usage / detach
+ * faults all ride 'webgpu-runtime-error' with structured .expected / .hint);
+ * re-shaped in feat-20260511-rhi-spec-realign-aggressive M1 (D-P2 #6):
+ *   - `mapAsync` resolves to `Result<MappedBuffer, RhiError>` (success branch
+ *     carries a branded handle subsequently used for getMappedRange / unmap).
+ *   - `getMappedRange` / `unmap` are methods on `MappedBuffer` (not Buffer);
+ *     calling them on a plain Buffer is a TS2345 compile-time red.
+ *
+ * The forgeax form keeps the spec verb names but routes failures via Result
+ * (charter proposition 4 explicit failure):
+ *   mapAsync(mode, offset?, size?): Promise<Result<MappedBuffer, RhiError>>
+ *   readonly mapState: 'unmapped' | 'pending' | 'mapped'  - getter (research
+ *                    §4.1; same closed union as GPUBufferMapState).
+ */
+export interface Buffer {
+    readonly [RhiBufferBrand]: void;
+    /**
+     * Map the buffer for CPU access.
+     *
+     * Spec anchor: W3C WebGPU §gpubuffer-mapasync /
+     * [@webgpu/types.GPUBuffer.mapAsync]. K-1 decision: `mode` is the raw
+     * `GPUMapMode` bitmask (NOT a closed union 'read' | 'write') so the forgeax
+     * form mirrors `GPUMapMode.READ` / `GPUMapMode.WRITE` literals.
+     *
+     * D-P2 #6 (feat-20260511-rhi-spec-realign-aggressive): the success branch
+     * resolves to `MappedBuffer`, a brand on top of `Buffer`. AI users
+     * subsequently call `mapped.getMappedRange(...)` / `mapped.unmap()` on the
+     * branded handle; calling those methods on a plain `Buffer` is a TS2345
+     * compile-time signal (charter proposition 4 explicit failure encoded at
+     * the type layer).
+     *
+     * Failure paths (research §4.2 + plan-strategy §2 K-2):
+     *   - mapState !== 'unmapped' (F-8 row 1) -> 'webgpu-runtime-error'.
+     *   - offset % 8 != 0 (step 4) -> 'webgpu-runtime-error'.
+     *   - rangeSize % 4 != 0 (step 5) -> 'webgpu-runtime-error'.
+     *   - offset + rangeSize > size (step 6) -> 'webgpu-runtime-error'.
+     *   - mode contains foreign bits (step 7) -> 'webgpu-runtime-error'.
+     *   - mode is not exactly READ or WRITE (step 8) -> 'webgpu-runtime-error'.
+     *   - mode-usage mismatch (step 9 / F-8 row 3) -> 'webgpu-runtime-error'.
+     *
+     * @example
+     *   const r = await buffer.mapAsync(GPUMapMode.WRITE);
+     *   if (!r.ok) {
+     *     // route via switch (r.error.code)
+     *     return;
+     *   }
+     *   const mapped: MappedBuffer = r.value;
+     *   const range = mapped.getMappedRange();
+     *   if (range.ok) new Uint32Array(range.value).set([1, 2, 3, 4]);
+     *   mapped.unmap();
+     */
+    mapAsync(mode: GPUMapModeFlags, offset?: number | undefined, size?: number | undefined): Promise<Result<MappedBuffer, RhiError>>;
+    /**
+     * Current mapping state (read-only getter).
+     *
+     * Spec anchor: research §4.1 mapState 3-state enum; mirrors
+     * GPUBufferMapState. Transitions:
+     *   - createBuffer({mappedAtCreation:true}) sets mapState='mapped'.
+     *   - mapAsync moves 'unmapped' -> 'pending' -> 'mapped'.
+     *   - unmap moves 'mapped' -> 'unmapped'.
+     */
+    readonly mapState: 'unmapped' | 'pending' | 'mapped';
+}
+/**
+ * Brand on top of `Buffer` indicating the mapping is currently open; only the
+ * `MappedBuffer` exposes `getMappedRange` / `unmap` method forms so AI users
+ * cannot accidentally call them on an unmapped `Buffer` (D-P2 #6).
+ *
+ * The brand is structural — runtime the `MappedBuffer` is the same JS object
+ * as the underlying `Buffer`; TypeScript narrows access through the
+ * `__mapped: void` private brand symbol.
+ *
+ * Spec anchor: W3C WebGPU §4 Buffers mapping lifecycle (research §4.1 /
+ * §4.4); plan-strategy §7.1 + D-P2 break-point #6 (brand + method form
+ * merged).
+ *
+ * @example
+ *   const r = await buffer.mapAsync(GPUMapMode.WRITE);
+ *   if (!r.ok) return;
+ *   const mapped: MappedBuffer = r.value;
+ *   mapped.getMappedRange();   // method form, this: MappedBuffer
+ *   mapped.unmap();            // method form, this: MappedBuffer
+ */
+export interface MappedBuffer extends Buffer {
+    readonly [RhiMappedBufferBrand]: void;
+    /**
+     * Return an ArrayBuffer view of the mapped range. Method form on
+     * `MappedBuffer` per D-P2 #6 — calling on a plain `Buffer` is TS2339.
+     *
+     * Spec anchor: W3C WebGPU §gpubuffer-getmappedrange /
+     * [@webgpu/types.GPUBuffer.getMappedRange].
+     *
+     * Failure paths:
+     *   - mapState !== 'mapped' (incl after unmap, F-8 row 2 detach guard) ->
+     *     'webgpu-runtime-error'.
+     */
+    getMappedRange(offset?: number | undefined, size?: number | undefined): Result<ArrayBuffer, RhiError>;
+    /**
+     * Unmap the buffer, detaching all ArrayBuffer views obtained from
+     * getMappedRange. Method form on `MappedBuffer` per D-P2 #6.
+     *
+     * Spec anchor: W3C WebGPU §gpubuffer-unmap /
+     * [@webgpu/types.GPUBuffer.unmap]. unmap() returns void per spec normative
+     * silent no-op (research §4.4); calling unmap on an already-unmapped buffer
+     * does NOT error. This is the ONE Result-shape exception in the buffer
+     * surface (AI User Affordances explicit listing).
+     *
+     * After unmap, the JS object continues to exist but the brand narrows
+     * away at the TS layer: AI users who hold a `MappedBuffer` after the
+     * underlying state flipped should re-`mapAsync` to obtain a fresh branded
+     * instance (OQ-5 plan-decisions: unmap returns void; subsequent mapAsync
+     * returns a new MappedBuffer brand).
+     */
+    unmap(): void;
+}
+declare const RhiTextureBrand: unique symbol;
+/** GPU texture opaque handle (2D / 3D / cube / array). */
+export interface Texture {
+    readonly [RhiTextureBrand]: void;
+}
+/** RHI-owned destination for queue.writeTexture. The resource handle remains opaque. */
+export interface TextureWriteDestination {
+    readonly texture: Texture;
+    readonly mipLevel?: number | undefined;
+    readonly origin?: GPUOrigin3D | undefined;
+    readonly aspect?: GPUTextureAspect | undefined;
+}
+/** RHI-owned destination for queue.copyExternalImageToTexture. */
+export type ExternalImageTextureDestination = Omit<Pick<GPUCopyExternalImageDestInfo, 'texture' | 'mipLevel' | 'origin' | 'aspect' | 'colorSpace' | 'premultipliedAlpha'>, 'texture'> & {
+    readonly texture: Texture;
+};
+declare const RhiTextureViewBrand: unique symbol;
+/** GPU texture view opaque handle. */
+export interface TextureView {
+    readonly [RhiTextureViewBrand]: void;
+}
+declare const RhiSamplerBrand: unique symbol;
+/** GPU sampler opaque handle. */
+export interface Sampler {
+    readonly [RhiSamplerBrand]: void;
+}
+declare const RhiBindGroupBrand: unique symbol;
+/** GPU bind group opaque handle (instantiated layout). */
+export interface BindGroup {
+    readonly [RhiBindGroupBrand]: void;
+}
+declare const RhiBindGroupLayoutBrand: unique symbol;
+/** GPU bind group layout opaque handle (declares binding shapes). */
+export interface BindGroupLayout {
+    readonly [RhiBindGroupLayoutBrand]: void;
+}
+declare const RhiPipelineLayoutBrand: unique symbol;
+/** GPU pipeline layout opaque handle (aggregates BindGroupLayouts). */
+export interface PipelineLayout {
+    readonly [RhiPipelineLayoutBrand]: void;
+}
+declare const RhiRenderPipelineBrand: unique symbol;
+/** GPU render pipeline opaque handle. */
+export interface RenderPipeline {
+    readonly [RhiRenderPipelineBrand]: void;
+}
+declare const RhiComputePipelineBrand: unique symbol;
+/** GPU compute pipeline opaque handle. */
+export interface ComputePipeline {
+    readonly [RhiComputePipelineBrand]: void;
+}
+declare const RhiShaderModuleBrand: unique symbol;
+/** GPU shader module opaque handle (WGSL / SPIR-V compile artifact). */
+export interface ShaderModule {
+    readonly [RhiShaderModuleBrand]: void;
+}
+declare const RhiQuerySetBrand: unique symbol;
+/** GPU query set opaque handle (occlusion / timestamp). */
+export interface QuerySet {
+    readonly [RhiQuerySetBrand]: void;
+}
+declare const RhiFenceBrand: unique symbol;
+/** GPU fence opaque handle (GPU/CPU sync barrier). */
+export interface Fence {
+    readonly [RhiFenceBrand]: void;
+}
+declare const RhiCommandEncoderBrand: unique symbol;
+/** GPU command encoder opaque handle (single-use). */
+export interface CommandEncoder {
+    readonly [RhiCommandEncoderBrand]: void;
+}
+declare const RhiCommandBufferBrand: unique symbol;
+/** GPU command buffer opaque handle (submitted to Queue). */
+export interface CommandBuffer {
+    readonly [RhiCommandBufferBrand]: void;
+}
+/**
+ * Convert `?: T` optional fields to `?: T | undefined` (decision S-7).
+ *
+ * Compatible with exactOptionalPropertyTypes: writers may pass `undefined`
+ * explicitly or omit the field; the M2 shim distinguishes the two via
+ * `'x' in src` guards (research F-3 anti-pattern 2).
+ */
+type ExplicitUndefined<T> = {
+    [K in keyof T]: T[K] | undefined;
+};
+/** GPU buffer descriptor. Field set strictly matches GPUBufferDescriptor;
+ *  optional fields use `?: T | undefined`. */
+export type BufferDescriptor = ExplicitUndefined<Pick<GPUBufferDescriptor, 'label' | 'size' | 'usage' | 'mappedAtCreation'>>;
+/** GPU texture descriptor. Field set strictly matches GPUTextureDescriptor
+ *  (incl R8 Compatibility Mode field). */
+export type TextureDescriptor = ExplicitUndefined<Pick<GPUTextureDescriptor, 'label' | 'size' | 'mipLevelCount' | 'sampleCount' | 'dimension' | 'format' | 'usage' | 'viewFormats' | 'textureBindingViewDimension'>>;
+/** GPU sampler descriptor. Field set strictly matches GPUSamplerDescriptor. */
+export type SamplerDescriptor = ExplicitUndefined<Pick<GPUSamplerDescriptor, 'label' | 'addressModeU' | 'addressModeV' | 'addressModeW' | 'magFilter' | 'minFilter' | 'mipmapFilter' | 'lodMinClamp' | 'lodMaxClamp' | 'compare' | 'maxAnisotropy'>>;
+/** GPU bind group layout descriptor. Field set strictly matches
+ *  GPUBindGroupLayoutDescriptor. */
+export type BindGroupLayoutDescriptor = ExplicitUndefined<Pick<GPUBindGroupLayoutDescriptor, 'label' | 'entries'>>;
+/**
+ * GPU texture view descriptor (Pick<GPUTextureViewDescriptor, 9 fields>).
+ *
+ * Spec anchor: W3C WebGPU §texture-view-creation /
+ * [@webgpu/types.GPUTextureViewDescriptor]. Field NAMES align byte-for-byte;
+ * field set excludes the feature-gated `swizzle` field (research §1.1 OOS-MVP;
+ * a future closure can add it once `'texture-component-swizzle'` is enabled).
+ *
+ * Cross-resource validation (shim fast-path, research §1.1):
+ *   - `format` must equal source.format OR be in source.viewFormats; otherwise
+ *     the shim returns Result.err({ code: 'webgpu-runtime-error' }).
+ *   - `usage` must be a subset of source.usage (bitmask); otherwise the shim
+ *     returns the same code.
+ *
+ * @example
+ *   const r = device.createTextureView(tex, { format: 'rgba8unorm', dimension: '2d' });
+ *   if (!r.ok) {
+ *     // route via switch (r.error.code)
+ *   }
+ */
+export type TextureViewDescriptor = ExplicitUndefined<Pick<GPUTextureViewDescriptor, 'label' | 'format' | 'dimension' | 'usage' | 'aspect' | 'baseMipLevel' | 'mipLevelCount' | 'baseArrayLayer' | 'arrayLayerCount'>>;
+/**
+ * GPU compute pipeline descriptor (Pick<GPUComputePipelineDescriptor,
+ * 'label' | 'layout' | 'compute'>).
+ *
+ * Spec anchor: W3C WebGPU §compute-pipeline-creation /
+ * [@webgpu/types.GPUComputePipelineDescriptor]. Field NAMES align byte-for-byte
+ * with spec.
+ *
+ * `layout` is the spec union `'auto' | GPUPipelineLayout`; forgeax tightens
+ * the explicit form to the `PipelineLayout` opaque handle (D-S5 pattern):
+ *   layout: 'auto' | PipelineLayout
+ *
+ * `compute` mirrors `GPUProgrammableStage` verbatim — `module` (required
+ * `ShaderModule` opaque handle), `entryPoint?` (optional string),
+ * `constants?` (optional `Record<string, number>`).
+ *
+ * Capability gate (research §1.2 NOTE; plan-strategy §4.3 boundary case row 1):
+ *   - `caps.compute === false` -> shim returns Result.err({
+ *     code: 'feature-not-enabled', expected: 'caps.compute === true',
+ *     hint: 'check device.caps.compute before calling createComputePipeline'
+ *   }). MVP WebGPU path always has caps.compute=true (spec mandate); the gate
+ *   exists for potential future non-WebGPU backends.
+ *
+ * @example
+ *   const r = device.createComputePipeline({
+ *     label: 'cs',
+ *     layout: 'auto',
+ *     compute: { module: csModule, entryPoint: 'cs_main' },
+ *   });
+ */
+export type ComputePipelineDescriptor = ExplicitUndefined<Omit<Pick<GPUComputePipelineDescriptor, 'label' | 'layout' | 'compute'>, 'layout' | 'compute'>> & {
+    /**
+     * Either `'auto'` for user-agent BGL inference or a forgeax
+     * `PipelineLayout` opaque handle (D-S5 pattern: forgeax handle replaces
+     * spec polymorphism `(GPUAutoLayoutMode or GPUPipelineLayout)`).
+     */
+    layout: 'auto' | PipelineLayout;
+    /**
+     * The compute programmable stage. `module` is the forgeax `ShaderModule`
+     * opaque handle (replacing spec `GPUShaderModule`); `entryPoint?` defaults
+     * to the module's single compute entry; `constants?` is a record of
+     * pipeline-overridable constants.
+     */
+    compute: {
+        module: ShaderModule;
+        entryPoint?: string | undefined;
+        constants?: Record<string, number> | undefined;
+    };
+};
+/**
+ * GPU query set descriptor (Pick<GPUQuerySetDescriptor, 'label' | 'type' | 'count'>).
+ *
+ * Spec anchor: W3C WebGPU §queries / [@webgpu/types.GPUQuerySetDescriptor].
+ * Field NAMES align byte-for-byte.
+ *
+ * Hard constraints (research §1.3):
+ *   - `count <= 4096` (spec normative). The shim fast-paths a violation to
+ *     Result.err({ code: 'limit-exceeded',
+ *       expected: 'count <= 4096 (spec normative)',
+ *       hint: 'create multiple QuerySet instances if more than 4096 queries needed' }).
+ *   - `type === 'timestamp'` requires `caps.timestampQuery === true` (the
+ *     'timestamp-query' feature). Otherwise the shim fast-paths to
+ *     Result.err({ code: 'feature-not-enabled' }).
+ *   - `count = 0` is legal (lower bound; dawn end2end test fixture).
+ *
+ * @example
+ *   const r = device.createQuerySet({ type: 'occlusion', count: 4 });
+ *   if (!r.ok) {
+ *     // route via switch (r.error.code)
+ *   }
+ */
+export type QuerySetDescriptor = ExplicitUndefined<Pick<GPUQuerySetDescriptor, 'label' | 'type' | 'count'>>;
+/**
+ * Discriminated union over the 4 BindGroup entry resource kinds (the spec
+ * polymorphic `GPUBindingResource` collapsed to a tagged union — charter
+ * proposition 4 closed-union exhaustive switch + proposition 5 consistent
+ * abstraction over duck-typing).
+ *
+ * Introduced in feat-20260511-rhi-spec-realign-aggressive w9 per requirements
+ * AC-10 + plan-strategy §7.1 + D-P2 break-point #5. AI users `switch
+ * (resource.kind)` is exhaustive without a default fallback; construction-side
+ * typos like `{ kind: 'samplre', ... }` trip TS2322 at the literal slot.
+ *
+ * Kind discriminator uses kebab-case for multi-word entries (`textureView` is
+ * already single-word camelCase by convention; `externalTexture` is multi-word
+ * camelCase for parity with the spec verb `GPUExternalTexture`).
+ *
+ * @example
+ *   const e: RhiBindingResource = { kind: 'sampler', value: linearSampler };
+ *   const e2: RhiBindingResource = {
+ *     kind: 'buffer',
+ *     value: { buffer: viewUniforms, offset: 0, size: 64 },
+ *   };
+ */
+export type RhiBindingResource = {
+    readonly kind: 'sampler';
+    readonly value: Sampler;
+} | {
+    readonly kind: 'buffer';
+    readonly value: {
+        readonly buffer: Buffer;
+        readonly offset?: number;
+        readonly size?: number;
+    };
+} | {
+    readonly kind: 'textureView';
+    readonly value: TextureView;
+} | {
+    readonly kind: 'externalTexture';
+    readonly value: GPUExternalTexture;
+};
+/**
+ * BindGroup entry — one slot in a BindGroup, identified by `binding` (the
+ * shader binding number) and `resource` (the tagged-union `RhiBindingResource`
+ * — replaces the spec polymorphic `GPUBindingResource`).
+ *
+ * Field set strictly mirrors `Pick<GPUBindGroupEntry, 'binding'>`; the
+ * `resource` field is tightened to the forgeax `RhiBindingResource` tagged
+ * union per D-P2 break-point #5 (charter proposition 5 consistent abstraction:
+ * AI users see one canonical 4-kind switch rather than spec duck-typing).
+ */
+export type BindGroupEntry = Pick<GPUBindGroupEntry, 'binding'> & {
+    resource: RhiBindingResource;
+};
+/**
+ * GPU bind group descriptor (Pick<GPUBindGroupDescriptor, 'label' | 'layout' | 'entries'>).
+ *
+ * Spec anchor: W3C WebGPU 10 Resource binding /
+ * [@webgpu/types.GPUBindGroupDescriptor].
+ *
+ * Introduced in feat-20260509-ecs-render-bridge-mvp (D-S1) so the RenderSystem
+ * can record `pass.setBindGroup(0/1/2, bg, ...)` through a single RHI surface
+ * (charter proposition 5 consistent abstraction; never via raw GPUDevice).
+ *
+ * The `layout` field references the forgeax `BindGroupLayout` opaque handle
+ * (created via `RhiDevice.createBindGroupLayout`); the `entries` array uses
+ * the forgeax `BindGroupEntry` shape (binding number + tagged-union
+ * `RhiBindingResource`) per feat-20260511-rhi-spec-realign-aggressive D-P2
+ * break-point #5 (was previously verbatim `GPUBindGroupEntry`).
+ *
+ * @example
+ *   const desc: BindGroupDescriptor = {
+ *     label: 'view-bg',
+ *     layout: bgl,
+ *     entries: [{ binding: 0, resource: { kind: 'buffer', value: { buffer: viewUniforms } } }],
+ *   };
+ */
+export type BindGroupDescriptor = ExplicitUndefined<Omit<Pick<GPUBindGroupDescriptor, 'label' | 'layout' | 'entries'>, 'layout' | 'entries'>> & {
+    /**
+     * BindGroupLayout opaque handle (forgeax tightening: `layout` is the
+     * already-shipped `BindGroupLayout` brand, not the spec
+     * `GPUBindGroupLayout`). Same D-S5 pattern as RenderPassColorAttachment.view
+     * — AI users receive a forgeax-creatable handle, never a phantom spec type.
+     */
+    layout: BindGroupLayout;
+    /**
+     * Iterable of forgeax `BindGroupEntry` (binding + tagged-union
+     * `RhiBindingResource`); replaces the spec polymorphic
+     * `iterable<GPUBindGroupEntry>` per D-P2 break-point #5.
+     */
+    entries: Iterable<BindGroupEntry>;
+};
+/**
+ * GPU pipeline layout descriptor (Pick<GPUPipelineLayoutDescriptor, 'label' | 'bindGroupLayouts'>).
+ *
+ * Spec anchor: W3C WebGPU 10.3 Pipeline layout /
+ * [@webgpu/types.GPUPipelineLayoutDescriptor].
+ *
+ * Introduced in feat-20260509-ecs-render-bridge-mvp (D-S1) so the
+ * `Renderer.ready` step 2 (PBR pipeline compile) can compose the 3
+ * BindGroupLayouts (view / material / mesh-array) into a single
+ * `PipelineLayout` for `RhiDevice.createRenderPipeline`.
+ *
+ * @example
+ *   const desc: PipelineLayoutDescriptor = {
+ *     label: 'pbr-pl',
+ *     bindGroupLayouts: [viewBgl, materialBgl, meshArrayBgl],
+ *   };
+ */
+export type PipelineLayoutDescriptor = ExplicitUndefined<Omit<Pick<GPUPipelineLayoutDescriptor, 'label' | 'bindGroupLayouts'>, 'bindGroupLayouts'>> & {
+    /**
+     * Iterable of BindGroupLayout opaque handles (forgeax tightening: the
+     * iterable element type is the forgeax `BindGroupLayout` brand). Same D-S5
+     * pattern as BindGroupDescriptor.layout.
+     */
+    bindGroupLayouts: Iterable<BindGroupLayout>;
+};
+/** GPU render pipeline vertex stage with an opaque forgeax shader module. */
+export type RenderPipelineVertexState = ExplicitUndefined<Omit<GPUVertexState, 'module' | 'buffers'>> & {
+    module: ShaderModule;
+    buffers: NonNullable<GPUVertexState['buffers']>;
+};
+/** GPU render pipeline fragment stage with an opaque forgeax shader module. */
+export type RenderPipelineFragmentState = ExplicitUndefined<Omit<GPUFragmentState, 'module' | 'targets'>> & {
+    module: ShaderModule;
+    targets: NonNullable<GPUFragmentState['targets']>;
+};
+/** GPU render pipeline descriptor with opaque forgeax layout and shader handles. */
+export type RenderPipelineDescriptor = ExplicitUndefined<Omit<Pick<GPURenderPipelineDescriptor, 'label' | 'layout' | 'vertex' | 'primitive' | 'depthStencil' | 'multisample' | 'fragment'>, 'layout' | 'vertex' | 'fragment'>> & {
+    layout: 'auto' | PipelineLayout;
+    vertex: RenderPipelineVertexState;
+    fragment?: RenderPipelineFragmentState | undefined;
+};
+/**
+ * Command encoder descriptor (Pick<GPUCommandEncoderDescriptor, 'label'>).
+ *
+ * Spec anchor: W3C WebGPU 22 GPUCommandEncoder /
+ * [@webgpu/types.GPUCommandEncoderDescriptor].
+ *
+ * @example
+ * const desc: CommandEncoderDescriptor = { label: 'frame-encoder' };
+ */
+export type CommandEncoderDescriptor = ExplicitUndefined<Pick<GPUCommandEncoderDescriptor, 'label'>>;
+/**
+ * Render-pass color attachment (Pick<GPURenderPassColorAttachment, ...> with
+ * `view` field aligned to the forgeax `TextureView` opaque handle, per
+ * feat-20260510-rhi-resource-creation M2 view narrow Path X / breakage point
+ * #1).
+ *
+ * Spec anchor: W3C WebGPU 22.7 Render pass /
+ * [@webgpu/types.GPURenderPassColorAttachment].
+ *
+ * v0.1.69 spec shape: `view: GPUTexture | GPUTextureView`. The forgeax RHI
+ * tightens the union to the single `TextureView` brand (the only branch the
+ * shim ever produces post-M1). Charter proposition 5 consistent abstraction
+ * (the field type matches what `RhiDevice.createTextureView` returns) +
+ * proposition 4 explicit failure (passing a `Texture` brand here is a tsc red
+ * signal; the AI user is steered to the spec idiom).
+ *
+ * **Migration**: see AGENTS.md break-point list 2026-05-10 #1
+ * "view: Texture -> TextureView narrow (major breaking)" for the call-site
+ * upgrade diff (3 narrowed fields: this `view` + `resolveTarget` +
+ * `RenderPassDepthStencilAttachment.view`).
+ *
+ * @example
+ * const view = device.createTextureView(tex, {}).unwrap();
+ * const att: RenderPassColorAttachment = {
+ *   view,
+ *   clearValue: { r: 0, g: 0, b: 0, a: 1 },
+ *   loadOp: 'clear',
+ *   storeOp: 'store',
+ * };
+ */
+export type RenderPassColorAttachment = ExplicitUndefined<Omit<Pick<GPURenderPassColorAttachment, 'view' | 'depthSlice' | 'resolveTarget' | 'clearValue' | 'loadOp' | 'storeOp'>, 'view' | 'resolveTarget'>> & {
+    /**
+     * TextureView target of this color attachment (view narrow Path X: aligned
+     * to the forgeax `TextureView` brand returned by `createTextureView`; not
+     * the spec union `GPUTexture | GPUTextureView`).
+     */
+    view: TextureView;
+    /**
+     * Optional resolve target for multisample resolution. Same view narrow
+     * alignment as `view`.
+     */
+    resolveTarget?: TextureView | undefined;
+};
+/**
+ * Render-pass depth/stencil attachment (Pick<GPURenderPassDepthStencilAttachment,
+ * ...> with `view` field aligned to the forgeax `TextureView` opaque handle,
+ * per feat-20260510-rhi-resource-creation M2 view narrow Path X / breakage
+ * point #1).
+ *
+ * Spec anchor: W3C WebGPU 22.7 Render pass /
+ * [@webgpu/types.GPURenderPassDepthStencilAttachment].
+ *
+ * Same view narrow alignment as RenderPassColorAttachment.
+ *
+ * **Migration**: see AGENTS.md break-point list 2026-05-10 #1 for the
+ * call-site upgrade diff covering this `view` field plus the two
+ * `RenderPassColorAttachment` narrowed fields.
+ *
+ * @example
+ * const view = device.createTextureView(depthTex, {}).unwrap();
+ * const ds: RenderPassDepthStencilAttachment = {
+ *   view,
+ *   depthClearValue: 1,
+ *   depthLoadOp: 'clear',
+ *   depthStoreOp: 'store',
+ * };
+ */
+export type RenderPassDepthStencilAttachment = ExplicitUndefined<Omit<Pick<GPURenderPassDepthStencilAttachment, 'view' | 'depthClearValue' | 'depthLoadOp' | 'depthStoreOp' | 'depthReadOnly' | 'stencilClearValue' | 'stencilLoadOp' | 'stencilStoreOp' | 'stencilReadOnly'>, 'view'>> & {
+    /**
+     * TextureView target of this depth/stencil attachment (view narrow Path X:
+     * aligned to the forgeax `TextureView` brand).
+     */
+    view: TextureView;
+};
+/**
+ * Render-pass descriptor (Pick<GPURenderPassDescriptor, ...>).
+ *
+ * Spec anchor: W3C WebGPU 22.7 Render pass /
+ * [@webgpu/types.GPURenderPassDescriptor].
+ *
+ * `colorAttachments` element type uses the forgeax narrow
+ * `RenderPassColorAttachment` (with `view: TextureView`);
+ * `depthStencilAttachment` uses `RenderPassDepthStencilAttachment`.
+ *
+ * @example
+ * const view = device.createTextureView(tex, {}).unwrap();
+ * const desc: RenderPassDescriptor = {
+ *   label: 'frame',
+ *   colorAttachments: [{ view, loadOp: 'clear', storeOp: 'store',
+ *                        clearValue: { r: 0, g: 0, b: 0, a: 1 } }],
+ * };
+ */
+export type RenderPassDescriptor = ExplicitUndefined<Omit<Pick<GPURenderPassDescriptor, 'label' | 'colorAttachments' | 'depthStencilAttachment' | 'occlusionQuerySet' | 'timestampWrites' | 'maxDrawCount'>, 'colorAttachments' | 'depthStencilAttachment' | 'occlusionQuerySet' | 'timestampWrites'>> & {
+    /**
+     * Color attachments for this render pass (forgeax narrow element type per
+     * view narrow Path X: each entry's `view` field is `TextureView`, not the
+     * spec union `GPUTexture | GPUTextureView`).
+     */
+    colorAttachments: Iterable<RenderPassColorAttachment | null | undefined>;
+    /** Optional depth/stencil attachment with the same view narrow alignment. */
+    depthStencilAttachment?: RenderPassDepthStencilAttachment | undefined;
+    /** Occlusion query set (capability-gated). The shim accepts a
+     *  `QuerySet` brand created via `device.createQuerySet({ type: 'occlusion',
+     *  count })` and pairs it with `pass.beginOcclusionQuery(idx) /
+     *  pass.endOcclusionQuery()`; both methods now have real implementations
+     *  (see `RhiRenderPassEncoder` below). Capability gate: read
+     *  `device.caps.timestampQuery` ahead of `'timestamp'` query sets;
+     *  occlusion sets are unconditionally available. */
+    occlusionQuerySet?: QuerySet | undefined;
+    /** Optional timestamp query set and the pass boundary write slots. */
+    timestampWrites?: RenderPassTimestampWrites | undefined;
+};
+/** Timestamp writes attached to a render pass descriptor. */
+export interface RenderPassTimestampWrites {
+    querySet: QuerySet;
+    beginningOfPassWriteIndex?: number | undefined;
+    endOfPassWriteIndex?: number | undefined;
+}
+/** Compute-pass descriptor with forgeax-owned timestamp query handles. */
+export type ComputePassDescriptor = ExplicitUndefined<Omit<Pick<GPUComputePassDescriptor, 'label' | 'timestampWrites'>, 'timestampWrites'>> & {
+    timestampWrites?: ComputePassTimestampWrites | undefined;
+};
+/** Timestamp writes attached to a compute pass descriptor. */
+export interface ComputePassTimestampWrites {
+    querySet: QuerySet;
+    beginningOfPassWriteIndex?: number | undefined;
+    endOfPassWriteIndex?: number | undefined;
+}
+/** Hardware-probe layer: readonly boolean capability flags. */
+export interface RhiCaps {
+    /**
+     * The rendering backend kind — single source of truth for backend-aware
+     * logic (e.g. explicit barrier insertion vs. spec-managed / GL-implicit
+     * sync). Closed 4-member union: every backend reports exactly one.
+     *
+     * - `'webgpu'`: browser WebGPU — spec-managed barriers, no explicit
+     *   barrier insertion needed.
+     * - `'wgpu-native'`: wgpu native-desktop runtime (Tauri / native) —
+     *   requires explicit Vulkan/Metal/DX12 barrier commands.
+     * - `'wgpu-webgl2'`: wgpu GLES3/WebGL2 backend — GL implicit sync, no
+     *   explicit barrier insertion needed (equivalence group with `'webgpu'`).
+     * - `'null'`: headless no-op backend (`@forgeax/engine-rhi-null`) for
+     *   structural unit tests — no GPU / DOM; records command-stream shape into
+     *   a ledger instead of executing it. No barrier insertion needed (the
+     *   no-op backend executes nothing); falls into the same no-barrier branch
+     *   as `'webgpu'` / `'wgpu-webgl2'`.
+     *
+     * @note `exactOptionalPropertyTypes` requires every backend fill this
+     *   field; a backend that omits it produces a tsc compile error.
+     */
+    readonly backendKind: 'webgpu' | 'wgpu-native' | 'wgpu-webgl2' | 'null';
+    /** Whether compute pipelines are supported. */
+    readonly compute: boolean;
+    /** Whether timestamp queries are supported. */
+    readonly timestampQuery: boolean;
+    /** Backend-owned nanoseconds represented by one timestamp tick, or null when unavailable. */
+    readonly timestampPeriodNanoseconds: number | null;
+    /** Whether indirect drawing is supported. */
+    readonly indirectDrawing: boolean;
+    /**
+     * Whether BC texture compression (BC1-BC7) is available.
+     *
+     * Derived from `adapter.features.has('texture-compression-bc')`.
+     * On rhi-null this is always `false` (headless has no compression hardware,
+     * AC-06).
+     */
+    readonly textureCompressionBc: boolean;
+    /**
+     * Whether ETC2 texture compression is available.
+     *
+     * Derived from `adapter.features.has('texture-compression-etc2')`.
+     * On rhi-null this is always `false` (headless has no compression hardware,
+     * AC-06).
+     */
+    readonly textureCompressionEtc2: boolean;
+    /**
+     * Whether ASTC texture compression is available.
+     *
+     * Derived from `adapter.features.has('texture-compression-astc')`.
+     * On rhi-null this is always `false` (headless has no compression hardware,
+     * AC-06).
+     */
+    readonly textureCompressionAstc: boolean;
+    /**
+     * Whether multi-draw indirect is available (wgpu native extension).
+     *
+     * @reserved-for-wgpu-native-only always `false` on browser backends; only
+     *   available when the forgeax renderer runs against a wgpu native runtime
+     *   (Tauri / native runtime, not the wasm bundle). `caps.X = false` is an
+     *   explicit signal, never an exception (charter proposition 4 / AGENTS.md
+     *   `RHI / WebGPU` shape rule #2 capability-gated).
+     */
+    readonly multiDrawIndirect: boolean;
+    /**
+     * Whether push constants are available (wgpu native extension).
+     *
+     * @reserved-for-wgpu-native-only always `false` on browser backends; only
+     *   available when the forgeax renderer runs against a wgpu native runtime
+     *   (Tauri / native runtime, not the wasm bundle). `caps.X = false` is an
+     *   explicit signal, never an exception (charter proposition 4 / AGENTS.md
+     *   `RHI / WebGPU` shape rule #2 capability-gated).
+     */
+    readonly pushConstants: boolean;
+    /**
+     * Whether bindless texture array is available (wgpu native extension).
+     *
+     * @reserved-for-wgpu-native-only always `false` on browser backends; only
+     *   available when the forgeax renderer runs against a wgpu native runtime
+     *   (Tauri / native runtime, not the wasm bundle). `caps.X = false` is an
+     *   explicit signal, never an exception (charter proposition 4 / AGENTS.md
+     *   `RHI / WebGPU` shape rule #2 capability-gated).
+     */
+    readonly textureBindingArray: boolean;
+    /**
+     * Whether sampler binding aliasing is supported across pipelines.
+     *
+     * @spec-anchor W3C WebGPU §10.3 Bind group layout — spec mandates that a
+     *   sampler may alias multiple binding slots; both navigator.gpu and the
+     *   wgpu wasm bundle satisfy this so the field is always `true` on browser
+     *   backends.
+     * @note Always `true` on shipped backends (WebGPU + wgpu wasm). The field
+     *   exists for potential future backends that lack sampler aliasing.
+     * @hint AI users use `caps.samplerAliasing` to gate code that creates two
+     *   `BindGroupEntry`s pointing at the same `Sampler` across different
+     *   layouts; `caps.X = false` is an explicit signal, never an exception
+     *   (charter proposition 4).
+     */
+    readonly samplerAliasing: boolean;
+    /**
+     * Whether the renderer can issue indirect draws with a non-zero
+     * `firstInstance`.
+     *
+     * @spec-anchor W3C WebGPU §22.4 drawIndirect — the `indirect-first-instance`
+     *   feature on `GPUAdapter.features` gates non-zero `firstInstance` in
+     *   indirect draws; rhi-webgpu maps this to `device.features.has(
+     *   'indirect-first-instance')`.
+     * @note `false` on backends without indirect drawing support.
+     * @hint Most AI users never need this; the field surfaces so a renderer
+     *   author building instanced draw batchers can gate the fast path. With
+     *   `caps.firstInstanceIndirect === false` the renderer must pre-rebase
+     *   instance indices in the vertex shader (charter proposition 5
+     *   consistent abstraction over a discoverable cap difference).
+     */
+    readonly firstInstanceIndirect: boolean;
+    /**
+     * Whether storage buffer bindings are available
+     * (`device.limits.maxStorageBuffersPerShaderStage > 0`).
+     *
+     * @spec-anchor W3C WebGPU §3.6.2 GPUSupportedLimits.
+     *   maxStorageBuffersPerShaderStage; `> 0` means the device supports the
+     *   `storage` / `read-only-storage` binding types.
+     * @note `false` on backends without storage buffer support.
+     * @hint AI users gate compute / large-buffer paths on
+     *   `caps.storageBuffer`; the per-stage numeric limit lives on
+     *   `device.limits.maxStorageBuffersPerShaderStage` for capacity planning
+     *   (charter proposition 4: `caps.X = false` is an explicit signal).
+     */
+    readonly storageBuffer: boolean;
+    /**
+     * Whether storage texture bindings are available
+     * (`device.limits.maxStorageTexturesPerShaderStage > 0`).
+     *
+     * @spec-anchor W3C WebGPU §3.6.2 GPUSupportedLimits.
+     *   maxStorageTexturesPerShaderStage; `> 0` means the device supports the
+     *   `write-only` / `read-write` storage texture binding types.
+     * @note `false` on backends without storage texture support.
+     * @hint AI users gate image-effects compute / postprocess paths on
+     *   `caps.storageTexture`; the per-stage numeric limit lives on
+     *   `device.limits.maxStorageTexturesPerShaderStage` (charter proposition
+     *   4: `caps.X = false` is an explicit signal).
+     */
+    readonly storageTexture: boolean;
+    /**
+     * Whether the device can create `rgba16float` textures with `RENDER_ATTACHMENT`
+     * usage, enabling the HDR cubemap path for IBL irradiance / specular prefilter
+     * and downstream HDR render-target chains.
+     *
+     * @spec-anchor W3C WebGPU $25.1 GPUTextureFormat — `rgba16float` is an
+     *   optional texture format whose `RENDER_ATTACHMENT` capability is probed by
+     *   attempting `createTexture({ format: 'rgba16float', usage:
+     *   GPUTextureUsage.RENDER_ATTACHMENT, size: [1, 1, 1] })` on the live
+     *   device; failure maps the cap to `false`.
+     * @note Probed at device-creation time via a synchronous `createTexture`
+     *   call, not via `GPUAdapter.features`. The `rgba16float` format is widely
+     *   supported but `RENDER_ATTACHMENT` with float formats is optional per spec
+     *   so the cap reflects the concrete device, not the adapter feature list.
+     * @hint AI users gate IBL / HDR post-processing paths on
+     *   `caps.rgba16floatRenderable`; when `false` the internal equirect-to-cubemap
+     *   IBL projection (driven by declaring `Skylight{equirect}`) degrades to the
+     *   white-cube fallback and fires `{ code: 'equirect-projection-failed' }` with
+     *   a machine-readable `expected` field naming this cap (charter P3 structured
+     *   failure).
+     */
+    readonly rgba16floatRenderable: boolean;
+    /**
+     * Whether the device can create `rg11b10ufloat` textures with
+     * `RENDER_ATTACHMENT` usage, enabling the HDR swapchain / render-target path
+     * with reduced bit-depth precision versus `rgba16float`.
+     *
+     * @spec-anchor W3C WebGPU $25.1 GPUTextureFormat — `rg11b10ufloat` is
+     *   `RENDER_ATTACHMENT`-capable only when the optional feature
+     *   `rg11b10ufloat-renderable` is enabled (W3C WebGPU $4.2). Probed by gating
+     *   on `device.features.has('rg11b10ufloat-renderable')` first; only then
+     *   confirmed by `createTexture({ format: 'rg11b10ufloat', usage:
+     *   GPUTextureUsage.RENDER_ATTACHMENT, size: [1, 1, 1] })`.
+     * @note The format packs 11+11+10 unsigned float bits into 32 bits per pixel;
+     *   it is a popular HDR swapchain format for engines that trade precision
+     *   for bandwidth but its `RENDER_ATTACHMENT` capability is not universal.
+     *   The feature gate is the authoritative answer (avoiding fan-out via
+     *   `device.onuncapturederror` when the optional feature is absent); the
+     *   subsequent probe handles the rare case where the feature is reported
+     *   but the concrete device still rejects.
+     * @hint AI users can select an HDR back-buffer format by reading
+     *   `caps.rg11b10ufloatRenderable` before creating a
+     *   `GPUTextureUsage.RENDER_ATTACHMENT` texture at that format; when `false`
+     *   fall back to `rgba16float` (if `caps.rgba16floatRenderable` is true)
+     *   or an SDR format.
+     */
+    readonly rg11b10ufloatRenderable: boolean;
+    /**
+     * Whether the device supports sampling `rgba32float` textures with a
+     * `filtering` sampler (linear / mipmap filtering), NOT just with a
+     * `non-filtering` sampler.
+     *
+     * @spec-anchor W3C WebGPU $10.3 Bind group layout — a bind group layout
+     *   entry pairing a `filtering` sampler type with `sampleType: 'float'`
+     *   (matching `rgba32float`) validates only when the
+     *   `float32-filterable` feature is enabled. The cap probes this via
+     *   `device.createBindGroupLayout({ entries: [{ sampler: { type:
+     *   'filtering' } }, { texture: { sampleType: 'float' } }] })` and
+     *   `device.createSampler({ minFilter: 'linear', magFilter: 'linear' })`;
+     *   failure maps the cap to `false`.
+     * @note Probed by gating on `device.features.has('float32-filterable')`
+     *   first (the authoritative answer per spec $4.2; avoids fan-out via
+     *   `device.onuncapturederror` when the optional feature is absent); only
+     *   then confirmed by exercising the bind-group-layout. The subsequent
+     *   probe handles the rare case where the feature is reported but the
+     *   concrete device still rejects (spec ambiguity, driver quirks).
+     * @hint AI users gate float32-sampled compute / post-process paths on
+     *   `caps.float32Filterable`; when `false` use `sampleType: 'unfilterable-
+     *   float'` with a `non-filtering` sampler and compute the filter kernel
+     *   manually in the shader, or fall back to `rgba16float` with filtering.
+     */
+    readonly float32Filterable: boolean;
+    /**
+     * Maximum number of color attachments per render pass.
+     *
+     * @spec-anchor W3C WebGPU $3.6.2 GPUSupportedLimits.maxColorAttachments;
+     *   spec minimum = 4, defaults to 8 on mainstream backends.
+     *   HDRP deferred pipeline requires >= 4 (3 g-buffer RT + 1 depth);
+     *   installPipeline checks this cap at install time and throws
+     *   `hdrp-deferred-caps-insufficient` on violation (charter P3).
+     * @note add-only minor (feat-20260612-hdrp-deferred-shading-learn-render-5-8
+     *   M1 / w5); no existing field is modified.
+     */
+    readonly maxColorAttachments: number;
+}
+/**
+ * Enabled feature set, opaque iteration only via `has()`.
+ *
+ * Aligned with `GPUSupportedFeatures` shape; this empty interface intentionally
+ * adds no fields — the concrete enabled set is decided at `requestDevice` time
+ * and is then probed by AI users via `device.features.has('feature-name')`
+ * (charter proposition 5 consistent abstraction; no implementation-detail leak,
+ * no enumeration helper that would tie callers to a fixed feature list).
+ *
+ * @see {@link GPUSupportedFeatures}
+ */
+export interface RhiFeatures extends ReadonlySet<GPUFeatureName> {
+}
+/** Numeric-limits layer aligned with GPUSupportedLimits (incl Compatibility
+ *  Mode follow-on fields). */
+export type RhiLimits = Readonly<GPUSupportedLimits>;
+/**
+ * RhiAdapter request options.
+ *
+ * Spec anchor: W3C WebGPU §3.2 `GPURequestAdapterOptions` /
+ * [@webgpu/types.GPURequestAdapterOptions]. Fields pass through to the
+ * underlying `navigator.gpu.requestAdapter(opts)` call.
+ */
+export type RequestAdapterOptions = ExplicitUndefined<Pick<GPURequestAdapterOptions, 'powerPreference' | 'forceFallbackAdapter'>>;
+/**
+ * RhiAdapter.requestDevice options.
+ *
+ * Spec anchor: W3C WebGPU §3.4 `GPUDeviceDescriptor` /
+ * [@webgpu/types.GPUDeviceDescriptor]. Fields pass through to the underlying
+ * `adapter.requestDevice(opts)` call.
+ */
+export type RequestDeviceOptions = ExplicitUndefined<Pick<GPUDeviceDescriptor, 'label' | 'requiredFeatures' | 'requiredLimits'>>;
+/**
+ * RhiInstance — entry point for adapter discovery (K-6 strict two-step path).
+ *
+ * Spec anchor: W3C WebGPU §3.1 `GPU` interface / [@webgpu/types.GPU]; wgpu
+ * `Instance::request_adapter` (research §6.1) + Dawn
+ * `InstanceBase::APIRequestAdapter` (§6.2).
+ *
+ * Replaces the legacy top-level `rhi.requestDevice(opts)` factory (break-
+ * point #2). AI users follow the spec idiom:
+ *   const a = (await rhi.requestAdapter()).unwrap();
+ *   const d = (await a.requestDevice(opts)).unwrap();
+ *
+ * @example
+ *   const adapterResult = await rhi.requestAdapter();
+ *   if (!adapterResult.ok) {
+ *     // route via switch (adapterResult.error.code)
+ *   }
+ */
+export interface RhiInstance {
+    /**
+     * Request a GPU adapter.
+     *
+     * Spec anchor: W3C WebGPU §3.1 `GPU.requestAdapter` /
+     * [@webgpu/types.GPU.requestAdapter].
+     *
+     * @param opts — W3C-spec request adapter options (powerPreference,
+     *   forceFallbackAdapter).
+     * @param compatibleSurface — non-W3C extension required by the wgpu GL
+     *   backend for adapter enumeration. Provided as a positional escape hatch
+     *   so the first parameter stays spec-aligned (plan-strategy D-5).
+     *   rhi-webgpu accepts and ignores this parameter (dual-impl symmetry);
+     *   rhi-wgpu routes it to `requestAdapterWithCanvas`.
+     *
+     * Failure paths (research §F-5):
+     *   - adapter null -> `Result.err({ code: 'adapter-unavailable' })`.
+     */
+    requestAdapter(opts?: RequestAdapterOptions | undefined, compatibleSurface?: HTMLCanvasElement | OffscreenCanvas | undefined): Promise<Result<RhiAdapter, RhiError>>;
+}
+/**
+ * RhiAdapter — capability-probe layer + device-creation entry (K-5 + K-6).
+ *
+ * Spec anchor: W3C WebGPU §3.2 `GPUAdapter` interface /
+ * [@webgpu/types.GPUAdapter]; wgpu `Adapter::request_device` (research §6.1)
+ * + Dawn `AdapterBase::APIRequestDevice` (§6.2).
+ *
+ * The `features` / `limits` fields let AI users **pre-screen** device
+ * capabilities before calling `requestDevice(opts)` (charter proposition 4
+ * forward-reachable: features mismatch becomes visible before spec
+ * validation surfaces it).
+ *
+ * @example
+ *   if (!adapter.features.has('timestamp-query')) {
+ *     // skip timestamp-related code paths
+ *   }
+ *   const deviceResult = await adapter.requestDevice({
+ *     requiredFeatures: ['timestamp-query'],
+ *   });
+ */
+export interface RhiAdapter {
+    /**
+     * Read-only feature-name set (K-5).
+     *
+     * Aligned with `GPUAdapter.features` projection of `GPUSupportedFeatures`
+     * (a read-only Set) **and** with `RhiDevice.features` (Round 3 fix-up
+     * F-P1-2: cross-tier shape uniformity — AI users use `.has(name)` on
+     * both abstraction layers, no projection drift).
+     *
+     * F-1 ai-user-review: mutation of set entries (`features.add('x')` /
+     * deletion / clear) is rejected at compile time via `ReadonlySet`;
+     * charter proposition 4 explicit failure + proposition 5 consistent
+     * abstraction.
+     */
+    readonly features: ReadonlySet<GPUFeatureName>;
+    /**
+     * Read-only numeric-limits map (K-5).
+     *
+     * Aligned with `GPUAdapter.limits` projection of `GPUSupportedLimits`. The
+     * forgeax form flattens to a `Readonly<Record<string, number>>` so AI users
+     * can do `adapter.limits.maxTextureDimension2D` lookups without holding the
+     * spec object handle.
+     *
+     * F-1 ai-user-review: mutation of values (`limits.x = 0`) is rejected at
+     * compile time.
+     */
+    readonly limits: Readonly<Record<string, number>>;
+    /**
+     * Request a GPU device.
+     *
+     * Spec anchor: W3C WebGPU §3.2 `GPUAdapter.requestDevice` /
+     * [@webgpu/types.GPUAdapter.requestDevice].
+     *
+     * Returns `Result<RhiDevice, RhiError>` (K-6: NOT a `(Device, Queue)` tuple
+     * — queue is exposed via `RhiDevice.queue`).
+     *
+     * Failure paths (research §F-5):
+     *   - feature not enabled -> `Result.err({ code: 'feature-not-enabled' })`.
+     *   - limit exceeded -> `Result.err({ code: 'limit-exceeded' })`.
+     */
+    requestDevice(opts?: RequestDeviceOptions | undefined): Promise<Result<RhiDevice, RhiError>>;
+}
+/**
+ * Canvas configuration descriptor (Pick<GPUCanvasConfiguration, 7 fields>).
+ *
+ * Spec anchor: W3C WebGPU §3.3 `GPUCanvasConfiguration` /
+ * [@webgpu/types.GPUCanvasConfiguration].
+ *
+ * 7 fields (research §3.2):
+ *   - `device` (required): the GPUDevice for the configured context.
+ *   - `format` (required): one of `{'bgra8unorm', 'rgba8unorm', 'rgba16float'}`
+ *     (the spec normative supported context formats).
+ *   - `usage` (default `0x10` = RENDER_ATTACHMENT): bitmask of GPUTextureUsage
+ *     for the swap-chain textures.
+ *   - `viewFormats` (default `[]`): list of formats createView may yield;
+ *     **the spec sRGB-render-target idiom** uses `format='bgra8unorm'` +
+ *     `viewFormats=['bgra8unorm-srgb']` + `device.createTextureView` (research
+ *     §3.2 normative).
+ *   - `colorSpace` (default `'srgb'`): predefined color space for the canvas.
+ *   - `toneMapping` (default `{}` ≅ `{ mode: 'standard' }`): HDR tone-mapping
+ *     descriptor; the spec NOTE in research §3.2 says implementations
+ *     without tone-mapping support **omit** this from `getConfiguration()`.
+ *   - `alphaMode` (default `'opaque'`): canvas compositing mode.
+ *
+ * Field NAMES align byte-for-byte with the spec; the forgeax `?: T |
+ * undefined` shape (S-7 / hard-constraint 10) lets writers omit or pass
+ * `undefined` explicitly while the shim distinguishes via `'x' in src`.
+ */
+export type CanvasConfiguration = ExplicitUndefined<Omit<Pick<GPUCanvasConfiguration, 'device' | 'format' | 'usage' | 'viewFormats' | 'colorSpace' | 'toneMapping' | 'alphaMode'>, 'device'>> & {
+    /**
+     * The forgeax RhiDevice the configured context binds to (D-S5 pattern: spec
+     * `device: GPUDevice` is replaced by the forgeax brand so AI users pass the
+     * device they got from `rhi.requestAdapter().requestDevice()`).
+     */
+    device: RhiDevice;
+};
+declare const RhiSurfaceBrand: unique symbol;
+/**
+ * RhiSurface — opaque abstraction over a canvas surface
+ * (HTMLCanvasElement / OffscreenCanvas).
+ *
+ * Spec couples GPUCanvasContext to a canvas (research §3.1); the forgeax
+ * abstraction wraps the raw GPUCanvasContext in an opaque brand. AI users
+ * obtain the `RhiCanvasContext` via
+ * `rhi.acquireCanvasContext(canvas)` (returns `Result<RhiCanvasContext, RhiError>`).
+ *
+ * Charter proposition 5 consistent abstraction: the surface brand decouples
+ * AI-user code from the DOM canvas zoo (HTMLCanvasElement / OffscreenCanvas /
+ * native Window).
+ */
+export interface RhiSurface {
+    readonly [RhiSurfaceBrand]: void;
+}
+/**
+ * RhiCanvasContext — forgeax canvas-context abstraction (M3 / K-4).
+ *
+ * Spec anchor: W3C WebGPU §3.3 `GPUCanvasContext` /
+ * [@webgpu/types.GPUCanvasContext]. 4 methods (research §3.1) match the spec
+ * names; the return types differ:
+ *   - `configure` returns `Result<void, RhiError>` (the spec returns void; the
+ *     forgeax form surfaces `webgpu-runtime-error` on format-gate / device-
+ *     lost paths via Result, charter proposition 4 explicit failure).
+ *   - `unconfigure` returns void (spec literal alignment).
+ *   - `getConfiguration` returns `CanvasConfiguration | undefined` (the spec
+ *     returns `GPUCanvasConfiguration?`; forgeax uses `undefined`).
+ *   - `getCurrentTexture` returns `Result<Texture, RhiError>` (K-4: Texture
+ *     brand, NOT TextureView; AI users go two-step
+ *     `device.createTextureView(canvasContext.getCurrentTexture().unwrap(), {})`).
+ *
+ * Lifecycle (research §3.3 [[Expire the current texture]]): currentTexture
+ * **must NOT be cached across frames** — every frame must call
+ * `getCurrentTexture()` afresh.
+ */
+export interface RhiCanvasContext {
+    /**
+     * Configure the canvas context with a forgeax CanvasConfiguration.
+     *
+     * Returns `Result<void, RhiError>` (charter proposition 4 explicit failure).
+     *
+     * Failure paths (research §3.3):
+     *   - `format` not in supported context formats (`{'bgra8unorm',
+     *     'rgba8unorm', 'rgba16float'}`) -> `'webgpu-runtime-error'` with
+     *     `.expected = 'one of bgra8unorm/rgba8unorm/rgba16float'`.
+     *   - `device` invalid | lost -> `'rhi-not-available'`.
+     *
+     * @example
+     *   const out = canvasContext.configure({
+     *     device,
+     *     format: 'bgra8unorm',
+     *     usage: GPUTextureUsage.RENDER_ATTACHMENT,
+     *     viewFormats: ['rgba8unorm-srgb'],
+     *   });
+     *   if (!out.ok) {
+     *     // route via switch (out.error.code)
+     *   }
+     */
+    configure(desc: CanvasConfiguration): Result<void, RhiError>;
+    /**
+     * Unconfigure the canvas context (spec literal void return).
+     *
+     * Idempotent (already-unconfigured contexts continue to be unconfigured;
+     * Operation is silent).
+     */
+    unconfigure(): void;
+    /**
+     * Return the current canvas configuration, or `undefined` if the context is
+     * unconfigured.
+     *
+     * Feature-detection entry (research §3.2 spec NOTE): when an implementation
+     * does not support a configuration field (e.g. tone-mapping), the field is
+     * **omitted** from the returned record (NOT defaulted) so AI users can use
+     * `'toneMapping' in conf` to detect support.
+     */
+    getConfiguration(): CanvasConfiguration | undefined;
+    /**
+     * Get the current swap-chain texture (K-4: returns Texture brand, NOT
+     * TextureView).
+     *
+     * Spec anchor: W3C WebGPU §3.3 `GPUCanvasContext.getCurrentTexture` /
+     * [@webgpu/types.GPUCanvasContext.getCurrentTexture].
+     *
+     * Failure paths (research §3.3):
+     *   - context unconfigured -> `'webgpu-runtime-error'` (spec
+     *     `InvalidStateError` mapping).
+     *
+     * AI users typically pair this with `device.createTextureView` to get the
+     * render-pass attachment view (charter proposition 5 consistent abstraction):
+     *   const tex = canvasContext.getCurrentTexture().unwrap();
+     *   const view = device.createTextureView(tex, {}).unwrap();
+     *   pass.beginRenderPass({ colorAttachments: [{ view, ... }] });
+     *
+     * Lifecycle (research §3.3 [[Expire the current texture]]): each frame
+     * **must call this fresh**; the forgeax shim does NOT cache across frames.
+     */
+    getCurrentTexture(): Result<Texture, RhiError>;
+}
+/** GPU device - sole entry point for resource creation + capability probing. */
+export interface RhiDevice {
+    /** Hardware-probe layer (charter proposition 5). */
+    readonly caps: RhiCaps;
+    /** Enabled-features layer. */
+    readonly features: RhiFeatures;
+    /** Numeric-limits layer. */
+    readonly limits: RhiLimits;
+    /** Create GPU buffer. */
+    createBuffer(desc: BufferDescriptor): Result<Buffer, RhiError>;
+    /** Create GPU texture. */
+    createTexture(desc: TextureDescriptor): Result<Texture, RhiError>;
+    /**
+     * Destroy a GPU buffer obtained from `createBuffer`.
+     *
+     * Spec anchor: W3C WebGPU §gpubuffer-destroy /
+     * [@webgpu/types.GPUBuffer.destroy]; wgpu wasm
+     * `RhiWgpuBuffer::destroy` (research §F-1; both surfaces are idempotent
+     * void at the underlying GPU).
+     *
+     * The forgeax form prefers fail-fast over the spec idempotent void:
+     * the shim layer (rhi-webgpu / rhi-wgpu) tracks per-handle
+     * `destroyed: boolean` and surfaces a second destroy as
+     * `Result.err({ code: 'destroy-after-destroy' })` rather than silently
+     * succeeding. Double destroy is almost always a lifecycle bug — caching
+     * a stale handle, a forgotten registry slot, a race between dispose
+     * paths — and surfacing it early at the call site is more useful than
+     * swallowing it (plan-strategy D-7 + architecture-principles §5 Fail
+     * Fast). Charter proposition 4 explicit failure.
+     *
+     * Failure paths:
+     *   - second destroy on the same handle ->
+     *     `Result.err({ code: 'destroy-after-destroy' })`.
+     *
+     * @example
+     *   const r = device.destroyBuffer(buf);
+     *   if (!r.ok) {
+     *     // route via switch (r.error.code)
+     *   }
+     */
+    destroyBuffer(buf: Buffer): Result<void, RhiError>;
+    /**
+     * Destroy a GPU query set obtained from `createQuerySet`.
+     *
+     * Query sets are device-owned resources even though the WebGPU surface does
+     * not expose them through the Buffer/Texture families. The explicit RHI
+     * seam lets Render release timestamp query sets exactly once after queue
+     * completion, including failure and disposal paths.
+     */
+    destroyQuerySet(querySet: QuerySet): Result<void, RhiError>;
+    /**
+     * Destroy a GPU texture obtained from `createTexture`.
+     *
+     * Spec anchor: W3C WebGPU §gputexture-destroy /
+     * [@webgpu/types.GPUTexture.destroy]; wgpu wasm idempotent void at the
+     * underlying GPU.
+     *
+     * Same fail-fast contract as `destroyBuffer`: the shim layer tracks
+     * per-handle `destroyed: boolean` and surfaces a second destroy as
+     * `Result.err({ code: 'destroy-after-destroy' })`.
+     *
+     * @example
+     *   const r = device.destroyTexture(tex);
+     *   if (!r.ok) {
+     *     // route via switch (r.error.code)
+     *   }
+     */
+    destroyTexture(tex: Texture): Result<void, RhiError>;
+    /**
+     * Create a GPU texture view of an existing texture.
+     *
+     * Spec anchor: W3C WebGPU §texture-view-creation /
+     * [@webgpu/types.GPUTexture.createView].
+     *
+     * Introduced in feat-20260510-rhi-resource-creation (M1). Cross-resource
+     * validation is performed fast-path by the shim before forwarding to raw
+     * GPUTexture.createView (research §1.1):
+     *   - `format` must be in `source.format ∪ source.viewFormats`; violation
+     *     returns Result.err({ code: 'webgpu-runtime-error' }).
+     *   - `usage` must be a subset of source.usage (bitmask); violation returns
+     *     the same code.
+     *
+     * @example
+     *   const r = device.createTextureView(tex, { format: 'rgba8unorm', dimension: '2d' });
+     *   if (!r.ok) {
+     *     // route via switch (r.error.code)
+     *   }
+     */
+    createTextureView(texture: Texture, desc: TextureViewDescriptor): Result<TextureView, RhiError>;
+    /** Create sampler (spec defaults are applied by the shim). */
+    createSampler(desc?: SamplerDescriptor | undefined): Result<Sampler, RhiError>;
+    /** Create bind group layout. */
+    createBindGroupLayout(desc: BindGroupLayoutDescriptor): Result<BindGroupLayout, RhiError>;
+    /**
+     * Create a bind group (instantiated layout + resource bindings).
+     *
+     * Spec anchor: W3C WebGPU 10 Resource binding /
+     * [@webgpu/types.GPUDevice.createBindGroup].
+     *
+     * Introduced in feat-20260509-ecs-render-bridge-mvp (D-S1) — additive
+     * extension; reuses the existing 17-member `RhiErrorCode` union
+     * ('feature-not-enabled' / 'limit-exceeded' / 'webgpu-runtime-error').
+     * No new error code is introduced (AGENTS.md evolution contract no-op,
+     * breakage list stays empty).
+     *
+     * @example
+     *   const out = device.createBindGroup({ label: 'view-bg', layout: bgl, entries: [...] });
+     *   if (!out.ok) {
+     *     // route via switch (out.error.code)
+     *   }
+     */
+    createBindGroup(desc: BindGroupDescriptor): Result<BindGroup, RhiError>;
+    /**
+     * Create a pipeline layout (aggregates BindGroupLayouts).
+     *
+     * Spec anchor: W3C WebGPU 10.3 Pipeline layout /
+     * [@webgpu/types.GPUDevice.createPipelineLayout].
+     *
+     * Introduced in feat-20260509-ecs-render-bridge-mvp (D-S1) — additive
+     * extension; reuses the existing 17-member `RhiErrorCode` union.
+     *
+     * @example
+     *   const out = device.createPipelineLayout({ label: 'pbr-pl', bindGroupLayouts: [viewBgl, materialBgl, meshArrayBgl] });
+     *   if (!out.ok) {
+     *     // route via switch (out.error.code)
+     *   }
+     */
+    createPipelineLayout(desc: PipelineLayoutDescriptor): Result<PipelineLayout, RhiError>;
+    /** Create render pipeline (synchronous path). */
+    createRenderPipeline(desc: RenderPipelineDescriptor): Result<RenderPipeline, RhiError>;
+    /**
+     * Create a compute pipeline (synchronous path).
+     *
+     * Spec anchor: W3C WebGPU §compute-pipeline-creation /
+     * [@webgpu/types.GPUDevice.createComputePipeline].
+     *
+     * Introduced in feat-20260510-rhi-resource-creation (M1). Capability gate
+     * (research §1.2 + plan-strategy §4.3 boundary case row 1):
+     *   `caps.compute === false` -> Result.err({ code: 'feature-not-enabled' }).
+     * The MVP WebGPU path always has caps.compute=true; the gate exists for
+     * potential future backends that lack compute.
+     *
+     * @example
+     *   const r = device.createComputePipeline({
+     *     layout: 'auto',
+     *     compute: { module, entryPoint: 'cs_main' },
+     *   });
+     *   if (!r.ok) {
+     *     // route via switch (r.error.code)
+     *   }
+     */
+    createComputePipeline(desc: ComputePipelineDescriptor): Result<ComputePipeline, RhiError>;
+    /**
+     * Create a query set (occlusion or timestamp).
+     *
+     * Spec anchor: W3C WebGPU §queries / [@webgpu/types.GPUDevice.createQuerySet].
+     *
+     * Introduced in feat-20260510-rhi-resource-creation (M1). Hard constraints
+     * (research §1.3):
+     *   - `count <= 4096` (spec normative); violation -> 'limit-exceeded'.
+     *   - `type === 'timestamp'` requires caps.timestampQuery; otherwise ->
+     *     'feature-not-enabled'.
+     *   - `count = 0` is legal.
+     *
+     * @example
+     *   const r = device.createQuerySet({ type: 'occlusion', count: 4 });
+     *   if (!r.ok) {
+     *     // route via switch (r.error.code)
+     *   }
+     */
+    createQuerySet(desc: QuerySetDescriptor): Result<QuerySet, RhiError>;
+    /**
+     * Create a command encoder.
+     *
+     * Spec anchor: W3C WebGPU 21.2 createCommandEncoder /
+     * [@webgpu/types.GPUDevice.createCommandEncoder].
+     *
+     * @example
+     *   const encResult = device.createCommandEncoder({ label: 'frame' });
+     *   if (!encResult.ok) {
+     *     // route via switch (encResult.error.code)
+     *   } else {
+     *     const enc = encResult.value;
+     *     // ... record commands ...
+     *   }
+     */
+    createCommandEncoder(desc?: CommandEncoderDescriptor | undefined): Result<RhiCommandEncoder, RhiError>;
+    /** Queue for command submission. */
+    readonly queue: RhiQueue;
+    /**
+     * Spec-style device.lost Promise (research F-4 / R2 mitigation). The engine
+     * layer performs single-source subscription + dual-form fan-out without a
+     * second cache. `reason` is a binary union ('destroyed' / 'unknown').
+     */
+    readonly lost: Promise<{
+        readonly reason: 'destroyed' | 'unknown';
+        readonly message: string;
+    }>;
+}
+/** GPU command queue - writeBuffer / submit + M5 writeTexture /
+ *  copyExternalImageToTexture / onSubmittedWorkDone. */
+export interface RhiQueue {
+    /** Direct write to a buffer (POD + ArrayBufferView, math-free). */
+    writeBuffer(buffer: Buffer, bufferOffset: number, data: ArrayBufferView | ArrayBuffer, dataOffset?: number | undefined, size?: number | undefined): Result<void, RhiError>;
+    /**
+     * Direct write to a texture region.
+     *
+     * Spec anchor: W3C WebGPU §queue-writetexture /
+     * [@webgpu/types.GPUQueue.writeTexture]. Field NAMES align byte-for-byte
+     * with the spec; the forgeax form returns Result<void, RhiError> instead
+     * of void so AI users can route alignment failures (research §1.3 +
+     * plan-strategy 2 K-2: bytesPerRow % 256 != 0 maps to
+     * 'queue-write-buffer-out-of-bounds').
+     *
+     * @example
+     *   const out = device.queue.writeTexture(
+     *     { texture: tex, mipLevel: 0, origin: [0, 0, 0] },
+     *     pixels,
+     *     { offset: 0, bytesPerRow: 256, rowsPerImage: H },
+     *     { width: W, height: H, depthOrArrayLayers: 1 },
+     *   );
+     *   if (!out.ok) {
+     *     // route via switch (out.error.code)
+     *   }
+     */
+    writeTexture(destination: TextureWriteDestination, data: ArrayBufferView | ArrayBuffer, dataLayout: Pick<GPUTexelCopyBufferLayout, 'offset' | 'bytesPerRow' | 'rowsPerImage'>, size: GPUExtent3DStrict): Result<void, RhiError>;
+    /**
+     * Copy an external image source (ImageBitmap / canvas / video) into a
+     * GPUTexture region.
+     *
+     * Spec anchor: W3C WebGPU §queue-copyexternalimagetotexture /
+     * [@webgpu/types.GPUQueue.copyExternalImageToTexture]. The forgeax form
+     * returns Result<void, RhiError>.
+     *
+     * dawn-node note: dawn-node lacks HTMLCanvasElement / VideoFrame /
+     * HTMLImageElement; only the ImageBitmap subset reachable from
+     * createImageBitmap is exercised in dawn tests (research §7.1).
+     */
+    copyExternalImageToTexture(source: Pick<GPUCopyExternalImageSourceInfo, 'source' | 'origin' | 'flipY'>, destination: ExternalImageTextureDestination, copySize: GPUExtent3DStrict): Result<void, RhiError>;
+    /** Submit command buffers (single-use). */
+    submit(commandBuffers: readonly CommandBuffer[]): Result<void, RhiError>;
+    /**
+     * Resolve when all currently-enqueued operations have completed.
+     *
+     * Spec anchor: W3C WebGPU §queue-onsubmittedworkdone /
+     * [@webgpu/types.GPUQueue.onSubmittedWorkDone]. Returns
+     * `Promise<undefined>` per spec normative (research §5.1: no reject path;
+     * device-lost flows through `RhiDevice.lost` instead). Ordering
+     * constraints (research §5.2):
+     *   - constraint #1 (FIFO): if p1 = q.onSubmittedWorkDone() is called
+     *     before p2 = q.onSubmittedWorkDone(), p1 must settle before p2.
+     *   - constraint #2 (mapAsync vs onSubmittedWorkDone): if p1 =
+     *     b.mapAsync() is called before p2 = q.onSubmittedWorkDone(), p1 must
+     *     settle before p2.
+     *
+     * @example Pattern A read-back idiom:
+     *   const cb = enc.finish().value;
+     *   queue.submit([cb]);
+     *   await queue.onSubmittedWorkDone();
+     *   await readBuf.mapAsync(GPUMapMode.READ);
+     *   const range = readBuf.getMappedRange().value;
+     */
+    onSubmittedWorkDone(): Promise<undefined>;
+}
+/** GPU command encoder - records render / compute passes + resource copies.
+ *
+ * Method NAMES align byte-for-byte with `@webgpu/types.GPUCommandEncoder` +
+ * `GPUDebugCommandsMixin` (research F-1 / D-S4). 12 methods total:
+ *   - 9 direct: beginRenderPass / beginComputePass / copyBufferToBuffer /
+ *               copyBufferToTexture / copyTextureToBuffer / copyTextureToTexture /
+ *               clearBuffer / resolveQuerySet / finish
+ *   - 3 mixin (GPUDebugCommandsMixin): pushDebugGroup / popDebugGroup /
+ *                                     insertDebugMarker
+ *
+ * Lifecycle: after `finish()`, all subsequent recording calls return
+ * Result.err({ code: 'command-encoder-finished' }) per D-S3 template 1
+ * (where the method returns Result; void-returning methods throw the
+ * structured error so AI users observe the failure consistently).
+ */
+export interface RhiCommandEncoder {
+    /** Begin render pass (auto-closes on end()).
+     *
+     * Spec anchor: [@webgpu/types.GPUCommandEncoder.beginRenderPass].
+     *
+     * @throws RhiError code === 'command-encoder-finished' when invoked on a finished encoder (dual-channel: spec-aligned void return throws on finished state; AI users wrap call sites with `try / catch (e: unknown) { if (e instanceof RhiError && e.code === 'command-encoder-finished') ... }`).
+     * @example
+     *   const pass = encoder.beginRenderPass({ colorAttachments: [{ ... }] });
+     */
+    beginRenderPass(desc: RenderPassDescriptor): RhiRenderPassEncoder;
+    /** Begin compute pass.
+     *
+     * Spec anchor: [@webgpu/types.GPUCommandEncoder.beginComputePass].
+     *
+     * @throws RhiError code === 'command-encoder-finished' when invoked on a finished encoder (dual-channel: see beginRenderPass for the recovery pattern).
+     * @example
+     *   const pass = encoder.beginComputePass();
+     */
+    beginComputePass(desc?: ComputePassDescriptor | undefined): RhiComputePassEncoder;
+    /** Copy a sub-region of a Buffer to another Buffer (5-arg full form).
+     *
+     * Spec anchor: [@webgpu/types.GPUCommandEncoder.copyBufferToBuffer].
+     *
+     * @throws RhiError code === 'command-encoder-finished' when invoked on a finished encoder (dual-channel; see beginRenderPass JSDoc for the recovery pattern). Both overloads share the same throw contract.
+     * @example
+     *   encoder.copyBufferToBuffer(src, 0, dst, 0, 256);
+     */
+    copyBufferToBuffer(source: Buffer, sourceOffset: number, destination: Buffer, destinationOffset: number, size: number): void;
+    /** Copy a Buffer to another Buffer (3-arg shorthand).
+     *
+     * Spec anchor: [@webgpu/types.GPUCommandEncoder.copyBufferToBuffer].
+     *
+     * @throws RhiError code === 'command-encoder-finished' when invoked on a finished encoder (dual-channel; see beginRenderPass JSDoc for the recovery pattern). Both overloads share the same throw contract.
+     * @example
+     *   encoder.copyBufferToBuffer(src, dst, 256);
+     */
+    copyBufferToBuffer(source: Buffer, destination: Buffer, size?: number | undefined): void;
+    /** Copy a Buffer sub-region to a Texture sub-region.
+     *
+     * Spec anchor: [@webgpu/types.GPUCommandEncoder.copyBufferToTexture].
+     *
+     * @throws RhiError code === 'command-encoder-finished' when invoked on a finished encoder (dual-channel; see beginRenderPass JSDoc for the recovery pattern).
+     * @example
+     *   encoder.copyBufferToTexture(srcInfo, dstInfo, [w, h, 1]);
+     */
+    copyBufferToTexture(source: GPUTexelCopyBufferInfo, destination: GPUTexelCopyTextureInfo, copySize: GPUExtent3DStrict): void;
+    /** Copy a Texture sub-region to a Buffer sub-region.
+     *
+     * Spec anchor: [@webgpu/types.GPUCommandEncoder.copyTextureToBuffer].
+     *
+     * @throws RhiError code === 'command-encoder-finished' when invoked on a finished encoder (dual-channel; see beginRenderPass JSDoc for the recovery pattern).
+     * @example
+     *   encoder.copyTextureToBuffer(srcInfo, dstInfo, [w, h, 1]);
+     */
+    copyTextureToBuffer(source: GPUTexelCopyTextureInfo, destination: GPUTexelCopyBufferInfo, copySize: GPUExtent3DStrict): void;
+    /** Copy a Texture sub-region to a Texture sub-region.
+     *
+     * Spec anchor: [@webgpu/types.GPUCommandEncoder.copyTextureToTexture].
+     *
+     * @throws RhiError code === 'command-encoder-finished' when invoked on a finished encoder (dual-channel; see beginRenderPass JSDoc for the recovery pattern).
+     * @example
+     *   encoder.copyTextureToTexture(srcInfo, dstInfo, [w, h, 1]);
+     */
+    copyTextureToTexture(source: GPUTexelCopyTextureInfo, destination: GPUTexelCopyTextureInfo, copySize: GPUExtent3DStrict): void;
+    /** Fill a Buffer sub-region with zeros.
+     *
+     * Spec anchor: [@webgpu/types.GPUCommandEncoder.clearBuffer].
+     *
+     * @throws RhiError code === 'command-encoder-finished' when invoked on a finished encoder (dual-channel; see beginRenderPass JSDoc for the recovery pattern).
+     * @example
+     *   encoder.clearBuffer(buf, 0, 256);
+     */
+    clearBuffer(buffer: Buffer, offset?: number | undefined, size?: number | undefined): void;
+    /** Resolve query results from a QuerySet to a Buffer.
+     *
+     * Real implementation (M3 / w26): writes 8-byte query results in 256-byte
+     * aligned strides into `destination` starting at `destinationOffset`.
+     * Validates `destination.usage & GPUBufferUsage.QUERY_RESOLVE` and the
+     * 256-byte alignment up front; on misuse returns
+     * `Result.err({ code: 'webgpu-runtime-error', ... })` with a structured
+     * .expected / .hint pair.
+     *
+     * Spec anchor: [@webgpu/types.GPUCommandEncoder.resolveQuerySet].
+     *
+     * @example
+     *   const out = encoder.resolveQuerySet(qs, 0, 4, dstBuf, 0);
+     *   if (!out.ok) {
+     *     // switch (out.error.code) { case 'webgpu-runtime-error': ... }
+     *   }
+     */
+    resolveQuerySet(querySet: QuerySet, firstQuery: number, queryCount: number, destination: Buffer, destinationOffset: number): Result<void, RhiError>;
+    /**
+     * Write a u64 GPU timestamp into a timestamp QuerySet at queryIndex.
+     *
+     * Spec anchor: W3C WebGPU §queries / [@webgpu/types.GPUCommandEncoder].
+     * dawn `TimestampOnCommandEncoder` reference (research §2.4): the entry is
+     * gated on the `'timestamp-query'` device feature. K-3 decision
+     * (plan-strategy §2): the forgeax form ships ONLY this CommandEncoder
+     * entry; CPE/RPE inside-pass timestamp writes are deferred to
+     * `feat-future-rhi-perf-timestamp-pass` (additive minor evolution).
+     *
+     * Return shape: `void` per spec literal alignment. When
+     * `caps.timestampQuery === false` the shim fans out a structured
+     * `'feature-not-enabled'` RhiError through the engine `onError` channel
+     * (the forgeax form keeps the spec void return; AI users probe the gate
+     * via `device.caps.timestampQuery` BEFORE calling this entry, charter
+     * proposition 4 explicit failure forward-reachable).
+     *
+     * @throws RhiError code === 'command-encoder-finished' when invoked on a finished encoder (dual-channel; see beginRenderPass JSDoc for the recovery pattern).
+     * @example
+     *   if (device.caps.timestampQuery) {
+     *     encoder.writeTimestamp(qs, 0);
+     *     // ... draw / dispatch ...
+     *     encoder.writeTimestamp(qs, 1);
+     *   }
+     */
+    writeTimestamp(querySet: QuerySet, queryIndex: number): void;
+    /** Push a labelled debug group (GPUDebugCommandsMixin).
+     *
+     * Spec anchor: [@webgpu/types.GPUDebugCommandsMixin.pushDebugGroup].
+     *
+     * @note silent delegate to raw GPU encoder on finished encoder; matches W3C spec lenience (the debug-commands mixin permits a no-op pass-through after finish() so the signal stays real instead of forging a `@throws` contract; charter proposition 4).
+     * @example
+     *   encoder.pushDebugGroup('frame-setup');
+     */
+    pushDebugGroup(groupLabel: string): void;
+    /** Pop the most recent debug group (GPUDebugCommandsMixin).
+     *
+     * Spec anchor: [@webgpu/types.GPUDebugCommandsMixin.popDebugGroup].
+     *
+     * @note silent delegate to raw GPU encoder on finished encoder; matches W3C spec lenience (see pushDebugGroup JSDoc for the dual-channel rationale).
+     * @example
+     *   encoder.popDebugGroup();
+     */
+    popDebugGroup(): void;
+    /** Insert a labelled debug marker (GPUDebugCommandsMixin).
+     *
+     * Spec anchor: [@webgpu/types.GPUDebugCommandsMixin.insertDebugMarker].
+     *
+     * @note silent delegate to raw GPU encoder on finished encoder; matches W3C spec lenience (see pushDebugGroup JSDoc for the dual-channel rationale).
+     * @example
+     *   encoder.insertDebugMarker('post-resolve');
+     */
+    insertDebugMarker(markerLabel: string): void;
+    /** Finish recording -> CommandBuffer. After finish() any further recording
+     *  call returns Result.err({ code: 'command-encoder-finished' }).
+     *
+     * Spec anchor: [@webgpu/types.GPUCommandEncoder.finish].
+     *
+     * @example
+     *   const cb = encoder.finish();
+     *   if (cb.ok) device.queue.submit([cb.value]);
+     */
+    finish(): Result<CommandBuffer, RhiError>;
+}
+/** GPU render pass encoder - records draw calls + state changes.
+ *
+ * Method NAMES align byte-for-byte with @webgpu/types.GPURenderPassEncoder +
+ * GPURenderCommandsMixin + GPUBindingCommandsMixin + GPUDebugCommandsMixin
+ * (research F-2 / D-S4): 17 spec stable + 1 setBindGroup overload + 1
+ * remaining capability-gated placeholder (`executeBundles` returns
+ * Result.err({ code: 'rhi-not-available', hint: 'see
+ * feat-future-rhi-render-bundle' })). The 2 occlusion-query methods
+ * (`beginOcclusionQuery` / `endOcclusionQuery`) shipped real implementations
+ * in M3 (w23) backed by `RenderPassDescriptor.occlusionQuerySet`.
+ *
+ * `setImmediates` (PROPOSED) is intentionally NOT exposed (charter
+ * proposition 4: untested features hide behind caps, not surfaces).
+ *
+ * Lifecycle: encoder.finish() while a pass is unfinished returns
+ * Result.err({ code: 'render-pass-not-ended' }) per D-S3 template 2.
+ */
+export interface RhiRenderPassEncoder {
+    /** Set the bound render pipeline.
+     *
+     * Spec anchor: [@webgpu/types.GPURenderCommandsMixin.setPipeline].
+     *
+     * @example pass.setPipeline(pipeline);
+     */
+    setPipeline(pipeline: RenderPipeline): void;
+    /** Set a vertex buffer.
+     *
+     * Spec anchor: [@webgpu/types.GPURenderCommandsMixin.setVertexBuffer].
+     *
+     * @example pass.setVertexBuffer(0, vbo);
+     */
+    setVertexBuffer(slot: number, buffer: Buffer, offset?: number | undefined, size?: number | undefined): void;
+    /** Set the index buffer.
+     *
+     * Spec anchor: [@webgpu/types.GPURenderCommandsMixin.setIndexBuffer].
+     *
+     * @example pass.setIndexBuffer(ibo, 'uint32');
+     */
+    setIndexBuffer(buffer: Buffer, format: 'uint16' | 'uint32', offset?: number | undefined, size?: number | undefined): void;
+    /** Set a bind group with optional dynamic offsets array (overload (a)).
+     *
+     * Spec anchor: [@webgpu/types.GPUBindingCommandsMixin.setBindGroup].
+     *
+     * @example pass.setBindGroup(0, bg, [0, 256]);
+     */
+    setBindGroup(index: number, bindGroup: BindGroup, dynamicOffsets?: readonly number[] | undefined): void;
+    /** Set a bind group with a Uint32Array slice for dynamic offsets (overload (b)).
+     *
+     * Spec anchor: [@webgpu/types.GPUBindingCommandsMixin.setBindGroup].
+     *
+     * @example
+     *   pass.setBindGroup(0, bg, dynamicOffsetsData, dynamicOffsetsDataStart, dynamicOffsetsDataLength);
+     */
+    setBindGroup(index: number, bindGroup: BindGroup, dynamicOffsetsData: Uint32Array, dynamicOffsetsDataStart: number, dynamicOffsetsDataLength: number): void;
+    /** Issue a draw.
+     *
+     * Spec anchor: [@webgpu/types.GPURenderCommandsMixin.draw].
+     *
+     * @example pass.draw(3);
+     */
+    draw(vertexCount: number, instanceCount?: number | undefined, firstVertex?: number | undefined, firstInstance?: number | undefined): void;
+    /** Issue an indexed draw.
+     *
+     * Spec anchor: [@webgpu/types.GPURenderCommandsMixin.drawIndexed].
+     *
+     * @example pass.drawIndexed(36);
+     */
+    drawIndexed(indexCount: number, instanceCount?: number | undefined, firstIndex?: number | undefined, baseVertex?: number | undefined, firstInstance?: number | undefined): void;
+    /** End the render pass.
+     *
+     * Spec anchor: [@webgpu/types.GPURenderPassEncoder.end].
+     *
+     * @example pass.end();
+     */
+    end(): void;
+    /** Set the viewport.
+     *
+     * Spec anchor: [@webgpu/types.GPURenderPassEncoder.setViewport].
+     *
+     * @example pass.setViewport(0, 0, 800, 600, 0, 1);
+     */
+    setViewport(x: number, y: number, w: number, h: number, minDepth: number, maxDepth: number): void;
+    /** Set the scissor rect.
+     *
+     * Spec anchor: [@webgpu/types.GPURenderPassEncoder.setScissorRect].
+     *
+     * @example pass.setScissorRect(0, 0, 800, 600);
+     */
+    setScissorRect(x: number, y: number, w: number, h: number): void;
+    /** Set the blend constant color.
+     *
+     * Spec anchor: [@webgpu/types.GPURenderPassEncoder.setBlendConstant].
+     *
+     * @example pass.setBlendConstant({ r: 1, g: 0, b: 0, a: 1 });
+     */
+    setBlendConstant(color: GPUColor): void;
+    /** Set the stencil reference value.
+     *
+     * Spec anchor: [@webgpu/types.GPURenderPassEncoder.setStencilReference].
+     *
+     * @example pass.setStencilReference(0xff);
+     */
+    setStencilReference(reference: number): void;
+    /** Issue an indirect draw.
+     *
+     * Spec anchor: [@webgpu/types.GPURenderCommandsMixin.drawIndirect].
+     *
+     * @example pass.drawIndirect(indirectBuf, 0);
+     */
+    drawIndirect(indirectBuffer: Buffer, indirectOffset: number): void;
+    /** Issue an indexed indirect draw.
+     *
+     * Spec anchor: [@webgpu/types.GPURenderCommandsMixin.drawIndexedIndirect].
+     *
+     * @example pass.drawIndexedIndirect(indirectBuf, 0);
+     */
+    drawIndexedIndirect(indirectBuffer: Buffer, indirectOffset: number): void;
+    /** Push a labelled debug group (GPUDebugCommandsMixin).
+     *
+     * Spec anchor: [@webgpu/types.GPUDebugCommandsMixin.pushDebugGroup].
+     *
+     * @note silent delegate to raw GPU encoder on finished encoder; matches W3C spec lenience (the debug-commands mixin permits a no-op pass-through after finish() so the signal stays real instead of forging a `@throws` contract; charter proposition 4).
+     * @example pass.pushDebugGroup('lighting');
+     */
+    pushDebugGroup(groupLabel: string): void;
+    /** Pop the most recent debug group (GPUDebugCommandsMixin).
+     *
+     * Spec anchor: [@webgpu/types.GPUDebugCommandsMixin.popDebugGroup].
+     *
+     * @note silent delegate to raw GPU encoder on finished encoder; matches W3C spec lenience (see pushDebugGroup JSDoc for the dual-channel rationale).
+     * @example pass.popDebugGroup();
+     */
+    popDebugGroup(): void;
+    /** Insert a labelled debug marker (GPUDebugCommandsMixin).
+     *
+     * Spec anchor: [@webgpu/types.GPUDebugCommandsMixin.insertDebugMarker].
+     *
+     * @note silent delegate to raw GPU encoder on finished encoder; matches W3C spec lenience (see pushDebugGroup JSDoc for the dual-channel rationale).
+     * @example pass.insertDebugMarker('post-shadow');
+     */
+    insertDebugMarker(markerLabel: string): void;
+    /** Execute render bundles. Capability-gated placeholder per D-S4: returns
+     *  Result.err({ code: 'rhi-not-available', hint: 'see feat-future-rhi-render-bundle' })
+     *  until that closure lands RenderBundle creation.
+     *
+     * Spec anchor: [@webgpu/types.GPURenderPassEncoder.executeBundles].
+     *
+     * @example
+     *   const out = pass.executeBundles([bundle]);
+     *   if (!out.ok) { ... route via switch (out.error.code) ... }
+     */
+    executeBundles(bundles: Iterable<unknown>): Result<void, RhiError>;
+    /** Begin an occlusion query. Real implementation (M3 / w23): pairs with
+     *  `endOcclusionQuery()` against the `RenderPassDescriptor.occlusionQuerySet`
+     *  and validates the spec [[occlusion_query_active]] state machine
+     *  (queries cannot nest; missing occlusionQuerySet returns
+     *  Result.err({ code: 'webgpu-runtime-error' }) with structured
+     *  .expected / .hint fields).
+     *
+     * Spec anchor: [@webgpu/types.GPURenderPassEncoder.beginOcclusionQuery].
+     *
+     * @example
+     *   const out = pass.beginOcclusionQuery(0);
+     *   if (!out.ok) { ... route via switch (out.error.code) ... }
+     */
+    beginOcclusionQuery(queryIndex: number): Result<void, RhiError>;
+    /** End an occlusion query. Real implementation (M3 / w23): finalizes the
+     *  matching `beginOcclusionQuery(idx)` slot; emits
+     *  Result.err({ code: 'render-pass-not-ended', ... }) if no active begin
+     *  is pending.
+     *
+     * Spec anchor: [@webgpu/types.GPURenderPassEncoder.endOcclusionQuery].
+     *
+     * @example
+     *   const out = pass.endOcclusionQuery();
+     *   if (!out.ok) { ... route via switch (out.error.code) ... }
+     */
+    endOcclusionQuery(): Result<void, RhiError>;
+}
+/** GPU compute pass encoder - records dispatch calls. */
+export interface RhiComputePassEncoder {
+    setPipeline(pipeline: ComputePipeline): void;
+    setBindGroup(index: number, bindGroup: BindGroup, dynamicOffsets?: readonly number[] | undefined): void;
+    dispatchWorkgroups(x: number, y?: number | undefined, z?: number | undefined): void;
+    /** Dispatch dimensions read from three consecutive u32 values in an indirect buffer. */
+    dispatchWorkgroupsIndirect(indirectBuffer: Buffer, indirectOffset: number): void;
+    end(): void;
+}
+/** GPU render pipeline operations - returned by RhiDevice.createRenderPipeline. */
+export interface RhiRenderPipelineOps {
+    /** Get bind group layout (used for dynamic bind-group creation). */
+    getBindGroupLayout(index: number): BindGroupLayout;
+}
+/** GPU compute pipeline operations. */
+export interface RhiComputePipelineOps {
+    /** Get bind group layout. */
+    getBindGroupLayout(index: number): BindGroupLayout;
+}
+export type { DrawOwnerSplit, LimitExceededDetail, Result, ResultErr, ResultOk, RhiAssetNotRegisteredDetail, RhiErrorCode, RhiErrorDetail, RhiOwnerOutOfRangeDetail, RhiShaderCompileDetail, RhiWebgpuRuntimeDetail, } from './errors';
+export { err, ok, RhiError, validateDrawArgs } from './errors';
+export type { AddressMode, CompareFunction, FilterMode, TextureFormat };
+/**
+ * Build a TextureDescriptor for a cube-array depth texture suitable for
+ * point-light shadow atlas (texture_depth_cube_array).
+ *
+ * Usage: `device.createTexture(cubeArrayDepthDescriptor(512, 4))`
+ *
+ * @param faceSize - width and height of each cube face in pixels (default 512)
+ * @param layers - number of cube layers (= max shadow-casting point lights, default 4)
+ * @param usage - texture usage flags (default RENDER_ATTACHMENT | TEXTURE_BINDING)
+ */
+export declare function cubeArrayDepthDescriptor(faceSize?: number, layers?: number, usage?: number): TextureDescriptor;
+/**
+ * Build a SamplerDescriptor for a depth-comparison sampler used with
+ * texture_depth_2d or texture_depth_cube_array.
+ *
+ * The returned descriptor uses clamp-to-edge addressing, linear filtering
+ * (required for comparison sampling on some backends), and `compare: 'less'`.
+ *
+ * Usage: `device.createSampler(comparisonSamplerDescriptor())`
+ */
+export declare function comparisonSamplerDescriptor(): SamplerDescriptor;
+/**
+ * Build a TextureViewDescriptor to view a single cube layer + face as a 2D
+ * depth attachment during shadow-caster rendering.
+ *
+ * Each shadow-caster pass renders to one face of one cube layer. This helper
+ * produces the view descriptor that selects `baseArrayLayer = layerIndex * 6 + faceIndex`
+ * with `arrayLayerCount = 1` and `dimension = '2d'`, which satisfies WebGPU's
+ * requirement that render pass attachments are 2D views (cube views cannot be
+ * bound as render targets).
+ *
+ * Usage:
+ * ```
+ * const viewDesc = cubeArrayDepthFaceView(lightIndex, faceIndex);
+ * const view = device.createTextureView(atlas, viewDesc).unwrap();
+ * ```
+ *
+ * @param layerIndex - 0-based shadow-casting light index (0..3)
+ * @param faceIndex - 0-based cube face index (0..5, +X/-X/+Y/-Y/+Z/-Z per §5.3)
+ */
+export declare function cubeArrayDepthFaceView(layerIndex: number, faceIndex: number): TextureViewDescriptor;
+//# sourceMappingURL=index.d.ts.map