@forgeax/engine-render 0.1.2

package/dist/gpu-resource-store.d.ts.map

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

package/dist/gpu-resource.d.ts

@@ -0,0 +1,73 @@
+import type { Buffer, Result, RhiDevice, RhiError, Texture } from '@forgeax/engine-rhi';
+/**
+ * Runtime wrapper around an RHI `Buffer` opaque handle that exposes
+ * an explicit `.destroy()` lifecycle.
+ *
+ * Holds the device by reference (no clone); the device's own lifetime
+ * outlives the buffer. After `.destroy()` returns ok, `isDestroyed`
+ * flips to true; a second `.destroy()` returns err code
+ * `'destroy-after-destroy'` forwarded from `device.destroyBuffer(...)`.
+ *
+ * @example
+ *   import { GpuBuffer } from '@forgeax/engine-render/internal';
+ *   const created = device.createBuffer({ size: 64, usage: GPUBufferUsage.STORAGE });
+ *   if (!created.ok) return;
+ *   const gpuBuf = new GpuBuffer(device, created.value);
+ *   // ... use gpuBuf.handle in RHI calls ...
+ *   const r = gpuBuf.destroy();
+ *   if (!r.ok) {
+ *     // r.error.code is one of the RhiErrorCode union members,
+ *     // typically 'destroy-after-destroy' on a stale handle.
+ *   }
+ */
+export declare class GpuBuffer {
+    readonly device: RhiDevice;
+    readonly handle: Buffer;
+    private destroyed;
+    constructor(device: RhiDevice, handle: Buffer);
+    get isDestroyed(): boolean;
+    /**
+     * Destroy the underlying GPU buffer. Forwards to
+     * `device.destroyBuffer(handle)`; on ok flips `isDestroyed` to true,
+     * on err leaves the flag unchanged so a downstream second destroy
+     * still surfaces the underlying RHI fail-fast.
+     */
+    destroy(): Result<void, RhiError>;
+}
+/**
+ * Runtime wrapper around an RHI `Texture` opaque handle that exposes
+ * an explicit `.destroy()` lifecycle. Mirrors `GpuBuffer` exactly --
+ * the only difference is the underlying RHI surface
+ * (`device.destroyTexture` instead of `device.destroyBuffer`) and the
+ * handle brand. Same SSOT rationale: the destroyed bookkeeping lives
+ * on the RHI shim's TEXTURE_META_MAP; the local flag is a derived view.
+ *
+ * @example
+ *   import { GpuTexture } from '@forgeax/engine-render/internal';
+ *   const r = device.createTexture({ size: [w, h, 1], format: 'rgba8unorm', usage: ... });
+ *   if (!r.ok) return;
+ *   const gpuTex = new GpuTexture(device, r.value);
+ *   // ... use gpuTex.handle in RHI calls ...
+ *   gpuTex.destroy();
+ */
+export declare class GpuTexture {
+    readonly device: RhiDevice;
+    readonly handle: Texture;
+    private destroyed;
+    constructor(device: RhiDevice, handle: Texture);
+    get isDestroyed(): boolean;
+    /**
+     * Destroy the underlying GPU texture. Forwards to
+     * `device.destroyTexture(handle)`; ok branch sets `isDestroyed=true`.
+     */
+    destroy(): Result<void, RhiError>;
+}
+/**
+ * Union of runtime-managed GPU resources requiring explicit
+ * `.destroy()`. AI-user-facing code that needs to dispose "any GPU
+ * resource" types its parameter as `GpuResource` and lets TS narrow
+ * via `instanceof GpuBuffer / GpuTexture` if branch-specific access
+ * is required. Charter F1 single-entry indexability.
+ */
+export type GpuResource = GpuBuffer | GpuTexture;
+//# sourceMappingURL=gpu-resource.d.ts.map

package/dist/gpu-resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-resource.d.ts","sourceRoot":"","sources":["../src/gpu-resource.ts"],"names":[],"mappings":"AAqDA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAExF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,SAAS;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAIxB,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM;IAK7C,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;;;OAKG;IACH,OAAO,IAAI,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC;CAOlC;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAU;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO;IAK9C,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;OAGG;IACH,OAAO,IAAI,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC;CAOlC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC"}

