@pithyjs/router 0.1.0-beta.0

package/dist/router/features/loading-ui-manager.js

@@ -0,0 +1,209 @@
+/** @codex
+{
+  "id": "pithy.router.features.loading-ui",
+  "title": "Loading UI Manager - Atomic Swap and Overlay Loading States",
+  "category": "runtime"
+}
+*/
+import { extractElement } from '../core/utils';
+import { LOADING_UI } from '../core/constants';
+import { loadRouteModule, getRouteModuleKey } from './module-loader';
+/**
+ * Loading UI Manager
+ * Handles atomic swap, overlay, and progress-only loading policies
+ *
+ * Supports two loading strategies:
+ * 1. Atomic Swap - Replace entire outlet content with loading UI
+ * 2. Overlay - Show loading UI on top of existing content
+ *
+ * @codexApi {"parent":"pithy.router.features.loading-ui","name":"LoadingUIManager","stability":"stable","signature":"class LoadingUIManager"}
+ */
+export class LoadingUIManager {
+    constructor() {
+        this.outletSnapshot = null;
+        this.mountedElement = null;
+    }
+    /**
+     * Set the mounted element (outlet)
+     */
+    setMountedElement(element) {
+        this.mountedElement = element;
+    }
+    /**
+     * Show atomic loading UI (replace outlet content)
+     * Creates a container with router-loading-atomic class that replaces all outlet content
+     *
+     * @codexApi {"parent":"pithy.router.features.loading-ui","name":"showAtomic","stability":"stable","signature":"async showAtomic(pattern: string, navId: NavigationId, outlet: HTMLElement, routes: RouteNode[]): Promise<void>"}
+     */
+    async showAtomic(pattern, navId, outlet, routes) {
+        // Resolve route-specific loading content or fall back to default
+        const contentEl = await this.buildForRoute(pattern, routes);
+        // Wrap the content in a removable atomic container (ALWAYS)
+        const container = document.createElement('div');
+        container.className = 'router-loading-atomic';
+        container.setAttribute('data-nav-id', navId.toString());
+        container.appendChild(contentEl);
+        // Atomic replace: no intermediate empty state
+        // Don't use View Transition for loading UI to prevent spinner from getting stuck
+        const frag = document.createDocumentFragment();
+        frag.appendChild(container);
+        outlet.replaceChildren(frag);
+    }
+    /**
+     * Show custom overlay loading UI with route-specific content
+     *
+     * @codexApi {"parent":"pithy.router.features.loading-ui","name":"showCustomOverlay","stability":"stable","signature":"async showCustomOverlay(pattern: string, navId: NavigationId, outlet: HTMLElement, routes: RouteNode[]): Promise<void>"}
+     */
+    async showCustomOverlay(pattern, navId, outlet, routes) {
+        // Resolve route-specific loading content or default
+        const content = await this.buildForRoute(pattern, routes);
+        this.mountOverlay(outlet, navId, content, true);
+    }
+    /**
+     * Internal helper to mount an overlay with content
+     * Consolidates overlay creation logic
+     */
+    mountOverlay(outlet, navId, content, isCustom) {
+        // Make outlet a positioning context
+        if (!outlet.style.position || outlet.style.position === 'static') {
+            outlet.style.position = 'relative';
+        }
+        // Remove any previous overlay for safety
+        this.removeOverlay(outlet);
+        const overlay = document.createElement('div');
+        overlay.className = isCustom
+            ? 'router-loading-overlay router-loading-overlay--custom'
+            : 'router-loading-overlay';
+        overlay.setAttribute('data-nav-id', String(navId));
+        // Base styles for all overlays
+        Object.assign(overlay.style, {
+            position: 'absolute',
+            inset: '0',
+            display: 'flex',
+            justifyContent: 'center',
+            alignItems: 'center',
+            zIndex: String(LOADING_UI.OVERLAY_Z_INDEX),
+            pointerEvents: 'none',
+        });
+        // Add background for default overlay only
+        if (!isCustom) {
+            Object.assign(overlay.style, {
+                backgroundColor: 'rgba(255, 255, 255, 0.9)',
+                backdropFilter: 'blur(2px)',
+            });
+        }
+        overlay.appendChild(content);
+        outlet.appendChild(overlay);
+    }
+    /**
+     * Remove loading overlay from outlet
+     *
+     * @codexApi {"parent":"pithy.router.features.loading-ui","name":"removeOverlay","stability":"stable","signature":"removeOverlay(outlet: HTMLElement): void"}
+     */
+    removeOverlay(outlet) {
+        const overlays = outlet.querySelectorAll('.router-loading-overlay');
+        overlays.forEach(overlay => {
+            overlay.remove();
+        });
+    }
+    /**
+     * Clear all loading UI from outlet (handles both overlays and atomic swap loading)
+     *
+     * @codexApi {"parent":"pithy.router.features.loading-ui","name":"clearAll","stability":"stable","signature":"clearAll(): void"}
+     */
+    clearAll() {
+        if (!this.mountedElement)
+            return;
+        // Remove overlay-style loading UI
+        this.removeOverlay(this.mountedElement);
+        // Remove atomic swap loading UI (elements with router-loading-atomic class)
+        const atomicLoadingElements = this.mountedElement.querySelectorAll('.router-loading-atomic');
+        atomicLoadingElements.forEach(element => {
+            element.remove();
+        });
+        // If outlet is now empty after clearing loading UI, restore snapshot
+        if (this.mountedElement.children.length === 0 && this.outletSnapshot) {
+            this.mountedElement.appendChild(this.outletSnapshot.cloneNode(true));
+        }
+    }
+    /**
+     * Build default loading content (spinner + "Loading..." text)
+     *
+     * @codexApi {"parent":"pithy.router.features.loading-ui","name":"buildDefault","stability":"stable","signature":"buildDefault(): HTMLElement"}
+     */
+    buildDefault() {
+        const wrap = document.createElement('div');
+        wrap.className = 'router-loading-content';
+        wrap.innerHTML = `
+      <div class="spinner"></div>
+      <p>Loading…</p>
+      <style>
+        .router-loading-content {
+          text-align: center;
+          background: white;
+          padding: 2rem;
+          border-radius: 8px;
+          box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+        }
+        .spinner {
+          width: ${LOADING_UI.SPINNER_SIZE}px;
+          height: ${LOADING_UI.SPINNER_SIZE}px;
+          border: ${LOADING_UI.SPINNER_BORDER}px solid #eee;
+          border-top-color: #3498db;
+          border-radius: 50%;
+          animation: spin 1s linear infinite;
+          margin: 0 auto 0.5rem;
+        }
+        @keyframes spin {
+          to { transform: rotate(${LOADING_UI.SPINNER_ROTATION}deg) }
+        }
+      </style>
+    `;
+        return wrap;
+    }
+    /**
+     * Build loading content for a specific route (supports many export shapes)
+     *
+     * @codexApi {"parent":"pithy.router.features.loading-ui","name":"buildForRoute","stability":"stable","signature":"async buildForRoute(pattern: string, routes: RouteNode[]): Promise<HTMLElement>"}
+     */
+    async buildForRoute(pattern, routes) {
+        const route = routes.find(r => r.pattern === pattern);
+        if (!route || !route.imports.loading) {
+            return this.buildDefault();
+        }
+        try {
+            // Load through shared module cache
+            const mod = await loadRouteModule(getRouteModuleKey(pattern, 'loading'), route.imports.loading);
+            // candidates to inspect
+            const modRecord = mod;
+            const candidates = [
+                modRecord?.default,
+                modRecord?.loading,
+                modRecord?.Loading,
+                mod,
+            ];
+            for (const c of candidates) {
+                if (!c)
+                    continue;
+                // If it's a function, call it (sync or async)
+                if (typeof c === 'function') {
+                    const out = await Promise.resolve(c());
+                    const el = extractElement(out);
+                    if (el)
+                        return el;
+                }
+                // If it's already an element-like or HTML string/object
+                const el = extractElement(c);
+                if (el)
+                    return el;
+            }
+            // Fallback
+            return this.buildDefault();
+        }
+        catch (e) {
+            console.warn('[Router] Failed to load loading component:', e);
+            return this.buildDefault();
+        }
+    }
+}
+//# sourceMappingURL=loading-ui-manager.js.map

