@forgeax/engine-render 0.1.2

package/dist/record/helpers.d.ts

@@ -0,0 +1,101 @@
+import type { World } from '@forgeax/engine-ecs';
+import { type Mat4 } from '@forgeax/engine-math';
+import type { RenderSystemInternals } from '../render-system';
+import type { CameraSnapshot, MaterialSnapshot, SkyboxSnapshot, SkylightSnapshot } from '../render-system-extract';
+import type { RenderFrameState } from './frame-snapshot';
+/** Convert pass-owned shader definitions into the manifest's canonical variant key. */
+export declare function variantSetFromDefines(defines: Readonly<Record<string, string>> | undefined): string | undefined;
+/**
+ * Select the equirect source for the shared lazy projection.
+ *
+ * Skylight uses handle 0 as a real "solid-color ambient" sentinel, so nullish
+ * coalescing cannot distinguish "no equirect" from a valid snapshot. Prefer a
+ * non-zero Skylight handle and fall back to SkyboxBackground otherwise.
+ */
+export declare function selectLazyEquirectHandle(skylight: Pick<SkylightSnapshot, 'equirectHandle'> | undefined, skybox: Pick<SkyboxSnapshot, 'equirectHandle'> | undefined): number;
+/**
+ * feat-20260608-multi-light-warn-once M3: warn-once latch for directional
+ * N>1 overrun. Fires console.warn at most once per RenderSystem lifetime.
+ * Extracted as a pure helper so the warn-once logic is directly testable
+ * without a full recordFrame argument list (AC-05 (c)).
+ */
+export declare function warnMultiLightDirectional(frameState: Pick<RenderFrameState, 'warnedMultiLightDirectional'>, directionalCount: number, envOverride?: {
+    env?: {
+        NODE_ENV?: string;
+    };
+}): void;
+/**
+ * feat-20260608-multi-light-warn-once M3: warn-once latch for point light
+ * N>4 overrun (first-slice cap). Fires at most once per RenderSystem
+ * lifetime.
+ */
+export declare function warnMultiLightPoint(frameState: Pick<RenderFrameState, 'warnedMultiLightPoint'>, pointCount: number, envOverride?: {
+    env?: {
+        NODE_ENV?: string;
+    };
+}): void;
+/**
+ * feat-20260608-multi-light-warn-once M3: warn-once latch for spot light
+ * N>4 overrun (first-slice cap). Fires at most once per RenderSystem
+ * lifetime.
+ */
+export declare function warnMultiLightSpot(frameState: Pick<RenderFrameState, 'warnedMultiLightSpot'>, spotCount: number, envOverride?: {
+    env?: {
+        NODE_ENV?: string;
+    };
+}): void;
+/**
+ * feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w19:
+ * once-warn for >1 Skylight entity (first archetype hit wins). Fires at most
+ * once per RenderSystem lifetime and names the WINNING entity handle so the
+ * scene author can tell which Skylight is used and that the rest are ignored
+ * (F-8: warn carries conflicting entity info; charter P3 explicit failure with
+ * a warn-once signal floor, no per-frame flooding).
+ */
+export declare function warnMultiSkylight(frameState: Pick<RenderFrameState, 'warnedMultiSkylight'>, skylightCount: number, winningEntityHandle: number): void;
+/**
+ * feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w19:
+ * once-warn for >1 SkyboxBackground entity (mirrors warnMultiSkylight). Names
+ * the winning entity handle; fires once per RenderSystem lifetime.
+ */
+export declare function warnMultiSkybox(frameState: Pick<RenderFrameState, 'warnedMultiSkybox'>, skyboxCount: number, winningEntityHandle: number): void;
+/**
+ * feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w18:
+ * lazy equirect-to-cubemap projection trigger. Driven once per frame from
+ * `recordFrame` for the active equirect handle (Skylight's, or the
+ * SkyboxBackground's when no Skylight cubemap is present -- both reuse one
+ * handle). Implements the plan-strategy D-4 state machine:
+ *
+ *   undefined (no entry) -> resolve POD + fire-and-forget projection; the
+ *                                    store selects rgba8 output on WebGL2
+ *                                     (the store writes status:'pending'
+ *                                     synchronously, so this launches once)
+ *   pending                        -> in flight; bind white fallback (no fire)
+ *   ready                          -> bound by recordMainPass's IBL cache check
+ *   failed                         -> fire EquirectProjectionFailedError ONCE
+ *                                     per handle (R-2/AC-09 no retry)
+ * Fire-and-forget: `_uploadCubemapFromEquirect` is invoked WITHOUT await so the
+ * record stay synchronous; the store mutates its own status map and (on
+ * success) the per-device IblPipelineCache, which recordMainPass reads on a
+ * later frame. The structured error from a fire-and-forget failure is reported
+ * via the explicit `status === 'failed'` arm here (read on the next frame), not
+ * by awaiting the promise (which would block record).
+ */
+export declare function driveLazyEquirectProjection(internals: RenderSystemInternals, world: World, frameState: Pick<RenderFrameState, 'firedEquirectProjectionFailedHandles'>, equirectHandle: number): void;
+/**
+ * Returns true when a MaterialSnapshot uses a builtin standard/PBR shader
+ * that will render black with zero lights.
+ *
+ * The default mid-grey fallback (materialShaderId === undefined) is excluded
+ * — it routes through defaultMaterialSnapshot and never triggers the
+ * zero-light warning. Custom shaders are also excluded: their lighting
+ * contract is authored by the shader and cannot be inferred from this
+ * generic diagnostic.
+ *
+ * @internal — exported so AC-02 zero-light-warning test can anchor to
+ * the production implementation rather than a test-local copy.
+ */
+export declare function isLitMaterialSnapshot(material: MaterialSnapshot): boolean;
+export declare function computeViewMatrix(camera: CameraSnapshot): Mat4;
+export declare function computeProjectionMatrix(camera: CameraSnapshot): Mat4;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/record/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/record/helpers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,KAAK,IAAI,EAAQ,MAAM,sBAAsB,CAAC;AAMvD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,uFAAuF;AACvF,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,GACpD,MAAM,GAAG,SAAS,CAQpB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,IAAI,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,SAAS,EAC9D,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,gBAAgB,CAAC,GAAG,SAAS,GACzD,MAAM,CAGR;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,IAAI,CAAC,gBAAgB,EAAE,6BAA6B,CAAC,EACjE,gBAAgB,EAAE,MAAM,EACxB,WAAW,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC5C,IAAI,CAkBN;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,IAAI,CAAC,gBAAgB,EAAE,uBAAuB,CAAC,EAC3D,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC5C,IAAI,CAkBN;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,IAAI,CAAC,gBAAgB,EAAE,sBAAsB,CAAC,EAC1D,SAAS,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC5C,IAAI,CAkBN;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,IAAI,CAAC,gBAAgB,EAAE,qBAAqB,CAAC,EACzD,aAAa,EAAE,MAAM,EACrB,mBAAmB,EAAE,MAAM,GAC1B,IAAI,CAUN;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,IAAI,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,EACvD,WAAW,EAAE,MAAM,EACnB,mBAAmB,EAAE,MAAM,GAC1B,IAAI,CAUN;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,qBAAqB,EAChC,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,IAAI,CAAC,gBAAgB,EAAE,sCAAsC,CAAC,EAC1E,cAAc,EAAE,MAAM,GACrB,IAAI,CAgCN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAEzE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAQ9D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAoBpE"}

