@pithyjs/router 0.1.0-beta.0

package/dist/router/core/utils.js

@@ -0,0 +1,152 @@
+/** @codex
+{
+  "id": "pithy.router.core.utils",
+  "title": "Router Utility Functions",
+  "category": "runtime"
+}
+*/
+/**
+ * Extract HTMLElement from various value types
+ * Supports: HTMLElement, DocumentFragment, { el: ... }, HTML string
+ *
+ * @param value - Value that may contain an element
+ * @returns HTMLElement or null if extraction failed
+ *
+ * @codexApi {"parent":"pithy.router.core.utils","name":"extractElement","stability":"stable","signature":"function extractElement(value: any): HTMLElement | null"}
+ */
+export function extractElement(value) {
+    if (!value)
+        return null;
+    const wrapFragment = (frag) => {
+        const wrapper = document.createElement('div');
+        // clone so callers can reuse their fragment
+        wrapper.appendChild(frag.cloneNode(true));
+        return wrapper;
+    };
+    // Direct HTMLElement
+    if (value instanceof HTMLElement) {
+        return value;
+    }
+    // Direct DocumentFragment
+    if (value instanceof DocumentFragment) {
+        return wrapFragment(value);
+    }
+    // { el: ... } shape
+    if (typeof value === 'object' && 'el' in value && value.el) {
+        const el = value.el;
+        if (el instanceof HTMLElement)
+            return el;
+        if (el instanceof DocumentFragment)
+            return wrapFragment(el);
+    }
+    // HTML string
+    if (typeof value === 'string') {
+        const wrapper = document.createElement('div');
+        wrapper.innerHTML = value;
+        return wrapper;
+    }
+    return null;
+}
+/**
+ * Generate a CSS selector for an element
+ * Used for scroll position restoration
+ *
+ * Priority:
+ * 1. data-remember-scroll-id attribute
+ * 2. element ID (#id)
+ * 3. data-remember-scroll attribute value
+ * 4. fallback to [data-remember-scroll]
+ *
+ * @param el - The element to generate a selector for
+ * @returns CSS selector string
+ *
+ * @codexApi {"parent":"pithy.router.core.utils","name":"selectorFor","stability":"stable","signature":"function selectorFor(el: HTMLElement): string"}
+ */
+export function selectorFor(el) {
+    return (el.getAttribute('data-remember-scroll-id') ||
+        (el.id && `#${CSS.escape(el.id)}`) ||
+        (el.dataset.rememberScroll &&
+            `[data-remember-scroll="${el.dataset.rememberScroll}"]`) ||
+        '[data-remember-scroll]');
+}
+/**
+ * Combine multiple abort signals into one
+ * Returns a signal that aborts when any of the input signals abort
+ *
+ * @param signals - Array of AbortSignals to combine
+ * @returns Combined AbortSignal
+ *
+ * @codexApi {"parent":"pithy.router.core.utils","name":"combineAbortSignals","stability":"stable","signature":"function combineAbortSignals(signals: AbortSignal[]): AbortSignal"}
+ */
+export function combineAbortSignals(signals) {
+    const controller = new AbortController();
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort();
+            break;
+        }
+        signal.addEventListener('abort', () => {
+            controller.abort();
+        }, { once: true });
+    }
+    return controller.signal;
+}
+/**
+ * Check if a mouse event should be handled for navigation
+ * Filters out modified clicks (ctrl, meta, shift, alt) and non-left clicks
+ *
+ * @param event - MouseEvent to check
+ * @returns true if the event should trigger navigation
+ *
+ * @codexApi {"parent":"pithy.router.core.utils","name":"isNavigationClick","stability":"stable","signature":"function isNavigationClick(event: MouseEvent): boolean"}
+ */
+export function isNavigationClick(event) {
+    // Only left clicks without modifier keys
+    return (event.button === 0 &&
+        !event.metaKey &&
+        !event.ctrlKey &&
+        !event.shiftKey &&
+        !event.altKey);
+}
+/**
+ * Check if an anchor element should be intercepted for client-side navigation
+ * Returns null if the link should not be intercepted (let browser handle)
+ * Returns the normalized href if it should be intercepted
+ *
+ * @param anchor - Anchor element to check
+ * @param basePath - Optional base path to strip from URLs
+ * @returns Normalized href string or null
+ *
+ * @codexApi {"parent":"pithy.router.core.utils","name":"shouldInterceptLink","stability":"stable","signature":"function shouldInterceptLink(anchor: HTMLAnchorElement, basePath?: string): string | null"}
+ */
+export function shouldInterceptLink(anchor, basePath) {
+    // Check target attribute
+    if (anchor.target && anchor.target !== '_self')
+        return null;
+    // Check download attribute
+    if (anchor.hasAttribute('download'))
+        return null;
+    // Get raw href
+    const rawHref = anchor.getAttribute('href');
+    if (!rawHref || rawHref.startsWith('#'))
+        return null;
+    // Parse and validate URL
+    let url;
+    try {
+        url = new URL(rawHref, window.location.origin);
+    }
+    catch {
+        return null; // Invalid URL, let browser handle
+    }
+    // Check if same-origin
+    if (url.origin !== window.location.origin)
+        return null;
+    // Normalize path by stripping base path if provided
+    let pathname = url.pathname;
+    if (basePath) {
+        pathname = pathname.replace(new RegExp(`^${basePath}`), '');
+    }
+    // Return full href including search and hash
+    return pathname + url.search + url.hash;
+}
+//# sourceMappingURL=utils.js.map

