@supernal/interface 1.0.0

package/dist/esm/src/testing/TestRunner.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Test Runner
+ *
+ * Orchestrates test generation and execution.
+ * Basic open-source version (TestGenerator and Story system are enterprise edition).
+ */
+export interface TestRunOptions {
+    outputDir?: string;
+    framework?: 'jest' | 'vitest' | 'mocha';
+    includePlaywright?: boolean;
+    includeGherkin?: boolean;
+    includeStories?: boolean;
+    filterByTag?: string;
+    filterByCategory?: string;
+}
+export declare class TestRunner {
+    /**
+     * Generate all test files
+     *
+     * NOTE: Full test generation is part of @supernal/interface-enterprise
+     * Open source edition includes basic Gherkin parsing only.
+     */
+    static generateTests(options?: TestRunOptions): Promise<Map<string, string>>;
+    /**
+     * Generate Gherkin feature files and tests
+     */
+    static generateGherkinTests(options: TestRunOptions): Map<string, string>;
+    /**
+     * Generate story-based test file
+     *
+     * NOTE: Story system is part of @supernal/interface-enterprise
+     */
+    static generateStoryTests(options: TestRunOptions): string;
+    /**
+     * Generate documentation
+     *
+     * NOTE: Full documentation generation requires ToolPromptGenerator
+     * which is under review for open source vs enterprise.
+     */
+    static generateDocumentation(): Map<string, string>;
+    /**
+     * Write files to disk
+     */
+    static writeFiles(files: Map<string, string>, outputDir: string): Promise<void>;
+    /**
+     * Generate and write all tests
+     */
+    static generateAndWrite(options?: TestRunOptions): Promise<void>;
+}
+//# sourceMappingURL=TestRunner.d.ts.map

package/dist/esm/src/testing/TestRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestRunner.d.ts","sourceRoot":"","sources":["../../../../src/testing/TestRunner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IACxC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,UAAU;IACrB;;;;;OAKG;WACU,aAAa,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IA0BtF;;OAEG;IACH,MAAM,CAAC,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAiCzE;;;;OAIG;IACH,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM;IAO1D;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAcnD;;OAEG;WACU,UAAU,CACrB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC;IAoBhB;;OAEG;WACU,gBAAgB,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;CAW3E"}

package/dist/esm/src/testing/TestRunner.js