package/dist/record/index.d.ts

@@ -0,0 +1,15 @@
+export * from './frame';
+export * from './frame-observation';
+export * from './frame-snapshot';
+export * from './frame-targets';
+export * from './helpers';
+export * from './main-pass';
+export * from './main-pass-material';
+export * from './main-pass-skin';
+export * from './main-pass-sprite';
+export * from './material-payload';
+export * from './mesh-ssbo';
+export * from './shadow-pass';
+export * from './skybox-post-pass';
+export * from './view-ubo';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/record/index.ts"],"names":[],"mappings":"AACA,cAAc,SAAS,CAAC;AACxB,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC"}

package/dist/record/main-pass-geometry.d.ts

@@ -0,0 +1,20 @@
+import { type BindGroup, type RhiRenderPassEncoder } from '@forgeax/engine-rhi';
+import type { PassKind } from '@forgeax/engine-types';
+import type { _InternalRenderPipelineContext } from '../render-pipeline-context';
+import type { MaterialSnapshot } from '../render-system-extract';
+/**
+ * feat-20260704 M3/w19: per-entity geometry (main colour) draw loop, extracted
+ * verbatim from recordMainPass. Walks `c.validatedOrdered`, selects the
+ * per-entity / per-submesh PBR / unlit / skin pipeline, uploads the per-submesh
+ * material UBO slices, binds view / material / mesh / instances bind groups, and
+ * issues the per-submesh draws into the already-begun geometry `pass`. Fully-
+ * transparent entities are skipped here (drawn in the LDR blend sub-pass);
+ * mixed meshes draw their opaque submeshes here and skip transparent submeshes.
+ * The pass-selector match set, per-entity material-slot start table, MSAA sample
+ * count, group(2) bind group, and the shared per-submesh material BG builder are
+ * threaded in explicitly.
+ *
+ * @internal
+ */
+export declare function recordGeometryDraws(c: _InternalRenderPipelineContext, pass: RhiRenderPassEncoder, matchedIndices: Set<number> | null, materialSlotIndices: readonly (readonly number[])[], sampleCount: number, meshGroup2: BindGroup | null, resolveMaterialBindGroup: (materialSlot: number, submeshMaterial: MaterialSnapshot, entityKey: number) => BindGroup, passKind?: PassKind): void;
+//# sourceMappingURL=main-pass-geometry.d.ts.map

