@forgeax/engine-render 0.1.2

package/dist/features/targets.d.ts

@@ -0,0 +1,32 @@
+/** Render-owned logical targets exposed to producer-owned RenderFeatures. */
+export type RenderFeatureTargetKind = 'scene-color' | 'scene-depth' | 'scene-temporal';
+/**
+ * A logical attachment supplied by the active RenderPipeline.
+ *
+ * The semantic kind plus attachment facts identify the target. The active
+ * pipeline supplies the graph resource, so feature authors never name an
+ * internal graph key.
+ */
+export interface RenderFeatureTargetHandle {
+    readonly kind: RenderFeatureTargetKind;
+    readonly format: string;
+    readonly sampleCount: 1 | 4;
+    readonly __renderFeatureTarget: unique symbol;
+}
+export interface RenderFeatureTargetInput {
+    readonly kind: RenderFeatureTargetKind;
+    readonly format: string;
+    readonly sampleCount: 1 | 4;
+}
+export declare function createRenderFeatureTarget(input: RenderFeatureTargetInput): RenderFeatureTargetHandle;
+export declare function isRenderFeatureTargetHandle(value: unknown): value is RenderFeatureTargetHandle;
+export declare function renderFeatureAttachmentResource(resource: string | RenderFeatureTargetHandle): string;
+export declare function resolveStandardRenderFeatureTargets(input: {
+    readonly pipelineId: string;
+    readonly tonemap: string;
+    readonly antialias: string;
+    readonly storageBuffer: boolean;
+    readonly multisample: boolean;
+    readonly colorAttachmentFormat: string;
+}): readonly RenderFeatureTargetHandle[];
+//# sourceMappingURL=targets.d.ts.map

package/dist/features/targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"targets.d.ts","sourceRoot":"","sources":["../../src/features/targets.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAE7E,MAAM,MAAM,uBAAuB,GAAG,aAAa,GAAG,aAAa,GAAG,gBAAgB,CAAC;AAEvF;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC;IAC5B,QAAQ,CAAC,qBAAqB,EAAE,OAAO,MAAM,CAAC;CAC/C;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC;CAC7B;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,wBAAwB,GAC9B,yBAAyB,CAE3B;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,yBAAyB,CAU9F;AAED,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,MAAM,GAAG,yBAAyB,GAC3C,MAAM,CAER;AAED,wBAAgB,mCAAmC,CAAC,KAAK,EAAE;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC,GAAG,SAAS,yBAAyB,EAAE,CA2BvC"}

package/dist/features/types.d.ts

