@forgeax/engine-render 0.1.2

package/dist/pipeline-errors.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Closed union of render-pipeline error codes.
+ *
+ * AI users perform exhaustive `switch (err.code)` without a default and TS guards
+ * completeness (AC-05).
+ *
+ * | code | channel | trigger |
+ * |:--|:--|:--|
+ * | `'pipeline-already-registered'` | throw | a second `registerPipeline(id, impl)` under an already-registered `id` |
+ * | `'pipeline-not-found'` | `Result.err` | `installPipeline(handle)` where the handle resolves to no registered pipeline |
+ */
+export type PipelineErrorCode = keyof typeof PIPELINE_POLICY;
+/**
+ * Detail for `'pipeline-already-registered'`: the pipeline id that was already taken.
+ * AI consumers read `.detail.id` by property access (charter P4), no message parsing.
+ */
+export interface PipelinePreviouslyRegisteredDetail {
+    readonly id: string;
+}
+/**
+ * Detail for `'pipeline-not-found'`: the raw u32 handle value that resolved to no
+ * registered pipeline. Read via `.detail.handle` after the code guard.
+ */
+export interface PipelineNotFoundDetail {
+    readonly handle: number;
+}
+export interface VertexColorVariantConflictDetail {
+    readonly authored: boolean;
+    readonly authoredValue: string;
+    readonly projected: boolean;
+    readonly variantSet: string;
+}
+/**
+ * Conditional resolver from `PipelineErrorCode` to its detail payload type. Used by the
+ * constructor signature so `new PipelineError({ code: 'X', detail })` narrows the
+ * `detail` parameter to the variant payload at compile time.
+ */
+export type PipelineErrorDetailFor<C extends PipelineErrorCode> = C extends 'pipeline-already-registered' ? PipelinePreviouslyRegisteredDetail : C extends 'pipeline-not-found' ? PipelineNotFoundDetail : C extends 'vertex-color-variant-conflict' ? VertexColorVariantConflictDetail : never;
+/**
+ * Tagged union of `.detail` payloads. The variants are unique by structural fields
+ * (`{ id }` vs `{ handle }`).
+ */
+export type PipelineErrorDetail = PipelineErrorDetailFor<PipelineErrorCode>;
+declare const PIPELINE_POLICY: {
+    'pipeline-already-registered': {
+        expected: string;
+        hint: (detail: unknown) => string;
+    };
+    'pipeline-not-found': {
+        expected: string;
+        hint: (detail: unknown) => string;
+    };
+    'vertex-color-variant-conflict': {
+        expected: string;
+        hint: (detail: unknown) => string;
+    };
+};
+declare class PipelineErrorClass extends Error {
+    readonly code: PipelineErrorCode;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: PipelineErrorDetail;
+    constructor(args: {
+        code: PipelineErrorCode;
+        detail: PipelineErrorDetail;
+    });
+}
+/**
+ * Variant intersection: a `PipelineErrorClass` instance whose `code` literal narrows to
+ * `C` and whose `detail` narrows to `PipelineErrorDetailFor<C>`, so `if (err.code === 'X')`
+ * simultaneously narrows `err.detail` (charter P3 + P4 discriminated union).
+ */
+type PipelineErrorVariant<C extends PipelineErrorCode> = PipelineErrorClass & {
+    readonly code: C;
+    readonly detail: PipelineErrorDetailFor<C>;
+};
+/**
+ * Public PipelineError type - discriminated union of the 2 variants.
+ *
+ * ```ts
+ * function recover(err: PipelineError): string {
+ *   switch (err.code) {
+ *     case 'pipeline-already-registered': return `id taken: ${err.detail.id}`;
+ *     case 'pipeline-not-found':          return `bad handle: ${err.detail.handle}`;
+ *   }
+ * }
+ * ```
+ */
+export type PipelineError = {
+    [C in PipelineErrorCode]: PipelineErrorVariant<C>;
+}[PipelineErrorCode];
+interface PipelineErrorConstructor {
+    new <C extends PipelineErrorCode>(args: {
+        code: C;
+        detail: PipelineErrorDetailFor<C>;
+    }): PipelineErrorVariant<C>;
+    readonly prototype: PipelineErrorClass;
+}
+/**
+ * PipelineError constructor - `new PipelineError({ code, detail })`.
+ *
+ * The generic `C` is inferred from the literal `code` argument, which narrows `detail` to
+ * the per-code payload (`PipelineErrorDetailFor<C>`) and narrows the return type to the
+ * corresponding `PipelineErrorVariant<C>` so the call site walks the discriminated union
+ * without manual cast (AppError pattern; TS class declarations cannot directly express
+ * `<C> ... PipelineErrorVariant<C>` polymorphism, hence the typed-cast affordance).
+ */
+export declare const PipelineError: PipelineErrorConstructor;
+export {};
+//# sourceMappingURL=pipeline-errors.d.ts.map