package/dist/gpu-scene-schema.d.ts

@@ -0,0 +1,171 @@
+export type GpuSceneScalar = 'u32' | 'i32' | 'f32';
+/**
+ * Renderer-owned mobility fact. `unknown` is intentional: a renderer must not
+ * infer staticness from how often an entity happened to move in one frame.
+ * Authoring/pack producers may provide the other two values explicitly.
+ */
+export type SceneMobility = 'static' | 'dynamic' | 'unknown';
+/**
+ * Explicit shadow-caster eligibility. `unknown` is not an eligible state; it
+ * keeps missing authoring/pack data visible to the later visibility owner.
+ */
+export type SceneCasterEligibility = 'eligible' | 'ineligible' | 'unknown';
+export type SceneFactRevisionDomain = 'transform' | 'geometry' | 'material' | 'eligibility' | 'space' | 'batch' | 'resource';
+export interface SceneFactRevisions {
+    readonly transform: number;
+    readonly geometry: number;
+    readonly material: number;
+    readonly eligibility: number;
+    readonly space: number;
+    readonly batch: number;
+    readonly resource: number;
+}
+/** Optional producer-owned facts carried by a RenderableSnapshot. */
+export interface RenderSceneFactInput {
+    readonly mobility?: SceneMobility;
+    readonly casterEligibility?: SceneCasterEligibility;
+    readonly revisions?: Partial<SceneFactRevisions>;
+}
+export type SceneBoundsFact = {
+    readonly status: 'present';
+    /** [minX, minY, minZ, maxX, maxY, maxZ] in world space. */
+    readonly worldAabb: Float32Array;
+    /** [minX, minY, minZ, maxX, maxY, maxZ] in local space. */
+    readonly localAabb: Float32Array;
+} | {
+    readonly status: 'missing';
+    readonly reason: 'missing-local-aabb' | 'invalid-local-aabb' | 'invalid-world-transform';
+};
+export interface RenderSceneFact {
+    readonly slot: number;
+    readonly generation: number;
+    readonly worldId: number;
+    readonly entityKey: number;
+    readonly bounds: SceneBoundsFact;
+    readonly mobility: SceneMobility;
+    readonly casterEligibility: SceneCasterEligibility;
+    readonly revisions: SceneFactRevisions;
+}
+export type SceneFactDiagnosticCode = 'missing-bounds' | 'invalid-revision' | 'stale-generation';
+export interface SceneFactDiagnostic {
+    readonly code: SceneFactDiagnosticCode;
+    readonly slot?: number;
+    readonly generation?: number;
+    readonly worldId?: number;
+    readonly entityKey?: number;
+    readonly expectedGeneration?: number;
+    readonly actualGeneration?: number;
+    readonly domain?: SceneFactRevisionDomain;
+    readonly reason?: string;
+}
+/** Stable primitive flag bits; the extra fact bits do not change the table ABI. */
+export declare const GPU_SCENE_PRIMITIVE_FLAGS: Readonly<{
+    active: 1;
+    hasBounds: 2;
+    gpuDriven: 4;
+    static: 8;
+    dynamic: 16;
+    casterEligible: 32;
+    casterIneligible: 64;
+    casterUnknown: 128;
+}>;
+declare const TYPE_LAYOUT: {
+    u32: {
+        size: number;
+        alignment: number;
+    };
+    i32: {
+        size: number;
+        alignment: number;
+    };
+    f32: {
+        size: number;
+        alignment: number;
+    };
+    'vec4<f32>': {
+        size: number;
+        alignment: number;
+    };
+    'mat4x4<f32>': {
+        size: number;
+        alignment: number;
+    };
+};
+export type GpuSceneFieldType = keyof typeof TYPE_LAYOUT;
+export interface GpuSceneField {
+    readonly name: string;
+    readonly type: GpuSceneFieldType;
+}
+export interface GpuSceneTableSchema {
+    readonly name: string;
+    readonly fields: readonly GpuSceneField[];
+}
+export interface GpuSceneFieldLayout extends GpuSceneField {
+    readonly offset: number;
+    readonly size: number;
+    readonly alignment: number;
+}
+export interface GpuSceneTableLayout {
+    readonly name: string;
+    readonly stride: number;
+    readonly fields: readonly GpuSceneFieldLayout[];
+}
+export declare function deriveGpuSceneTableLayout(schema: GpuSceneTableSchema): GpuSceneTableLayout;
+export declare function gpuSceneFieldOffset(layout: GpuSceneTableLayout, name: string): number;
+export declare function gpuSceneWgsl(layout: GpuSceneTableLayout): string;
+export declare const GPU_SCENE_SCHEMAS: Readonly<{
+    primitive: {
+        name: string;
+        fields: ({
+            name: string;
+            type: "u32";
+        } | {
+            name: string;
+            type: "vec4<f32>";
+        })[];
+    };
+    instance: {
+        name: string;
+        fields: {
+            name: string;
+            type: "u32";
+        }[];
+    };
+    transform: {
+        name: string;
+        fields: {
+            name: string;
+            type: "mat4x4<f32>";
+        }[];
+    };
+    drawTemplate: {
+        name: string;
+        fields: ({
+            name: string;
+            type: "u32";
+        } | {
+            name: string;
+            type: "i32";
+        })[];
+    };
+    material: {
+        name: string;
+        fields: ({
+            name: string;
+            type: "vec4<f32>";
+        } | {
+            name: string;
+            type: "u32";
+        })[];
+    };
+}>;
+export declare const GPU_SCENE_LAYOUTS: Readonly<{
+    readonly primitive: GpuSceneTableLayout;
+    readonly instance: GpuSceneTableLayout;
+    readonly transform: GpuSceneTableLayout;
+    readonly drawTemplate: GpuSceneTableLayout;
+    readonly material: GpuSceneTableLayout;
+}>;
+export declare const GPU_SCENE_WGSL: string;
+export {};
+//# sourceMappingURL=gpu-scene-schema.d.ts.map