package/dist/router/core/utils.js.map

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

package/dist/router/features/coordinator.d.ts

@@ -0,0 +1,75 @@
+/** @codex
+{
+  "id": "pithy.router.features.coordinator",
+  "title": "Feature Coordinator - Orchestrates Guards, Loaders, Loading UI, and UX Features",
+  "category": "runtime"
+}
+*/
+import { type RouteNode, type RouteMatch, type NavigationId, type RouterConfig, type GuardContext as BaseGuardContext, type LoaderContext as BaseLoaderContext, type GuardExecutionResult, type ResourceState } from '../core/types';
+import { type GuardFunction } from './guards';
+import { LoadingUIManager } from './loading-ui-manager';
+export type GuardContext = BaseGuardContext;
+/**
+ * Router state updates type
+ * Partial type to avoid circular dependency with RouterState from router.ts
+ */
+export interface RouterStateUpdates {
+    loaderData?: ResourceState;
+}
+/**
+ * Loader context for loader execution (extends base with router state update)
+ */
+export interface LoaderContext extends BaseLoaderContext {
+    updateRouterState?: (updates: RouterStateUpdates) => void;
+}
+/**
+ * Feature Coordinator
+ * Orchestrates guards, loaders, loading UI, scroll, focus, HMR, and history
+ *
+ * @codexApi {"parent":"pithy.router.features.coordinator","name":"FeatureCoordinator","stability":"stable","signature":"class FeatureCoordinator"}
+ */
+export declare class FeatureCoordinator {
+    private guardManager;
+    private loadingUI;
+    constructor(_config: RouterConfig);
+    /**
+     * Get the loading UI manager
+     * Allows external access for router to set mounted element
+     */
+    getLoadingUI(): LoadingUIManager;
+    /**
+     * Load guards for a specific route pattern
+     * Dynamically imports the route config and extracts guards
+     *
+     * @codexApi {"parent":"pithy.router.features.coordinator","name":"loadGuards","stability":"stable","signature":"async loadGuards(pattern: string, routes: RouteNode[]): Promise<GuardFunction[]>"}
+     */
+    loadGuards(pattern: string, routes: RouteNode[]): Promise<GuardFunction[]>;
+    /**
+     * Execute guards for a route
+     * Returns guard result with allowed status and optional redirect
+     *
+     * @codexApi {"parent":"pithy.router.features.coordinator","name":"executeGuards","stability":"stable","signature":"async executeGuards(guards: GuardFunction[], context: GuardContext): Promise<GuardExecutionResult>"}
+     */
+    executeGuards(guards: GuardFunction[], context: GuardContext): Promise<GuardExecutionResult>;
+    /**
+     * Execute loaders for a route with caching, error handling, and state updates
+     * This is the COMPLETE implementation that handles everything
+     *
+     * @codexApi {"parent":"pithy.router.features.coordinator","name":"executeLoaders","stability":"stable","signature":"async executeLoaders(pattern: string, context: LoaderContext, routes: RouteNode[]): Promise<boolean>"}
+     */
+    executeLoaders(pattern: string, context: LoaderContext, routes: RouteNode[]): Promise<boolean>;
+    /**
+     * Show loading UI based on policy and route configuration
+     * Encapsulates the loading policy logic (replace vs overlay) and checks if route has loader
+     *
+     * @codexApi {"parent":"pithy.router.features.coordinator","name":"showLoadingUI","stability":"stable","signature":"async showLoadingUI(route: RouteNode | undefined, match: RouteMatch, navId: NavigationId, mountedElement: HTMLElement | null, loadingPolicy: string, routes: RouteNode[]): Promise<void>"}
+     */
+    showLoadingUI(route: RouteNode | undefined, match: RouteMatch, navId: NavigationId, mountedElement: HTMLElement | null, loadingPolicy: string, routes: RouteNode[]): Promise<void>;
+    /**
+     * Clear all loading UI
+     *
+     * @codexApi {"parent":"pithy.router.features.coordinator","name":"clearLoadingUI","stability":"stable","signature":"clearLoadingUI(): void"}
+     */
+    clearLoadingUI(): void;
+}
+//# sourceMappingURL=coordinator.d.ts.map