package/dist/pipeline-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-errors.d.ts","sourceRoot":"","sources":["../src/pipeline-errors.ts"],"names":[],"mappings":"AAuBA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,eAAe,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,CAAC,CAAC,SAAS,iBAAiB,IAC5D,CAAC,SAAS,6BAA6B,GACnC,kCAAkC,GAClC,CAAC,SAAS,oBAAoB,GAC5B,sBAAsB,GACtB,CAAC,SAAS,+BAA+B,GACvC,gCAAgC,GAChC,KAAK,CAAC;AAEhB;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,sBAAsB,CAAC,iBAAiB,CAAC,CAAC;AAE5E,QAAA,MAAM,eAAe;;;;;;;;;;;;;CA4BpB,CAAC;AAEF,cAAM,kBAAmB,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;gBAEzB,IAAI,EAAE;QAAE,IAAI,EAAE,iBAAiB,CAAC;QAAC,MAAM,EAAE,mBAAmB,CAAA;KAAE;CAU3E;AAED;;;;GAIG;AACH,KAAK,oBAAoB,CAAC,CAAC,SAAS,iBAAiB,IAAI,kBAAkB,GAAG;IAC5E,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC;CAC5C,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG;KACzB,CAAC,IAAI,iBAAiB,GAAG,oBAAoB,CAAC,CAAC,CAAC;CAClD,CAAC,iBAAiB,CAAC,CAAC;AAErB,UAAU,wBAAwB;IAChC,KAAK,CAAC,SAAS,iBAAiB,EAAE,IAAI,EAAE;QACtC,IAAI,EAAE,CAAC,CAAC;QACR,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC;KACnC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;CACxC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,EAAE,wBAC+B,CAAC"}

package/dist/pipeline-spec.d.ts