package/dist/gpu-scene-schema.d.ts.map

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

package/dist/gpu-scene.d.ts

@@ -0,0 +1,81 @@
+import type { Buffer, Result, RhiDevice, RhiError } from '@forgeax/engine-rhi';
+import type { RenderSceneApplyResult, RenderSceneProjection, RenderSceneSubmissionDelta, SpatialIndexInspection } from './render-scene-projection';
+interface GpuSceneBuffers {
+    readonly primitive: Buffer;
+    readonly instance: Buffer;
+    readonly transform: Buffer;
+    readonly drawTemplate: Buffer;
+    readonly material: Buffer;
+}
+type GpuSceneTableName = keyof GpuSceneBuffers;
+export interface GpuSceneTableInspection {
+    readonly capacity: number;
+    readonly bytes: number;
+}
+export interface GpuSceneInspection {
+    readonly capacity: number;
+    readonly tables: Readonly<Record<GpuSceneTableName, GpuSceneTableInspection>>;
+    readonly uploadRanges: number;
+    readonly uploadBytes: number;
+    readonly capacityGrows: number;
+    readonly fullRebuilds: number;
+    readonly clearedSlots: number;
+    readonly noChangeFrames: number;
+    /** Mirrored CPU broadphase evidence; RenderSceneProjection remains the owner. */
+    readonly spatialIndex: SpatialIndexInspection | undefined;
+}
+export interface GpuSceneSyncResult {
+    readonly ranges: number;
+    readonly bytes: number;
+    readonly grew: boolean;
+    readonly cleared: number;
+}
+export type GpuSceneAvailability = {
+    readonly status: 'available';
+    readonly scene: GpuScene;
+} | {
+    readonly status: 'unavailable';
+    readonly reason: 'storage-buffer-unavailable';
+};
+/** Persistent GPU tables derived only from renderer projection slots. */
+export declare class GpuScene {
+    private readonly device;
+    private capacity;
+    private tableBytes;
+    private buffers;
+    private uploadRanges;
+    private uploadBytes;
+    private capacityGrows;
+    private fullRebuilds;
+    private clearedSlots;
+    private noChangeFrames;
+    private readonly allocations;
+    private readonly instances;
+    private readonly transforms;
+    private readonly draws;
+    private readonly materials;
+    private readonly pendingSubmittedSlots;
+    private spatialIndex;
+    private constructor();
+    static create(device: RhiDevice, initialCapacity?: number): Result<GpuSceneAvailability, RhiError>;
+    get primitiveBuffer(): Buffer;
+    get instanceBuffer(): Buffer;
+    get transformBuffer(): Buffer;
+    get drawTemplateBuffer(): Buffer;
+    get materialBuffer(): Buffer;
+    sync(projection: RenderSceneProjection, delta: RenderSceneApplyResult): Result<GpuSceneSyncResult, RhiError>;
+    rebuild(projection: RenderSceneProjection): Result<GpuSceneSyncResult, RhiError>;
+    inspect(): GpuSceneInspection;
+    dispose(): void;
+    stageSubmitted(delta: RenderSceneSubmissionDelta): void;
+    private writeSlot;
+    private writePreviousTransforms;
+    private clearSlot;
+    private uploadRows;
+    private ensureAllocation;
+    private clearAllocation;
+    private grow;
+    private allocateCpuTables;
+}
+export {};
+//# sourceMappingURL=gpu-scene.d.ts.map

