@supernal/interface 1.0.0

package/dist/esm/src/routes/scanners/NextjsDynamicScanner.js

@@ -0,0 +1,98 @@
+// Generated from: 2025-12-28-simple-name-extraction.md
+// Generated on: 2025-12-28
+// DO NOT EDIT - Regenerate from documentation if changes needed
+import { RouteScanner } from './RouteScanner.js';
+import { NameExtractor } from './NameExtractor.js';
+/**
+ * Scanner that extracts route names from Next.js applications.
+ *
+ * Supports two discovery strategies:
+ * 1. VALID_VIEWS arrays - Extracts view names from configuration files
+ * 2. App directory structure - Scans Next.js App Router directories for API routes
+ *
+ * @example
+ * ```typescript
+ * import { NextjsDynamicScanner } from '@supernal/interface-core/routes';
+ *
+ * const scanner = new NextjsDynamicScanner({
+ *   routingSystem: 'nextjs-name-extraction',
+ *   scanPaths: {
+ *     configs: ['src/lib/routing/slugService.ts'],  // Contains VALID_VIEWS
+ *     routes: ['src/app/api']                        // API routes directory
+ *   },
+ *   output: {
+ *     contractsPath: 'src/lib/routing/Routes.ts',
+ *     moduleFormat: 'esm'
+ *   }
+ * });
+ *
+ * const result = await scanner.scan();
+ * // result.routes contains all discovered routes
+ * ```
+ */
+export class NextjsDynamicScanner extends RouteScanner {
+    constructor() {
+        super(...arguments);
+        this.extractor = new NameExtractor();
+    }
+    getName() {
+        return 'Next.js Name Extraction Scanner';
+    }
+    async scan() {
+        const routes = [];
+        // Strategy 1: Extract from VALID_VIEWS array
+        if (this.config.scanPaths.configs) {
+            for (const configPath of this.config.scanPaths.configs) {
+                const viewNames = this.extractor.extractArrayLiteral(configPath, 'VALID_VIEWS');
+                viewNames.forEach(view => {
+                    routes.push({
+                        id: `view-${view}`,
+                        pattern: `/:repo/:branch/${view}`,
+                        params: ['repo', 'branch'],
+                        metadata: {
+                            category: 'view',
+                            source: 'VALID_VIEWS',
+                        },
+                    });
+                });
+            }
+        }
+        // Strategy 2: Extract from app directory structure
+        if (this.config.scanPaths.routes) {
+            for (const routePath of this.config.scanPaths.routes) {
+                // Don't add prefix - let the directory structure determine the route
+                const appRoutes = this.extractor.extractAppDirectoryRoutes(routePath, '' // Empty prefix - routes are determined by directory structure
+                );
+                appRoutes.forEach(route => {
+                    routes.push({
+                        id: `api-${route.name}`,
+                        pattern: route.pattern,
+                        params: route.params,
+                        metadata: {
+                            category: 'api',
+                            source: 'file-structure',
+                            methods: route.methods,
+                            sourceFile: route.sourceFile,
+                        },
+                    });
+                });
+            }
+        }
+        return {
+            routes,
+            metadata: {
+                timestamp: new Date().toISOString(),
+                scannedPaths: [
+                    ...(this.config.scanPaths.configs || []),
+                    ...(this.config.scanPaths.routes || []),
+                ],
+                routingSystem: 'nextjs-name-extraction',
+            },
+        };
+    }
+    async validate(routes) {
+        // Basic validation - check all routes have patterns and ids
+        return routes.every(route => route.id && route.pattern);
+    }
+}
+//# sourceMappingURL=NextjsDynamicScanner.js.map

