@forgeax/engine-render 0.1.2

package/dist/record/membership-timing.d.ts

@@ -0,0 +1,232 @@
+import type { Buffer, CommandBuffer, ComputePassDescriptor, Result, RhiCommandEncoder, RhiDevice } from '@forgeax/engine-rhi';
+export declare const MEMBERSHIP_TIMING_REASON_CODES: readonly ["invalid-options", "timestamp-query-unsupported", "timestamp-period-unavailable", "timestamp-write-unavailable", "capture-capacity-exhausted", "capture-already-active", "queue-submit-failed", "queue-completion-failed", "readback-map-failed", "capture-timeout", "device-lost", "stale-device-generation", "capture-disposed", "timestamp-range-invalid", "profile-incomplete", "provenance-missing", "provenance-mismatch", "reference-missing", "reference-reused", "reference-cross-parent", "membership-output-mismatch", "pixel-output-mismatch", "terminal-record-incomplete"];
+export type MembershipTimingReasonCode = (typeof MEMBERSHIP_TIMING_REASON_CODES)[number];
+export declare const MEMBERSHIP_TIMING_REASON_MAPPING: {
+    readonly 'invalid-options': {
+        readonly api: "refused";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+    readonly 'timestamp-query-unsupported': {
+        readonly api: "refused";
+        readonly topLevel: "refused";
+        readonly reference: "refused";
+    };
+    readonly 'timestamp-period-unavailable': {
+        readonly api: "refused";
+        readonly topLevel: "refused";
+        readonly reference: "refused";
+    };
+    readonly 'timestamp-write-unavailable': {
+        readonly api: "terminal";
+        readonly topLevel: "refused";
+        readonly reference: "refused";
+    };
+    readonly 'capture-capacity-exhausted': {
+        readonly api: "refused";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+    readonly 'capture-already-active': {
+        readonly api: "refused";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+    readonly 'queue-submit-failed': {
+        readonly api: "terminal";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+    readonly 'queue-completion-failed': {
+        readonly api: "terminal";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+    readonly 'readback-map-failed': {
+        readonly api: "terminal";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+    readonly 'capture-timeout': {
+        readonly api: "terminal";
+        readonly topLevel: "timed-out";
+        readonly reference: "timed-out";
+    };
+    readonly 'device-lost': {
+        readonly api: "terminal";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+    readonly 'stale-device-generation': {
+        readonly api: "terminal";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+    readonly 'capture-disposed': {
+        readonly api: "terminal";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+    readonly 'timestamp-range-invalid': {
+        readonly api: "terminal";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+    readonly 'profile-incomplete': {
+        readonly api: "terminal";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+    readonly 'provenance-missing': {
+        readonly api: "terminal";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+    readonly 'provenance-mismatch': {
+        readonly api: "terminal";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+    readonly 'reference-missing': {
+        readonly api: "terminal";
+        readonly topLevel: "incomplete";
+        readonly reference: "none";
+    };
+    readonly 'reference-reused': {
+        readonly api: "terminal";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+    readonly 'reference-cross-parent': {
+        readonly api: "terminal";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+    readonly 'membership-output-mismatch': {
+        readonly api: "terminal";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+    readonly 'pixel-output-mismatch': {
+        readonly api: "terminal";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+    readonly 'terminal-record-incomplete': {
+        readonly api: "terminal";
+        readonly topLevel: "incomplete";
+        readonly reference: "incomplete";
+    };
+};
+export declare const MEMBERSHIP_TIMING_REASON_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://forgeax.dev/schemas/render/membership-timing-reason-code.schema.json";
+    readonly title: "ForgeaX Render membership timing reason code";
+    readonly type: "string";
+    readonly enum: readonly ["invalid-options", "timestamp-query-unsupported", "timestamp-period-unavailable", "timestamp-write-unavailable", "capture-capacity-exhausted", "capture-already-active", "queue-submit-failed", "queue-completion-failed", "readback-map-failed", "capture-timeout", "device-lost", "stale-device-generation", "capture-disposed", "timestamp-range-invalid", "profile-incomplete", "provenance-missing", "provenance-mismatch", "reference-missing", "reference-reused", "reference-cross-parent", "membership-output-mismatch", "pixel-output-mismatch", "terminal-record-incomplete"];
+};
+/** Canonical membership facts projected by the Render HDRP producer. */
+export interface MembershipTimingMembershipOutput {
+    readonly schemaVersion: 1;
+    readonly lightCount: number;
+    readonly grid: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    };
+    readonly clusterOffsetsAndCounts: readonly number[];
+    readonly attemptedTotal: number;
+    readonly writtenTotal: number;
+    readonly capacity: number;
+    readonly overflow: boolean;
+    readonly lightIndexPrefix: readonly number[];
+}
+/** Actual device buffers consumed/written by hdrp-cluster-membership. */
+export interface MembershipTimingGpuOutputSource {
+    readonly clusterGridBuffer: Buffer;
+    readonly clusterGridBytes: number;
+    readonly lightIndexListBuffer: Buffer;
+    readonly lightIndexListBytes: number;
+    readonly lightCount: number;
+    readonly grid: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    };
+    readonly attemptedTotal: number;
+    readonly writtenTotal: number;
+    readonly capacity: number;
+    readonly overflow: boolean;
+}
+export type MembershipTimingOptions = {
+    readonly mode: 'gpu';
+    readonly maxPendingCaptures?: number;
+} | {
+    readonly mode: 'cpu-control';
+};
+export type MembershipTimingGpuReport = {
+    readonly rawUnit: 'ticks';
+    readonly rawBeginTick: string;
+    readonly rawEndTick: string;
+    readonly deltaTicks: string;
+    readonly timestampPeriodNanoseconds: number;
+    readonly durationNanoseconds: number;
+};
+export interface MembershipTimingInterval {
+    readonly startNanoseconds: number;
+    readonly endNanoseconds: number;
+    readonly durationNanoseconds: number;
+}
+export interface MembershipTimingReport {
+    readonly captureId: string;
+    readonly submissionToken: string | null;
+    readonly dispatchId: string | null;
+    readonly actualProducer: 'gpu' | 'cpu';
+    readonly backendKind: RhiDevice['caps']['backendKind'];
+    readonly compute: boolean;
+    readonly timestampQuery: boolean;
+    readonly timestampPeriodNanoseconds: number | null;
+    readonly gpu: MembershipTimingGpuReport | null;
+    readonly membership: MembershipTimingMembershipOutput | null;
+    readonly cpu: {
+        readonly encode: MembershipTimingInterval | null;
+        readonly submit: MembershipTimingInterval | null;
+    };
+    readonly async: {
+        readonly queueCompletion: MembershipTimingInterval | null;
+        readonly readback: MembershipTimingInterval | null;
+    };
+}
+export declare class MembershipTimingError extends Error {
+    readonly code: MembershipTimingReasonCode;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: string;
+    constructor(code: MembershipTimingReasonCode, expected: string, hint: string, detail?: string);
+}
+export interface MembershipTimingController {
+    readonly mode: MembershipTimingOptions['mode'];
+    readonly maxPendingCaptures: number;
+    readonly active: boolean;
+    readonly shouldTimestampPass: boolean;
+    usesCpuControl(): boolean;
+    start(): Result<{
+        readonly captureId: string;
+    }, MembershipTimingError>;
+    finish(): Promise<Result<MembershipTimingReport, MembershipTimingError>>;
+    beforeMembership(): ComputePassDescriptor | undefined;
+    afterMembership(encoder: RhiCommandEncoder): void;
+    markEncodeFinished(): void;
+    markEncodeFailed(detail?: string): void;
+    markTimestampPassFailed(detail?: string): void;
+    markSubmitStarted(): void;
+    markSubmitted(command: CommandBuffer): void;
+    markSubmitFailed(detail?: string): void;
+    markDeviceLost(detail?: string): void;
+    bindDevice(device: RhiDevice): void;
+    recordGpuMembershipSource(source: MembershipTimingGpuOutputSource): void;
+    recordMembershipOutput(output: MembershipTimingMembershipOutput): void;
+    dispose(): void;
+}
+export declare function createMembershipTiming(initialDevice: RhiDevice, options: MembershipTimingOptions): MembershipTimingController;
+//# sourceMappingURL=membership-timing.d.ts.map

package/dist/record/membership-timing.d.ts.map

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

package/dist/record/mesh-ssbo.d.ts

@@ -0,0 +1,173 @@
+import type { BindGroup, Buffer, RhiQueue } from '@forgeax/engine-rhi';
+import type { FoldDispatchPlan } from '../render-system-fold';
+import type { ValidatedRenderable } from './frame-snapshot';
+/**
+ * Stride between per-renderable `entity_world` mat4 slots inside the
+ * shared `pipelineState.meshStorageBuffer`. The 256-byte alignment is
+ * required because the storage buffer is bound with
+ * `hasDynamicOffset: true` and WebGPU spec
+ * `minStorageBufferOffsetAlignment` defaults to 256.
+ */
+export declare const MESH_PER_ENTITY_STRIDE = 256;
+export declare const MESH_SSBO_BYTES = 192;
+export declare const MESH_UBO_FULL_ARRAY_BYTES: number;
+export declare const INSTANCE_UBO_FULL_ARRAY_BYTES: number;
+export declare const MAX_UNIFORM_INSTANCES = 128;
+/**
+ * M3 / w12: extracts the underlying GPU resource object from a bind
+ * group entry descriptor. Returns the raw object reference (Buffer,
+ * TextureView, or Sampler) usable as a WeakMap chain key.
+ */
+export declare function extractEntryResourceHandle(entry: {
+    resource: {
+        kind: string;
+        value: unknown;
+    };
+}): object;
+/**
+ * feat-20260622-handle-to-id-allocator-elimination M2 / w7: walks a nested
+ * WeakMap chain to find or create a BindGroup leaf. Each handle in the
+ * `handles` array is a chain node; the final leaf is a Map<string, BindGroup>
+ * keyed by `variant` (D-2). Chain keys are always object references, never
+ * numeric ids — GC reclaims entries for dead handles automatically.
+ *
+ * On cache hit returns the cached BindGroup. On miss calls `factory`,
+ * bumps `bindGroupCounts.createBindGroup`, stores the result at the leaf,
+ * and returns it. Hit/miss accounting is observable via `bindGroupCounts`
+ * (D-8: the skin probe reads `counts.createBindGroup` delta).
+ */
+export declare function getOrCreateFromChain(root: WeakMap<object, unknown>, handles: readonly object[], variant: string, factory: () => BindGroup, counts: {
+    createBindGroup: number;
+    keys: string[];
+}): BindGroup;
+/**
+ * feat-20260622-handle-to-id-allocator-elimination M2 / w8: per-entity bind
+ * group lookup-or-create helper (D-2). Two-step lookup: outer Map.get(outerKey)
+ * finds or lazily creates an inner WeakMap chain, then delegates to
+ * `getOrCreateFromChain` for the chain walk. outerKey is `string | number`
+ * to cover both per-entity (number entityKey) and material-shared
+ * (string shaderId) caches (D-1 / OQ-1).
+ */
+export declare function getOrCreatePerEntity(outerMap: Map<string | number, WeakMap<object, unknown>>, outerKey: string | number, handles: readonly object[], variant: string, factory: () => BindGroup, counts: {
+    createBindGroup: number;
+    keys: string[];
+}): BindGroup;
+/**
+ * feat-20260622-handle-to-id-allocator-elimination M2 / w8: evicts per-entity
+ * cache entries whose entityKey is not in the validated set. Works on
+ * Map<entityKey, WeakMap<handle, BindGroup>> by iterating the outer Map keys
+ * and deleting entries for which validatedEntityKeys.has(ek) is false.
+ * No string parsing, no Number / Number.isNaN — the entityKey is already a
+ * number (D-1 / RD4).
+ *
+ * @internal — exported for unit test access (AC-08)
+ */
+export declare function cleanPerEntityCache(cache: Map<number, WeakMap<object, unknown>>, validatedEntityKeys: Set<number>): void;
+/**
+ * feat-20260608-mesh-ssbo-dynamic-grow-l1-lift-1024-entity-cap M3 / T-M3-04:
+ * record-stage entry-point hook to the closure-scoped mesh-SSBO grow
+ * controller (createRenderer.ts). Called once per frame, after
+ * `validatedOrdered` has been finalised and BEFORE the first per-entity
+ * `queue.writeBuffer`. Returns Result-like (never throws — D-5):
+ *
+ *  - `{ ok: true }`       — slotCount already covers `neededSlots` (idempotent
+ *                           short-circuit), or the controller successfully grew
+ *                           in this call. Caller proceeds with the frame.
+ *  - `{ ok: false, code, degradedToSlotCount }` — controller hit ceiling /
+ *                           capacity and ALREADY fired the structured error
+ *                           via errorRegistry.  Caller truncates the draw
+ *                           list to the largest complete entity prefix that
+ *                           fits within `degradedToSlotCount` slots (graceful
+ *                           degradation per plan-strategy D-2): renders the
+ *                           subset that fits, discards overflow, no black
+ *                           frame.
+ *
+ * This helper does NOT re-fire on `ok:false` — the controller is the single
+ * fire site (createRenderer.ts grow factory), so callers see exactly one
+ * structured error per ceiling event (charter P3 explicit failure: no
+ * double-fire).
+ *
+ * Dev-mode visibility: when grow actually grew (slotCount transition) AND
+ * `import.meta.env?.DEV` is truthy, a single `console.info('[mesh-ssbo] ...')`
+ * line reports the before / after / requested counts. The optional-chain
+ * keeps non-vite envs (dawn-node smoke, plain tsup tests) silent —
+ * `import.meta.env` is undefined there, the chain short-circuits to
+ * undefined, the if-guard is falsy (AC-11 + plan-strategy §2.D-3).
+ *
+ * Bind-group cache invalidation is automatic: on grow, the controller
+ * mutates `meshSsboState.mesh.buffer` / `.material.buffer` in place
+ * (wrapper-object identity preserved, inner buffer replaced — research §F8).
+ * Downstream the fresh inner buffer object is a new WeakMap chain key, so
+ * `getOrCreateFromChain` misses and rebuilds the BindGroup on the next frame
+ * (AC-07; T-M3-03 (a) test).
+ *
+ * @internal — exported for unit-test access (`mesh-ssbo-grow.test.ts`
+ * T-M3-01 / T-M3-02 / T-M3-03 cover idempotency, ceiling, dev info).
+ */
+export declare function ensureMeshSsboCapacity(internals: {
+    readonly growMeshSsbo?: ((neededSlots: number) => {
+        readonly ok: true;
+    } | {
+        readonly ok: false;
+        readonly code: 'mesh-ssbo-ceiling-reached' | 'mesh-ssbo-capacity-exceeded';
+        readonly degradedToSlotCount: number;
+    }) | undefined;
+    readonly meshSsboState?: {
+        readonly slotCount: number;
+    } | undefined;
+}, neededSlots: number): {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly code: 'mesh-ssbo-ceiling-reached' | 'mesh-ssbo-capacity-exceeded';
+    readonly degradedToSlotCount: number;
+};
+/**
+ * @internal — test-only injection seam for `ensureMeshSsboCapacity`'s
+ * dev-mode gate. Pass `undefined` to restore the production probe
+ * (`isMeshSsboDevMode`). Production code paths NEVER call this.
+ */
+export declare function setMeshSsboDevModeProbeForTests(probe: (() => boolean) | undefined): void;
+/**
+ * Dev-mode probe for `ensureMeshSsboCapacity`'s console.info gate
+ * (plan-strategy §2.D-3 + AC-11). True when the build is in dev mode:
+ *   - `import.meta.env?.DEV` is truthy (vite dev / vitest), OR
+ *   - `process.env.NODE_ENV !== 'production'` (esbuild / tsup / dawn-node).
+ * Optional-chain keeps it safe in non-vite ESM envs that never inject
+ * `import.meta.env` (the chain short-circuits to undefined → falsy).
+ *
+ * Vite's `import.meta.env.DEV` is constant-folded at build time, so the
+ * production bundle dead-code-strips the entire branch even though the
+ * test fall-through reads `process.env.NODE_ENV`.
+ *
+ * @internal — exported as a function (not a const) so unit tests can
+ * `vi.spyOn(...).mockReturnValue(false)` to exercise the dev=false path
+ * (vitest 4.x cannot toggle `import.meta.env.DEV` at runtime — it is
+ * compile-time-frozen by the vite transform).
+ */
+export declare function isMeshSsboDevMode(): boolean;
+/**
+ * feat-20260704 M3/w21: per-renderable `entity_world` upload (batched). All N
+ * mat4+normalMatrix slots are assembled into a single contiguous scratch
+ * buffer, then flushed as one `writeBuffer` call instead of N individual
+ * calls. Extracted verbatim from `recordFrame` (frame.ts) — the module-scoped
+ * `_meshSsboScratch` let and its only reassignment site now co-locate in this
+ * file so the two mesh-SSBO module lets live together (AC-06).
+ *
+ * feat-20260518 M3 / w14 (AC-08): each 256-byte slot carries a 16-float mat4
+ * at [0..64B) and a 48-byte mat3 normalMatrix at [64..112B) (3 vec4 columns;
+ * padding at indices 19/23/27 stays 0). The mat3 =
+ * transpose(invert(mat3(worldFromLocal))) for correct normal transform under
+ * non-uniform scale.
+ *
+ * feat-20260622-chunk-gpu-instancing-sprite-tilemap M1 / w4-record-swap (D-1):
+ * fold-bucket heads write identity into their slot; the fold path assembles
+ * per-instance world matrices into the @group(3) instances buffer instead
+ * (sprite/unlit shaders ignore normals; AC-01/AC-02).
+ *
+ * @internal
+ */
+export declare function uploadMeshSsboBatch(queue: RhiQueue, meshStorageBuffer: {
+    readonly buffer: Buffer;
+}, validatedOrdered: readonly ValidatedRenderable[], foldDispatchPlan: FoldDispatchPlan | null, reactiveRevisionChanged?: boolean): void;
+//# sourceMappingURL=mesh-ssbo.d.ts.map

package/dist/record/mesh-ssbo.d.ts.map

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

package/dist/record/shadow-caster-uniform.d.ts

@@ -0,0 +1,8 @@
+import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
+import type { ExtractedLights } from '../render-system-extract';
+export declare const SHADOW_CASTER_SLOT_STRIDE = 256;
+export declare const SHADOW_CASTER_BUFFER_SIZE: number;
+export declare function directionalShadowCasterOffset(cascadeIndex: number): number;
+export declare function spotShadowCasterOffset(tile: number): number;
+export declare function writeShadowCasterUniforms(queue: RhiQueue, buffer: Buffer, lights: ExtractedLights): void;
+//# sourceMappingURL=shadow-caster-uniform.d.ts.map

package/dist/record/shadow-caster-uniform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow-caster-uniform.d.ts","sourceRoot":"","sources":["../../src/record/shadow-caster-uniform.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAC7C,eAAO,MAAM,yBAAyB,QAAgC,CAAC;AAEvE,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,QAAQ,EACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,eAAe,GACtB,IAAI,CAkBN"}

package/dist/record/shadow-pass.d.ts

@@ -0,0 +1,125 @@
+import type { GraphResourceResolver } from '@forgeax/engine-render-graph';
+import { type RhiRenderPassEncoder } from '@forgeax/engine-rhi';
+import type { PassSelector } from '@forgeax/engine-types';
+import type { RenderPipelineGpuDrivenShadowProjection } from '../render-pipeline';
+import type { _InternalRenderPipelineContext } from '../render-pipeline-context';
+import type { DispatchEntry } from '../render-system-extract';
+export declare function encodeDirectionalShadowPass(c: _InternalRenderPipelineContext, pass: RhiRenderPassEncoder, cascadeIndex: number, viewport: {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}, gpuDriven?: {
+    readonly projection: RenderPipelineGpuDrivenShadowProjection;
+    readonly resources: GraphResourceResolver;
+}): void;
+export declare function encodePointShadowPass(c: _InternalRenderPipelineContext, pass: RhiRenderPassEncoder, snapshotIndex: number, face: number): void;
+export declare function encodeSpotShadowPass(c: _InternalRenderPipelineContext, pass: RhiRenderPassEncoder, snapshotIndex: number): void;
+/**
+ * feat-20260609 M2: filter dispatch entries by a {@link PassSelector}.
+ *
+ * Each dispatch entry carries `tags` (a free key-value map) sourced from the
+ * material's per-pass tags.  The selector is matched entry-by-entry via
+ * {@link matchPass}; entries whose tags satisfy the selector are returned.
+ * An empty selector returns the input array unchanged (match-all semantics).
+ *
+ * @param dispatch Per-frame dispatch entries (from the extract stage).
+ * @param selector Pipeline-specific pass selector (e.g. `{ LightMode: ['Forward'] }`).
+ * @returns Dispatch entries whose tags match the selector.
+ */
+export declare function filterDispatchBySelector(dispatch: readonly DispatchEntry[], selector: PassSelector): readonly DispatchEntry[];
+/**
+ * feat-20260609 M2: build a set of renderable indices whose dispatch entries
+ * match the given selector.  Used by the record pass closures to skip entities
+ * that do not belong to the current pass.
+ *
+ * Returns null when the dispatch array is empty (no dispatch-based filtering
+ * to apply — draw all entities).  Returns an empty set when dispatch is
+ * non-empty but no entries matched (draw nothing).  Returns a populated set
+ * when at least one dispatch entry matched.
+ */
+export declare function buildMatchedRenderableIndices(dispatch: readonly DispatchEntry[], selector: PassSelector): Set<number> | null;
+/**
+ * feat-20260529-rendergraph-pass-abstraction M4 / w13b: shadow depth pass
+ * recording, extracted verbatim from recordFrame. Renders shadow casters
+ * into the shadow depth RT using an INDEPENDENT command encoder + its own
+ * queue.submit (RD-4: this independent-encoder boundary is the runtime-side
+ * manual barrier that synchronizes the depth-texture write with the
+ * subsequent sample in the main pass). Driven by the render-graph 'shadow'
+ * pass execute closure.
+ */
+export declare function recordShadowPass(c: _InternalRenderPipelineContext, selector?: PassSelector, viewport?: {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}, cascadeIndex?: number): void;
+/**
+ * feat-20260612-point-light-shadows-urp-hdrp M3 / T-M3-2 (plan-strategy §D-1
+ * + §D-3 + AC-04). Records the 6 x N point-shadow caster passes — one render
+ * pass per (shadow-casting point light, cube face) pair — that write per-light
+ * cube_array atlas depth. Driven by the URP `addPointShadowPass` graph closure;
+ * gated upstream on `frameState.pointShadowSnapshots.length > 0` (AC-09 zero-
+ * shadow zero-pass).
+ *
+ * Pass count = 6 * N where N = `frameState.pointShadowSnapshots.length`. Each
+ * pass opens an INDEPENDENT command encoder + queue.submit so Dawn / WebGPU
+ * synchronizes the depth-write boundary with the subsequent atlas sample in
+ * the forward pass (RD-4 manual barrier; same pattern as `recordShadowPass`).
+ *
+ * Round-2 F-3 fix-up: actual geometry walk + draw landed. Per face we
+ * (1) write the face VP mat4 into `viewUniformBuffer` at offset 112 (the
+ * `lightSpaceMatrix` slot) — `forgeax::default-shadow-caster` reads
+ * `view.lightSpaceMatrix * worldPos` and the encoder boundary serializes
+ * the queue.writeBuffer with the subsequent draw, so each face sees its own
+ * VP without needing a per-face UBO bind. (2) Reuse the directional shadow
+ * caster PSO + cached `shadow-view-bg` / `shadow-material-singleton` /
+ * `shadow-mesh-bg` already built by `recordShadowPass`. (3) After all
+ * (snapshot, face) passes complete, restore `viewUniformBuffer.lightSpaceMatrix`
+ * to the directional value the main forward pass needs (the queue.submit
+ * ordering guarantees the restore lands before the main encoder runs).
+ *
+ * Caveat: the cached `view-shadow` BG binds `shadowAtlasFallbackTextureView`
+ * at binding 5 (NOT the real ShadowAtlas atlas view) so the BG is valid even
+ * while the real atlas faces are being written through the depth attachment;
+ * the shadow_caster.wgsl shader never samples binding 5 anyway (vertex-only
+ * pipeline).
+ *
+ * No new shader / no new PSO / no new BGL is required for this round; the
+ * change is purely runtime wiring. A dedicated `forgeax::default-point-
+ * shadow-caster` PSO with a per-face VP UBO + dynamic offset would let the
+ * pass run without touching `viewUniformBuffer.lightSpaceMatrix` and could
+ * be considered for a follow-on optimization milestone (`OOS-future`).
+ */
+export declare function recordPointShadowPass(c: _InternalRenderPipelineContext): void;
+/**
+ * feat-20260625-spot-light-shadow-mapping M2 / w11 (D-1 + D-2). Records the
+ * spot-light shadow caster passes — one render pass per castShadow spot (cap 4)
+ * — that write each spot's perspective depth into its `spotShadowDepth` atlas
+ * tile. Driven by the URP `addSpotShadowPass` graph closure; reads
+ * `frameState.spotShadowSnapshots`.
+ *
+ * Per spot with `shadowAtlasTile >= 0` (castShadow + non-degenerate dir + not
+ * clipped) and a valid `lightViewProj`:
+ *   (1) Write the spot perspective matrix into `shadowCasterCascadeBuffer`
+ *       (D-1: spotLightViewProj lane at byte 16) and set `isSpot = 1` so the
+ *       shadow_caster vertex shader routes through the spot matrix instead of
+ *       the directional `view.lightViewProj_A..D` slots. The per-pass
+ *       independent command encoder + queue.submit serialize each host write
+ *       against that pass's GPU read.
+ *   (2) Open an INDEPENDENT command encoder targeting the spotShadowDepth view
+ *       with `depthLoadOp = (first valid tile ? clear : load)` — independent
+ *       clear counting decoupled from the directional cascadeIndex (D-2). Set a
+ *       per-tile viewport (col = tile % 2, row = tile / 2).
+ *   (3) Reuse the vertex-only `forgeax::default-shadow-caster` PSO + the cached
+ *       `view-shadow` BG + `shadow-material-singleton` + meshBindGroup built by
+ *       recordShadowPass (or built on-demand here when no directional shadow
+ *       ran this frame).
+ *
+ * AC-03 zero-shadow zero-pass: early-returns when no spot has a valid tile, so
+ * castShadow:false scenes (all tile=-1) record zero spot passes. After the
+ * loop, `isSpot` is reset to 0 so the next directional cascade pass (or next
+ * frame) sees the directional routing.
+ */
+export declare function recordSpotShadowPass(c: _InternalRenderPipelineContext): void;
+//# sourceMappingURL=shadow-pass.d.ts.map

package/dist/record/shadow-pass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow-pass.d.ts","sourceRoot":"","sources":["../../src/record/shadow-pass.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAKL,KAAK,oBAAoB,EAE1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAoB1D,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AAEjF,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,0BAA0B,CAAC;AAqejF,wBAAgB,2BAA2B,CACzC,CAAC,EAAE,8BAA8B,EACjC,IAAI,EAAE,oBAAoB,EAC1B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE;IAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAC5F,SAAS,CAAC,EAAE;IACV,QAAQ,CAAC,UAAU,EAAE,uCAAuC,CAAC;IAC7D,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;CAC3C,GACA,IAAI,CAsDN;AAED,wBAAgB,qBAAqB,CACnC,CAAC,EAAE,8BAA8B,EACjC,IAAI,EAAE,oBAAoB,EAC1B,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,GACX,IAAI,CAuBN;AAED,wBAAgB,oBAAoB,CAClC,CAAC,EAAE,8BAA8B,EACjC,IAAI,EAAE,oBAAoB,EAC1B,aAAa,EAAE,MAAM,GACpB,IAAI,CAkDN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,QAAQ,EAAE,YAAY,GACrB,SAAS,aAAa,EAAE,CAG1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,QAAQ,EAAE,YAAY,GACrB,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAmBpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,EAAE,8BAA8B,EACjC,QAAQ,CAAC,EAAE,YAAY,EACvB,QAAQ,CAAC,EAAE;IAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAC7F,YAAY,GAAE,MAAU,GACvB,IAAI,CA6YN;AAyYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,8BAA8B,GAAG,IAAI,CA6Y7E;AAuLD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,8BAA8B,GAAG,IAAI,CAsD5E"}

package/dist/record/shadow-submit-mode.d.ts

@@ -0,0 +1,66 @@
+import type { CommandBuffer } from '@forgeax/engine-rhi';
+export declare const SHADOW_SUBMIT_MODES: readonly ["independent", "coalesced-with-frame"];
+export type ShadowSubmitMode = (typeof SHADOW_SUBMIT_MODES)[number];
+export interface RendererOwnerIdentity {
+    readonly carrierId: string;
+    readonly pageIdentity: string;
+    readonly browserRealmId: string;
+    readonly runtimeId: string;
+    readonly canvasIdentity: string;
+    readonly rendererGeneration: string;
+}
+export interface ShadowSubmitModeRequest {
+    readonly schema: 'renderer-owner-admission/v1';
+    readonly shadowSubmitMode: ShadowSubmitMode;
+    readonly identity: RendererOwnerIdentity;
+}
+export interface ShadowSubmitModeError {
+    readonly code: string;
+    readonly category: 'precondition' | 'state';
+    readonly expected: unknown;
+    readonly observed: unknown;
+    readonly hint: string;
+    readonly recoveryActions: readonly ['renderer.ownerAdmission.rediscover'];
+    readonly safeRerun: true;
+}
+export type ShadowSubmitResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: ShadowSubmitModeError;
+};
+export declare function validateShadowSubmitModeRequest(value: unknown): ShadowSubmitResult<ShadowSubmitModeRequest>;
+export interface ShadowSubmitFrame<TCommandBuffer> {
+    readonly rendererGeneration: string;
+    readonly expectedRendererGeneration?: string;
+    readonly shadowCommandBuffers: readonly TCommandBuffer[];
+    readonly frameCommandBuffer: TCommandBuffer;
+    readonly drawCaptureParity: unknown;
+}
+export interface ShadowSubmitPlan<TCommandBuffer> {
+    readonly shadowSubmitMode: ShadowSubmitMode;
+    readonly rendererGeneration: string;
+    readonly rawSubmissions: readonly {
+        readonly commandBuffers: readonly TCommandBuffer[];
+    }[];
+    readonly deferredShadowCommandBuffers: readonly TCommandBuffer[];
+    readonly rawSubmitCount: number;
+    readonly reRecorded: false;
+    readonly drawCaptureParity: unknown;
+}
+export declare function createShadowSubmitPlan<TCommandBuffer>(input: ShadowSubmitFrame<TCommandBuffer> & {
+    readonly shadowSubmitMode: ShadowSubmitMode;
+}): ShadowSubmitResult<ShadowSubmitPlan<TCommandBuffer>>;
+export interface ShadowSubmitModeState {
+    readonly mode: ShadowSubmitMode;
+    readonly rendererGeneration: string | null;
+    readonly appliedCount: number;
+    readonly restoredCount: number;
+    readonly active: boolean;
+}
+export declare function createShadowSubmitModeState(): ShadowSubmitModeState;
+export declare function applyShadowSubmitMode(state: ShadowSubmitModeState, mode: ShadowSubmitMode, rendererGeneration: string): ShadowSubmitResult<ShadowSubmitModeState>;
+export declare function restoreShadowSubmitMode(state: ShadowSubmitModeState, rendererGeneration: string): ShadowSubmitResult<ShadowSubmitModeState>;
+export declare function commandBufferPlanForFrame(state: ShadowSubmitModeState, pendingShadowCommandBuffers: readonly CommandBuffer[], frameCommandBuffer: CommandBuffer): ShadowSubmitResult<ShadowSubmitPlan<CommandBuffer>>;
+//# sourceMappingURL=shadow-submit-mode.d.ts.map

package/dist/record/shadow-submit-mode.d.ts.map

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