@pithyjs/router 0.1.0-beta.0

package/dist/router/core/router.js

@@ -0,0 +1,762 @@
+/** @codex
+{
+  "id": "pithy.router.core",
+  "title": "Router Core with Navigation Transaction State Machine",
+  "category": "runtime"
+}
+*/
+import { signal, computed } from '@pithyjs/signals';
+import { parseQueryParams } from './params';
+import { findBestMatch, normalizePath } from './matcher';
+import { flattenRouteTree } from './route-tree';
+import { initializeScrollRestoration } from './config';
+import { ROUTER_CONFIG } from './constants';
+import { NavigationPipeline } from './pipeline';
+import { HistoryManager } from './history';
+import { FeatureCoordinator, } from '../features/coordinator';
+import { OutletManager } from '../features/outlet';
+import { buildSegmentChain } from '../features/outlet/segment-chain';
+import { scrollFocusManager } from '../features/ux/scroll-focus';
+import { viewTransitionManager } from '../features/ux/transitions';
+import { hmrManager } from '../integration/hmr';
+import { LinkInterceptor } from '../integration/link-interceptor';
+import { BrowserHistoryAdapter } from '../integration/history-adapter';
+import { setGlobalRouter } from '../integration/directive-binder';
+/** @codexApi {"parent":"pithy.router.core","name":"Router","stability":"stable","signature":"class Router","description":"Core router class with navigation transaction state machine"} */
+/**
+ * Core router class with navigation transaction state machine
+ * Implements enhanced architectural improvements for production-ready routing
+ */
+export class Router {
+    constructor(routes, config = {}) {
+        this.previousSegmentChain = [];
+        this.mountedElement = null;
+        this.isMounted = false;
+        // Cleanup references for dispose()
+        this.popstateListener = null;
+        this.hmrCleanup = null;
+        // Memoized computed accessors (created once to avoid leaking effects)
+        this._path = null;
+        this._params = null;
+        this._query = null;
+        this._loaderData = null;
+        // Router signals
+        this.routerState = signal({
+            path: '/',
+            params: {},
+            query: {},
+            match: null,
+            loaderData: null,
+            isNavigating: false,
+            activeNavigation: null,
+        });
+        // Committed state tracking for two-phase commit
+        this.committed = { path: '/', params: {}, query: {}, match: null };
+        // DOM snapshot for safety belt
+        this.outletSnapshot = null;
+        this.routes = routes;
+        // Detect if running in development mode
+        const isDev = typeof import.meta !== 'undefined' &&
+            import.meta.env?.DEV === true;
+        this.config = {
+            basePath: '',
+            trailingSlash: 'never',
+            decodeParams: true,
+            viewTransitions: false,
+            a11y: true,
+            interceptLinks: true,
+            linkIgnoreAttr: 'data-router-ignore',
+            loadingPolicy: 'replace',
+            popstateLoading: 'none',
+            setAsGlobal: true,
+            exposeToWindow: isDev,
+            windowKey: 'router',
+            outletSelector: '[data-router-outlet]',
+            ...config,
+        };
+        // Take control of scroll restoration - disable browser's automatic behavior
+        initializeScrollRestoration();
+        // Initialize history manager with adapter (defaults to browser adapter, enables SSR)
+        const historyAdapter = config.historyAdapter || new BrowserHistoryAdapter();
+        this.historyManager = new HistoryManager(historyAdapter);
+        // Initialize navigation pipeline
+        this.pipeline = new NavigationPipeline();
+        // Initialize feature coordinator
+        this.features = new FeatureCoordinator(this.config);
+        // Initialize link interceptor
+        this.linkInterceptor = new LinkInterceptor();
+        // Initialize outlet manager
+        this.outletManager = new OutletManager();
+        this.outletManager.setRouter(this);
+        // Managers are now handled by FeatureCoordinator
+        // Configure view transition manager with router config
+        // Handle both boolean (simple enable/disable) and object (advanced config)
+        if (typeof this.config.viewTransitions === 'boolean') {
+            viewTransitionManager.updateConfig({
+                enabled: this.config.viewTransitions,
+            });
+        }
+        else if (this.config.viewTransitions) {
+            viewTransitionManager.updateConfig(this.config.viewTransitions);
+        }
+        else {
+            viewTransitionManager.updateConfig({
+                enabled: false,
+            });
+        }
+        // Configure scroll/focus manager with a11y settings
+        scrollFocusManager.updateConfig({
+            liveRegion: {
+                enabled: this.config.a11y ?? true,
+            },
+        });
+        // Extract route patterns for matching (including nested routes)
+        // Flatten the route tree to get all patterns
+        const flatRoutes = flattenRouteTree(routes);
+        this.routePatterns = flatRoutes.map(entry => entry.node.pattern);
+        // Install global link interception once (if enabled)
+        if (this.config.interceptLinks) {
+            this.setupLinkInterceptor();
+        }
+        // Initialize with current location
+        this.initializeFromCurrentLocation();
+        // Set up history listeners
+        this.setupHistoryListeners();
+        // Enable HMR integration (thin layer delegates to updateRoutes)
+        this.setupHMR();
+        // Expose router to window for debugging (in dev mode)
+        if (this.config.exposeToWindow && typeof window !== 'undefined') {
+            const key = this.config.windowKey || 'router';
+            Reflect.set(window, key, this);
+        }
+    }
+    /** @codexApi {"parent":"pithy.router.core","name":"state","stability":"stable","signature":"() => Signal<RouterState>","description":"Get current router state as a reactive signal"} */
+    /**
+     * Get current router state as reactive signal
+     */
+    state() {
+        return this.routerState;
+    }
+    /** @codexApi {"parent":"pithy.router.core","name":"path","stability":"stable","signature":"() => () => string","description":"Get current path as a computed reactive signal"} */
+    /**
+     * Get current path as reactive signal (memoized to avoid leaking effects)
+     */
+    path() {
+        return (this._path ?? (this._path = computed(() => this.routerState().path)));
+    }
+    /** @codexApi {"parent":"pithy.router.core","name":"params","stability":"stable","signature":"() => () => RouteParams","description":"Get current route params as a computed reactive signal"} */
+    /**
+     * Get current params as reactive signal (memoized to avoid leaking effects)
+     */
+    params() {
+        return (this._params ?? (this._params = computed(() => this.routerState().params)));
+    }
+    /** @codexApi {"parent":"pithy.router.core","name":"query","stability":"stable","signature":"() => () => QueryParams","description":"Get current query params as a computed reactive signal"} */
+    /**
+     * Get current query as reactive signal (memoized to avoid leaking effects)
+     */
+    query() {
+        return (this._query ?? (this._query = computed(() => this.routerState().query)));
+    }
+    /** @codexApi {"parent":"pithy.router.core","name":"loaderData","stability":"stable","signature":"() => () => ResourceState | null","description":"Get current loader data as a computed reactive signal"} */
+    /**
+     * Get current loader data as reactive signal (memoized to avoid leaking effects)
+     */
+    loaderData() {
+        return (this._loaderData ?? (this._loaderData = computed(() => this.routerState().loaderData)));
+    }
+    /** @codexApi {"parent":"pithy.router.core","name":"navigate","stability":"stable","signature":"(path: string, options?: NavigationOptions) => Promise<boolean>","description":"Navigate to a path with two-phase commit via the pipeline"} */
+    /**
+     * Navigate to a new path with two-phase commit and transactional navigation
+     * Delegates to NavigationPipeline for orchestration
+     */
+    async navigate(path, options = {}) {
+        // Delegate to NavigationPipeline
+        return this.pipeline.execute(path, options, this.createNavigationContext());
+    }
+    /** @codexApi {"parent":"pithy.router.core","name":"back","stability":"stable","signature":"() => void","description":"Go back one entry in browser history"} */
+    /**
+     * Go back in history
+     */
+    back() {
+        this.historyManager.back();
+    }
+    /** @codexApi {"parent":"pithy.router.core","name":"forward","stability":"stable","signature":"() => void","description":"Go forward one entry in browser history"} */
+    /**
+     * Go forward in history
+     */
+    forward() {
+        this.historyManager.forward();
+    }
+    /** @codexApi {"parent":"pithy.router.core","name":"mount","stability":"stable","signature":"(rootElement: HTMLElement) => void","description":"Mount router to a DOM element and activate outlet routing"} */
+    /**
+     * Mount router to DOM element with outlet management
+     * Automatically finds outlet element and sets up routing
+     *
+     * @param rootElement - Root element containing the router outlet
+     */
+    mount(rootElement) {
+        // Make mount idempotent - calling multiple times is safe
+        if (this.isMounted) {
+            console.warn('[Router] Already mounted, ignoring duplicate mount call');
+            return;
+        }
+        // Find the outlet element within the root element
+        const outletSelector = this.config.outletSelector || '[data-router-outlet]';
+        const outlet = rootElement.querySelector(outletSelector);
+        if (!outlet) {
+            throw new Error(`[Router] Outlet not found. Add <div @routerOutlet></div> to your app root. ` +
+                `Searched for selector: ${outletSelector}`);
+        }
+        // Set the outlet as mounted element
+        this.mountedElement = outlet;
+        this.isMounted = true;
+        // Set mounted element on LoadingUIManager
+        this.features.getLoadingUI().setMountedElement(outlet);
+        // Set router as global for directive binding (if configured)
+        if (this.config.setAsGlobal) {
+            setGlobalRouter(this);
+        }
+        // Initial mount of current route
+        this.mountCurrentRoute();
+    }
+    /** @codexApi {"parent":"pithy.router.core","name":"getActiveNavId","stability":"experimental","signature":"() => NavigationId","description":"Get the active navigation ID for outlet manager integration"} */
+    /**
+     * Get the active navigation ID for outlet manager integration
+     */
+    getActiveNavId() {
+        return this.pipeline.getActiveNavId();
+    }
+    /** @codexApi {"parent":"pithy.router.core","name":"isNavActive","stability":"experimental","signature":"(navId: NavigationId) => boolean","description":"Check if a navigation ID is still active"} */
+    /**
+     * Check if a navigation ID is still active
+     */
+    isNavActive(navId) {
+        return this.isNavigationActive(navId);
+    }
+    /** @codexApi {"parent":"pithy.router.core","name":"prefetchRoute","stability":"experimental","signature":"(href: string, signal: AbortSignal) => Promise<void>","description":"Prefetch route components using shared module cache"} */
+    /**
+     * Prefetch route components (for PrefetchManager integration)
+     * Uses shared module cache from @pithyjs/core for deduplication
+     */
+    async prefetchRoute(href, signal) {
+        if (signal.aborted)
+            return;
+        const url = new URL(href, window.location.origin);
+        const pathname = this.normalizePath(url.pathname);
+        const match = findBestMatch(pathname, this.routePatterns, this.config);
+        if (!match) {
+            return;
+        }
+        const route = this.routes.find(r => r.pattern === match.pattern);
+        if (!route)
+            return;
+        try {
+            // Import module loader utility for shared cache integration
+            const { loadRouteModule, getRouteModuleKey } = await import('../features/module-loader');
+            // Prefetch page component
+            if (route.imports.page && !signal.aborted) {
+                await loadRouteModule(getRouteModuleKey(route.pattern, 'page'), route.imports.page);
+            }
+            // Prefetch layout component if exists
+            if (route.imports.layout && !signal.aborted) {
+                await loadRouteModule(getRouteModuleKey(route.pattern, 'layout'), route.imports.layout);
+            }
+            // Prefetch loading component if exists
+            if (route.imports.loading && !signal.aborted) {
+                await loadRouteModule(getRouteModuleKey(route.pattern, 'loading'), route.imports.loading);
+            }
+            // Prefetch error component if exists
+            if (route.imports.error && !signal.aborted) {
+                await loadRouteModule(getRouteModuleKey(route.pattern, 'error'), route.imports.error);
+            }
+            // Prefetch config and execute prefetchChunks if defined
+            if (route.imports.config && !signal.aborted) {
+                const configModule = await loadRouteModule(getRouteModuleKey(route.pattern, 'config'), route.imports.config);
+                // Execute prefetchChunks if defined in config
+                if (configModule?.prefetchChunks &&
+                    Array.isArray(configModule.prefetchChunks)) {
+                    const prefetchPromises = [];
+                    for (const chunk of configModule.prefetchChunks) {
+                        if (signal.aborted)
+                            break;
+                        if (typeof chunk === 'function') {
+                            prefetchPromises.push(Promise.resolve(chunk()).catch(() => {
+                                // Silently ignore prefetch chunk failures
+                            }));
+                        }
+                    }
+                    // Wait for all prefetch chunks to complete (in parallel)
+                    await Promise.all(prefetchPromises);
+                }
+            }
+        }
+        catch (error) {
+            if (!signal.aborted) {
+                console.warn('[Router] Prefetch failed:', error);
+            }
+        }
+    }
+    /** @codexApi {"parent":"pithy.router.core","name":"updateRoutes","stability":"stable","signature":"(newRoutes: RouteNode[], options?: { source?: string }) => Promise<void>","description":"Hot-update routes for HMR, preserving router state"} */
+    /**
+     * Update routes (for HMR support)
+     * Called by HMR manager when route modules are updated
+     * Preserves router state and only re-mounts outlets with new code
+     *
+     * @param newRoutes - Updated route tree from HMR
+     * @param options - Optional configuration
+     */
+    async updateRoutes(newRoutes, _options) {
+        const currentMatch = this.routerState().match;
+        // Capture scroll position for restoration after remount (uses singleton)
+        hmrManager.captureScrollSnapshot();
+        // Invalidate module cache for all routes (HMR needs fresh imports)
+        // This ensures HMR'd components are actually re-imported
+        try {
+            const { invalidateAllRouteModules } = await import('../features/module-loader');
+            await invalidateAllRouteModules(newRoutes);
+        }
+        catch {
+            // Module loader not available, continue without cache invalidation
+        }
+        // Update router's internal state with new routes FIRST
+        this.routes = newRoutes;
+        // Force full remount by clearing previous segment chain
+        // This ensures HMR'd components are actually re-imported and re-mounted
+        this.previousSegmentChain = [];
+        // Navigate to refresh routes using HMR manager singleton
+        this.routePatterns = await hmrManager.handleRouteUpdate(newRoutes, currentMatch, (path, opts) => this.navigate(path, opts), () => this.features.clearLoadingUI());
+    }
+    /** @codexApi {"parent":"pithy.router.core","name":"prefetchLoader","stability":"experimental","signature":"(href: string, signal: AbortSignal) => Promise<void>","description":"Prefetch route loader data with guard checks"} */
+    /**
+     * Prefetch route loader data (for PrefetchManager integration)
+     */
+    async prefetchLoader(href, signal) {
+        if (signal.aborted)
+            return;
+        const url = new URL(href, window.location.origin);
+        const pathname = this.normalizePath(url.pathname);
+        const search = url.search;
+        const match = findBestMatch(pathname, this.routePatterns, this.config);
+        if (!match) {
+            return;
+        }
+        const route = this.routes.find(r => r.pattern === match.pattern);
+        if (!route || !route.imports.loader) {
+            // No loader to prefetch
+            return;
+        }
+        try {
+            const query = this.parseQueryParams(search);
+            // Check guards before prefetching loader
+            const guards = await this.features.loadGuards(match.pattern, this.routes);
+            if (guards.length > 0) {
+                const guardRes = await this.features.executeGuards(guards, {
+                    path: pathname,
+                    params: match.params,
+                    query,
+                    signal,
+                    navId: ROUTER_CONFIG.INITIAL_NAV_ID,
+                    from: this.routerState().path,
+                });
+                // If guards deny access, don't prefetch the loader
+                if (!guardRes.allowed) {
+                    return;
+                }
+            }
+            // Execute the loader and cache the result using FeatureCoordinator
+            await this.features.executeLoaders(match.pattern, {
+                params: match.params,
+                query,
+                signal,
+                navId: ROUTER_CONFIG.INITIAL_NAV_ID, // Use special navId for prefetch
+                updateRouterState: (updates) => this.updateRouterState(updates),
+            }, this.routes);
+        }
+        catch (error) {
+            if (!signal.aborted) {
+                console.warn('[Router] Prefetch loader failed:', error);
+            }
+        }
+    }
+    /** @codexApi {"parent":"pithy.router.core","name":"getRouteCacheTTL","stability":"experimental","signature":"(href: string) => Promise<number | undefined>","description":"Get the configured cache TTL for a specific route"} */
+    /**
+     * Get the cache TTL for a specific route (for PrefetchManager integration)
+     * Returns the route's configured cache TTL, or undefined if not configured
+     */
+    async getRouteCacheTTL(href) {
+        const url = new URL(href, window.location.origin);
+        const pathname = this.normalizePath(url.pathname);
+        const match = findBestMatch(pathname, this.routePatterns, this.config);
+        if (!match) {
+            return undefined;
+        }
+        const route = this.routes.find(r => r.pattern === match.pattern);
+        if (!route || !route.imports.config) {
+            return undefined;
+        }
+        try {
+            const configModule = await route.imports.config();
+            const cache = configModule?.cache;
+            if (cache &&
+                typeof cache === 'object' &&
+                typeof cache.ttl === 'number') {
+                return cache.ttl;
+            }
+        }
+        catch {
+            // Ignore config loading errors
+        }
+        return undefined;
+    }
+    /** @codexApi {"parent":"pithy.router.core","name":"dispose","stability":"stable","signature":"() => void","description":"Dispose router and clean up all listeners, outlets, and navigations"} */
+    /**
+     * Dispose of the router and clean up all resources
+     *
+     * This method should be called when unmounting the router or destroying the app.
+     * It cleans up:
+     * - Mounted components and their disposers
+     * - Event listeners (popstate, click)
+     * - HMR subscriptions
+     * - Active navigation transactions
+     *
+     * Note: In typical SPA usage, the router lives for the entire page lifetime,
+     * so dispose() is rarely needed. It's mainly useful for:
+     * - Testing (to prevent memory leaks between tests)
+     * - Multiple router instances
+     * - Micro-frontends
+     * - Server-side rendering cleanup
+     */
+    dispose() {
+        // 1. Clean up outlet manager (mounted components and disposers)
+        this.outletManager.dispose();
+        // 2. Remove popstate listener
+        if (this.popstateListener) {
+            window.removeEventListener('popstate', this.popstateListener);
+            this.popstateListener = null;
+        }
+        // 3. Clean up HMR subscription
+        if (this.hmrCleanup) {
+            this.hmrCleanup();
+            this.hmrCleanup = null;
+        }
+        // 4. Abort any active navigation
+        this.pipeline.cancelActiveNavigation();
+        // 5. Uninstall link interceptor
+        this.linkInterceptor.uninstall();
+        // 6. Clean up scroll/focus manager (including live region announcer)
+        scrollFocusManager.updateConfig({
+            liveRegion: { enabled: false },
+        });
+        // 7. Clean up view transition manager (remove injected styles)
+        viewTransitionManager.cleanup();
+        // 8. Clear mounted element reference
+        this.mountedElement = null;
+        // 9. Clear previous segment chain
+        this.previousSegmentChain = [];
+        // 10. Clear outlet snapshot
+        this.outletSnapshot = null;
+        // 11. Clear memoized computed accessors (prevents retaining Router via closures)
+        this._path = null;
+        this._params = null;
+        this._query = null;
+        this._loaderData = null;
+    }
+    // Private methods for navigation transaction state machine
+    /**
+     * Save current scroll position to history.state before navigation
+     * Delegates to HistoryManager to avoid code duplication
+     */
+    saveScrollToHistory() {
+        this.historyManager.saveScrollPosition();
+    }
+    /**
+     * Generate a stable selector for an element
+     */
+    isNavigationActive(navId) {
+        // Special case: navId 0 is always considered active (initial mount)
+        if (navId === ROUTER_CONFIG.INITIAL_NAV_ID)
+            return true;
+        // Delegate to pipeline for transaction check
+        const txActive = this.pipeline.isActive(navId);
+        // Fallback: commit already happened for this nav (match set),
+        // so mount is still relevant even if tx was cleared.
+        const committedForThisNav = this.pipeline.getActiveNavId() === navId && !!this.routerState().match;
+        return txActive || committedForThisNav;
+    }
+    initializeFromCurrentLocation() {
+        const currentPath = window.location.pathname;
+        const search = window.location.search;
+        const fullPath = currentPath + search;
+        // Run initial navigation through the same guard system
+        // Use replace: true to avoid adding to history
+        this.navigate(fullPath, { replace: true }).catch(error => {
+            console.error('[Router] Initial navigation failed:', error);
+            // Fallback to direct state update if navigation fails
+            const normalizedPath = this.normalizePath(currentPath);
+            const match = findBestMatch(normalizedPath, this.routePatterns, this.config);
+            const queryParams = this.parseQueryParams(search);
+            this.updateRouterState({
+                path: normalizedPath,
+                params: match?.params || {},
+                query: queryParams,
+                match,
+                isNavigating: false,
+                activeNavigation: null,
+            });
+        });
+    }
+    setupHistoryListeners() {
+        this.popstateListener = event => {
+            const url = new URL(window.location.href);
+            const pathname = this.normalizePath(url.pathname);
+            const search = url.search;
+            // Start a navigation sourced from POP; never push/replace during this flow
+            this.navigate(pathname + search, {
+                state: event.state,
+                source: 'pop',
+            }).catch(err => console.warn('[Router] Popstate failed:', err));
+        };
+        window.addEventListener('popstate', this.popstateListener);
+    }
+    /**
+     * Set up HMR integration (thin layer pattern)
+     * Delegates to HMRManager which handles Vite HMR subscription
+     * Preserves router state and only re-mounts outlets
+     */
+    setupHMR() {
+        // Only enable in development with Vite HMR available
+        if (typeof window !== 'undefined' &&
+            import.meta.hot) {
+            // Enable HMR manager singleton with callback to updateRoutes
+            this.hmrCleanup = hmrManager.enable(async (newRoutes) => {
+                await this.updateRoutes(newRoutes, { source: 'hmr' });
+            });
+        }
+    }
+    /**
+     * Set up global link interceptor - delegates to LinkInterceptor class
+     */
+    setupLinkInterceptor() {
+        this.linkInterceptor.install(href => this.navigate(href), this.config);
+    }
+    normalizePath(path) {
+        // Apply base path if configured
+        let normalizedPath = path;
+        if (this.config.basePath) {
+            normalizedPath = normalizedPath.replace(new RegExp(`^${this.config.basePath}`), '');
+        }
+        return normalizePath(normalizedPath, this.config.trailingSlash);
+    }
+    parseQueryParams(search) {
+        return parseQueryParams(search);
+    }
+    async updateRouterState(updates) {
+        const currentState = this.routerState();
+        this.routerState.set({
+            ...currentState,
+            ...updates,
+        });
+        // Trigger route mounting when state changes
+        if (this.mountedElement && updates.match !== undefined) {
+            await this.mountCurrentRoute();
+        }
+    }
+    /**
+     * Show route loading in outlet using atomic swap (no overlay, no blank)
+     * Implements the core "replace" policy for forward navigations
+     * NOTE: No View Transition here - loading UI should be plain swap to avoid
+     * the spinner becoming the "transition target" and getting stuck
+     */
+    /**
+     * Snapshot committed DOM for safety belt
+     */
+    snapshotCommittedOutlet() {
+        if (!this.mountedElement)
+            return;
+        const frag = document.createDocumentFragment();
+        // Clone nodes to avoid moving them out
+        this.mountedElement.childNodes.forEach(node => {
+            frag.appendChild(node.cloneNode(true));
+        });
+        this.outletSnapshot = frag;
+    }
+    /**
+     * Restore snapshot if outlet is empty (safety belt)
+     */
+    restoreSnapshotIfEmpty() {
+        if (!this.mountedElement)
+            return;
+        if (this.mountedElement.childNodes.length === 0 && this.outletSnapshot) {
+            this.mountedElement.appendChild(this.outletSnapshot.cloneNode(true));
+        }
+    }
+    /**
+     * Mount the current route using the outlet manager
+     */
+    async mountCurrentRoute() {
+        if (!this.mountedElement || !this.routerState().match) {
+            return;
+        }
+        try {
+            const segmentChain = this.buildCurrentSegmentChain();
+            if (!segmentChain)
+                return;
+            const success = await this.outletManager.mountSegments(segmentChain, this.pipeline.getActiveNavId(), this.mountedElement);
+            if (success) {
+                this.handleMountSuccess(segmentChain);
+            }
+            else {
+                this.handleMountFailure();
+            }
+        }
+        catch (error) {
+            console.error('[Router] Mount error:', error);
+        }
+    }
+    /**
+     * Build segment chain for the current route
+     * @returns Segment chain or null if empty
+     */
+    buildCurrentSegmentChain() {
+        const currentState = this.routerState();
+        const segmentChain = buildSegmentChain(this.routes, currentState.path, currentState.params, this.previousSegmentChain);
+        if (segmentChain.length === 0) {
+            console.warn('[Router] Empty segment chain - no routes to mount');
+            return null;
+        }
+        return segmentChain;
+    }
+    /**
+     * Handle successful route mount
+     * Updates state, snapshots DOM, and manages scroll/focus restoration
+     */
+    handleMountSuccess(segmentChain) {
+        const currentState = this.routerState();
+        // Update previous segment chain for next diff
+        this.previousSegmentChain = segmentChain;
+        // Update "committed" logical route
+        this.committed = {
+            path: currentState.path,
+            params: currentState.params,
+            query: currentState.query,
+            match: currentState.match,
+        };
+        // Snapshot current committed DOM for safety
+        this.snapshotCommittedOutlet();
+        // Restore HMR scroll position if needed
+        this.restoreHMRScrollIfNeeded();
+        // Manage focus after route mount completes
+        this.scheduleFocusManagement();
+    }
+    /**
+     * Restore HMR scroll position after successful mount
+     * Uses HMRManager singleton to consume the scroll snapshot
+     */
+    restoreHMRScrollIfNeeded() {
+        const state = this.routerState();
+        // Consume scroll snapshot from HMR manager
+        const scrollSnapshot = hmrManager.consumeScrollSnapshot();
+        if (!scrollSnapshot || scrollSnapshot.path !== state.path) {
+            return;
+        }
+        const { x, y } = scrollSnapshot;
+        // Wait two frames to ensure layout is stable
+        requestAnimationFrame(() => {
+            requestAnimationFrame(() => {
+                window.scrollTo(x, y);
+            });
+        });
+    }
+    /**
+     * Schedule focus management after route mount
+     */
+    scheduleFocusManagement() {
+        requestAnimationFrame(() => {
+            requestAnimationFrame(() => {
+                scrollFocusManager.manageFocus({ preventScroll: true });
+            });
+        });
+    }
+    /**
+     * Handle failed route mount
+     * Clears loading UI but keeps old view
+     */
+    handleMountFailure() {
+        // Mount failed: do not clear DOM; remove overlays, keep old view
+        this.features.clearLoadingUI();
+        // Transaction is managed by NavigationPipeline
+    }
+    /**
+     * Create navigation context for pipeline
+     * @private
+     */
+    createNavigationContext() {
+        return {
+            // State access
+            getCurrentPath: () => this.routerState().path,
+            getCurrentMatch: () => this.routerState().match,
+            // State mutation
+            updateState: async (updates) => await this.updateRouterState(updates),
+            // Router configuration
+            config: this.config,
+            routes: this.routes,
+            routePatterns: this.routePatterns,
+            // Feature hooks (delegating to FeatureCoordinator)
+            onLoadGuards: (pattern) => this.features.loadGuards(pattern, this.routes),
+            onExecuteGuards: (guards, context) => this.features.executeGuards(guards, context),
+            onExecuteLoaders: (pattern, context) => this.features.executeLoaders(pattern, {
+                ...context,
+                updateRouterState: (updates) => this.updateRouterState(updates),
+            }, this.routes),
+            onShowLoadingUI: async (route, match, navId, _source) => {
+                const loadingPolicy = this.config.loadingPolicy || 'replace';
+                await this.features.showLoadingUI(route, match, navId, this.mountedElement, loadingPolicy, this.routes);
+            },
+            onClearLoadingUI: () => this.features.clearLoadingUI(),
+            onSaveScrollToHistory: () => this.saveScrollToHistory(),
+            onRestoreSnapshotIfEmpty: () => this.restoreSnapshotIfEmpty(),
+            // History management hooks
+            onHistoryPush: (state, url) => this.historyManager.push(state, url),
+            onHistoryReplace: (state, url) => this.historyManager.replace(state, url),
+            onHistorySnapBack: () => this.historyManager.snapBack(),
+            // Path utilities
+            normalizePath: (path) => this.normalizePath(path),
+            parseQueryParams: (search) => this.parseQueryParams(search),
+            findMatch: (pathname) => findBestMatch(pathname, this.routePatterns, this.config),
+        };
+    }
+}
+/** @codexApi {"parent":"pithy.router.core","name":"createRouter","stability":"stable","signature":"(routes: RouteNode[], config?: RouterConfig) => Router","description":"Create a router instance with HMR hot-singleton reuse"} */
+/**
+ * Create a new router instance with HMR hot-singleton pattern
+ *
+ * In development with HMR enabled, this function reuses the same router instance
+ * across module updates, preserving router state and avoiding duplicate instances.
+ *
+ * @param routes - Route tree from virtual:pithy/routes.gen
+ * @param config - Router configuration options
+ * @returns Router instance (may be existing instance if HMR is active)
+ */
+export function createRouter(routes, config) {
+    const HOT_KEY = '__pithy_router_singleton__';
+    // Check for existing router instance in HMR data (hot-singleton pattern)
+    const hot = import.meta.hot;
+    if (typeof hot !== 'undefined') {
+        const existingRouter = hot.data?.[HOT_KEY];
+        if (existingRouter) {
+            // Reuse existing router instance across HMR updates
+            return existingRouter;
+        }
+        // Create new router and persist it for future HMR updates
+        const router = new Router(routes, config);
+        // Persist router instance across HMR updates
+        hot.dispose((data) => {
+            data[HOT_KEY] = router;
+        });
+        return router;
+    }
+    // No HMR available, create normal instance
+    return new Router(routes, config);
+}
+//# sourceMappingURL=router.js.map