manim-web 0.17.0 → 0.19.0

package/dist/mobjects/three-d/InstancedMobject.d.ts

@@ -0,0 +1,130 @@
+import { Mobject, Vector3Tuple } from '../../core/Mobject';
+import { Mobject3D } from './Mobject3D';
+import * as THREE from 'three';
+/**
+ * A single instance of the shared template geometry.
+ *
+ * `position` is required. `rotation` is a Euler tuple in radians (`XYZ` order).
+ * `scale` is a uniform factor or a per-axis tuple. `color` is a CSS color string
+ * applied to this instance only; omit it to keep the material color.
+ */
+export interface InstanceTransform {
+    /** Instance position [x, y, z]. */
+    position: Vector3Tuple;
+    /** Euler rotation [x, y, z] in radians (XYZ order). Default: no rotation. */
+    rotation?: Vector3Tuple;
+    /** Uniform scale, or per-axis [x, y, z] scale. Default: 1. */
+    scale?: number | Vector3Tuple;
+    /** Per-instance CSS color. Default: inherit the material color. */
+    color?: string;
+}
+/**
+ * Options for creating an {@link InstancedMobject}.
+ *
+ * Provide a template as either an explicit `geometry` + `material`, or a
+ * `template` mobject to derive both from. If none is given, a unit box with a
+ * standard material is used.
+ */
+export interface InstancedMobjectOptions {
+    /** Geometry shared by every instance. Cloned on {@link InstancedMobject.copy}. */
+    geometry?: THREE.BufferGeometry;
+    /** Material shared by every instance. Cloned on {@link InstancedMobject.copy}. */
+    material?: THREE.Material;
+    /** Template mobject to derive geometry and material from (cloned, not kept). */
+    template?: Mobject;
+    /** Per-instance transforms. Default: empty (no instances). */
+    instances?: InstanceTransform[];
+    /** Base material color as a CSS color string. Default: '#ffffff'. */
+    color?: string;
+    /** Material opacity from 0 to 1. Default: 1. */
+    opacity?: number;
+}
+/**
+ * InstancedMobject - renders many copies of one template via `THREE.InstancedMesh`.
+ *
+ * This is a safe, opt-in mobject for large scenes. It draws `count` copies of a
+ * single geometry + material in ONE draw call, instead of one mesh per copy.
+ * It does not change the default render path: scenes that do not use it are
+ * unaffected.
+ *
+ * Each instance has its own transform (position, optional rotation and scale)
+ * and an optional per-instance color. Use {@link setInstances} to replace the
+ * whole set, or {@link setInstanceTransform} / {@link setInstanceColor} to
+ * update one instance in place.
+ *
+ * @example
+ * ```typescript
+ * const dots = new InstancedMobject({
+ *   geometry: new THREE.SphereGeometry(0.1, 16, 16),
+ *   material: new THREE.MeshStandardMaterial(),
+ *   instances: [
+ *     { position: [0, 0, 0], color: '#ff0000' },
+ *     { position: [1, 0, 0], scale: 2 },
+ *   ],
+ * });
+ * scene.add(dots);
+ * ```
+ */
+export declare class InstancedMobject extends Mobject3D {
+    private _geometry;
+    private _material;
+    private _instances;
+    /** The single InstancedMesh; null until the Three.js object is built. */
+    private _mesh;
+    constructor(options?: InstancedMobjectOptions);
+    /**
+     * Resolve the shared geometry and material from the options.
+     * Order: explicit geometry/material, then a template mobject, then a default
+     * unit box. A geometry or material derived from a template is cloned so the
+     * template is never mutated or disposed by this mobject.
+     */
+    private static _resolveTemplate;
+    /** Find the first Mesh in a Three.js subtree, or null if there is none. */
+    private static _findMesh;
+    /** Deep-copy one instance transform so callers cannot alias our state. */
+    private static _cloneTransform;
+    /**
+     * Build the InstancedMesh with `count = instances.length` and fill its matrix
+     * and color buffers. Wrapped in a Group so a later count change can swap the
+     * mesh without touching the scene-graph parent.
+     */
+    protected _createThreeObject(): THREE.Object3D;
+    /** Create a fresh InstancedMesh for the current instances and populate it. */
+    private _buildMesh;
+    /** Write every instance matrix (and color, when present) into `mesh`. */
+    private _writeAllInstances;
+    /** Compose a transform matrix for one instance into `out`. */
+    private static _composeMatrix;
+    /** Sync base material color and opacity onto the shared material. */
+    protected _syncMaterialToThree(): void;
+    /**
+     * Replace all instances. Reuses the existing mesh when the count is unchanged;
+     * otherwise rebuilds the InstancedMesh (its count is fixed at construction).
+     */
+    setInstances(instances: InstanceTransform[]): this;
+    /** Update one instance transform in place and flag the matrix buffer. */
+    setInstanceTransform(index: number, transform: Partial<InstanceTransform>): this;
+    /** Update one instance color in place and flag the color buffer. */
+    setInstanceColor(index: number, color: string): this;
+    private _assertIndex;
+    /** Number of instances this mobject draws. */
+    getInstanceCount(): number;
+    /** The single backing InstancedMesh, building the Three.js object if needed. */
+    getInstancedMesh(): THREE.InstancedMesh;
+    /** The transform of instance `index` as a Matrix4 (reads back from the mesh). */
+    getInstanceMatrix(index: number, out?: THREE.Matrix4): THREE.Matrix4;
+    /** The shared geometry used by every instance. */
+    getGeometry(): THREE.BufferGeometry;
+    /** The shared material used by every instance. */
+    getMaterial(): THREE.Material;
+    /**
+     * An instance cloud is empty only when it has no instances. The base
+     * {@link Mobject.getCenter} / {@link Mobject.getBounds} then skip the bounding
+     * box, which would be empty and throw.
+     */
+    isEmpty(): boolean;
+    /** Dispose the InstancedMesh buffers, geometry, and material. No leaks. */
+    dispose(): void;
+    copy(): InstancedMobject;
+}
+//# sourceMappingURL=InstancedMobject.d.ts.map

