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

package/dist/mesh-material-bindings.d.ts

@@ -0,0 +1,43 @@
+import type { AssetErrorDetail, AssetGuid, MeshAsset } from '@forgeax/engine-types';
+export type MeshMaterialBindingSource = 'renderer-override' | 'mesh-default' | 'engine-default';
+export interface MeshMaterialBindingDiagnostic {
+    readonly code: 'mesh-renderer-material-override-invalid' | 'mesh-renderer-material-override-overflow';
+    readonly slotIndex: number;
+    readonly handle?: number;
+    /** Structured detail mirrors the renderer error for the active frame. */
+    readonly detail?: Readonly<AssetErrorDetail>;
+}
+export interface ResolvedMeshMaterialBinding {
+    readonly handle: number;
+    readonly source: MeshMaterialBindingSource;
+}
+/** Public read-only observation of the bindings used by the last frame. */
+export interface MeshMaterialBindingObservation {
+    readonly worldId: number;
+    readonly entityKey: number;
+    readonly bindings: readonly ResolvedMeshMaterialBinding[];
+    readonly diagnostics: readonly MeshMaterialBindingDiagnostic[];
+}
+export type ResolveMeshMaterialBindingsResult = {
+    readonly ok: true;
+    readonly bindings: readonly ResolvedMeshMaterialBinding[];
+    readonly diagnostics: readonly MeshMaterialBindingDiagnostic[];
+} | {
+    readonly ok: false;
+    readonly code: 'mesh-material-slots-missing';
+} | {
+    readonly ok: false;
+    readonly code: 'mesh-default-material-not-ready';
+    readonly slotIndex: number;
+    readonly defaultMaterial: AssetGuid;
+};
+/**
+ * Single owner of the instance override -> mesh default -> engine default
+ * inheritance rule. It resolves once per logical slot; submeshes only project
+ * their materialSlot index onto the returned table.
+ */
+export declare function resolveMeshMaterialBindings(mesh: MeshAsset, rendererOverrides: ArrayLike<number>, deps: {
+    readonly isValidOverride: (handle: number) => boolean;
+    readonly resolveMeshDefault: (guid: AssetGuid) => number | undefined;
+}): ResolveMeshMaterialBindingsResult;
+//# sourceMappingURL=mesh-material-bindings.d.ts.map

package/dist/mesh-material-bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh-material-bindings.d.ts","sourceRoot":"","sources":["../src/mesh-material-bindings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEpF,MAAM,MAAM,yBAAyB,GAAG,mBAAmB,GAAG,cAAc,GAAG,gBAAgB,CAAC;AAEhG,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EACT,yCAAyC,GACzC,0CAA0C,CAAC;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAC;CAC5C;AAED,2EAA2E;AAC3E,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,2BAA2B,EAAE,CAAC;IAC1D,QAAQ,CAAC,WAAW,EAAE,SAAS,6BAA6B,EAAE,CAAC;CAChE;AAED,MAAM,MAAM,iCAAiC,GACzC;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,QAAQ,EAAE,SAAS,2BAA2B,EAAE,CAAC;IAC1D,QAAQ,CAAC,WAAW,EAAE,SAAS,6BAA6B,EAAE,CAAC;CAChE,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;CAC9C,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,SAAS,CAAC;CACrC,CAAC;AAEN;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,SAAS,EACf,iBAAiB,EAAE,SAAS,CAAC,MAAM,CAAC,EACpC,IAAI,EAAE;IACJ,QAAQ,CAAC,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IACtD,QAAQ,CAAC,kBAAkB,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,GAAG,SAAS,CAAC;CACtE,GACA,iCAAiC,CA8CnC"}

package/dist/pbr-pipeline.d.ts

