@pithyjs/router 0.1.0-beta.0

package/dist/router/features/errors/error-codes.js

@@ -0,0 +1,247 @@
+/** @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 var RouterErrorCode;
+(function (RouterErrorCode) {
+    // ========== Loader Errors (1xxx) ==========
+    /** Loader function threw an error */
+    RouterErrorCode["LOADER_EXECUTION_ERROR"] = "LOADER_EXECUTION_ERROR";
+    /** Loader timed out */
+    RouterErrorCode["LOADER_TIMEOUT"] = "LOADER_TIMEOUT";
+    /** Loader was aborted/cancelled */
+    RouterErrorCode["LOADER_ABORTED"] = "LOADER_ABORTED";
+    /** Loader returned LOADER_FAILED sentinel */
+    RouterErrorCode["LOADER_FAILED_SENTINEL"] = "LOADER_FAILED_SENTINEL";
+    // ========== Guard Errors (2xxx) ==========
+    /** Guard function threw an error */
+    RouterErrorCode["GUARD_EXECUTION_ERROR"] = "GUARD_EXECUTION_ERROR";
+    /** Guard timed out */
+    RouterErrorCode["GUARD_TIMEOUT"] = "GUARD_TIMEOUT";
+    /** Guard was aborted/cancelled */
+    RouterErrorCode["GUARD_ABORTED"] = "GUARD_ABORTED";
+    /** Guard denied navigation (returned false) */
+    RouterErrorCode["GUARD_DENIED"] = "GUARD_DENIED";
+    // ========== Component Errors (3xxx) ==========
+    /** Component factory function threw error */
+    RouterErrorCode["COMPONENT_FACTORY_ERROR"] = "COMPONENT_FACTORY_ERROR";
+    /** Component render threw error */
+    RouterErrorCode["COMPONENT_RENDER_ERROR"] = "COMPONENT_RENDER_ERROR";
+    /** Component module failed to load */
+    RouterErrorCode["COMPONENT_LOAD_ERROR"] = "COMPONENT_LOAD_ERROR";
+    /** Component lifecycle hook threw error */
+    RouterErrorCode["COMPONENT_LIFECYCLE_ERROR"] = "COMPONENT_LIFECYCLE_ERROR";
+    // ========== Navigation Errors (4xxx) ==========
+    /** Route not found for path */
+    RouterErrorCode["ROUTE_NOT_FOUND"] = "ROUTE_NOT_FOUND";
+    /** Navigation was aborted */
+    RouterErrorCode["NAVIGATION_ABORTED"] = "NAVIGATION_ABORTED";
+    /** Navigation was superseded by another navigation */
+    RouterErrorCode["NAVIGATION_SUPERSEDED"] = "NAVIGATION_SUPERSEDED";
+    /** Circular redirect detected */
+    RouterErrorCode["CIRCULAR_REDIRECT"] = "CIRCULAR_REDIRECT";
+    // ========== Error Boundary Errors (5xxx) ==========
+    /** Error boundary component failed to load */
+    RouterErrorCode["ERROR_BOUNDARY_LOAD_ERROR"] = "ERROR_BOUNDARY_LOAD_ERROR";
+    /** Error boundary component threw error during render */
+    RouterErrorCode["ERROR_BOUNDARY_RENDER_ERROR"] = "ERROR_BOUNDARY_RENDER_ERROR";
+    // ========== Unknown/Generic (9xxx) ==========
+    /** Unknown error with no specific categorization */
+    RouterErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+})(RouterErrorCode || (RouterErrorCode = {}));
+/** @codexApi {"parent":"pithy.router.error-codes","name":"ErrorSeverity","stability":"stable","signature":"enum ErrorSeverity"} */
+/**
+ * Error severity levels for prioritization and handling
+ */
+export var ErrorSeverity;
+(function (ErrorSeverity) {
+    /** Critical error - requires immediate attention, blocks navigation */
+    ErrorSeverity["CRITICAL"] = "critical";
+    /** Error - navigation failed but recoverable */
+    ErrorSeverity["ERROR"] = "error";
+    /** Warning - operation completed with issues */
+    ErrorSeverity["WARNING"] = "warning";
+    /** Info - informational message about navigation state */
+    ErrorSeverity["INFO"] = "info";
+})(ErrorSeverity || (ErrorSeverity = {}));
+/** @codexApi {"parent":"pithy.router.error-codes","name":"ErrorRecoveryStrategy","stability":"stable","signature":"enum ErrorRecoveryStrategy"} */
+/**
+ * Error recovery strategies for different error types
+ */
+export var ErrorRecoveryStrategy;
+(function (ErrorRecoveryStrategy) {
+    /** Show error UI with retry button */
+    ErrorRecoveryStrategy["SHOW_ERROR_UI"] = "show-error-ui";
+    /** Redirect to fallback route */
+    ErrorRecoveryStrategy["REDIRECT_FALLBACK"] = "redirect-fallback";
+    /** Silent fail - log error but don't show UI */
+    ErrorRecoveryStrategy["SILENT_FAIL"] = "silent-fail";
+    /** Retry operation automatically */
+    ErrorRecoveryStrategy["AUTO_RETRY"] = "auto-retry";
+    /** Throw to parent error boundary */
+    ErrorRecoveryStrategy["BUBBLE_UP"] = "bubble-up";
+})(ErrorRecoveryStrategy || (ErrorRecoveryStrategy = {}));
+/** @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 const ERROR_TAXONOMY = {
+    // ========== Loader Errors ==========
+    [RouterErrorCode.LOADER_EXECUTION_ERROR]: {
+        code: RouterErrorCode.LOADER_EXECUTION_ERROR,
+        severity: ErrorSeverity.ERROR,
+        defaultStrategy: ErrorRecoveryStrategy.SHOW_ERROR_UI,
+        userMessage: 'Failed to load data for this page',
+        retryable: true,
+    },
+    [RouterErrorCode.LOADER_TIMEOUT]: {
+        code: RouterErrorCode.LOADER_TIMEOUT,
+        severity: ErrorSeverity.ERROR,
+        defaultStrategy: ErrorRecoveryStrategy.SHOW_ERROR_UI,
+        userMessage: 'Loading data took too long',
+        retryable: true,
+    },
+    [RouterErrorCode.LOADER_ABORTED]: {
+        code: RouterErrorCode.LOADER_ABORTED,
+        severity: ErrorSeverity.INFO,
+        defaultStrategy: ErrorRecoveryStrategy.SILENT_FAIL,
+        userMessage: 'Loading was cancelled',
+        retryable: false,
+    },
+    [RouterErrorCode.LOADER_FAILED_SENTINEL]: {
+        code: RouterErrorCode.LOADER_FAILED_SENTINEL,
+        severity: ErrorSeverity.ERROR,
+        defaultStrategy: ErrorRecoveryStrategy.SHOW_ERROR_UI,
+        userMessage: 'Failed to load data',
+        retryable: true,
+    },
+    // ========== Guard Errors ==========
+    [RouterErrorCode.GUARD_EXECUTION_ERROR]: {
+        code: RouterErrorCode.GUARD_EXECUTION_ERROR,
+        severity: ErrorSeverity.CRITICAL,
+        defaultStrategy: ErrorRecoveryStrategy.REDIRECT_FALLBACK,
+        userMessage: 'Navigation check failed',
+        retryable: false,
+    },
+    [RouterErrorCode.GUARD_TIMEOUT]: {
+        code: RouterErrorCode.GUARD_TIMEOUT,
+        severity: ErrorSeverity.ERROR,
+        defaultStrategy: ErrorRecoveryStrategy.REDIRECT_FALLBACK,
+        userMessage: 'Navigation check took too long',
+        retryable: true,
+    },
+    [RouterErrorCode.GUARD_ABORTED]: {
+        code: RouterErrorCode.GUARD_ABORTED,
+        severity: ErrorSeverity.INFO,
+        defaultStrategy: ErrorRecoveryStrategy.SILENT_FAIL,
+        userMessage: 'Navigation was cancelled',
+        retryable: false,
+    },
+    [RouterErrorCode.GUARD_DENIED]: {
+        code: RouterErrorCode.GUARD_DENIED,
+        severity: ErrorSeverity.WARNING,
+        defaultStrategy: ErrorRecoveryStrategy.SILENT_FAIL,
+        userMessage: "You don't have permission to access this page",
+        retryable: false,
+    },
+    // ========== Component Errors ==========
+    [RouterErrorCode.COMPONENT_FACTORY_ERROR]: {
+        code: RouterErrorCode.COMPONENT_FACTORY_ERROR,
+        severity: ErrorSeverity.ERROR,
+        defaultStrategy: ErrorRecoveryStrategy.SHOW_ERROR_UI,
+        userMessage: 'Failed to initialize page component',
+        retryable: true,
+    },
+    [RouterErrorCode.COMPONENT_RENDER_ERROR]: {
+        code: RouterErrorCode.COMPONENT_RENDER_ERROR,
+        severity: ErrorSeverity.ERROR,
+        defaultStrategy: ErrorRecoveryStrategy.SHOW_ERROR_UI,
+        userMessage: 'Failed to render page',
+        retryable: true,
+    },
+    [RouterErrorCode.COMPONENT_LOAD_ERROR]: {
+        code: RouterErrorCode.COMPONENT_LOAD_ERROR,
+        severity: ErrorSeverity.ERROR,
+        defaultStrategy: ErrorRecoveryStrategy.SHOW_ERROR_UI,
+        userMessage: 'Failed to load page component',
+        retryable: true,
+    },
+    [RouterErrorCode.COMPONENT_LIFECYCLE_ERROR]: {
+        code: RouterErrorCode.COMPONENT_LIFECYCLE_ERROR,
+        severity: ErrorSeverity.ERROR,
+        defaultStrategy: ErrorRecoveryStrategy.SHOW_ERROR_UI,
+        userMessage: 'Page component error',
+        retryable: true,
+    },
+    // ========== Navigation Errors ==========
+    [RouterErrorCode.ROUTE_NOT_FOUND]: {
+        code: RouterErrorCode.ROUTE_NOT_FOUND,
+        severity: ErrorSeverity.ERROR,
+        defaultStrategy: ErrorRecoveryStrategy.REDIRECT_FALLBACK,
+        userMessage: 'Page not found',
+        retryable: false,
+    },
+    [RouterErrorCode.NAVIGATION_ABORTED]: {
+        code: RouterErrorCode.NAVIGATION_ABORTED,
+        severity: ErrorSeverity.INFO,
+        defaultStrategy: ErrorRecoveryStrategy.SILENT_FAIL,
+        userMessage: 'Navigation was cancelled',
+        retryable: false,
+    },
+    [RouterErrorCode.NAVIGATION_SUPERSEDED]: {
+        code: RouterErrorCode.NAVIGATION_SUPERSEDED,
+        severity: ErrorSeverity.INFO,
+        defaultStrategy: ErrorRecoveryStrategy.SILENT_FAIL,
+        userMessage: 'Navigation was replaced by a newer navigation',
+        retryable: false,
+    },
+    [RouterErrorCode.CIRCULAR_REDIRECT]: {
+        code: RouterErrorCode.CIRCULAR_REDIRECT,
+        severity: ErrorSeverity.CRITICAL,
+        defaultStrategy: ErrorRecoveryStrategy.SHOW_ERROR_UI,
+        userMessage: 'Circular redirect detected',
+        retryable: false,
+    },
+    // ========== Error Boundary Errors ==========
+    [RouterErrorCode.ERROR_BOUNDARY_LOAD_ERROR]: {
+        code: RouterErrorCode.ERROR_BOUNDARY_LOAD_ERROR,
+        severity: ErrorSeverity.CRITICAL,
+        defaultStrategy: ErrorRecoveryStrategy.BUBBLE_UP,
+        userMessage: 'Failed to load error page',
+        retryable: false,
+    },
+    [RouterErrorCode.ERROR_BOUNDARY_RENDER_ERROR]: {
+        code: RouterErrorCode.ERROR_BOUNDARY_RENDER_ERROR,
+        severity: ErrorSeverity.CRITICAL,
+        defaultStrategy: ErrorRecoveryStrategy.BUBBLE_UP,
+        userMessage: 'Error page failed to render',
+        retryable: false,
+    },
+    // ========== Unknown/Generic ==========
+    [RouterErrorCode.UNKNOWN_ERROR]: {
+        code: RouterErrorCode.UNKNOWN_ERROR,
+        severity: ErrorSeverity.ERROR,
+        defaultStrategy: ErrorRecoveryStrategy.SHOW_ERROR_UI,
+        userMessage: 'An unexpected error occurred',
+        retryable: true,
+    },
+};
+/** @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 function getErrorMetadata(code) {
+    return ERROR_TAXONOMY[code] || ERROR_TAXONOMY[RouterErrorCode.UNKNOWN_ERROR];
+}
+//# sourceMappingURL=error-codes.js.map

package/dist/router/features/errors/error-codes.js.map

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

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

@@ -0,0 +1,31 @@
+/** @codex
+{
+  "id": "pithy.router.error-resolution",
+  "title": "Error Component Resolution",
+  "category": "runtime"
+}
+*/
+import type { RouteNode } from '../../core/types';
+/** @codexApi {"parent":"pithy.router.error-resolution","name":"resolveErrorImport","stability":"internal","signature":"(node: RouteNode, getParent: (node: RouteNode) => RouteNode | undefined) => (() => Promise<unknown>) | null","description":"Resolve error component by walking parent chain"} */
+/**
+ * Resolve error component import function by walking parent chain
+ * Returns the dynamic import function for the nearest error.ts in the route hierarchy.
+ * Error boundaries follow the parent chain until an error component is found.
+ *
+ * @param node - Current route node where error occurred
+ * @param getParent - Function to get parent node (from segment chain)
+ * @returns Dynamic import function for error component, or null if none found
+ * @internal Used internally by outlet manager for error boundary resolution
+ */
+export declare function resolveErrorImport(node: RouteNode, getParent: (node: RouteNode) => RouteNode | undefined): (() => Promise<unknown>) | null;
+/** @codexApi {"parent":"pithy.router.error-resolution","name":"hasErrorComponent","stability":"internal","signature":"(node: RouteNode) => boolean","description":"Check if a route node has an error component"} */
+/**
+ * Check if a route node has an error component
+ * Useful for determining if error boundaries are available at a route level.
+ *
+ * @param node - Route node to check
+ * @returns True if node has error.ts file
+ * @internal Used internally for error boundary presence checks
+ */
+export declare function hasErrorComponent(node: RouteNode): boolean;
+//# sourceMappingURL=error-resolution.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"error-resolution.d.ts","sourceRoot":"","sources":["../../../../src/router/features/errors/error-resolution.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,wSAAwS;AACxS;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,EACf,SAAS,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,SAAS,GAAG,SAAS,GACpD,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,CAkBjC;AAED,qNAAqN;AACrN;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAE1D"}