package/dist/mobjects/three-d/InstancedMobject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InstancedMobject.d.ts","sourceRoot":"","sources":["../../../src/mobjects/three-d/InstancedMobject.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,QAAQ,EAAE,YAAY,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAC9B,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,kFAAkF;IAClF,QAAQ,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC;IAChC,kFAAkF;IAClF,QAAQ,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAChC,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,gBAAiB,SAAQ,SAAS;IAC7C,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,SAAS,CAAiB;IAClC,OAAO,CAAC,UAAU,CAAsB;IACxC,yEAAyE;IACzE,OAAO,CAAC,KAAK,CAAoC;gBAErC,OAAO,GAAE,uBAA4B;IAsBjD;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAiC/B,2EAA2E;IAC3E,OAAO,CAAC,MAAM,CAAC,SAAS;IAQxB,0EAA0E;IAC1E,OAAO,CAAC,MAAM,CAAC,eAAe;IAQ9B;;;;OAIG;IACH,SAAS,CAAC,kBAAkB,IAAI,KAAK,CAAC,QAAQ;IAO9C,8EAA8E;IAC9E,OAAO,CAAC,UAAU;IAMlB,yEAAyE;IACzE,OAAO,CAAC,kBAAkB;IAe1B,8DAA8D;IAC9D,OAAO,CAAC,MAAM,CAAC,cAAc;IAW7B,qEAAqE;cAClD,oBAAoB,IAAI,IAAI;IAQ/C;;;OAGG;IACH,YAAY,CAAC,SAAS,EAAE,iBAAiB,EAAE,GAAG,IAAI;IAgBlD,yEAAyE;IACzE,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI;IAiBhF,oEAAoE;IACpE,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAWpD,OAAO,CAAC,YAAY;IAQpB,8CAA8C;IAC9C,gBAAgB,IAAI,MAAM;IAI1B,gFAAgF;IAChF,gBAAgB,IAAI,KAAK,CAAC,aAAa;IAQvC,iFAAiF;IACjF,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,KAAK,CAAC,OAA6B,GAAG,KAAK,CAAC,OAAO;IAMzF,kDAAkD;IAClD,WAAW,IAAI,KAAK,CAAC,cAAc;IAInC,kDAAkD;IAClD,WAAW,IAAI,KAAK,CAAC,QAAQ;IAI7B;;;;OAIG;IACM,OAAO,IAAI,OAAO;IAI3B,2EAA2E;IAClE,OAAO,IAAI,IAAI;IAOf,IAAI,IAAI,gBAAgB;CAWlC"}