package/dist/record/main-pass-geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main-pass-geometry.d.ts","sourceRoot":"","sources":["../../src/record/main-pass-geometry.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,SAAS,EAId,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,QAAQ,EAAqB,MAAM,uBAAuB,CAAC;AAezE,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AAEjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AA0FjE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,8BAA8B,EACjC,IAAI,EAAE,oBAAoB,EAC1B,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,EAClC,mBAAmB,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EACnD,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,SAAS,GAAG,IAAI,EAC5B,wBAAwB,EAAE,CACxB,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,gBAAgB,EACjC,SAAS,EAAE,MAAM,KACd,SAAS,EACd,QAAQ,GAAE,QAAoB,GAC7B,IAAI,CA0qBN"}

package/dist/record/main-pass-material.d.ts

@@ -0,0 +1,173 @@
+import type { World } from '@forgeax/engine-ecs';
+import { type BindGroup, type BindGroupLayout, type Buffer, type RenderPipeline, type Result, RhiError } from '@forgeax/engine-rhi';
+import type { DerivedMaterialInterface, Handle, MaterialRenderState, PassKind, PrimitiveTopology } from '@forgeax/engine-types';
+import type { DynamicTextureStore } from '../dynamic-texture-store';
+import type { GpuResourceStore } from '../gpu-resource-store';
+import { type SkylightBindGroupResources } from '../ibl/skylight-bind-group';
+import type { PipelineState, RenderSystemRuntime } from '../render-system';
+import type { MaterialSnapshot } from '../render-system-extract';
+import type { MaterialRenderProjection } from '../renderer/material/assembly.js';
+import { type MaterialDrawRoute, type MaterialPipelineMiss, type MaterialPipelineReady, type MaterialReadiness, type MaterialRenderReady } from '../renderer/material/pipeline-projection.js';
+import type { BindGroupCounts, MaterialBgAssemblyCacheEntry } from './frame-snapshot';
+export { applyParamSnapshotToUbo, writeMaterialSnapshotPayload, } from './material-payload';
+/**
+ * feat-20260604-learn-render-4.10-anti-aliasing-msaa M2 / w9: pick the static
+ * unlit geometry pipeline handle for a (tonemapActive x msaaActive)
+ * combination. The four mode axes (LDR/HDR x single/MSAA) map to the 14 static
+ * pipeline handles built in createRenderer (7 base + 7 count=4 variants). A
+ * pipeline's `multisample.count` must match the colour-attachment sampleCount,
+ * so the count=4 variant is required whenever the camera carries
+ * `antialias === 'msaa'`. Returns null when the requested pipeline was not
+ * built (empty-manifest path / MSAA variant build failure) -- the caller fires
+ * a structured `shader-compile-failed` on the null-narrow.
+ */
+export declare function selectGeometryPipeline(pipelineState: PipelineState, tonemapActive: boolean, msaaActive: boolean): RenderPipeline | null;
+/**
+ * Resolve a cooked material projection for record. The record stage receives
+ * the already-resolved projection and an immutable artifact lookup; it never
+ * follows parent GUIDs, reads authored material state, or invokes a compiler.
+ * A missing or mismatched artifact is an explicit route miss so callers cannot
+ * silently substitute a default shader.
+ */
+export declare function selectCookedMaterialPipelineForRender(args: {
+    readonly projection: MaterialRenderProjection;
+    readonly lookupArtifact: (key: string) => import('@forgeax/engine-shader').MaterialRuntimeArtifact | undefined;
+}): MaterialPipelineReady | MaterialPipelineMiss;
+/** Route a record-stage draw through the canonical readiness result. */
+export declare function selectMaterialDrawForRender<TPipeline>(args: {
+    readonly readiness: MaterialReadiness;
+    readonly buildPipeline: (ready: MaterialRenderReady) => TPipeline;
+    readonly reportedDiagnosticKeys: Set<string>;
+}): MaterialDrawRoute<TPipeline>;
+/**
+ * feat-city-glb Bug 5 (per-submesh transparency): true when EVERY submesh
+ * material of the entity is transparent (blend). Used by the geometry pass to
+ * decide whether to skip the whole entity (fully transparent → deferred to the
+ * blend sub-pass) vs. draw its opaque submeshes and skip only the transparent
+ * ones per-submesh.
+ *
+ * Falls back to the entity-level `material.transparent` when `materials` is
+ * absent (single-material entities / test fixtures), byte-identical to the
+ * pre-fix whole-entity gate.
+ *
+ * @internal
+ */
+export declare function isEntityFullyTransparent(source: {
+    readonly material: MaterialSnapshot;
+    readonly materials?: readonly MaterialSnapshot[];
+}): boolean;
+/**
+ * feat-city-glb Bug 5: true when the entity has at least one transparent AND at
+ * least one opaque submesh — i.e. it must be drawn in BOTH the geometry pass
+ * (opaque submeshes) and the blend sub-pass (transparent submeshes). A pure-
+ * opaque or pure-transparent entity returns false (handled by the whole-entity
+ * fast paths).
+ *
+ * @internal
+ */
+export declare function entityHasTransparentSubmesh(source: {
+    readonly material: MaterialSnapshot;
+    readonly materials?: readonly MaterialSnapshot[];
+}): boolean;
+/**
+ * Selects the PSO for a transparent (or any generic materialShaderId) draw
+ * via the runtime's per-MaterialShader pipeline cache. Returns a
+ * structured RhiError on cache miss / pending build -- the caller MUST
+ * surface this via the error registry rather than substituting a silent
+ * fallback (charter P3 explicit failure).
+ *
+ * The `getMaterialShaderPipeline` argument mirrors
+ * {@link RenderSystemRuntime.getMaterialShaderPipeline}'s 9-arg signature
+ * but is injected so the helper is unit-testable with a plain
+ * `() => null` stand-in. The helper threads only the inputs the caller
+ * already has on the dispatch entry -- it never reads from
+ * MaterialAsset internals (plan-strategy section 5.6 gate R-H).
+ *
+ * @internal
+ */
+export declare function selectMaterialPipelineForRender(args: {
+    readonly materialShaderId: string;
+    readonly isHdr: boolean;
+    readonly renderState?: MaterialRenderState | undefined;
+    readonly topology?: PrimitiveTopology | undefined;
+    readonly indexFormat?: 'uint16' | 'uint32' | undefined;
+    readonly variantSet?: string | undefined;
+    readonly sampleCount?: number | undefined;
+    readonly getMaterialShaderPipeline: ((materialShaderId: string, isHdr: boolean, renderState?: MaterialRenderState, topology?: PrimitiveTopology, indexFormat?: 'uint16' | 'uint32', variantSet?: string, passKind?: PassKind, meshAttributes?: import('@forgeax/engine-types').VertexAttributeMap, sampleCount?: number) => RenderPipeline | null) | undefined;
+}): Result<RenderPipeline, RhiError>;
+export declare function residentTextureView(world: World, store: GpuResourceStore, runtime: RenderSystemRuntime, handle: Handle<'TextureAsset', 'shared'>, worldId?: number): any | undefined;
+export declare function videoTextureView(world: World, store: DynamicTextureStore | undefined, runtime: RenderSystemRuntime, entityKey: number, clip: Handle<'VideoAsset', 'shared'>, highPerfAvailable: boolean): any | undefined;
+/**
+ * feat-20260621-learn-render-5-5-parallax M2 / w8 (D-3): ordered user-region
+ * texture field names for a material's bind-group assembly, derived from the
+ * shader's paramSchema via the `derive()` SSOT (insertion order = sampler/
+ * texture pair order in derive().bglEntries). An unavailable schema yields no
+ * inferred layout fields.
+ */
+export declare function userRegionTextureFieldOrder(projection: DerivedMaterialInterface | undefined): readonly string[];
+/**
+ * feat-20260621-learn-render-5-5-parallax M2 / w8: the fallback texture view
+ * for a user-region field when no handle is provided (graceful, charter P3).
+ * normalTexture decodes to a flat tangent normal; everything else (baseColor,
+ * MR, height, ...) uses the 1x1 white default (height white -> zero displacement).
+ */
+export declare function defaultViewForUserRegionField(field: string, pipelineState: PipelineState): any;
+/**
+ * feat-20260527-sprite-nineslice M4 / w17 (AC-16): once-per-renderable
+ * detection of "Transform.scale below the four 9-slice corner anchors". Pure
+ * helper extracted out of recordFrame so unit tests can drive it without a
+ * GPU device — the recordFrame loop calls this with its `transformWorld` /
+ * `slices` / `renderableIndex` / `seenIndices` / `metrics` arguments.
+ *
+ * The scale-vs-anchor formula mirrors plan-strategy §D-3 — the world x scale must
+ * accommodate `|slices.x| + |slices.z|`, and `scaleY` must accommodate
+ * `|slices.y| + |slices.w|`. Slices ≡ all zero is a no-op (legacy quad
+ * path); a breach increments `nineslice.scale-too-small` exactly once per
+ * `renderableIndex` per RenderSystem lifetime via the `seenIndices` Set
+ * (the same warn-once anchor pattern used for missing-texture sprites).
+ *
+ * @param transformWorld The entity's resolved Transform.world mat4 (16 floats column-major).
+ * @param slices         The four anchor distances `[left, top, right, bottom]`
+ *                       (sentinel `bottom < 0` for tile mode is consumed via abs()).
+ * @param renderableIndex The entity index into the validated renderables list.
+ * @param seenIndices    The per-frame-state guard Set; entries are added on increment.
+ * @param metrics        The per-Renderer EngineMetrics counter.
+ * @internal — exported for unit-test access (w17).
+ */
+export declare function detectNineSliceScaleTooSmall(transformWorld: Float32Array, slices: readonly [number, number, number, number], renderableIndex: number, seenIndices: Set<number>, metrics: {
+    increment(name: string): void;
+}): void;
+/**
+ * feat-20260704 M3/w19: shared per-submesh material bind-group assembly, hoisted
+ * from the `buildPerSubmeshMaterialBg` closure inside recordMainPass so both the
+ * geometry pass and the LDR blend sub-pass (extracted to separate functions)
+ * call the identical layout.
+ *
+ * feat-city-glb Bug 5 (per-submesh transparency): a transparent PBR submesh
+ * binds the identical metallic/roughness/normal/emissive/occlusion +
+ * Skylight layout the geometry pass uses (the sub-pass previously bound a
+ * sprite-only BG, which cannot render a PBR decal). The per-frame closure state
+ * (runtime / pipelineState / world / store / skylightResources / the shared
+ * material BG cache + counters) is threaded through `deps`; the caller passes
+ * the per-submesh material snapshot + entityKey (video texture routing) and sets
+ * the dynamic UBO offset itself.
+ *
+ * @internal
+ */
+export interface PerSubmeshMaterialBgDeps {
+    readonly runtime: RenderSystemRuntime;
+    readonly pipelineState: PipelineState;
+    readonly world: World;
+    readonly store: GpuResourceStore;
+    readonly materialSlice: number;
+    readonly videoHighPerfAvailable: boolean;
+    readonly skylightResources: SkylightBindGroupResources;
+    readonly materialBgShared: Map<string, WeakMap<object, unknown>>;
+    /** Cross-frame final BG reuse keyed by the stable source material handle. */
+    readonly materialBgAssemblyCache: Map<number, MaterialBgAssemblyCacheEntry>;
+    readonly bindGroupCounts: BindGroupCounts;
+}
+/** @internal Exported only so buffer-generation invalidation stays regression-tested. */
+export declare function isMaterialBgAssemblyCacheHit(cached: MaterialBgAssemblyCacheEntry | undefined, material: MaterialSnapshot, materialBgl: BindGroupLayout, materialBuffer: Buffer, skylightResources: SkylightBindGroupResources, materialResourceEpoch: number): cached is MaterialBgAssemblyCacheEntry;
+export declare function buildPerSubmeshMaterialBg(deps: PerSubmeshMaterialBgDeps, submeshMaterial: MaterialSnapshot, entityKey: number): BindGroup;
+//# sourceMappingURL=main-pass-material.d.ts.map

