@rxflow/manhattan 0.0.2 → 0.0.3

package/cjs/utils/ErrorRecovery.d.ts

@@ -0,0 +1,182 @@
+/**
+ * ErrorRecovery - 错误恢复和降级策略
+ *
+ * 提供路径计算失败时的恢复机制，包括：
+ * - 超时检测和处理
+ * - 降级路径生成
+ * - 错误分类和报告
+ *
+ * Implements: Requirements 4.2, 3.6
+ */
+import { Point, Rectangle } from '../geometry';
+/**
+ * 错误类型枚举
+ */
+export declare enum PathfindingErrorType {
+    /** 超时错误 - 计算时间超过限制 */
+    TIMEOUT = "TIMEOUT",
+    /** 无路径错误 - 无法找到有效路径 */
+    NO_PATH = "NO_PATH",
+    /** 无效输入错误 - 输入参数无效 */
+    INVALID_INPUT = "INVALID_INPUT",
+    /** 障碍物阻塞错误 - 起点或终点被障碍物阻塞 */
+    BLOCKED = "BLOCKED",
+    /** 内部错误 - 算法内部错误 */
+    INTERNAL = "INTERNAL"
+}
+/**
+ * 路径计算错误
+ */
+export declare class PathfindingError extends Error {
+    readonly type: PathfindingErrorType;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(type: PathfindingErrorType, message: string, details?: Record<string, unknown> | undefined);
+}
+/**
+ * 恢复策略类型
+ */
+export declare enum RecoveryStrategy {
+    /** 直线连接 */
+    DIRECT_LINE = "DIRECT_LINE",
+    /** L形路径 */
+    L_SHAPE = "L_SHAPE",
+    /** Z形路径 */
+    Z_SHAPE = "Z_SHAPE",
+    /** 简化曼哈顿路径 */
+    SIMPLE_MANHATTAN = "SIMPLE_MANHATTAN",
+    /** 无恢复 */
+    NONE = "NONE"
+}
+/**
+ * 恢复结果
+ */
+export interface RecoveryResult {
+    /** 是否成功恢复 */
+    success: boolean;
+    /** 恢复后的路径 */
+    path: Point[];
+    /** 使用的恢复策略 */
+    strategy: RecoveryStrategy;
+    /** 原始错误 */
+    originalError?: PathfindingError;
+    /** 恢复耗时（毫秒） */
+    recoveryTime: number;
+}
+/**
+ * 错误恢复配置
+ */
+export interface ErrorRecoveryConfig {
+    /** 是否启用自动恢复 */
+    enabled: boolean;
+    /** 最大恢复尝试次数 */
+    maxAttempts: number;
+    /** 恢复策略优先级 */
+    strategyPriority: RecoveryStrategy[];
+    /** 是否记录恢复日志 */
+    logRecovery: boolean;
+}
+/**
+ * 默认恢复配置
+ */
+export declare const DEFAULT_RECOVERY_CONFIG: ErrorRecoveryConfig;
+/**
+ * 错误恢复类
+ */
+export declare class ErrorRecovery {
+    private config;
+    private recoveryAttempts;
+    constructor(config?: Partial<ErrorRecoveryConfig>);
+    /**
+     * 尝试恢复路径计算
+     */
+    recover(from: Point, to: Point, error: PathfindingError, obstacles?: Rectangle[]): RecoveryResult;
+    /**
+     * 应用恢复策略
+     */
+    private applyStrategy;
+    /**
+     * 直线连接策略
+     */
+    private directLine;
+    /**
+     * L形路径策略
+     */
+    private lShape;
+    /**
+     * Z形路径策略
+     */
+    private zShape;
+    /**
+     * 简化曼哈顿路径策略
+     */
+    private simpleManhattan;
+    /**
+     * 检查路径是否与障碍物相交
+     */
+    private pathIntersectsObstacles;
+    /**
+     * 检查线段是否与矩形相交
+     */
+    private lineIntersectsRect;
+    /**
+     * 检查点是否在矩形内部
+     */
+    private pointInRect;
+    /**
+     * 检查两条线段是否相交
+     */
+    private lineIntersectsLine;
+    /**
+     * 计算叉积方向
+     */
+    private direction;
+    /**
+     * 检查点是否在线段上
+     */
+    private onSegment;
+    /**
+     * 创建超时错误
+     */
+    static createTimeoutError(iterations: number, maxIterations: number): PathfindingError;
+    /**
+     * 创建无路径错误
+     */
+    static createNoPathError(from: Point, to: Point): PathfindingError;
+    /**
+     * 创建无效输入错误
+     */
+    static createInvalidInputError(message: string): PathfindingError;
+    /**
+     * 创建阻塞错误
+     */
+    static createBlockedError(point: Point, type: 'source' | 'target'): PathfindingError;
+    /**
+     * 创建内部错误
+     */
+    static createInternalError(message: string, cause?: Error): PathfindingError;
+    /**
+     * 生成回退路径（静态方法）
+     */
+    static generateFallbackPath(source: Point, target: Point): Point[];
+    /**
+     * 验证并修复配置选项
+     */
+    static validateAndFixOptions<T extends Record<string, unknown>>(options: T, defaults: T): T;
+    /**
+     * 获取恢复尝试次数
+     */
+    getRecoveryAttempts(): number;
+    /**
+     * 重置恢复状态
+     */
+    reset(): void;
+    /**
+     * 更新配置
+     */
+    updateConfig(config: Partial<ErrorRecoveryConfig>): void;
+    /**
+     * 获取当前配置
+     */
+    getConfig(): ErrorRecoveryConfig;
+}
+//# sourceMappingURL=ErrorRecovery.d.ts.map

