xray-manager 1.1.1 → 1.2.0

package/dist/services/layout-manager.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * Layout Manager Service
+ *
+ * Manages terminal layout detection, caching, and resize events
+ * Feature: 005-ui-layout-expansion
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LayoutManager = void 0;
+const layout_1 = require("../types/layout");
+/**
+ * Resize debounce delay (300ms as per research.md)
+ */
+const RESIZE_DEBOUNCE_MS = 300;
+/**
+ * Layout Manager class
+ *
+ * Singleton service for managing terminal layouts
+ */
+class LayoutManager {
+    constructor() {
+        this.currentLayout = null;
+        this.layoutCache = new Map();
+        this.resizeCallbacks = [];
+        this.resizeTimer = null;
+    }
+    /**
+     * Detect current terminal size
+     */
+    detectTerminalSize() {
+        const isTTY = process.stdout.isTTY ?? false;
+        if (isTTY && process.stdout.columns && process.stdout.rows) {
+            return {
+                width: process.stdout.columns,
+                height: process.stdout.rows,
+                isTTY: true,
+            };
+        }
+        // Fallback to default size
+        return {
+            width: layout_1.DEFAULT_LAYOUT.width,
+            height: layout_1.DEFAULT_LAYOUT.height,
+            isTTY,
+        };
+    }
+    /**
+     * Calculate layout mode based on terminal width
+     */
+    calculateLayoutMode(width) {
+        if (width < layout_1.LAYOUT_MODE_THRESHOLDS.STANDARD_MIN) {
+            return layout_1.LayoutMode.COMPACT;
+        }
+        else if (width > layout_1.LAYOUT_MODE_THRESHOLDS.STANDARD_MAX) {
+            return layout_1.LayoutMode.WIDE;
+        }
+        else {
+            return layout_1.LayoutMode.STANDARD;
+        }
+    }
+    /**
+     * Create a new layout configuration
+     */
+    createLayout(mode, regions, options) {
+        const size = this.detectTerminalSize();
+        // Determine columns based on mode
+        let columns = 1;
+        if (mode === layout_1.LayoutMode.WIDE) {
+            columns = 2; // Default to 2 columns for WIDE mode
+        }
+        // Allow force mode override
+        const actualMode = options?.forceMode ?? mode;
+        const layout = {
+            width: size.width,
+            height: size.height,
+            mode: actualMode,
+            columns,
+            regions,
+            timestamp: Date.now(),
+        };
+        // Validate before returning
+        (0, layout_1.validateLayout)(layout);
+        // Cache if enabled
+        if (options?.enableCache !== false) {
+            const cacheKey = `${actualMode}-${regions.length}`;
+            this.layoutCache.set(cacheKey, {
+                layout,
+                timestamp: Date.now(),
+            });
+        }
+        this.currentLayout = layout;
+        return layout;
+    }
+    /**
+     * Get current cached layout
+     */
+    getCurrentLayout() {
+        return this.currentLayout;
+    }
+    /**
+     * Clear layout cache
+     */
+    clearCache() {
+        this.layoutCache.clear();
+    }
+    /**
+     * Refresh layout (re-detect and re-create)
+     */
+    refreshLayout(regions, options) {
+        const size = this.detectTerminalSize();
+        const mode = this.calculateLayoutMode(size.width);
+        const regionsToUse = regions ?? this.currentLayout?.regions ?? [];
+        return this.createLayout(mode, regionsToUse, options);
+    }
+    /**
+     * Register resize event listener with debounce
+     */
+    onResize(callback) {
+        this.resizeCallbacks.push(callback);
+        // Set up resize listener if this is the first callback
+        if (this.resizeCallbacks.length === 1) {
+            process.stdout.on('resize', this.handleResize.bind(this));
+        }
+        // Return unsubscribe function
+        return () => {
+            const index = this.resizeCallbacks.indexOf(callback);
+            if (index > -1) {
+                this.resizeCallbacks.splice(index, 1);
+            }
+            // Remove listener if no more callbacks
+            if (this.resizeCallbacks.length === 0) {
+                process.stdout.off('resize', this.handleResize.bind(this));
+            }
+        };
+    }
+    /**
+     * Handle resize event with debounce
+     */
+    handleResize() {
+        // Clear existing timer
+        if (this.resizeTimer) {
+            clearTimeout(this.resizeTimer);
+        }
+        // Set new timer
+        this.resizeTimer = setTimeout(() => {
+            const newLayout = this.refreshLayout();
+            // Notify all callbacks
+            for (const callback of this.resizeCallbacks) {
+                callback(newLayout);
+            }
+            this.resizeTimer = null;
+        }, RESIZE_DEBOUNCE_MS);
+    }
+    /**
+     * Validate terminal size meets minimum requirements
+     */
+    validateTerminalSize(size) {
+        if (size.width < layout_1.MIN_TERMINAL_SIZE.width) {
+            return {
+                isValid: false,
+                message: `Terminal too narrow (${size.width} cols). Minimum: ${layout_1.MIN_TERMINAL_SIZE.width} cols.`,
+                suggestion: `Please resize your terminal to at least ${layout_1.MIN_TERMINAL_SIZE.width}x${layout_1.MIN_TERMINAL_SIZE.height} for optimal display.`,
+            };
+        }
+        if (size.height < layout_1.MIN_TERMINAL_SIZE.height) {
+            return {
+                isValid: false,
+                message: `Terminal too short (${size.height} rows). Minimum: ${layout_1.MIN_TERMINAL_SIZE.height} rows.`,
+                suggestion: `Please resize your terminal to at least ${layout_1.MIN_TERMINAL_SIZE.width}x${layout_1.MIN_TERMINAL_SIZE.height} for optimal display.`,
+            };
+        }
+        return {
+            isValid: true,
+        };
+    }
+}
+exports.LayoutManager = LayoutManager;
+/**
+ * Singleton instance
+ */
+exports.default = new LayoutManager();
+//# sourceMappingURL=layout-manager.js.map