@@ -0,0 +1,121 @@
+/**
+ * Test Runner
+ *
+ * Orchestrates test generation and execution.
+ * Basic open-source version (TestGenerator and Story system are enterprise edition).
+ */
+// Enterprise features - not available in open source edition
+// import { TestGenerator } from '../generators/TestGenerator.js';
+// import { StoryRegistry, StoryExecutor } from '../background/stories.js';
+import { GherkinParser } from './GherkinParser.js';
+import { ToolRegistry } from '../background/registry/ToolRegistry.js';
+export class TestRunner {
+    /**
+     * Generate all test files
+     *
+     * NOTE: Full test generation is part of @supernal/interface-enterprise
+     * Open source edition includes basic Gherkin parsing only.
+     */
+    static async generateTests(options = {}) {
+        const tests = new Map();
+        // 1. Standard test generation - Enterprise feature
+        // const standardTests = TestGenerator.generateAllTests({...});
+        // Enterprise feature - see https://supernal.ai/enterprise
+        // 2. Generate Gherkin-based tests if requested (basic support)
+        if (options.includeGherkin) {
+            const gherkinTests = this.generateGherkinTests(options);
+            for (const [filename, content] of gherkinTests) {
+                tests.set(filename, content);
+            }
+        }
+        // 3. Story-based tests - Enterprise feature
+        if (options.includeStories) {
+            throw new Error('Story system is part of @supernal/interface-enterprise. ' +
+                'Visit https://supernal.ai/enterprise for more information.');
+        }
+        return tests;
+    }
+    /**
+     * Generate Gherkin feature files and tests
+     */
+    static generateGherkinTests(options) {
+        const files = new Map();
+        // Get tools grouped by category
+        const categories = new Set(ToolRegistry.getTools().map(t => t.category));
+        for (const category of categories) {
+            if (options.filterByCategory && category !== options.filterByCategory) {
+                continue;
+            }
+            const tools = ToolRegistry.getToolsByCategory(category);
+            if (tools.length === 0)
+                continue;
+            // Generate feature file
+            const featureName = `${category} Tools`;
+            const feature = GherkinParser.generateFeature(featureName, tools, {
+                description: `Test ${category} tool interactions`,
+                tags: [category.toLowerCase(), 'generated']
+            });
+            files.set(`${category.toLowerCase()}.feature`, feature);
+            // Parse and generate Playwright test
+            const parsedFeature = GherkinParser.parseFeature(feature);
+            const test = GherkinParser.generatePlaywrightTest(parsedFeature);
+            files.set(`${category.toLowerCase()}.gherkin.spec.ts`, test);
+        }
+        return files;
+    }
+    /**
+     * Generate story-based test file
+     *
+     * NOTE: Story system is part of @supernal/interface-enterprise
+     */
+    static generateStoryTests(options) {
+        throw new Error('Story system is part of @supernal/interface-enterprise. ' +
+            'Visit https://supernal.ai/enterprise for more information.');
+    }
+    /**
+     * Generate documentation
+     *
+     * NOTE: Full documentation generation requires ToolPromptGenerator
+     * which is under review for open source vs enterprise.
+     */
+    static generateDocumentation() {
+        const docs = new Map();
+        // Basic registry overview (available in open source)
+        const overview = ToolRegistry.overview();
+        docs.set('REGISTRY_OVERVIEW.txt', overview);
+        // Advanced documentation - Enterprise feature
+        // const toolDocs = ToolPromptGenerator.generatePrompt('documentation', {...});
+        // const summary = ToolPromptGenerator.generateToolSummary();
+        return docs;
+    }
+    /**
+     * Write files to disk
+     */
+    static async writeFiles(files, outputDir) {
+        const fs = await import('fs/promises');
+        const path = await import('path');
+        // Ensure output directory exists
+        await fs.mkdir(outputDir, { recursive: true });
+        // Write each file
+        for (const [filename, content] of files) {
+            const filePath = path.join(outputDir, filename);
+            // Create subdirectories if needed
+            const dir = path.dirname(filePath);
+            await fs.mkdir(dir, { recursive: true });
+            await fs.writeFile(filePath, content, 'utf8');
+            console.log(`✅ Generated: ${filePath}`);
+        }
+    }
+    /**
+     * Generate and write all tests
+     */
+    static async generateAndWrite(options = {}) {
+        const outputDir = options.outputDir || './tests/generated';
+        console.log(`🔧 Generating tests...`);
+        const tests = await this.generateTests(options);
+        console.log(`📝 Writing ${tests.size} test files to ${outputDir}...`);
+        await this.writeFiles(tests, outputDir);
+        console.log(`✅ Test generation complete!`);
+    }
+}
+//# sourceMappingURL=TestRunner.js.map

package/dist/esm/src/testing/TestRunner.js.map

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

package/dist/esm/src/testing/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Testing Utilities - Browser State Injection
+ *
+ * Provides complete testing infrastructure for component state management
+ * in E2E and integration tests.
+ *
+ * @module @supernal-interface/core/testing
+ */
+export { initializeTestStateManager, getTestStateManager, type TestStateManager, type StateUpdateEvent, type StateResetEvent, } from './BrowserStateInjection';
+export { setComponentState, getComponentState, resetComponentState, waitForComponent, hasComponent, setComponentStateFromContract, assertComponentStateMatches, getComponentElement, initializeTestState, batchStateOperations, } from './PlaywrightStateHelpers';
+export { testId, testIds, tid, testIdContains, testIdStartsWith, testIdEndsWith, } from './selectors';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/src/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACL,0BAA0B,EAC1B,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,yBAAyB,CAAC;AAWjC,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACZ,6BAA6B,EAC7B,2BAA2B,EAC3B,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,MAAM,EACN,OAAO,EACP,GAAG,EACH,cAAc,EACd,gBAAgB,EAChB,cAAc,GACf,MAAM,aAAa,CAAC"}