package/dist/router/features/coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../../src/router/features/coordinator.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EAEjB,KAAK,YAAY,IAAI,gBAAgB,EACrC,KAAK,aAAa,IAAI,iBAAiB,EACvC,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAM5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AASxD,MAAM,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAE5C;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,aAAa,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,CAAC;CAC3D;AAED;;;;;GAKG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,SAAS,CAAmB;gBAExB,OAAO,EAAE,YAAY;IAKjC;;;OAGG;IACH,YAAY,IAAI,gBAAgB;IAIhC;;;;;OAKG;IACG,UAAU,CACd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,EAAE,GAClB,OAAO,CAAC,aAAa,EAAE,CAAC;IA4B3B;;;;;OAKG;IACG,aAAa,CACjB,MAAM,EAAE,aAAa,EAAE,EACvB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,oBAAoB,CAAC;IAIhC;;;;;OAKG;IACG,cAAc,CAClB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,SAAS,EAAE,GAClB,OAAO,CAAC,OAAO,CAAC;IAqInB;;;;;OAKG;IACG,aAAa,CACjB,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,YAAY,EACnB,cAAc,EAAE,WAAW,GAAG,IAAI,EAClC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,SAAS,EAAE,GAClB,OAAO,CAAC,IAAI,CAAC;IAwBhB;;;;OAIG;IACH,cAAc,IAAI,IAAI;CAGvB"}

package/dist/router/features/coordinator.js