@@ -0,0 +1,247 @@
+/** Public RenderFeature lifecycle, diagnostics, and host-context declarations. */
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import type { Result } from '@forgeax/engine-types';
+import type { RenderError } from '../errors/render';
+import type { VisibilitySnapshot } from '../extract/visibility';
+import type { RenderFeatureContributionStaging } from './graph-contribution';
+import type { RenderFeatureGpuPrepare } from './prepared-gpu-work';
+import type { PreparedKind, RenderFeatureGraphicsContributionStaging, RenderFeatureGraphicsPrepare } from './prepared-graphics';
+import type { RenderFeatureTargetHandle } from './targets';
+export type { RenderFeatureTargetHandle } from './targets';
+/** Closed lifecycle states exposed by the feature host. */
+export type RenderFeatureStatus = 'active' | 'failed' | 'disabled' | 'disposed';
+/** Callback stages that can attribute a feature failure. */
+export type RenderFeatureStage = 'extract' | 'prepare' | 'contribute' | 'record' | 'recover' | 'dispose';
+/** Recovery action attached to a structured feature failure. */
+export type RenderFeatureRecovery = 'next-frame' | 'renderer-recover' | 'registration';
+/**
+ * Render-owned feature error codes. The detail map below is the membership
+ * owner consumed by the RenderError union.
+ */
+export type RenderFeatureErrorCode = keyof RenderFeatureErrorDetailByCode;
+/** Boolean capability names are derived from the RHI capability source. */
+type BooleanCapabilityKey = {
+    [Key in keyof RhiCaps]-?: RhiCaps[Key] extends boolean ? Key : never;
+}[keyof RhiCaps];
+export type RenderFeatureCapabilityKey = BooleanCapabilityKey;
+export interface RenderFeatureRegistrationConflictDetail {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly conflictingOrder: number;
+}
+export interface RenderFeatureStageFailedDetail {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: RenderFeatureStage;
+    readonly recovery: RenderFeatureRecovery;
+    readonly cleanupFailures?: readonly RenderFeatureCleanupFailure[];
+}
+export interface RenderFeatureCleanupFailure {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly code: string;
+}
+export interface RenderFeatureCapabilityMissingDetail {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly capability: RenderFeatureCapabilityKey;
+}
+export interface RenderFeaturePassOrderConflictDetail {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly passIdentity: string;
+    readonly dependencyIdentity: string;
+}
+export interface RenderFeaturePreparationFailedDetail {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: 'prepare';
+    readonly operation: string;
+    readonly resourceKind: PreparedKind;
+    readonly resourceName: string;
+    readonly reason: string;
+    readonly recovery: RenderFeatureRecovery;
+}
+export type RenderFeaturePreparedStateMismatchDetail = {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: 'contribute';
+    readonly operation: string;
+    readonly resourceKind: PreparedKind;
+    readonly reason: 'missing-prepared-state';
+    readonly missingResource: string;
+    readonly recovery: RenderFeatureRecovery;
+} | {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: 'contribute';
+    readonly operation: string;
+    readonly resourceKind: PreparedKind;
+    readonly reason: 'foreign-feature';
+    readonly expectedFeatureIdentity: string;
+    readonly actualFeatureIdentity: string;
+    readonly recovery: RenderFeatureRecovery;
+} | {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: 'contribute';
+    readonly operation: string;
+    readonly resourceKind: PreparedKind;
+    readonly reason: 'foreign-kind';
+    readonly expectedKind: PreparedKind;
+    readonly actualKind: PreparedKind;
+    readonly recovery: RenderFeatureRecovery;
+} | {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: 'contribute';
+    readonly operation: string;
+    readonly resourceKind: PreparedKind;
+    readonly reason: 'generation-mismatch';
+    readonly expectedGeneration: number;
+    readonly actualGeneration: number;
+    readonly recovery: RenderFeatureRecovery;
+} | {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: 'contribute';
+    readonly operation: string;
+    readonly resourceKind: PreparedKind;
+    readonly reason: 'layout-mismatch';
+    readonly expectedLayout: string;
+    readonly actualLayout: string;
+    readonly recovery: RenderFeatureRecovery;
+} | {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: 'contribute';
+    readonly operation: string;
+    readonly resourceKind: PreparedKind;
+    readonly reason: 'format-mismatch';
+    readonly expectedFormat: string;
+    readonly actualFormat: string;
+    readonly recovery: RenderFeatureRecovery;
+};
+export interface RenderFeatureDrawRecordingFailedDetail {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: 'record';
+    readonly operation: string;
+    readonly resourceKind: PreparedKind;
+    readonly reason: string;
+    readonly backendReason: string;
+    readonly recovery: RenderFeatureRecovery;
+}
+export type RenderFeatureErrorDetailByCode = {
+    'render-feature-registration-conflict': RenderFeatureRegistrationConflictDetail;
+    'render-feature-stage-failed': RenderFeatureStageFailedDetail;
+    'render-feature-capability-missing': RenderFeatureCapabilityMissingDetail;
+    'render-feature-pass-order-conflict': RenderFeaturePassOrderConflictDetail;
+    'render-feature-preparation-failed': RenderFeaturePreparationFailedDetail;
+    'render-feature-prepared-state-mismatch': RenderFeaturePreparedStateMismatchDetail;
+    'render-feature-draw-recording-failed': RenderFeatureDrawRecordingFailedDetail;
+};
+/** Machine-readable four-field diagnostic exposed by every feature error. */
+export type RenderFeatureErrorDescriptor = {
+    [Code in RenderFeatureErrorCode]: {
+        readonly code: Code;
+        readonly expected: string;
+        readonly hint: string;
+        readonly detail: RenderFeatureErrorDetailByCode[Code];
+    };
+}[RenderFeatureErrorCode];
+export interface RenderFeatureFrameIdentity {
+    readonly frameNumber: number;
+}
+export interface RenderFeatureResourceHandle {
+    readonly __renderFeatureResource: unique symbol;
+}
+export interface RenderFeatureErrorSink {
+    report(error: RenderError): void;
+}
+/** One World-local visibility snapshot prepared for the current frame batch. */
+export interface RenderFeatureWorldVisibilitySnapshot {
+    readonly world: World;
+    readonly snapshot: VisibilitySnapshot;
+}
+/** A producer's structured report for one hidden render candidate. */
+export interface RenderFeatureHiddenEntityReport {
+    readonly world: World;
+    readonly entity: EntityHandle;
+}
+export interface RenderFeatureExtractContext {
+    readonly worlds: readonly World[];
+    readonly owner: number;
+    readonly frameNumber: number;
+    /** Same-batch World snapshots; absent for synthetic direct feature probes. */
+    readonly visibilitySnapshots?: readonly RenderFeatureWorldVisibilitySnapshot[];
+    /** Host-owned report sink; feature code never owns the merged diagnostic. */
+    readonly reportHiddenEntity?: (report: RenderFeatureHiddenEntityReport) => void;
+}
+/**
+ * Host-owned preparation surface. A feature prepares references here first and
+ * consumes them later through the contribute staging surface. The host owns
+ * resources and generation validity for the whole lifecycle.
+ */
+export interface RenderFeaturePrepareContext {
+    readonly caps: Readonly<RhiCaps>;
+    readonly frame: RenderFeatureFrameIdentity;
+    readonly resources: readonly RenderFeatureResourceHandle[];
+    readonly targets: readonly RenderFeatureTargetHandle[];
+    readonly reportError: RenderFeatureErrorSink;
+    /** Controlled pipeline, bindings, vertex-data, and index-data preparation. */
+    readonly graphics: RenderFeatureGraphicsPrepare;
+    /** Renderer-owned persistent compute/storage preparation, when compute is available. */
+    readonly gpu?: RenderFeatureGpuPrepare;
+}
+/** The narrow context visible to a feature-owned graph pass. */
+export interface RenderFeaturePassContext {
+    readonly frame: RenderFeatureFrameIdentity;
+    /** The named pass currently executing inside the active RenderGraph. */
+    readonly pass: {
+        readonly name: string;
+        readonly reads: readonly string[];
+        readonly writes: readonly string[];
+    };
+}
+export interface RenderFeatureContributeContext extends RenderFeaturePrepareContext {
+    /** Graph-owned staging retains the ordinary graph-only `addPass` path. */
+    readonly staging: RenderFeatureContributionStaging & RenderFeatureGraphicsContributionStaging;
+}
+/**
+ * Producer-owned extension seam for one render frame.
+ *
+ * `FrameData` is the single value that crosses extract, prepare, and
+ * contribute. A producer owns its shape; the host owns ordering, failure
+ * isolation, graph composition, recovery, generation checks, and disposal.
+ * The lifecycle is extract -> prepare -> contribute, with optional recover and
+ * dispose callbacks.
+ */
+export interface RenderFeature<FrameData> {
+    readonly identity: string;
+    readonly requiredCapabilities?: readonly RenderFeatureCapabilityKey[];
+    /**
+     * Material shader identifiers whose modules must be ready before the first
+     * frame. The renderer resolves these against the loaded manifest and seeds
+     * the same lazy module cache used by prepared graphics.
+     */
+    readonly requiredMaterialShaders?: readonly string[];
+    extract(context: RenderFeatureExtractContext): Result<FrameData, RenderError>;
+    prepare(data: FrameData, context: RenderFeaturePrepareContext): Result<void, RenderError>;
+    contribute(data: FrameData, context: RenderFeatureContributeContext): Result<void, RenderError>;
+    recover?(context: RenderFeaturePrepareContext): Result<void, RenderError>;
+    dispose?(context: RenderFeaturePrepareContext): Result<void, RenderError>;
+}
+export interface RenderFeatureRecoverInput {
+    readonly caps: Readonly<RhiCaps>;
+    readonly frameNumber: number;
+}
+/** Read-only, machine-readable lifecycle state for one registered feature. */
+export interface RenderFeatureDiagnostics {
+    readonly identity: string;
+    readonly order: number;
+    readonly status: RenderFeatureStatus;
+    readonly latestError: RenderFeatureErrorDescriptor | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/features/types.d.ts.map

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

package/dist/frame-chain.d.ts

@@ -0,0 +1,14 @@
+import type { RenderResult } from './renderer';
+export interface ExtractedFrame {
+    readonly worlds: readonly unknown[];
+}
+export interface PreparedFrame {
+    readonly extracted: ExtractedFrame;
+    readonly resources: Map<unknown, unknown>;
+}
+export declare function buildFrameChain(worlds: readonly unknown[]): ExtractedFrame;
+export declare function prepareFrame(extracted: ExtractedFrame, options: {
+    resources: Map<unknown, unknown>;
+}): PreparedFrame;
+export declare function recordFrame(_frame: PreparedFrame): RenderResult<void, Error>;
+//# sourceMappingURL=frame-chain.d.ts.map

package/dist/frame-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-chain.d.ts","sourceRoot":"","sources":["../src/frame-chain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;CACrC;AACD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;CAC3C;AACD,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,cAAc,CAE1E;AACD,wBAAgB,YAAY,CAC1B,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE;IAAE,SAAS,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;CAAE,GAC5C,aAAa,CAEf;AACD,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,CAE5E"}

package/dist/fullscreen-post-process-pass.d.ts

@@ -0,0 +1,178 @@
+import type { BindGroup, BindGroupLayout, Buffer, RhiDevice, RhiError, RhiRenderPassEncoder, Sampler, TextureView } from '@forgeax/engine-rhi';
+/**
+ * Declared sample type for a post-process read entry.
+ *
+ * Closed union (plan-strategy D-7): only `'depth'` is an explicit sampleType
+ * discriminant; color inputs are the default (bare `string` or un-suffixed
+ * `{ key }`).  Future texture types (`r32float`, etc.) are add-only.
+ *
+ * AI-user affordance: IDE autocomplete exposes `'depth'` at the register call
+ * site; misspellings are caught by the type system (AC-08).
+ */
+export type PostProcessReadSampleType = 'depth';
+/**
+ * A registered fullscreen post-process shader entry.
+ *
+ * Analogous to MaterialShaderEntry in the ShaderRegistry but with post-process-specific
+ * fields: the input-texture + sampler BGL is auto-built by the primitive,
+ * no paramSchema (params are passed inline via a {type, value} struct — plan-strategy D-4).
+ *
+ * `params` carries the WGSL struct definition + default value. When `params` is
+ * `undefined`, the post-process shader has no UBO (e.g. FXAA — Finding M2-1).
+ *
+ * `reads` declares graph resource keys this pass samples as input texture(s).
+ * If omitted, the pass samples the swap-chain color attachment (default path).
+ *
+ * Structured reads (plan-strategy D-1): each entry can be a bare string
+ * (backward-compatible color input) or an object `{ key, sampleType? }`.
+ * When `sampleType` is `'depth'`, the dispatcher resolves a depth-only view
+ * and binds it at depthTex@3 / depthSampler@4 in the fullscreen bind group.
+ */
+export interface PostProcessShaderEntry {
+    /** Composed WGSL source for the fragment stage (post-naga_oil). */
+    readonly source: string;
+    /**
+     * Params UBO schema. When undefined, the shader has no uniform buffer (e.g. FXAA)
+     * and the BGL degrades to 2 entries (texture@0 + sampler@1). When present, the
+     * primitive eager-creates a params UBO (at register, sized `byteSize`) and binds
+     * it at bindgroup(1) binding(2) as part of a 3-entry BGL
+     * (texture@0 + sampler@1 + buffer@2). feat-20260621 M-A2 / D-2.
+     */
+    readonly params?: PostProcessParamsSchema | undefined;
+    /**
+     * Graph resource keys this post-process reads (as input textures).
+     * The primitive binds the first read as its input texture at @group(1)
+     * @binding(0) (the sampler is @group(1) @binding(1); group 0 is reserved for a
+     * future view bind group — dispatchFullscreenPass calls setBindGroup(1, ...)).
+     * When empty or omitted, the pass reads the swap-chain directly.
+     *
+     * Each entry is either a bare string (backward-compatible color input) or an
+     * object `{ key: string; sampleType?: PostProcessReadSampleType }` for typed
+     * reads (e.g. `{ key: 'depth', sampleType: 'depth' }` for depth sampling).
+     * Bare strings and `{ key }` without `sampleType` are equivalent — both
+     * represent a color input (plan-strategy D-1 / D-7).
+     */
+    readonly reads?: readonly (string | PostProcessReadEntry)[] | undefined;
+}
+/**
+ * Structured read entry for a post-process shader.
+ *
+ * `key` is the graph resource key (matching a graph color target).
+ * `sampleType` is an optional type discriminant (D-1 SSOT); when omitted
+ * the entry is treated as a color input (same as a bare string).
+ */
+export interface PostProcessReadEntry {
+    readonly key: string;
+    readonly sampleType?: PostProcessReadSampleType | undefined;
+}
+/**
+ * Params schema: the WGSL struct definition + default byte array for a post-process
+ * UBO. The primitive allocates a GPU buffer of `byteSize` and uploads `defaultValue`
+ * at register time; the UBO is then updated per-frame via the data-driven
+ * `PostProcessParams` ECS component (component `data` -> extract snapshot ->
+ * dispatchFullscreenPass `queue.writeBuffer`), NOT via an imperative setter.
+ * feat-20260621 M-A1/M-A2 / D-1.
+ */
+export interface PostProcessParamsSchema {
+    /** Byte size of the WGSL params struct (must be UBO-aligned, min 16 B). */
+    readonly byteSize: number;
+    /** Default UBO contents (length must equal `byteSize`). */
+    readonly defaultValue: Uint8Array;
+}
+/**
+ * Descriptor for a fullscreen post-process pass. Declares which registered shader
+ * to use, which color target to write, and which graph resource(s) to read.
+ */
+export interface FullscreenPassDescriptor {
+    /** Registered post-process shader id (must be registered via postProcess.register). */
+    readonly shader: string;
+    /**
+     * Color target: the graph resource key to write into. The pipeline must have
+     * already declared this target via `graph.addColorTarget` (the dispatcher
+     * resolves it, it does not auto-create one); a pass that names an undeclared
+     * key falls back to the swap-chain `ctx.view`.
+     */
+    readonly color: string;
+    /**
+     * Graph resource keys to read. The primitive binds the first read entry as its
+     * input texture (@group(1) @binding(0); sampler @binding(1)). Passes with
+     * reads==[] sample the swap-chain directly (copyTextureToTexture path — plan-strategy D-1).
+     */
+    readonly reads?: readonly string[] | undefined;
+}
+/**
+ * The minimal surface a `registerFullscreenPostProcess` injector receives.
+ * Contains the RHI device (for creating BGLs / pipelines / samplers) and the
+ * error registry for structured failure reporting.
+ */
+export interface FullscreenPostProcessDeviceContext {
+    readonly device: RhiDevice;
+    readonly errorRegistry: {
+        fire(error: RhiError): void;
+    };
+}
+/**
+ * Check whether the entry's {@link PostProcessShaderEntry.reads} declares a read
+ * with `sampleType: 'depth'`. Used by {@link buildFullscreenPostProcessPass} to
+ * select between the single-sample and multisample depth BGL variants and the
+ * existing color-only kinds.
+ */
+export declare function entryHasDepthRead(entry: PostProcessShaderEntry): boolean;
+/**
+ * Byte size of the minimal params UBO auto-allocated for a depth-reading entry
+ * that declares no `params`. The `'fullscreen-post-with-scene-depth'` BGL always
+ * declares `params@2`, so a bound UBO must exist even when the shader has no
+ * user params (plan D-3: param-less depth effect gets a minimal 16B UBO). 16 B
+ * is WebGPU's minimum uniform-buffer binding size.
+ */
+export declare const DEPTH_MIN_PARAMS_BYTE_SIZE = 16;
+/**
+ * State of a registered fullscreen post-process pass.
+ *
+ * Created by `addFullscreenPass` and stored per-pass in the render system.
+ * The `draw` method is called by the per-frame execute closure.
+ */
+export interface FullscreenPostProcessPassHandle {
+    /** The pass name (same as the `color` target key). */
+    readonly name: string;
+    /** Execute one fullscreen draw: bind input texture, set pipeline, draw 3 vertices. */
+    draw(encoder: RhiRenderPassEncoder, inputView: TextureView): void;
+    /**
+     * The per-frame params UBO this pass binds at group(1) binding(2), or null
+     * when `entry.params === undefined` (param-less consumer, 2-entry BGL). The
+     * dispatcher writes the snapshot bytes into it before draw and composes it
+     * into the bind group via {@link createFullscreenBindGroup}.
+     */
+    readonly paramsBuffer: Buffer | null;
+}
+/**
+ * Build a fullscreen post-process pass primitive.
+ *
+ * Creates BGL, sampler, and pipeline state from the registered shader entry.
+ * Returns the pass handle + the BGL + the sampler so the caller can compose
+ * bind groups. The BGL + sampler are shared across instances of the same shader.
+ *
+ * @returns The BGL, sampler, and a factory to create pass handles.
+ */
+export declare function buildFullscreenPostProcessPass(ctx: FullscreenPostProcessDeviceContext, entry: PostProcessShaderEntry, depthMultisampled?: boolean): {
+    bindGroupLayout: BindGroupLayout;
+    sampler: Sampler | null;
+    depthSampler: Sampler | null;
+    createHandle: (name: string, pipeline: unknown, paramsBuffer: Buffer | null) => FullscreenPostProcessPassHandle;
+} | null;
+/**
+ * Create a fullscreen bind group (lazy, per-frame). Composes the input texture
+ * view + the linear sampler into group(1) (texture@0 + sampler@1). When
+ * `paramsBuffer` is supplied (feat-20260621 D-2: `entry.params !== undefined`),
+ * appends the per-frame params UBO at binding 2 (uniform), matching the 3-entry
+ * `'fullscreen-post-with-params'` BGL. Omitting it yields the 2-entry shape
+ * param-less consumers degrade to (R-A7).
+ *
+ * When `depthTexView` + `depthSampler` are supplied (plan-strategy D-3:
+ * depth reads present), appends the depth texture view at binding 3 and the
+ * non-filtering depth sampler at binding 4, matching the 5-entry
+ * `'fullscreen-post-with-scene-depth'` BGL. Both must be supplied together
+ * (or both omitted for existing color-only consumers — AC-03 zero-regression).
+ */
+export declare function createFullscreenBindGroup(device: RhiDevice, bgl: BindGroupLayout, inputView: TextureView, sampler: Sampler | null, paramsBuffer?: Buffer | null, depthTexView?: TextureView | null, depthSampler?: Sampler | null, gbufferNormalView?: TextureView | null, gbufferEmissiveView?: TextureView | null): BindGroup | null;
+//# sourceMappingURL=fullscreen-post-process-pass.d.ts.map

package/dist/fullscreen-post-process-pass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fullscreen-post-process-pass.d.ts","sourceRoot":"","sources":["../src/fullscreen-post-process-pass.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EACf,MAAM,EACN,SAAS,EACT,QAAQ,EACR,oBAAoB,EACpB,OAAO,EACP,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAsB7B;;;;;;;;;GASG;AACH,MAAM,MAAM,yBAAyB,GAAG,OAAO,CAAC;AAIhD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,uBAAuB,GAAG,SAAS,CAAC;IACtD;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,oBAAoB,CAAC,EAAE,GAAG,SAAS,CAAC;CACzE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,CAAC,EAAE,yBAAyB,GAAG,SAAS,CAAC;CAC7D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACtC,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC;CACnC;AAID;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAChD;AAID;;;;GAIG;AACH,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE;QACtB,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;KAC7B,CAAC;CACH;AAmDD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAGxE;AAaD;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAI7C;;;;;GAKG;AACH,MAAM,WAAW,+BAA+B;IAC9C,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sFAAsF;IACtF,IAAI,CAAC,OAAO,EAAE,oBAAoB,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;IAClE;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAC5C,GAAG,EAAE,kCAAkC,EACvC,KAAK,EAAE,sBAAsB,EAC7B,iBAAiB,UAAQ,GACxB;IACD,eAAe,EAAE,eAAe,CAAC;IACjC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,YAAY,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,YAAY,EAAE,CACZ,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,OAAO,EACjB,YAAY,EAAE,MAAM,GAAG,IAAI,KACxB,+BAA+B,CAAC;CACtC,GAAG,IAAI,CAuDP;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,eAAe,EACpB,SAAS,EAAE,WAAW,EACtB,OAAO,EAAE,OAAO,GAAG,IAAI,EACvB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,EAC5B,YAAY,CAAC,EAAE,WAAW,GAAG,IAAI,EACjC,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,EAC7B,iBAAiB,CAAC,EAAE,WAAW,GAAG,IAAI,EACtC,mBAAmB,CAAC,EAAE,WAAW,GAAG,IAAI,GACvC,SAAS,GAAG,IAAI,CA8BlB"}

package/dist/glyph-text-layout-system.d.ts

@@ -0,0 +1,18 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { Handle } from '@forgeax/engine-types';
+import { type Result, TextError } from '@forgeax/engine-types';
+import type { GpuResourceStore } from './gpu-resource-store';
+/** Clear the per-entity bake + per-font material caches (test isolation). */
+export declare function resetGlyphBakeCache(): void;
+/**
+ * Lay out + bake every `GlyphText` entity, attaching MeshFilter + MeshRenderer
+ * on first observation and re-baking in place on a text / size / color change.
+ *
+ * @param world The ECS world holding the GlyphText entities.
+ * @returns `ok(void)` on a clean pass, or `err(TextError)` carrying the FIRST
+ *   structured failure (currently only `font-concurrency-exceeded`). Healthy
+ *   entities observed before the failing one are still baked.
+ */
+export declare function glyphTextLayoutSystem(world: World, gpuStore: GpuResourceStore): Result<void, TextError>;
+export declare function ensureGlyphMeshMaterialSlots(world: World, meshHandle: Handle<'MeshAsset', 'shared'>): void;
+//# sourceMappingURL=glyph-text-layout-system.d.ts.map

package/dist/glyph-text-layout-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyph-text-layout-system.d.ts","sourceRoot":"","sources":["../src/glyph-text-layout-system.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAgB,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAS/D,OAAO,KAAK,EAAa,MAAM,EAAqC,MAAM,uBAAuB,CAAC;AAClG,OAAO,EAAW,KAAK,MAAM,EAAE,SAAS,EAAc,MAAM,uBAAuB,CAAC;AAIpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AA0B7D,6EAA6E;AAC7E,wBAAgB,mBAAmB,IAAI,IAAI,CAI1C;AAsED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,gBAAgB,GACzB,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAwBzB;AA+KD,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,GACxC,IAAI,CAKN"}

package/dist/gpu-driven/batch-topology.d.ts

@@ -0,0 +1,124 @@
+import type { RenderSceneApplyResult, RenderSceneProjectionSlot } from '../render-scene-projection';
+import type { GpuDrivenDrawSnapshot, RenderableSnapshot } from '../render-system-extract';
+export interface GpuDrivenBatchKey {
+    readonly assetHandle: number;
+    readonly drawKind: 'indexed' | 'non-indexed';
+    readonly first: number;
+    readonly count: number;
+    readonly baseVertex: number;
+    readonly materialSlot: number;
+    readonly submeshIndex: number;
+    readonly passIndex: number;
+    readonly queue: number;
+    readonly topology: string;
+    readonly pipelineClass: string;
+    readonly materialResourceClass: string;
+    /** Material shader identity is part of topology, not a record-time guess. */
+    readonly materialClass: string;
+    /** Scene Fact resource revision invalidates stale resource bindings. */
+    readonly resourceRevision: number;
+    /** Scene Fact material revision keeps material payload changes isolated. */
+    readonly materialRevision: number;
+    /** Explicit alpha-test qualification (queue or alphaCutoff > 0). */
+    readonly alphaTest: boolean;
+    /** `true` means the raster state intentionally keeps both faces. */
+    readonly doubleSided: boolean;
+    /** Standard/custom PBR qualification used by the capability lane. */
+    readonly pbr: boolean;
+    /**
+     * ShadowCaster batch qualification; only explicit ineligible excludes a
+     * candidate. Unknown facts stay in the pool until the existing ShadowCaster
+     * dispatch and CascadeVolumeSet membership make the per-view decision.
+     */
+    readonly shadowCaster: boolean;
+}
+export interface GpuDrivenBatchSemantics {
+    readonly pipelineClass: string;
+    readonly materialClass: string;
+    readonly materialResourceClass: string;
+    readonly resourceRevision: number;
+    readonly materialRevision: number;
+    readonly alphaTest: boolean;
+    readonly doubleSided: boolean;
+    readonly pbr: boolean;
+    readonly shadowCaster: boolean;
+}
+export interface GpuDrivenCandidate {
+    readonly primitiveIndex: number;
+    readonly generation: number;
+    readonly drawItemIndex: number;
+    readonly instanceOrdinal: number;
+}
+export interface GpuDrivenBatch {
+    readonly batchId: number;
+    readonly generation: number;
+    readonly key: GpuDrivenBatchKey;
+    readonly candidates: readonly GpuDrivenCandidate[];
+    readonly visibleBase: number;
+    readonly visibleCapacity: number;
+    readonly indirectOffset: number;
+}
+export interface SubmissionPlan {
+    readonly revision: number;
+    readonly batches: readonly GpuDrivenBatch[];
+    readonly candidateCount: number;
+    readonly visibleCapacity: number;
+}
+export interface SubmissionCandidateMembershipEntry {
+    readonly batchId: number;
+    readonly candidate: GpuDrivenCandidate;
+}
+/**
+ * Immutable reverse membership for one submission topology.
+ *
+ * Candidate-domain owners publish stable primitive ids, while both the
+ * shadow view projector and cascade-local cache tokens need to answer the
+ * inverse question: which source batches contain this primitive? Keep that
+ * join beside the immutable SubmissionPlan so each consumer pays O(D) once
+ * per topology instead of rescanning every batch for every view/cascade.
+ */
+export interface SubmissionCandidateMembership {
+    readonly source: SubmissionPlan;
+    readonly byPrimitiveIndex: ReadonlyMap<number, readonly SubmissionCandidateMembershipEntry[]>;
+    /** O(1) lookup for batch metadata after a primitive-to-batch join. */
+    readonly byBatchId: ReadonlyMap<number, SubmissionPlan['batches'][number]>;
+}
+export declare function buildSubmissionCandidateMembership(source: SubmissionPlan): SubmissionCandidateMembership;
+/**
+ * Build a submission while retaining the source topology identity.
+ *
+ * Visibility is allowed to replace candidates and capacities per view, but it
+ * must not allocate a second batch identity or change indirect slot ownership.
+ * This helper is shared by the forward and shadow capability lanes so compact
+ * arrays, aligned bases, and indirect offsets have one producer.
+ */
+export declare function buildBatchAlignedSubmission(source: SubmissionPlan, candidatesByBatch: ReadonlyMap<number, readonly GpuDrivenCandidate[]>): SubmissionPlan;
+export interface BatchTopologyInspection {
+    readonly revision: number;
+    readonly batchCount: number;
+    readonly candidateCount: number;
+    readonly rebuilds: number;
+    readonly patches: number;
+    readonly ineligible: number;
+}
+export declare function deriveGpuDrivenBatchSemantics(snapshot: RenderableSnapshot, draw: GpuDrivenDrawSnapshot): GpuDrivenBatchSemantics;
+export declare function buildGpuDrivenBatchKey(snapshot: RenderableSnapshot, draw: GpuDrivenDrawSnapshot): GpuDrivenBatchKey;
+/** Stable compatibility grouping; per-view visibility never mutates this owner. */
+export declare class BatchTopology {
+    private readonly batches;
+    private readonly membershipByPrimitive;
+    private readonly ineligiblePrimitives;
+    private readonly generationByBatchId;
+    private readonly freeBatchIds;
+    private revision;
+    private rebuilds;
+    private patches;
+    private cachedPlan;
+    rebuild(slots: readonly RenderSceneProjectionSlot[]): void;
+    apply(delta: RenderSceneApplyResult): boolean;
+    plan(): SubmissionPlan;
+    inspect(): BatchTopologyInspection;
+    private add;
+    private remove;
+}
+//# sourceMappingURL=batch-topology.d.ts.map