package/dist/record/main-pass-material.d.ts.map

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

package/dist/record/main-pass-skin.d.ts

@@ -0,0 +1,46 @@
+/**
+ * feat-20260612-skin-palette-per-frame-upload M3 / m3-2: pure helper that
+ * builds the `setBindGroup(2, ...)` dynamic-offset tuple at the skin /
+ * non-skin draw site.
+ *
+ * - Skin entries (`skinByteOffset !== undefined`) bind a 3-entry mesh-array
+ *   BGL (binding 0 mesh-array UBO, bindings 1/2 current/previous palette UBOs;
+ *   all `hasDynamicOffset: true`), so the tuple carries three offsets: the
+ *   mesh slot follows the per-entity 256-byte stride and both palette slots
+ *   carry the per-entity cursor M2 m2-6 wrote into
+ *   `entry.source.skin.byteOffset`.
+ * - Non-skin entries bind the URP / HDRP 1-entry mesh-array BGL, so the
+ *   tuple carries only the mesh slot offset (length 1). Adding palette
+ *   offset there would trip WebGPU validation against the 1-binding BGL.
+ *
+ * Extracted from the inline `group2DynamicOffsets = [i * MESH_PER_ENTITY_STRIDE,
+ * 0]` site (PR #353 stub) so the contract `group2DynamicOffsets[1] ===
+ * byteOffset` is testable from a focused unit fixture without driving
+ * recordFrame end-to-end.
+ *
+ * @internal -- exported for unit test access (m3-1)
+ */
+export declare function _computeSkinGroup2DynOffsets(meshSlotIdx: number, skinByteOffset: number | undefined): readonly number[];
+/**
+ * feat-20260612-skin-palette-per-frame-upload M3 / m3-2: read-side accessor
+ * for the per-frame skin BG cache miss / hit counters published by the
+ * record stage. Mirrors the existing `bindGroupCounts.createBindGroup`
+ * surface but scoped to the skin-mesh BG cache so the m3-1 acceptanceCheck
+ * (miss=1 + hit=N-1 across N skinned entities sharing one allocator buffer
+ * + mesh SSBO) can be observed without traversing the full record-stage
+ * dispatch log. The PipelineState carries the mutable counter object
+ * (`_skinBgCacheStats: { miss, hit }`); the record-stage cache miss / hit
+ * branches bump it; this accessor returns the live reference.
+ *
+ * @internal -- exported for unit test access (m3-1)
+ */
+export declare function _skinBgCacheStats(pipelineState: {
+    readonly _skinBgCacheStats: {
+        miss: number;
+        hit: number;
+    };
+}): {
+    miss: number;
+    hit: number;
+};
+//# sourceMappingURL=main-pass-skin.d.ts.map

