@supernal/interface 1.0.0

package/dist/esm/src/data/TestDataManager.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Test Data Manager
+ *
+ * Manages test fixtures, scenarios, and data providers.
+ * Enables mock/real data switching for comprehensive testing.
+ */
+export interface TestDataSet<T = any> {
+    id: string;
+    name: string;
+    description: string;
+    data: T;
+    tags: string[];
+    dependencies?: string[];
+}
+export interface TestScenario {
+    id: string;
+    name: string;
+    description: string;
+    storyId?: string;
+    initialData: Record<string, any>;
+    expectedOutcome: any;
+    tags?: string[];
+}
+export type DataMode = 'mock' | 'real' | 'hybrid';
+export declare class TestDataManager {
+    private fixtures;
+    private scenarios;
+    private mode;
+    /**
+     * Load fixtures from data object
+     */
+    loadFixtures(fixtures: Record<string, any>): void;
+    /**
+     * Load scenarios
+     */
+    loadScenarios(scenarios: TestScenario[]): void;
+    /**
+     * Register a single fixture
+     */
+    registerFixture<T>(fixture: TestDataSet<T>): void;
+    /**
+     * Get data by key
+     */
+    getData<T = any>(key: string, fallback?: T): T;
+    /**
+     * Get scenario by ID
+     */
+    getScenario(id: string): TestScenario | undefined;
+    /**
+     * Get all scenarios with tag
+     */
+    getScenariosByTag(tag: string): TestScenario[];
+    /**
+     * Set data mode
+     */
+    setMode(mode: DataMode): void;
+    /**
+     * Get current mode
+     */
+    getMode(): DataMode;
+    /**
+     * Check if key exists
+     */
+    has(key: string): boolean;
+    /**
+     * Get all fixture keys
+     */
+    getKeys(): string[];
+    /**
+     * Clear all data
+     */
+    clear(): void;
+    /**
+     * Get statistics
+     */
+    getStats(): {
+        fixtures: number;
+        scenarios: number;
+        mode: DataMode;
+    };
+}
+/**
+ * Default fixtures for common test scenarios
+ */
+export declare const defaultFixtures: {
+    users: {
+        admin: {
+            username: string;
+            password: string;
+            role: string;
+            permissions: string[];
+        };
+        standard: {
+            username: string;
+            password: string;
+            role: string;
+            permissions: string[];
+        };
+        guest: {
+            username: string;
+            password: string;
+            role: string;
+            permissions: never[];
+        };
+    };
+    messages: {
+        simple: string;
+        long: string;
+        special: string;
+        emoji: string;
+    };
+    navigation: {
+        paths: {
+            home: string;
+            demo: string;
+            dashboard: string;
+            settings: string;
+        };
+    };
+};
+/**
+ * Global test data manager instance
+ */
+export declare const testDataManager: TestDataManager;
+//# sourceMappingURL=TestDataManager.d.ts.map

package/dist/esm/src/data/TestDataManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestDataManager.d.ts","sourceRoot":"","sources":["../../../../src/data/TestDataManager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,GAAG;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,CAAC,CAAC;IACR,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,eAAe,EAAE,GAAG,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAElD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,IAAI,CAAoB;IAEhC;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAajD;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,IAAI;IAM9C;;OAEG;IACH,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI;IAIjD;;OAEG;IACH,OAAO,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC;IAoC9C;;OAEG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIjD;;OAEG;IACH,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE;IAK9C;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;IAK7B;;OAEG;IACH,OAAO,IAAI,QAAQ;IAInB;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAQzB;;OAEG;IACH,OAAO,IAAI,MAAM,EAAE;IAInB;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,QAAQ,IAAI;QACV,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,QAAQ,CAAC;KAChB;CAOF;AAED;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqC3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,iBAAwB,CAAC"}

package/dist/esm/src/data/TestDataManager.js

