@supernal/interface 1.0.0

package/dist/cjs/src/react/useNavigationHandler.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * useNavigationHandler - React Hook for Automatic Navigation Setup
+ *
+ * Single-line hook that sets up navigation for any page.
+ * Uses NavigationGraph to automatically resolve routes from container definitions.
+ *
+ * This eliminates the need for manual route maps in every page component.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useNavigationHandler = useNavigationHandler;
+const react_1 = require("react");
+const NavigationGraph_1 = require("../background/navigation/NavigationGraph");
+/**
+ * Set up automatic navigation handler for the current page
+ *
+ * This hook:
+ * 1. Gets routes from NavigationGraph (populated by container definitions)
+ * 2. Creates a handler that resolves page names → routes
+ * 3. Registers the handler with NavigationGraph
+ * 4. Supports dynamic routes (e.g., "blog/post-slug")
+ *
+ * @param router - Next.js router or any router with a `push` method
+ *
+ * @example
+ * ```typescript
+ * import { useRouter } from 'next/router';
+ * import { useNavigationHandler } from '@supernal-interface/core/react';
+ *
+ * export default function MyPage() {
+ *   const router = useRouter();
+ *   useNavigationHandler(router); // ← ONE LINE!
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Without a router (uses window.location as fallback)
+ * useNavigationHandler();
+ * ```
+ */
+function useNavigationHandler(router) {
+    (0, react_1.useEffect)(() => {
+        const graph = NavigationGraph_1.NavigationGraph.getInstance();
+        const handler = (pageNameOrRoute) => {
+            const pageName = typeof pageNameOrRoute === 'string' ? pageNameOrRoute : pageNameOrRoute?.name || pageNameOrRoute?.path;
+            if (!pageName)
+                return;
+            console.log(`🗺️  [Navigation] Request: ${pageName}`);
+            // Use NavigationGraph to resolve route
+            let route = graph.getRouteByName(pageName);
+            if (!route) {
+                console.warn(`⚠️  [Navigation] No exact route found for: ${pageName}`);
+                // Try treating as a path (e.g., "blog/type-safe" → "/blog/type-safe")
+                if (pageName.includes('/')) {
+                    const routePath = pageName.startsWith('/') ? pageName : `/${pageName}`;
+                    console.log(`🗺️  [Navigation] Attempting dynamic path: ${routePath}`);
+                    // Navigate using provided router or fallback to window.location
+                    if (router?.push) {
+                        router.push(routePath);
+                    }
+                    else if (typeof window !== 'undefined') {
+                        window.location.href = routePath;
+                    }
+                }
+                return;
+            }
+            // Extract path from RouteInfo
+            const routePath = route.path || route.name || pageName;
+            console.log(`🗺️  [Navigation] Resolved: ${pageName} → ${routePath}`);
+            // Navigate using provided router or fallback to window.location
+            if (router?.push) {
+                router.push(routePath);
+            }
+            else if (typeof window !== 'undefined') {
+                window.location.href = routePath;
+            }
+        };
+        graph.setNavigationHandler(handler);
+        return () => {
+            // Clean up handler on unmount
+            graph.setNavigationHandler(() => { });
+        };
+    }, [router]);
+}
+//# sourceMappingURL=useNavigationHandler.js.map