package/dist/record/main-pass-skin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main-pass-skin.d.ts","sourceRoot":"","sources":["../../src/record/main-pass-skin.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,SAAS,MAAM,EAAE,CAInB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE;IAC/C,QAAQ,CAAC,iBAAiB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3D,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAEhC"}

package/dist/record/main-pass-sprite-draws.d.ts

@@ -0,0 +1,18 @@
+import { type BindGroup, type RhiRenderPassEncoder } from '@forgeax/engine-rhi';
+import { type SkylightBindGroupResources } from '../ibl/skylight-bind-group';
+import type { _InternalRenderPipelineContext } from '../render-pipeline-context';
+import type { MaterialSnapshot } from '../render-system-extract';
+/**
+ * feat-20260704 M3/w19: LDR sprite split sub-pass, extracted verbatim from
+ * recordMainPass. Runs after the geometry pass when there are sprite / LDR
+ * transparent entities and the split path is active (splitLdrSprite && a raw
+ * unorm swap-chain view exists). Ends the geometry `pass`, opens a `spritePass`
+ * on the resolved transparent-pass view (loadOp=load), draws the sprite / sprite-lit
+ * entities (fold-instanced where possible) then the generic per-submesh
+ * transparent PBR submeshes, and ends the sprite pass. Returns the updated
+ * `geometryPassEnded` flag so the caller skips the unconditional pass.end().
+ *
+ * @internal
+ */
+export declare function recordSpritePass(c: _InternalRenderPipelineContext, pass: RhiRenderPassEncoder, matchedIndices: Set<number> | null, materialSlotIndices: readonly (readonly number[])[], sampleCount: number, resolveMaterialBindGroup: (materialSlot: number, submeshMaterial: MaterialSnapshot, entityKey: number) => BindGroup, skylightResources: SkylightBindGroupResources, graphPass?: RhiRenderPassEncoder): boolean;
+//# sourceMappingURL=main-pass-sprite-draws.d.ts.map