package/dist/esm/src/routes/scanners/NextjsDynamicScanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NextjsDynamicScanner.js","sourceRoot":"","sources":["../../../../../src/routes/scanners/NextjsDynamicScanner.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,2BAA2B;AAC3B,gEAAgE;AAEhE,OAAO,EAAE,YAAY,EAA8B,MAAM,gBAAgB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IAAtD;;QACU,cAAS,GAAG,IAAI,aAAa,EAAE,CAAC;IAyE1C,CAAC;IAvEC,OAAO;QACL,OAAO,iCAAiC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,MAAM,GAAgB,EAAE,CAAC;QAE/B,6CAA6C;QAC7C,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;YAClC,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;gBACvD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,mBAAmB,CAClD,UAAU,EACV,aAAa,CACd,CAAC;gBAEF,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE;oBACvB,MAAM,CAAC,IAAI,CAAC;wBACV,EAAE,EAAE,QAAQ,IAAI,EAAE;wBAClB,OAAO,EAAE,kBAAkB,IAAI,EAAE;wBACjC,MAAM,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC;wBAC1B,QAAQ,EAAE;4BACR,QAAQ,EAAE,MAAM;4BAChB,MAAM,EAAE,aAAa;yBACtB;qBACF,CAAC,CAAC;gBACL,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,mDAAmD;QACnD,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;YACjC,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;gBACrD,qEAAqE;gBACrE,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,yBAAyB,CACxD,SAAS,EACT,EAAE,CAAE,8DAA8D;iBACnE,CAAC;gBAEF,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE;oBACxB,MAAM,CAAC,IAAI,CAAC;wBACV,EAAE,EAAE,OAAO,KAAK,CAAC,IAAI,EAAE;wBACvB,OAAO,EAAE,KAAK,CAAC,OAAO;wBACtB,MAAM,EAAE,KAAK,CAAC,MAAM;wBACpB,QAAQ,EAAE;4BACR,QAAQ,EAAE,KAAK;4BACf,MAAM,EAAE,gBAAgB;4BACxB,OAAO,EAAE,KAAK,CAAC,OAAO;4BACtB,UAAU,EAAE,KAAK,CAAC,UAAU;yBAC7B;qBACF,CAAC,CAAC;gBACL,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO;YACL,MAAM;YACN,QAAQ,EAAE;gBACR,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,YAAY,EAAE;oBACZ,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,IAAI,EAAE,CAAC;oBACxC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,IAAI,EAAE,CAAC;iBACxC;gBACD,aAAa,EAAE,wBAAwB;aACxC;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,MAAmB;QAChC,4DAA4D;QAC5D,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;IAC1D,CAAC;CACF"}

package/dist/esm/src/routes/scanners/RouteScanner.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Abstract interface for route scanners
+ *
+ * Each routing system (Next.js, React Router, etc.) implements this interface
+ * to provide route discovery for that system.
+ */
+import { RouteContractsConfig } from '../RouteContractsConfig';
+export interface RouteInfo {
+    /** Unique route identifier (e.g., 'overview', 'requirements') */
+    id: string;
+    /** Route pattern (e.g., '/:repo/:branch/:view') */
+    pattern: string;
+    /** Parameter names in order (e.g., ['repo', 'branch', 'view']) */
+    params: string[];
+    /** Optional metadata */
+    metadata?: {
+        /** Category for grouping (e.g., 'view', 'api', 'admin') */
+        category?: string;
+        /** Description for JSDoc */
+        description?: string;
+        /** Example usage */
+        example?: string;
+        /** Default parameter values */
+        defaults?: Record<string, any>;
+        /** Source file where route was found */
+        source?: string;
+        /** HTTP methods supported by this route (GET, POST, etc.) */
+        methods?: string[];
+        /** Source file path (for API routes) */
+        sourceFile?: string;
+    };
+}
+export interface RouteScanResult {
+    /** All discovered routes */
+    routes: RouteInfo[];
+    /** Route categories (optional, for organization) */
+    categories?: Record<string, RouteInfo[]>;
+    /** Metadata about the scan */
+    metadata: {
+        /** When the scan was performed */
+        timestamp: string;
+        /** What was scanned */
+        scannedPaths: string[];
+        /** Routing system detected */
+        routingSystem: string;
+    };
+}
+export declare abstract class RouteScanner {
+    protected config: RouteContractsConfig;
+    constructor(config: RouteContractsConfig);
+    /**
+     * Scan the routing system and discover all routes
+     */
+    abstract scan(): Promise<RouteScanResult>;
+    /**
+     * Validate that discovered routes are valid
+     */
+    abstract validate(routes: RouteInfo[]): Promise<boolean>;
+    /**
+     * Get scanner name for logging
+     */
+    abstract getName(): string;
+}
+//# sourceMappingURL=RouteScanner.d.ts.map

package/dist/esm/src/routes/scanners/RouteScanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteScanner.d.ts","sourceRoot":"","sources":["../../../../../src/routes/scanners/RouteScanner.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAE/D,MAAM,WAAW,SAAS;IACxB,iEAAiE;IACjE,EAAE,EAAE,MAAM,CAAC;IAEX,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAEhB,kEAAkE;IAClE,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB,wBAAwB;IACxB,QAAQ,CAAC,EAAE;QACT,2DAA2D;QAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;QAElB,4BAA4B;QAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;QAErB,oBAAoB;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC;QAEjB,+BAA+B;QAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAE/B,wCAAwC;QACxC,MAAM,CAAC,EAAE,MAAM,CAAC;QAEhB,6DAA6D;QAC7D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QAEnB,wCAAwC;QACxC,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,MAAM,EAAE,SAAS,EAAE,CAAC;IAEpB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IAEzC,8BAA8B;IAC9B,QAAQ,EAAE;QACR,kCAAkC;QAClC,SAAS,EAAE,MAAM,CAAC;QAElB,uBAAuB;QACvB,YAAY,EAAE,MAAM,EAAE,CAAC;QAEvB,8BAA8B;QAC9B,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED,8BAAsB,YAAY;IACpB,SAAS,CAAC,MAAM,EAAE,oBAAoB;gBAA5B,MAAM,EAAE,oBAAoB;IAElD;;OAEG;IACH,QAAQ,CAAC,IAAI,IAAI,OAAO,CAAC,eAAe,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAExD;;OAEG;IACH,QAAQ,CAAC,OAAO,IAAI,MAAM;CAC3B"}