@@ -0,0 +1,203 @@
+/** @codex
+{
+  "id": "pithy.router.features.coordinator",
+  "title": "Feature Coordinator - Orchestrates Guards, Loaders, Loading UI, and UX Features",
+  "category": "runtime"
+}
+*/
+import { LOADER_FAILED, } from '../core/types';
+import { LOADER_DEFAULTS } from '../core/constants';
+import { GuardManager } from './guards';
+import { executeRouteLoader, } from './loaders';
+import { LoadingUIManager } from './loading-ui-manager';
+import { RouterError, RouterErrorCode, setRouteError, clearRouteError, } from './errors';
+/**
+ * Feature Coordinator
+ * Orchestrates guards, loaders, loading UI, scroll, focus, HMR, and history
+ *
+ * @codexApi {"parent":"pithy.router.features.coordinator","name":"FeatureCoordinator","stability":"stable","signature":"class FeatureCoordinator"}
+ */
+export class FeatureCoordinator {
+    constructor(_config) {
+        this.guardManager = new GuardManager();
+        this.loadingUI = new LoadingUIManager();
+    }
+    /**
+     * Get the loading UI manager
+     * Allows external access for router to set mounted element
+     */
+    getLoadingUI() {
+        return this.loadingUI;
+    }
+    /**
+     * Load guards for a specific route pattern
+     * Dynamically imports the route config and extracts guards
+     *
+     * @codexApi {"parent":"pithy.router.features.coordinator","name":"loadGuards","stability":"stable","signature":"async loadGuards(pattern: string, routes: RouteNode[]): Promise<GuardFunction[]>"}
+     */
+    async loadGuards(pattern, routes) {
+        // Find the route node for this pattern
+        const route = routes.find(r => r.pattern === pattern);
+        if (!route || !route.imports.config) {
+            return []; // No config file, no guards
+        }
+        try {
+            // Dynamically import the route config
+            const configModule = await route.imports.config();
+            // Extract guards from the config module
+            if (configModule &&
+                configModule.guards &&
+                Array.isArray(configModule.guards)) {
+                return configModule.guards;
+            }
+            return [];
+        }
+        catch (error) {
+            console.error(`[Router] Failed to load guards for ${pattern}:`, error);
+            return [];
+        }
+    }
+    /**
+     * Execute guards for a route
+     * Returns guard result with allowed status and optional redirect
+     *
+     * @codexApi {"parent":"pithy.router.features.coordinator","name":"executeGuards","stability":"stable","signature":"async executeGuards(guards: GuardFunction[], context: GuardContext): Promise<GuardExecutionResult>"}
+     */
+    async executeGuards(guards, context) {
+        return this.guardManager.executeGuards(guards, context);
+    }
+    /**
+     * Execute loaders for a route with caching, error handling, and state updates
+     * This is the COMPLETE implementation that handles everything
+     *
+     * @codexApi {"parent":"pithy.router.features.coordinator","name":"executeLoaders","stability":"stable","signature":"async executeLoaders(pattern: string, context: LoaderContext, routes: RouteNode[]): Promise<boolean>"}
+     */
+    async executeLoaders(pattern, context, routes) {
+        const route = routes.find(r => r.pattern === pattern);
+        if (!route || !route.imports.loader) {
+            return true; // No loader file = success (nothing to fail)
+        }
+        try {
+            // Dynamically import the loader module
+            const loaderModule = await route.imports.loader();
+            // Extract loader function from the module
+            const loaderExport = loaderModule.loader || loaderModule.default;
+            if (typeof loaderExport !== 'function') {
+                return true; // No valid loader = success (nothing to fail)
+            }
+            const loaderFunction = loaderExport;
+            // Load route config to get cache options
+            let cacheOptions = {
+                strategy: 'swr',
+                ttl: LOADER_DEFAULTS.CACHE_TTL,
+            };
+            if (route.imports.config) {
+                try {
+                    const configModule = await route.imports.config();
+                    const routeCache = configModule?.cache;
+                    if (routeCache && typeof routeCache === 'object') {
+                        const cache = routeCache;
+                        // Merge route cache config with defaults
+                        cacheOptions = {
+                            strategy: cache.strategy || cacheOptions.strategy,
+                            ttl: cache.ttl || cacheOptions.ttl,
+                        };
+                    }
+                }
+                catch {
+                    // Use defaults if config loading fails
+                }
+            }
+            // Execute the loader with caching and error handling
+            try {
+                const result = await executeRouteLoader(route.id, loaderFunction, {
+                    params: context.params,
+                    query: context.query,
+                    signal: context.signal,
+                    navId: context.navId,
+                }, cacheOptions);
+                // Don't treat abort as error
+                if (context.signal.aborted) {
+                    return false;
+                }
+                // Check for LOADER_FAILED sentinel
+                if (result === LOADER_FAILED) {
+                    const err = new RouterError('Loader failed', {
+                        navId: String(context.navId),
+                        routeId: route.id,
+                        parentRouteId: undefined,
+                        routePath: route.pattern,
+                        ts: Date.now(),
+                    }, undefined, RouterErrorCode.LOADER_FAILED_SENTINEL);
+                    setRouteError(route.id, err);
+                    return false;
+                }
+                // Success: clear any previous error
+                clearRouteError(route.id);
+                // Update router state with the loaded data (if callback provided)
+                if (context.updateRouterState) {
+                    context.updateRouterState({
+                        loaderData: {
+                            status: 'ready',
+                            data: result,
+                            navId: context.navId,
+                            loadedAt: Date.now(),
+                        },
+                    });
+                }
+                return true;
+            }
+            catch (cause) {
+                // Don't treat abort as error
+                if (context.signal.aborted) {
+                    return false;
+                }
+                console.error('[Router] Loader failed:', cause);
+                // Create and set error
+                const err = cause instanceof RouterError
+                    ? cause
+                    : new RouterError(cause?.message ?? 'Loader failed', {
+                        navId: String(context.navId),
+                        routeId: route.id,
+                        parentRouteId: undefined,
+                        routePath: route.pattern,
+                        ts: Date.now(),
+                    }, cause, RouterErrorCode.LOADER_EXECUTION_ERROR);
+                setRouteError(route.id, err);
+                return false;
+            }
+        }
+        catch (error) {
+            console.error('[Router] Failed to load loader module:', error);
+            return false;
+        }
+    }
+    /**
+     * Show loading UI based on policy and route configuration
+     * Encapsulates the loading policy logic (replace vs overlay) and checks if route has loader
+     *
+     * @codexApi {"parent":"pithy.router.features.coordinator","name":"showLoadingUI","stability":"stable","signature":"async showLoadingUI(route: RouteNode | undefined, match: RouteMatch, navId: NavigationId, mountedElement: HTMLElement | null, loadingPolicy: string, routes: RouteNode[]): Promise<void>"}
+     */
+    async showLoadingUI(route, match, navId, mountedElement, loadingPolicy, routes) {
+        if (!mountedElement)
+            return;
+        const hasLoader = !!route?.imports.loader;
+        if (hasLoader) {
+            if (loadingPolicy === 'replace') {
+                await this.loadingUI.showAtomic(match.pattern, navId, mountedElement, routes);
+            }
+            else if (loadingPolicy === 'overlay') {
+                await this.loadingUI.showCustomOverlay(match.pattern, navId, mountedElement, routes);
+            }
+        }
+    }
+    /**
+     * Clear all loading UI
+     *
+     * @codexApi {"parent":"pithy.router.features.coordinator","name":"clearLoadingUI","stability":"stable","signature":"clearLoadingUI(): void"}
+     */
+    clearLoadingUI() {
+        this.loadingUI.clearAll();
+    }
+}
+//# sourceMappingURL=coordinator.js.map