package/cjs/utils/ErrorRecovery.d.ts.map

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

package/cjs/utils/ErrorRecovery.js

@@ -0,0 +1,413 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.RecoveryStrategy = exports.PathfindingErrorType = exports.PathfindingError = exports.ErrorRecovery = exports.DEFAULT_RECOVERY_CONFIG = void 0;
+var _geometry = require("../geometry");
+/**
+ * ErrorRecovery - 错误恢复和降级策略
+ *
+ * 提供路径计算失败时的恢复机制，包括：
+ * - 超时检测和处理
+ * - 降级路径生成
+ * - 错误分类和报告
+ *
+ * Implements: Requirements 4.2, 3.6
+ */
+/**
+ * 错误类型枚举
+ */
+let PathfindingErrorType = exports.PathfindingErrorType = /*#__PURE__*/function (PathfindingErrorType) {
+  PathfindingErrorType["TIMEOUT"] = "TIMEOUT";
+  PathfindingErrorType["NO_PATH"] = "NO_PATH";
+  PathfindingErrorType["INVALID_INPUT"] = "INVALID_INPUT";
+  PathfindingErrorType["BLOCKED"] = "BLOCKED";
+  PathfindingErrorType["INTERNAL"] = "INTERNAL";
+  return PathfindingErrorType;
+}({});
+/**
+ * 路径计算错误
+ */
+class PathfindingError extends Error {
+  constructor(type, message, details) {
+    super(message);
+    this.type = type;
+    this.details = details;
+    this.name = 'PathfindingError';
+  }
+}
+
+/**
+ * 恢复策略类型
+ */
+exports.PathfindingError = PathfindingError;
+let RecoveryStrategy = exports.RecoveryStrategy = /*#__PURE__*/function (RecoveryStrategy) {
+  RecoveryStrategy["DIRECT_LINE"] = "DIRECT_LINE";
+  RecoveryStrategy["L_SHAPE"] = "L_SHAPE";
+  RecoveryStrategy["Z_SHAPE"] = "Z_SHAPE";
+  RecoveryStrategy["SIMPLE_MANHATTAN"] = "SIMPLE_MANHATTAN";
+  RecoveryStrategy["NONE"] = "NONE";
+  return RecoveryStrategy;
+}({});
+/**
+ * 恢复结果
+ */
+/**
+ * 错误恢复配置
+ */
+/**
+ * 默认恢复配置
+ */
+const DEFAULT_RECOVERY_CONFIG = exports.DEFAULT_RECOVERY_CONFIG = {
+  enabled: true,
+  maxAttempts: 3,
+  strategyPriority: [RecoveryStrategy.SIMPLE_MANHATTAN, RecoveryStrategy.L_SHAPE, RecoveryStrategy.Z_SHAPE, RecoveryStrategy.DIRECT_LINE],
+  logRecovery: false
+};
+
+/**
+ * 错误恢复类
+ */
+class ErrorRecovery {
+  config;
+  recoveryAttempts = 0;
+  constructor(config = {}) {
+    this.config = {
+      ...DEFAULT_RECOVERY_CONFIG,
+      ...config
+    };
+  }
+
+  /**
+   * 尝试恢复路径计算
+   */
+  recover(from, to, error, obstacles) {
+    const startTime = performance.now();
+    if (!this.config.enabled) {
+      return {
+        success: false,
+        path: [],
+        strategy: RecoveryStrategy.NONE,
+        originalError: error,
+        recoveryTime: performance.now() - startTime
+      };
+    }
+    this.recoveryAttempts = 0;
+    for (const strategy of this.config.strategyPriority) {
+      if (this.recoveryAttempts >= this.config.maxAttempts) {
+        break;
+      }
+      this.recoveryAttempts++;
+      const path = this.applyStrategy(strategy, from, to, obstacles);
+      if (path.length > 0) {
+        if (this.config.logRecovery) {
+          console.info(`[ErrorRecovery] Recovered using ${strategy} after ${this.recoveryAttempts} attempts`);
+        }
+        return {
+          success: true,
+          path,
+          strategy,
+          originalError: error,
+          recoveryTime: performance.now() - startTime
+        };
+      }
+    }
+
+    // 所有策略都失败，返回直线作为最后手段
+    return {
+      success: true,
+      path: [from, to],
+      strategy: RecoveryStrategy.DIRECT_LINE,
+      originalError: error,
+      recoveryTime: performance.now() - startTime
+    };
+  }
+
+  /**
+   * 应用恢复策略
+   */
+  applyStrategy(strategy, from, to, obstacles) {
+    switch (strategy) {
+      case RecoveryStrategy.DIRECT_LINE:
+        return this.directLine(from, to);
+      case RecoveryStrategy.L_SHAPE:
+        return this.lShape(from, to, obstacles);
+      case RecoveryStrategy.Z_SHAPE:
+        return this.zShape(from, to, obstacles);
+      case RecoveryStrategy.SIMPLE_MANHATTAN:
+        return this.simpleManhattan(from, to, obstacles);
+      default:
+        return [];
+    }
+  }
+
+  /**
+   * 直线连接策略
+   */
+  directLine(from, to) {
+    return [from, to];
+  }
+
+  /**
+   * L形路径策略
+   */
+  lShape(from, to, obstacles) {
+    // 尝试先水平后垂直
+    const corner1 = new _geometry.Point(to.x, from.y);
+    const path1 = [from, corner1, to];
+    if (!obstacles || !this.pathIntersectsObstacles(path1, obstacles)) {
+      return path1;
+    }
+
+    // 尝试先垂直后水平
+    const corner2 = new _geometry.Point(from.x, to.y);
+    const path2 = [from, corner2, to];
+    if (!obstacles || !this.pathIntersectsObstacles(path2, obstacles)) {
+      return path2;
+    }
+    return [];
+  }
+
+  /**
+   * Z形路径策略
+   */
+  zShape(from, to, obstacles) {
+    const midX = (from.x + to.x) / 2;
+    const midY = (from.y + to.y) / 2;
+
+    // 尝试水平-垂直-水平 Z形
+    const path1 = [from, new _geometry.Point(midX, from.y), new _geometry.Point(midX, to.y), to];
+    if (!obstacles || !this.pathIntersectsObstacles(path1, obstacles)) {
+      return path1;
+    }
+
+    // 尝试垂直-水平-垂直 Z形
+    const path2 = [from, new _geometry.Point(from.x, midY), new _geometry.Point(to.x, midY), to];
+    if (!obstacles || !this.pathIntersectsObstacles(path2, obstacles)) {
+      return path2;
+    }
+    return [];
+  }
+
+  /**
+   * 简化曼哈顿路径策略
+   */
+  simpleManhattan(from, to, obstacles) {
+    const offsets = [0.25, 0.5, 0.75, 0.1, 0.9];
+    for (const offset of offsets) {
+      // 水平方向偏移
+      const midX = from.x + (to.x - from.x) * offset;
+      const path1 = [from, new _geometry.Point(midX, from.y), new _geometry.Point(midX, to.y), to];
+      if (!obstacles || !this.pathIntersectsObstacles(path1, obstacles)) {
+        return path1;
+      }
+
+      // 垂直方向偏移
+      const midY = from.y + (to.y - from.y) * offset;
+      const path2 = [from, new _geometry.Point(from.x, midY), new _geometry.Point(to.x, midY), to];
+      if (!obstacles || !this.pathIntersectsObstacles(path2, obstacles)) {
+        return path2;
+      }
+    }
+    return [];
+  }
+
+  /**
+   * 检查路径是否与障碍物相交
+   */
+  pathIntersectsObstacles(path, obstacles) {
+    for (let i = 0; i < path.length - 1; i++) {
+      const p1 = path[i];
+      const p2 = path[i + 1];
+      for (const obstacle of obstacles) {
+        if (this.lineIntersectsRect(p1, p2, obstacle)) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  /**
+   * 检查线段是否与矩形相交
+   */
+  lineIntersectsRect(p1, p2, rect) {
+    const minX = rect.x;
+    const maxX = rect.x + rect.width;
+    const minY = rect.y;
+    const maxY = rect.y + rect.height;
+
+    // 检查线段是否完全在矩形外部
+    if (p1.x < minX && p2.x < minX || p1.x > maxX && p2.x > maxX || p1.y < minY && p2.y < minY || p1.y > maxY && p2.y > maxY) {
+      return false;
+    }
+
+    // 检查线段端点是否在矩形内部
+    if (this.pointInRect(p1, rect) || this.pointInRect(p2, rect)) {
+      return true;
+    }
+
+    // 检查线段是否与矩形的四条边相交
+    return this.lineIntersectsLine(p1, p2, new _geometry.Point(minX, minY), new _geometry.Point(maxX, minY)) || this.lineIntersectsLine(p1, p2, new _geometry.Point(maxX, minY), new _geometry.Point(maxX, maxY)) || this.lineIntersectsLine(p1, p2, new _geometry.Point(maxX, maxY), new _geometry.Point(minX, maxY)) || this.lineIntersectsLine(p1, p2, new _geometry.Point(minX, maxY), new _geometry.Point(minX, minY));
+  }
+
+  /**
+   * 检查点是否在矩形内部
+   */
+  pointInRect(p, rect) {
+    return p.x > rect.x && p.x < rect.x + rect.width && p.y > rect.y && p.y < rect.y + rect.height;
+  }
+
+  /**
+   * 检查两条线段是否相交
+   */
+  lineIntersectsLine(p1, p2, p3, p4) {
+    const d1 = this.direction(p3, p4, p1);
+    const d2 = this.direction(p3, p4, p2);
+    const d3 = this.direction(p1, p2, p3);
+    const d4 = this.direction(p1, p2, p4);
+    if ((d1 > 0 && d2 < 0 || d1 < 0 && d2 > 0) && (d3 > 0 && d4 < 0 || d3 < 0 && d4 > 0)) {
+      return true;
+    }
+    if (d1 === 0 && this.onSegment(p3, p4, p1)) return true;
+    if (d2 === 0 && this.onSegment(p3, p4, p2)) return true;
+    if (d3 === 0 && this.onSegment(p1, p2, p3)) return true;
+    if (d4 === 0 && this.onSegment(p1, p2, p4)) return true;
+    return false;
+  }
+
+  /**
+   * 计算叉积方向
+   */
+  direction(p1, p2, p3) {
+    return (p3.x - p1.x) * (p2.y - p1.y) - (p2.x - p1.x) * (p3.y - p1.y);
+  }
+
+  /**
+   * 检查点是否在线段上
+   */
+  onSegment(p1, p2, p) {
+    return p.x >= Math.min(p1.x, p2.x) && p.x <= Math.max(p1.x, p2.x) && p.y >= Math.min(p1.y, p2.y) && p.y <= Math.max(p1.y, p2.y);
+  }
+
+  /**
+   * 创建超时错误
+   */
+  static createTimeoutError(iterations, maxIterations) {
+    return new PathfindingError(PathfindingErrorType.TIMEOUT, `Pathfinding timeout: exceeded ${maxIterations} iterations`, {
+      iterations,
+      maxIterations
+    });
+  }
+
+  /**
+   * 创建无路径错误
+   */
+  static createNoPathError(from, to) {
+    return new PathfindingError(PathfindingErrorType.NO_PATH, `No path found from (${from.x}, ${from.y}) to (${to.x}, ${to.y})`, {
+      from: {
+        x: from.x,
+        y: from.y
+      },
+      to: {
+        x: to.x,
+        y: to.y
+      }
+    });
+  }
+
+  /**
+   * 创建无效输入错误
+   */
+  static createInvalidInputError(message) {
+    return new PathfindingError(PathfindingErrorType.INVALID_INPUT, message);
+  }
+
+  /**
+   * 创建阻塞错误
+   */
+  static createBlockedError(point, type) {
+    return new PathfindingError(PathfindingErrorType.BLOCKED, `${type === 'source' ? 'Source' : 'Target'} point (${point.x}, ${point.y}) is blocked`, {
+      point: {
+        x: point.x,
+        y: point.y
+      },
+      type
+    });
+  }
+
+  /**
+   * 创建内部错误
+   */
+  static createInternalError(message, cause) {
+    return new PathfindingError(PathfindingErrorType.INTERNAL, message, {
+      cause: cause?.message
+    });
+  }
+
+  /**
+   * 生成回退路径（静态方法）
+   */
+  static generateFallbackPath(source, target) {
+    const midX = (source.x + target.x) / 2;
+    return [source, new _geometry.Point(midX, source.y), new _geometry.Point(midX, target.y), target];
+  }
+
+  /**
+   * 验证并修复配置选项
+   */
+  static validateAndFixOptions(options, defaults) {
+    const fixed = {
+      ...options
+    };
+    for (const key of Object.keys(defaults)) {
+      const value = fixed[key];
+      const defaultValue = defaults[key];
+      if (value === undefined || value === null) {
+        ;
+        fixed[key] = defaultValue;
+      } else if (typeof defaultValue === 'number' && typeof value === 'number') {
+        if (value <= 0 && defaultValue > 0) {
+          console.warn(`Invalid ${key} value (${value}), using default (${defaultValue})`);
+          fixed[key] = defaultValue;
+        }
+      }
+    }
+    return fixed;
+  }
+
+  /**
+   * 获取恢复尝试次数
+   */
+  getRecoveryAttempts() {
+    return this.recoveryAttempts;
+  }
+
+  /**
+   * 重置恢复状态
+   */
+  reset() {
+    this.recoveryAttempts = 0;
+  }
+
+  /**
+   * 更新配置
+   */
+  updateConfig(config) {
+    this.config = {
+      ...this.config,
+      ...config
+    };
+  }
+
+  /**
+   * 获取当前配置
+   */
+  getConfig() {
+    return {
+      ...this.config
+    };
+  }
+}
+exports.ErrorRecovery = ErrorRecovery;

package/cjs/utils/GlobalGrid.d.ts

@@ -0,0 +1,99 @@
+/**
+ * GlobalGrid class for consistent path alignment
+ * Feature: manhattan-optimization
+ *
+ * This class ensures all paths align to a unified global grid,
+ * solving the path overlap problem where paths should share segments.
+ */
+import { Point } from '../geometry';
+/**
+ * Global grid configuration
+ */
+export interface GlobalGridConfig {
+    /** Grid step size in X direction */
+    stepX: number;
+    /** Grid step size in Y direction */
+    stepY: number;
+    /** Grid origin point (default: (0, 0)) */
+    origin?: Point;
+}
+/**
+ * GlobalGrid class for managing grid alignment
+ *
+ * Key features:
+ * - Uses a fixed global origin (0, 0) for consistent alignment across all paths
+ * - Supports configurable step sizes
+ * - Provides methods for snapping points to grid
+ * - Ensures path segments can properly overlap when they should
+ */
+export declare class GlobalGrid {
+    /** Grid origin point */
+    readonly origin: Point;
+    /** Grid step size in X direction */
+    readonly stepX: number;
+    /** Grid step size in Y direction */
+    readonly stepY: number;
+    constructor(config: GlobalGridConfig);
+    /**
+     * Create a GlobalGrid with uniform step size
+     */
+    static uniform(step: number, origin?: Point): GlobalGrid;
+    /**
+     * Snap a single value to the grid
+     */
+    snapValue(value: number, step: number, originOffset?: number): number;
+    /**
+     * Snap a point to the global grid
+     */
+    snapToGrid(point: Point): Point;
+    /**
+     * Snap a point to grid and apply precision rounding
+     */
+    snapToGridWithPrecision(point: Point, precision: number): Point;
+    /**
+     * Check if a point is on the grid (within tolerance)
+     */
+    isOnGrid(point: Point, tolerance?: number): boolean;
+    /**
+     * Get the nearest grid point in a specific direction
+     */
+    getNearestGridPoint(point: Point, direction: 'up' | 'down' | 'left' | 'right' | 'nearest'): Point;
+    /**
+     * Get all grid points within a rectangle
+     */
+    getGridPointsInRect(minX: number, minY: number, maxX: number, maxY: number): Point[];
+    /**
+     * Calculate the grid distance between two points
+     * (number of grid steps, not actual distance)
+     */
+    gridDistance(p1: Point, p2: Point): {
+        x: number;
+        y: number;
+        total: number;
+    };
+    /**
+     * Snap an array of points to the grid
+     */
+    snapPathToGrid(points: Point[]): Point[];
+    /**
+     * Snap path to grid and remove duplicate consecutive points
+     */
+    snapAndSimplifyPath(points: Point[], tolerance?: number): Point[];
+    /**
+     * Get grid offset for a direction
+     */
+    getDirectionOffset(direction: 'up' | 'down' | 'left' | 'right'): Point;
+    /**
+     * Clone this grid with optional overrides
+     */
+    clone(overrides?: Partial<GlobalGridConfig>): GlobalGrid;
+    /**
+     * Create a string representation for debugging
+     */
+    toString(): string;
+}
+/**
+ * Default global grid instance with step size 10
+ */
+export declare const defaultGlobalGrid: GlobalGrid;
+//# sourceMappingURL=GlobalGrid.d.ts.map

package/cjs/utils/GlobalGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GlobalGrid.d.ts","sourceRoot":"","sources":["../../src/utils/GlobalGrid.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAEnC;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,0CAA0C;IAC1C,MAAM,CAAC,EAAE,KAAK,CAAA;CACf;AAED;;;;;;;;GAQG;AACH,qBAAa,UAAU;IACrB,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAA;IAEtB,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IAEtB,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;gBAEV,MAAM,EAAE,gBAAgB;IAWpC;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,GAAG,UAAU;IAQxD;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,GAAE,MAAU,GAAG,MAAM;IAMxE;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK;IAO/B;;OAEG;IACH,uBAAuB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,GAAG,KAAK;IAI/D;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,GAAE,MAAc,GAAG,OAAO;IAM1D;;OAEG;IACH,mBAAmB,CACjB,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GACtD,KAAK;IAqCR;;OAEG;IACH,mBAAmB,CACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,KAAK,EAAE;IAkBV;;;OAGG;IACH,YAAY,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,GAAG;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAW3E;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE;IAIxC;;OAEG;IACH,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,SAAS,GAAE,MAAc,GAAG,KAAK,EAAE;IAsBxE;;OAEG;IACH,kBAAkB,CAAC,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK;IAatE;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,UAAU;IAQxD;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGnB;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,YAAyB,CAAA"}