@@ -0,0 +1,506 @@
+import { type VertexLayoutProjection } from '@forgeax/engine-geometry';
+import { type RegisteredMaterialShaderEntry, type ShaderRegistry } from '@forgeax/engine-shader';
+import { type BindGroupLayoutEntry, KNOWN_PASS_KINDS, type MaterialRenderState, type ParamSchemaEntry, type PrimitiveTopology, type VertexAttributeMap } from '@forgeax/engine-types';
+import { type PbrCaps } from './pbr-pipeline';
+export { KNOWN_PASS_KINDS };
+/**
+ * The engine-owned deferred material target layout. `fs_gbuffer` returns
+ * normal+roughness, albedo+metallic, and emissive+AO in this order.
+ */
+export declare const DEFERRED_COLOR_FORMATS: readonly GPUTextureFormat[];
+/** Derive the color attachment shape for a material pass kind. */
+export declare function colorFormatsForPassKind(passKind: string, defaultColorFormat: GPUTextureFormat): readonly GPUTextureFormat[];
+/**
+ * Pipeline specification — immutable 4-axis data that completely determines
+ * what `device.createRenderPipeline(...)` does for a material shader pass.
+ *
+ * The 4 axes are:
+ * - `shader`: which WGSL source + material param schema + pass kind + variant set
+ * - `attachments`: color/depth/stencil formats + sample count (MSAA)
+ * - `geometry`: primitive topology + vertex attribute layout + index format
+ * - `renderState`: optional per-material render-state overrides (blend/cull/depth/stencil)
+ *
+ * Business-agnostic: no `'pbr'` / `'sprite'` / `'skybox'` strings pollute this
+ * type. BGL shape taxonomy is derived from `ShaderRegistry` internal reflection
+ * and never appears on the spec surface (plan-strategy D-7).
+ *
+ * @see plan-strategy §1 (4-axis) · D-7 (business-agnostic) · requirements §3.1
+ */
+export interface PipelineSpec {
+    /** Shader identity + routing axis. */
+    readonly shader: {
+        /** Registered shader identifier (e.g. `'forgeax::default-standard-pbr'`). */
+        readonly id: string;
+        /** Pass kind for attachment shape selection. Must be in {@link KNOWN_PASS_KINDS} or registered. */
+        readonly passKind: string;
+        /** Shader variant set string (e.g. `'SKIN_AVAILABLE=1'`). `undefined` for no variant. */
+        readonly variantSet: string | undefined;
+        /** Fragment entry point; omitted means the shader's standard `fs_main`. */
+        readonly fragmentEntry?: string | undefined;
+    };
+    /** Attachment format + sample-count axis. */
+    readonly attachments: {
+        /** Colour attachment formats in draw order. Empty for depth-only passes (shadow-caster). */
+        readonly colorFormats: readonly GPUTextureFormat[];
+        /** Depth-stencil format, or `undefined` when no depth target is bound. */
+        readonly depthFormat: GPUTextureFormat | undefined;
+        /** Sample count: 1 (no MSAA) or 4 (4x MSAA). */
+        readonly sampleCount: 1 | 4;
+    };
+    /** Geometry layout axis. */
+    readonly geometry: {
+        /** Primitive topology baked into the PSO. */
+        readonly topology: PrimitiveTopology;
+        /** Strip index format (uint16 / uint32), only meaningful for strip topologies. */
+        readonly stripIndexFormat?: 'uint16' | 'uint32' | undefined;
+        /** Per-vertex attribute layout (position / normal / uv / tangent / skinIndex / skinWeight). */
+        readonly vertexLayout: VertexAttributeMap;
+        /** Canonical geometry-owned projection; derived when omitted for legacy callers. */
+        readonly vertexLayoutProjection?: VertexLayoutProjection | undefined;
+        /**
+         * Number of UV sets declared by the shader (derived from @location reflection).
+         * Forwarded to deriveVertexBufferLayout for clamp-to-last alias (D-1 / D-4).
+         * Undefined = fallback to mesh-provided UV count (no clamping).
+         * feat-20260629-multi-uv-set-support m3-w5: plumbed placeholder.
+         * TODO(M4/m4-w3): fill from naga reflection JSON when available.
+         */
+        readonly shaderUvSetCount?: number | undefined;
+    };
+    /** Per-material render-state overrides (optional — engine defaults applied when absent). */
+    readonly renderState: MaterialRenderState | undefined;
+}
+/**
+ * Closed union of PipelineSpec error codes.
+ *
+ * 5 business codes:
+ * - `'spec-inconsistent'`: axis mutual exclusion violated
+ * - `'unknown-pass-kind'`: passKind not in KNOWN_PASS_KINDS or registered
+ * - `'shader-bgl-reflection-mismatch'`: reflected BGL shape != shader declaration
+ * - `'attachment-format-incompatible'`: depth/stencil format vs PSO mismatch
+ * - `'unsupported-vertex-layout'`: vertex attributes don't match shader vs_main
+ *
+ * 2 transit codes:
+ * - `'pipeline-build-failed'`: wraps RhiError from device.createRenderPipeline
+ * - `'shader-not-registered'`: ShaderRegistry.lookup returned undefined
+ *
+ * @see requirements §3.4 · AC-10 · charter P3
+ */
+export type PipelineSpecErrorCode = 'spec-inconsistent' | 'unknown-pass-kind' | 'shader-bgl-reflection-mismatch' | 'attachment-format-incompatible' | 'unsupported-vertex-layout' | 'pipeline-build-failed' | 'shader-not-registered';
+/**
+ * Structured pipeline-spec error — carries `.code` (discriminated union) +
+ * `.detail` (narrowed per code) + `.hint` (AI-user actionable prose).
+ *
+ * Inherits from `Error` so it integrates with existing catch blocks; the
+ * `.code` field enables exhaustive `switch` narrowing without string parsing
+ * (charter P3).
+ */
+export declare class PipelineSpecError extends Error {
+    readonly code: PipelineSpecErrorCode;
+    /**
+     * Narrowed detail payload — shape depends on `code`.
+     *
+     * - `'spec-inconsistent'`: `{ reason: string }`
+     * - `'unknown-pass-kind'`: `{ expected: readonly string[]; actual: string; hint?: string }`
+     * - `'shader-bgl-reflection-mismatch'`: `{ reflected: unknown; declared: unknown }`
+     * - `'attachment-format-incompatible'`: `{ reason: string; expected?: string; actual?: string }`
+     * - `'unsupported-vertex-layout'`: `{ specAttrs: string[]; shaderAttrs: string[] }`
+     * - `'pipeline-build-failed'`: `{ gpuMessage?: string; cause?: unknown }`
+     * - `'shader-not-registered'`: `{ shaderId: string; hint?: string }`
+     */
+    readonly detail: Record<string, unknown>;
+    constructor(args: {
+        code: PipelineSpecErrorCode;
+        detail: Record<string, unknown>;
+        hint?: string;
+    });
+}
+/**
+ * Bind group layout shape derived from ShaderRegistry reflection.
+ *
+ * `entries` mirrors `GPUBindGroupLayoutDescriptor.entries` — the binding
+ * slot layout the shader expects for a given variantSet.
+ */
+export interface BindGroupLayoutShape {
+    readonly entries: readonly BindGroupLayoutEntry[];
+}
+/**
+ * Derive BGL shape from a registered shader entry's paramSchema.
+ *
+ * Pure function: same `entry` always yields the same shape (no variant-set
+ * dispatch — that role moved into `BglKind` after D-13's closed-union
+ * dispatch landed; see plan-decisions.md). The `_variantSet` parameter is
+ * preserved for backward signature compat but ignored — variant routing is
+ * now explicit at the BglKind level (see `buildBindGroupLayoutDescriptor`
+ * arms `pbr-skin-mesh-array` vs `hdrp-7-slot` vs `pbr-mesh-array`).
+ *
+ * This helper lives in `pipeline-spec.ts` (not ShaderRegistry) per D-1:
+ * it wraps the existing `derive(paramSchema).bglEntries` from
+ * `@forgeax/engine-types` so cacheKeyOf can hash BGL shape deterministically
+ * without expanding the ShaderRegistry public interface.
+ *
+ * @param entry - material shader entry from ShaderRegistry.findMaterialArtifact
+ * @param _variantSet - unused (post D-13); kept for backward signature compat
+ * @returns the BGL shape for the given entry
+ * @see plan-decisions.md D-13
+ */
+export declare function deriveBglShapeFromShader(entry: RegisteredMaterialShaderEntry, _variantSet?: string | undefined): BindGroupLayoutShape;
+/**
+ * Deterministic hash suffix for MaterialRenderState (sorted keys, JSON.stringify).
+ *
+ * Returns `''` when `renderState` is `undefined` or has zero entries,
+ * preserving cache-key byte-compatibility with the pre-M1 shape.
+ */
+export declare function renderStateHash(renderState: MaterialRenderState | undefined): string;
+/**
+ * Compute a deterministic cache key from a PipelineSpec.
+ *
+ * The key covers all 4 axes + BGL shape hash (derived from ShaderRegistry
+ * reflection via {@link deriveBglShapeFromShader}). Two specs that produce
+ * the same cache key MUST produce byte-identical PSO descriptors.
+ *
+ * Algorithm: concatenate each axis segment with `:` separators, hash the
+ * BGL shape for compactness, and emit a single cache-key string.
+ *
+ * @see plan-strategy §3.1 · requirements AC-02
+ */
+export declare function cacheKeyOf(spec: PipelineSpec): string;
+/**
+ * Build a `GPURenderPipelineDescriptor` from a PipelineSpec + shader modules.
+ *
+ * Pure derivation: same (spec, modules) always produces the same descriptor.
+ * Consumed by `getOrBuildPipeline` on cache miss; also available as a public
+ * helper for AI users who want the descriptor shape without going through the
+ * cache entrypoint.
+ *
+ * @param spec - the pipeline spec (4 axes)
+ * @param modules - `{ vertex: GPUShaderModule; fragment: GPUShaderModule }`
+ * @returns a complete WebGPU render-pipeline descriptor
+ * @see plan-strategy §3.2 · requirements AC-02
+ */
+export declare function buildPipelineDescriptor(spec: PipelineSpec, modules: {
+    vertex: unknown;
+    fragment: unknown;
+    vertexEntryPoint?: string;
+    fragmentEntryPoint?: string;
+    layout?: unknown;
+}): Record<string, unknown>;
+/**
+ * Closed union of bind-group-layout shapes the runtime constructs.
+ *
+ * Each kind names one physically distinct BGL the runtime has historically
+ * built by hand. {@link buildBindGroupLayoutDescriptor} dispatches on this
+ * union so every `device.createBindGroupLayout(...)` call site shares one
+ * SSOT for entries / labels (plan-strategy §3.2; D-13 round-2 decision).
+ *
+ * Three groups by derivation source:
+ * 1. Shader-derived (paramSchema reflection + injection chain):
+ *    - `'pbr-material-merged'` — derived user region + Skylight 7 + lightmap 4
+ *    - `'unlit-material'` — 7 entries: base PBR material only (no inject)
+ *    - `'hdrp-7-slot'` — 7 entries (binding 0 + 3..8): HDRP cluster + SSAO group(2) BGL
+ * 2. Caps-driven literal shapes (no shader):
+ *    - `'pbr-view'` — 10 entries: view UBO + lights + 6 shadow bindings
+ *      (directional 3/4, point 5/6, cascade 7, spot atlas 8, spot
+ *      lightViewProj matrices 9 — feat-20260625)
+ *    - `'pbr-mesh-array'` — 1 entry: per-entity mesh SSBO (dynamic-offset)
+ *    - `'pbr-instances'` — 1 entry: per-instance SSBO (no dynamic-offset)
+ *    - `'pbr-skin-mesh-array'` — 3 entries: meshes + current/previous skin palettes
+ * 3. Attachment-driven (fullscreen post-process):
+ *    - `'fullscreen-post'` — 2 entries: input texture + sampler. The texture
+ *      `sampleType` is derived from `spec.attachments` (plan §R3 fix):
+ *      `'depth32float'` → `'depth'`; `'r32float'` → `'unfilterable-float'`;
+ *      else → `'float'`.
+ *    - `'fullscreen-post-with-params'` — 3 entries: the same texture@0 +
+ *      sampler@1 as `'fullscreen-post'`, plus a `buffer@2` uniform for the
+ *      per-frame params UBO (feat-20260621 D-2: `entry.params !== undefined`
+ *      passes route here; the layout stays group(1), q3=B). `'fullscreen-post'`
+ *      stays byte-identical so param-less consumers degrade with no change.
+ *    - `'fullscreen-post-with-scene-depth-msaa'` — the depth-read layout with
+ *      `texture.multisampled=true`, selected for a 4-sample scene depth target.
+ */
+export type BglKind = 'pbr-view' | 'pbr-material-merged' | 'pbr-mesh-array' | 'pbr-instances' | 'pbr-skin-mesh-array' | 'unlit-material' | 'hdrp-7-slot' | 'fullscreen-post' | 'fullscreen-post-with-params' | 'fullscreen-post-with-scene-depth' | 'fullscreen-post-with-scene-depth-msaa' | 'fullscreen-post-with-gbuffer-depth';
+/**
+ * Output shape of {@link buildBindGroupLayoutDescriptor}: matches the RHI
+ * `BindGroupLayoutDescriptor` (label + entries with `ExplicitUndefined`) so
+ * the result can be passed directly to `device.createBindGroupLayout(...)`.
+ *
+ * `entries` is a mutable `Array` to match `GPUBindGroupLayoutDescriptor`
+ * (WebGPU types declare it mutable). Callers MUST treat the array as
+ * read-only — the dispatcher freezes neither the array nor its entries
+ * for hot-path performance.
+ */
+export interface BindGroupLayoutDescriptorOutput {
+    readonly label: string | undefined;
+    readonly entries: GPUBindGroupLayoutEntry[];
+}
+export declare function buildBindGroupLayoutDescriptor(spec: PipelineSpec, options: {
+    kind: BglKind;
+    registry?: ShaderRegistry;
+    caps?: PbrCaps;
+    /**
+     * Material paramSchema for the per-shader user-region derivation
+     * (`'pbr-material-merged'` / `'unlit-material'`). When supplied it is the
+     * authoritative source for the user-region BGL shape (D-1); when omitted,
+     * `buildPbrMaterialUserRegionEntries` falls back to the built-in
+     * standard-PBR 4-texture schema (user region is 9 entries), so
+     * the caps-driven `buildPbrPipelineLayouts` seam keeps working unchanged.
+     * A registry + resolvable shader id takes precedence over this field.
+     */
+    materialParamSchema?: readonly ParamSchemaEntry[];
+}): BindGroupLayoutDescriptorOutput;
+/**
+ * Default colour-attachment ops carried by a passKind policy.
+ *
+ * `clearValue` is `undefined` for `loadOp='load'` policies (no clear value
+ * is emitted into the descriptor when the prior contents are loaded).
+ */
+export interface AttachmentColorOps {
+    readonly loadOp: 'clear' | 'load';
+    readonly storeOp: 'store' | 'discard';
+    readonly clearValue: GPUColor | undefined;
+}
+/**
+ * Default depth-attachment ops carried by a passKind policy.
+ *
+ * `stencilLoadOp` / `stencilStoreOp` are absent on the policy itself — the
+ * stencil-op gate is auto-derived from `specAttachments.depthFormat` at call
+ * time (`'depth24plus-stencil8'` → `'clear'+'discard'`; everything else
+ * elides stencil ops). This collapses the R3/R5 stencil-op duplicates that
+ * previously lived inline at every forward-pass beginRenderPass call site.
+ */
+export interface AttachmentDepthOps {
+    readonly loadOp: 'clear' | 'load';
+    readonly storeOp: 'store' | 'discard';
+    readonly clearValue: number;
+}
+/**
+ * Attachment policy for a single passKind — declares the colour / depth shape
+ * the pass produces and the default load/store ops. Per-call-site overrides
+ * (skybox vs main forward differing on `colorLoadOp`, sprite-split forward
+ * differing on both `colorLoadOp` and `depthLoadOp`) flow through the
+ * `options` parameter of {@link buildBeginRenderPassDescriptor}.
+ *
+ * `shape` discriminator drives which attachment slots the descriptor emits:
+ * - `'depth-only'` → empty `colorAttachments[]`, `depthStencilAttachment` set
+ * - `'color-only'` → populated `colorAttachments[]`, no `depthStencilAttachment`
+ * - `'color-and-depth'` → both
+ */
+export interface PassKindAttachmentPolicy {
+    readonly shape: 'depth-only' | 'color-only' | 'color-and-depth';
+    readonly defaultColorOps: AttachmentColorOps | undefined;
+    readonly defaultDepthOps: AttachmentDepthOps | undefined;
+}
+/**
+ * Closed map of passKind → attachment policy. Covers the 10 attachment shapes
+ * the runtime ships (per plan-strategy M4):
+ *
+ * 1. `'forward'` — main geometry pass: color+depth(+stencil-gated)
+ * 2. `'deferred'` — HDRP G-Buffer geometry pass: MRT color+depth
+ * 3. `'shadow-caster'` — directional shadow caster: depth-only
+ * 4. `'point-shadow-caster'` — HDRP point-shadow caster: depth-only
+ * 5. `'skybox'` — fullscreen skybox: color-only clear/store
+ * 6. `'tonemap'` — HDR→LDR tonemap fullscreen: color-only clear/store
+ * 7. `'bloom-bright'` / `'bloom-blur'` — bloom downsample/blur: color-only
+ *    clear/store
+ * 8. `'bloom-composite'` — bloom add-back: color-only load/store (NOT clear)
+ * 9. `'fxaa'` — fullscreen FXAA: color-only clear/store
+ * 10. `'post-process'` — generic fullscreen primitive (SSAO, render-graph
+ *    fullscreen-post-process-pass dispatcher, M2 tonemap pre-warm slot):
+ *    color-only clear/store
+ *
+ * Sprite-split forward sub-pass reuses the `'forward'` policy with
+ * `options.colorLoadOp='load'` + `options.depthLoadOp='load'`.
+ *
+ * Stencil-op gate is NOT in this table — it is derived from
+ * `specAttachments.depthFormat` inside the helper (depth24plus-stencil8
+ * → emit `stencilLoadOp:'clear' / stencilStoreOp:'discard'`).
+ */
+export declare const passKindPolicyTable: Readonly<Record<string, PassKindAttachmentPolicy>>;
+/**
+ * Build a `GPURenderPassDescriptor` from spec attachments + resolved views +
+ * a passKind policy lookup.
+ *
+ * The helper is the single SSOT for `device.beginRenderPass(...)` descriptor
+ * shape — every record-stage call site routes through it (plan-strategy M4
+ * AC-06). It dispatches on `passKindPolicyTable[passKind]` to pick the
+ * attachment shape (depth-only / color-only / color-and-depth) and applies
+ * default color/depth load+store ops; per-call overrides (sprite-split's
+ * `loadOp:'load'`, main pass's dynamic `mainColorLoadOp`, skybox's specific
+ * clearColor) flow through `options`.
+ *
+ * Stencil-op gate is auto-derived from `specAttachments.depthFormat`:
+ * - `'depth24plus-stencil8'` → emits `stencilLoadOp:'clear', stencilStoreOp:'discard'`
+ * - any other depth format → omits stencil ops entirely
+ *
+ * This collapses the R3/R5 stencil-op duplicates that previously lived inline
+ * at every forward-pass beginRenderPass site.
+ *
+ * @param specAttachments - the attachments axis from a PipelineSpec
+ * @param viewBindings - resolved texture views: `{ colorViews, depthView?, resolveTargets? }`
+ * @param passKind - one of the keys in {@link passKindPolicyTable}
+ * @param options - per-call ops overrides (loadOp / clearValue / label)
+ * @returns a WebGPU render-pass descriptor
+ * @throws PipelineSpecError(`'unknown-pass-kind'`) when passKind is not registered
+ * @see plan-strategy M4 · requirements AC-06
+ */
+export declare function buildBeginRenderPassDescriptor(specAttachments: PipelineSpec['attachments'], viewBindings: {
+    readonly colorViews: readonly unknown[];
+    readonly resolveTargets?: readonly (unknown | undefined)[];
+    readonly depthView?: unknown;
+}, passKind: string, options?: {
+    readonly colorLoadOp?: 'clear' | 'load';
+    readonly colorStoreOp?: 'store' | 'discard';
+    readonly clearColor?: GPUColor;
+    readonly depthLoadOp?: 'clear' | 'load';
+    readonly depthStoreOp?: 'store' | 'discard';
+    readonly label?: string;
+}): Record<string, unknown>;
+/**
+ * Dev-mode equality check: two PipelineSpec instances are structurally equal
+ * when every axis field is `===` (shallow compare).
+ *
+ * Not intended for runtime hot paths — use `cacheKeyOf(a) === cacheKeyOf(b)`
+ * for cache-hit checks. This function exists for dev-time assertions
+ * (`assert(specsEqual(specA, specB))`) and unit-test round-trip verification.
+ *
+ * @see plan-strategy §3.2 · requirements AC-02
+ */
+export declare function specsEqual(a: PipelineSpec, b: PipelineSpec): boolean;
+/**
+ * Validate a PipelineSpec before attempting to build.
+ *
+ * Fail-fast checks (charter P5) covering axis mutual-exclusion rules.
+ * Returns `Result<void, PipelineSpecError>` — ok for valid specs,
+ * err with structured code + detail for invalid ones.
+ *
+ * Checks:
+ * 1. `sampleCount=4` with empty `colorFormats` → `'spec-inconsistent'`
+ * 2. Pass kind not in `KNOWN_PASS_KINDS` → `'unknown-pass-kind'`
+ * 3. `depthFormat` undefined but `renderState` implies depth testing →
+ *    `'attachment-format-incompatible'`
+ *
+ * @see plan-strategy §3.2 · requirements AC-02 · charter P5
+ */
+export declare function validateSpec(spec: PipelineSpec): {
+    ok: true;
+} | {
+    ok: false;
+    code: PipelineSpecErrorCode;
+    detail: Record<string, unknown>;
+    hint?: string;
+};
+/**
+ * Pipeline cache — Map from cacheKeyOf(spec) to opaque RenderPipeline handle.
+ *
+ * Constructed once at createRenderer boot time; shared across all call sites.
+ * Consumers call `getOrBuildPipeline(spec, deviceProvider, cache)` — the
+ * entrypoint does cache lookup internally; consumers never touch the Map
+ * directly.
+ *
+ * @see plan-strategy D-12 · requirements §3.2
+ */
+export type PipelineCache = Map<string, unknown>;
+/**
+ * Device factory interface consumed by {@link getOrBuildPipeline}.
+ *
+ * Slim abstraction: only `createRenderPipeline` is needed; the entrypoint
+ * does not depend on the full `RhiDevice` interface so it can be tested
+ * with a mock.
+ */
+export interface PipelineDeviceProvider {
+    createRenderPipeline(descriptor: Record<string, unknown>): {
+        ok: true;
+        value: unknown;
+    } | {
+        ok: false;
+        error: unknown;
+    };
+}
+/**
+ * Single entrypoint for obtaining a render pipeline from a spec.
+ *
+ * Cache-hit path: key = cacheKeyOf(spec), returns cached handle immediately.
+ * Cache-miss path: validates spec → builds descriptor → calls device.createRenderPipeline
+ * → caches result → returns handle.
+ * Build failure: throws PipelineSpecError (charter P3 fail-fast, no silent fallback).
+ *
+ * Pure function: same (spec, deviceProvider, cache) always produces the same result.
+ * Boot-time call site: createRenderer wires the real device; record-stage call site
+ * uses ctx.runtime.device (same entrypoint, same signature).
+ *
+ * @param spec - immutable 4-axis pipeline specification
+ * @param deviceProvider - factory with createRenderPipeline method
+ * @param cache - the PipelineCache (shared across boot + record stage)
+ * @returns a RenderPipeline handle (opaque, typed as unknown for M1)
+ * @throws PipelineSpecError on validation failure or build failure
+ * @see plan-strategy D-12 · requirements AC-03 · charter F1
+ */
+export declare function getOrBuildPipeline(spec: PipelineSpec, deviceProvider: PipelineDeviceProvider, cache: PipelineCache, modules?: {
+    vertex: unknown;
+    fragment: unknown;
+    vertexEntryPoint?: string;
+    fragmentEntryPoint?: string;
+    layout?: unknown;
+}): unknown;
+/**
+ * Build the boot-time pre-warm table: 15 standard PipelineSpec variants.
+ *
+ * feat-20260625-refactor-sprite-as-transparent-mesh M3 / w14 (AC-12): the
+ * four `forgeax::default-sprite` entries (LDR S1 + LDR S4 + HDR S1 + HDR S4)
+ * are gone — sprite PSO lands lazily through the generic
+ * per-MaterialShader pipeline cache. Pre-feat count was 19; post-feat 15.
+ *
+ * Matrix:
+ *   - 8 base material variants — {unlit, standard-pbr} x {LDR, HDR} x {S1, S4}
+ *   - 4 URP-variant standard-pbr — standard-pbr (variantSet=URP_PBR_VARIANT_SET)
+ *     x {LDR, HDR} x {S1, S4}; URP record path requests these specs by
+ *     `getMaterialShaderPipeline` keying off `cacheKeyOf` so the boot-time
+ *     prewarm seeds `materialShaderPipelineCache` and avoids a 1-frame
+ *     async-compile skip-draw (M6 fix-up; see render-system-record.ts §URP)
+ *   - 3 fullscreen-post — tonemap (LDR S1) + skybox (HDR S1, HDR S4)
+ *
+ * Total: 15. The URP variant is PBR-only because:
+ *   - unlit URP record path passes `variantSet=undefined` (the no-variant
+ *     boot-default entries already cover it; createRenderer.ts §unlitRsp)
+ *   - sprite goes through `getMaterialShaderPipeline('forgeax::sprite', ...)`
+ *     lazily at first transparent-LDR-split draw — no boot-time pre-warm.
+ *   - HDRP variant (`variantSet=''` or compound `=true` form) is registered
+ *     lazily on `installPipeline(hdrpAsset)`, not at boot — adding HDRP
+ *     prewarm here would build PSOs against the URP layout (the boot-time
+ *     `pbrModule` is the URP variant when `isHdrpActive=false`)
+ *
+ * `ldrViewFormat` parameterises the LDR color attachment format. Callers
+ * pass the runtime-resolved swap-chain view format (Channel 2 typically
+ * `bgra8unorm-srgb`; Channel 3 wgpu-wasm and dawn-node typically
+ * `rgba8unorm-srgb`). Hard-coding `bgra8unorm-srgb` at module load made
+ * the pre-warmed PSOs incompatible with the actual RenderPass color
+ * attachment on Channel 3 / dawn-node, producing whole-commandBuffer
+ * invalid errors on every frame (bug-20260615 fix-up — see
+ * `createRenderer` boot-time pre-warm site).
+ *
+ * Fullscreen passes (fxaa / bloom x 3 / SSAO x 2) are lazy-build — they
+ * use the same getOrBuildPipeline entrypoint but are not in this table.
+ *
+ * @see plan-strategy D-4 · research R-D4 · requirements AC-16
+ * @see bug-20260612-webgpu-canvas-format-prefer-bgra-shipped (same trap shape)
+ */
+export declare function buildSpecConstTable(ldrViewFormat: GPUTextureFormat): readonly Readonly<PipelineSpec>[];
+/**
+ * Derive the material-only pre-warm table for a native linear-LDR target.
+ *
+ * The regular SPEC_CONST table targets the swap-chain view, while the
+ * tonemap=none path records geometry directly into the graph-owned
+ * `rgba16float` target. Keep that second attachment matrix derived from the
+ * same material specs so the first frame does not depend on an asynchronous
+ * lazy PSO build.
+ */
+export declare function buildLinearLdrMaterialSpecTable(ldrViewFormat: GPUTextureFormat): readonly Readonly<PipelineSpec>[];
+/**
+ * Backward-compatible SPEC_CONST_TABLE — the table built with the default
+ * LDR view format (`bgra8unorm-srgb`). Unit tests that exercise the
+ * spec/cache-keying layer in isolation import this directly. Runtime
+ * callers MUST call `buildSpecConstTable(swapChainFormats.view)` instead
+ * so the pre-warmed PSO color format matches the actual RenderPass color
+ * attachment on every backend (bug-20260615 fix-up).
+ */
+export declare const SPEC_CONST_TABLE: readonly Readonly<PipelineSpec>[];
+//# sourceMappingURL=pipeline-spec.d.ts.map

