@zengjing/xmind-mcp 1.0.0

package/dist/model/schemas.js.map

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

package/dist/model/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Core data types representing the unified XMind AST model.
+ * Both Zen (JSON) and Legacy (XML) formats are normalized to this structure.
+ */
+export interface XMindNode {
+    /** Globally unique node identifier within the document */
+    id: string;
+    /** Node display title */
+    title: string;
+    /** Optional notes/description attached to the node */
+    note?: string;
+    /** Array of label strings (e.g., "Important", "Review") */
+    labels?: string[];
+    /** Array of marker types (e.g., "priority-1", "task-done", "bookmark") */
+    markers?: string[];
+    /** Child nodes in hierarchical order */
+    children: XMindNode[];
+    /** Optional hyperlink or internal node reference ID */
+    href?: string;
+    /** Optional position metadata (for layout preservation, if needed) */
+    position?: {
+        x?: number;
+        y?: number;
+    };
+}
+export interface XMindRelationship {
+    /** Unique relationship identifier */
+    id: string;
+    /** Optional relationship label/title */
+    title?: string;
+    /** Source node ID */
+    sourceId: string;
+    /** Target node ID */
+    targetId: string;
+}
+export interface XMindSheet {
+    /** Sheet unique identifier */
+    id: string;
+    /** Sheet display title */
+    title: string;
+    /** Root topic of the sheet (required in XMind) */
+    rootTopic: XMindNode;
+    /** Cross-node relationships/connectors (optional) */
+    relationships?: XMindRelationship[];
+}
+export interface XMindParsedResult {
+    /** Absolute file path of the parsed .xmind file */
+    filePath: string;
+    /** Array of sheets (typically 1, but XMind supports multiple) */
+    sheets: XMindSheet[];
+    /** Metadata about the parsing operation */
+    meta?: {
+        /** Format version detected: 'zen' (modern JSON) or 'legacy' (XML-based) */
+        formatVersion: 'zen' | 'legacy';
+        /** Total count of topics across all sheets */
+        topicCount: number;
+        /** Timestamp of parsing operation */
+        parsedAt: string;
+    };
+}
+export interface SearchResult {
+    /** The matched node */
+    node: XMindNode;
+    /** Where the match occurred: "title", "note", or "label" */
+    matchType: 'title' | 'note' | 'label';
+    /** The matched text excerpt */
+    matchText: string;
+    /** Breadcrumb path from root to this node (node IDs) */
+    pathToRoot: string[];
+}
+export interface BranchExtractionResult {
+    /** The root of the extracted subtree */
+    rootNode: XMindNode;
+    /** Actual depth reached (≤ requested depth) */
+    depthReached: number;
+    /** Total nodes in the extracted branch */
+    nodeCount: number;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/model/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,SAAS;IACxB,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IAEX,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IAEd,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB,wCAAwC;IACxC,QAAQ,EAAE,SAAS,EAAE,CAAC;IAEtB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,sEAAsE;IACtE,QAAQ,CAAC,EAAE;QACT,CAAC,CAAC,EAAE,MAAM,CAAC;QACX,CAAC,CAAC,EAAE,MAAM,CAAC;KACZ,CAAC;CACH;AAED,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,EAAE,EAAE,MAAM,CAAC;IAEX,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,qBAAqB;IACrB,QAAQ,EAAE,MAAM,CAAC;IAEjB,qBAAqB;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IAEX,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IAEd,kDAAkD;IAClD,SAAS,EAAE,SAAS,CAAC;IAErB,qDAAqD;IACrD,aAAa,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IAEjB,iEAAiE;IACjE,MAAM,EAAE,UAAU,EAAE,CAAC;IAErB,2CAA2C;IAC3C,IAAI,CAAC,EAAE;QACL,2EAA2E;QAC3E,aAAa,EAAE,KAAK,GAAG,QAAQ,CAAC;QAEhC,8CAA8C;QAC9C,UAAU,EAAE,MAAM,CAAC;QAEnB,qCAAqC;QACrC,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED,MAAM,WAAW,YAAY;IAC3B,uBAAuB;IACvB,IAAI,EAAE,SAAS,CAAC;IAEhB,4DAA4D;IAC5D,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IAEtC,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAElB,wDAAwD;IACxD,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,wCAAwC;IACxC,QAAQ,EAAE,SAAS,CAAC;IAEpB,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAC;IAErB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/model/types.js

@@ -0,0 +1,6 @@
+/**
+ * Core data types representing the unified XMind AST model.
+ * Both Zen (JSON) and Legacy (XML) formats are normalized to this structure.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/model/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/model/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/tools/branch-tool.d.ts

@@ -0,0 +1,20 @@
+/**
+ * MCP Tool: get_xmind_node_branch
+ * Extract a specific node and its descendants (up to specified depth).
+ */
+import type { Tool } from '@modelcontextprotocol/sdk/types';
+export declare const GET_BRANCH_TOOL: Tool;
+export interface BranchToolInput {
+    path: string;
+    nodeId: string;
+    depth?: number;
+}
+/**
+ * Execute the get_xmind_node_branch tool.
+ * Parses the file, finds the target node, extracts its branch with depth limit, and formats output.
+ *
+ * @param input - Tool input containing path, nodeId, and optional depth
+ * @returns Formatted branch output with Markdown outline and metadata
+ */
+export declare function executeBranchTool(input: BranchToolInput): Promise<string>;
+//# sourceMappingURL=branch-tool.d.ts.map

package/dist/tools/branch-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-tool.d.ts","sourceRoot":"","sources":["../../src/tools/branch-tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iCAAiC,CAAC;AAS5D,eAAO,MAAM,eAAe,EAAE,IAuB7B,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA0DD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CA4E/E"}

package/dist/tools/branch-tool.js

@@ -0,0 +1,150 @@
+/**
+ * MCP Tool: get_xmind_node_branch
+ * Extract a specific node and its descendants (up to specified depth).
+ */
+import { parseXMindFile } from '../core/parser.js';
+import { GetBranchInputSchema } from '../model/schemas.js';
+import { xmindToMarkdown } from '../formatters/markdown-formatter.js';
+import { resolveFilePath, isValidNodeId } from '../utils/file-utils.js';
+import { isXMindError } from '../utils/errors.js';
+import { debug, info, warn, error as logError } from '../utils/logger.js';
+export const GET_BRANCH_TOOL = {
+    name: 'get_xmind_node_branch',
+    description: 'Extract a specific node and its subtree (up to specified depth) from an XMind file. ' +
+        'Useful for large mind maps to avoid token overload by retrieving only relevant branches.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Absolute file path to the .xmind file',
+            },
+            nodeId: {
+                type: 'string',
+                description: 'Target node ID to extract (get available IDs via search_xmind_nodes or parse_xmind)',
+            },
+            depth: {
+                type: 'number',
+                description: 'Maximum recursion depth for children (optional, default unlimited)',
+            },
+        },
+        required: ['path', 'nodeId'],
+    },
+};
+/**
+ * Find a node by ID in the tree using recursive search.
+ * Returns the first matching node or null if not found.
+ *
+ * @param node - Root node to start searching from
+ * @param targetId - ID of the node to find
+ * @returns The matching XMindNode or null
+ */
+function findNodeById(node, targetId) {
+    if (node.id === targetId) {
+        return node;
+    }
+    for (const child of node.children) {
+        const found = findNodeById(child, targetId);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/**
+ * Extract a subtree with optional depth limit.
+ * Traverses the tree and returns extracted node, actual depth reached, and node count.
+ *
+ * @param node - Root node of the subtree to extract
+ * @param maxDepth - Maximum depth to traverse (optional)
+ * @returns Object containing extracted node, actual depth, and node count
+ */
+function extractBranch(node, maxDepth) {
+    let actualDepth = 0;
+    let nodeCount = 0;
+    const extract = (n, currentDepth) => {
+        nodeCount++;
+        actualDepth = Math.max(actualDepth, currentDepth);
+        if (maxDepth !== undefined && currentDepth >= maxDepth) {
+            return { ...n, children: [] };
+        }
+        return {
+            ...n,
+            children: n.children.map(child => extract(child, currentDepth + 1)),
+        };
+    };
+    const extractedNode = extract(node, 0);
+    return { node: extractedNode, actualDepth, nodeCount };
+}
+/**
+ * Execute the get_xmind_node_branch tool.
+ * Parses the file, finds the target node, extracts its branch with depth limit, and formats output.
+ *
+ * @param input - Tool input containing path, nodeId, and optional depth
+ * @returns Formatted branch output with Markdown outline and metadata
+ */
+export async function executeBranchTool(input) {
+    try {
+        // Step 1: Validate input
+        const validated = GetBranchInputSchema.parse(input);
+        const filePath = resolveFilePath(validated.path);
+        if (!isValidNodeId(validated.nodeId)) {
+            warn('Invalid node ID format', { nodeId: validated.nodeId });
+            return `Invalid node ID format: "${validated.nodeId}". Node IDs should be alphanumeric with hyphens/underscores.`;
+        }
+        // Step 2: Parse the XMind file
+        debug('Extracting branch', { nodeId: validated.nodeId, maxDepth: validated.depth });
+        const parsed = await parseXMindFile(filePath);
+        info('File parsed successfully for branch extraction', {
+            sheetCount: parsed.sheets.length,
+            nodeId: validated.nodeId,
+        });
+        // Step 3: Find the target node across all sheets
+        let targetNode = null;
+        for (const sheet of parsed.sheets) {
+            targetNode = findNodeById(sheet.rootTopic, validated.nodeId);
+            if (targetNode)
+                break;
+        }
+        if (!targetNode) {
+            warn('Node not found', { nodeId: validated.nodeId });
+            return `Node not found: "${validated.nodeId}". Verify the ID using search_xmind_nodes or parse_xmind first.`;
+        }
+        // Step 4: Extract the branch with depth limit
+        const { node: extractedNode, actualDepth, nodeCount } = extractBranch(targetNode, validated.depth);
+        debug('Branch extracted successfully', { nodeCount, actualDepth });
+        // Step 5: Format output as Markdown
+        const markdown = xmindToMarkdown({
+            filePath,
+            sheets: [
+                {
+                    id: 'extracted',
+                    title: 'Extracted Branch',
+                    rootTopic: extractedNode,
+                },
+            ],
+            meta: {
+                formatVersion: parsed.meta?.formatVersion || 'zen',
+                topicCount: nodeCount,
+                parsedAt: new Date().toISOString(),
+            },
+        });
+        info('Branch extraction completed', { nodeCount, depth: actualDepth });
+        // Step 6: Return formatted results
+        const depthInfo = validated.depth ? `${actualDepth}/${validated.depth}` : `${actualDepth}/∞`;
+        return `Extracted ${nodeCount} nodes (depth: ${depthInfo})\n\n${markdown}`;
+    }
+    catch (err) {
+        // Step 7: Error handling with user-friendly messages
+        if (isXMindError(err)) {
+            warn('XMind error during branch extraction', { code: err.code, message: err.message });
+            return `Error: ${err.message}`;
+        }
+        if (err instanceof Error) {
+            logError('Unexpected error in get_xmind_node_branch', err);
+            return `Unexpected error: ${err.message}`;
+        }
+        logError('Unknown error in get_xmind_node_branch', err);
+        return 'Error: An unknown error occurred while extracting the branch.';
+    }
+}
+//# sourceMappingURL=branch-tool.js.map

package/dist/tools/branch-tool.js.map

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

package/dist/tools/parse-tool.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Parse Tool - MCP tool for full document parsing.
+ * Parses XMind files (.xmind) and returns formatted output (Markdown or JSON).
+ * Includes token estimation and helpful suggestions for large documents.
+ */
+import type { Tool } from '@modelcontextprotocol/sdk/types';
+import { z } from 'zod';
+import { ParseXMindInputSchema } from '../model/schemas.js';
+/**
+ * Input type for parse_xmind tool.
+ * Requires absolute path to .xmind file and optional output format.
+ */
+export type ParseToolInput = z.infer<typeof ParseXMindInputSchema>;
+/**
+ * MCP Tool definition for parse_xmind.
+ * Enables full document parsing with format selection and output formatting.
+ */
+export declare const PARSE_XMIND_TOOL: Tool;
+/**
+ * Executes the parse_xmind tool.
+ *
+ * @param input - Tool input containing path and optional format
+ * @returns Formatted document output with metadata and token estimation
+ * @throws Error with user-friendly message if parsing fails
+ */
+export declare function executeParseTool(input: ParseToolInput): Promise<string>;
+//# sourceMappingURL=parse-tool.d.ts.map

package/dist/tools/parse-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-tool.d.ts","sourceRoot":"","sources":["../../src/tools/parse-tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iCAAiC,CAAC;AAC5D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAQ5D;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEnE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,IAyB9B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAuF7E"}

package/dist/tools/parse-tool.js

@@ -0,0 +1,126 @@
+/**
+ * Parse Tool - MCP tool for full document parsing.
+ * Parses XMind files (.xmind) and returns formatted output (Markdown or JSON).
+ * Includes token estimation and helpful suggestions for large documents.
+ */
+import { parseXMindFile } from '../core/parser.js';
+import { xmindToMarkdown, getMarkdownTokenEstimate } from '../formatters/markdown-formatter.js';
+import { xmindToJSON, getJSONTokenEstimate, getStructureSummary } from '../formatters/json-formatter.js';
+import { resolveFilePath, validateXMindPath } from '../utils/file-utils.js';
+import { isXMindError } from '../utils/errors.js';
+import { info, warn, error as logError } from '../utils/logger.js';
+/**
+ * MCP Tool definition for parse_xmind.
+ * Enables full document parsing with format selection and output formatting.
+ */
+export const PARSE_XMIND_TOOL = {
+    name: 'parse_xmind',
+    description: 'Parse an entire XMind document (.xmind file) and return formatted output (Markdown or JSON). ' +
+        'Markdown format is more token-efficient and recommended for large documents. ' +
+        'JSON format includes structure summary and detailed metadata. ' +
+        'Supports both Zen (modern) and Legacy (XMind 8) formats.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Absolute file path to the .xmind file. Supports ~ for home directory expansion.',
+            },
+            format: {
+                type: 'string',
+                enum: ['markdown', 'json'],
+                default: 'markdown',
+                description: 'Output format. "markdown" (default) is more token-efficient; "json" is more structured. ' +
+                    'Markdown recommended for large documents.',
+            },
+        },
+        required: ['path'],
+    },
+};
+/**
+ * Executes the parse_xmind tool.
+ *
+ * @param input - Tool input containing path and optional format
+ * @returns Formatted document output with metadata and token estimation
+ * @throws Error with user-friendly message if parsing fails
+ */
+export async function executeParseTool(input) {
+    try {
+        // Step 1: Validate and resolve file path
+        info('parse_xmind tool invoked', { path: input.path, format: input.format || 'markdown' });
+        const resolvedPath = resolveFilePath(input.path);
+        await validateXMindPath(resolvedPath);
+        // Step 2: Parse the XMind file
+        const parsedResult = await parseXMindFile(resolvedPath);
+        info('File parsed successfully', { sheetCount: parsedResult.sheets.length });
+        // Step 3: Format output based on requested format
+        const format = input.format || 'markdown';
+        let formattedOutput;
+        let tokenInfo;
+        if (format === 'json') {
+            // JSON format with structure summary
+            const summary = getStructureSummary(parsedResult);
+            const jsonContent = xmindToJSON(parsedResult, false);
+            tokenInfo = getJSONTokenEstimate(jsonContent);
+            formattedOutput = [
+                '## JSON Format Output',
+                '',
+                '### Structure Summary',
+                '',
+                JSON.stringify(summary, null, 2),
+                '',
+                '### Full Content',
+                '',
+                jsonContent,
+            ].join('\n');
+        }
+        else {
+            // Markdown format (default, more token-efficient)
+            formattedOutput = xmindToMarkdown(parsedResult);
+            tokenInfo = getMarkdownTokenEstimate(formattedOutput);
+        }
+        // Step 4: Build result with token estimation and suggestions
+        const result = [
+            formattedOutput,
+            '',
+            '---',
+            '',
+            '## Parse Tool Metadata',
+            '',
+            `- **Format**: ${format}`,
+            `- **File**: ${resolvedPath}`,
+            `- **XMind Format**: ${parsedResult.meta?.formatVersion || 'unknown'}`,
+            `- **Sheets**: ${parsedResult.sheets.length}`,
+            `- **Total Topics**: ${parsedResult.meta?.topicCount || 0}`,
+            `- **Characters**: ${tokenInfo.characterCount}`,
+            `- **Estimated Tokens**: ${tokenInfo.estimatedTokens}`,
+        ];
+        // Add suggestion if content is large
+        if (tokenInfo.hint) {
+            result.push(`- **Suggestion**: ${tokenInfo.hint}`);
+        }
+        // Add recommendations for best practices
+        if (format === 'markdown' && tokenInfo.estimatedTokens > 20000) {
+            result.push('');
+            result.push('**For optimal context efficiency with large documents:**');
+            result.push('- Consider using the `search_xmind` tool to find specific topics');
+            result.push('- Use `get_branch` to extract relevant subtrees');
+            result.push('- Break analysis into smaller, focused queries');
+        }
+        return result.join('\n');
+    }
+    catch (err) {
+        // Step 5: Error handling with user-friendly messages
+        if (isXMindError(err)) {
+            warn('XMind parsing error', { code: err.code, message: err.message });
+            return `Error: ${err.message}`;
+        }
+        if (err instanceof Error) {
+            logError('Unexpected error in parse_xmind', err);
+            return `Error: ${err.message}`;
+        }
+        logError('Unknown error in parse_xmind', err);
+        return 'Error: An unknown error occurred while parsing the file.';
+    }
+}
+//# sourceMappingURL=parse-tool.js.map