package/dist/router/features/errors/error-resolution.js

@@ -0,0 +1,47 @@
+/** @codex
+{
+  "id": "pithy.router.error-resolution",
+  "title": "Error Component Resolution",
+  "category": "runtime"
+}
+*/
+/** @codexApi {"parent":"pithy.router.error-resolution","name":"resolveErrorImport","stability":"internal","signature":"(node: RouteNode, getParent: (node: RouteNode) => RouteNode | undefined) => (() => Promise<unknown>) | null","description":"Resolve error component by walking parent chain"} */
+/**
+ * Resolve error component import function by walking parent chain
+ * Returns the dynamic import function for the nearest error.ts in the route hierarchy.
+ * Error boundaries follow the parent chain until an error component is found.
+ *
+ * @param node - Current route node where error occurred
+ * @param getParent - Function to get parent node (from segment chain)
+ * @returns Dynamic import function for error component, or null if none found
+ * @internal Used internally by outlet manager for error boundary resolution
+ */
+export function resolveErrorImport(node, getParent) {
+    let current = node;
+    const visited = new Set();
+    while (current) {
+        // Prevent infinite loops from circular parent chains
+        if (visited.has(current)) {
+            return null;
+        }
+        visited.add(current);
+        if (current.imports.error) {
+            return current.imports.error;
+        }
+        current = getParent(current);
+    }
+    return null;
+}
+/** @codexApi {"parent":"pithy.router.error-resolution","name":"hasErrorComponent","stability":"internal","signature":"(node: RouteNode) => boolean","description":"Check if a route node has an error component"} */
+/**
+ * Check if a route node has an error component
+ * Useful for determining if error boundaries are available at a route level.
+ *
+ * @param node - Route node to check
+ * @returns True if node has error.ts file
+ * @internal Used internally for error boundary presence checks
+ */
+export function hasErrorComponent(node) {
+    return !!node.imports.error;
+}
+//# sourceMappingURL=error-resolution.js.map