@@ -0,0 +1,183 @@
+/**
+ * Test Data Manager
+ *
+ * Manages test fixtures, scenarios, and data providers.
+ * Enables mock/real data switching for comprehensive testing.
+ */
+export class TestDataManager {
+    constructor() {
+        this.fixtures = new Map();
+        this.scenarios = new Map();
+        this.mode = 'mock';
+    }
+    /**
+     * Load fixtures from data object
+     */
+    loadFixtures(fixtures) {
+        for (const [key, data] of Object.entries(fixtures)) {
+            const dataset = {
+                id: key,
+                name: key,
+                description: `Test fixture: ${key}`,
+                data,
+                tags: []
+            };
+            this.fixtures.set(key, dataset);
+        }
+    }
+    /**
+     * Load scenarios
+     */
+    loadScenarios(scenarios) {
+        scenarios.forEach(scenario => {
+            this.scenarios.set(scenario.id, scenario);
+        });
+    }
+    /**
+     * Register a single fixture
+     */
+    registerFixture(fixture) {
+        this.fixtures.set(fixture.id, fixture);
+    }
+    /**
+     * Get data by key
+     */
+    getData(key, fallback) {
+        const parts = key.split('.');
+        // Support nested access like 'users.admin'
+        if (parts.length > 1) {
+            const [fixtureId, ...path] = parts;
+            const fixture = this.fixtures.get(fixtureId);
+            if (!fixture) {
+                if (fallback !== undefined)
+                    return fallback;
+                throw new Error(`Fixture '${fixtureId}' not found`);
+            }
+            let value = fixture.data;
+            for (const prop of path) {
+                if (value && typeof value === 'object' && prop in value) {
+                    value = value[prop];
+                }
+                else {
+                    if (fallback !== undefined)
+                        return fallback;
+                    throw new Error(`Property '${key}' not found in fixture`);
+                }
+            }
+            return value;
+        }
+        // Direct fixture access
+        const fixture = this.fixtures.get(key);
+        if (!fixture) {
+            if (fallback !== undefined)
+                return fallback;
+            throw new Error(`Fixture '${key}' not found`);
+        }
+        return fixture.data;
+    }
+    /**
+     * Get scenario by ID
+     */
+    getScenario(id) {
+        return this.scenarios.get(id);
+    }
+    /**
+     * Get all scenarios with tag
+     */
+    getScenariosByTag(tag) {
+        return Array.from(this.scenarios.values())
+            .filter(scenario => scenario.tags?.includes(tag));
+    }
+    /**
+     * Set data mode
+     */
+    setMode(mode) {
+        this.mode = mode;
+        console.log(`🔄 Test data mode: ${mode}`);
+    }
+    /**
+     * Get current mode
+     */
+    getMode() {
+        return this.mode;
+    }
+    /**
+     * Check if key exists
+     */
+    has(key) {
+        const parts = key.split('.');
+        if (parts.length > 1) {
+            return this.fixtures.has(parts[0]);
+        }
+        return this.fixtures.has(key);
+    }
+    /**
+     * Get all fixture keys
+     */
+    getKeys() {
+        return Array.from(this.fixtures.keys());
+    }
+    /**
+     * Clear all data
+     */
+    clear() {
+        this.fixtures.clear();
+        this.scenarios.clear();
+    }
+    /**
+     * Get statistics
+     */
+    getStats() {
+        return {
+            fixtures: this.fixtures.size,
+            scenarios: this.scenarios.size,
+            mode: this.mode
+        };
+    }
+}
+/**
+ * Default fixtures for common test scenarios
+ */
+export const defaultFixtures = {
+    users: {
+        admin: {
+            username: 'admin@test.com',
+            password: 'test123',
+            role: 'admin',
+            permissions: ['read', 'write', 'delete']
+        },
+        standard: {
+            username: 'user@test.com',
+            password: 'test123',
+            role: 'user',
+            permissions: ['read']
+        },
+        guest: {
+            username: 'guest@test.com',
+            password: 'guest123',
+            role: 'guest',
+            permissions: []
+        }
+    },
+    messages: {
+        simple: 'Hello, World!',
+        long: 'This is a longer test message that spans multiple words and tests text handling.',
+        special: 'Test with special chars: @#$%^&*()',
+        emoji: 'Test with emoji 🎉 🚀 ✨'
+    },
+    navigation: {
+        paths: {
+            home: '/',
+            demo: '/demo',
+            dashboard: '/dashboard',
+            settings: '/settings'
+        }
+    }
+};
+/**
+ * Global test data manager instance
+ */
+export const testDataManager = new TestDataManager();
+// Load default fixtures
+testDataManager.loadFixtures(defaultFixtures);
+//# sourceMappingURL=TestDataManager.js.map

package/dist/esm/src/data/TestDataManager.js.map

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

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

@@ -0,0 +1,7 @@
+/**
+ * Data Index
+ *
+ * Central export for data management
+ */
+export * from './TestDataManager';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/data/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,mBAAmB,CAAC"}

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

@@ -0,0 +1,7 @@
+/**
+ * Data Index
+ *
+ * Central export for data management
+ */
+export * from './TestDataManager.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/data/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,mBAAmB,CAAC"}