package/dist/tools/parse-tool.js.map

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

package/dist/tools/search-tool.d.ts

@@ -0,0 +1,27 @@
+/**
+ * MCP Tool: search_xmind_nodes
+ * Search XMind nodes by keyword, label, or status marker.
+ */
+import type { Tool } from '@modelcontextprotocol/sdk/types';
+import { z } from 'zod';
+import { SearchXMindInputSchema } from '../model/schemas.js';
+/**
+ * Input type for search_xmind_nodes tool.
+ * Requires file path and search query, with optional field filtering and case sensitivity.
+ */
+export type SearchToolInput = z.infer<typeof SearchXMindInputSchema>;
+/**
+ * MCP Tool definition for search_xmind_nodes.
+ * Enables keyword/label/marker filtering with breadcrumb path resolution.
+ */
+export declare const SEARCH_XMIND_TOOL: Tool;
+/**
+ * Executes the search_xmind_nodes tool.
+ * Parses the file, searches all sheets, and returns formatted results with breadcrumb paths.
+ *
+ * @param input - Tool input containing path, query, and optional search parameters
+ * @returns Formatted search results or error message
+ * @throws Does not throw; returns user-friendly error messages
+ */
+export declare function executeSearchTool(input: SearchToolInput): Promise<string>;
+//# sourceMappingURL=search-tool.d.ts.map

package/dist/tools/search-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-tool.d.ts","sourceRoot":"","sources":["../../src/tools/search-tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iCAAiC,CAAC;AAC5D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAK7D;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,IA+B/B,CAAC;AAmHF;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAgD/E"}