package/dist/services/layout-manager.js.map

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

package/dist/types/layout.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Layout Type Definitions
+ *
+ * Core types for terminal layout system supporting responsive layouts
+ * and multi-column displays.
+ *
+ * Feature: 005-ui-layout-expansion
+ */
+/**
+ * Layout mode enum - defines different terminal size strategies
+ */
+export declare enum LayoutMode {
+    /** Narrow terminals (< 80 columns) */
+    COMPACT = "compact",
+    /** Standard terminals (80-120 columns) */
+    STANDARD = "standard",
+    /** Wide terminals (> 120 columns) */
+    WIDE = "wide"
+}
+/**
+ * Content region type enum - categorizes different UI regions
+ */
+export declare enum ContentRegionType {
+    /** Page header/title area */
+    HEADER = "header",
+    /** Menu options area */
+    MENU = "menu",
+    /** Status information area */
+    STATUS = "status",
+    /** Main content area */
+    CONTENT = "content",
+    /** Footer/hints area */
+    FOOTER = "footer"
+}
+/**
+ * Content region interface - defines a rectangular area in the terminal
+ */
+export interface ContentRegion {
+    /** Unique identifier for this region */
+    id: string;
+    /** Type of content this region contains */
+    type: ContentRegionType;
+    /** Position in the terminal (row, column) */
+    position: {
+        row: number;
+        column: number;
+    };
+    /** Size of the region (width, height in characters) */
+    size: {
+        width: number;
+        height: number;
+    };
+    /** Padding inside the region (top, right, bottom, left in characters) */
+    padding: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    /** Whether to display a border around this region */
+    showBorder: boolean;
+    /** Optional content data (type depends on region type) */
+    content?: unknown;
+}
+/**
+ * Terminal layout interface - complete layout configuration
+ */
+export interface TerminalLayout {
+    /** Terminal width in columns */
+    width: number;
+    /** Terminal height in rows */
+    height: number;
+    /** Current layout mode based on terminal width */
+    mode: LayoutMode;
+    /** Number of columns for multi-column layouts (1 for COMPACT/STANDARD, 2-3 for WIDE) */
+    columns: number;
+    /** List of content regions in this layout */
+    regions: ContentRegion[];
+    /** Timestamp when layout was calculated (for cache invalidation) */
+    timestamp: number;
+}
+/**
+ * Default layout configuration for non-TTY or fallback scenarios
+ */
+export declare const DEFAULT_LAYOUT: TerminalLayout;
+/**
+ * Minimum terminal size constraints
+ */
+export declare const MIN_TERMINAL_SIZE: {
+    readonly width: 60;
+    readonly height: 20;
+};
+/**
+ * Layout mode thresholds for width-based mode selection
+ */
+export declare const LAYOUT_MODE_THRESHOLDS: {
+    readonly COMPACT_MAX: 79;
+    readonly STANDARD_MIN: 80;
+    readonly STANDARD_MAX: 120;
+    readonly WIDE_MIN: 121;
+};
+/**
+ * Validate that a TerminalLayout configuration is valid
+ *
+ * @param layout - Layout to validate
+ * @returns true if valid
+ * @throws Error if validation fails
+ */
+export declare function validateLayout(layout: TerminalLayout): boolean;
+/**
+ * Validate that a ContentRegion is valid within a given layout
+ *
+ * @param region - Region to validate
+ * @param layout - Parent layout
+ * @returns true if valid
+ * @throws Error if validation fails
+ */
+export declare function validateRegion(region: ContentRegion, layout: TerminalLayout): boolean;
+//# sourceMappingURL=layout.d.ts.map