package/dist/esm/src/decorators/Component.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Component Decorator - Component Namespace Pattern
+ *
+ * Registers all @Tool methods under this component's namespace.
+ * Provides scoping via containerId for locality resolution.
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   name: 'counter',
+ *   containerId: 'Examples',
+ *   elementId: 'counter-widget'
+ * })
+ * export class Counter {
+ *   @Tool({ aiEnabled: true })
+ *   increment(amount = 1) { }
+ * }
+ * // Registers: counter.increment (Examples scope)
+ * ```
+ */
+export interface ComponentConfig {
+    /**
+     * Component name (namespace)
+     * Must be unique within containerId
+     * Use lowercase kebab-case: 'counter', 'user-form', 'settings-panel'
+     */
+    name: string;
+    /**
+     * Container/page this component belongs to
+     * Used for scoped tool resolution (local > global)
+     */
+    containerId?: string;
+    /**
+     * Root element ID (data-testid)
+     * Points to component's container element
+     */
+    elementId?: string;
+    /**
+     * Component description
+     */
+    description?: string;
+    /**
+     * Whether this component is stateful
+     * Helps AI understand tool methods modify shared state
+     */
+    stateful?: boolean;
+}
+export declare function Component(config: ComponentConfig): <T extends {
+    new (...args: any[]): {};
+}>(constructor: T) => T;
+/**
+ * Get component configuration for a class
+ */
+export declare function getComponentConfig(target: any): ComponentConfig | undefined;
+/**
+ * Check if a class is a component
+ */
+export declare function isComponent(target: any): boolean;
+//# sourceMappingURL=Component.d.ts.map

package/dist/esm/src/decorators/Component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Component.d.ts","sourceRoot":"","sources":["../../../../src/decorators/Component.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,IAC/B,CAAC,SAAS;IAAE,KAAI,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,CAAA;CAAE,EAAE,aAAa,CAAC,OAuFtE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,GAAG,GAAG,eAAe,GAAG,SAAS,CAE3E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAEhD"}

package/dist/esm/src/decorators/Component.js

@@ -0,0 +1,103 @@
+/**
+ * Component Decorator - Component Namespace Pattern
+ *
+ * Registers all @Tool methods under this component's namespace.
+ * Provides scoping via containerId for locality resolution.
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   name: 'counter',
+ *   containerId: 'Examples',
+ *   elementId: 'counter-widget'
+ * })
+ * export class Counter {
+ *   @Tool({ aiEnabled: true })
+ *   increment(amount = 1) { }
+ * }
+ * // Registers: counter.increment (Examples scope)
+ * ```
+ */
+import { ToolRegistry } from '../background/registry/ToolRegistry.js';
+import { ComponentRegistry } from '../background/registry/ComponentRegistry.js';
+import { isStatefulComponent } from '../interfaces/StatefulComponent.js';
+export function Component(config) {
+    return function (constructor) {
+        const componentName = config.name;
+        // Validate component name
+        if (!/^[a-z][a-z0-9-]*$/.test(componentName)) {
+            throw new Error(`Component name '${componentName}' must be lowercase kebab-case`);
+        }
+        // Get all @Tool methods from class prototype
+        const tools = (constructor.prototype.__tools__ || []);
+        if (tools.length === 0) {
+            console.warn(`⚠️  Component '${componentName}' has no @Tool methods. ` +
+                `Did you forget to decorate methods with @Tool()?`);
+        }
+        // Register each tool under component namespace
+        tools.forEach((toolMetadata) => {
+            // Start with the full tool metadata from @Tool decorator
+            const enhancedMetadata = {
+                ...toolMetadata, // Preserve ALL fields from @Tool
+                // Add/override component-specific fields
+                componentName,
+                containerId: config.containerId || toolMetadata.containerId,
+                elementId: toolMetadata.elementId || config.elementId,
+                stateful: config.stateful,
+                // Only override description if tool didn't provide one
+                description: toolMetadata.description ||
+                    `${config.description || componentName}.${toolMetadata.methodName}`,
+            };
+            // Update the existing tool registered by @Tool (registered as ClassName.methodName)
+            // We update it IN PLACE rather than creating a new registration
+            const classBasedToolId = `${toolMetadata.providerClass || constructor.name}.${toolMetadata.methodName}`;
+            const existingTool = ToolRegistry.getTool(classBasedToolId);
+            if (existingTool) {
+                // Merge ALL enhanced metadata into existing tool
+                Object.assign(existingTool, enhancedMetadata);
+                console.log(`📦 [Component] Enhanced: ${classBasedToolId} with component namespace '${componentName}'` +
+                    (config.containerId ? ` (${config.containerId})` : ''));
+            }
+            else {
+                // Fallback: Register as new if class-based tool doesn't exist
+                ToolRegistry.registerTool(componentName, // Provider is component name
+                toolMetadata.methodName, // Method name
+                enhancedMetadata);
+                console.log(`📦 [Component] Registered: ${componentName}.${toolMetadata.methodName}` +
+                    (config.containerId ? ` (${config.containerId})` : ''));
+            }
+        });
+        // Store component config on class
+        constructor.__componentConfig__ = config;
+        // Week 2: Auto-register stateful components
+        if (config.stateful) {
+            // Return wrapped constructor that registers instance on creation
+            return class extends constructor {
+                constructor(...args) {
+                    super(...args);
+                    // Check if instance implements StatefulComponent interface
+                    if (isStatefulComponent(this)) {
+                        ComponentRegistry.registerInstance(componentName, this);
+                    }
+                    else {
+                        console.warn(`⚠️  Component '${componentName}' is marked as stateful but doesn't implement StatefulComponent interface`);
+                    }
+                }
+            };
+        }
+        return constructor;
+    };
+}
+/**
+ * Get component configuration for a class
+ */
+export function getComponentConfig(target) {
+    return target.constructor?.__componentConfig__;
+}
+/**
+ * Check if a class is a component
+ */
+export function isComponent(target) {
+    return !!target.constructor?.__componentConfig__;
+}
+//# sourceMappingURL=Component.js.map