package/dist/gpu-scene.d.ts.map

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

package/dist/gpu-stage.d.ts

@@ -0,0 +1,4 @@
+export declare const GPU_SHADER_STAGE_VERTEX = 1;
+export declare const GPU_SHADER_STAGE_FRAGMENT = 2;
+export declare const GPU_SHADER_STAGE_COMPUTE = 4;
+//# sourceMappingURL=gpu-stage.d.ts.map

package/dist/gpu-stage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-stage.d.ts","sourceRoot":"","sources":["../src/gpu-stage.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,uBAAuB,IAAM,CAAC;AAC3C,eAAO,MAAM,yBAAyB,IAAM,CAAC;AAC7C,eAAO,MAAM,wBAAwB,IAAM,CAAC"}

package/dist/gpu-texture-usage.d.ts

@@ -0,0 +1,6 @@
+export declare const GPU_TEXTURE_USAGE_COPY_SRC = 1;
+export declare const GPU_TEXTURE_USAGE_COPY_DST = 2;
+export declare const GPU_TEXTURE_USAGE_TEXTURE_BINDING = 4;
+export declare const GPU_TEXTURE_USAGE_RENDER_ATTACHMENT = 16;
+export declare const GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING: number;
+//# sourceMappingURL=gpu-texture-usage.d.ts.map

package/dist/gpu-texture-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-texture-usage.d.ts","sourceRoot":"","sources":["../src/gpu-texture-usage.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,0BAA0B,IAAO,CAAC;AAC/C,eAAO,MAAM,0BAA0B,IAAO,CAAC;AAC/C,eAAO,MAAM,iCAAiC,IAAO,CAAC;AACtD,eAAO,MAAM,mCAAmC,KAAO,CAAC;AACxD,eAAO,MAAM,uDAAuD,QACK,CAAC"}

package/dist/gpu-usage.d.ts

@@ -0,0 +1,9 @@
+export declare const GPU_BUFFER_USAGE_VERTEX = 32;
+export declare const GPU_BUFFER_USAGE_INDEX = 16;
+export declare const GPU_BUFFER_USAGE_COPY_DST = 8;
+export declare const GPU_BUFFER_USAGE_COPY_SRC = 4;
+export declare const GPU_BUFFER_USAGE_UNIFORM = 64;
+export declare const GPU_BUFFER_USAGE_STORAGE = 128;
+export declare const GPU_BUFFER_USAGE_INDIRECT = 256;
+export declare const GPU_BUFFER_USAGE_MAP_READ = 1;
+//# sourceMappingURL=gpu-usage.d.ts.map

