@iwsdk/core 0.1.0

package/dist/transform/synced-vector3.js

@@ -0,0 +1,106 @@
+import '../runtime/three.js';
+import { Vector3 } from 'three';
+
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Vector3 whose x/y/z accessors read from and write to a target Float32Array.
+ *
+ * @remarks
+ * - Used by {@link TransformSystem} to bind Object3D.position/scale directly to
+ *   ECS component storage for zero‑copy updates.
+ * - When no target is set, falls back to internal fields so it behaves like a
+ *   normal `Vector3`.
+ *
+ * @category Scene
+ */
+class SyncedVector3 extends Vector3 {
+    constructor(x = 0, y = 0, z = 0) {
+        super(x, y, z);
+        this.target = null;
+        this.targetOffset = 0;
+        this.__x = 0;
+        this.__y = 0;
+        this.__z = 0;
+        // Preserve the values set by parent constructor before overriding properties
+        this.__x = this.x;
+        this.__y = this.y;
+        this.__z = this.z;
+        this.setupProperties();
+    }
+    setupProperties() {
+        // Override x, y, z properties to sync with target
+        Object.defineProperty(this, 'x', {
+            get: () => {
+                if (this.target) {
+                    return this.target[this.targetOffset];
+                }
+                // Fallback to a private property when no target is set
+                return this.__x;
+            },
+            set: (value) => {
+                if (this.target) {
+                    this.target[this.targetOffset] = value;
+                }
+                else {
+                    this.__x = value;
+                }
+            },
+            enumerable: true,
+            configurable: true,
+        });
+        Object.defineProperty(this, 'y', {
+            get: () => {
+                if (this.target) {
+                    return this.target[this.targetOffset + 1];
+                }
+                return this.__y;
+            },
+            set: (value) => {
+                if (this.target) {
+                    this.target[this.targetOffset + 1] = value;
+                }
+                else {
+                    this.__y = value;
+                }
+            },
+            enumerable: true,
+            configurable: true,
+        });
+        Object.defineProperty(this, 'z', {
+            get: () => {
+                if (this.target) {
+                    return this.target[this.targetOffset + 2];
+                }
+                return this.__z;
+            },
+            set: (value) => {
+                if (this.target) {
+                    this.target[this.targetOffset + 2] = value;
+                }
+                else {
+                    this.__z = value;
+                }
+            },
+            enumerable: true,
+            configurable: true,
+        });
+    }
+    /**
+     * Bind this vector to a packed float array.
+     * @param target Float32Array to read/write.
+     * @param offset Starting index within the array (x at `offset`).
+     */
+    setTarget(target, offset = 0) {
+        this.target = target;
+        this.targetOffset = offset;
+        return this;
+    }
+}
+
+export { SyncedVector3 };
+//# sourceMappingURL=synced-vector3.js.map