@@ -0,0 +1,301 @@
+import type { BindGroup, BindGroupEntry, BindGroupLayout, BindGroupLayoutDescriptor, Buffer, PipelineLayout, RhiDevice, Sampler, TextureView } from '@forgeax/engine-rhi';
+import { type ShaderCatalog } from '@forgeax/engine-shader';
+import { type ParamSchemaEntry } from '@forgeax/engine-types';
+import type { PipelineSpec } from './pipeline-spec-types';
+/** The PBR layout builder consumes only the two creation methods it owns. */
+export type PbrPipelineDevice = Pick<RhiDevice, 'createBindGroupLayout' | 'createPipelineLayout'>;
+export interface PbrPipelineLayoutBundle {
+    /** Pipeline layout passed to `createRenderPipeline({ layout })`. */
+    readonly pipelineLayout: PipelineLayout;
+    /** view BindGroupLayout (slot 0). */
+    readonly viewBgl: BindGroupLayout;
+    /**
+     * PBR material BindGroupLayout (slot 1) -- derived user-region entries plus
+     * Skylight and lightmap injection.
+     */
+    readonly materialBgl: BindGroupLayout;
+    /** Per-entity mesh BindGroupLayout (slot 2). */
+    readonly meshArrayBgl: BindGroupLayout;
+    /** Per-instance storage BindGroupLayout (slot 3). */
+    readonly instancesBgl: BindGroupLayout;
+    /**
+     * Same 4 layouts in slot order. Useful for assertion sites that check the
+     * pipeline-layout `bindGroupLayouts` array shape (t57 (a) + (d)).
+     */
+    readonly bindGroupLayouts: readonly [
+        BindGroupLayout,
+        BindGroupLayout,
+        BindGroupLayout,
+        BindGroupLayout
+    ];
+}
+/**
+ * The built-in standard-PBR material paramSchema's texture/user-region shape,
+ * used as the fallback when the material BGL is built without a registry
+ * (the caps-driven `buildPbrPipelineLayouts` seam). Declares the 3 standard
+ * user-region textures + a numeric UBO run; `derive()` collapses the numerics
+ * into binding 0 and emits sampler/texture pairs at 1..6 — byte-equivalent to
+ * the legacy fixed base-7. The shared PBR parameter contract comes from the
+ * shader package; this module only derives the GPU layout.
+ */
+/**
+ * Build the PBR material BGL **user-region** from a paramSchema via the
+ * `derive()` SSOT (D-1). The user-region is binding 0 (the run-merged material
+ * UBO) followed by one sampler/texture pair per declared texture. Engine
+ * injection (IBL + lightmap) is appended AFTER this region by the caller via
+ * `appendInjection`, with start binding = `userRegion.length` — so a 4-texture
+ * custom schema (e.g. parallax + heightTexture) shifts the injection region by
+ * one sampler/texture pair automatically.
+ *
+ * The built-in `default-standard-pbr` paramSchema declares exactly 4 textures,
+ * so this derives to binding 0 UBO + 4 pairs = 9 entries. Injection is appended
+ * after that derived region.
+ *
+ * One material-UBO convention is layered on top of the pure `derive()` output:
+ * binding 0 is patched to `{ type: 'uniform', hasDynamicOffset: true }` with
+ * `VERTEX | FRAGMENT` visibility. The material UBO is bound with a per-submesh
+ * dynamic offset (`render-system-record.ts setBindGroup(1, bg, [offset])`) and
+ * the vertex stage reads material params, so this is required for GPU
+ * validation. `derive()` stays FRAGMENT-only / no-dynamic-offset for its other
+ * consumers (it is the generic SSOT, not the material-UBO authority).
+ *
+ * @param paramSchema - the material shader's paramSchema (defaults to the
+ *   built-in standard-PBR shape when omitted, for the caps-driven seam).
+ */
+export declare function buildPbrMaterialUserRegionEntries(paramSchema?: readonly ParamSchemaEntry[]): GPUBindGroupLayoutEntry[];
+export type InjectionKind = keyof typeof INJECTION_KIND_LENGTHS;
+/**
+ * Append the engine-injection BGL entries for the given `kind` after the
+ * user-region BGL entries, with binding numbers starting at `bgl.length`.
+ *
+ * The function reads `bgl.length` (NOT a hardcoded constant) so each
+ * user-region size — derived from `derive(schema).userRegionBindingEnd` or
+ * computed manually — flows through to the injection start binding without
+ * a coupled edit.
+ *
+ * Returns ONLY the injected entries; the caller spreads them after `bgl`:
+ *
+ * ```ts
+ * const merged = [...userBgl, ...appendInjection(userBgl, 'ibl')];
+ * device.createBindGroupLayout({ entries: merged });
+ * ```
+ */
+export declare function appendInjection(bgl: readonly GPUBindGroupLayoutEntry[], kind: InjectionKind): GPUBindGroupLayoutEntry[];
+export declare const INJECTION_KIND_LENGTHS: {
+    shadow: number;
+    ibl: number;
+    lightmap: number;
+};
+/**
+ * Caps shape consumed by the BGL factory functions for storage-buffer vs
+ * uniform-buffer branching. Mirrors the two fields the engine reads from
+ * `RhiCaps` (plan D-4 + D-5).
+ */
+export interface PbrCaps {
+    readonly storageBuffer: boolean;
+}
+/**
+ * The view BGL entry list. binding 0 = view UBO (vertex + fragment);
+ * binding 1 = pointLights (storage or uniform, per caps);
+ * binding 2 = spotLights (storage or uniform, per caps);
+ * binding 3 = directional shadowMap atlas (texture_depth_2d, vertex+fragment).
+ *   feat-20260613-csm-cascaded-shadow-maps: this is the CSM atlas — N
+ *   cascades tiled into one 2D depth texture, sampled via per-cascade UV
+ *   mapping in `lighting-directional.wgsl`. Single binding survives N=1..4
+ *   (no array-layer form; cascades live in viewport offsets per the
+ *   check-csm-unique-shadow-path grep gate).
+ * binding 4 = shadow comparison sampler (shared by directional + point);
+ * binding 5 = point shadow cube_array depth atlas (texture_depth_cube_array;
+ *   fragment-only). feat-20260612-point-light-shadows-urp-hdrp Round-2 F-1.
+ * binding 6 = point shadow params UBO (`array<vec4<f32>, 4>`, 64 B;
+ *   fragment-only). One lane per shadow-casting point light slot
+ *   (shadowAtlasLayer in [0, 4)) carrying `(near, far, 1/(far-near), 0)`.
+ * binding 7 = shadowCasterCascade UBO (16 B; vertex + fragment). Per-pass
+ *   cascade-index uniform consumed exclusively by `shadow_caster.wgsl` to
+ *   pick `view.lightViewProj_X` for the cascade currently being rasterized
+ *   (feat-20260613-csm-cascaded-shadow-maps M5 / w28). Forward PBR shaders
+ *   declare the binding via `common.wgsl` but do not reference it; WebGPU
+ *   still requires a populated entry on every view BG so the host writes a
+ *   stable singleton buffer.
+ * binding 8 = spot shadow atlas (texture_depth_2d; fragment-only).
+ *   feat-20260625-spot-light-shadow-mapping M3 / w14 (D-5). A single 2D depth
+ *   texture holding up to 4 spot shadows in a 2x2 tile grid. ALWAYS-ON (no caps
+ *   gate — `texture_depth_2d` is compat-safe everywhere), matching the
+ *   unconditional `spotShadowMap` WGSL declaration in common.wgsl. Reuses the
+ *   comparison sampler at binding 4 (no binding 9). Every view BG must populate
+ *   binding 8 (real spotShadowDepth view when spot shadows run, else a 1x1
+ *   fallback depth view cleared to fully-lit).
+ *
+ * Mirrors feat-20260519-light-casters M3 D-S1 layout +
+ * feat-20260520-directional-light-shadow-mapping M2 / w14 (D-1) shadow
+ * map binding +
+ * feat-20260612-point-light-shadows-urp-hdrp Round-2 F-1 BGL hookup
+ * (always-on bindings 5/6 paired with the unconditional `POINT_SHADOW_AVAILABLE`
+ * define registered in vite-plugin-shader) +
+ * feat-20260613-csm-cascaded-shadow-maps M5 / w28 (binding 7 cascade UBO).
+ *   binding 10 (Points/Lines viewport UBO; always bound for the shared view
+ *   layout and consumed only by the dedicated points-lines shader).
+ * Isolated here so M4 round-4 tests can recreate the layout.
+ *
+ * feat-20260526-pbr-uniform-fallback-no-storage-buffer M3 / w9:
+ * caps.storageBuffer===false switches bindings 1+2 from
+ * 'read-only-storage' to 'uniform'.
+ */
+export declare function buildPbrViewBglEntries(caps: PbrCaps): GPUBindGroupLayoutEntry[];
+/**
+ * Build the PBR pipeline layout under D-5 round-4: 4 slots `[view,
+ * material, mesh-array, instances]`; the material BGL is derived from the
+ * standard material schema and engine injection chain.
+ *
+ * `caps.storageBuffer===false` switches every storage-buffer BGL entry
+ * (view bindings 1+2, mesh-array, instances) to `uniform`.
+ *
+ * Throws on each `createBindGroupLayout` / `createPipelineLayout` Result
+ * failure -- the engine bootstrap path (createRenderer) wraps the call in
+ * `runShimSyncStep` to fold the throw into the structured error pipe.
+ */
+export declare function buildPbrPipelineLayouts(device: PbrPipelineDevice, caps: PbrCaps): PbrPipelineLayoutBundle;
+/**
+ * SSOT for the skin material shader's registered identifier. The shader
+ * package registers under this string (see register-default-standard-pbr-skin.ts
+ * `RESERVED_ID`); runtime dispatch sites import this constant rather than
+ * carrying a literal so a future rename is a one-line change. AC-09 grep
+ * gate: the body of `selectPipelineLayoutForVariant` MUST NOT contain a
+ * literal `'forgeax::pbr-skin'` -- callers map this constant to
+ * `LayoutKind = 'pbr-skin'` upstream.
+ */
+export declare const SKIN_MATERIAL_SHADER_ID: "forgeax::pbr-skin";
+/** Returns true for the engine-shipped standard-PBR material shader family. */
+export declare function isStandardPbrMaterialShader(shaderId: string | undefined): boolean;
+/**
+ * Build the PBR skin pipeline layout (4 slots `[view, material,
+ * mesh-array(2-entry), instances]`). View / material / instances BGLs are
+ * shared with the standard-PBR layout (passed in via `pbr` bundle); the only
+ * new BGL is the 2-entry mesh-array slot for `meshes` + `palette`.
+ *
+ * Throws on each `createBindGroupLayout` / `createPipelineLayout` Result
+ * failure -- the engine bootstrap path wraps the call in `runShimSyncStep`
+ * to fold the throw into the structured error pipe.
+ */
+export declare function buildPbrSkinLayouts(device: PbrPipelineDevice, caps: PbrCaps, pbr: PbrPipelineLayoutBundle): PbrPipelineLayoutBundle;
+/**
+ * Build a stand-alone 7-entry unlit material BGL. Round-4 D-5 keeps unlit
+ * material BG isolated from Skylight binding 7..13 -- unlit demos do not
+ * pay for IBL state. The unlit pipeline still binds material at slot 1,
+ * just with a 7-entry layout.
+ *
+ * Note: at the moment the runtime still routes both unlit + standard
+ * through a single 14-entry pipeline layout; the unlit material BG
+ * carries fallback identity resources at binding 7..13. This factory is
+ * exported as a future-proof seam for the moment when unlit demos own
+ * their own pipeline layout (t57 (e) test pins the contract today so the
+ * eventual split has a green target).
+ */
+export declare function buildUnlitMaterialBgl(device: PbrPipelineDevice): BindGroupLayout;
+/**
+ * Inputs for `buildUnlitMaterialBindGroupEntries`. The fields mirror the
+ * record-stage's local variables; isolating the assembler here lets t58
+ * (e) test exercise the contract without recreating the entire record
+ * stage.
+ */
+export interface UnlitMaterialBindGroupEntryInputs {
+    readonly materialUniform: Buffer;
+    readonly materialOffset: number;
+    readonly materialSize: number;
+    readonly defaultSampler: Sampler;
+    readonly baseColorView: TextureView;
+    readonly defaultWhiteView: TextureView;
+}
+/**
+ * Build the 7 BindGroupEntry values for the unlit material BG (binding
+ * 0..6). Output flows into `device.createBindGroup({ layout:
+ * unlitMaterialBgl, entries })`.
+ */
+export declare function buildUnlitMaterialBindGroupEntries(inputs: UnlitMaterialBindGroupEntryInputs): BindGroupEntry[];
+export type { BindGroup };
+/**
+ * variantSet string fired into the sprite-pass pipeline cache when the
+ * entity carries `SpriteInstances` (plan-strategy D-1 interleaved single
+ * buffer + D-4 axis on `sprite.wgsl`).
+ *
+ * bug-20260708 M2 (c): aligned with the canonical all-true variant key
+ * `''` — sprite's manifest emits `{PIR:true, SBA:true}` under the empty-
+ * string key (all variant axes true → canonical). The runtime's
+ * `getMaterialShaderPipeline` variant-substitution branch
+ * (`createRenderer.ts:1730`) resolves this via
+ * `findVariantByKey(msEntry, '')` returning the 5653B PIR=true variant.
+ * Combined with the `cacheKeyOf` sentinel `~` (bug-20260708 M2 (b)) this
+ * value produces a cache key distinct from the `variantSet=undefined`
+ * character/default path (which now resolves to the PIR=false 5575B boot-
+ * registered variant). Sprite pipeline layout routing is anchored via
+ * `LayoutKind='sprite-urp'` so `variantSet=''` here does NOT trigger the
+ * HDRP-layout branch of `selectPipelineLayoutForVariant` (research R-12
+ * flow; plan-strategy §4 R-1' guard).
+ */
+export declare const SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET = "";
+/**
+ * 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'` — 2 entries: meshes + skin palette
+ * 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';
+/**
+ * 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[];
+}
+/** Build the canonical HDRP group(2) bind-group layout. */
+export declare function createHdrpBindGroupLayoutDescriptor(storageBuffer?: boolean): BindGroupLayoutDescriptor;
+export declare function buildBindGroupLayoutDescriptor(spec: PipelineSpec, options: {
+    kind: BglKind;
+    registry?: ShaderCatalog;
+    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;
+//# sourceMappingURL=pbr-pipeline.d.ts.map

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

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

package/dist/pipeline/standard-forward-lane.d.ts

@@ -0,0 +1,5 @@
+import type { RenderPipeline, RenderPipelineBuildContext, RenderPipelineFrame, RenderPipelineTopology } from '../render-pipeline';
+declare function buildUrp(context: RenderPipelineBuildContext<RenderPipelineFrame>, topology: RenderPipelineTopology): ReturnType<RenderPipeline['build']>;
+export declare const buildStandardForwardLane: typeof buildUrp;
+export {};
+//# sourceMappingURL=standard-forward-lane.d.ts.map

package/dist/pipeline/standard-forward-lane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard-forward-lane.d.ts","sourceRoot":"","sources":["../../src/pipeline/standard-forward-lane.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,cAAc,EACd,0BAA0B,EAC1B,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,oBAAoB,CAAC;AAyB5B,iBAAS,QAAQ,CACf,OAAO,EAAE,0BAA0B,CAAC,mBAAmB,CAAC,EACxD,QAAQ,EAAE,sBAAsB,GAC/B,UAAU,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CA0LrC;AAED,eAAO,MAAM,wBAAwB,iBAAW,CAAC"}

package/dist/pipeline/standard-pipeline.d.ts

@@ -0,0 +1,31 @@
+import { type Result } from '@forgeax/engine-types';
+import type { RenderPipeline } from '../render-pipeline';
+import { STANDARD_PIPELINE_ID } from './standard-profile';
+/** WGSL owner for the Standard clustered membership producer. */
+export declare const STANDARD_CLUSTER_MEMBERSHIP_WGSL = "\nstruct ClusterUniform {\n  grid : vec4<u32>,\n  near_far_log : vec4<f32>,\n};\n\n@group(0) @binding(0) var<storage, read> cluster_grid : array<u32>;\n@group(0) @binding(1) var<storage, read_write> light_index_list : array<u32>;\n@group(0) @binding(2) var<uniform> cluster_uniform : ClusterUniform;\n@group(0) @binding(3) var<storage, read> light_bounds : array<i32>;\n\n@compute @workgroup_size(64)\nfn cs_cluster_membership(@builtin(global_invocation_id) global_id : vec3<u32>) {\n  let cluster_index = global_id.x;\n  let grid_x = cluster_uniform.grid.x;\n  let grid_y = cluster_uniform.grid.y;\n  let grid_z = cluster_uniform.grid.z;\n  let cluster_count = grid_x * grid_y * grid_z;\n  if (cluster_index >= cluster_count) {\n    return;\n  }\n\n  let cluster_x = cluster_index % grid_x;\n  let cluster_yz = cluster_index / grid_x;\n  let cluster_y = cluster_yz % grid_y;\n  let cluster_z = cluster_yz / grid_y;\n  let grid_offset = cluster_index * 2u;\n  let output_offset = cluster_grid[grid_offset];\n  let output_count = cluster_grid[grid_offset + 1u];\n  let cluster_x_i = i32(cluster_x);\n  let cluster_y_i = i32(cluster_y);\n  let cluster_z_i = i32(cluster_z);\n  var output_index = output_offset;\n\n  var light_index = 0u;\n  loop {\n    if (light_index >= cluster_uniform.grid.w || light_index >= 256u) {\n      break;\n    }\n    let bounds_offset = light_index * 6u;\n    let min_x = light_bounds[bounds_offset];\n    if (min_x >= 0) {\n      let min_y = light_bounds[bounds_offset + 1u];\n      let min_z = light_bounds[bounds_offset + 2u];\n      let max_x = light_bounds[bounds_offset + 3u];\n      let max_y = light_bounds[bounds_offset + 4u];\n      let max_z = light_bounds[bounds_offset + 5u];\n      if (\n        cluster_x_i >= min_x && cluster_x_i <= max_x &&\n        cluster_y_i >= min_y && cluster_y_i <= max_y &&\n        cluster_z_i >= min_z && cluster_z_i <= max_z\n      ) {\n        if (output_index < output_offset + output_count) {\n          light_index_list[output_index] = light_index;\n          output_index += 1u;\n        }\n      }\n    }\n    light_index += 1u;\n  }\n}\n";
+export declare class HdrpInstallError extends Error {
+    readonly code: "hdrp-grid-invalid";
+    readonly expected = "clusterGrid.{x,y,z} each integer in [1, 64]";
+    readonly hint: string;
+    readonly detail: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    };
+    constructor(x: number, y: number, z: number);
+}
+export declare function validateClusterGrid(grid: {
+    x: number;
+    y: number;
+    z: number;
+}): Result<{
+    x: number;
+    y: number;
+    z: number;
+}, HdrpInstallError>;
+export interface StandardPipeline extends RenderPipeline {
+    readonly identity: typeof STANDARD_PIPELINE_ID;
+}
+export declare const standardPipeline: StandardPipeline;
+export { DEFAULT_STANDARD_PROFILE, STANDARD_PIPELINE_ID } from './standard-profile';
+//# sourceMappingURL=standard-pipeline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"standard-pipeline.d.ts","sourceRoot":"","sources":["../../src/pipeline/standard-pipeline.ts"],"names":[],"mappings":"AAOA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAW7D,OAAO,KAAK,EACV,cAAc,EAIf,MAAM,oBAAoB,CAAC;AAoB5B,OAAO,EAOL,oBAAoB,EAErB,MAAM,oBAAoB,CAAC;AAE5B,iEAAiE;AACjE,eAAO,MAAM,gCAAgC,ykEA6D5C,CAAC;AACF,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAG,mBAAmB,CAAU;IAC7C,QAAQ,CAAC,QAAQ,iDAAiD;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;gBAEpE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM;CAO5C;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX,GAAG,MAAM,CAAC;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,gBAAgB,CAAC,CAahE;AAqWD,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,QAAQ,CAAC,QAAQ,EAAE,OAAO,oBAAoB,CAAC;CAChD;AAyCD,eAAO,MAAM,gBAAgB,EAAE,gBAG7B,CAAC;AAEH,OAAO,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/pipeline/standard-profile.d.ts

@@ -0,0 +1,40 @@
+export declare const STANDARD_PIPELINE_ID: "forgeax::standard";
+export declare const STANDARD_LIGHT_COUNTS: readonly [1, 32, 256];
+/** Shared clustered-lighting facts consumed by pipeline, record, and buffers. */
+export declare const DEFAULT_CLUSTER_GRID: {
+    readonly x: 16;
+    readonly y: 9;
+    readonly z: 24;
+};
+export declare const CLUSTER_GRID_STRIDE_U32 = 2;
+export declare const LIGHT_INDEX_LIST_CAPACITY = 1048576;
+export declare const MAX_LIGHTS = 256;
+export type StandardLightCount = (typeof STANDARD_LIGHT_COUNTS)[number];
+export type StandardLightingLane = 'direct' | 'clustered';
+export type StandardFallbackLane = 'native' | 'cpu-webgl2';
+export type StandardShadowMode = 'off' | 'hard' | 'filtered';
+export type StandardTone = 'none' | 'aces-filmic' | 'agx' | 'cineon' | 'linear' | 'neutral' | 'reinhard' | 'reinhard-extended';
+export type StandardAntialias = 'none' | 'fxaa' | 'msaa';
+export type StandardPostStage = 'transparent-blend' | 'bloom' | 'tone' | 'fxaa' | 'output';
+export interface StandardProfile {
+    readonly pipelineId: typeof STANDARD_PIPELINE_ID;
+    readonly lightCount: StandardLightCount;
+    readonly lighting: StandardLightingLane;
+    readonly shadows: StandardShadowMode;
+    readonly pbr: boolean;
+    readonly ibl: boolean;
+    readonly ssao: boolean;
+    readonly bloom: boolean;
+    readonly tone: StandardTone;
+    readonly antialias: StandardAntialias;
+    readonly sky: boolean;
+    readonly fallback: StandardFallbackLane;
+    readonly postStages: readonly ['transparent-blend', 'bloom', 'tone', 'fxaa', 'output'];
+}
+export declare const DEFAULT_STANDARD_PROFILE: StandardProfile;
+export type StandardLane = StandardLightingLane | 'cpu-webgl2';
+export declare function resolveStandardLane(profile: Pick<StandardProfile, 'lighting'>, capabilities: {
+    readonly compute: boolean;
+    readonly storageBuffer: boolean;
+}): StandardLane;
+//# sourceMappingURL=standard-profile.d.ts.map

package/dist/pipeline/standard-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard-profile.d.ts","sourceRoot":"","sources":["../../src/pipeline/standard-profile.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,EAAG,mBAA4B,CAAC;AACjE,eAAO,MAAM,qBAAqB,uBAAwB,CAAC;AAC3D,iFAAiF;AACjF,eAAO,MAAM,oBAAoB;;;;CAAkC,CAAC;AACpE,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,eAAO,MAAM,yBAAyB,UAAU,CAAC;AACjD,eAAO,MAAM,UAAU,MAAM,CAAC;AAE9B,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AACxE,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAC1D,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,YAAY,CAAC;AAC3D,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,CAAC;AAC7D,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,aAAa,GACb,KAAK,GACL,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,UAAU,GACV,mBAAmB,CAAC;AACxB,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AACzD,MAAM,MAAM,iBAAiB,GAAG,mBAAmB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE3F,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,OAAO,oBAAoB,CAAC;IACjD,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,mBAAmB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;CACxF;AAED,eAAO,MAAM,wBAAwB,EAAE,eAcrC,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,oBAAoB,GAAG,YAAY,CAAC;AAE/D,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,UAAU,CAAC,EAC1C,YAAY,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;CAAE,GAC3E,YAAY,CAGd"}

package/dist/pipeline-builder.d.ts

@@ -0,0 +1,122 @@
+import { type PipelineLayout, type RenderPipeline, type Result, type RhiDevice, RhiError, type ShaderModule } from '@forgeax/engine-rhi';
+import type { MaterialShaderEntry } from '@forgeax/engine-shader';
+import type { MaterialRenderState, PassKind, PrimitiveTopology } from '@forgeax/engine-types';
+/**
+ * feat-20260604-mesh-topology-debug-draw M3 / w8: per-mesh geometry facts that
+ * are baked into the immutable GPURenderPipeline `primitive` block. Distinct
+ * from {@link MaterialRenderState} (material-authored state); these are
+ * geometry properties of the mesh being drawn (requirements D-2 / D-A3).
+ */
+export interface PipelineGeometry {
+    /** Primitive topology baked into `primitive.topology`. Defaults to 'triangle-list'. */
+    readonly topology?: PrimitiveTopology;
+    /**
+     * Index format for strip topologies (`line-strip` / `triangle-strip`), baked
+     * into `primitive.stripIndexFormat`. WebGPU spec: only valid for strip
+     * topologies; ignored (left undefined in the descriptor) for list topologies.
+     */
+    readonly stripIndexFormat?: 'uint16' | 'uint32';
+}
+/**
+ * Sync shader-module factory consumed by `buildPipelineForMaterialShader`.
+ * Mirrors `ShaderCatalogDevice.createShaderModule` (sync Result shape) so
+ * the same `makeShaderDeviceAdapter` in `createRenderer.ts` can satisfy
+ * both surfaces (charter P4 consistent abstraction). The adapter caches
+ * the underlying async `pack.createShaderModule` so subsequent sync calls
+ * return cached modules; first call typically returns
+ * `Result.err('rhi-not-available')` while the async build is in flight,
+ * letting the caller fall back to the existing `standardPipeline` for
+ * one frame and retry on the next (matches `render-system-record`'s
+ * 1-frame-warmup idiom).
+ */
+export interface PipelineBuilderShaderModuleFactory {
+    createShaderModule(desc: {
+        readonly code: string;
+        readonly label?: string | undefined;
+    }): Result<ShaderModule, RhiError>;
+}
+/**
+ * Build context for `buildPipelineForMaterialShader`. Caller (createRenderer
+ * + render-system-record) computes this once per renderer and reuses across
+ * cache misses; the values mirror the existing PBR pipeline construction
+ * (createRenderer.ts ~line 2712 standardPipelineResult) so user shaders
+ * land on the same 4-BindGroupLayout chain (charter P4 + plan-strategy
+ * R-H).
+ */
+export interface PipelineBuilderContext {
+    /** RHI device that owns the pipeline allocation. */
+    readonly device: RhiDevice;
+    /**
+     * Sync shader-module factory (see {@link PipelineBuilderShaderModuleFactory}).
+     * In production the engine wires the same `makeShaderDeviceAdapter` it
+     * already uses for `ShaderCatalog.get(hash)`; tests pass a
+     * `vi.fn`-based stub.
+     */
+    readonly shaderModuleFactory: PipelineBuilderShaderModuleFactory;
+    /**
+     * Shared pipeline layout (4 BindGroupLayouts: view + material + mesh-array
+     * + instances). User shaders bind through the same slots as
+     * default-standard-pbr; D-5 round-4 SSOT.
+     */
+    readonly pipelineLayout: PipelineLayout;
+    /**
+     * Color attachment format. The LDR / HDR variants pick `bgra8unorm-srgb` /
+     * `rgba16float` respectively; record-stage gate matches the camera's
+     * tonemap field (M9 keeps the LDR shape; HDR variants are OOS-M9).
+     */
+    readonly colorFormat: GPUTextureFormat;
+    /** Depth attachment format, or `undefined` for a color-only pass. */
+    readonly depthFormat: GPUTextureFormat | undefined;
+    /**
+     * Vertex buffer layout descriptors. Procedural geometry uses the 12-floats
+     * stride (position + normal + uv + tangent); user shaders share this
+     * layout for v1 (OOS-9 leaves alternative vertex layouts for a follow-up
+     * feat).
+     */
+    readonly vertexBuffers: readonly GPUVertexBufferLayout[];
+    /** Pipeline label (for GPU debug captures); defaults to `pbr-pipeline-${id}`. */
+    readonly label?: string | undefined;
+    /**
+     * feat-20260604-mesh-topology-debug-draw w16-b: the shader-MODULE cache
+     * identity, decoupled from the PSO `label` and the `id` arg. The WGSL module
+     * depends ONLY on (source + defines), NOT on topology / renderState / isHdr /
+     * indexFormat -- all of which WebGPU bakes into the immutable PSO, never the
+     * module. `makeShaderDeviceAdapter` keys its `moduleCache` on this label, so
+     * passing a stable per-(shader-source, defines) value here lets every
+     * topology / renderState / HDR pipeline variant of the same shader SHARE one
+     * compiled module: the first variant warms it, every later variant reuses it
+     * synchronously (no per-variant async recompile, no event-loop yield).
+     * Falls back to `shader-${id}` when omitted (pre-w16-b behaviour: the `id`
+     * arg doubled as both PSO cache key and module label). The defines dimension
+     * is NOT folded in here because the engine pre-resolves define variants into
+     * distinct registered `source` strings (createRenderer.ts variant
+     * resolution); callers that thread `defines` directly must include them in
+     * `moduleLabel` so two `#define` prefixes do not collide on one module.
+     */
+    readonly moduleLabel?: string | undefined;
+}
+/**
+ * Build a render pipeline for a material shader entry. Returns
+ * `Result.err(RhiError)` on shader-module compile failure or pipeline
+ * descriptor rejection (closed union RhiErrorCode pattern; AGENTS.md
+ * "Errors are structured" + charter P3 explicit failure).
+ *
+ * Caller flow (M9-T03):
+ * ```ts
+ * let pipeline = pipelineCache.get(materialShaderId);
+ * if (pipeline === undefined) {
+ *   const lookup = registry.findMaterialArtifact(materialShaderId);
+ *   if (!lookup.ok) {
+ *     // fallback to default-standard-pbr pipelineState.standardPipeline
+ *   } else {
+ *     const built = buildPipelineForMaterialShader(materialShaderId, lookup.value, ctx);
+ *     if (built.ok) pipelineCache.set(materialShaderId, built.value);
+ *     else if (built.error.code === 'rhi-not-available') {
+ *       // shader module still compiling async; retry next frame.
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare function buildPipelineForMaterialShader(id: string, entry: MaterialShaderEntry, ctx: PipelineBuilderContext, renderState?: MaterialRenderState, geometry?: PipelineGeometry, vertexEntry?: string, fragmentEntry?: string, defines?: Record<string, string>, passKind?: PassKind, sampleCount?: number): Result<RenderPipeline, RhiError>;
+//# sourceMappingURL=pipeline-builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-builder.d.ts","sourceRoot":"","sources":["../src/pipeline-builder.ts"],"names":[],"mappings":"AA2CA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,cAAc,EAEnB,KAAK,MAAM,EACX,KAAK,SAAS,EACd,QAAQ,EACR,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG9F;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;CACjD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kCAAkC;IACjD,kBAAkB,CAAC,IAAI,EAAE;QACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KACrC,GAAG,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,EAAE,kCAAkC,CAAC;IACjE;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACnD;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACzD,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,8BAA8B,CAC5C,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,mBAAmB,EAC1B,GAAG,EAAE,sBAAsB,EAC3B,WAAW,CAAC,EAAE,mBAAmB,EACjC,QAAQ,CAAC,EAAE,gBAAgB,EAC3B,WAAW,CAAC,EAAE,MAAM,EACpB,aAAa,CAAC,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,QAAQ,GAAE,QAAoB,EAO9B,WAAW,GAAE,MAAU,GACtB,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC,CA2LlC"}

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

@@ -0,0 +1,24 @@
+import type { VertexLayoutProjection } from '@forgeax/engine-geometry';
+import type { MaterialRenderState, PrimitiveTopology, VertexAttributeMap } from '@forgeax/engine-types';
+export interface PipelineSpec {
+    readonly shader: {
+        readonly id: string;
+        readonly passKind: string;
+        readonly variantSet: string | undefined;
+    };
+    readonly attachments: {
+        readonly colorFormats: readonly GPUTextureFormat[];
+        readonly depthFormat: GPUTextureFormat | undefined;
+        readonly sampleCount: 1 | 4;
+    };
+    readonly geometry: {
+        readonly topology: PrimitiveTopology;
+        readonly stripIndexFormat?: 'uint16' | 'uint32' | undefined;
+        readonly vertexLayout: VertexAttributeMap;
+        /** Geometry-owned immutable descriptor projection, when already derived. */
+        readonly vertexLayoutProjection?: VertexLayoutProjection | undefined;
+        readonly shaderUvSetCount?: number | undefined;
+    };
+    readonly renderState: MaterialRenderState | undefined;
+}
+//# sourceMappingURL=pipeline-spec-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-spec-types.d.ts","sourceRoot":"","sources":["../src/pipeline-spec-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;KACzC,CAAC;IACF,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,YAAY,EAAE,SAAS,gBAAgB,EAAE,CAAC;QACnD,QAAQ,CAAC,WAAW,EAAE,gBAAgB,GAAG,SAAS,CAAC;QACnD,QAAQ,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC;KAC7B,CAAC;IACF,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;QACrC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;QAC5D,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;QAC1C,4EAA4E;QAC5E,QAAQ,CAAC,sBAAsB,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;QACrE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAChD,CAAC;IACF,QAAQ,CAAC,WAAW,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACvD"}