package/dist/pipeline-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-spec.d.ts","sourceRoot":"","sources":["../src/pipeline-spec.ts"],"names":[],"mappings":"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"}

package/dist/plugin.d.ts

@@ -0,0 +1,17 @@
+import type { Plugin } from '@forgeax/engine-plugin';
+import type { RenderFeature } from './features';
+import type { Renderer } from './renderer';
+declare module '@forgeax/engine-plugin' {
+    interface EngineContextServices {
+        renderer?: Renderer;
+    }
+}
+/** Install the built-in render and authoring component vocabulary in one World. */
+export declare function renderComponentsPlugin(): Plugin;
+/** Provide the renderer without transferring its host-owned lifetime. */
+export declare function rendererPlugin(renderer: Renderer): Plugin;
+/** Provide an App/Worker-owned Renderer and release it after dependent Fibers. */
+export declare function ownedRendererPlugin(renderer: Renderer): Plugin;
+/** Install a producer at Renderer safe points and remove it with the owning Fiber. */
+export declare function renderFeaturePlugin(feature: RenderFeature<unknown>): Plugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AA2BrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAiD3C,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,qBAAqB;QAC7B,QAAQ,CAAC,EAAE,QAAQ,CAAC;KACrB;CACF;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,IAAI,MAAM,CAS/C;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAQzD;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAS9D;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,MAAM,CAgB3E"}