package/dist/record/main-pass-sprite-draws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main-pass-sprite-draws.d.ts","sourceRoot":"","sources":["../../src/record/main-pass-sprite-draws.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,SAAS,EAId,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAQ7B,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,4BAA4B,CAAC;AAMpC,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AAEjF,OAAO,KAAK,EAAE,gBAAgB,EAA2B,MAAM,0BAA0B,CAAC;AAW1F;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,EAAE,8BAA8B,EACjC,IAAI,EAAE,oBAAoB,EAC1B,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,EAClC,mBAAmB,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EACnD,WAAW,EAAE,MAAM,EACnB,wBAAwB,EAAE,CACxB,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,gBAAgB,EACjC,SAAS,EAAE,MAAM,KACd,SAAS,EACd,iBAAiB,EAAE,0BAA0B,EAC7C,SAAS,CAAC,EAAE,oBAAoB,GAC/B,OAAO,CAiPT"}

package/dist/record/main-pass-sprite.d.ts

@@ -0,0 +1,69 @@
+import type { MaterialSnapshot, SpriteInstancesSnapshot } from '../render-system-extract';
+/** Re-export of the extract-stage snapshot so test sites can build it. */
+export type { SpriteInstancesSnapshot };
+/**
+ * Interleave SpriteInstances transforms (stride 16) and regions (stride 4)
+ * into a single Float32Array with stride 20 (= 80 bytes per instance,
+ * plan-strategy D-1). Callers feed the output buffer to
+ * `device.queue.writeBuffer` against the per-entity GPU buffer slot.
+ *
+ * Pre-conditions guaranteed by render-system-extract M3 / w10:
+ *   - `transforms.length` is a multiple of 16
+ *   - `regions.length` is a multiple of 4
+ *   - `transforms.length / 16 === regions.length / 4`
+ *
+ * Violations fire `sprite-instances-count-mismatch` at the extract entry and
+ * never reach this helper. The helper itself does NOT re-validate the
+ * pre-conditions — single-validator invariant (charter P4 explicit failure
+ * routed once at the extract boundary; downstream consumers trust the
+ * snapshot shape).
+ *
+ * @param transforms — packed mat4 (column-major) Float32Array (stride 16).
+ * @param regions    — packed vec4 [uMin, vMin, uW, vH] Float32Array (stride 4).
+ * @returns interleaved Float32Array with length `(transforms.length + regions.length)`.
+ */
+export declare function interleaveSpriteInstanceBuffer(transforms: Float32Array, regions: Float32Array, previousTransforms?: Float32Array | undefined, includePrevious?: boolean): Float32Array;
+/**
+ * Boolean side of the per-entity sprite-pass GPU buffer cache fingerprint
+ * check. Returns true iff the existing entry is byte-for-byte safe to reuse:
+ *
+ *   - `entry` exists (the entity has been recorded at least once);
+ *   - `entry.uploadedArchVersion === snapshot.archVersion` (archetype
+ *     storage has not been re-allocated since last upload);
+ *   - `entry.uploadedByteLength === requestedBytes` (byte count matches the
+ *     interleaved layout this frame would write).
+ *
+ * The record stage gates the `createBuffer + queue.writeBuffer` round on the
+ * negation of this predicate; a hit short-circuits to a `writeBuffer`-only
+ * refresh against the existing GPU buffer.
+ *
+ * @param entry — cached `InstanceBufferCacheEntry` for this `cacheKey`, or
+ *   `undefined` if the entity has never been recorded.
+ * @param snapshot — current frame's snapshot (carries `cacheKey + archVersion`).
+ * @param requestedBytes — `transforms.byteLength + regions.byteLength` =
+ *   80 * `instanceCount` for SpriteInstances (D-1 interleaved layout).
+ */
+export declare function spriteInstancesCacheHit(entry: import('../instance-buffer-cache').InstanceBufferCacheEntry | undefined, snapshot: SpriteInstancesSnapshot, requestedBytes: number): boolean;
+/**
+ * Decides whether the LDR (tonemapActive=false) main pass needs the
+ * sprite-style split into two serial sub-passes (geometry sRGB + transparent
+ * unorm). Triggered by any validated dispatch entry carrying
+ * `material.transparent === true` — derived by the extract stage from
+ * `passes[0].renderState.blend !== undefined` (post-feat-20260626-collapse
+ * SSOT, plan-strategy D-3; MaterialPass no longer carries a
+ * dedicated `transparent` field).
+ *
+ * feat-20260625-refactor-sprite-as-transparent-mesh M3 / w13: the M2 union
+ * with `shadingModel === 'sprite'` is gone — sprite materials now declare
+ * `transparent: true` on their pass descriptor (or extract folds it onto
+ * `MaterialSnapshot.transparent`), so the legacy arm is redundant.
+ *
+ * @internal
+ */
+export declare function computeSplitLdrSprite(validatedOrdered: readonly ({
+    readonly source: {
+        readonly material: MaterialSnapshot;
+        readonly materials?: readonly MaterialSnapshot[];
+    };
+} | undefined)[], tonemapActive: boolean): boolean;
+//# sourceMappingURL=main-pass-sprite.d.ts.map