package/dist/mobjects/three-d/ModelMobject.d.ts

@@ -1,5 +1,6 @@
 import { Vector3Tuple } from '../../core/Mobject';
 import { Mobject3D } from './Mobject3D';
+import { MtlLoader } from './objMaterials';
 /**
  * ModelMobject - import an external 3D model (glTF / .glb / .obj) as a mobject.
  *
@@ -56,12 +57,25 @@ export interface ModelMobjectOptions {
     center?: boolean;
     /** Convenience fill color applied to every mesh material. */
     color?: string;
-    /** Replace every mesh material with this one. Wins over `color`. */
+    /** Replace every mesh material with this one. Wins over `color` and MTL. */
     materialOverride?: THREE.Material;
+    /**
+     * For .obj only: explicit companion .mtl URL. Its materials and texture maps
+     * apply to the meshes. `materialOverride` and `color` still win over them.
+     * Ignored for glTF, which embeds its materials natively.
+     */
+    mtlUrl?: string;
+    /**
+     * For .obj only: auto-derive the .mtl URL from the .obj URL and load it.
+     * `mtlUrl` takes priority when both are set. Default: false.
+     */
+    loadMaterials?: boolean;
     /** Progress callback forwarded to the loader. */
     onProgress?: (event: ProgressEvent) => void;
     /** Inject a loader directly (bypasses the factory and the network). */
     loader?: ModelLoader;
+    /** Inject an MTLLoader directly (bypasses the factory and the network). */
+    mtlLoader?: MtlLoader;
     /**
      * When false, a load failure resolves to an empty ModelMobject whose
      * {@link ModelMobject.getLoadError} holds the error instead of rejecting.
@@ -96,6 +110,10 @@ export declare class ModelMobject extends Mobject3D {
      * The loader is chosen from the extension: `.glb` / `.gltf` -> GLTFLoader,
      * `.obj` -> OBJLoader. Inject a loader with the `loader` option (or
      * `setModelLoaderFactory`) to avoid the network, e.g. in tests.
+     *
+     * For `.obj`, set `mtlUrl` (or `loadMaterials: true` to derive the .mtl URL)
+     * to load the companion .mtl and apply its materials and texture maps before
+     * the OBJ parse. `materialOverride` and `color` still win over them.
      */
     static fromUrl(url: string, options?: ModelMobjectOptions): Promise<ModelMobject>;
     /** Offset the center group so the model's bounding box sits at the origin. */

package/dist/mobjects/three-d/ModelMobject.d.ts.map

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

package/dist/mobjects/three-d/index.d.ts

