@supernal/interface 1.0.0

package/dist/esm/src/exposure/ExposureCollector.js

@@ -0,0 +1,354 @@
+/**
+ * ExposureCollector - Production-Quality Singleton (REQ-004)
+ *
+ * Collects and manages real-time tool exposure states across the entire application.
+ * Works with 1 tool or 10,000 tools - designed for production use.
+ */
+import { ExposureState, } from '../types/ExposureState.js';
+export class ExposureCollector {
+    constructor() {
+        /** Current state of all registered tools */
+        this.states = new Map();
+        /** Observers for state changes (global and per-tool) */
+        this.globalObservers = new Set();
+        this.toolObservers = new Map();
+        /** IntersectionObserver instances (one per tool element) */
+        this.intersectionObservers = new Map();
+        // Private constructor for singleton
+        this.initializeMutationObserver();
+    }
+    static getInstance() {
+        if (!ExposureCollector.instance) {
+            ExposureCollector.instance = new ExposureCollector();
+        }
+        return ExposureCollector.instance;
+    }
+    /**
+     * Register a tool and start observing its exposure state
+     */
+    registerTool(toolId, element, metadata) {
+        // Check for duplicate toolId
+        if (this.states.has(toolId)) {
+            console.warn(`⚠️  Tool "${toolId}" is already registered. Updating registration.\n` +
+                `   This might indicate duplicate tool IDs in your application.`);
+        }
+        const initialState = {
+            toolId,
+            state: element ? ExposureState.PRESENT : ExposureState.NOT_PRESENT,
+            element,
+            lastUpdate: Date.now(),
+            metadata,
+        };
+        this.states.set(toolId, initialState);
+        // Start observing if element exists
+        if (element) {
+            this.observeElement(toolId, element);
+        }
+    }
+    /**
+     * Unregister a tool and stop observing
+     */
+    unregisterTool(toolId) {
+        const observer = this.intersectionObservers.get(toolId);
+        if (observer) {
+            observer.disconnect();
+            this.intersectionObservers.delete(toolId);
+        }
+        this.states.delete(toolId);
+        this.toolObservers.delete(toolId);
+    }
+    /**
+     * Get current state of a tool
+     */
+    getToolState(toolId) {
+        return this.states.get(toolId);
+    }
+    /**
+     * Get all registered tools
+     */
+    getAllTools() {
+        return Array.from(this.states.values());
+    }
+    /**
+     * Subscribe to state changes (global or per-tool)
+     */
+    subscribe(observer, toolId) {
+        if (toolId) {
+            // Subscribe to specific tool
+            if (!this.toolObservers.has(toolId)) {
+                this.toolObservers.set(toolId, new Set());
+            }
+            this.toolObservers.get(toolId).add(observer);
+            return () => {
+                this.toolObservers.get(toolId)?.delete(observer);
+            };
+        }
+        else {
+            // Subscribe to all state changes
+            this.globalObservers.add(observer);
+            return () => {
+                this.globalObservers.delete(observer);
+            };
+        }
+    }
+    /**
+     * Wait for a tool to reach a specific state (returns Promise)
+     *
+     * @example
+     * const ready = await collector.waitForState('save-button', ExposureState.INTERACTABLE, 5000);
+     * if (ready) {
+     *   // Execute tool
+     * }
+     */
+    waitForState(toolId, targetState, timeoutMs = 5000) {
+        return new Promise((resolve) => {
+            const currentState = this.states.get(toolId);
+            // Already at target state or higher
+            if (currentState && currentState.state >= targetState) {
+                resolve(true);
+                return;
+            }
+            // Set up timeout
+            const timeout = setTimeout(() => {
+                unsubscribe();
+                resolve(false);
+            }, timeoutMs);
+            // Subscribe to state changes
+            const unsubscribe = this.subscribe((change) => {
+                if (change.newState >= targetState) {
+                    clearTimeout(timeout);
+                    unsubscribe();
+                    resolve(true);
+                }
+            }, toolId);
+        });
+    }
+    /**
+     * Manually update tool state (for external integrations)
+     */
+    updateToolState(toolId, newState, metadata) {
+        const currentState = this.states.get(toolId);
+        if (!currentState) {
+            console.warn(`Cannot update state for unregistered tool: ${toolId}`);
+            return;
+        }
+        if (currentState.state === newState) {
+            return; // No change
+        }
+        const change = {
+            toolId,
+            oldState: currentState.state,
+            newState,
+            timestamp: Date.now(),
+            metadata,
+        };
+        // Update state
+        currentState.state = newState;
+        currentState.lastUpdate = change.timestamp;
+        if (metadata) {
+            currentState.metadata = { ...currentState.metadata, ...metadata };
+        }
+        // Notify observers
+        this.notifyObservers(change);
+    }
+    /**
+     * Initialize DOM mutation observer to detect element additions/removals
+     */
+    initializeMutationObserver() {
+        if (typeof window === 'undefined' || typeof MutationObserver === 'undefined') {
+            return; // Not in browser environment
+        }
+        this.mutationObserver = new MutationObserver((mutations) => {
+            for (const mutation of mutations) {
+                if (mutation.type === 'childList') {
+                    // Check if any registered tools were added/removed
+                    this.handleDOMMutations(mutation);
+                }
+            }
+        });
+        // Observe entire document
+        this.mutationObserver.observe(document.body, {
+            childList: true,
+            subtree: true,
+        });
+    }
+    /**
+     * Handle DOM mutations to detect tool additions/removals
+     */
+    handleDOMMutations(mutation) {
+        // Check removed nodes
+        for (const node of Array.from(mutation.removedNodes)) {
+            if (node instanceof Element) {
+                for (const [toolId, state] of this.states.entries()) {
+                    if (state.element === node || node.contains(state.element)) {
+                        this.updateToolState(toolId, ExposureState.NOT_PRESENT, { reason: 'DOM element removed' });
+                    }
+                }
+            }
+        }
+        // Check added nodes (re-register tools that reappeared)
+        for (const node of Array.from(mutation.addedNodes)) {
+            if (node instanceof Element) {
+                for (const [toolId, state] of this.states.entries()) {
+                    if (state.state === ExposureState.NOT_PRESENT) {
+                        // Check if tool's element was added back (by data-tool-id or stored reference)
+                        const toolElement = this.findToolElement(toolId);
+                        if (toolElement) {
+                            state.element = toolElement;
+                            this.observeElement(toolId, toolElement);
+                            this.updateToolState(toolId, ExposureState.PRESENT, { reason: 'DOM element added' });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Find a tool's element by data-tool-id attribute
+     */
+    findToolElement(toolId) {
+        if (typeof document === 'undefined')
+            return null;
+        return document.querySelector(`[data-tool-id="${toolId}"]`);
+    }
+    /**
+     * Observe an element for visibility and interaction changes
+     */
+    observeElement(toolId, element) {
+        // Clean up existing observer
+        const existingObserver = this.intersectionObservers.get(toolId);
+        if (existingObserver) {
+            existingObserver.disconnect();
+        }
+        // Create IntersectionObserver to detect visibility and viewport exposure
+        const observer = new IntersectionObserver((entries) => {
+            for (const entry of entries) {
+                this.handleIntersectionChange(toolId, entry);
+            }
+        }, { threshold: [0, 0.1] } // Trigger when any part becomes visible
+        );
+        observer.observe(element);
+        this.intersectionObservers.set(toolId, observer);
+        // Initial state check
+        this.checkElementState(toolId, element);
+    }
+    /**
+     * Handle IntersectionObserver changes
+     */
+    handleIntersectionChange(toolId, entry) {
+        const element = entry.target;
+        const isIntersecting = entry.isIntersecting;
+        // Check visibility (hidden, display:none, etc)
+        const computedStyle = window.getComputedStyle(element);
+        const isVisible = computedStyle.display !== 'none' &&
+            computedStyle.visibility !== 'hidden' &&
+            computedStyle.opacity !== '0';
+        // Check if enabled
+        const isEnabled = !element.hasAttribute('disabled') &&
+            element.getAttribute('aria-disabled') !== 'true';
+        // Determine new state
+        let newState;
+        if (!isVisible) {
+            newState = ExposureState.PRESENT;
+        }
+        else if (!isIntersecting) {
+            newState = ExposureState.VISIBLE;
+        }
+        else if (!isEnabled) {
+            newState = ExposureState.EXPOSED;
+        }
+        else {
+            newState = ExposureState.INTERACTABLE;
+        }
+        this.updateToolState(toolId, newState, {
+            reason: 'Intersection change',
+            isIntersecting,
+            isVisible,
+            isEnabled,
+        });
+    }
+    /**
+     * Check element state (initial or manual check)
+     */
+    checkElementState(toolId, element) {
+        if (typeof window === 'undefined')
+            return;
+        const computedStyle = window.getComputedStyle(element);
+        const isVisible = computedStyle.display !== 'none' &&
+            computedStyle.visibility !== 'hidden' &&
+            computedStyle.opacity !== '0';
+        const rect = element.getBoundingClientRect();
+        const isInViewport = rect.top >= 0 &&
+            rect.left >= 0 &&
+            rect.bottom <= (window.innerHeight || document.documentElement.clientHeight) &&
+            rect.right <= (window.innerWidth || document.documentElement.clientWidth);
+        const isEnabled = !element.hasAttribute('disabled') &&
+            element.getAttribute('aria-disabled') !== 'true';
+        // Determine state
+        let newState;
+        if (!isVisible) {
+            newState = ExposureState.PRESENT;
+        }
+        else if (!isInViewport) {
+            newState = ExposureState.VISIBLE;
+        }
+        else if (!isEnabled) {
+            newState = ExposureState.EXPOSED;
+        }
+        else {
+            newState = ExposureState.INTERACTABLE;
+        }
+        this.updateToolState(toolId, newState, {
+            reason: 'Initial state check',
+            isVisible,
+            isInViewport,
+            isEnabled,
+        });
+    }
+    /**
+     * Notify all observers of a state change
+     */
+    notifyObservers(change) {
+        // Notify global observers
+        for (const observer of this.globalObservers) {
+            try {
+                observer(change);
+            }
+            catch (error) {
+                console.error('Error in exposure observer:', error);
+            }
+        }
+        // Notify tool-specific observers
+        const toolObservers = this.toolObservers.get(change.toolId);
+        if (toolObservers) {
+            for (const observer of toolObservers) {
+                try {
+                    observer(change);
+                }
+                catch (error) {
+                    console.error('Error in tool-specific observer:', error);
+                }
+            }
+        }
+    }
+    /**
+     * Clean up all observers (call on unmount/cleanup)
+     */
+    destroy() {
+        // Disconnect all intersection observers
+        for (const observer of this.intersectionObservers.values()) {
+            observer.disconnect();
+        }
+        this.intersectionObservers.clear();
+        // Disconnect mutation observer
+        if (this.mutationObserver) {
+            this.mutationObserver.disconnect();
+            this.mutationObserver = undefined;
+        }
+        // Clear all state
+        this.states.clear();
+        this.globalObservers.clear();
+        this.toolObservers.clear();
+    }
+}
+//# sourceMappingURL=ExposureCollector.js.map

package/dist/esm/src/exposure/ExposureCollector.js.map

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

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

@@ -0,0 +1,8 @@
+/**
+ * Export all REQ-004 and REQ-005 APIs
+ */
+export * from '../types/ExposureState';
+export * from './ExposureCollector';
+export * from '../types/NavigationGraph';
+export * from '../background/navigation/NavigationGraph';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/exposure/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AAGpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0CAA0C,CAAC"}

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

@@ -0,0 +1,10 @@
+/**
+ * Export all REQ-004 and REQ-005 APIs
+ */
+// REQ-004: Exposure State Detection
+export * from '../types/ExposureState.js';
+export * from './ExposureCollector.js';
+// REQ-005: Context-Aware Navigation
+export * from '../types/NavigationGraph.js';
+export * from '../background/navigation/NavigationGraph.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/exposure/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,oCAAoC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AAEpC,oCAAoC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0CAA0C,CAAC"}

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

@@ -0,0 +1,49 @@
+/**
+ * @supernal/interface - Open Source Edition
+ *
+ * Universal AI Interface - Make any application AI-controllable with decorators.
+ * Core framework, basic features, and adapter system.
+ *
+ * Enterprise features (test generation, architecture visualization, story system)
+ * available at https://supernal.ai/enterprise
+ */
+export { Tool, ToolConfig, ToolMetadata } from './decorators/Tool';
+export { getStandaloneTools, getStandaloneTool } from './decorators/Tool';
+export { ToolProvider, ToolProviderConfig, getToolProviderConfig, isToolProvider, } from './decorators/ToolProvider';
+export { ClickTool, ChangeTool, TypeTool, HoverTool, MultiActionTool, FormTool } from './decorators/ToolHelpers';
+export { AITool, TestTool, OnboardingTool, DangerousTool, DestructiveTool, DataReadTool, DataWriteTool, NavigationTool, AIAndTestTool, OnboardingAndTestTool, } from './decorators/SpecializedTools';
+export { ToolPreset, getToolPreset, applyPreset, registerPendingPreset, clearToolPresets, PresetTemplates, createPreset, containerPreset, pathPreset, } from './decorators/ToolPreset';
+export { ToolRegistry } from './background/registry/ToolRegistry';
+export { ComponentRegistry, ComponentMetadata } from './background/registry/ComponentRegistry';
+export { Component, ComponentConfig } from './decorators/Component';
+export { StatefulComponent, isStatefulComponent } from './interfaces/StatefulComponent';
+export * from './storage';
+export { SystemTools } from './tools/SystemTools';
+export * from './testing';
+export * from './data';
+export * as Names from '../names';
+export { ContractScanner, RouteContractScanner, type ScanResult, type ContractEntry, } from './name-contracts';
+export { RouteScanner, NextjsDynamicScanner, NameExtractor, RouteContractGenerator, RouteContractsConfig, type RouteInfo, type RouteScanResult, } from './routes';
+export { ComponentScanner, type ComponentScannerConfig, type ComponentScanResult, type ComponentMigrationChange, type ComponentMigrateResult, } from './components';
+export { DOMExecutor } from './execution/DOMExecutor';
+export { useToolBinding } from './react';
+export * from './types';
+export type { ComponentStorage, ToolOptions } from './types/Tool';
+export * from './ai';
+export { ExposureCollector } from './exposure/ExposureCollector';
+export { initializeArchitecture, createAutoInitializer, } from './background/architecture';
+export { architectureRegistry, inferNavToContainerMap } from './architecture/registry';
+export { createContainer, createContainers } from './architecture/createContainer';
+export type { ContainerConfig } from './architecture/createContainer';
+export type { ArchitectureOptions, InitializedArchitecture } from './architecture/initialize';
+export type { ContainerDefinition } from './background/architecture/Containers';
+export { createNames, getComponentIds, isComponentId } from './names/createNames';
+export type { ComponentId } from './names/createNames';
+export { ChatUIAdapter, ChatUIProps, ReadableState, ToolExecutionCallback, AdapterFactory, ChatUIProviderConfig, ChatUIProvider, ChatUI, useChatUI, useChatUIOptional, withChatUI, CopilotKitAdapter, createCopilotKitAdapter, NativeAdapter, createNativeAdapter, bridgeToolRegistry, bridgeComponentState, registerReadable, createAuditTrail, setupBridge, } from './adapters';
+export type { CopilotKitAdapterConfig, NativeAdapterConfig, BridgeToolRegistryOptions, BridgeComponentStateOptions, AuditTrailOptions, ToolExecution as ChatToolExecution, } from './adapters';
+export type { UniversalExecutionContext, UniversalToolResult } from './background/registry/ToolRegistry';
+export { NavigationGraph } from './background/navigation/NavigationGraph';
+export { RuntimeTreeBuilder } from './background/navigation/RuntimeTreeBuilder';
+export declare const VERSION = "1.0.0";
+export declare const PACKAGE_NAME = "@supernal/interface";
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/esm/src/index.js

@@ -0,0 +1,79 @@
+/**
+ * @supernal/interface - Open Source Edition
+ *
+ * Universal AI Interface - Make any application AI-controllable with decorators.
+ * Core framework, basic features, and adapter system.
+ *
+ * Enterprise features (test generation, architecture visualization, story system)
+ * available at https://supernal.ai/enterprise
+ */
+// Core decorators and registry
+export { Tool } from './decorators/Tool.js';
+export { getStandaloneTools, getStandaloneTool } from './decorators/Tool.js';
+export { ToolProvider, getToolProviderConfig, isToolProvider, } from './decorators/ToolProvider.js';
+export { ClickTool, ChangeTool, TypeTool, HoverTool, MultiActionTool, FormTool } from './decorators/ToolHelpers.js';
+// Specialized decorators and presets
+export { AITool, TestTool, OnboardingTool, DangerousTool, DestructiveTool, DataReadTool, DataWriteTool, NavigationTool, AIAndTestTool, OnboardingAndTestTool, } from './decorators/SpecializedTools.js';
+export { ToolPreset, getToolPreset, applyPreset, registerPendingPreset, clearToolPresets, PresetTemplates, createPreset, containerPreset, pathPreset, } from './decorators/ToolPreset.js';
+// Registries
+export { ToolRegistry } from './background/registry/ToolRegistry.js';
+export { ComponentRegistry } from './background/registry/ComponentRegistry.js';
+// Component decorators
+export { Component } from './decorators/Component.js';
+// Stateful components
+export { isStatefulComponent } from './interfaces/StatefulComponent.js';
+// Storage (basic adapters only - browser/memory)
+export * from './storage/index.js';
+// System tools
+export { SystemTools } from './tools/SystemTools.js';
+// Testing utilities (basic - no generation)
+export * from './testing/index.js';
+// Data management
+export * from './data/index.js';
+// Name contracts (hierarchical IDs)
+export * as Names from '../names/index.js';
+// Name contract scanning
+export { ContractScanner, RouteContractScanner, } from './name-contracts/index.js';
+// Route scanning
+export { RouteScanner, NextjsDynamicScanner, NameExtractor, RouteContractGenerator, } from './routes/index.js';
+// Component scanning
+export { ComponentScanner, } from './components/index.js';
+// Execution engines
+export { DOMExecutor } from './execution/DOMExecutor.js';
+// React hooks
+export { useToolBinding } from './react/index.js';
+// Types
+export * from './types/index.js';
+// AI (basic matching and execution)
+export * from './ai/index.js';
+// Exposure API
+export { ExposureCollector } from './exposure/ExposureCollector.js';
+// Architecture initialization (basic)
+export { initializeArchitecture, createAutoInitializer, } from './background/architecture/index.js';
+export { architectureRegistry, inferNavToContainerMap } from './architecture/registry.js';
+export { createContainer, createContainers } from './architecture/createContainer.js';
+// Names
+export { createNames, getComponentIds, isComponentId } from './names/createNames.js';
+// Chat UI Adapters (ALL OPEN - Key value proposition!)
+export { 
+// Provider
+ChatUIProvider, ChatUI, useChatUI, useChatUIOptional, withChatUI, 
+// Adapters
+CopilotKitAdapter, createCopilotKitAdapter, NativeAdapter, createNativeAdapter, 
+// Bridge utilities
+bridgeToolRegistry, bridgeComponentState, registerReadable, createAuditTrail, setupBridge, } from './adapters/index.js';
+// Enterprise feature stubs (warn users, drive upgrade)
+export { NavigationGraph } from './background/navigation/NavigationGraph.js';
+export { RuntimeTreeBuilder } from './background/navigation/RuntimeTreeBuilder.js';
+// Version info
+export const VERSION = '1.0.0';
+export const PACKAGE_NAME = '@supernal/interface';
+// Enterprise features not included in open source
+// Available at https://supernal.ai/enterprise:
+// - Test Generation (TestGenerator, ComponentTestGenerator, DocumentationGenerator)
+// - Story System (StoryBuilder, StoryExecutor, StoryRegistry)
+// - Architecture Visualization (ArchitectureGraph, RuntimeGraphTracker)
+// - Advanced AI (LLMProvider, ParameterExtractor, SuggestionEngine)
+// - File Storage Adapter (Node.js)
+// - Navigation Graph (runtime tracking)
+//# sourceMappingURL=index.js.map

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

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

package/dist/esm/src/interfaces/StatefulComponent.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Stateful Component Interface
+ *
+ * Week 2: State Integration
+ *
+ * Defines the interface that all stateful components must implement
+ * to enable state management through ComponentRegistry and story execution.
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   name: 'counter',
+ *   stateful: true,
+ * })
+ * class CounterComponent implements StatefulComponent<CounterState> {
+ *   private state: CounterState = { count: 0 };
+ *
+ *   getState(): CounterState {
+ *     return { ...this.state };
+ *   }
+ *
+ *   setState(newState: Partial<CounterState>): void {
+ *     this.state = { ...this.state, ...newState };
+ *     this.render();
+ *   }
+ *
+ *   resetState(): void {
+ *     this.state = { count: 0 };
+ *     this.render();
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Interface for components with managed state
+ *
+ * @template TState - The type of the component's state object
+ */
+export interface StatefulComponent<TState = any> {
+    /**
+     * Get the current state of the component
+     *
+     * Should return a copy of the state to prevent external mutation
+     *
+     * @returns Copy of the current component state
+     */
+    getState(): TState;
+    /**
+     * Set the component's state
+     *
+     * Should merge the provided state with existing state
+     * and trigger a re-render if applicable
+     *
+     * @param state - Partial state to merge with current state
+     */
+    setState(state: Partial<TState>): void;
+    /**
+     * Reset the component to its initial state
+     *
+     * Should restore the component to its default/initial state
+     * and trigger a re-render if applicable
+     */
+    resetState(): void;
+}
+/**
+ * Type guard to check if a component implements StatefulComponent
+ *
+ * @param component - Component to check
+ * @returns True if component implements StatefulComponent interface
+ */
+export declare function isStatefulComponent(component: any): component is StatefulComponent;
+//# sourceMappingURL=StatefulComponent.d.ts.map

package/dist/esm/src/interfaces/StatefulComponent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StatefulComponent.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/StatefulComponent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,MAAM,GAAG,GAAG;IAC7C;;;;;;OAMG;IACH,QAAQ,IAAI,MAAM,CAAC;IAEnB;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAEvC;;;;;OAKG;IACH,UAAU,IAAI,IAAI,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,GAAG,GAAG,SAAS,IAAI,iBAAiB,CAQlF"}