@keenmate/svelte-spa-router 5.1.0 → 5.2.0-rc01

package/CHANGELOG.md

@@ -5,9 +5,136 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [5.2.0-rc01] - 2026-02-18
 
-## [5.1.0] - TBD
+### Fixed
+- **`routeContext()` function missing / mangled name** (Issue #3) — The exported function was named `routerouteContext()` instead of `routeContext()` due to a find-replace accident during the `userData` → `routeContext` rename. The README also referenced the old name `routeUserData()`.
+  - Renamed `routerouteContext()` → `routeContext()` in `route-metadata.svelte.js` (function + all internal variable references)
+  - Updated `route-metadata.d.ts` type declaration to match
+  - Fixed README.md: `routeUserData` → `routeContext` in all import examples and API reference
+
+- **`wrap()` not merging title/breadcrumbs into routeContext** (Issue #3) — `routeTitle()` and `routeBreadcrumbs()` returned empty values for routes defined with `wrap({ title, breadcrumbs })` because `wrap()` never merged these into `routeContext`. The Router's `pipelineComputeMetadata()` only reads from `routeItem.routeContext`, so title and breadcrumbs were silently lost.
+  - Fixed in both single-component and zones code paths in `wrap.js`
+  - `createRouteDefinition()` already had the merge logic — only `wrap()` was missing it
+
+- **Logger TypeScript errors** — Added `.d.ts` type declarations for vendored loglevel libraries
+  - Created `src/lib/vendor/loglevel/index.d.ts` and `prefix.d.ts`
+  - Removed `@ts-ignore` comments from `logger.ts`
+  - `svelte-check` now passes with 0 errors and 0 warnings
+
+- **Missing TypeScript declarations for GlobalErrorHandler and ErrorDisplay** (Issue #4) — `Cannot find module '@keenmate/svelte-spa-router/helpers/GlobalErrorHandler' or its corresponding type declarations`
+  - Created `GlobalErrorHandler.svelte.d.ts` with `GlobalErrorHandlerProps` and `ErrorComponentProps` interfaces
+  - Created `ErrorDisplay.svelte.d.ts` with `ErrorDisplayProps` interface
+  - Added `types` field to `./helpers/GlobalErrorHandler` export in `package.json`
+  - Added new `./helpers/ErrorDisplay` export to `package.json` (was not exported at all)
+
+- **Missing TypeScript declarations for `setHierarchicalRoutesEnabled` and `setIncludeReferrer`** (Issue #5) — `Module has no exported member 'setHierarchicalRoutesEnabled'`
+  - Added `setHierarchicalRoutesEnabled()`, `getHierarchicalRoutesEnabled()`, `setIncludeReferrer()`, and `getIncludeReferrer()` declarations to `utils.d.ts`
+  - Removed phantom `active.svelte.js` re-export from `index.d.ts` (type declared an export that didn't exist at runtime)
+
+### Added
+- **`defineRoutes()` — Type-safe route definitions** (Issue #2) - Single source of truth for routes, navigation, and URL building
+  - Returns `routes` (for `<Router>`), `nav` (navigation helpers), and `paths` (URL builders)
+  - Full TypeScript support with IDE autocomplete on route names and parameters
+  - Extracts `:param` names from path patterns at the type level — catches typos at compile time
+  - `nav.X.push(params)` / `nav.X.replace(params)` — programmatic navigation with autocomplete
+  - `nav.X.link(params)` — returns object for `use:link` action
+  - `paths.X(params)` — builds URL string for `href` attributes
+  - Smart optimization: sync components without options skip `wrap()` overhead
+  - Async components and routes with options automatically use `createRoute()`
+  - Automatically calls `registerRoutes()` — no separate registration step needed
+  - Supports all existing route options: `conditions`, `breadcrumbs`, `permissions`, `loadingComponent`, `props`, `title`, etc.
+  - Example:
+    ```javascript
+    import { defineRoutes } from '@keenmate/svelte-spa-router/routes'
+
+    const { routes, nav, paths } = defineRoutes({
+      home: { path: '/', component: Home },
+      user: { path: '/user/:id', component: () => import('./User.svelte') }
+    })
+
+    // <Router {routes} />
+    // nav.user.push({ id: 123 })       — autocomplete on 'id'
+    // <a href={paths.user({ id: 123 })} use:link>
+    ```
+
+- **Route Context Demo pages** — Example pages demonstrating `routeContext()`, `routeTitle()`, and `routeBreadcrumbs()` with live output
+  - `example/src/routes/RouteContextDemo.svelte` — explains routeContext, shows live values, code examples
+  - `example/src/routes/RouteContextTarget.svelte` — target page reached via button, displays its own routeContext
+  - Both wired into App.svelte with nav link in Routing dropdown
+
+- **Comprehensive test suite** — Expanded from ~156 to 347 passing tests across 16 test files (0 skipped)
+  - **New test files:**
+    - `route-metadata.test.js` (26 tests) — `updateRouteMetadata`, `routeContext()`, `routeTitle()`, `routeBreadcrumbs()`, `updateBreadcrumb()`, `updateTitle()`, `clearBreadcrumbCache()`, loading state functions
+    - `navigation-guard.test.js` (22 tests) — `NavigationCancelledError`, `registerBeforeLeave()`, `runBeforeLeaveGuards()`, `createDirtyCheckGuard()`
+    - `error-handler.test.js` (23 tests) — `configureGlobalErrorHandler()`, error state, `shouldIgnoreError()`, restart loop prevention, `createErrorInfo()`, `createRecoveryHelpers()`
+    - `filters.test.js` (18 tests) — `configureFilters()`, `filters()` flat/structured modes, `updateFilters()`, custom parse/stringify round-trip
+    - `querystring-shared.test.js` (7 tests) — `configureQuerystring()`, `query()` with arrayFormat/arrays config
+    - `zones-and-scroll.test.js` (12 tests) — `getZoneComponent()`, `setZoneComponents()`, `restoreScroll()`
+    - `logger.test.js` (13 tests) — `enableLogging()`, `disableLogging()`, `setLogLevel()`, `setCategoryLevel()` for all 12 categories, `logStructured()`
+  - **Extended test files:**
+    - `wrap.test.js` (9 → 42 tests) — zones mode, inheritance flags, `createRouteDefinition()`, `createRoute()`, sync component wrapping, condition normalization, validation errors
+    - `navigation.test.js` (10 → 27 tests) — `goBack()`, `loc()`, `routeParams()`/`setParams()`, `navigationContext()`/`setNavigationContext()`, array/object/multi-param push formats, `setIncludeReferrer()`, `setParamReplacementPlaceholder()`
+    - `permissions.test.js` (13 → 33 tests) — `createProtectedRouteDefinition()`, `authorizationCallback` execution order/fail-fast, `getUnauthorizedBehavior/Route/Component/Handler()`, `hasExplicitHandler()`, `all:` permission requirement
+  - **Removed 34 `it.skip` stubs** that required Svelte component rendering or real browser DOM (deleted 3 empty test files: Router.test.js, hierarchical-routes.test.js, link-action.test.js; trimmed active-action.test.js and querystring-helpers.test.js)
+
+### Documentation
+- **defineRoutes() example page** — Added interactive demo page to example app (`example/src/routes/DefineRoutesDemo.svelte`)
+  - Covers basic usage, navigation helpers, path builders, and supported route options
+  - Includes interactive playground with real-time output
+  - Shows before/after comparison with manual route definitions
+- **Example app navbar rework** — Replaced flat navigation with grouped dropdown menus
+  - 5 dropdown groups: Navigation, URL & Data, Routing, Errors, Security
+  - CSS hover-based dropdowns (no JavaScript state management)
+- **AI Assistant Documentation** - Added 15 concise text files in `./ai` folder optimized for AI assistants
+  - Plain text format (no markdown) with bullet-style structure for efficient AI parsing
+  - Files organized by feature: basic-setup, navigation, named-routes, route-params, permissions, guards-conditions, hierarchical-routes, tree-structure, link-actions, error-handling, referrer-tracking, debug-logging, import-patterns, utilities, breadcrumbs
+  - Includes correct/incorrect usage patterns (✅/❌) for common mistakes
+  - Code examples designed for copy-paste usage
+  - Complements CLAUDE.md by providing quick-reference documentation
+  - Aimed at helping AI coding assistants (like Claude, Cursor, Copilot) quickly understand router functionality
+- **Breadcrumbs Documentation** - Added comprehensive `ai/breadcrumbs.txt` covering breadcrumb navigation system
+  - Basic breadcrumb definition and structure
+  - Accessing breadcrumbs in components via `routeBreadcrumbs()` helper
+  - Breadcrumb component examples with navigation and styling
+  - Dynamic breadcrumb updates using `updateBreadcrumb(id, updates)` after data loads
+  - Integration with route parameters for dynamic segments
+  - Hierarchical breadcrumb inheritance with automatic concatenation
+  - Tree structure support with `createHierarchy()`
+  - Best practices and common patterns
+  - Debugging with ROUTER:METADATA logging category
+
+## [5.1.1] - 2025-11-30
+
+### Fixed
+- **Breadcrumbs preserved on querystring changes** - Fixed breadcrumbs resetting to "Loading..." when only the querystring changes (e.g., tab navigation)
+  - Issue: Changing tabs via `replace('/items/1', {}, { tab: 'settings' })` would reset dynamically updated breadcrumbs back to their initial "Loading..." state
+  - Root cause: `updateRouteMetadata()` was resetting the entire route context on any navigation, including querystring-only changes
+  - Solution: Detect when only querystring changed (same location + params) and preserve current breadcrumbs instead of resetting
+  - Also applies cached breadcrumb updates when the route context is updated
+
+### Added
+- **TabsDemo example** - New example demonstrating correct pattern for tabs with querystring state
+  - Shows how to use `replace()` instead of `push()` for tab changes
+  - Demonstrates dynamic breadcrumbs that persist across tab switches
+  - Located at `example/src/routes/TabsDemo.svelte`
+
+### Documentation
+- **AI Documentation Index** - Added comprehensive `ai/INDEX.txt` file for quick keyword lookup
+  - Organized by topic sections: Getting Started, Imports, Navigation, Named Routes, etc.
+  - Includes file descriptions, reading order recommendations, and cross-references
+  - Quick problem solving guide mapping common errors to solutions
+  - Examples organized by use case (Simple SPA, Admin Dashboard, E-commerce, etc.)
+- **Breadcrumbs with Tabs** - Added "TABS WITH QUERY STRING" section to `ai/breadcrumbs.txt`
+  - Documents the pattern for tabs that use querystring for state
+  - Explains why `replace()` is necessary to preserve breadcrumbs
+  - Includes complete code example
+- **Named Routes in Basic Setup** - Added "ENABLING NAMED ROUTES" section to `ai/basic-setup.txt`
+  - Documents that `registerRoutes()` must be called for named route navigation to work
+  - Shows common pattern with page definitions array
+  - Explains the "Route X not found in registry" error and how to fix it
+
+## [5.1.0] - 2025-11-20 ✅ Published
 
 ### Added
 - **Global Window API:** Added runtime debugging and introspection via `window.components['svelte-spa-router']`

package/README.md

@@ -11,6 +11,7 @@ Main features:
 
 - **Dual-mode routing**: Supports both hash-based (`#/path`) and history API (`/path`) routing
 - Built with **Svelte 5 runes** for better reactivity and performance
+- **Type-safe routes**: `defineRoutes()` — single source of truth with IDE autocomplete on route names and params
 - **TypeScript-first**: Full generic support for `routeParams()`, `query()`, and `filters()` with intellisense
 - **Flexible Navigation**: Multi-parameter signatures, named routes, navigation context (WinForms-like data passing)
 - **Referrer Tracking**: Automatic previous route tracking with configurable modes ('never', 'notfound', 'always')
@@ -84,6 +85,9 @@ let { routeParams = {} } = $props()
 ### Route Configuration
 
 ```javascript
+// Type-safe route definitions (recommended!)
+import { defineRoutes } from '@keenmate/svelte-spa-router/routes'
+
 // Wrap routes with loading/conditions
 import { wrap } from '@keenmate/svelte-spa-router/wrap'
 
@@ -451,6 +455,96 @@ const routes = {
 }
 ```
 
+### Define routes with type safety (Recommended)
+
+Use `defineRoutes()` for a single source of truth that gives you IDE autocomplete on route names and parameters, preventing typos at compile time:
+
+```javascript
+// src/routes.js (or routes.ts for TypeScript)
+import { defineRoutes } from '@keenmate/svelte-spa-router/routes'
+import Home from './routes/Home.svelte'
+
+const { routes, nav, paths } = defineRoutes({
+  home: {
+    path: '/',
+    component: Home
+  },
+  about: {
+    path: '/about',
+    component: () => import('./routes/About.svelte')
+  },
+  user: {
+    path: '/user/:id',
+    component: () => import('./routes/User.svelte'),
+    conditions: [checkAuth],
+    breadcrumbs: [{ label: 'Users' }, { id: 'user', label: 'User' }]
+  },
+  settings: {
+    path: '/settings',
+    component: () => import('./routes/Settings.svelte'),
+    permissions: { any: ['settings.read'] }
+  }
+})
+
+export { routes, nav, paths }
+```
+
+**Use in App.svelte:**
+
+```svelte
+<script>
+import Router from '@keenmate/svelte-spa-router'
+import { link } from '@keenmate/svelte-spa-router'
+import { routes, nav, paths } from './routes'
+</script>
+
+<!-- Pass routes to Router -->
+<Router {routes} />
+
+<!-- Links with autocomplete on route names + params -->
+<a href={paths.user({ id: 123 })} use:link>User 123</a>
+<a href={paths.about()} use:link>About</a>
+
+<!-- Programmatic navigation -->
+<button onclick={() => nav.user.push({ id: 42 })}>Go to User 42</button>
+<button onclick={() => nav.settings.replace()}>Settings</button>
+
+<!-- For use:link action -->
+<a use:link={nav.user.link({ id: 99 })}>User 99</a>
+```
+
+**What `defineRoutes()` returns:**
+
+| Property | Description |
+|----------|-------------|
+| `routes` | Standard routes object for `<Router {routes} />` |
+| `nav.X.push(params?, query?, ctx?)` | Navigate to route X (calls `push()` internally) |
+| `nav.X.replace(params?, query?, ctx?)` | Replace with route X (calls `replace()` internally) |
+| `nav.X.link(params?, query?)` | Returns object for `use:link` action |
+| `nav.X.path` | Raw path pattern (e.g. `'/user/:id'`) |
+| `paths.X(params?, query?)` | Build URL string for `href` attributes |
+
+**TypeScript support:**
+
+In TypeScript, `defineRoutes()` extracts `:param` names from path patterns at the type level:
+
+```typescript
+const { nav, paths } = defineRoutes({
+  user: { path: '/user/:id', component: UserPage }
+})
+
+nav.user.push({ id: 123 })       // ✅ TypeScript knows 'id' is required
+nav.user.push({ userId: 123 })   // ❌ Type error — 'userId' doesn't exist
+nav.user.push()                   // ✅ OK — params are optional at runtime
+paths.user({ id: 123 })          // ✅ Returns '/user/123'
+```
+
+**Supported route options:**
+
+Each route in `defineRoutes()` accepts `path`, `component`, and all existing `createRoute()` / `wrap()` options: `loadingComponent`, `loadingParams`, `conditions`, `props`, `routeContext`, `title`, `breadcrumbs`, `shouldDisplayLoadingOnRouteLoad`, `permissions`, `authorizationCallback`, and inheritance flags (`inheritBreadcrumbs`, `inheritPermissions`, etc.).
+
+> **Note:** `defineRoutes()` automatically calls `registerRoutes()` internally — no separate registration step is needed. Named routes work immediately with `push()`, `replace()`, and `buildUrl()`.
+
 ### Include the router
 
 In your main component (usually `App.svelte`):
@@ -1077,11 +1171,11 @@ Access current route metadata reactively:
 
 ```svelte
 <script>
-import { routeTitle, routeBreadcrumbs, routeUserData } from '@keenmate/svelte-spa-router/helpers/route-metadata'
+import { routeTitle, routeBreadcrumbs, routeContext } from '@keenmate/svelte-spa-router/helpers/route-metadata'
 
 const title = $derived(routeTitle())
 const breadcrumbs = $derived(routeBreadcrumbs())
-const userData = $derived(routeUserData())
+const context = $derived(routeContext())
 </script>
 
 <h1>{title || 'Default Title'}</h1>
@@ -1115,7 +1209,7 @@ import {
     // Reactive metadata access
     routeTitle,            // Get current title
     routeBreadcrumbs,      // Get current breadcrumbs
-    routeUserData          // Get full userData object
+    routeContext            // Get full route context object
 } from '@keenmate/svelte-spa-router/helpers/route-metadata'
 ```
 
@@ -1716,12 +1810,12 @@ const routes = {
 
 Define routes in a hierarchical tree structure as an alternative to flat definitions. Child paths are automatically concatenated to parent paths, and routes inherit metadata from parents.
 
-**Enable hierarchical mode first:**
+**Enable hierarchical mode first** (disabled by default — routes are flat with no inheritance):
 ```javascript
 // main.js - before mounting app
 import { setHierarchicalRoutesEnabled } from '@keenmate/svelte-spa-router'
 
-setHierarchicalRoutesEnabled(true)
+setHierarchicalRoutesEnabled(true)  // default: false
 ```
 
 **Define routes using tree structure:**
@@ -1800,7 +1894,7 @@ import Router from '@keenmate/svelte-spa-router'
 import { push, replace, pop, goBack, location, querystring, routeParams, navigationContext } from '@keenmate/svelte-spa-router'
 
 // Named routes (for use with push/replace/link)
-import { registerRoutes, buildUrl } from '@keenmate/svelte-spa-router/routes'
+import { registerRoutes, buildUrl, defineRoutes } from '@keenmate/svelte-spa-router/routes'
 
 // Route creation (recommended - no wrap() needed!)
 import { createRoute, createRouteDefinition } from '@keenmate/svelte-spa-router/wrap'
@@ -1815,7 +1909,7 @@ import { createHierarchy } from '@keenmate/svelte-spa-router/helpers/hierarchy'
 import active from '@keenmate/svelte-spa-router/active'
 
 // Configuration
-import { setHashRoutingEnabled, setBasePath, setParamReplacementPlaceholder, setHierarchicalRoutesEnabled } from '@keenmate/svelte-spa-router'
+import { setHashRoutingEnabled, setBasePath, setParamReplacementPlaceholder, setHierarchicalRoutesEnabled, setIncludeReferrer } from '@keenmate/svelte-spa-router'
 
 // Querystring helpers (shared reactive state)
 import { configureQuerystring, query } from '@keenmate/svelte-spa-router/helpers/querystring'
@@ -1865,7 +1959,7 @@ import {
   updateRouteMetadata,
   routeTitle,
   routeBreadcrumbs,
-  routeUserData
+  routeContext
 } from '@keenmate/svelte-spa-router/helpers/route-metadata'
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keenmate/svelte-spa-router",
-  "version": "5.1.0",
+  "version": "5.2.0-rc01",
   "description": "Router for SPAs using Svelte 5 with runes, dual-mode routing, permissions, and error handling",
   "main": "./src/lib/index.js",
   "svelte": "./src/lib/Router.svelte",
@@ -72,8 +72,13 @@
       "import": "./src/lib/helpers/error-handler.svelte.js"
     },
     "./helpers/GlobalErrorHandler": {
+      "types": "./src/lib/helpers/GlobalErrorHandler.svelte.d.ts",
       "svelte": "./src/lib/helpers/GlobalErrorHandler.svelte"
     },
+    "./helpers/ErrorDisplay": {
+      "types": "./src/lib/helpers/ErrorDisplay.svelte.d.ts",
+      "svelte": "./src/lib/helpers/ErrorDisplay.svelte"
+    },
     "./helpers/hierarchy": {
       "types": "./src/lib/helpers/hierarchy.d.ts",
       "import": "./src/lib/helpers/hierarchy.svelte.js"

package/src/lib/Router.svelte

@@ -595,11 +595,6 @@ function commitToReactiveState(ctx) {
                     }
                 }
 
-                // Debug log AFTER navigationContext is set
-                const finalReferrer = ctx.updatedNavigationContext?.referrer?.location || 'none'
-                const finalSeq = typeof window !== 'undefined' && window.history.state?.__navigationSequence || 0
-                console.log(`🔍 NAV: route="${ctx.location}" referrer="${finalReferrer}" seq=${finalSeq}`)
-
                 // Update current route tracking (unless catch-all)
                 if (!ctx.isCatchAll) {
                     currentRoute = ctx.location
@@ -1298,11 +1293,11 @@ $effect(() => {
         {@const Comp = zoneComponentData.component}
         {@const zoneParams = zoneComponentData.params}
         {@const zoneProps = zoneComponentData.props}
-        {@const zonerouteContext = zoneComponentData.routeContext}
+        {@const zoneRouteContext = zoneComponentData.routeContext}
         {#if zoneParams}
-            <Comp routeParams={zoneParams} routeContext={zonerouteContext} {...zoneProps} />
+            <Comp routeParams={zoneParams} routeContext={zoneRouteContext} {...zoneProps} />
         {:else}
-            <Comp routeContext={zonerouteContext} {...zoneProps} />
+            <Comp routeContext={zoneRouteContext} {...zoneProps} />
         {/if}
     {/if}
 {:else if component}
@@ -1317,8 +1312,20 @@ $effect(() => {
         {/if}
     {/if}
 
-    <!-- Real component (hidden while loading, visible after hideLoading() called) -->
-    <div style:display={isWaitingForData ? 'none' : 'block'}>
+    <!-- Real component -->
+    {#if loadingComponent}
+        <!-- Routes with loading: wrapper needed to hide component while loading spinner shows -->
+        <div style:display={isWaitingForData ? 'none' : 'contents'}>
+            {#if componentParams}
+                {@const Comp = component}
+                <Comp routeParams={componentParams} {...componentProps} />
+            {:else}
+                {@const Comp = component}
+                <Comp {...componentProps} />
+            {/if}
+        </div>
+    {:else}
+        <!-- Routes without loading: render directly, no wrapper div -->
         {#if componentParams}
             {@const Comp = component}
             <Comp routeParams={componentParams} {...componentProps} />
@@ -1326,5 +1333,5 @@ $effect(() => {
             {@const Comp = component}
             <Comp {...componentProps} />
         {/if}
-    </div>
+    {/if}
 {/if}

package/src/lib/helpers/ErrorDisplay.svelte.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Type definitions for ErrorDisplay.svelte component
+ */
+
+import type { Component } from 'svelte'
+import type { ErrorInfo } from './error-handler.js'
+
+/**
+ * ErrorDisplay component props
+ */
+export interface ErrorDisplayProps {
+    /** The error to display */
+    error: Error
+
+    /** Additional error context */
+    errorInfo: ErrorInfo | null
+
+    /** Restart the application */
+    onRestart: () => void
+
+    /** Navigate to the safe route */
+    onNavigateSafe: () => void
+
+    /** Dismiss the error and continue */
+    onContinue: () => void
+
+    /** Whether restart is allowed (not in a restart loop) */
+    canRestart: boolean
+
+    /**
+     * Route to navigate to when clicking "Go to Home Page"
+     * @default '/'
+     */
+    safeRoute?: string
+
+    /**
+     * Show detailed technical information (stack trace, error context)
+     * @default false
+     */
+    isDevelopment?: boolean
+}
+
+declare const ErrorDisplay: Component<ErrorDisplayProps>
+export default ErrorDisplay

package/src/lib/helpers/GlobalErrorHandler.svelte.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Type definitions for GlobalErrorHandler.svelte component
+ */
+
+import type { Component, Snippet } from 'svelte'
+import type { ErrorInfo } from './error-handler.js'
+
+/**
+ * Props passed to a custom errorComponent snippet
+ */
+export interface ErrorComponentProps {
+    /** The caught error */
+    error: Error
+    /** Additional error context */
+    errorInfo: ErrorInfo | null
+    /** Restart the application */
+    onRestart: () => void
+    /** Navigate to the safe route */
+    onNavigateSafe: () => void
+    /** Dismiss the error and continue */
+    onContinue: () => void
+    /** Whether restart is allowed (not in a restart loop) */
+    canRestart: boolean
+}
+
+/**
+ * GlobalErrorHandler component props
+ */
+export interface GlobalErrorHandlerProps {
+    /**
+     * App content rendered inside the error boundary.
+     */
+    children: Snippet
+
+    /**
+     * Custom error UI snippet. When provided, replaces the default ErrorDisplay.
+     * Receives ErrorComponentProps as its argument.
+     * @default null
+     */
+    errorComponent?: Snippet<[ErrorComponentProps]> | null
+}
+
+declare const GlobalErrorHandler: Component<GlobalErrorHandlerProps>
+export default GlobalErrorHandler

package/src/lib/helpers/route-metadata.d.ts

@@ -68,14 +68,14 @@ export function routeBreadcrumbs(): BreadcrumbItem[];
  *
  * @example
  * ```typescript
- * import { routerouteContext } from '@keenmate/svelte-spa-router/helpers/route-metadata'
+ * import { routeContext } from '@keenmate/svelte-spa-router/helpers/route-metadata'
  *
  * // In a component
- * const routeContext = $derived(routerouteContext())
+ * const routeContext = $derived(routeContext())
  * const customField = routeContext.myCustomField
  * ```
  */
-export function routerouteContext(): Record<string, any>;
+export function routeContext(): Record<string, any>;
 
 /**
  * Hide the loading screen

package/src/lib/helpers/route-metadata.svelte.js

@@ -11,9 +11,9 @@ import { metadataLogger } from '../logger.ts'
  * Current route metadata state
  * Single source of truth - other values derive from this
  */
-let currentRouterouteContext = $state({})
-let currentRouteTitle = $derived(currentRouterouteContext.title || '')
-let currentRouteBreadcrumbs = $derived(currentRouterouteContext.breadcrumbs || [])
+let currentRouteContext = $state({})
+let currentRouteTitle = $derived(currentRouteContext.title || '')
+let currentRouteBreadcrumbs = $derived(currentRouteContext.breadcrumbs || [])
 
 /**
  * Loading control state
@@ -32,7 +32,7 @@ let currentBasePath = null // Track base path to clear cache on major route chan
  * Cache for manually updated breadcrumbs
  * Maps breadcrumb ID to updated breadcrumb data
  */
-let updatedBreadcrumbsCache = new Map()
+const updatedBreadcrumbsCache = new Map()
 
 /**
  * Update route metadata (called by Router or user code)
@@ -42,8 +42,11 @@ let updatedBreadcrumbsCache = new Map()
  * @param {Object} params - route params
  */
 export function updateRouteMetadata(routeContext = {}, location = '', querystring = '', params = {}) {
-    // Create a unique key for this route (location + querystring + params)
-    const routeKey = `${location}|${querystring}|${JSON.stringify(params)}`
+    // Create a key for the route path (without querystring) to detect actual route changes
+    const locationKey = `${location}|${JSON.stringify(params)}`
+
+    // Create full key including querystring for logging
+    const fullRouteKey = `${location}|${querystring}|${JSON.stringify(params)}`
 
     // Extract base path (e.g., /documents/1 → /documents, /documents/1/logs → /documents/1)
     // This is a simple heuristic: get path up to the last segment
@@ -56,12 +59,45 @@ export function updateRouteMetadata(routeContext = {}, location = '', querystrin
         clearBreadcrumbCache()
     }
 
-    // Only update if route actually changed
-    if (currentRouteKey !== routeKey) {
-        currentRouterouteContext = routeContext
-        currentRouteKey = routeKey
-        currentBasePath = basePath
-        metadataLogger.debug('[updateRouteMetadata] Route changed to:', routeKey)
+    // Check if only querystring changed (same location and params)
+    const onlyQuerystringChanged = currentRouteKey && currentRouteKey.startsWith(locationKey.split('|')[0] + '|')
+        && currentRouteKey.includes('|' + JSON.stringify(params))
+        && currentRouteKey !== fullRouteKey
+
+    // Only update context if the actual route (location + params) changed, not just querystring
+    if (currentRouteKey !== fullRouteKey) {
+        if (onlyQuerystringChanged) {
+            // Querystring-only change: preserve breadcrumbs, just update the key
+            metadataLogger.debug('[updateRouteMetadata] Querystring changed, preserving breadcrumbs')
+            currentRouteKey = fullRouteKey
+        } else {
+            // Actual route change: update context but apply cached breadcrumb updates
+            let finalContext = { ...routeContext }
+
+            // Apply any cached breadcrumb updates to the new context
+            if (routeContext.breadcrumbs && updatedBreadcrumbsCache.size > 0) {
+                const breadcrumbs = [...routeContext.breadcrumbs]
+                let appliedUpdates = false
+
+                for (const [id, updates] of updatedBreadcrumbsCache) {
+                    const index = breadcrumbs.findIndex(crumb => crumb.id === id)
+                    if (index !== -1) {
+                        breadcrumbs[index] = { ...breadcrumbs[index], ...updates }
+                        appliedUpdates = true
+                        metadataLogger.debug('[updateRouteMetadata] Applied cached update for:', id)
+                    }
+                }
+
+                if (appliedUpdates) {
+                    finalContext = { ...finalContext, breadcrumbs }
+                }
+            }
+
+            currentRouteContext = finalContext
+            currentRouteKey = fullRouteKey
+            currentBasePath = basePath
+            metadataLogger.debug('[updateRouteMetadata] Route changed to:', fullRouteKey)
+        }
     } else {
         metadataLogger.debug('[updateRouteMetadata] Same route, ignoring update')
     }
@@ -103,14 +139,14 @@ export function routeBreadcrumbs() {
  *
  * @example
  * ```javascript
- * import { routerouteContext } from '@keenmate/svelte-spa-router/helpers/route-metadata'
+ * import { routeContext } from '@keenmate/svelte-spa-router/helpers/route-metadata'
  *
- * const routeContext = $derived(routerouteContext())
+ * const routeContext = $derived(routeContext())
  * const customData = $derived(routeContext.myCustomField)
  * ```
  */
-export function routerouteContext() {
-    return currentRouterouteContext
+export function routeContext() {
+    return currentRouteContext
 }
 
 /**
@@ -145,7 +181,7 @@ export function updateBreadcrumb(id, updates) {
     metadataLogger.debug('[updateBreadcrumb] Cached update for id:', id, 'updates:', updates)
 
     // Get snapshot to work with plain values (not proxies)
-    const currentContext = $state.snapshot(currentRouterouteContext)
+    const currentContext = $state.snapshot(currentRouteContext)
     const breadcrumbs = [...(currentContext.breadcrumbs || [])]
     const index = breadcrumbs.findIndex(crumb => crumb.id === id)
     metadataLogger.debug('[updateBreadcrumb] Found at index:', index)
@@ -156,7 +192,7 @@ export function updateBreadcrumb(id, updates) {
             ...updates
         }
         metadataLogger.debug('[updateBreadcrumb] Updated breadcrumb to:', breadcrumbs[index])
-        currentRouterouteContext = {
+        currentRouteContext = {
             ...currentContext,
             breadcrumbs
         }
@@ -199,8 +235,8 @@ export function clearBreadcrumbCache() {
  * ```
  */
 export function updateTitle(title) {
-    currentRouterouteContext = {
-        ...currentRouterouteContext,
+    currentRouteContext = {
+        ...currentRouteContext,
         title
     }
     // Title updates don't affect breadcrumbs flag

package/src/lib/index.d.ts

@@ -6,7 +6,6 @@
 export { default as Router } from './Router.svelte';
 
 // Core utilities
-export * from './active.svelte.js';
 export * from './utils';
 export * from './constants';
 export { default as wrap } from './wrap';

package/src/lib/logger.ts

@@ -36,9 +36,7 @@
  */
 
 // Import vendored libraries via ES module wrappers
-// @ts-ignore - Vendored library without type definitions
 import log from './vendor/loglevel/index.js';
-// @ts-ignore - Vendored library without type definitions
 import prefix from './vendor/loglevel/prefix.js';
 
 // Define color scheme

package/src/lib/routes.d.ts

@@ -74,3 +74,104 @@ export function buildUrl(
  * @returns True if route is registered
  */
 export function hasRoute(name: string): boolean;
+
+/**
+ * Get the pattern for a registered route by name
+ *
+ * @param name - Route name
+ * @returns Route pattern or undefined if not registered
+ */
+export function getRouteByName(name: string): string | undefined;
+
+// --- defineRoutes types ---
+
+/** Extract :param names from a route path pattern */
+type ExtractParams<T extends string> =
+    T extends `${string}:${infer Param}/${infer Rest}`
+        ? { [K in Param]: string | number } & ExtractParams<`/${Rest}`>
+        : T extends `${string}:${infer Param}`
+            ? { [K in Param]: string | number }
+            : Record<string, never>;
+
+/** Route definition for defineRoutes() */
+interface RouteDefinition {
+    path: string;
+    component: any;
+    loadingComponent?: any;
+    loadingParams?: Record<string, any>;
+    conditions?: Function | Function[];
+    props?: Record<string, any>;
+    routeContext?: Record<string, any>;
+    title?: string;
+    breadcrumbs?: Array<{ label: string; path?: string; id?: string }>;
+    shouldDisplayLoadingOnRouteLoad?: boolean;
+    permissions?: { any?: string[]; all?: string[] };
+    authorizationCallback?: Function;
+    inheritBreadcrumbs?: boolean;
+    inheritPermissions?: boolean;
+    inheritConditions?: boolean;
+    inheritAuthorization?: boolean;
+}
+
+/** Navigation helper for a single route */
+interface RouteNav<Path extends string> {
+    push(
+        params?: ExtractParams<Path>,
+        query?: Record<string, any>,
+        navigationContext?: any
+    ): Promise<void>;
+    replace(
+        params?: ExtractParams<Path>,
+        query?: Record<string, any>,
+        navigationContext?: any
+    ): Promise<void>;
+    link(
+        params?: ExtractParams<Path>,
+        query?: Record<string, any>
+    ): { route: string; params?: any; query?: any };
+    readonly path: Path;
+}
+
+/** Return type of defineRoutes() */
+interface DefineRoutesResult<T extends Record<string, RouteDefinition>> {
+    routes: Record<string, any>;
+    nav: {
+        [K in keyof T]: RouteNav<T[K]['path']>;
+    };
+    paths: {
+        [K in keyof T]: (
+            params?: ExtractParams<T[K]['path']>,
+            query?: Record<string, any>
+        ) => string;
+    };
+}
+
+/**
+ * Define routes as a single source of truth, returning the routes object
+ * for <Router>, navigation helpers with autocomplete, and path builders.
+ *
+ * @param definitions - Route definitions keyed by name
+ * @returns Routes object, navigation helpers, and path builders
+ *
+ * @example
+ * ```typescript
+ * const { routes, nav, paths } = defineRoutes({
+ *   home: { path: '/', component: Home },
+ *   user: { path: '/user/:id', component: () => import('./User.svelte') },
+ *   about: { path: '/about', component: () => import('./About.svelte') }
+ * })
+ *
+ * // Navigate with autocomplete on route names and params
+ * nav.user.push({ id: 123 })
+ * nav.home.replace()
+ *
+ * // Build URLs for links
+ * paths.user({ id: 123 })  // '/user/123'
+ *
+ * // For use:link action
+ * nav.user.link({ id: 123 })  // { route: 'user', params: { id: 123 } }
+ * ```
+ */
+export function defineRoutes<const T extends Record<string, RouteDefinition>>(
+    definitions: T
+): DefineRoutesResult<T>;

package/src/lib/routes.svelte.js

@@ -7,7 +7,8 @@
  * 3. Use named routes in the link action
  */
 
-import { getParamReplacementPlaceholder } from './utils.svelte.js'
+import { getParamReplacementPlaceholder, push as navPush, replace as navReplace } from './utils.svelte.js'
+import { createRoute } from './wrap.js'
 
 // Route registry - maps route names to path patterns
 let routeRegistry = $state({})
@@ -130,3 +131,77 @@ export function hasRoute(name) {
 export function getRouteByName(name) {
     return routeRegistry[name]
 }
+
+/**
+ * Define routes as a single source of truth, returning the routes object
+ * for <Router>, navigation helpers with autocomplete, and path builders.
+ *
+ * @param {Object.<string, {path: string, component: any, [key: string]: any}>} definitions - Route definitions keyed by name
+ * @returns {{routes: Object, nav: Object, paths: Object}} Routes object, navigation helpers, and path builders
+ *
+ * @example
+ * ```javascript
+ * const { routes, nav, paths } = defineRoutes({
+ *   home: { path: '/', component: Home },
+ *   user: { path: '/user/:id', component: () => import('./User.svelte') },
+ *   about: { path: '/about', component: () => import('./About.svelte'), conditions: [checkAuth] }
+ * })
+ *
+ * // Use routes with Router
+ * <Router {routes} />
+ *
+ * // Navigate with autocomplete
+ * nav.user.push({ id: 123 })
+ * nav.home.replace()
+ *
+ * // Build URLs for links
+ * <a href={paths.user({ id: 123 })} use:link>User 123</a>
+ *
+ * // For use:link action
+ * <a use:link={nav.user.link({ id: 123 })}>User 123</a>
+ * ```
+ */
+export function defineRoutes(definitions) {
+    const routes = {}
+    const routeMap = {}
+    const nav = {}
+    const paths = {}
+
+    for (const [name, config] of Object.entries(definitions)) {
+        const { path, component, ...options } = config
+
+        // Build routes object for <Router>
+        const hasOptions = Object.keys(options).length > 0
+        const isAsync = typeof component === 'function' && component.length === 0
+
+        if (!hasOptions && !isAsync) {
+            // Simple sync component — use directly (no wrap overhead)
+            routes[path] = component
+        } else {
+            // Has options or async component — use createRoute()
+            routes[path] = createRoute({ component, ...options })
+        }
+
+        // Track for named route registration
+        routeMap[name] = path
+
+        // Build nav helper
+        nav[name] = {
+            push: (params, query, navigationContext) =>
+                navPush(name, params, query, navigationContext),
+            replace: (params, query, navigationContext) =>
+                navReplace(name, params, query, navigationContext),
+            link: (params, query) =>
+                ({ route: name, params, query }),
+            path
+        }
+
+        // Build path helper
+        paths[name] = (params, query) => buildUrl(name, params, query)
+    }
+
+    // Register all named routes
+    registerRoutes(routeMap)
+
+    return { routes, nav, paths }
+}

package/src/lib/utils.d.ts

@@ -96,6 +96,51 @@ export function setParamReplacementPlaceholder(value: string): void;
  */
 export function getParamReplacementPlaceholder(): string;
 
+/**
+ * Enable or disable hierarchical route inheritance
+ * Must be called before app initialization
+ *
+ * When enabled, child routes automatically inherit breadcrumbs, permissions,
+ * conditions, and authorization callbacks from parent routes.
+ *
+ * @param value - true to enable hierarchical mode, false for flat mode (default: false)
+ *
+ * @example
+ * ```typescript
+ * import { setHierarchicalRoutesEnabled } from '@keenmate/svelte-spa-router'
+ * setHierarchicalRoutesEnabled(true)
+ * ```
+ */
+export function setHierarchicalRoutesEnabled(value: boolean): void;
+
+/**
+ * Get current hierarchical routes mode
+ *
+ * @returns true if hierarchical mode is enabled
+ */
+export function getHierarchicalRoutesEnabled(): boolean;
+
+/**
+ * Configure automatic referrer tracking in navigationContext
+ * Must be called before app initialization
+ *
+ * @param value - 'never' (default), 'notfound' (404 only), or 'always' (all routes)
+ *
+ * @example
+ * ```typescript
+ * import { setIncludeReferrer } from '@keenmate/svelte-spa-router'
+ * setIncludeReferrer('always')
+ * ```
+ */
+export function setIncludeReferrer(value: 'never' | 'notfound' | 'always'): void;
+
+/**
+ * Get current referrer tracking mode
+ *
+ * @returns Current mode: 'never', 'notfound', or 'always'
+ */
+export function getIncludeReferrer(): 'never' | 'notfound' | 'always';
+
 /**
  * Get the current location path
  *

package/src/lib/utils.svelte.js

@@ -380,29 +380,6 @@ function navigate(location, shouldReplace = false, context = null) {
             // Manually trigger hashchange event
             window.dispatchEvent(new HashChangeEvent('hashchange'))
         } else {
-            // Try to save context in history state for back/forward support
-            let processedNavigationContext = context
-            let shouldSaveContext = true
-
-            try {
-                // First try structured clone
-                if (context !== null) {
-                    structuredClone(context)
-                }
-            } catch {
-                // If structured clone fails, try JSON serialization
-                try {
-                    if (context !== null) {
-                        const jsonString = JSON.stringify(context)
-                        processedNavigationContext = JSON.parse(jsonString)
-                    }
-                } catch (jsonError) {
-                    // If JSON also fails, don't save context
-                    console.warn('Navigation context data cannot be stored in history (not serializable). Navigation context will not persist on back/forward navigation.', jsonError)
-                    shouldSaveContext = false
-                }
-            }
-
             try {
                 // Save CURRENT context (with referrer) to current history entry before navigating
                 const currentContext = navigationContextState
@@ -616,7 +593,7 @@ export async function push(location, param2, param3, param4, param5) {
     }
 
     // Build URL from route if needed
-    let href = opts.route
+    const href = opts.route
         ? buildUrl(opts.route, opts.params, opts.query)
         : opts.href
 
@@ -729,7 +706,7 @@ export async function replace(location, param2, param3, param4, param5) {
     }
 
     // Build URL from route if needed
-    let href = opts.route
+    const href = opts.route
         ? buildUrl(opts.route, opts.params, opts.query)
         : opts.href
 

package/src/lib/vendor/loglevel/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Type definitions for vendored loglevel library
+ */
+
+type LogLevelNames = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
+
+interface MethodFactory {
+    (methodName: string, logLevel: number, loggerName: string): (...args: any[]) => void;
+}
+
+interface Logger {
+    trace(...args: any[]): void;
+    debug(...args: any[]): void;
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+    setLevel(level: LogLevelNames | number): void;
+    getLevel(): number;
+    methodFactory: MethodFactory;
+    getLogger(name: string): Logger;
+}
+
+declare const log: Logger;
+export default log;

package/src/lib/vendor/loglevel/prefix.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Type definitions for vendored loglevel-plugin-prefix
+ */
+
+interface PrefixOptions {
+    format?(level: string, name: string | undefined, timestamp: string): string;
+    timestampFormatter?(date: Date): string;
+}
+
+interface PrefixPlugin {
+    reg(logger: any): void;
+    apply(logger: any, options?: PrefixOptions): void;
+}
+
+declare const prefix: PrefixPlugin;
+export default prefix;

package/src/lib/wrap.js

@@ -101,10 +101,15 @@ export function wrap(args) {
             }
         }
 
+        // Merge title and breadcrumbs into routeContext
+        const zoneRouteContext = { ...(args.routeContext || {}) }
+        if (args.title) zoneRouteContext.title = args.title
+        if (args.breadcrumbs) zoneRouteContext.breadcrumbs = args.breadcrumbs
+
         // Return zone-based route object
         return {
             zones: asyncZones,
-            routeContext: args.routeContext,
+            routeContext: Object.keys(zoneRouteContext).length > 0 ? zoneRouteContext : undefined,
             conditions: (args.conditions && args.conditions.length) ? args.conditions : undefined,
             props: (args.props && Object.keys(args.props).length) ? args.props : {},
             shouldDisplayLoadingOnRouteLoad: args.shouldDisplayLoadingOnRouteLoad || false,
@@ -151,11 +156,16 @@ export function wrap(args) {
         args.asyncComponent.loadingParams = args.loadingParams || undefined
     }
 
+    // Merge title and breadcrumbs into routeContext
+    const mergedRouteContext = { ...(args.routeContext || {}) }
+    if (args.title) mergedRouteContext.title = args.title
+    if (args.breadcrumbs) mergedRouteContext.breadcrumbs = args.breadcrumbs
+
     // Returns an object that contains all the functions to execute too
     // The _sveltesparouter flag is to confirm the object was created by this router
     const obj = {
         component: args.asyncComponent,
-        routeContext: args.routeContext,
+        routeContext: Object.keys(mergedRouteContext).length > 0 ? mergedRouteContext : undefined,
         conditions: (args.conditions && args.conditions.length) ? args.conditions : undefined,
         props: (args.props && Object.keys(args.props).length) ? args.props : {},
         shouldDisplayLoadingOnRouteLoad: args.shouldDisplayLoadingOnRouteLoad || false,