package/dist/router/features/loading-ui-manager.js.map

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

package/dist/router/features/module-loader.d.ts

@@ -0,0 +1,50 @@
+/** @codex
+{
+  "id": "pithy.router.module-loader",
+  "title": "Route Module Loader with Shared Cache Integration",
+  "category": "runtime"
+}
+*/
+/**
+ * Module Loader Utility
+ *
+ * Provides integration with @pithyjs/core's shared module cache for route imports.
+ * Falls back to direct imports if core is not available.
+ *
+ * @module router/features/module-loader
+ */
+import { type RouteModuleType } from '../core/constants';
+/** @codexApi {"parent":"pithy.router.module-loader","name":"loadRouteModule","stability":"stable","signature":"<T>(key: string, loader: () => Promise<T>) => Promise<T>"} */
+/**
+ * Load a route module through the shared cache
+ *
+ * @param key - Cache key for deduplication (e.g., "route:/users:page")
+ * @param loader - Dynamic import function
+ * @returns The loaded module
+ */
+export declare function loadRouteModule<T>(key: string, loader: () => Promise<T>): Promise<T>;
+/** @codexApi {"parent":"pithy.router.module-loader","name":"getRouteModuleKey","stability":"stable","signature":"(pattern: string, type: RouteModuleType) => string"} */
+/**
+ * Generate a cache key for a route module
+ *
+ * @param pattern - Route pattern (e.g., "/users/:id")
+ * @param type - Module type ("page", "layout", "loading", "error", "loader")
+ * @returns Cache key (e.g., "route:/users/:id:page")
+ */
+export declare function getRouteModuleKey(pattern: string, type: RouteModuleType): string;
+/** @codexApi {"parent":"pithy.router.module-loader","name":"invalidateAllRouteModules","stability":"stable","signature":"(routes: Array<{ pattern: string }>) => Promise<void>"} */
+/**
+ * Invalidate all route modules for a list of routes (for HMR full refresh)
+ *
+ * @param routes - Array of route nodes to invalidate
+ */
+export declare function invalidateAllRouteModules(routes: Array<{
+    pattern: string;
+}>): Promise<void>;
+/** @codexApi {"parent":"pithy.router.module-loader","name":"clearAllModuleCache","stability":"stable","signature":"() => Promise<void>"} */
+/**
+ * Clear all route modules from the shared cache (for testing)
+ * This clears both the loader cache and the @pithyjs/core module cache
+ */
+export declare function clearAllModuleCache(): Promise<void>;
+//# sourceMappingURL=module-loader.d.ts.map