@@ -20,4 +20,5 @@ export { Prism, Dot3D, ThreeDVMobject, type PrismOptions, type Dot3DOptions, typ
 export { ConvexHull3D, type ConvexHull3DOptions } from './ConvexHull3D';
 export { marchingCubes, type MarchingCubesOptions, type MarchingCubesResult, type ScalarField3D, } from './marchingCubes';
 export { ImplicitSurface, type ImplicitSurfaceOptions } from './ImplicitSurface';
+export { InstancedMobject, type InstancedMobjectOptions, type InstanceTransform, } from './InstancedMobject';
 //# sourceMappingURL=index.d.ts.map

package/dist/mobjects/three-d/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mobjects/three-d/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAGnD,OAAO,EACL,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAGnE,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,KAAK,wBAAwB,GAC9B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,eAAe,EACf,cAAc,EACd,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGlE,OAAO,EACL,KAAK,EACL,KAAK,EACL,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,qBAAqB,GAC3B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mobjects/three-d/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAGnD,OAAO,EACL,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAGnE,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,KAAK,wBAAwB,GAC9B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,eAAe,EACf,cAAc,EACd,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGlE,OAAO,EACL,KAAK,EACL,KAAK,EACL,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,qBAAqB,GAC3B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAGjF,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,GACvB,MAAM,oBAAoB,CAAC"}

package/dist/mobjects/three-d/objMaterials.d.ts

@@ -0,0 +1,54 @@
+import { ModelLoader } from './ModelMobject';
+/** A preloaded MTL material set. Three.js MaterialCreator satisfies it. */
+export interface MtlMaterials {
+    preload(): void;
+}
+/**
+ * The minimal MTLLoader contract ModelMobject needs. Three.js MTLLoader
+ * satisfies it structurally. Tests implement it with a stub.
+ */
+export interface MtlLoader {
+    setPath(path: string): MtlLoader;
+    setResourcePath(path: string): MtlLoader;
+    loadAsync(url: string, onProgress?: (event: ProgressEvent) => void): Promise<MtlMaterials>;
+}
+/**
+ * The OBJLoader subset that accepts materials. OBJLoader.setMaterials applies
+ * the given materials to the meshes it then parses.
+ */
+export interface ObjMaterialSink {
+    setMaterials(materials: MtlMaterials): void;
+}
+/** Builds an MTLLoader. The DI seam set by `setMtlLoaderFactory`. */
+export type MtlLoaderFactory = () => MtlLoader | Promise<MtlLoader>;
+/** The options that drive OBJ material loading. A subset of ModelMobjectOptions. */
+export interface ObjMaterialOptions {
+    /** Explicit companion .mtl URL. Takes priority over `loadMaterials`. */
+    mtlUrl?: string;
+    /** Auto-derive the .mtl URL from the .obj URL and load it. Default: false. */
+    loadMaterials?: boolean;
+    /** Inject an MTLLoader directly (bypasses the factory and the network). */
+    mtlLoader?: MtlLoader;
+    /** Progress callback forwarded to the MTLLoader. */
+    onProgress?: (event: ProgressEvent) => void;
+}
+/**
+ * Inject an MTLLoader factory, replacing the lazy-loaded Three.js MTLLoader.
+ * Pass `null` to restore the default. Tests use this to avoid any real loader.
+ */
+export declare function setMtlLoaderFactory(factory: MtlLoaderFactory | null): void;
+/** The directory part of a URL, with its trailing slash; ignores query and fragment. */
+export declare function deriveBasePath(url: string): string;
+/** The companion .mtl URL for an .obj URL (same name, .mtl extension). */
+export declare function deriveMtlUrl(objUrl: string): string;
+/**
+ * Load the companion .mtl and hand its materials to the OBJ loader before it
+ * parses. Call this on the resolved OBJ loader before `loadAsync`.
+ *
+ * It is a no-op when neither `mtlUrl` nor `loadMaterials` is set (so an OBJ
+ * loads exactly as before), and when the loader cannot accept materials. The
+ * MTLLoader base path and resource path come from the .mtl URL, so texture maps
+ * named in the .mtl load from the same directory.
+ */
+export declare function applyObjMaterials(loader: ModelLoader, objUrl: string, options: ObjMaterialOptions): Promise<void>;
+//# sourceMappingURL=objMaterials.d.ts.map

package/dist/mobjects/three-d/objMaterials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"objMaterials.d.ts","sourceRoot":"","sources":["../../../src/mobjects/three-d/objMaterials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC3B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC5F;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,SAAS,EAAE,YAAY,GAAG,IAAI,CAAC;CAC7C;AAED,qEAAqE;AACrE,MAAM,MAAM,gBAAgB,GAAG,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;AAEpE,oFAAoF;AACpF,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,oDAAoD;IACpD,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CAC7C;AAKD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAE1E;AAeD,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIlD;AASD,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGnD;AAcD;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAWf"}