package/dist/router/features/errors/error-resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-resolution.js","sourceRoot":"","sources":["../../../../src/router/features/errors/error-resolution.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAIF,wSAAwS;AACxS;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAe,EACf,SAAqD;IAErD,IAAI,OAAO,GAA0B,IAAI,CAAC;IAC1C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAa,CAAC;IAErC,OAAO,OAAO,EAAE,CAAC;QACf,qDAAqD;QACrD,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAErB,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YAC1B,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;QAC/B,CAAC;QACD,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,qNAAqN;AACrN;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAe;IAC/C,OAAO,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;AAC9B,CAAC"}

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

@@ -0,0 +1,60 @@
+/** @codex
+{
+  "id": "pithy.router.error-types",
+  "title": "Router Error Type Definitions",
+  "category": "types"
+}
+*/
+import { RouterErrorCode } from './error-codes';
+export { RouterErrorCode } from './error-codes';
+/** @codexApi {"parent":"pithy.router.error-types","name":"ErrorContext","stability":"stable","signature":"type ErrorContext"} */
+/**
+ * Context information for router errors
+ * Includes navigation tracking and route identification for precise error reporting
+ */
+export type ErrorContext = {
+    /** Navigation ID when error occurred */
+    navId: string;
+    /** Route ID where error occurred */
+    routeId: string;
+    /** Parent route ID for error resolution */
+    parentRouteId?: string | undefined;
+    /** Route path where error occurred */
+    routePath: string;
+    /** Canonical error code for deterministic handling */
+    code?: RouterErrorCode;
+    /** Timestamp when error occurred */
+    ts: number;
+};
+/** @codexApi {"parent":"pithy.router.error-types","name":"RouterError","stability":"stable","signature":"class RouterError extends Error"} */
+/**
+ * Router-specific error class with context
+ * Extends native Error with routing metadata for enhanced error tracking.
+ * Use this when throwing errors in guards, loaders, or route components.
+ */
+export declare class RouterError extends Error {
+    /** Error context with navigation and route info */
+    ctx: ErrorContext;
+    /** Original error cause if wrapped */
+    cause?: unknown;
+    /** Canonical error code for deterministic handling */
+    code: RouterErrorCode;
+    constructor(message: string, ctx: ErrorContext, cause?: unknown, code?: RouterErrorCode);
+    /**
+     * Check if this error is retryable
+     */
+    isRetryable(): boolean;
+    /**
+     * Get user-friendly error message
+     */
+    getUserMessage(): string;
+    /**
+     * Get error severity
+     */
+    getSeverity(): string;
+    /**
+     * Get recommended recovery strategy
+     */
+    getRecoveryStrategy(): string;
+}
+//# sourceMappingURL=error-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"error-types.d.ts","sourceRoot":"","sources":["../../../../src/router/features/errors/error-types.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,EAAE,eAAe,EAAoB,MAAM,eAAe,CAAC;AAGlE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,iIAAiI;AACjI;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,oCAAoC;IACpC,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,8IAA8I;AAC9I;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,mDAAmD;IACnD,GAAG,EAAE,YAAY,CAAC;IAClB,sCAAsC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sDAAsD;IACtD,IAAI,EAAE,eAAe,CAAC;gBAGpB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,YAAY,EACjB,KAAK,CAAC,EAAE,OAAO,EACf,IAAI,GAAE,eAA+C;IAkBvD;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACH,WAAW,IAAI,MAAM;IAIrB;;OAEG;IACH,mBAAmB,IAAI,MAAM;CAG9B"}