package/dist/types/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../src/types/layout.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AAEH,oBAAY,UAAU;IACpB,sCAAsC;IACtC,OAAO,YAAY;IACnB,0CAA0C;IAC1C,QAAQ,aAAa;IACrB,qCAAqC;IACrC,IAAI,SAAS;CACd;AAGD;;GAEG;AAEH,oBAAY,iBAAiB;IAC3B,6BAA6B;IAC7B,MAAM,WAAW;IACjB,wBAAwB;IACxB,IAAI,SAAS;IACb,8BAA8B;IAC9B,MAAM,WAAW;IACjB,wBAAwB;IACxB,OAAO,YAAY;IACnB,wBAAwB;IACxB,MAAM,WAAW;CAClB;AAGD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IAEX,2CAA2C;IAC3C,IAAI,EAAE,iBAAiB,CAAC;IAExB,6CAA6C;IAC7C,QAAQ,EAAE;QACR,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IAEF,uDAAuD;IACvD,IAAI,EAAE;QACJ,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IAEF,yEAAyE;IACzE,OAAO,EAAE;QACP,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IAEF,qDAAqD;IACrD,UAAU,EAAE,OAAO,CAAC;IAEpB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IAEd,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IAEf,kDAAkD;IAClD,IAAI,EAAE,UAAU,CAAC;IAEjB,wFAAwF;IACxF,OAAO,EAAE,MAAM,CAAC;IAEhB,6CAA6C;IAC7C,OAAO,EAAE,aAAa,EAAE,CAAC;IAEzB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,cAO5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;CAGpB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;;CAKzB,CAAC;AAEX;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAoC9D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAsCrF"}