package/dist/router/features/module-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-loader.d.ts","sourceRoot":"","sources":["../../../src/router/features/module-loader.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF;;;;;;;GAOG;AAEH,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAoC7E,6KAA6K;AAC7K;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAGZ;AAED,yKAAyK;AACzK;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,eAAe,GACpB,MAAM,CAER;AA2BD,oLAAoL;AACpL;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,4IAA4I;AAC5I;;;GAGG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAazD"}

package/dist/router/features/module-loader.js

@@ -0,0 +1,121 @@
+/** @codex
+{
+  "id": "pithy.router.module-loader",
+  "title": "Route Module Loader with Shared Cache Integration",
+  "category": "runtime"
+}
+*/
+/**
+ * Module Loader Utility
+ *
+ * Provides integration with @pithyjs/core's shared module cache for route imports.
+ * Falls back to direct imports if core is not available.
+ *
+ * @module router/features/module-loader
+ */
+import { ROUTE_MODULE_TYPES } from '../core/constants';
+/**
+ * Cached reference to the module loader function
+ */
+let cachedLoader = null;
+/**
+ * Get the module loader function from @pithyjs/core
+ * Caches the result for performance
+ */
+async function getModuleLoader() {
+    if (cachedLoader) {
+        return cachedLoader;
+    }
+    try {
+        const core = await import('@pithyjs/core');
+        if (core.loadModule) {
+            const loader = core.loadModule;
+            cachedLoader = loader;
+            return loader;
+        }
+    }
+    catch {
+        // Core not available
+    }
+    // Fallback: direct import without caching
+    cachedLoader = (_key, loader) => loader();
+    return cachedLoader;
+}
+/** @codexApi {"parent":"pithy.router.module-loader","name":"loadRouteModule","stability":"stable","signature":"<T>(key: string, loader: () => Promise<T>) => Promise<T>"} */
+/**
+ * Load a route module through the shared cache
+ *
+ * @param key - Cache key for deduplication (e.g., "route:/users:page")
+ * @param loader - Dynamic import function
+ * @returns The loaded module
+ */
+export async function loadRouteModule(key, loader) {
+    const moduleLoader = await getModuleLoader();
+    return moduleLoader(key, loader);
+}
+/** @codexApi {"parent":"pithy.router.module-loader","name":"getRouteModuleKey","stability":"stable","signature":"(pattern: string, type: RouteModuleType) => string"} */
+/**
+ * Generate a cache key for a route module
+ *
+ * @param pattern - Route pattern (e.g., "/users/:id")
+ * @param type - Module type ("page", "layout", "loading", "error", "loader")
+ * @returns Cache key (e.g., "route:/users/:id:page")
+ */
+export function getRouteModuleKey(pattern, type) {
+    return `route:${pattern}:${type}`;
+}
+/**
+ * Invalidate a route module in the cache (for HMR)
+ */
+async function invalidateRouteModule(key) {
+    try {
+        const core = await import('@pithyjs/core');
+        if (core.invalidateModule) {
+            return core.invalidateModule(key);
+        }
+    }
+    catch {
+        // Core not available
+    }
+    return false;
+}
+/**
+ * Invalidate all cached modules for a route pattern (for HMR)
+ * Clears page, layout, loading, error, and loader cache entries
+ */
+async function invalidateRouteModules(pattern) {
+    for (const type of ROUTE_MODULE_TYPES) {
+        await invalidateRouteModule(getRouteModuleKey(pattern, type));
+    }
+}
+/** @codexApi {"parent":"pithy.router.module-loader","name":"invalidateAllRouteModules","stability":"stable","signature":"(routes: Array<{ pattern: string }>) => Promise<void>"} */
+/**
+ * Invalidate all route modules for a list of routes (for HMR full refresh)
+ *
+ * @param routes - Array of route nodes to invalidate
+ */
+export async function invalidateAllRouteModules(routes) {
+    for (const route of routes) {
+        await invalidateRouteModules(route.pattern);
+    }
+}
+/** @codexApi {"parent":"pithy.router.module-loader","name":"clearAllModuleCache","stability":"stable","signature":"() => Promise<void>"} */
+/**
+ * Clear all route modules from the shared cache (for testing)
+ * This clears both the loader cache and the @pithyjs/core module cache
+ */
+export async function clearAllModuleCache() {
+    // Reset the local loader cache
+    cachedLoader = null;
+    // Clear the @pithyjs/core module cache if available
+    try {
+        const core = await import('@pithyjs/core');
+        if (core.clearModuleCache) {
+            core.clearModuleCache();
+        }
+    }
+    catch {
+        // Core not available
+    }
+}
+//# sourceMappingURL=module-loader.js.map