package/dist/router/features/errors/error-types.js

@@ -0,0 +1,57 @@
+/** @codex
+{
+  "id": "pithy.router.error-types",
+  "title": "Router Error Type Definitions",
+  "category": "types"
+}
+*/
+import { RouterErrorCode, getErrorMetadata } from './error-codes';
+// Re-export error codes for convenience
+export { RouterErrorCode } from './error-codes';
+/** @codexApi {"parent":"pithy.router.error-types","name":"RouterError","stability":"stable","signature":"class RouterError extends Error"} */
+/**
+ * Router-specific error class with context
+ * Extends native Error with routing metadata for enhanced error tracking.
+ * Use this when throwing errors in guards, loaders, or route components.
+ */
+export class RouterError extends Error {
+    constructor(message, ctx, cause, code = RouterErrorCode.UNKNOWN_ERROR) {
+        // Use user-friendly message from taxonomy if available
+        const metadata = getErrorMetadata(code);
+        const userMessage = message || metadata.userMessage;
+        super(userMessage);
+        this.name = 'RouterError';
+        this.ctx = { ...ctx, code };
+        this.cause = cause;
+        this.code = code;
+        // Maintain proper stack trace in V8
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, RouterError);
+        }
+    }
+    /**
+     * Check if this error is retryable
+     */
+    isRetryable() {
+        return getErrorMetadata(this.code).retryable;
+    }
+    /**
+     * Get user-friendly error message
+     */
+    getUserMessage() {
+        return getErrorMetadata(this.code).userMessage;
+    }
+    /**
+     * Get error severity
+     */
+    getSeverity() {
+        return getErrorMetadata(this.code).severity;
+    }
+    /**
+     * Get recommended recovery strategy
+     */
+    getRecoveryStrategy() {
+        return getErrorMetadata(this.code).defaultStrategy;
+    }
+}
+//# sourceMappingURL=error-types.js.map

