@ifc-lite/renderer 1.49.0 → 1.50.0

package/dist/shadow-occluders.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Occluder collection for the sun shadow depth pass (issue #2670, Phase 2a).
+ *
+ * Turns the scene's three GPU draw lists into a flat {@link ShadowOccluderDraw}
+ * array the {@link ShadowPass} rasterises. The whole point of this module is
+ * the maintainer's acceptance criterion: EVERY geometry path must cast, or part
+ * of the model silently stops shadowing. So each of the four paths —
+ *
+ *   • flat colour batches         → kind 'flat'
+ *   • lattice-quantized batches   → kind 'quantized'
+ *   • GPU-instanced templates     → kind 'instanced'
+ *   • surface-textured meshes     → kind 'textured'
+ *
+ * is handled here, and `occluder-collection.test.ts` asserts a scene carrying
+ * all four emits one occluder per path.
+ *
+ * Kept pure (no `Scene`, no GPU calls beyond passing buffer handles through) so
+ * it is unit-testable with plain fakes.
+ */
+import type { BatchedMesh, Mesh } from './types.js';
+import type { InstancedTemplateGPU, TexturedMesh } from './scene.js';
+import type { ShadowOccluderDraw } from './shadow-pass.js';
+/** The draw lists a `Scene` exposes, as the collector needs them. */
+export interface ShadowOccluderSources {
+    batches: readonly BatchedMesh[];
+    instanced: readonly InstancedTemplateGPU[];
+    textured: readonly TexturedMesh[];
+    /**
+     * Individual meshes (the `Renderer.addMesh()` / no-batch fallback path).
+     * Optional — the batched viewer never populates it. Hydrated meshes (lazy
+     * selection-highlight copies that duplicate batch geometry) are skipped so
+     * they don't double-cast.
+     */
+    meshes?: readonly Mesh[];
+}
+/** Hide/isolate state, matching `RenderOptions`. */
+export interface ShadowVisibility {
+    hiddenIds?: ReadonlySet<number>;
+    isolatedIds?: ReadonlySet<number>;
+}
+/** Tuning for {@link collectShadowOccluders}. */
+export interface ShadowOccluderOptions {
+    /**
+     * Material-alpha floor for casting: geometry whose base colour alpha is below
+     * this does NOT cast a shadow, so light passes through it (#2670). This is
+     * how glass windows let daylight through their opening — the wall mesh keeps
+     * the void, the transparent glass filling it simply stops occluding — and it
+     * also spares the virtual transparent volumes (IfcSpace, IfcOpeningElement)
+     * from throwing solid shadows. Uses the MATERIAL alpha (`color[3]`), not the
+     * X-ray/ghost view overrides, so ghosting the model does not delete its
+     * shadows. Default {@link DEFAULT_MIN_CAST_ALPHA}.
+     */
+    minCastAlpha?: number;
+}
+/**
+ * Below this material alpha a surface is treated as glass-like and stops
+ * casting. Solid materials are 1.0; IFC glass / spaces / openings render well
+ * under it, while a lightly tinted-but-solid material (>= 0.9) still casts.
+ */
+export declare const DEFAULT_MIN_CAST_ALPHA = 0.9;
+/**
+ * Column-major model matrix for a per-batch/per-mesh local frame: identity
+ * rotation with the origin in the translation column, matching how the main
+ * pass reconstructs `world = origin + position` (the vertex buffers store
+ * origin-relative positions). Reused into `out` when provided to avoid a
+ * per-draw allocation on the hot path.
+ */
+export declare function originModelMatrix(origin: readonly [number, number, number] | undefined, out?: Float32Array): Float32Array;
+/**
+ * How a shared batch stands under the current hide/isolate state (#2670, Phase
+ * 2b), so the renderer can feed the shadow collector the SAME visible subset the
+ * colour pass draws:
+ * - `all` — no filtering, or every element visible → cast the batch's own buffers.
+ * - `none` — every element hidden/excluded → the batch does not cast at all.
+ * - `partial` — a mix → cast only `visibleIds` (via the colour pass's cached
+ *   partial sub-batch), so an individually-hidden element stops casting instead
+ *   of throwing a phantom shadow.
+ *
+ * Uses {@link isEntityVisible}, so the empty-isolate-hides-everything and
+ * hiding-wins-over-isolation rules match every other visibility surface exactly.
+ */
+export type BatchVisibilityClass = {
+    kind: 'all';
+} | {
+    kind: 'none';
+} | {
+    kind: 'partial';
+    visibleIds: Set<number>;
+};
+export declare function classifyBatchVisibility(expressIds: readonly number[], hiddenIds: ReadonlySet<number> | null | undefined, isolatedIds: ReadonlySet<number> | null | undefined): BatchVisibilityClass;
+/**
+ * Collect every occluder draw for the shadow depth pass.
+ *
+ * A batch casts if it is GPU-resident, opaque enough (material alpha >=
+ * `minCastAlpha` — transparent glass lets light through, see
+ * {@link ShadowOccluderOptions.minCastAlpha}) and has at least one visible
+ * element. Per-element hide/isolate within a shared batch is applied UPSTREAM:
+ * the renderer feeds this collector the same visible subset it draws (a
+ * fully-hidden batch is dropped, a partially-hidden one arrives as its visible
+ * sub-batch), so `sources.batches` is already visibility-correct. Instanced
+ * templates carry a per-occurrence HIDDEN flag the depth shader discards on, so
+ * a hidden/isolated occurrence stops casting. Textured meshes are filtered per
+ * element like the main textured sub-pass.
+ */
+export declare function collectShadowOccluders(sources: ShadowOccluderSources, visibility?: ShadowVisibility, options?: ShadowOccluderOptions): ShadowOccluderDraw[];
+//# sourceMappingURL=shadow-occluders.d.ts.map

package/dist/shadow-occluders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow-occluders.d.ts","sourceRoot":"","sources":["../src/shadow-occluders.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG3D,qEAAqE;AACrE,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IAChC,SAAS,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC3C,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAClC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;CAC1B;AAED,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAChC,WAAW,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACnC;AAED,iDAAiD;AACjD,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EACrD,GAAG,GAAE,YAAmC,GACvC,YAAY,CASd;AAgBD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GACf;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC;AAEjD,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,SAAS,EACjD,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,SAAS,GAClD,oBAAoB,CAYtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,qBAAqB,EAC9B,UAAU,CAAC,EAAE,gBAAgB,EAC7B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,kBAAkB,EAAE,CAgEtB"}

package/dist/shadow-occluders.js

@@ -0,0 +1,156 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+import { isEntityVisible } from './entity-visibility.js';
+/**
+ * Below this material alpha a surface is treated as glass-like and stops
+ * casting. Solid materials are 1.0; IFC glass / spaces / openings render well
+ * under it, while a lightly tinted-but-solid material (>= 0.9) still casts.
+ */
+export const DEFAULT_MIN_CAST_ALPHA = 0.9;
+/**
+ * Column-major model matrix for a per-batch/per-mesh local frame: identity
+ * rotation with the origin in the translation column, matching how the main
+ * pass reconstructs `world = origin + position` (the vertex buffers store
+ * origin-relative positions). Reused into `out` when provided to avoid a
+ * per-draw allocation on the hot path.
+ */
+export function originModelMatrix(origin, out = new Float32Array(16)) {
+    out[0] = 1;
+    out[1] = 0;
+    out[2] = 0;
+    out[3] = 0;
+    out[4] = 0;
+    out[5] = 1;
+    out[6] = 0;
+    out[7] = 0;
+    out[8] = 0;
+    out[9] = 0;
+    out[10] = 1;
+    out[11] = 0;
+    out[12] = origin ? origin[0] : 0;
+    out[13] = origin ? origin[1] : 0;
+    out[14] = origin ? origin[2] : 0;
+    out[15] = 1;
+    return out;
+}
+/** Whether a batch/mesh with these ids has at least one visible element. */
+function anyVisible(ids, vis) {
+    if (!vis)
+        return true;
+    const { hiddenIds, isolatedIds } = vis;
+    const hasIsolate = isolatedIds != null && isolatedIds.size > 0;
+    if (!hiddenIds && !hasIsolate)
+        return true;
+    for (const id of ids) {
+        if (hiddenIds?.has(id))
+            continue;
+        if (hasIsolate && !isolatedIds.has(id))
+            continue;
+        return true;
+    }
+    return false;
+}
+export function classifyBatchVisibility(expressIds, hiddenIds, isolatedIds) {
+    // No active filter → the whole batch is visible (fast path, no Set built).
+    if ((hiddenIds == null || hiddenIds.size === 0) && isolatedIds == null) {
+        return { kind: 'all' };
+    }
+    const visibleIds = new Set();
+    for (const id of expressIds) {
+        if (isEntityVisible(id, hiddenIds, isolatedIds))
+            visibleIds.add(id);
+    }
+    if (visibleIds.size === 0)
+        return { kind: 'none' };
+    if (visibleIds.size === expressIds.length)
+        return { kind: 'all' };
+    return { kind: 'partial', visibleIds };
+}
+/**
+ * Collect every occluder draw for the shadow depth pass.
+ *
+ * A batch casts if it is GPU-resident, opaque enough (material alpha >=
+ * `minCastAlpha` — transparent glass lets light through, see
+ * {@link ShadowOccluderOptions.minCastAlpha}) and has at least one visible
+ * element. Per-element hide/isolate within a shared batch is applied UPSTREAM:
+ * the renderer feeds this collector the same visible subset it draws (a
+ * fully-hidden batch is dropped, a partially-hidden one arrives as its visible
+ * sub-batch), so `sources.batches` is already visibility-correct. Instanced
+ * templates carry a per-occurrence HIDDEN flag the depth shader discards on, so
+ * a hidden/isolated occurrence stops casting. Textured meshes are filtered per
+ * element like the main textured sub-pass.
+ */
+export function collectShadowOccluders(sources, visibility, options) {
+    const draws = [];
+    const minCastAlpha = options?.minCastAlpha ?? DEFAULT_MIN_CAST_ALPHA;
+    for (const batch of sources.batches) {
+        if (batch.gpuResident === false)
+            continue;
+        if (!batch.vertexBuffer || !batch.indexBuffer || batch.indexCount <= 0)
+            continue;
+        if (batch.color[3] < minCastAlpha)
+            continue; // transparent (glass) → light through
+        if (!anyVisible(batch.expressIds, visibility))
+            continue;
+        const q = batch.quantized;
+        draws.push({
+            kind: q ? 'quantized' : 'flat',
+            vertexBuffer: batch.vertexBuffer,
+            indexBuffer: batch.indexBuffer,
+            indexCount: batch.indexCount,
+            model: originModelMatrix(batch.origin),
+            quantParams: q ? [q.min[0], q.min[1], q.min[2], q.step] : undefined,
+        });
+    }
+    for (const it of sources.instanced) {
+        if (!it.vertexBuffer || !it.indexBuffer || it.indexCount <= 0 || it.instanceCount <= 0)
+            continue;
+        draws.push({
+            kind: 'instanced',
+            vertexBuffer: it.vertexBuffer,
+            indexBuffer: it.indexBuffer,
+            indexCount: it.indexCount,
+            instanceBuffer: it.instanceBuffer,
+            instanceCount: it.instanceCount,
+        });
+    }
+    for (const tm of sources.textured) {
+        if (!tm.vertexBuffer || !tm.indexBuffer || tm.indexCount <= 0)
+            continue;
+        if (tm.color[3] < minCastAlpha)
+            continue; // transparent → light through
+        if (!anyVisible([tm.expressId], visibility))
+            continue;
+        draws.push({
+            kind: 'textured',
+            vertexBuffer: tm.vertexBuffer,
+            indexBuffer: tm.indexBuffer,
+            indexCount: tm.indexCount,
+            model: originModelMatrix(tm.origin),
+        });
+    }
+    // Individual meshes (Renderer.addMesh() / no-batch fallback). Same 28-byte
+    // flat vertex layout as a batch, so kind 'flat'; the mesh's full transform is
+    // the model matrix. Skip hydrated meshes (selection-highlight copies that
+    // duplicate batch geometry — they would double-cast).
+    for (const mesh of sources.meshes ?? []) {
+        if (mesh.hydrated)
+            continue;
+        if (!mesh.vertexBuffer || !mesh.indexBuffer || mesh.indexCount <= 0)
+            continue;
+        if (mesh.color[3] < minCastAlpha)
+            continue; // transparent → light through
+        if (!anyVisible([mesh.expressId], visibility))
+            continue;
+        draws.push({
+            kind: 'flat',
+            vertexBuffer: mesh.vertexBuffer,
+            indexBuffer: mesh.indexBuffer,
+            indexCount: mesh.indexCount,
+            model: mesh.transform.m,
+        });
+    }
+    return draws;
+}
+//# sourceMappingURL=shadow-occluders.js.map

package/dist/shadow-occluders.js.map

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

package/dist/shadow-pass.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Sun shadow-map depth pre-pass (issue #2670, Phase 2a).
+ *
+ * Owns the shadow depth texture and the four depth-only pipelines (one per
+ * geometry path — flat, quantized, instanced, textured), and records a single
+ * depth-only render pass that rasterises every occluder from the sun's point
+ * of view. The main colour pass (Phase 2b) then samples this depth map to
+ * decide lit vs. shadowed.
+ *
+ * Per-draw `model`/`quantParams` are supplied through ONE dynamic-offset
+ * uniform buffer (a grow-only ring) rather than a buffer per batch, so a
+ * CATIA-class model with thousands of batches costs one allocation, not
+ * thousands. `lightViewProj` is shared (written once per frame).
+ *
+ * The pass is single-sample and double-sided (cullMode 'none'): IFC winding is
+ * not reliably outward — the colour pipelines already draw double-sided for
+ * the same reason — so front/back-face culling would drop occluders and punch
+ * holes in the shadow.
+ */
+import type { Mat4 } from './types.js';
+/** Which geometry path an occluder draw came from — selects the pipeline. */
+export type ShadowDrawKind = 'flat' | 'quantized' | 'instanced' | 'textured';
+/**
+ * Resolve the shadow-map side length to actually allocate.
+ *
+ * `requested === 0` (or a non-positive / non-finite value) means **Auto**: pick
+ * a sensible size from the device's 2D texture limit — a laptop iGPU capped at
+ * 4096 gets a 2048 map, a discrete GPU (8192+) gets 4096 (#2670 review). A
+ * manual request is honoured but never allowed to exceed the device limit,
+ * since `createTexture` would otherwise fail outright on a smaller device.
+ */
+export declare function resolveShadowMapResolution(requested: number | undefined, maxTextureDim: number): number;
+/** One occluder draw recorded into the depth pre-pass. */
+export interface ShadowOccluderDraw {
+    kind: ShadowDrawKind;
+    /** Slot-0 vertex buffer (positions). */
+    vertexBuffer: GPUBuffer;
+    indexBuffer: GPUBuffer;
+    indexCount: number;
+    /**
+     * Column-major model matrix (16 floats). Carries the batch origin for the
+     * flat/quantized/textured paths; ignored for the instanced path.
+     */
+    model?: Float32Array;
+    /** Dequantization params [minX, minY, minZ, step]; quantized path only. */
+    quantParams?: readonly [number, number, number, number];
+    /** Slot-1 per-occurrence instance buffer; instanced path only. */
+    instanceBuffer?: GPUBuffer;
+    /** Instance count; instanced path only. */
+    instanceCount?: number;
+}
+/**
+ * The clip this frame, mirrored from the colour pass so clipped-away geometry
+ * stops casting (a sectioned-off roof must not keep shadowing the floor).
+ * `null`/all-absent members mean "no clipping" and keep the fragment-less
+ * depth-only pipelines.
+ */
+export interface ShadowClip {
+    /** World-space plane; fragments on its + side are cut (see `flipped`). */
+    section?: {
+        normal: readonly [number, number, number];
+        distance: number;
+        flipped?: boolean;
+    } | null;
+    /** World-space crop box; fragments outside it are cut. */
+    box?: {
+        min: readonly [number, number, number];
+        max: readonly [number, number, number];
+    } | null;
+}
+export declare class ShadowPass {
+    private device;
+    private resolution;
+    private depthTexture;
+    private depthTextureView;
+    private bindGroupLayout;
+    private pipelines;
+    /**
+     * Clipping twins of {@link pipelines} — same state plus the discarding
+     * fragment stage. Built on the first clipped frame only, so a session that
+     * never sections anything never pays for the extra pipelines.
+     */
+    private clipPipelines;
+    private shaderModule;
+    private pipelineLayout;
+    private lightBuffer;
+    private lightScratch;
+    /** Clip uniform (floats 0..11) with the flag word aliased as u32 (word 12). */
+    private clipBuffer;
+    private clipScratch;
+    private clipFlags;
+    /** Grow-only ring for per-draw uniforms, bound with a dynamic offset. */
+    private drawBuffer;
+    private drawBufferSlots;
+    private drawStride;
+    private drawBindGroup;
+    private drawScratch;
+    private destroyed;
+    constructor(device: GPUDevice, resolution: number);
+    /** One pipeline per geometry path, with or without the clipping fragment stage. */
+    private createPipelineSet;
+    /** Depth-texture view for the colour pass to sample. */
+    getDepthTextureView(): GPUTextureView;
+    getResolution(): number;
+    /** Resize the shadow map (Quality-panel control, Phase 2b). No-op if same. */
+    setResolution(resolution: number): void;
+    /**
+     * Record the depth pre-pass: rasterise every occluder from the sun. Writes
+     * all uniforms (queue ops, before the pass begins), then draws.
+     *
+     * `clip` mirrors the colour pass's section plane / clip box; when it cuts
+     * anything the draws go through the clipping pipelines so removed geometry
+     * casts nothing.
+     */
+    render(encoder: GPUCommandEncoder, lightViewProj: Mat4, draws: readonly ShadowOccluderDraw[], clip?: ShadowClip | null): void;
+    destroy(): void;
+    /**
+     * Pack this frame's clip into the uniform, laid out (and flag-packed) exactly
+     * like the colour pass's. Returns whether anything is actually being cut —
+     * the caller uses that to pick the clipping pipelines. Writes only when
+     * clipping: with nothing cut the uniform is never read.
+     */
+    private writeClipUniform;
+    private createDepthTexture;
+    private createDrawBuffer;
+    private createDrawBindGroup;
+    private posBuffer;
+    private quantBuffer;
+    private instanceBuffer;
+    private createPipeline;
+}
+//# sourceMappingURL=shadow-pass.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shadow-pass.d.ts","sourceRoot":"","sources":["../src/shadow-pass.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAGvC,6EAA6E;AAC7E,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,CAAC;AAE7E;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAYvG;AAED,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,cAAc,CAAC;IACrB,wCAAwC;IACxC,YAAY,EAAE,SAAS,CAAC;IACxB,WAAW,EAAE,SAAS,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACxD,kEAAkE;IAClE,cAAc,CAAC,EAAE,SAAS,CAAC;IAC3B,2CAA2C;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,OAAO,CAAC,EAAE;QACR,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC1C,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,GAAG,IAAI,CAAC;IACT,0DAA0D;IAC1D,GAAG,CAAC,EAAE;QACJ,GAAG,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACvC,GAAG,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;KACxC,GAAG,IAAI,CAAC;CACV;AAWD,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,UAAU,CAAS;IAE3B,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,gBAAgB,CAAiB;IAEzC,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,SAAS,CAA4C;IAC7D;;;;OAIG;IACH,OAAO,CAAC,aAAa,CAA0D;IAC/E,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,cAAc,CAAoB;IAE1C,OAAO,CAAC,WAAW,CAAY;IAC/B,OAAO,CAAC,YAAY,CAAwB;IAE5C,+EAA+E;IAC/E,OAAO,CAAC,UAAU,CAAY;IAC9B,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,SAAS,CAA4C;IAE7D,yEAAyE;IACzE,OAAO,CAAC,UAAU,CAAY;IAC9B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,WAAW,CAAe;IAElC,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM;IAoDjD,mFAAmF;IACnF,OAAO,CAAC,iBAAiB;IAWzB,wDAAwD;IACxD,mBAAmB,IAAI,cAAc;IAIrC,aAAa,IAAI,MAAM;IAIvB,8EAA8E;IAC9E,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IASvC;;;;;;;OAOG;IACH,MAAM,CACJ,OAAO,EAAE,iBAAiB,EAC1B,aAAa,EAAE,IAAI,EACnB,KAAK,EAAE,SAAS,kBAAkB,EAAE,EACpC,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,GACvB,IAAI;IA2EP,OAAO,IAAI,IAAI;IASf;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IA2BxB,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,cAAc;CA2CvB"}