package/dist/transform/synced-vector3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"synced-vector3.js","sources":["../../src/transform/synced-vector3.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/transform/transform.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Types } from '../ecs/index.js';
+/**
+ * 3D transform component that binds an entity to a Three.js Object3D.
+ *
+ * @remarks
+ * - The {@link TransformSystem} wires Object3D.position/quaternion/scale to
+ *   component views for zero‑copy updates and parenting.
+ * - Default values are `NaN` so an existing Object3D keeps its initial transform
+ *   unless a value is explicitly written by code or GLXF.
+ * - Set `parent` to reparent under another entity. When unset, entities are
+ *   automatically parented under the active level root (or scene if persistent).
+ *
+ * @category Scene
+ * @hideineditor
+ */
+export declare const Transform: import("elics").Component<{
+    position: {
+        type: Types.Vec3;
+        default: [number, number, number];
+    };
+    orientation: {
+        type: Types.Vec4;
+        default: [number, number, number, number];
+    };
+    scale: {
+        type: Types.Vec3;
+        default: [number, number, number];
+    };
+    parent: {
+        type: Types.Entity;
+        default: any;
+    };
+}>;
+declare const TransformSystem_base: import("elics").SystemConstructor<import("elics").SystemSchema, {
+    transform: {
+        required: import("elics").Component<{
+            position: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            orientation: {
+                type: Types.Vec4;
+                default: [number, number, number, number];
+            };
+            scale: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            parent: {
+                type: Types.Entity;
+                default: any;
+            };
+        }>[];
+    };
+}, import("../ecs/world.js").World, import("../ecs/system.js").System<import("elics").SystemSchema, {
+    transform: {
+        required: import("elics").Component<{
+            position: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            orientation: {
+                type: Types.Vec4;
+                default: [number, number, number, number];
+            };
+            scale: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            parent: {
+                type: Types.Entity;
+                default: any;
+            };
+        }>[];
+    };
+}>>;
+/**
+ * Keeps Object3D and Transform component in sync and manages parenting.
+ *
+ * @remarks
+ * - Replaces Object3D accessors with synced views for fast ECS writes.
+ * - Ensures entities without an explicit `parent` attach to the level root
+ *   (or the scene for persistent objects).
+ * - If an Object3D is manually reparented under another entity, the component
+ *   `parent` value is updated to match.
+ *
+ * @category Scene
+ */
+export declare class TransformSystem extends TransformSystem_base {
+    init(): void;
+    update(): void;
+}
+export {};
+//# sourceMappingURL=transform.d.ts.map

package/dist/transform/transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/transform/transform.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,KAAK,EAKN,MAAM,iBAAiB,CAAC;AAMzB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;iBAMkC,GAAG;;EAG1D,CAAC;;;;;;;;;;;;;;;;;;yBAHsD,GAAG;;;;;;;;;;;;;;;;;;;;;yBAAH,GAAG;;;;;AAsH3D;;;;;;;;;;;GAWG;AACH,qBAAa,eAAgB,SAAQ,oBAEnC;IACA,IAAI,IAAI,IAAI;IAKZ,MAAM,IAAI,IAAI;CA4Bf"}

package/dist/transform/transform.js

@@ -0,0 +1,194 @@
+import { createSystem } from '../ecs/system.js';
+import '../ecs/world.js';
+import { createComponent, Types } from 'elics';
+import { NullEntity } from '../ecs/entity.js';
+import '../ecs/component-registry.js';
+import '../level/level-system.js';
+import { LevelTag } from '../level/level-tag.js';
+import '@iwsdk/glxf';
+import '../asset/asset-manager.js';
+import '../asset/cache-manager.js';
+import '@pmndrs/uikit';
+import '@preact/signals-core';
+import { Vector3, Quaternion } from 'three';
+import '../ui/ui.js';
+import '../ui/follow.js';
+import '../ui/screenspace.js';
+import '../level/level-root.js';
+import '../runtime/three.js';
+import { SyncedQuaternion } from './synced-quaternion.js';
+import { SyncedVector3 } from './synced-vector3.js';
+
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * 3D transform component that binds an entity to a Three.js Object3D.
+ *
+ * @remarks
+ * - The {@link TransformSystem} wires Object3D.position/quaternion/scale to
+ *   component views for zero‑copy updates and parenting.
+ * - Default values are `NaN` so an existing Object3D keeps its initial transform
+ *   unless a value is explicitly written by code or GLXF.
+ * - Set `parent` to reparent under another entity. When unset, entities are
+ *   automatically parented under the active level root (or scene if persistent).
+ *
+ * @category Scene
+ * @hideineditor
+ */
+const Transform = createComponent('Transform', {
+    position: { type: Types.Vec3, default: [NaN, NaN, NaN] }, // Local position [x,y,z]; NaN preserves Object3D value
+    orientation: { type: Types.Vec4, default: [NaN, NaN, NaN, NaN] }, // Local rotation quaternion [x,y,z,w]; NaN preserves
+    scale: { type: Types.Vec3, default: [NaN, NaN, NaN] }, // Local scale [x,y,z]; NaN preserves
+    parent: { type: Types.Entity, default: undefined }, // Parent entity for hierarchy (defaults to level root)
+}, 'Component for 3D transformation (position, rotation, scale)');
+function attachToEntity(entity) {
+    const object3D = entity.object3D;
+    if (!object3D) {
+        return;
+    }
+    if (object3D.__transformAttached) {
+        return;
+    }
+    object3D.__transformAttached = true;
+    object3D.entityIdx = entity.index;
+    object3D.positionView = entity.getVectorView(Transform, 'position');
+    object3D.quaternionView = entity.getVectorView(Transform, 'orientation');
+    object3D.scaleView = entity.getVectorView(Transform, 'scale');
+    // if component values contains NaN, keep original values instead
+    if (object3D.positionView.some(Number.isNaN)) {
+        object3D.position.toArray(object3D.positionView);
+    }
+    if (object3D.quaternionView.some(Number.isNaN)) {
+        object3D.quaternion.toArray(object3D.quaternionView);
+    }
+    if (object3D.scaleView.some(Number.isNaN)) {
+        object3D.scale.toArray(object3D.scaleView);
+    }
+    Object.defineProperty(object3D, 'position', {
+        value: new SyncedVector3().setTarget(object3D.positionView),
+        writable: false,
+        configurable: true,
+        enumerable: true,
+    });
+    Object.defineProperty(object3D, 'quaternion', {
+        value: new SyncedQuaternion().setTarget(object3D.quaternionView),
+        writable: false,
+        configurable: true,
+        enumerable: true,
+    });
+    Object.defineProperty(object3D, 'scale', {
+        value: new SyncedVector3().setTarget(object3D.scaleView),
+        writable: false,
+        configurable: true,
+        enumerable: true,
+    });
+    object3D._parent = object3D.parent; // save original parent
+    Object.defineProperty(object3D, 'parent', {
+        get: () => {
+            return object3D._parent;
+        },
+        set: (value) => {
+            var _a;
+            object3D._parent = value;
+            Transform.data.parent[entity.index] = (_a = value === null || value === void 0 ? void 0 : value.entityIdx) !== null && _a !== void 0 ? _a : NullEntity;
+        },
+        configurable: true,
+        enumerable: true,
+    });
+}
+function detachFromEntity(entity) {
+    const object3D = entity.object3D;
+    if (!object3D) {
+        return;
+    }
+    if (!object3D.__transformAttached) {
+        return;
+    }
+    delete object3D.entityIdx;
+    delete object3D.positionView;
+    delete object3D.quaternionView;
+    delete object3D.scaleView;
+    Object.defineProperty(object3D, 'position', {
+        value: new Vector3().copy(object3D.position),
+        writable: false,
+        configurable: true,
+        enumerable: true,
+    });
+    Object.defineProperty(object3D, 'quaternion', {
+        value: new Quaternion().copy(object3D.quaternion),
+        writable: false,
+        configurable: true,
+        enumerable: true,
+    });
+    Object.defineProperty(object3D, 'scale', {
+        value: new Vector3().copy(object3D.scale),
+        writable: false,
+        configurable: true,
+        enumerable: true,
+    });
+    Object.defineProperty(object3D, 'parent', {
+        value: object3D._parent,
+        writable: true,
+        configurable: true,
+        enumerable: true,
+    });
+    delete object3D._parent;
+    delete object3D.__transformAttached;
+}
+/**
+ * Keeps Object3D and Transform component in sync and manages parenting.
+ *
+ * @remarks
+ * - Replaces Object3D accessors with synced views for fast ECS writes.
+ * - Ensures entities without an explicit `parent` attach to the level root
+ *   (or the scene for persistent objects).
+ * - If an Object3D is manually reparented under another entity, the component
+ *   `parent` value is updated to match.
+ *
+ * @category Scene
+ */
+class TransformSystem extends createSystem({
+    transform: { required: [Transform] },
+}) {
+    init() {
+        this.queries.transform.subscribe('qualify', attachToEntity);
+        this.queries.transform.subscribe('disqualify', detachFromEntity);
+    }
+    update() {
+        this.queries.transform.entities.forEach((entity) => {
+            var _a;
+            const object = entity.object3D;
+            if (!object || object === this.world.scene) {
+                return;
+            }
+            const parentEntity = entity.getValue(Transform, 'parent');
+            const parentObject = parentEntity === null || parentEntity === void 0 ? void 0 : parentEntity.object3D;
+            if (!parentObject) {
+                // no valid parent specified in Transform
+                if (((_a = object.parent) === null || _a === void 0 ? void 0 : _a.entityIdx) !== undefined) {
+                    // check whether object is already parented under an entity, if so, update parent in Transform
+                    Transform.data.parent[entity.index] = object.parent.entityIdx;
+                }
+                else {
+                    // Default parent: active level if entity has LevelTag; otherwise scene (persistent)
+                    const targetEntity = entity.hasComponent(LevelTag)
+                        ? this.world.activeLevel.value
+                        : this.world.sceneEntity;
+                    targetEntity.object3D.add(object);
+                    entity.setValue(Transform, 'parent', targetEntity);
+                }
+            }
+            else if (parentObject !== object.parent) {
+                // parent changed in Transform
+                parentObject.add(object);
+            }
+        });
+    }
+}
+
+export { Transform, TransformSystem };
+//# sourceMappingURL=transform.js.map

package/dist/transform/transform.js.map

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

package/dist/types/webxr-augmentations.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+declare global {
+    interface XRSession {
+        trackedSources?: XRInputSourceArray;
+        initiateRoomCapture?: () => Promise<undefined>;
+    }
+    interface XRFrame {
+        readonly detectedPlanes?: XRPlaneSet;
+        readonly detectedMeshes?: XRMeshSet;
+        fillPoses?: (space: ArrayLike<XRSpace>, baseSpace: XRSpace, transforms: Float32Array) => boolean;
+        fillJointRadii?: (space: ArrayLike<XRSpace>, radii: Float32Array) => boolean;
+    }
+    interface XRSystem {
+        offerSession?: (mode: XRSessionMode, options?: XRSessionInit) => Promise<XRSession>;
+    }
+}
+export {};
+//# sourceMappingURL=webxr-augmentations.d.ts.map

package/dist/types/webxr-augmentations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webxr-augmentations.d.ts","sourceRoot":"","sources":["../../src/types/webxr-augmentations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,SAAS;QACjB,cAAc,CAAC,EAAE,kBAAkB,CAAC;QACpC,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC;KAChD;IAED,UAAU,OAAO;QACf,QAAQ,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC;QACrC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,CAAC;QACpC,SAAS,CAAC,EAAE,CACV,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,EACzB,SAAS,EAAE,OAAO,EAClB,UAAU,EAAE,YAAY,KACrB,OAAO,CAAC;QACb,cAAc,CAAC,EAAE,CACf,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,EACzB,KAAK,EAAE,YAAY,KAChB,OAAO,CAAC;KACd;IAED,UAAU,QAAQ;QAChB,YAAY,CAAC,EAAE,CACb,IAAI,EAAE,aAAa,EACnB,OAAO,CAAC,EAAE,aAAa,KACpB,OAAO,CAAC,SAAS,CAAC,CAAC;KACzB;CACF;AAED,OAAO,EAAE,CAAC"}

package/dist/ui/document.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Component } from '@pmndrs/uikit';
+import { Signal } from '@preact/signals-core';
+import { Group } from 'three';
+/**
+ * Lightweight DOM-like wrapper around a UIKit root `Component` that lives in the 3D scene.
+ *
+ * @remarks
+ * - Provides query helpers (`getElementById`, `getElementsByClassName`, `querySelector(All)`).
+ * - Maintains reactive target dimensions via {@link targetWidth}/{@link targetHeight} and
+ *   scales the group to fit while preserving aspect ratio.
+ * - Intended to be attached to an entity's `object3D` in world space or to the `camera` for
+ *   screen‑space UI. Use together with {@link PanelUISystem} and {@link ScreenSpaceUISystem}.
+ *
+ * @category UI
+ */
+export declare class UIKitDocument extends Group {
+    private elementMap;
+    private classMap;
+    private _rootElement;
+    private _abortController;
+    /** Reactive target width in meters. Set via {@link setTargetDimensions}. */
+    readonly targetWidth: Signal<number>;
+    /** Reactive target height in meters. Set via {@link setTargetDimensions}. */
+    readonly targetHeight: Signal<number>;
+    /**
+     * Create a document backed by a UIKit root component.
+     * @param rootComponent The root `Component` produced by `@pmndrs/uikitml` `interpret()`.
+     */
+    constructor(rootComponent: Component<any>);
+    /**
+     * Return the first element with a matching `id` (UIKit property).
+     * @param id The element identifier without the `#` prefix.
+     */
+    getElementById(id: string): Component<any> | null;
+    /**
+     * Return all elements that include `className` in their class list.
+     * @param className The class without the preceding dot.
+     */
+    getElementsByClassName(className: string): Component<any>[];
+    /**
+     * Return the first element matching a simple CSS‑like selector.
+     *
+     * @remarks
+     * Supported selectors:
+     * - `#id`
+     * - `.class`
+     * - Descendant combinations, e.g. `#parent .child`
+     */
+    querySelector(selector: string): Component<any> | null;
+    /**
+     * Return all elements matching a simple CSS‑like selector. See {@link querySelector}.
+     */
+    querySelectorAll(selector: string): Component<any>[];
+    /** Parse descendant selectors like `#parent .child`. */
+    private parseDescendantSelector;
+    /** Find all descendants of a parent that match a selector. */
+    private findDescendants;
+    /** Recursively search for descendants matching a selector. */
+    private searchDescendants;
+    /** Check if a component matches a simple selector (`#id` or `.class`). */
+    private matchesSelector;
+    /**
+     * Check if `element` is a descendant of `ancestor`.
+     * @returns `true` if `ancestor` appears in the parent chain of `element`.
+     */
+    isDescendantOf(element: Component<any>, ancestor: Component<any>): boolean;
+    /** Convenience for `querySelectorAll("${parent} ${child}")`. */
+    querySelectorAllWithin(parentSelector: string, childSelector: string): Component<any>[];
+    /** Convenience for the first match of `querySelectorAllWithin`. */
+    querySelectorWithin(parentSelector: string, childSelector: string): Component<any> | null;
+    /** Set up reactivity that rescales the group when size or target changes. */
+    private setupReactiveResizing;
+    /** Compute uniform scale to fit the target width/height while preserving aspect ratio. */
+    private updateScaling;
+    /**
+     * Set desired dimensions for the UI in meters. The document computes a uniform scale
+     * that fits these constraints while preserving aspect ratio.
+     * @param width Target width in meters.
+     * @param height Target height in meters.
+     */
+    setTargetDimensions(width: number, height: number): void;
+    /**
+     * Current intrinsic size of the UIKit root component (in UIKit units, centimeters),
+     * if available from the underlying component's `size` signal.
+     */
+    get computedSize(): {
+        width: number;
+        height: number;
+    } | null;
+    /** Return the most recently requested target size in meters. */
+    get targetSize(): {
+        width: number;
+        height: number;
+    };
+    /** The root UIKit component for this document. */
+    get rootElement(): Component<any>;
+    /**
+     * Dispose of internal resources and detach children. Safe to call multiple times.
+     */
+    dispose(): void;
+    /** String summary useful for debugging. */
+    toString(): string;
+    /** Index IDs and classes for DOM‑like queries. */
+    private indexElements;
+}
+//# sourceMappingURL=document.d.ts.map