package/dist/cjs/src/react/useNavigationHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNavigationHandler.js","sourceRoot":"","sources":["../../../../src/react/useNavigationHandler.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAmCH,oDAoDC;AArFD,iCAAkC;AAClC,8EAA2E;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,SAAgB,oBAAoB,CAClC,MAAyC;IAEzC,IAAA,iBAAS,EAAC,GAAG,EAAE;QACb,MAAM,KAAK,GAAG,iCAAe,CAAC,WAAW,EAAE,CAAC;QAE5C,MAAM,OAAO,GAAG,CAAC,eAA6B,EAAE,EAAE;YAChD,MAAM,QAAQ,GAAG,OAAO,eAAe,KAAK,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,eAAe,EAAE,IAAI,IAAI,eAAe,EAAE,IAAI,CAAC;YACxH,IAAI,CAAC,QAAQ;gBAAE,OAAO;YAEtB,OAAO,CAAC,GAAG,CAAC,8BAA8B,QAAQ,EAAE,CAAC,CAAC;YAEtD,uCAAuC;YACvC,IAAI,KAAK,GAAG,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;YAE3C,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,OAAO,CAAC,IAAI,CAAC,8CAA8C,QAAQ,EAAE,CAAC,CAAC;gBAEvE,sEAAsE;gBACtE,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;oBAC3B,MAAM,SAAS,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,EAAE,CAAC;oBACvE,OAAO,CAAC,GAAG,CAAC,8CAA8C,SAAS,EAAE,CAAC,CAAC;oBAEvE,gEAAgE;oBAChE,IAAI,MAAM,EAAE,IAAI,EAAE,CAAC;wBACjB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;oBACzB,CAAC;yBAAM,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;wBACzC,MAAM,CAAC,QAAQ,CAAC,IAAI,GAAG,SAAS,CAAC;oBACnC,CAAC;gBACH,CAAC;gBACD,OAAO;YACT,CAAC;YAED,8BAA8B;YAC9B,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,QAAQ,CAAC;YACvD,OAAO,CAAC,GAAG,CAAC,+BAA+B,QAAQ,MAAM,SAAS,EAAE,CAAC,CAAC;YAEtE,gEAAgE;YAChE,IAAI,MAAM,EAAE,IAAI,EAAE,CAAC;gBACjB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACzB,CAAC;iBAAM,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;gBACzC,MAAM,CAAC,QAAQ,CAAC,IAAI,GAAG,SAAS,CAAC;YACnC,CAAC;QACH,CAAC,CAAC;QAEF,KAAK,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAEpC,OAAO,GAAG,EAAE;YACV,8BAA8B;YAC9B,KAAK,CAAC,oBAAoB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACvC,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;AACf,CAAC"}

