@forgeax/engine-render 0.1.2

package/dist/mipmap-generator.d.ts

@@ -0,0 +1,39 @@
+import { type Result, RhiError } from '@forgeax/engine-rhi';
+export type MipmapDevice = {
+    createSampler(desc?: any): Result<any, any>;
+    createBindGroupLayout(desc: any): Result<any, any>;
+    createPipelineLayout(desc: any): Result<any, any>;
+    createRenderPipeline(desc: any): Result<any, any>;
+};
+export type MipmapShaderModuleFactory = (device: MipmapDevice, desc: {
+    code: string;
+    label?: string;
+}) => Promise<Result<unknown, RhiError>>;
+export declare function numMipLevels(size: {
+    width: number;
+    height: number;
+}): number;
+export declare function mipmapCacheSize(device: MipmapDevice): number;
+export declare function getOrCreateMipmapPipeline(device: MipmapDevice, format: GPUTextureFormat, asyncCreateShaderModule: MipmapShaderModuleFactory): Promise<Result<any, unknown>>;
+export type MipmapBlitDevice = MipmapDevice & {
+    createTexture(desc: any): Result<any, any>;
+    createBindGroup(desc: any): Result<any, any>;
+    createTextureView(texture: any, desc: any): Result<any, any>;
+    createCommandEncoder(desc?: any): Result<any, any>;
+    readonly queue: {
+        submit(buffers: ReadonlyArray<unknown>): Result<void, unknown>;
+    };
+};
+export declare function generateMipmaps(device: MipmapBlitDevice, texture: any, descriptor: {
+    readonly format: GPUTextureFormat;
+    readonly width: number;
+    readonly height: number;
+    readonly levels?: number;
+}, asyncCreateShaderModule: MipmapShaderModuleFactory): Promise<Result<void, unknown>>;
+export declare function blitMipmapsSync(device: MipmapBlitDevice, texture: any, descriptor: {
+    readonly format: GPUTextureFormat;
+    readonly width: number;
+    readonly height: number;
+    readonly levels?: number;
+}): Result<void, RhiError>;
+//# sourceMappingURL=mipmap-generator.d.ts.map

package/dist/mipmap-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mipmap-generator.d.ts","sourceRoot":"","sources":["../src/mipmap-generator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,MAAM,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAErE,MAAM,MAAM,YAAY,GAAG;IAEzB,aAAa,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAE5C,qBAAqB,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAEnD,oBAAoB,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAElD,oBAAoB,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;CACnD,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG,CACtC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,KACnC,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AA6BxC,wBAAgB,YAAY,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAG5E;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAE5D;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,gBAAgB,EACxB,uBAAuB,EAAE,yBAAyB,GAEjD,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAoB/B;AAqCD,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG;IAE5C,aAAa,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAE3C,eAAe,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAE7C,iBAAiB,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAE7D,oBAAoB,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE;QAAE,MAAM,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;CACpF,CAAC;AAyDF,wBAAsB,eAAe,CACnC,MAAM,EAAE,gBAAgB,EAExB,OAAO,EAAE,GAAG,EACZ,UAAU,EAAE;IACV,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,EACD,uBAAuB,EAAE,yBAAyB,GACjD,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAahC;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,gBAAgB,EAExB,OAAO,EAAE,GAAG,EACZ,UAAU,EAAE;IACV,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,GACA,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAwBxB"}

package/dist/param-schema-projection-census.d.ts

@@ -0,0 +1,18 @@
+import type { DerivedMaterialInterface, EngineMetrics, ParamSchemaDeriveObservationKind, ParamSchemaDeriveObserver, ParamSchemaEntry } from '@forgeax/engine-types';
+export type ParamSchemaProjectionCensusSite = 'entity-extract' | 'submesh' | 'prepared-material' | 'record-payload' | 'pipeline-bgl';
+export type ParamSchemaProjectionCensusKind = ParamSchemaDeriveObservationKind | 'registered-projection-read' | 'empty-schema-legacy-inference';
+export interface ParamSchemaProjectionCensus extends ParamSchemaDeriveObserver {
+    readonly record: (kind: ParamSchemaProjectionCensusKind, site: ParamSchemaProjectionCensusSite) => void;
+}
+/**
+ * Create the renderer-scoped, debug-only ParamSchema compatibility observer.
+ *
+ * The observer writes only to the existing per-Renderer EngineMetrics map.
+ * When `enabled` is false, both `observe` and `record` are no-ops; callers
+ * continue through the original derive/projection path without a new cache or
+ * content hash. Counter names are intentionally stable so a browser probe can
+ * subtract before/after snapshots without retaining renderer objects.
+ */
+export declare function createParamSchemaProjectionCensus(metrics: EngineMetrics, enabled: boolean): ParamSchemaProjectionCensus;
+export declare function deriveParamSchemaForCensus(schema: readonly ParamSchemaEntry[], census: ParamSchemaProjectionCensus | undefined, site: ParamSchemaProjectionCensusSite): DerivedMaterialInterface;
+//# sourceMappingURL=param-schema-projection-census.d.ts.map