package/dist/router/features/module-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-loader.js","sourceRoot":"","sources":["../../../src/router/features/module-loader.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF;;;;;;;GAOG;AAEH,OAAO,EAAE,kBAAkB,EAAwB,MAAM,mBAAmB,CAAC;AAE7E;;GAEG;AACH,IAAI,YAAY,GAEL,IAAI,CAAC;AAEhB;;;GAGG;AACH,KAAK,UAAU,eAAe;IAG5B,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;QAC3C,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;YAC/B,YAAY,GAAG,MAAM,CAAC;YACtB,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,qBAAqB;IACvB,CAAC;IAED,0CAA0C;IAC1C,YAAY,GAAG,CAAC,IAAY,EAAE,MAA8B,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC;IAC1E,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,6KAA6K;AAC7K;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,GAAW,EACX,MAAwB;IAExB,MAAM,YAAY,GAAG,MAAM,eAAe,EAAE,CAAC;IAC7C,OAAO,YAAY,CAAC,GAAG,EAAE,MAAM,CAAe,CAAC;AACjD,CAAC;AAED,yKAAyK;AACzK;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,IAAqB;IAErB,OAAO,SAAS,OAAO,IAAI,IAAI,EAAE,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,qBAAqB,CAAC,GAAW;IAC9C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;QAC3C,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,qBAAqB;IACvB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,sBAAsB,CAAC,OAAe;IACnD,KAAK,MAAM,IAAI,IAAI,kBAAkB,EAAE,CAAC;QACtC,MAAM,qBAAqB,CAAC,iBAAiB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;IAChE,CAAC;AACH,CAAC;AAED,oLAAoL;AACpL;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,MAAkC;IAElC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,sBAAsB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;AACH,CAAC;AAED,4IAA4I;AAC5I;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB;IACvC,+BAA+B;IAC/B,YAAY,GAAG,IAAI,CAAC;IAEpB,oDAAoD;IACpD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;QAC3C,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC1B,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC1B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,qBAAqB;IACvB,CAAC;AACH,CAAC"}