package/dist/cjs/src/react/usePersistedState.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * usePersistedState - SSR-safe state persistence hook
+ *
+ * Like useState, but persists using StateManager and handles hydration properly.
+ * Uses the storage adapter pattern for pluggable persistence.
+ *
+ * @example
+ * ```tsx
+ * const [count, setCount] = usePersistedState('my-count', 0);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usePersistedState = usePersistedState;
+const react_1 = require("react");
+const StateManager_1 = require("../storage/StateManager");
+const LocalStorageAdapter_1 = require("../storage/LocalStorageAdapter");
+const StateManagers_1 = require("../types/StateManagers");
+// Get or create a singleton StateManager for browser usage
+let browserStateManager = null;
+function getBrowserStateManager() {
+    if (!browserStateManager && typeof window !== 'undefined') {
+        browserStateManager = StateManager_1.StateManager.getInstance(StateManagers_1.StateManagers.SupernalCoreV1, new LocalStorageAdapter_1.LocalStorageAdapter());
+    }
+    return browserStateManager;
+}
+function usePersistedState(key, defaultValue) {
+    // Always start with default value (matches SSR)
+    const [state, setState] = (0, react_1.useState)(defaultValue);
+    const [isHydrated, setIsHydrated] = (0, react_1.useState)(false);
+    // Hydrate from storage after mount (client-only)
+    (0, react_1.useEffect)(() => {
+        if (typeof window === 'undefined')
+            return;
+        const stateManager = getBrowserStateManager();
+        (async () => {
+            try {
+                await stateManager.initialize();
+                const stored = await stateManager.get(key);
+                if (stored && 'value' in stored) {
+                    setState(stored.value);
+                }
+            }
+            catch (e) {
+                // eslint-disable-next-line no-console
+                console.warn(`[usePersistedState] Failed to load "${key}":`, e);
+            }
+            setIsHydrated(true);
+        })();
+    }, [key]);
+    // Persist to storage on changes (but only after hydration)
+    (0, react_1.useEffect)(() => {
+        if (!isHydrated || typeof window === 'undefined')
+            return;
+        const stateManager = getBrowserStateManager();
+        (async () => {
+            try {
+                await stateManager.set(key, {
+                    kind: 'ui-component',
+                    componentId: key,
+                    value: state
+                }); // Type assertion needed as we're adding custom 'value' field
+            }
+            catch (e) {
+                // eslint-disable-next-line no-console
+                console.warn(`[usePersistedState] Failed to save "${key}":`, e);
+            }
+        })();
+    }, [key, state, isHydrated]);
+    return [state, setState];
+}
+//# sourceMappingURL=usePersistedState.js.map

package/dist/cjs/src/react/usePersistedState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePersistedState.js","sourceRoot":"","sources":["../../../../src/react/usePersistedState.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAqBH,8CAmDC;AAtED,iCAA4C;AAC5C,0DAAuD;AACvD,wEAAqE;AACrE,0DAAuD;AAGvD,2DAA2D;AAC3D,IAAI,mBAAmB,GAAwB,IAAI,CAAC;AAEpD,SAAS,sBAAsB;IAC7B,IAAI,CAAC,mBAAmB,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAC1D,mBAAmB,GAAG,2BAAY,CAAC,WAAW,CAC5C,6BAAa,CAAC,cAAc,EAC5B,IAAI,yCAAmB,EAAE,CAC1B,CAAC;IACJ,CAAC;IACD,OAAO,mBAAoB,CAAC;AAC9B,CAAC;AAED,SAAgB,iBAAiB,CAC/B,GAAW,EACX,YAAe;IAEf,gDAAgD;IAChD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,IAAA,gBAAQ,EAAI,YAAY,CAAC,CAAC;IACpD,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,GAAG,IAAA,gBAAQ,EAAC,KAAK,CAAC,CAAC;IAEpD,iDAAiD;IACjD,IAAA,iBAAS,EAAC,GAAG,EAAE;QACb,IAAI,OAAO,MAAM,KAAK,WAAW;YAAE,OAAO;QAE1C,MAAM,YAAY,GAAG,sBAAsB,EAAE,CAAC;QAE9C,CAAC,KAAK,IAAI,EAAE;YACV,IAAI,CAAC;gBACH,MAAM,YAAY,CAAC,UAAU,EAAE,CAAC;gBAChC,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,GAAG,CAAgC,GAAG,CAAC,CAAC;gBAC1E,IAAI,MAAM,IAAI,OAAO,IAAI,MAAM,EAAE,CAAC;oBAChC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACzB,CAAC;YACH,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,sCAAsC;gBACtC,OAAO,CAAC,IAAI,CAAC,uCAAuC,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC;YAClE,CAAC;YAED,aAAa,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC,CAAC,EAAE,CAAC;IACP,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAEV,2DAA2D;IAC3D,IAAA,iBAAS,EAAC,GAAG,EAAE;QACb,IAAI,CAAC,UAAU,IAAI,OAAO,MAAM,KAAK,WAAW;YAAE,OAAO;QAEzD,MAAM,YAAY,GAAG,sBAAsB,EAAE,CAAC;QAE9C,CAAC,KAAK,IAAI,EAAE;YACV,IAAI,CAAC;gBACH,MAAM,YAAY,CAAC,GAAG,CAAgC,GAAG,EAAE;oBACzD,IAAI,EAAE,cAAc;oBACpB,WAAW,EAAE,GAAG;oBAChB,KAAK,EAAE,KAAK;iBACN,CAAC,CAAC,CAAE,6DAA6D;YAC3E,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,sCAAsC;gBACtC,OAAO,CAAC,IAAI,CAAC,uCAAuC,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC;YAClE,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;IACP,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC;IAE7B,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AAC3B,CAAC"}

package/dist/cjs/src/react/useToolBinding.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * useToolBinding Hook
+ * Auto-wires DOM elements to @Tool decorators based on data-testid
+ *
+ * Simplified version - tools receive raw events and handle their own logic
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useToolBinding = useToolBinding;
+const react_1 = require("react");
+const ToolRegistry_1 = require("../background/registry/ToolRegistry");
+function useToolBinding(containerRef, containerTestId, instanceId) {
+    (0, react_1.useEffect)(() => {
+        if (!containerRef.current)
+            return;
+        const storageKey = instanceId ? `${containerTestId}:${instanceId}` : containerTestId;
+        // 1. Register instance for duplicate detection
+        try {
+            ToolRegistry_1.ToolRegistry.registerInstance(storageKey, containerRef.current);
+        }
+        catch (error) {
+            console.error(`[useToolBinding] Instance already exists: ${storageKey}`, error);
+            return; // Don't wire up duplicate instances
+        }
+        // 2. Find all elements with data-testid within container (and the container itself)
+        const elements = [];
+        // Check if container itself has data-testid
+        if (containerRef.current.hasAttribute('data-testid')) {
+            elements.push(containerRef.current);
+        }
+        // Find children with data-testid
+        const childElements = containerRef.current.querySelectorAll('[data-testid]');
+        elements.push(...Array.from(childElements));
+        const handlers = [];
+        elements.forEach((element) => {
+            const testId = element.getAttribute('data-testid');
+            if (!testId)
+                return;
+            // 3. Find matching tool from registry
+            const tool = ToolRegistry_1.ToolRegistry.findToolByElementId(testId);
+            if (!tool || !tool.method) {
+                console.warn(`[useToolBinding] Tool not found or has no method for elementId: ${testId}`);
+                return;
+            }
+            // Note: instance may not be set yet (lazy initialization)
+            // We'll check for it when the event fires
+            // 4. Create handler that extracts values from events and calls tool
+            const handler = async (event) => {
+                if (!tool.method || !tool.instance) {
+                    console.warn(`[useToolBinding] Tool ${tool.name} missing method or instance`);
+                    return;
+                }
+                // Extract value from event based on element type
+                let value;
+                const target = event.target;
+                if (target instanceof HTMLInputElement) {
+                    if (target.type === 'checkbox') {
+                        value = target.checked;
+                    }
+                    else if (target.type === 'radio') {
+                        value = target.value;
+                    }
+                    else {
+                        value = target.value;
+                    }
+                }
+                else if (target instanceof HTMLSelectElement) {
+                    value = target.value;
+                }
+                else if (target instanceof HTMLTextAreaElement) {
+                    value = target.value;
+                }
+                // For buttons and other elements, no value needed (void call)
+                const options = {
+                // Storage will be added in next step
+                // For now, tools get extracted value
+                };
+                try {
+                    // Call the actual decorated method with extracted value
+                    const result = value !== undefined
+                        ? await tool.method.call(tool.instance, value, options)
+                        : await tool.method.call(tool.instance, options);
+                    console.log(`[useToolBinding] Tool ${tool.name} executed successfully`, result);
+                }
+                catch (error) {
+                    console.error(`[useToolBinding] Tool execution failed: ${tool.name}`, error);
+                }
+            };
+            // 5. Wire up with appropriate event type
+            // Use tool's actionType if specified, otherwise infer from element
+            let eventType = tool.actionType || 'click';
+            if (!tool.actionType) {
+                if (element instanceof HTMLInputElement || element instanceof HTMLSelectElement || element instanceof HTMLTextAreaElement) {
+                    eventType = 'change';
+                }
+            }
+            console.log(`[useToolBinding] Wiring ${testId} with event: ${eventType}`);
+            element.addEventListener(eventType, handler);
+            handlers.push({ element, event: eventType, handler });
+        });
+        // 6. Cleanup
+        return () => {
+            handlers.forEach(({ element, event, handler }) => {
+                element.removeEventListener(event, handler);
+            });
+            ToolRegistry_1.ToolRegistry.unregisterInstance(storageKey);
+        };
+    }, [containerRef, containerTestId, instanceId]);
+}
+//# sourceMappingURL=useToolBinding.js.map

package/dist/cjs/src/react/useToolBinding.js.map

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

package/dist/cjs/src/routes/RouteContractGenerator.js

@@ -0,0 +1,119 @@
+"use strict";
+// Generated from: 2025-12-28-simple-name-extraction.md
+// Generated on: 2025-12-28
+// DO NOT EDIT - Regenerate from documentation if changes needed
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RouteContractGenerator = void 0;
+/**
+ * Generates type-safe route contracts with structured output.
+ * Groups routes by category (Views, API, etc.) and HTTP methods.
+ *
+ * @example
+ * ```typescript
+ * import { RouteContractGenerator } from '@supernal/interface-core/routes';
+ *
+ * const generator = new RouteContractGenerator();
+ * const scanResult = await scanner.scan();
+ *
+ * // Generate contracts
+ * const content = generator.generate(scanResult);
+ *
+ * // Generated output:
+ * // export const Routes = {
+ * //   Views: {
+ * //     Overview: '/:repo/:branch/overview'
+ * //   },
+ * //   API: {
+ * //     Users: {
+ * //       GET: '/api/users',
+ * //       POST: '/api/users'
+ * //     }
+ * //   }
+ * // } as const;
+ * ```
+ */
+class RouteContractGenerator {
+    generate(scanResult) {
+        // Group routes by category
+        const grouped = this.groupRoutes(scanResult.routes);
+        return `
+// Generated from route scanning
+// DO NOT EDIT - Regenerate with: sc routes generate
+
+${this.generateViews(grouped.view)}
+${this.generateAPI(grouped.api)}
+
+// Helper to build route with params
+// Supports both string patterns and route objects with metadata
+export function buildRoute(
+  route: string | { pattern: string; [key: string]: any }, 
+  params: Record<string, string>
+): string {
+  const pattern = typeof route === 'string' ? route : route.pattern;
+  let result = pattern;
+  for (const [key, value] of Object.entries(params)) {
+    result = result.replace(\`:$\{key}\`, value);
+  }
+  return result;
+}
+`.trim();
+    }
+    groupRoutes(routes) {
+        const grouped = {};
+        routes.forEach(route => {
+            const category = route.metadata?.category || 'other';
+            if (!grouped[category])
+                grouped[category] = [];
+            grouped[category].push(route);
+        });
+        return grouped;
+    }
+    generateViews(views = []) {
+        if (views.length === 0)
+            return '';
+        const entries = views.map(view => {
+            const name = this.toPascalCase(view.id.replace('view-', ''));
+            return `    ${name}: '${view.pattern}',`;
+        }).join('\n');
+        return `
+export const Routes = {
+  Views: {
+${entries}
+  },
+`;
+    }
+    generateAPI(apis = []) {
+        if (apis.length === 0)
+            return '';
+        const entries = apis.map(api => {
+            const name = this.toPascalCase(api.id.replace('api-', ''));
+            const methods = api.metadata?.methods;
+            const params = api.params;
+            // Generate route object with metadata
+            if (methods || params.length > 0) {
+                const parts = [
+                    `pattern: '${api.pattern}'`,
+                    methods && methods.length > 0 ? `methods: [${methods.map(m => `'${m}'`).join(', ')}] as const` : null,
+                    params.length > 0 ? `params: [${params.map(p => `'${p}'`).join(', ')}] as const` : null,
+                ].filter(Boolean);
+                return `    ${name}: {\n      ${parts.join(',\n      ')}\n    },`;
+            }
+            // Fallback: simple string (for backward compatibility)
+            return `    ${name}: '${api.pattern}',`;
+        }).join('\n');
+        return `
+  API: {
+${entries}
+  },
+} as const;
+`;
+    }
+    toPascalCase(str) {
+        return str
+            .split(/[-_]/)
+            .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+            .join('');
+    }
+}
+exports.RouteContractGenerator = RouteContractGenerator;
+//# sourceMappingURL=RouteContractGenerator.js.map

package/dist/cjs/src/routes/RouteContractGenerator.js.map

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

package/dist/cjs/src/routes/RouteContractsConfig.js

@@ -0,0 +1,39 @@
+"use strict";
+// Generated from: 2025-12-27-implementation.md
+// Generated on: 2025-12-28
+// DO NOT EDIT - Regenerate from documentation if changes needed
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exampleNextjsConfig = void 0;
+/**
+ * Example config for Next.js 14 app with dynamic routing
+ */
+exports.exampleNextjsConfig = {
+    routingSystem: 'nextjs-dynamic',
+    scanPaths: {
+        routes: ['src/app'],
+        configs: ['src/lib/routing'],
+        components: ['src/components/views'],
+    },
+    output: {
+        contractsPath: 'src/lib/routing/Routes.ts',
+        testUtilsPath: 'tests/utils/routes.ts',
+        moduleFormat: 'esm',
+    },
+    generation: {
+        includeJsDocs: true,
+        includeValidation: true,
+        defaults: {
+            repo: 'default-repo',
+            branch: 'main',
+        },
+    },
+    migration: {
+        detectPatterns: [
+            'page\\.goto\\([\'"`](.+?)[\'"`]\\)',
+            'navigate\\([\'"`](.+?)[\'"`]\\)',
+        ],
+        filePatterns: ['**/*.spec.ts', '**/*.test.ts'],
+        dryRun: false,
+    },
+};
+//# sourceMappingURL=RouteContractsConfig.js.map

package/dist/cjs/src/routes/RouteContractsConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteContractsConfig.js","sourceRoot":"","sources":["../../../../src/routes/RouteContractsConfig.ts"],"names":[],"mappings":";AAAA,+CAA+C;AAC/C,2BAA2B;AAC3B,gEAAgE;;;AA8GhE;;GAEG;AACU,QAAA,mBAAmB,GAAyB;IACvD,aAAa,EAAE,gBAAgB;IAC/B,SAAS,EAAE;QACT,MAAM,EAAE,CAAC,SAAS,CAAC;QACnB,OAAO,EAAE,CAAC,iBAAiB,CAAC;QAC5B,UAAU,EAAE,CAAC,sBAAsB,CAAC;KACrC;IACD,MAAM,EAAE;QACN,aAAa,EAAE,2BAA2B;QAC1C,aAAa,EAAE,uBAAuB;QACtC,YAAY,EAAE,KAAK;KACpB;IACD,UAAU,EAAE;QACV,aAAa,EAAE,IAAI;QACnB,iBAAiB,EAAE,IAAI;QACvB,QAAQ,EAAE;YACR,IAAI,EAAE,cAAc;YACpB,MAAM,EAAE,MAAM;SACf;KACF;IACD,SAAS,EAAE;QACT,cAAc,EAAE;YACd,oCAAoC;YACpC,iCAAiC;SAClC;QACD,YAAY,EAAE,CAAC,cAAc,EAAE,cAAc,CAAC;QAC9C,MAAM,EAAE,KAAK;KACd;CACF,CAAC"}

package/dist/cjs/src/routes/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Route Scanning System
+ *
+ * Scans Next.js routes (App Router + Pages Router) and generates
+ * type-safe route contracts with HTTP method extraction.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RouteContractGenerator = exports.NameExtractor = exports.NextjsDynamicScanner = exports.RouteScanner = void 0;
+// Scanners
+var RouteScanner_1 = require("./scanners/RouteScanner");
+Object.defineProperty(exports, "RouteScanner", { enumerable: true, get: function () { return RouteScanner_1.RouteScanner; } });
+var NextjsDynamicScanner_1 = require("./scanners/NextjsDynamicScanner");
+Object.defineProperty(exports, "NextjsDynamicScanner", { enumerable: true, get: function () { return NextjsDynamicScanner_1.NextjsDynamicScanner; } });
+var NameExtractor_1 = require("./scanners/NameExtractor");
+Object.defineProperty(exports, "NameExtractor", { enumerable: true, get: function () { return NameExtractor_1.NameExtractor; } });
+// Generation
+var RouteContractGenerator_1 = require("./RouteContractGenerator");
+Object.defineProperty(exports, "RouteContractGenerator", { enumerable: true, get: function () { return RouteContractGenerator_1.RouteContractGenerator; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/src/routes/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/routes/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,WAAW;AACX,wDAAuD;AAA9C,4GAAA,YAAY,OAAA;AAGrB,wEAAuE;AAA9D,4HAAA,oBAAoB,OAAA;AAC7B,0DAAyD;AAAhD,8GAAA,aAAa,OAAA;AAEtB,aAAa;AACb,mEAAkE;AAAzD,gIAAA,sBAAsB,OAAA"}