package/dist/record/main-pass-sprite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main-pass-sprite.d.ts","sourceRoot":"","sources":["../../src/record/main-pass-sprite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAqB1F,0EAA0E;AAC1E,YAAY,EAAE,uBAAuB,EAAE,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,YAAY,EACxB,OAAO,EAAE,YAAY,EACrB,kBAAkB,GAAE,YAAY,GAAG,SAAqB,EACxD,eAAe,UAAO,GACrB,YAAY,CAoBd;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,0BAA0B,EAAE,wBAAwB,GAAG,SAAS,EAC9E,QAAQ,EAAE,uBAAuB,EACjC,cAAc,EAAE,MAAM,GACrB,OAAO,CAKT;AAgBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,gBAAgB,EAAE,SAAS,CACvB;IACE,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;QACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;KAClD,CAAC;CACH,GACD,SAAS,CACZ,EAAE,EACH,aAAa,EAAE,OAAO,GACrB,OAAO,CAqBT"}

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

@@ -0,0 +1,20 @@
+import { type RhiRenderPassEncoder, type TextureView } from '@forgeax/engine-rhi';
+import type { PassKind, PassSelector } from '@forgeax/engine-types';
+import type { _InternalRenderPipelineContext } from '../render-pipeline-context';
+export type MainPassOptions = {
+    readonly colorViews?: readonly (TextureView | null)[];
+    readonly colorFormats?: readonly GPUTextureFormat[];
+    readonly depthView?: TextureView | null;
+    readonly passKind?: PassKind;
+    readonly clearColor?: readonly [number, number, number, number];
+};
+/**
+ * feat-20260529-rendergraph-pass-abstraction M4 / w13b: main forward
+ * (geometry) pass recording, extracted verbatim from recordFrame. Uses the
+ * SHARED frame encoder (c.encoder); the geometry + optional LDR sprite-split
+ * sub-pass write into geometryColorView (HDR target or swap-chain view).
+ * Driven by the render-graph 'main' pass execute closure.
+ */
+export declare function recordMainPass(c: _InternalRenderPipelineContext, selector?: PassSelector, options?: MainPassOptions, graphPass?: RhiRenderPassEncoder): void;
+export declare function encodeMainPass(c: _InternalRenderPipelineContext, pass: RhiRenderPassEncoder, selector?: PassSelector, options?: MainPassOptions): void;
+//# sourceMappingURL=main-pass.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"main-pass.d.ts","sourceRoot":"","sources":["../../src/record/main-pass.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,oBAAoB,EACzB,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAU,QAAQ,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAM5E,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AAiBjF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAAE,CAAC;IACtD,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACjE,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,8BAA8B,EACjC,QAAQ,CAAC,EAAE,YAAY,EACvB,OAAO,CAAC,EAAE,eAAe,EACzB,SAAS,CAAC,EAAE,oBAAoB,GAC/B,IAAI,CAghBN;AAED,wBAAgB,cAAc,CAC5B,CAAC,EAAE,8BAA8B,EACjC,IAAI,EAAE,oBAAoB,EAC1B,QAAQ,CAAC,EAAE,YAAY,EACvB,OAAO,CAAC,EAAE,eAAe,GACxB,IAAI,CAEN"}

package/dist/record/material-payload.d.ts