package/dist/router/features/errors/error-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-types.js","sourceRoot":"","sources":["../../../../src/router/features/errors/error-types.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAElE,wCAAwC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAsBhD,8IAA8I;AAC9I;;;;GAIG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAQpC,YACE,OAAe,EACf,GAAiB,EACjB,KAAe,EACf,OAAwB,eAAe,CAAC,aAAa;QAErD,uDAAuD;QACvD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;QACxC,MAAM,WAAW,GAAG,OAAO,IAAI,QAAQ,CAAC,WAAW,CAAC;QAEpD,KAAK,CAAC,WAAW,CAAC,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,GAAG,GAAG,EAAE,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QAEjB,oCAAoC;QACpC,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC;IAC/C,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,WAAW,CAAC;IACjD,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC;IAC9C,CAAC;IAED;;OAEG;IACH,mBAAmB;QACjB,OAAO,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,eAAe,CAAC;IACrD,CAAC;CACF"}

package/dist/router/features/errors/global-error-fallback.d.ts

@@ -0,0 +1,33 @@
+/** @codex
+{
+  "id": "pithy.router.error-fallback",
+  "title": "Global Error Fallback Component",
+  "category": "runtime"
+}
+*/
+import type { RouterError } from './error-types';
+/** @codexApi {"parent":"pithy.router.error-fallback","name":"ErrorComponentProps","stability":"stable","signature":"interface ErrorComponentProps","description":"Props passed to error boundary components"} */
+/**
+ * Props interface for error components
+ * Passed to both custom error.ts and global fallback
+ */
+export interface ErrorComponentProps {
+    /** The error that occurred (may be a plain Error or a RouterError) */
+    error: Error & Partial<RouterError>;
+    /** Function to retry the failed operation */
+    retry: () => void;
+}
+/** @codexApi {"parent":"pithy.router.error-fallback","name":"GlobalErrorFallback","stability":"stable","signature":"(props: ErrorComponentProps) => Component","description":"Default error UI when no route-specific error.ts exists"} */
+/**
+ * Global fallback error component
+ * Shown when no route-specific error.ts exists
+ * Provides basic error display with retry button
+ *
+ * @param props - Error component props
+ * @returns PithyJS component instance
+ */
+export declare function GlobalErrorFallback({ error, retry }: ErrorComponentProps): {
+    el: HTMLElement | DocumentFragment;
+    destroy: () => void;
+};
+//# sourceMappingURL=global-error-fallback.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"global-error-fallback.d.ts","sourceRoot":"","sources":["../../../../src/router/features/errors/global-error-fallback.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAGF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,iNAAiN;AACjN;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACpC,6CAA6C;IAC7C,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,2OAA2O;AAC3O;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,mBAAmB;;;EA6KxE"}