package/dist/router/features/outlet/errors.d.ts

@@ -0,0 +1,24 @@
+/** @codex
+{
+  "id": "pithy.router.outlet.errors",
+  "title": "Outlet Error Boundary System",
+  "category": "runtime"
+}
+*/
+import type { RouteSegmentChain, NavigationId } from '../../core/types';
+import { type RouterError } from '../errors';
+/** @codexApi {"parent":"pithy.router.outlet.errors","name":"buildErrorUI","stability":"experimental","signature":"(segment: RouteSegmentChain, navId: NavigationId, error: any, retryHandler: () => void) => Promise<HTMLElement>"} */
+/**
+ * Build error UI for a route segment
+ * Returns an HTMLElement with error component or global fallback
+ *
+ * Tries to resolve error component from route hierarchy, falls back to global error UI
+ */
+export declare function buildErrorUI(segment: RouteSegmentChain, navId: NavigationId, error: Error & Partial<RouterError>, retryHandler: () => void): Promise<HTMLElement>;
+/** @codexApi {"parent":"pithy.router.outlet.errors","name":"createRetryHandler","stability":"experimental","signature":"() => () => void"} */
+/**
+ * Create a retry handler for route navigation
+ * Simple URL-level refresh for v0
+ */
+export declare function createRetryHandler(): () => void;
+//# sourceMappingURL=errors.d.ts.map

package/dist/router/features/outlet/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/router/features/outlet/errors.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EAEb,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAyB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAEpE,uOAAuO;AACvO;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,EACnC,YAAY,EAAE,MAAM,IAAI,GACvB,OAAO,CAAC,WAAW,CAAC,CAiEtB;AAaD,8IAA8I;AAC9I;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,IAAI,CAM/C"}

package/dist/router/features/outlet/errors.js