package/dist/esm/src/testing/index.js

@@ -0,0 +1,25 @@
+/**
+ * Testing Utilities - Browser State Injection
+ *
+ * Provides complete testing infrastructure for component state management
+ * in E2E and integration tests.
+ *
+ * @module @supernal-interface/core/testing
+ */
+// Browser-side utilities
+export { initializeTestStateManager, getTestStateManager, } from './BrowserStateInjection.js';
+// React hooks (enterprise feature - not in open source)
+// export {
+//   useTestStateInjection,
+//   useTestStateAttributes,
+//   useTestState,
+//   setupTestStateInjection,
+// } from './useTestStateInjection.js';
+// Playwright helpers
+export { setComponentState, getComponentState, resetComponentState, waitForComponent, hasComponent, setComponentStateFromContract, assertComponentStateMatches, getComponentElement, initializeTestState, batchStateOperations, } from './PlaywrightStateHelpers.js';
+// Test selectors
+export { testId, testIds, tid, testIdContains, testIdStartsWith, testIdEndsWith, } from './selectors.js';
+// NOTE: ComponentStateHelpers are NOT exported here because they import Playwright
+// which cannot be bundled in client code. Import directly in test files:
+// import { assertComponentState } from '@supernal-interface/core/testing/ComponentStateHelpers';
+//# sourceMappingURL=index.js.map

package/dist/esm/src/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,yBAAyB;AACzB,OAAO,EACL,0BAA0B,EAC1B,mBAAmB,GAIpB,MAAM,yBAAyB,CAAC;AAEjC,wDAAwD;AACxD,WAAW;AACX,2BAA2B;AAC3B,4BAA4B;AAC5B,kBAAkB;AAClB,6BAA6B;AAC7B,oCAAoC;AAEpC,qBAAqB;AACrB,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACZ,6BAA6B,EAC7B,2BAA2B,EAC3B,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAElC,iBAAiB;AACjB,OAAO,EACL,MAAM,EACN,OAAO,EACP,GAAG,EACH,cAAc,EACd,gBAAgB,EAChB,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,mFAAmF;AACnF,yEAAyE;AACzE,iGAAiG"}

package/dist/esm/src/testing/selectors.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Testing Selector Helpers
+ *
+ * Utilities for converting component name contracts to test selectors.
+ * Reduces boilerplate and ensures consistency across test files.
+ */
+/**
+ * Convert a component name (from name contracts) to a data-testid selector
+ *
+ * @example
+ * ```typescript
+ * import { Chat } from '../architecture/DemoComponentNames';
+ * import { testId } from '@supernal-interface/core/testing';
+ *
+ * const input = page.locator(testId(Chat.input));
+ * // Equivalent to: page.locator('[data-testid="chat-input"]')
+ * ```
+ */
+export declare function testId(componentId: string): string;
+/**
+ * Create multiple selectors at once
+ *
+ * @example
+ * ```typescript
+ * const selectors = testIds({
+ *   input: Chat.input,
+ *   button: Chat.sendButton
+ * });
+ *
+ * await page.locator(selectors.input).fill('hello');
+ * await page.locator(selectors.button).click();
+ * ```
+ */
+export declare function testIds<T extends Record<string, string>>(ids: T): {
+    [K in keyof T]: string;
+};
+/**
+ * Alias for testId - shorter for repetitive use
+ */
+export declare const tid: typeof testId;
+/**
+ * Create a selector for elements with partial testid match
+ *
+ * @example
+ * ```typescript
+ * // Find all chat messages
+ * const messages = page.locator(testIdContains('chat-message'));
+ * ```
+ */
+export declare function testIdContains(partial: string): string;
+/**
+ * Create a selector for elements with testid starting with prefix
+ *
+ * @example
+ * ```typescript
+ * // Find all navigation elements
+ * const navElements = page.locator(testIdStartsWith('nav-'));
+ * ```
+ */
+export declare function testIdStartsWith(prefix: string): string;
+/**
+ * Create a selector for elements with testid ending with suffix
+ */
+export declare function testIdEndsWith(suffix: string): string;
+//# sourceMappingURL=selectors.d.ts.map