package/dist/ui/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/ui/document.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAU,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,KAAK,EAAY,MAAM,OAAO,CAAC;AAExC;;;;;;;;;;;GAWG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,OAAO,CAAC,UAAU,CAAqC;IACvD,OAAO,CAAC,QAAQ,CAAuC;IACvD,OAAO,CAAC,YAAY,CAAiB;IACrC,OAAO,CAAC,gBAAgB,CAAyB;IAEjD,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAa;IACjD,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,CAAa;IAElD;;;OAGG;gBACS,aAAa,EAAE,SAAS,CAAC,GAAG,CAAC;IAUzC;;;OAGG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI;IAIjD;;;OAGG;IACH,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE;IAI3D;;;;;;;;OAQG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI;IAKtD;;OAEG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE;IAkBpD,wDAAwD;IACxD,OAAO,CAAC,uBAAuB;IA4B/B,8DAA8D;IAC9D,OAAO,CAAC,eAAe;IASvB,8DAA8D;IAC9D,OAAO,CAAC,iBAAiB;IAgBzB,0EAA0E;IAC1E,OAAO,CAAC,eAAe;IAsBvB;;;OAGG;IACH,cAAc,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,GAAG,CAAC,GAAG,OAAO;IAW1E,gEAAgE;IAChE,sBAAsB,CACpB,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,GACpB,SAAS,CAAC,GAAG,CAAC,EAAE;IAGnB,mEAAmE;IACnE,mBAAmB,CACjB,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,GACpB,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI;IAGxB,6EAA6E;IAC7E,OAAO,CAAC,qBAAqB;IAqB7B,0FAA0F;IAC1F,OAAO,CAAC,aAAa;IAiCrB;;;;;OAKG;IACH,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAKxD;;;OAGG;IACH,IAAI,YAAY,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAS3D;IAED,gEAAgE;IAChE,IAAI,UAAU,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAKlD;IAED,kDAAkD;IAClD,IAAI,WAAW,IAAI,SAAS,CAAC,GAAG,CAAC,CAEhC;IAED;;OAEG;IACH,OAAO,IAAI,IAAI;IAiBf,2CAA2C;IAC3C,QAAQ,IAAI,MAAM;IAQlB,kDAAkD;IAClD,OAAO,CAAC,aAAa;CA+BtB"}