package/dist/param-schema-projection-census.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"param-schema-projection-census.d.ts","sourceRoot":"","sources":["../src/param-schema-projection-census.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,aAAa,EACb,gCAAgC,EAChC,yBAAyB,EACzB,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAG/B,MAAM,MAAM,+BAA+B,GACvC,gBAAgB,GAChB,SAAS,GACT,mBAAmB,GACnB,gBAAgB,GAChB,cAAc,CAAC;AAEnB,MAAM,MAAM,+BAA+B,GACvC,gCAAgC,GAChC,4BAA4B,GAC5B,+BAA+B,CAAC;AAEpC,MAAM,WAAW,2BAA4B,SAAQ,yBAAyB;IAC5E,QAAQ,CAAC,MAAM,EAAE,CACf,IAAI,EAAE,+BAA+B,EACrC,IAAI,EAAE,+BAA+B,KAClC,IAAI,CAAC;CACX;AAED;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,OAAO,GACf,2BAA2B,CAW7B;AAeD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,gBAAgB,EAAE,EACnC,MAAM,EAAE,2BAA2B,GAAG,SAAS,EAC/C,IAAI,EAAE,+BAA+B,GACpC,wBAAwB,CAE1B"}

package/dist/pbr-pipeline.d.ts

@@ -0,0 +1,253 @@
+import type { BindGroup, BindGroupEntry, BindGroupLayout, Buffer, PipelineLayout, Result, RhiError, Sampler, TextureView } from '@forgeax/engine-rhi';
+import { type DerivedMaterialInterface } from '@forgeax/engine-types';
+export interface PbrPipelineDevice {
+    createBindGroupLayout(desc: {
+        label: string | undefined;
+        entries: readonly GPUBindGroupLayoutEntry[];
+    }): Result<BindGroupLayout, RhiError>;
+    createPipelineLayout(desc: {
+        label?: string;
+        bindGroupLayouts: readonly BindGroupLayout[];
+    }): Result<PipelineLayout, RhiError>;
+}
+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(derived?: DerivedMaterialInterface): 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 any
+ * 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).
+ * 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 any `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(3-entry), instances]`). View / material / instances BGLs are
+ * shared with the standard-PBR layout (passed in via `pbr` bundle); the only
+ * new BGL is the 3-entry mesh-array slot for `meshes` plus current and
+ * previous palettes.
+ *
+ * Throws on any `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 = "";
+/**
+ * Pick the sprite-pass variant set for the current sprite entry. Returns
+ * `''` (canonical all-true variant key, per bug-20260708 M2 (c)) when
+ * `hasSpriteInstances` is true (the extract stage has populated
+ * `RenderableSnapshot.spriteInstances`), otherwise `undefined` so the
+ * existing sprite path stays byte-identical for non-SpriteInstances callers
+ * (plan-strategy D-4 reverse-falsifier).
+ *
+ * @param hasSpriteInstances — true when the renderable carries a
+ *   `SpriteInstancesSnapshot` (extracted by render-system-extract M3 w10).
+ */
+export declare function selectSpritePassVariantSet(hasSpriteInstances: boolean): string | undefined;
+//# 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/persistent-render-scene.d.ts

@@ -0,0 +1,158 @@
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import type { RhiDevice, RhiError } from '@forgeax/engine-rhi';
+import { type BatchTopologyInspection, type SubmissionPlan } from './gpu-driven/batch-topology';
+import { GpuScene, type GpuSceneInspection } from './gpu-scene';
+import type { RenderSceneSubmissionDelta } from './render-scene-projection';
+import { RenderSceneProjection } from './render-scene-projection';
+import type { DispatchEntry, ExtractedFrame, FogSelection, FogSnapshot, RenderableSnapshot } from './render-system-extract';
+export type RenderSceneResyncReason = 'attach' | 'asset-catalog-changed' | 'shared-ref-changed' | 'journal-overflow' | 'unsupported-change' | 'non-rigid-lane' | 'explicit-invalidate';
+export type PersistentFogFailureCode = 'fog-owner-conflict' | 'fog-parameters-invalid';
+export interface PersistentFogInspection {
+    readonly enabled: boolean;
+    readonly resourceOwner: number | undefined;
+    readonly entity: number | undefined;
+    readonly revision: number | undefined;
+    readonly reactive: boolean;
+    readonly failure: PersistentFogFailureCode | undefined;
+}
+export interface PersistentFogFailure {
+    readonly code: PersistentFogFailureCode;
+    readonly resourceOwner: number;
+}
+export interface PersistentRenderSceneInspection {
+    readonly worldEntitiesScanned: number;
+    readonly fullRebuilds: number;
+    readonly noChangeFrames: number;
+    readonly deltaFrames: number;
+    readonly transformUpdates: number;
+    readonly materialUpdates: number;
+    readonly instanceUpdates: number;
+    readonly cameraUpdates: number;
+    readonly resourceUpdates: number;
+    /** Number of journal entities admitted to the local topology reconciler. */
+    readonly topologyEntitiesReconciled: number;
+    /** Number of identity-addressed production render extractions requested. */
+    readonly singleEntityExtractions: number;
+    readonly removals: number;
+    readonly lastResyncReason: RenderSceneResyncReason | undefined;
+    /** @internal M0 attribution for a rebuild that otherwise only says unsupported-change. */
+    readonly lastResyncDetail: string | undefined;
+    readonly cursor: number | undefined;
+    readonly projectionRecords: number;
+    readonly spatialIndex: import('./render-scene-projection').SpatialIndexInspection | undefined;
+    readonly topology: BatchTopologyInspection;
+    readonly gpu: {
+        readonly status: 'inactive';
+    } | {
+        readonly status: 'unsupported';
+        readonly reason: 'storage-buffer-unavailable';
+    } | ({
+        readonly status: 'resident';
+    } & GpuSceneInspection) | {
+        readonly status: 'rebuild-pending';
+    } | {
+        readonly status: 'error';
+    };
+    readonly fog: PersistentFogInspection;
+}
+export interface PersistentRenderSceneOptions {
+    readonly getDevice?: (() => RhiDevice) | undefined;
+    readonly onGpuError?: ((error: RhiError) => void) | undefined;
+    /** @internal Collect complete per-candidate CSM decisions for debug capture. */
+    readonly collectShadowDebugCandidates?: (() => boolean) | undefined;
+}
+/**
+ * Complete facts produced by the render-domain admission owner for one ECS
+ * entity. Dispatch entries use the local candidate index from that extraction;
+ * PersistentRenderScene rebases them onto its slot-owned candidate domain.
+ */
+export interface PersistentRenderableExtraction {
+    readonly snapshot: RenderableSnapshot;
+    readonly candidateDispatch: readonly DispatchEntry[];
+}
+export interface PersistentGpuDrivenState {
+    readonly scene: GpuScene;
+    readonly plan: SubmissionPlan;
+    readonly slots: readonly import('./render-scene-projection').RenderSceneProjectionSlot[];
+    /**
+     * The same projection that owns `slots` and the spatial index. Visibility
+     * must query this owner; a revision number copied into GpuScene is only
+     * diagnostic metadata and cannot select a candidate domain by itself.
+     */
+    /** Present for the production owner; optional keeps older test doubles honest. */
+    readonly projection?: RenderSceneProjection;
+}
+/** Persistent single-World rigid scene used by the renderer's ordinary path. */
+export declare class PersistentRenderScene {
+    private readonly options;
+    private readonly entries;
+    private readonly worldIds;
+    private readonly worldsById;
+    private nextWorldId;
+    private fullRebuilds;
+    private worldEntitiesScanned;
+    private noChangeFrames;
+    private deltaFrames;
+    private transformUpdates;
+    private materialUpdates;
+    private instanceUpdates;
+    private cameraUpdates;
+    private resourceUpdates;
+    private topologyEntitiesReconciled;
+    private singleEntityExtractions;
+    private removals;
+    private lastResyncReason;
+    private lastResyncDetail;
+    private lastWorld;
+    private composition;
+    private gpuScene;
+    private gpuOwner;
+    private gpuDevice;
+    private gpuStatus;
+    private fogCandidate;
+    private fogLastKnownGood;
+    private fogFailure;
+    private fogFailureOwner;
+    private fogReactive;
+    constructor(options?: PersistentRenderSceneOptions);
+    readonly worldForRenderId: (worldId: number) => World | undefined;
+    extract(world: World, catalogEpoch: number, buildCandidateFrame: () => ExtractedFrame, refreshMaterial?: (snapshot: RenderableSnapshot, materialHandle: number) => RenderableSnapshot | undefined, refreshCameras?: (frame: ExtractedFrame) => ExtractedFrame, gpuDrivenCoverageKey?: string, refreshPostProcessParams?: (frame: ExtractedFrame) => ExtractedFrame, refreshLights?: (frame: ExtractedFrame) => ExtractedFrame, refreshRenderable?: (entity: EntityHandle, currentFrame: ExtractedFrame) => PersistentRenderableExtraction | undefined): ExtractedFrame;
+    extractComposition(worlds: readonly World[], owner: {
+        readonly cameraOwner: number;
+        readonly resourceOwner: number;
+    }, catalogEpoch: number, buildCandidateFrame: () => ExtractedFrame, refreshRenderable?: (world: World, worldId: number, entity: EntityHandle, currentFrame: ExtractedFrame) => PersistentRenderableExtraction | undefined): ExtractedFrame;
+    invalidate(world?: World): void;
+    setGpuDrivenCoverage(world: World, key: string, ownsAll: boolean): void;
+    setCompositionGpuDrivenCoverage(key: string, ownsAll: boolean): void;
+    detach(world: World): void;
+    /** Drop only device-owned tables; the CPU projection remains the recovery authority. */
+    resetGpuForRecover(): void;
+    dispose(): void;
+    inspect(world?: World | undefined): PersistentRenderSceneInspection;
+    /** Stage a resource-owner Fog candidate; publication waits for submit. */
+    stageFogCandidate(candidate: FogSelection): void;
+    /** Return the accepted Fog payload for failed-candidate frame reuse. */
+    fogSnapshot(): FogSnapshot | undefined;
+    /** Retain the previous accepted Fog when extraction or validation fails. */
+    stageFogFailure(failure: PersistentFogFailure): void;
+    /** Drop an unsubmitted candidate without mutating the accepted snapshot. */
+    discardFogCandidate(): void;
+    /** Commit the staged Fog candidate at the existing successful-submit seam. */
+    stageFogSubmission(): void;
+    private inspectFog;
+    gpuDrivenState(world?: World | undefined): PersistentGpuDrivenState | undefined;
+    compositionGpuDrivenState(): PersistentGpuDrivenState | undefined;
+    temporalProjection(worlds: readonly World[]): RenderSceneProjection | undefined;
+    stageTemporalSubmission(delta: RenderSceneSubmissionDelta): void;
+    private inspectGpu;
+    private rebuild;
+    private rebuildComposition;
+    private syncGpu;
+    private syncGpuOwner;
+    private acquireGpuScene;
+    private failGpu;
+    private cameraEntities;
+    private attachWorld;
+    private remapWorldIds;
+}
+//# sourceMappingURL=persistent-render-scene.d.ts.map

package/dist/persistent-render-scene.d.ts.map

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

package/dist/pipeline/index.d.ts

@@ -0,0 +1,11 @@
+import type { VertexLayoutProjection } from '@forgeax/engine-geometry';
+import { type Result } from '@forgeax/engine-types';
+import { PipelineError } from '../pipeline-errors';
+export declare const pipelineStages: readonly ["extract", "prepare", "record"];
+export type PipelineStage = (typeof pipelineStages)[number];
+/**
+ * Compose the renderer-owned vertex-color axis from geometry projection facts.
+ * Authored material definitions never participate in this decision.
+ */
+export declare function variantSetFromVertexLayoutProjection(projection: VertexLayoutProjection | undefined, variantSet: string | undefined): Result<string | undefined, PipelineError>;
+//# sourceMappingURL=index.d.ts.map

package/dist/pipeline/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pipeline/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,eAAO,MAAM,cAAc,2CAA4C,CAAC;AACxE,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D;;;GAGG;AACH,wBAAgB,oCAAoC,CAClD,UAAU,EAAE,sBAAsB,GAAG,SAAS,EAC9C,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,CAAC,MAAM,GAAG,SAAS,EAAE,aAAa,CAAC,CAyB3C"}

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, type PassKind, type 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 `ShaderRegistryDevice.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 `ShaderRegistry.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,EACnB,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,EAEL,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACb,KAAK,iBAAiB,EACvB,MAAM,uBAAuB,CAAC;AAO/B;;;;;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,CAuLlC"}