package/dist/esm/src/testing/selectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.d.ts","sourceRoot":"","sources":["../../../../src/testing/selectors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACtD,GAAG,EAAE,CAAC,GACL;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM;CAAE,CAK5B;AAED;;GAEG;AACH,eAAO,MAAM,GAAG,eAAS,CAAC;AAE1B;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/esm/src/testing/selectors.js

@@ -0,0 +1,76 @@
+/**
+ * Testing Selector Helpers
+ *
+ * Utilities for converting component name contracts to test selectors.
+ * Reduces boilerplate and ensures consistency across test files.
+ */
+/**
+ * Convert a component name (from name contracts) to a data-testid selector
+ *
+ * @example
+ * ```typescript
+ * import { Chat } from '../architecture/DemoComponentNames.js';
+ * import { testId } from '@supernal-interface/core/testing';
+ *
+ * const input = page.locator(testId(Chat.input));
+ * // Equivalent to: page.locator('[data-testid="chat-input"]')
+ * ```
+ */
+export function testId(componentId) {
+    return `[data-testid="${componentId}"]`;
+}
+/**
+ * Create multiple selectors at once
+ *
+ * @example
+ * ```typescript
+ * const selectors = testIds({
+ *   input: Chat.input,
+ *   button: Chat.sendButton
+ * });
+ *
+ * await page.locator(selectors.input).fill('hello');
+ * await page.locator(selectors.button).click();
+ * ```
+ */
+export function testIds(ids) {
+    return Object.entries(ids).reduce((acc, [key, value]) => {
+        acc[key] = testId(value);
+        return acc;
+    }, {});
+}
+/**
+ * Alias for testId - shorter for repetitive use
+ */
+export const tid = testId;
+/**
+ * Create a selector for elements with partial testid match
+ *
+ * @example
+ * ```typescript
+ * // Find all chat messages
+ * const messages = page.locator(testIdContains('chat-message'));
+ * ```
+ */
+export function testIdContains(partial) {
+    return `[data-testid*="${partial}"]`;
+}
+/**
+ * Create a selector for elements with testid starting with prefix
+ *
+ * @example
+ * ```typescript
+ * // Find all navigation elements
+ * const navElements = page.locator(testIdStartsWith('nav-'));
+ * ```
+ */
+export function testIdStartsWith(prefix) {
+    return `[data-testid^="${prefix}"]`;
+}
+/**
+ * Create a selector for elements with testid ending with suffix
+ */
+export function testIdEndsWith(suffix) {
+    return `[data-testid$="${suffix}"]`;
+}
+//# sourceMappingURL=selectors.js.map

package/dist/esm/src/testing/selectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.js","sourceRoot":"","sources":["../../../../src/testing/selectors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,MAAM,CAAC,WAAmB;IACxC,OAAO,iBAAiB,WAAW,IAAI,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,OAAO,CACrB,GAAM;IAEN,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;QACtD,GAAG,CAAC,GAAc,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QACpC,OAAO,GAAG,CAAC;IACb,CAAC,EAAE,EAAgC,CAAC,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,MAAM,CAAC;AAE1B;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,OAAO,kBAAkB,OAAO,IAAI,CAAC;AACvC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,OAAO,kBAAkB,MAAM,IAAI,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,kBAAkB,MAAM,IAAI,CAAC;AACtC,CAAC"}

package/dist/esm/src/tools/SystemTools.d.ts