package/dist/gpu-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-usage.d.ts","sourceRoot":"","sources":["../src/gpu-usage.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,uBAAuB,KAAO,CAAC;AAC5C,eAAO,MAAM,sBAAsB,KAAO,CAAC;AAC3C,eAAO,MAAM,yBAAyB,IAAO,CAAC;AAC9C,eAAO,MAAM,yBAAyB,IAAO,CAAC;AAC9C,eAAO,MAAM,wBAAwB,KAAO,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAO,CAAC;AAC7C,eAAO,MAAM,yBAAyB,MAAQ,CAAC;AAC/C,eAAO,MAAM,yBAAyB,IAAO,CAAC"}

package/dist/hdrp-buffers.d.ts

@@ -0,0 +1,213 @@
+import { type BindGroup, type BindGroupLayout, type BindGroupLayoutDescriptor, type Buffer, RhiError, type Sampler, type Texture, type TextureView } from '@forgeax/engine-rhi';
+import type { RenderSystemRuntime } from './render-system';
+/**
+ * WebGL2 HDRP downlevel light-list capacity. 128 x 64 B = 8 KiB, below the
+ * WebGL2 minimum uniform-buffer binding size of 16 KiB. The storage path
+ * keeps the full MAX_LIGHTS budget; the uniform path uses the same LightSlot
+ * POD and only changes the transport.
+ */
+export declare const HDRP_UNIFORM_LIGHT_CAPACITY = 128;
+/**
+ * Build the unified BGL descriptor for HDRP group(2). Round-2 (M7) extends
+ * the original 5-entry layout (binding 0 + 3..6) with 2 SSAO-specific slots
+ * at binding 7..8, giving 7 total entries.
+ *
+ * Entries:
+ *   binding 0 — mesh SSBO (vertex stage, dynamic offset)
+ *   binding 1 — absent (URP isolation gap)
+ *   binding 2 — absent (URP isolation gap)
+ *   binding 3 — light_data SSBO (fragment stage)
+ *   binding 4 — cluster_grid SSBO (fragment stage)
+ *   binding 5 — light_index_list SSBO (fragment stage)
+ *   binding 6 — cluster_uniform UBO (fragment stage; .near_far_log.w
+ *               carries SSAO intensity — scope-amend-webgl2-ubo fold)
+ *   binding 7 — ssaoBlurred texture_2d<f32> (fragment stage; plan D-B)
+ *   binding 8 — ssaoSampler (fragment stage; plan D-B)
+ *
+ * Single PSO, dual behavior: when SSAO is disabled the bind group at
+ * binding 7 binds a 1x1 white fallback texture (AO = 1.0) and the host
+ * writes intensity=0 into cluster_uniform.near_far_log.w, so the lighting
+ * blend `mix(1.0, ssao*ao, 0) = 1.0` collapses to the round-1 baseline
+ * (plan-strategy §D-B; charter P4 one consistent abstraction). Material
+ * PSOs never recompile across enable / disable.
+ *
+ * scope-amend-webgl2-ubo: a dedicated intensity UBO would push
+ * fragment-stage UBO count to 12, exceeding WebGL2's
+ * `max_uniform_buffers_per_shader_stage = 11` budget on rhi-wgpu's
+ * fallback path. Folding intensity into the existing cluster UBO pad
+ * lane keeps the count at 11.
+ *
+ * When `storageBuffer=false` (no storage-buffer caps), bindings 0,3,4,5 fall
+ * back to 'uniform' (same pattern as `buildPbrViewBglEntries` in pbr-pipeline.ts).
+ *
+ * Exported for unit-test access.
+ */
+export declare function createHdrpBindGroupLayoutDescriptor(storageBuffer?: boolean): BindGroupLayoutDescriptor;
+/** Bind-group layout used only by the WebGPU cluster membership producer. */
+export declare function createHdrpClusterMembershipBindGroupLayoutDescriptor(): BindGroupLayoutDescriptor;
+interface SsaoFallbackResources {
+    readonly texture: Texture;
+    readonly view: TextureView;
+    readonly sampler: Sampler;
+}
+/**
+ * Lazily allocate the 1x1 r8unorm white fallback texture + a sampler for
+ * SSAO disabled / resource-missing path. Cached per RenderSystemRuntime so
+ * subsequent calls reuse the same resources (charter P5 one-owner).
+ *
+ * Returns `null` if `device.createTexture` / `createTextureView` /
+ * `createSampler` / `queue.writeTexture` fails; the caller (createBindGroup)
+ * propagates the structured RhiError that landed on `runtime.errorRegistry`.
+ */
+export declare function getOrCreateSsaoFallbackTexture(runtime: RenderSystemRuntime): SsaoFallbackResources | null;
+/**
+ * The persistent HDRP GPU buffers (plan D-1, BGL slot 3..6) plus the unified
+ * BGL layout for group(2) (plan D-6, feat-20260609-hdrp-cluster-fragment-ggx M3).
+ *
+ * AC-11: light_data stride = `BYTES_PER_LIGHT_SLOT` = 64 (double-sided lock with
+ * WGSL hdrp-cluster-forward.wgsl LightSlot).
+ * AC-13: 4 distinct RHI Buffer handles, ready for slot-3..6 BGL binding.
+ * AC-14: clusterUniform is a uniform buffer (not storage); runtime grid change
+ * is a writeBuffer field update, not a PSO rebuild.
+ * AC-06: unifiedBindGroupLayout is the 7-entry group(2) BGL (mesh SSBO +
+ * cluster 4 buffer).
+ */
+export interface HdrpBuffers {
+    /** Whether bindings 3..5 carry storage buffers or uniform-buffer fallback data. */
+    readonly storageBuffer: boolean;
+    /** light_data -- 256 x 64 B on storage, 128 x 64 B on uniform fallback. */
+    readonly lightDataBuffer: Buffer;
+    readonly lightDataBytes: number;
+    /** cluster_grid SSBO -- gridX*gridY*gridZ * 2 u32, BGL slot 4. */
+    readonly clusterGridBuffer: Buffer;
+    readonly clusterGridBytes: number;
+    /** light_index_list SSBO -- 65536 u32 = 256 KiB, BGL slot 5. */
+    readonly lightIndexListBuffer: Buffer;
+    readonly lightIndexListBytes: number;
+    /** cluster_uniform UBO -- 32 B (2 vec4 std140), BGL slot 6. */
+    readonly clusterUniformBuffer: Buffer;
+    readonly clusterUniformBytes: number;
+    /** CPU-produced light AABBs consumed by the optional WebGPU membership pass. */
+    readonly lightBoundsBuffer: Buffer;
+    readonly lightBoundsBytes: number;
+    /** The grid the buffers were sized for; cluster_grid is sized by gridX*gridY*gridZ. */
+    readonly grid: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    };
+    /** Unified BGL layout for group(2). */
+    readonly unifiedBindGroupLayout: BindGroupLayout;
+}
+/**
+ * Lazily allocate the 4 persistent HDRP buffers for `runtime`. Returns the same
+ * `HdrpBuffers` object on subsequent calls (per-RenderSystem stable identity).
+ *
+ * On `device.createBuffer` failure, fires a structured RhiError on the runtime's
+ * error registry and returns `null`; HDRP buildGraph treats null as a hard
+ * pipeline disable (charter P3 explicit failure).
+ *
+ * `grid` defaults to `DEFAULT_CLUSTER_GRID` when undefined (matches the M5
+ * record-stage default). The buffers are sized at the *first* call's grid; a
+ * later install with a different grid keeps the existing allocation as long as
+ * it has enough capacity (gridX*gridY*gridZ <= cached.grid product). Different
+ * grids that exceed capacity are not currently re-allocated -- M-future.
+ */
+export declare function getOrCreateHdrpBuffers(runtime: RenderSystemRuntime, grid?: {
+    x: number;
+    y: number;
+    z: number;
+}): HdrpBuffers | null;
+/**
+ * Build the 8-float cluster_uniform std140 payload.
+ *
+ *   [0] gridX  u32 (cast in shader)
+ *   [1] gridY  u32
+ *   [2] gridZ  u32
+ *   [3] lightCount u32 (vec4 alignment; capped by the active transport)
+ *   [4] near   f32
+ *   [5] far    f32
+ *   [6] logFarOverNear  f32
+ *   [7] ssaoIntensity   f32   (scope-amend-webgl2-ubo: folded from removed
+ *                              dedicated @binding(9) UBO; lighting shader
+ *                              reads `cluster_uniform.near_far_log.w`)
+ *
+ * Matches `__tests__/hdrp-bgl-slots.test.ts CLUSTER_UNIFORM_LAYOUT`.
+ *
+ * Note: u32 values written into a Float32Array view are bit-pattern correct
+ * because writeBuffer copies raw bytes; the WGSL `var<uniform>` declares the
+ * field as u32 / f32 per its position so the device reinterprets correctly.
+ * Use a Uint32Array view for the integer slots to keep the bit pattern intact.
+ */
+export declare function packClusterUniform(grid: {
+    x: number;
+    y: number;
+    z: number;
+}, near: number, far: number, ssaoIntensity?: number, lightCount?: number, lightCapacity?: number): ArrayBuffer;
+/**
+ * Consumers pass the same mesh storage buffer + stride that URP uses, so the
+ * dynamic offset (`i * MESH_PER_ENTITY_STRIDE`) at `setBindGroup(2, ...)`
+ * stays valid across both pipelines.
+ */
+/**
+ * Build the unified group(2) BindGroup for HDRP — binding 0 = mesh SSBO
+ * (dynamic offset, same buffer URP binds), bindings 3..6 = the cluster
+ * buffers from `getOrCreateHdrpBuffers`.
+ *
+ * feat-20260609-hdrp-cluster-fragment-ggx M4 / w19. Called per-frame from the
+ * recordFrame HDRP block after binner+writeBuffer; the resulting BindGroup
+ * lands on `passCtx.hdrpClusterBindGroup` and recordMainPass binds it at
+ * group(2) when `frameState.isHdrpActive`.
+ *
+ * Returns `null` on `device.createBindGroup` failure (a structured RhiError
+ * is fired on `runtime.errorRegistry`); recordMainPass gracefully falls back
+ * to the URP mesh bindGroup when null.
+ *
+ * Plan D-1 / D-4: the mesh SSBO buffer + stride mirror the URP path, so the
+ * single dynamic offset issued at `setBindGroup(2, ...)` covers binding 0 of
+ * the unified BGL just as it covers binding 0 of the URP mesh BGL.
+ */
+/**
+ * SSAO bind-group input (plan-strategy §D-B, M7;
+ * scope-amend-webgl2-ubo: dedicated @binding(9) intensity UBO removed).
+ *
+ * The HDRP unified BGL always declares 7 entries (cluster 5 + ssao 2); the
+ * caller supplies one of two shapes depending on `config.ssao?.enabled`:
+ *
+ *   { enabled: true, ssaoBlurredView }
+ *     -> binding 7 = real ssaoBlurred view
+ *     -> binding 8 = real ssao sampler (lazy-allocated alongside fallback)
+ *
+ *   { enabled: false }
+ *     -> binding 7 = 1x1 white fallback texture (AO = 1.0)
+ *     -> binding 8 = fallback sampler
+ *
+ * Intensity flows via `cluster_uniform.near_far_log.w` (binding 6); the host
+ * writes intensity=0 when SSAO is disabled so the lighting blend
+ * `mix(1.0, ssao*ao, 0) = 1.0` collapses to the round-1 baseline. The
+ * "always-7-entries" invariant lets every PBR PSO use the same pipeline
+ * layout regardless of SSAO state — toggling the runtime config never
+ * triggers shader recompile (charter P4 one consistent abstraction).
+ *
+ * `ssaoBuffers` is no longer carried in the enabled variant: the SSAO
+ * compute-side UBO continues to live on the SSAO compute pipeline's own
+ * group(0) BGL, decoupled from the lighting-stage group(2).
+ */
+export type SsaoBindOptions = {
+    readonly enabled: true;
+    readonly ssaoBlurredView: TextureView;
+} | {
+    readonly enabled: false;
+};
+export declare function createHdrpUnifiedBindGroup(runtime: RenderSystemRuntime, hdrpBuffers: HdrpBuffers, meshStorageBuffer: Buffer, ssaoOptions?: SsaoBindOptions): BindGroup | null;
+/**
+ * Build the compute-only bind group for ordered cluster membership output.
+ * Its group is intentionally separate from the fragment group: the same
+ * light-index buffer is read-only in the fragment pipeline but read-write in
+ * the producer pipeline, which WebGPU represents with different binding
+ * types.
+ */
+export declare function createHdrpClusterMembershipBindGroup(runtime: RenderSystemRuntime, hdrpBuffers: HdrpBuffers, layout: BindGroupLayout): BindGroup | null;
+/** Sentinel error class re-export for tests asserting the error path. */
+export { RhiError as HdrpBufferAllocError };
+//# sourceMappingURL=hdrp-buffers.d.ts.map