package/dist/router/features/coordinator.js.map

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

package/dist/router/features/errors/error-codes.d.ts

@@ -0,0 +1,107 @@
+/** @codex
+{
+  "id": "pithy.router.error-codes",
+  "title": "Router Error Code Taxonomy",
+  "category": "types"
+}
+*/
+/** @codexApi {"parent":"pithy.router.error-codes","name":"RouterErrorCode","stability":"stable","signature":"enum RouterErrorCode"} */
+/**
+ * Canonical error codes for router errors
+ * Provides deterministic error categorization and handling
+ */
+export declare enum RouterErrorCode {
+    /** Loader function threw an error */
+    LOADER_EXECUTION_ERROR = "LOADER_EXECUTION_ERROR",
+    /** Loader timed out */
+    LOADER_TIMEOUT = "LOADER_TIMEOUT",
+    /** Loader was aborted/cancelled */
+    LOADER_ABORTED = "LOADER_ABORTED",
+    /** Loader returned LOADER_FAILED sentinel */
+    LOADER_FAILED_SENTINEL = "LOADER_FAILED_SENTINEL",
+    /** Guard function threw an error */
+    GUARD_EXECUTION_ERROR = "GUARD_EXECUTION_ERROR",
+    /** Guard timed out */
+    GUARD_TIMEOUT = "GUARD_TIMEOUT",
+    /** Guard was aborted/cancelled */
+    GUARD_ABORTED = "GUARD_ABORTED",
+    /** Guard denied navigation (returned false) */
+    GUARD_DENIED = "GUARD_DENIED",
+    /** Component factory function threw error */
+    COMPONENT_FACTORY_ERROR = "COMPONENT_FACTORY_ERROR",
+    /** Component render threw error */
+    COMPONENT_RENDER_ERROR = "COMPONENT_RENDER_ERROR",
+    /** Component module failed to load */
+    COMPONENT_LOAD_ERROR = "COMPONENT_LOAD_ERROR",
+    /** Component lifecycle hook threw error */
+    COMPONENT_LIFECYCLE_ERROR = "COMPONENT_LIFECYCLE_ERROR",
+    /** Route not found for path */
+    ROUTE_NOT_FOUND = "ROUTE_NOT_FOUND",
+    /** Navigation was aborted */
+    NAVIGATION_ABORTED = "NAVIGATION_ABORTED",
+    /** Navigation was superseded by another navigation */
+    NAVIGATION_SUPERSEDED = "NAVIGATION_SUPERSEDED",
+    /** Circular redirect detected */
+    CIRCULAR_REDIRECT = "CIRCULAR_REDIRECT",
+    /** Error boundary component failed to load */
+    ERROR_BOUNDARY_LOAD_ERROR = "ERROR_BOUNDARY_LOAD_ERROR",
+    /** Error boundary component threw error during render */
+    ERROR_BOUNDARY_RENDER_ERROR = "ERROR_BOUNDARY_RENDER_ERROR",
+    /** Unknown error with no specific categorization */
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+/** @codexApi {"parent":"pithy.router.error-codes","name":"ErrorSeverity","stability":"stable","signature":"enum ErrorSeverity"} */
+/**
+ * Error severity levels for prioritization and handling
+ */
+export declare enum ErrorSeverity {
+    /** Critical error - requires immediate attention, blocks navigation */
+    CRITICAL = "critical",
+    /** Error - navigation failed but recoverable */
+    ERROR = "error",
+    /** Warning - operation completed with issues */
+    WARNING = "warning",
+    /** Info - informational message about navigation state */
+    INFO = "info"
+}
+/** @codexApi {"parent":"pithy.router.error-codes","name":"ErrorRecoveryStrategy","stability":"stable","signature":"enum ErrorRecoveryStrategy"} */
+/**
+ * Error recovery strategies for different error types
+ */
+export declare enum ErrorRecoveryStrategy {
+    /** Show error UI with retry button */
+    SHOW_ERROR_UI = "show-error-ui",
+    /** Redirect to fallback route */
+    REDIRECT_FALLBACK = "redirect-fallback",
+    /** Silent fail - log error but don't show UI */
+    SILENT_FAIL = "silent-fail",
+    /** Retry operation automatically */
+    AUTO_RETRY = "auto-retry",
+    /** Throw to parent error boundary */
+    BUBBLE_UP = "bubble-up"
+}
+/**
+ * Metadata for each error code including severity and recovery strategy
+ */
+interface ErrorCodeMetadata {
+    code: RouterErrorCode;
+    severity: ErrorSeverity;
+    defaultStrategy: ErrorRecoveryStrategy;
+    userMessage: string;
+    retryable: boolean;
+}
+/** @codexApi {"parent":"pithy.router.error-codes","name":"ERROR_TAXONOMY","stability":"stable","signature":"Record<RouterErrorCode, ErrorCodeMetadata>"} */
+/**
+ * Complete error taxonomy with metadata for each error code
+ * Maps error codes to their handling characteristics
+ */
+export declare const ERROR_TAXONOMY: Record<RouterErrorCode, ErrorCodeMetadata>;
+/** @codexApi {"parent":"pithy.router.error-codes","name":"getErrorMetadata","stability":"stable","signature":"(code: RouterErrorCode) => ErrorCodeMetadata"} */
+/**
+ * Get error metadata for a specific error code
+ * Provides severity, recovery strategy, and user message
+ * Used internally by RouterError instance methods
+ */
+export declare function getErrorMetadata(code: RouterErrorCode): ErrorCodeMetadata;
+export {};
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/router/features/errors/error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../../../../src/router/features/errors/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,uIAAuI;AACvI;;;GAGG;AACH,oBAAY,eAAe;IAEzB,qCAAqC;IACrC,sBAAsB,2BAA2B;IACjD,uBAAuB;IACvB,cAAc,mBAAmB;IACjC,mCAAmC;IACnC,cAAc,mBAAmB;IACjC,6CAA6C;IAC7C,sBAAsB,2BAA2B;IAGjD,oCAAoC;IACpC,qBAAqB,0BAA0B;IAC/C,sBAAsB;IACtB,aAAa,kBAAkB;IAC/B,kCAAkC;IAClC,aAAa,kBAAkB;IAC/B,+CAA+C;IAC/C,YAAY,iBAAiB;IAG7B,6CAA6C;IAC7C,uBAAuB,4BAA4B;IACnD,mCAAmC;IACnC,sBAAsB,2BAA2B;IACjD,sCAAsC;IACtC,oBAAoB,yBAAyB;IAC7C,2CAA2C;IAC3C,yBAAyB,8BAA8B;IAGvD,+BAA+B;IAC/B,eAAe,oBAAoB;IACnC,6BAA6B;IAC7B,kBAAkB,uBAAuB;IACzC,sDAAsD;IACtD,qBAAqB,0BAA0B;IAC/C,iCAAiC;IACjC,iBAAiB,sBAAsB;IAGvC,8CAA8C;IAC9C,yBAAyB,8BAA8B;IACvD,yDAAyD;IACzD,2BAA2B,gCAAgC;IAG3D,oDAAoD;IACpD,aAAa,kBAAkB;CAChC;AAED,mIAAmI;AACnI;;GAEG;AACH,oBAAY,aAAa;IACvB,uEAAuE;IACvE,QAAQ,aAAa;IACrB,gDAAgD;IAChD,KAAK,UAAU;IACf,gDAAgD;IAChD,OAAO,YAAY;IACnB,0DAA0D;IAC1D,IAAI,SAAS;CACd;AAED,mJAAmJ;AACnJ;;GAEG;AACH,oBAAY,qBAAqB;IAC/B,sCAAsC;IACtC,aAAa,kBAAkB;IAC/B,iCAAiC;IACjC,iBAAiB,sBAAsB;IACvC,gDAAgD;IAChD,WAAW,gBAAgB;IAC3B,oCAAoC;IACpC,UAAU,eAAe;IACzB,qCAAqC;IACrC,SAAS,cAAc;CACxB;AAED;;GAEG;AACH,UAAU,iBAAiB;IACzB,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,EAAE,aAAa,CAAC;IACxB,eAAe,EAAE,qBAAqB,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,4JAA4J;AAC5J;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,eAAe,EAAE,iBAAiB,CAiJrE,CAAC;AAEF,gKAAgK;AAChK;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAEzE"}