package/dist/esm/src/decorators/Component.js.map

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

package/dist/esm/src/decorators/ContainerHelpers.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Container HOC - marks components as navigation containers
+ *
+ * Wraps a React component to automatically:
+ * 1. Register in RuntimeTreeBuilder component hierarchy
+ * 2. Update NavigationGraph current context
+ * 3. Track container lifecycle (mount/unmount)
+ *
+ * Zero boilerplate - just wrap your page/modal component.
+ */
+/**
+ * Hook to mark a component as a container
+ * Call this at the top of your component function
+ *
+ * @param containerName - Name of the container (must match Containers.ts)
+ *
+ * @example
+ * ```typescript
+ * export function DemoPage() {
+ *   useContainer('Demo');
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+export declare function useContainer(containerName: string): void;
+//# sourceMappingURL=ContainerHelpers.d.ts.map

package/dist/esm/src/decorators/ContainerHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContainerHelpers.d.ts","sourceRoot":"","sources":["../../../../src/decorators/ContainerHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAexD"}

package/dist/esm/src/decorators/ContainerHelpers.js

@@ -0,0 +1,42 @@
+/**
+ * Container HOC - marks components as navigation containers
+ *
+ * Wraps a React component to automatically:
+ * 1. Register in RuntimeTreeBuilder component hierarchy
+ * 2. Update NavigationGraph current context
+ * 3. Track container lifecycle (mount/unmount)
+ *
+ * Zero boilerplate - just wrap your page/modal component.
+ */
+import { useEffect } from 'react';
+import { TreeBuilder } from '../background/navigation/RuntimeTreeBuilder.js';
+import { NavigationGraph } from '../background/navigation/NavigationGraph.js';
+/**
+ * Hook to mark a component as a container
+ * Call this at the top of your component function
+ *
+ * @param containerName - Name of the container (must match Containers.ts)
+ *
+ * @example
+ * ```typescript
+ * export function DemoPage() {
+ *   useContainer('Demo');
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+export function useContainer(containerName) {
+    useEffect(() => {
+        // Register container
+        TreeBuilder.enterComponent(containerName);
+        const graph = NavigationGraph.getInstance();
+        graph.setCurrentContext(containerName);
+        console.log(`📦 [Container] Registered: ${containerName}`);
+        // Cleanup on unmount
+        return () => {
+            TreeBuilder.exitComponent();
+            console.log(`📦 [Container] Unregistered: ${containerName}`);
+        };
+    }, [containerName]);
+}
+//# sourceMappingURL=ContainerHelpers.js.map

package/dist/esm/src/decorators/ContainerHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContainerHelpers.js","sourceRoot":"","sources":["../../../../src/decorators/ContainerHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,MAAM,6CAA6C,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAE3E;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAAC,aAAqB;IAChD,SAAS,CAAC,GAAG,EAAE;QACb,qBAAqB;QACrB,WAAW,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;QAC1C,MAAM,KAAK,GAAG,eAAe,CAAC,WAAW,EAAE,CAAC;QAC5C,KAAK,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC;QAEvC,OAAO,CAAC,GAAG,CAAC,8BAA8B,aAAa,EAAE,CAAC,CAAC;QAE3D,qBAAqB;QACrB,OAAO,GAAG,EAAE;YACV,WAAW,CAAC,aAAa,EAAE,CAAC;YAC5B,OAAO,CAAC,GAAG,CAAC,gCAAgC,aAAa,EAAE,CAAC,CAAC;QAC/D,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC;AACtB,CAAC"}