@@ -0,0 +1,96 @@
+/** @codex
+{
+  "id": "pithy.router.outlet.errors",
+  "title": "Outlet Error Boundary System",
+  "category": "runtime"
+}
+*/
+import { resolveErrorImport } from '../errors/error-resolution';
+import { GlobalErrorFallback } from '../errors/global-error-fallback';
+import { ErrorRecoveryStrategy } from '../errors';
+/** @codexApi {"parent":"pithy.router.outlet.errors","name":"buildErrorUI","stability":"experimental","signature":"(segment: RouteSegmentChain, navId: NavigationId, error: any, retryHandler: () => void) => Promise<HTMLElement>"} */
+/**
+ * Build error UI for a route segment
+ * Returns an HTMLElement with error component or global fallback
+ *
+ * Tries to resolve error component from route hierarchy, falls back to global error UI
+ */
+export async function buildErrorUI(segment, navId, error, retryHandler) {
+    const { node } = segment;
+    // Check recovery strategy - silent fail errors don't show UI
+    const strategy = error?.getRecoveryStrategy?.();
+    if (strategy === ErrorRecoveryStrategy.SILENT_FAIL) {
+        console.log('[Router] Silent fail - error will not display UI:', error);
+        // Return empty hidden placeholder
+        const placeholder = document.createElement('div');
+        placeholder.style.display = 'none';
+        placeholder.setAttribute('data-silent-error', 'true');
+        return placeholder;
+    }
+    // Build a node-to-segment map for parent lookups
+    // This allows us to traverse the parent chain to find error boundaries
+    const nodeToSegment = new Map();
+    let currentSegment = segment;
+    while (currentSegment) {
+        nodeToSegment.set(currentSegment.node, currentSegment);
+        currentSegment = currentSegment.parent;
+    }
+    // Try to resolve error component from route hierarchy
+    // Walk up the parent chain until we find an error component
+    const errorImport = resolveErrorImport(node, n => {
+        const seg = nodeToSegment.get(n);
+        return seg?.parent?.node;
+    });
+    // If route has error component, use it
+    if (errorImport) {
+        try {
+            const errorModule = (await errorImport());
+            const candidate = errorModule.default ?? errorModule;
+            if (typeof candidate === 'function') {
+                const errorFactory = candidate;
+                const errorInstance = errorFactory({
+                    error,
+                    retry: retryHandler,
+                });
+                if (errorInstance && errorInstance.el) {
+                    return toElement(errorInstance.el);
+                }
+            }
+            else {
+                console.warn('[Router] Route error component default export is not a function; falling back to global error UI.');
+            }
+        }
+        catch (errorLoadError) {
+            console.warn('[Router] Failed to load error component:', errorLoadError);
+            // Fall through to global fallback
+        }
+    }
+    // Use global fallback
+    const fallbackInstance = GlobalErrorFallback({
+        error,
+        retry: retryHandler,
+    });
+    return toElement(fallbackInstance.el);
+}
+// Wrap fragments in a div — appendChild moves the nodes (preserving listeners)
+// so callers that hold the returned element keep a live, non-empty handle.
+function toElement(node) {
+    if (node instanceof DocumentFragment) {
+        const wrapper = document.createElement('div');
+        wrapper.appendChild(node);
+        return wrapper;
+    }
+    return node;
+}
+/** @codexApi {"parent":"pithy.router.outlet.errors","name":"createRetryHandler","stability":"experimental","signature":"() => () => void"} */
+/**
+ * Create a retry handler for route navigation
+ * Simple URL-level refresh for v0
+ */
+export function createRetryHandler() {
+    return () => {
+        const currentUrl = window.location.pathname + window.location.search + window.location.hash;
+        window.location.href = currentUrl;
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/router/features/outlet/errors.js.map

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

package/dist/router/features/outlet/index.d.ts

@@ -0,0 +1,45 @@
+/** @codex
+{
+  "id": "pithy.router.outlet",
+  "title": "Router Outlet Mounting System",
+  "category": "runtime"
+}
+*/
+import type { RouteSegmentChain, NavigationId } from '../../core/types';
+import { type RouterInstance } from './mount';
+/** @codexApi {"parent":"pithy.router.outlet","name":"OutletManager","stability":"experimental","signature":"class OutletManager"} */
+/**
+ * Enhanced outlet mounting system
+ * Implements segment diff mounting with robust outlet resolution
+ * Fixed memory leak with proper two-phase mounting and cleanup
+ */
+export declare class OutletManager {
+    private mountedComponents;
+    private loadingStates;
+    private outletElements;
+    private router;
+    private disposers;
+    /** @codexApi {"parent":"pithy.router.outlet","name":"mountSegments","stability":"experimental","signature":"(segmentChain: RouteSegmentChain[], navId: NavigationId, rootElement: HTMLElement) => Promise<boolean>"} */
+    /**
+     * Mount route segments with two-phase mounting and rollback
+     * Phase 1: Build everything off-DOM, Phase 2: Atomic commit
+     * Only remounts changed segments, preserves parent layouts
+     */
+    mountSegments(segmentChain: RouteSegmentChain[], navId: NavigationId, rootElement: HTMLElement): Promise<boolean>;
+    /** @codexApi {"parent":"pithy.router.outlet","name":"setRouter","stability":"experimental","signature":"(router: RouterInstance) => void"} */
+    /**
+     * Set router instance for navigation checking
+     */
+    setRouter(router: RouterInstance): void;
+    /** @codexApi {"parent":"pithy.router.outlet","name":"dispose","stability":"experimental","signature":"() => void"} */
+    /**
+     * Clean up all mounted components and state
+     */
+    dispose(): void;
+    /**
+     * Generate unique key for outlet element
+     */
+    private getOutletKey;
+}
+export type { RouterInstance };
+//# sourceMappingURL=index.d.ts.map

package/dist/router/features/outlet/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/router/features/outlet/index.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,KAAK,EACV,iBAAiB,EAGjB,YAAY,EACb,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,SAAS,CAAC;AAEjB,qIAAqI;AACrI;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,iBAAiB,CAA6C;IACtE,OAAO,CAAC,aAAa,CAAwC;IAC7D,OAAO,CAAC,cAAc,CAAkC;IACxD,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,SAAS,CAAwC;IAEzD,wNAAwN;IACxN;;;;OAIG;IACG,aAAa,CACjB,YAAY,EAAE,iBAAiB,EAAE,EACjC,KAAK,EAAE,YAAY,EACnB,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,OAAO,CAAC;IAoDnB,8IAA8I;IAC9I;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAIvC,sHAAsH;IACtH;;OAEG;IACH,OAAO,IAAI,IAAI;IAmBf;;OAEG;IACH,OAAO,CAAC,YAAY;CAGrB;AAED,YAAY,EAAE,cAAc,EAAE,CAAC"}