package/dist/types/layout.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * Layout Type Definitions
+ *
+ * Core types for terminal layout system supporting responsive layouts
+ * and multi-column displays.
+ *
+ * Feature: 005-ui-layout-expansion
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LAYOUT_MODE_THRESHOLDS = exports.MIN_TERMINAL_SIZE = exports.DEFAULT_LAYOUT = exports.ContentRegionType = exports.LayoutMode = void 0;
+exports.validateLayout = validateLayout;
+exports.validateRegion = validateRegion;
+/**
+ * Layout mode enum - defines different terminal size strategies
+ */
+/* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars */
+var LayoutMode;
+(function (LayoutMode) {
+    /** Narrow terminals (< 80 columns) */
+    LayoutMode["COMPACT"] = "compact";
+    /** Standard terminals (80-120 columns) */
+    LayoutMode["STANDARD"] = "standard";
+    /** Wide terminals (> 120 columns) */
+    LayoutMode["WIDE"] = "wide";
+})(LayoutMode || (exports.LayoutMode = LayoutMode = {}));
+/* eslint-enable @typescript-eslint/no-unused-vars, no-unused-vars */
+/**
+ * Content region type enum - categorizes different UI regions
+ */
+/* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars */
+var ContentRegionType;
+(function (ContentRegionType) {
+    /** Page header/title area */
+    ContentRegionType["HEADER"] = "header";
+    /** Menu options area */
+    ContentRegionType["MENU"] = "menu";
+    /** Status information area */
+    ContentRegionType["STATUS"] = "status";
+    /** Main content area */
+    ContentRegionType["CONTENT"] = "content";
+    /** Footer/hints area */
+    ContentRegionType["FOOTER"] = "footer";
+})(ContentRegionType || (exports.ContentRegionType = ContentRegionType = {}));
+/**
+ * Default layout configuration for non-TTY or fallback scenarios
+ */
+exports.DEFAULT_LAYOUT = {
+    width: 80,
+    height: 24,
+    mode: LayoutMode.STANDARD,
+    columns: 1,
+    regions: [],
+    timestamp: 0,
+};
+/**
+ * Minimum terminal size constraints
+ */
+exports.MIN_TERMINAL_SIZE = {
+    width: 60,
+    height: 20,
+};
+/**
+ * Layout mode thresholds for width-based mode selection
+ */
+exports.LAYOUT_MODE_THRESHOLDS = {
+    COMPACT_MAX: 79,
+    STANDARD_MIN: 80,
+    STANDARD_MAX: 120,
+    WIDE_MIN: 121,
+};
+/**
+ * Validate that a TerminalLayout configuration is valid
+ *
+ * @param layout - Layout to validate
+ * @returns true if valid
+ * @throws Error if validation fails
+ */
+function validateLayout(layout) {
+    // 1. Check minimum size
+    if (layout.width < exports.MIN_TERMINAL_SIZE.width || layout.height < exports.MIN_TERMINAL_SIZE.height) {
+        throw new Error(`Terminal too small: ${layout.width}x${layout.height} (min: ${exports.MIN_TERMINAL_SIZE.width}x${exports.MIN_TERMINAL_SIZE.height})`);
+    }
+    // 2. Check mode matches width
+    const expectedMode = layout.width < exports.LAYOUT_MODE_THRESHOLDS.STANDARD_MIN
+        ? LayoutMode.COMPACT
+        : layout.width > exports.LAYOUT_MODE_THRESHOLDS.STANDARD_MAX
+            ? LayoutMode.WIDE
+            : LayoutMode.STANDARD;
+    if (layout.mode !== expectedMode) {
+        throw new Error(`LayoutMode mismatch: expected ${expectedMode} for width ${layout.width}, got ${layout.mode}`);
+    }
+    // 3. Check columns constraint
+    if (layout.mode === LayoutMode.WIDE && layout.columns < 2) {
+        throw new Error(`WIDE mode requires columns >= 2, got ${layout.columns}`);
+    }
+    if (layout.mode !== LayoutMode.WIDE && layout.columns !== 1) {
+        throw new Error(`Non-WIDE mode requires columns = 1, got ${layout.columns}`);
+    }
+    // 4. Validate all content regions
+    for (const region of layout.regions) {
+        validateRegion(region, layout);
+    }
+    return true;
+}
+/**
+ * Validate that a ContentRegion is valid within a given layout
+ *
+ * @param region - Region to validate
+ * @param layout - Parent layout
+ * @returns true if valid
+ * @throws Error if validation fails
+ */
+function validateRegion(region, layout) {
+    // 1. Check position bounds
+    if (region.position.row < 0 || region.position.row >= layout.height) {
+        throw new Error(`Region ${region.id}: row ${region.position.row} out of bounds (0-${layout.height - 1})`);
+    }
+    if (region.position.column < 0 || region.position.column >= layout.width) {
+        throw new Error(`Region ${region.id}: column ${region.position.column} out of bounds (0-${layout.width - 1})`);
+    }
+    // 2. Check size bounds
+    const maxWidth = layout.width - region.position.column;
+    const maxHeight = layout.height - region.position.row;
+    if (region.size.width <= 0 || region.size.width > maxWidth) {
+        throw new Error(`Region ${region.id}: width ${region.size.width} out of bounds (1-${maxWidth})`);
+    }
+    if (region.size.height <= 0 || region.size.height > maxHeight) {
+        throw new Error(`Region ${region.id}: height ${region.size.height} out of bounds (1-${maxHeight})`);
+    }
+    // 3. Check padding validity
+    const totalHorizontalPadding = region.padding.left + region.padding.right;
+    const totalVerticalPadding = region.padding.top + region.padding.bottom;
+    if (totalHorizontalPadding >= region.size.width) {
+        throw new Error(`Region ${region.id}: horizontal padding ${totalHorizontalPadding} >= width ${region.size.width}`);
+    }
+    if (totalVerticalPadding >= region.size.height) {
+        throw new Error(`Region ${region.id}: vertical padding ${totalVerticalPadding} >= height ${region.size.height}`);
+    }
+    return true;
+}
+//# sourceMappingURL=layout.js.map

package/dist/types/layout.js.map

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