package/dist/hdrp-buffers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hdrp-buffers.d.ts","sourceRoot":"","sources":["../src/hdrp-buffers.ts"],"names":[],"mappings":"AAkCA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC9B,KAAK,MAAM,EACX,QAAQ,EACR,KAAK,OAAO,EACZ,KAAK,OAAO,EACZ,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAC;AAsB7B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAa3D;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,mCAAmC,CACjD,aAAa,GAAE,OAAc,GAC5B,yBAAyB,CA4C3B;AAED,6EAA6E;AAC7E,wBAAgB,oDAAoD,IAAI,yBAAyB,CA0BhG;AAYD,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAID;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,mBAAmB,GAC3B,qBAAqB,GAAG,IAAI,CAyE9B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,kEAAkE;IAClE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,gEAAgE;IAChE,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,+DAA+D;IAC/D,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,gFAAgF;IAChF,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9E,uCAAuC;IACvC,QAAQ,CAAC,sBAAsB,EAAE,eAAe,CAAC;CAClD;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,mBAAmB,EAC5B,IAAI,GAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAyB,GAC/D,WAAW,GAAG,IAAI,CA+GpB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EACzC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,aAAa,GAAE,MAAU,EACzB,UAAU,GAAE,MAAU,EACtB,aAAa,GAAE,MAAoC,GAClD,WAAW,CAgBb;AAED;;;;GAIG;AACH;;;;;;;;;;;;;;;;;GAiBG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,eAAe,GACvB;IACE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC;CACvC,GACD;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAA;CAAE,CAAC;AAEhC,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,mBAAmB,EAC5B,WAAW,EAAE,WAAW,EACxB,iBAAiB,EAAE,MAAM,EACzB,WAAW,GAAE,eAAoC,GAChD,SAAS,GAAG,IAAI,CAmElB;AAED;;;;;;GAMG;AACH,wBAAgB,oCAAoC,CAClD,OAAO,EAAE,mBAAmB,EAC5B,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,eAAe,GACtB,SAAS,GAAG,IAAI,CA4BlB;AAED,yEAAyE;AACzE,OAAO,EAAE,QAAQ,IAAI,oBAAoB,EAAE,CAAC"}

package/dist/hdrp-cluster-membership.d.ts

@@ -0,0 +1,2 @@
+export declare const HDRP_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";
+//# sourceMappingURL=hdrp-cluster-membership.d.ts.map

package/dist/hdrp-cluster-membership.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hdrp-cluster-membership.d.ts","sourceRoot":"","sources":["../src/hdrp-cluster-membership.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,4BAA4B,ykEA6DxC,CAAC"}

package/dist/hdrp-pipeline.d.ts

@@ -0,0 +1,36 @@
+import { type Result } from '@forgeax/engine-types';
+import type { RenderPipeline } from './render-pipeline';
+export declare const HDRP_PIPELINE_ID = "forgeax::hdrp";
+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 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 declare function isGpuMembershipProducerAvailable(caps: {
+    readonly compute?: boolean;
+} | null | undefined, pipeline: unknown, bindGroup: unknown): boolean;
+export declare const hdrpPipeline: RenderPipeline;
+//# sourceMappingURL=hdrp-pipeline.d.ts.map