@@ -0,0 +1,139 @@
+/**
+ * System Tools - AI Discovery & Help System
+ *
+ * Provides mandatory tools for AI agents to discover and understand
+ * available capabilities without hardcoding tool names.
+ *
+ * Features:
+ * - help(): Get usage information and available tools
+ * - listCapabilities(): Query and filter available tools
+ * - describe(): Get detailed information about specific tools
+ * - Smart suggestions using Levenshtein distance for typos
+ *
+ * @example
+ * ```typescript
+ * // AI discovers tools
+ * const tools = await SystemTools.listCapabilities({ category: ToolCategory.DEMO });
+ *
+ * // AI gets help on a specific tool
+ * const info = await SystemTools.describe('sendMessage');
+ *
+ * // AI gets suggestions on typos
+ * try {
+ *   await someAPI.setPriorty('high');  // Typo!
+ * } catch (err) {
+ *   // "setPriorty not found. Did you mean: setPriority, setStatus?"
+ * }
+ * ```
+ */
+import { Tool, ToolCategory } from '../types/Tool';
+/**
+ * Query options for listCapabilities
+ */
+export interface CapabilityQuery {
+    /**
+     * Filter by category
+     */
+    category?: ToolCategory;
+    /**
+     * Filter by keyword search
+     */
+    keyword?: string;
+    /**
+     * Filter by platform support
+     */
+    platform?: 'chrome' | 'web' | 'desktop';
+    /**
+     * Filter by enabled status
+     */
+    enabled?: boolean;
+    /**
+     * Limit results
+     */
+    limit?: number;
+    /**
+     * Include only specific fields
+     */
+    fields?: Array<keyof Tool>;
+}
+/**
+ * Tool summary for list results
+ */
+export interface ToolSummary {
+    toolId: string;
+    name: string;
+    description: string;
+    category: ToolCategory;
+    aiEnabled?: boolean;
+}
+/**
+ * Help result
+ */
+export interface HelpResult {
+    /**
+     * General help message
+     */
+    message: string;
+    /**
+     * Available tool categories
+     */
+    categories: ToolCategory[];
+    /**
+     * Total tool count
+     */
+    toolCount: number;
+    /**
+     * System tools (always available)
+     */
+    systemTools: string[];
+    /**
+     * Example queries
+     */
+    examples: string[];
+}
+/**
+ * System Tools for AI Discovery
+ */
+export declare class SystemTools {
+    /**
+     * Similarity threshold for suggestions
+     */
+    private static readonly SIMILARITY_THRESHOLD;
+    /**
+     * Maximum suggestions to return
+     */
+    private static readonly MAX_SUGGESTIONS;
+    /**
+     * Get general help and overview
+     */
+    static help(): Promise<HelpResult>;
+    /**
+     * List available capabilities with optional filtering
+     */
+    static listCapabilities(query?: CapabilityQuery): Promise<ToolSummary[]>;
+    /**
+     * Get detailed information about a specific tool
+     */
+    static describe(toolId: string): Promise<any | null>;
+    /**
+     * Suggest similar tool names (for error messages)
+     */
+    static suggestTools(invalidName: string): string[];
+    /**
+     * Search tools by natural language query
+     */
+    static search(query: string): Promise<ToolSummary[]>;
+    /**
+     * Get tool suggestions based on current context
+     */
+    static suggestByContext(context: {
+        recentTools?: string[];
+        currentCategory?: ToolCategory;
+        completedTools?: string[];
+    }): Promise<ToolSummary[]>;
+    /**
+     * Wrap tool execution with suggestion on error
+     */
+    static executeWithSuggestions<T>(toolId: string, executor: () => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=SystemTools.d.ts.map

package/dist/esm/src/tools/SystemTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SystemTools.d.ts","sourceRoot":"","sources":["../../../../src/tools/SystemTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAInD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;IAExB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IAExC;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,UAAU,EAAE,YAAY,EAAE,CAAC;IAE3B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;IAEtB;;OAEG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA0CD;;GAEG;AACH,qBAAa,WAAW;IACtB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAO;IAEnD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAK;IAE5C;;OAEG;WACU,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;IAiCxC;;OAEG;WACU,gBAAgB,CAAC,KAAK,GAAE,eAAoB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAyClF;;OAEG;WACU,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAwB1D;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE;IAoBlD;;OAEG;WACU,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAiC1D;;OAEG;WACU,gBAAgB,CAAC,OAAO,EAAE;QACrC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB,eAAe,CAAC,EAAE,YAAY,CAAC;QAC/B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;KAC3B,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IA0B1B;;OAEG;WACU,sBAAsB,CAAC,CAAC,EACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC;CAcd"}