@@ -0,0 +1,43 @@
+import type { DerivedMaterialInterface, ParamSchemaEntry } from '@forgeax/engine-types';
+import { type derive, type MaterialError, type Result } from '@forgeax/engine-types';
+import { type ParamSchemaProjectionCensus } from '../param-schema-projection-census';
+import type { MaterialSnapshot } from '../render-system-extract';
+export type MaterialUboPayload = ArrayBuffer | Uint8Array | Float32Array;
+export declare function materialUboFloatView(payload: MaterialUboPayload): Float32Array;
+export declare function derivedParamSchema(schema: readonly ParamSchemaEntry[], paramSchemaProjectionCensus?: ParamSchemaProjectionCensus): ReturnType<typeof derive>;
+export declare function materialBindingByteLength(schema: readonly ParamSchemaEntry[] | undefined, fallbackBytes: number, paramSchemaProjectionCensus?: ParamSchemaProjectionCensus): number;
+export interface DerivedMaterialPayloadCoordinate {
+    readonly set?: number;
+    readonly transform?: {
+        readonly offset?: readonly [number, number];
+        readonly scale?: readonly [number, number];
+        readonly rotation?: number;
+    };
+    readonly physicalUvScale?: readonly [number, number];
+}
+export interface DerivedMaterialSlotPlan {
+    readonly layout: ReturnType<typeof derive>['uboLayout'];
+    readonly numericMembers: ReturnType<typeof derive>['numericMembers'];
+    readonly coordinateRecords: ReturnType<typeof derive>['coordinateRecords'];
+    readonly layoutIdentity: string;
+    readonly totalBytes: number;
+}
+export interface DerivedMaterialPayloadInput {
+    readonly material: string;
+    readonly schema: readonly ParamSchemaEntry[] | undefined;
+    readonly projection?: DerivedMaterialInterface;
+    readonly values: Readonly<Record<string, number | readonly number[] | string | undefined>>;
+    readonly coordinates: Readonly<Record<string, DerivedMaterialPayloadCoordinate>> | ReadonlyMap<string, DerivedMaterialPayloadCoordinate>;
+    readonly capacityBytes?: number;
+    readonly paramSchemaProjectionCensus?: ParamSchemaProjectionCensus;
+}
+export declare function createDerivedMaterialSlotPlan(schema: readonly ParamSchemaEntry[]): DerivedMaterialSlotPlan;
+export declare function writeDerivedMaterialPayload(input: DerivedMaterialPayloadInput): Result<Uint8Array, MaterialError>;
+/**
+ * Build one record-stage payload from the typed extract projection. The record
+ * path does not reconstruct authored values or texture coordinates: the
+ * projection is the only input that can satisfy the derived interface.
+ */
+export declare function writeMaterialSnapshotPayload(material: MaterialSnapshot, capacityBytes?: number, paramSchemaProjectionCensus?: ParamSchemaProjectionCensus): Result<Uint8Array, MaterialError>;
+export declare function applyParamSnapshotToUbo(payload: MaterialUboPayload, paramSchema: readonly ParamSchemaEntry[] | undefined, paramSnapshot: Readonly<Record<string, number | readonly number[] | string | undefined>> | undefined, paramSchemaProjectionCensus?: ParamSchemaProjectionCensus): void;
+//# sourceMappingURL=material-payload.d.ts.map

package/dist/record/material-payload.d.ts.map

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

package/dist/record/material-slot-plan.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A frame-local material table. Repeated snapshot objects share one UBO slot;
+ * each renderable keeps only the slot index used by each authored material.
+ */
+export interface MaterialSlotPlan<T extends object> {
+    readonly slotIndices: readonly (readonly number[])[];
+    readonly slots: readonly T[];
+    /** Index of the first renderable that referenced each slot. */
+    readonly slotOwners: readonly number[];
+}
+/**
+ * Intern identical material snapshots into one frame-local slot table.
+ * Snapshot identity is the extract layer's invalidation token, so this keeps
+ * the same correctness boundary while avoiding duplicate payload assembly and
+ * upload for repeated scene instances.
+ */
+export declare function buildMaterialSlotPlan<T extends object>(materialGroups: readonly (readonly T[])[]): MaterialSlotPlan<T>;
+/**
+ * Return the largest complete renderable prefix supported by a shared
+ * mesh/material capacity. Mesh rows consume one slot per renderable; material
+ * rows use the deduplicated slot indices assigned in first-seen order.
+ */
+export declare function findRenderablePrefixForSlotCapacity(materialSlotIndices: readonly (readonly number[])[], slotCapacity: number): number;
+/** Count material slots reachable from a prefix of a first-seen slot plan. */
+export declare function materialSlotCountForPrefix(materialSlotIndices: readonly (readonly number[])[], renderableCount: number): number;
+//# sourceMappingURL=material-slot-plan.d.ts.map

package/dist/record/material-slot-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"material-slot-plan.d.ts","sourceRoot":"","sources":["../../src/record/material-slot-plan.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,MAAM;IAChD,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IACrD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,EACpD,cAAc,EAAE,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,GACxC,gBAAgB,CAAC,CAAC,CAAC,CAgBrB;AAED;;;;GAIG;AACH,wBAAgB,mCAAmC,CACjD,mBAAmB,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EACnD,YAAY,EAAE,MAAM,GACnB,MAAM,CAUR;AAED,8EAA8E;AAC9E,wBAAgB,0BAA0B,CACxC,mBAAmB,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EACnD,eAAe,EAAE,MAAM,GACtB,MAAM,CAMR"}