package/dist/utils/layout.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Layout Utility Functions
+ *
+ * Pure functions for layout calculations, text fitting, and rendering
+ * Feature: 005-ui-layout-expansion
+ */
+/**
+ * Table column definition
+ */
+export interface TableColumn {
+    header: string;
+    key: string;
+    width?: number;
+    align?: 'left' | 'center' | 'right';
+}
+/**
+ * Render options for tables and sections
+ */
+export interface RenderOptions {
+    showBorder?: boolean;
+    borderStyle?: 'single' | 'double' | 'compact';
+    padding?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+/**
+ * Calculate the display width of a string, accounting for Chinese characters
+ *
+ * Chinese characters (and other full-width characters) occupy 2 columns,
+ * while ASCII characters occupy 1 column.
+ *
+ * @param text - Input text
+ * @returns Display width in terminal columns
+ */
+export declare function calculateDisplayWidth(text: string): number;
+/**
+ * Calculate the width of each column in a multi-column layout
+ *
+ * Formula: (totalWidth - (columns - 1) * gap) / columns
+ *
+ * @param totalWidth - Total available width
+ * @param columns - Number of columns
+ * @param gap - Space between columns
+ * @returns Width of each column (rounded down)
+ */
+export declare function calculateColumnWidth(totalWidth: number, columns: number, gap: number): number;
+/**
+ * Fit text to a specific width by truncating or padding
+ *
+ * @param text - Input text
+ * @param width - Target width in columns
+ * @param align - Alignment ('left', 'center', 'right')
+ * @param ellipsis - Ellipsis string for truncation (default '...')
+ * @returns Text adjusted to exact width
+ */
+export declare function fitText(text: string, width: number, align?: 'left' | 'center' | 'right', ellipsis?: string): string;
+/**
+ * Render a horizontal separator line
+ *
+ * @param width - Width of separator in columns
+ * @param char - Character to use (default '─')
+ * @param color - Optional chalk color name
+ * @returns Separator string
+ */
+export declare function renderSeparator(width: number, char?: string, color?: string): string;
+/**
+ * Render a header with optional alignment and border
+ *
+ * @param title - Header title text
+ * @param width - Total width
+ * @param align - Alignment
+ * @param options - Render options
+ * @returns Rendered header string
+ */
+export declare function renderHeader(title: string, width: number, align?: 'left' | 'center' | 'right', options?: {
+    showBorder?: boolean;
+    color?: string;
+}): string;
+/**
+ * Apply padding to a text block
+ *
+ * @param text - Original text (can be multi-line)
+ * @param padding - Padding configuration
+ * @param width - Target width (for horizontal padding)
+ * @returns Padded text
+ */
+export declare function applyPadding(text: string, padding: {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}, width: number): string;
+/**
+ * Render a table using cli-table3
+ *
+ * @param columns - Column definitions
+ * @param rows - Data rows
+ * @param options - Render options
+ * @returns Rendered table string
+ */
+export declare function renderTable(columns: TableColumn[], rows: Record<string, unknown>[], options?: RenderOptions): string;
+/**
+ * Render a section with title and content
+ *
+ * @param title - Section title
+ * @param content - Section content (can be multi-line)
+ * @param options - Render options
+ * @returns Rendered section string
+ */
+export declare function renderSection(title: string, content: string, options?: RenderOptions): string;
+/**
+ * Distribute items evenly across multiple columns
+ *
+ * @param items - Array of items to distribute
+ * @param columnCount - Number of columns to create
+ * @returns Array of columns, each containing a subset of items
+ *
+ * @example
+ * distributeToColumns(['A', 'B', 'C', 'D', 'E', 'F'], 2)
+ * // Returns: [['A', 'B', 'C'], ['D', 'E', 'F']]
+ *
+ * distributeToColumns(['A', 'B', 'C', 'D', 'E'], 2)
+ * // Returns: [['A', 'B', 'C'], ['D', 'E']]
+ */
+export declare function distributeToColumns<T>(items: T[], columnCount: number): T[][];
+/**
+ * Render multiple columns of text side by side
+ *
+ * @param columns - Array of columns, each containing lines of text
+ * @param totalWidth - Total width available for all columns
+ * @param gap - Space between columns (default: 2)
+ * @returns Rendered multi-column text
+ *
+ * @example
+ * renderColumns([['Line 1', 'Line 2'], ['Col 2 Line 1', 'Col 2 Line 2']], 80, 2)
+ * // Returns text with two columns side by side
+ */
+export declare function renderColumns(columns: string[][], totalWidth: number, gap?: number): string;
+//# sourceMappingURL=layout.d.ts.map

package/dist/utils/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../src/utils/layout.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC9C,OAAO,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACxE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAwB1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7F;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAM,GAAG,QAAQ,GAAG,OAAgB,EAC3C,QAAQ,GAAE,MAAc,GACvB,MAAM,CAwCR;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,MAAY,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAczF;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAM,GAAG,QAAQ,GAAG,OAAkB,EAC7C,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD,MAAM,CAiBR;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACrE,KAAK,EAAE,MAAM,GACZ,MAAM,CAuBR;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,WAAW,EAAE,EACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,OAAO,CAAC,EAAE,aAAa,GACtB,MAAM,CAkFR;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,aAAa,GACtB,MAAM,CAoDR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAoB7E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,GAAE,MAAU,GAAG,MAAM,CAyB9F"}