package/dist/esm/src/routes/scanners/RouteScanner.js

@@ -0,0 +1,9 @@
+// Generated from: 2025-12-27-implementation.md
+// Generated on: 2025-12-28
+// DO NOT EDIT - Regenerate from documentation if changes needed
+export class RouteScanner {
+    constructor(config) {
+        this.config = config;
+    }
+}
+//# sourceMappingURL=RouteScanner.js.map

package/dist/esm/src/routes/scanners/RouteScanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteScanner.js","sourceRoot":"","sources":["../../../../../src/routes/scanners/RouteScanner.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,2BAA2B;AAC3B,gEAAgE;AAkEhE,MAAM,OAAgB,YAAY;IAChC,YAAsB,MAA4B;QAA5B,WAAM,GAAN,MAAM,CAAsB;IAAG,CAAC;CAgBvD"}

package/dist/esm/src/storage/LocalStorageAdapter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * LocalStorageAdapter - Browser-only storage using localStorage
+ *
+ * Safe for browser bundling - no Node.js dependencies
+ */
+export interface StorageAdapter {
+    get(key: string): Promise<any>;
+    set(key: string, value: any): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    keys(): Promise<string[]>;
+}
+/**
+ * Storage adapter using browser localStorage
+ * Compatible with SSR - checks for window availability
+ */
+export declare class LocalStorageAdapter implements StorageAdapter {
+    private prefix;
+    constructor(prefix?: string);
+    private getKey;
+    get(key: string): Promise<any>;
+    set(key: string, value: any): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    keys(): Promise<string[]>;
+}
+//# sourceMappingURL=LocalStorageAdapter.d.ts.map

package/dist/esm/src/storage/LocalStorageAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalStorageAdapter.d.ts","sourceRoot":"","sources":["../../../../src/storage/LocalStorageAdapter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC3B;AAED;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,cAAc;IACxD,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,GAAE,MAAoB;IAIxC,OAAO,CAAC,MAAM;IAIR,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAa9B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAY3C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAYtB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMlC,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAYhC"}

package/dist/esm/src/storage/LocalStorageAdapter.js

@@ -0,0 +1,83 @@
+/**
+ * LocalStorageAdapter - Browser-only storage using localStorage
+ *
+ * Safe for browser bundling - no Node.js dependencies
+ */
+/**
+ * Storage adapter using browser localStorage
+ * Compatible with SSR - checks for window availability
+ */
+export class LocalStorageAdapter {
+    constructor(prefix = 'supernal_') {
+        this.prefix = prefix;
+    }
+    getKey(key) {
+        return `${this.prefix}${key}`;
+    }
+    async get(key) {
+        if (typeof window === 'undefined')
+            return null;
+        try {
+            const item = localStorage.getItem(this.getKey(key));
+            return item ? JSON.parse(item) : null;
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.error('[LocalStorageAdapter] Failed to get:', key, e);
+            return null;
+        }
+    }
+    async set(key, value) {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            localStorage.setItem(this.getKey(key), JSON.stringify(value));
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.error('[LocalStorageAdapter] Failed to set:', key, e);
+            throw e;
+        }
+    }
+    async delete(key) {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            localStorage.removeItem(this.getKey(key));
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.error('[LocalStorageAdapter] Failed to delete:', key, e);
+        }
+    }
+    async clear() {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            const keys = await this.keys();
+            keys.forEach(key => localStorage.removeItem(this.getKey(key)));
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.error('[LocalStorageAdapter] Failed to clear:', e);
+        }
+    }
+    async has(key) {
+        if (typeof window === 'undefined')
+            return false;
+        return localStorage.getItem(this.getKey(key)) !== null;
+    }
+    async keys() {
+        if (typeof window === 'undefined')
+            return [];
+        const allKeys = [];
+        for (let i = 0; i < localStorage.length; i++) {
+            const key = localStorage.key(i);
+            if (key && key.startsWith(this.prefix)) {
+                allKeys.push(key.substring(this.prefix.length));
+            }
+        }
+        return allKeys;
+    }
+}
+//# sourceMappingURL=LocalStorageAdapter.js.map

package/dist/esm/src/storage/LocalStorageAdapter.js.map

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

package/dist/esm/src/storage/StateManager.d.ts

@@ -0,0 +1,175 @@
+/**
+ * State Manager
+ *
+ * Hierarchical state management with named instances and pluggable storage adapters.
+ *
+ * Key Features:
+ * - Named instances for multi-context support
+ * - Plugin storage adapters (MV3-safe)
+ * - Path-based state access
+ * - Subscription system
+ * - No default adapter (must be injected)
+ *
+ * @example
+ * ```typescript
+ * // Browser
+ * const state = StateManager.getInstance(
+ *   StateManagers.SupernalCoreV1,
+ *   new LocalStorageAdapter()
+ * );
+ *
+ * // Chrome Extension MV3
+ * const state = StateManager.getInstance(
+ *   StateManagers.SupernalCoreV1,
+ *   new ChromeStorageAdapter()
+ * );
+ *
+ * // Testing
+ * const state = StateManager.getInstance(
+ *   StateManagers.Testing,
+ *   new MemoryStorageAdapter()
+ * );
+ * ```
+ */
+import { StateManagers } from '../types/StateManagers';
+import { ComponentState } from '../types/ComponentState';
+import { StorageAdapter } from './StorageAdapter';
+/**
+ * Subscription callback type
+ */
+export type StateSubscriber<T = any> = (state: T, prevState: T | null) => void;
+/**
+ * Subscription handle for cleanup
+ */
+export interface SubscriptionHandle {
+    unsubscribe: () => void;
+}
+/**
+ * State Manager Options
+ */
+export interface StateManagerOptions {
+    /**
+     * Whether to auto-save on state changes
+     * @default true
+     */
+    autoSave?: boolean;
+    /**
+     * Debounce time for auto-save (ms)
+     * @default 100
+     */
+    saveDebounce?: number;
+    /**
+     * Whether to enable verbose logging
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Named State Manager with plugin storage
+ */
+export declare class StateManager {
+    /**
+     * Registry of named StateManager instances
+     */
+    private static instances;
+    /**
+     * Instance name (from StateManagers enum)
+     */
+    private readonly name;
+    /**
+     * Storage adapter (injected, no default)
+     */
+    private readonly adapter;
+    /**
+     * In-memory state cache
+     */
+    private state;
+    /**
+     * Subscribers for state changes
+     */
+    private subscribers;
+    /**
+     * Options
+     */
+    private options;
+    /**
+     * Save timeout for debouncing
+     */
+    private saveTimeout;
+    /**
+     * Private constructor (use getInstance)
+     */
+    private constructor();
+    /**
+     * Get or create a named StateManager instance
+     *
+     * CRITICAL: Storage adapter MUST be provided. No default adapter.
+     *
+     * @param name The StateManager name
+     * @param adapter The storage adapter to use
+     * @param options Optional configuration
+     */
+    static getInstance(name: StateManagers, adapter: StorageAdapter, options?: StateManagerOptions): StateManager;
+    /**
+     * Clear all instances (useful for testing)
+     */
+    static clearAllInstances(): void;
+    /**
+     * Get instance name
+     */
+    getName(): StateManagers;
+    /**
+     * Initialize from storage
+     * Loads persisted state into memory
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get component state by ID
+     */
+    get<T extends ComponentState = ComponentState>(componentId: string): Promise<T | null>;
+    /**
+     * Set component state
+     */
+    set<T extends ComponentState = ComponentState>(componentId: string, state: T): Promise<void>;
+    /**
+     * Merge partial state (shallow merge)
+     */
+    merge<T extends ComponentState = ComponentState>(componentId: string, partialState: Partial<T>): Promise<void>;
+    /**
+     * Delete component state
+     */
+    delete(componentId: string): Promise<void>;
+    /**
+     * Restore state from storage (force refresh)
+     */
+    restore(componentId: string): Promise<ComponentState | null>;
+    /**
+     * Subscribe to state changes for a component
+     */
+    subscribe<T extends ComponentState = ComponentState>(componentId: string, callback: StateSubscriber<T>): SubscriptionHandle;
+    /**
+     * Get all component IDs
+     */
+    keys(): Promise<string[]>;
+    /**
+     * Get all states
+     */
+    getAll(): Promise<Map<string, ComponentState>>;
+    /**
+     * Clear all state (memory + storage)
+     */
+    clear(): Promise<void>;
+    /**
+     * Notify subscribers of state changes
+     */
+    private notifySubscribers;
+    /**
+     * Schedule a save with debouncing
+     */
+    private scheduleSave;
+    /**
+     * Flush pending saves immediately
+     */
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=StateManager.d.ts.map

package/dist/esm/src/storage/StateManager.d.ts.map

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