native-document 1.0.165 → 1.0.168

package/docs/routing.md

@@ -1,826 +1,417 @@
-# Routing
+---
+title: Routing
+description: Build single-page applications with NativeDocument's full-featured router - hash, history, and memory modes with layouts, middlewares, and named routes
+---
 
-NativeDocument's routing system enables building single-page applications with client-side navigation. The router automatically manages URL changes, renders appropriate components, and maintains application state without full page reloads.
+# Routing
 
-## Understanding Routing
+NativeDocument's routing system enables single-page applications with client-side navigation. The router manages URL changes, renders the right components, and maintains application state without full page reloads.
 
-The routing system works by matching URL patterns against registered routes and rendering corresponding components. When users navigate, the router updates the view while preserving application state and providing smooth transitions.
+## Setup
 
 ```javascript
-import { Router } from 'native-document/router';
+import { Router, Link } from 'native-document/router';
 
-// Create router and define routes
-const router = Router.create({ mode: 'history' }, (router) => {
+Router.create({ name: 'default', mode: 'history' }, (router) => {
     router.add('/', HomePage);
     router.add('/about', AboutPage);
     router.add('/users/{id}', UserProfile);
 });
-
-// Mount to DOM
-router.mount('#app');
 ```
 
 ## Router Modes
 
-NativeDocument supports three routing modes for different deployment scenarios:
+### History mode (recommended)
 
-### History Mode (Recommended)
-
-Uses HTML5 History API for clean URLs without hash symbols:
+Uses the HTML5 History API for clean URLs:
 
 ```javascript
-const router = Router.create({ mode: 'history' }, (router) => {
-    router.add('/', () => Div('Home Page'));
-    router.add('/products', () => Div('Product List'));
-    router.add('/contact', () => Div('Contact Us'));
+Router.create({ name: 'app', mode: 'history' }, (router) => {
+    router.add('/', HomePage);
+    router.add('/products', ProductList);
 });
-
-// URLs: /products, /contact, /users/123
+// URLs: /products, /users/123
 ```
 
-### Hash Mode
+### Hash mode
 
-Uses URL fragments for compatibility with static hosting:
+Uses URL fragments - compatible with static hosting:
 
 ```javascript
-const router = Router.create({ mode: 'hash' }, (router) => {
-    router.add('/', () => Div('Home Page'));
-    router.add('/dashboard', () => Div('Dashboard'));
+Router.create({ name: 'app', mode: 'hash' }, (router) => {
+    router.add('/', HomePage);
+    router.add('/dashboard', Dashboard);
 });
-
 // URLs: #/dashboard, #/users/456
 ```
 
-### Memory Mode
+### Memory mode
 
-Keeps routing state in memory without URL changes (useful for testing):
+Keeps routing state in memory without changing the URL - useful for testing or embedded flows:
 
 ```javascript
-const router = Router.create({ mode: 'memory' }, (router) => {
-    router.add('/', () => Div('Test Home'));
-    router.add('/test', () => Div('Test Page'));
+Router.create({ name: 'app', mode: 'memory' }, (router) => {
+    router.add('/', HomePage);
+    router.add('/step2', Step2);
 });
-
-// URLs don't change, navigation happens programmatically
 ```
 
-## Basic Route Definition
+---
 
-Routes map URL patterns to component functions that receive navigation data:
+## Defining Routes
 
 ```javascript
-const router = Router.create({ mode: 'history' }, (router) => {
+Router.create({ name: 'app', mode: 'history' }, (router) => {
     // Static routes
-    router.add('/', () => Div('Welcome to our site'));
-    router.add('/about', () => Div('About our company'));
-    
-    // Routes with parameters
-    router.add('/users/{id}', ({ params }) => 
-        Div(['User Profile for ID: ', params.id])
+    router.add('/', HomePage);
+    router.add('/about', AboutPage);
+
+    // Route with parameter
+    router.add('/users/{id}', ({ params }) =>
+        Div(['User: ', params.id])
     );
-    
+
     // Multiple parameters
-    router.add('/posts/{category}/{slug}', ({ params }) => 
-        Div([
-            'Category: ', params.category,
-            ', Post: ', params.slug
-        ])
+    router.add('/posts/{category}/{slug}', ({ params }) =>
+        BlogPost({ category: params.category, slug: params.slug })
     );
+
+    // Catch-all 404 (must be last)
+    router.add('{*}', NotFoundPage);
 });
 ```
 
-## Route Parameters
+---
 
-Extract dynamic values from URLs using parameter syntax:
+## Route Parameters
 
-### Basic Parameters
+### Basic parameters
 
 ```javascript
-router.add('/users/{userId}', ({ params }) => {
-    const user = getUserById(params.userId);
-    return UserProfileComponent(user);
-});
-
-router.add('/blog/{year}/{month}', ({ params }) => {
-    return BlogArchive({
-        year: parseInt(params.year),
-        month: parseInt(params.month)
-    });
-});
-```
-
-### Parameter Validation
-
-Define custom patterns for parameter validation:
+router.add('/users/{id}', ({ params }) => UserProfile(params.id));
 
-```javascript
-// Define global patterns
-RouteParamPatterns.number = '[0-9]+';
-
-const router = Router.create({ mode: 'history' }, (router) => {
-    // Only numeric IDs - inline pattern
-    router.add('/users/{id}', ({ params }) => 
-        UserProfile(params.id), 
-        { with: { id: '[0-9]+' }}
-    );
-    
-    // OR using global pattern
-    router.add('/users/{id:number}', ({ params }) => 
-        UserProfile(params.id)
-    );
-    
-    // Custom patterns - inline
-    router.add('/posts/{slug}', ({ params }) => 
-        BlogPost(params.slug),
-        { with: { slug: '[a-z0-9-]+' }}
-    );
-    
-    // OR define and use pattern
-    RouteParamPatterns.slug = '[a-z0-9-]+';
-    router.add('/posts/{slug:slug}', ({ params }) => 
-        BlogPost(params.slug)
-    );
-});
+router.add('/blog/{year}/{month}', ({ params }) =>
+    BlogArchive({ year: parseInt(params.year), month: parseInt(params.month) })
+);
 ```
 
-## Query Parameters
+### Parameter validation
 
-Access URL query strings through the query object:
+Use `{ with: { paramName: pattern } }` to restrict a parameter to a regex pattern:
 
 ```javascript
-router.add('/search', ({ query }) => {
-    const { term, category, page = 1 } = query;
-    
-    return SearchResults({
-        searchTerm: term,
-        category: category,
-        currentPage: parseInt(page)
-    });
-});
+// Inline pattern - only numeric ids
+router.add('/users/{id}', UserProfile, { with: { id: '[0-9]+' } });
 
-// URL: /search?term=javascript&category=tutorials&page=2
-// query = { term: 'javascript', category: 'tutorials', page: '2' }
+// Slug pattern
+router.add('/posts/{slug}', BlogPost, { with: { slug: '[a-z0-9-]+' } });
 ```
 
-## Navigation
-
-Navigate programmatically using router methods:
-
-### Push Navigation
-
-Add new entries to browser history. **Specify router name** when using multiple routers:
+You can also register patterns globally via `RouteParamPatterns` and reference them as `{param:patternName}`:
 
 ```javascript
-const NavigationExample = Div([
-    Button('Go to About').nd.onClick(() => {
-        Router.push('/about'); // Uses default router
-    }),
-    
-    Button('Go to About (Main Router)').nd.onClick(() => {
-        Router.push('/about', 'main'); // Uses named router
-    }),
-    
-    Button('View User 123').nd.onClick(() => {
-        // Navigate in specific router
-        Router.push('/users/123', 'app');
-    }),
-    
-    Button('Search Products').nd.onClick(() => {
-        Router.push('/search?term=laptop&category=electronics', 'main');
-    })
-]);
+import { RouteParamPatterns } from 'native-document/router';
 ```
 
-### Replace Navigation
-
-Replace current history entry without adding to stack:
+Built-in patterns:
+
+| Name | Pattern | Matches |
+|---|---|---|
+| `id` | `[0-9]+` | Numeric IDs |
+| `uuid` | `[0-9a-f]{8}-...` | UUIDs |
+| `slug` | `[a-z0-9]+(?:-[a-z0-9]+)*` | URL slugs |
+| `hash` | `[a-f0-9]{32,64}` | MD5/SHA hashes |
+| `alpha` | `[a-zA-Z]+` | Letters only |
+| `alphanum` | `[a-zA-Z0-9]+` | Letters and digits |
+| `string` | `[^/]+` | Any non-slash string |
+| `any` | `.*` | Anything including slashes |
+| `int` | `[0-9]+` | Integers |
+| `float` | `[0-9]+\.[0-9]+` | Floats |
+| `number` | `[0-9]+(\.[0-9]+)?` | Integers or floats |
+| `positive` | `[1-9][0-9]*` | Positive integers (no zero) |
+| `locale` | `[a-z]{2}(-[A-Z]{2})?` | Locale codes (`fr`, `en-US`) |
+| `lang` | `[a-z]{2}` | Language codes (`fr`, `en`) |
+| `token` | `[A-Za-z0-9_\-]+` | Tokens and API keys |
 
 ```javascript
-const LoginRedirect = () => {
-    // Redirect after login without allowing back navigation
-    Router.replace('/dashboard'); // Default router
-    
-    // Or specify router
-    Router.replace('/dashboard', 'main');
-    
-    return Div('Redirecting...');
-};
+router.add('/users/{id:id}',         UserProfile);  // numeric only
+router.add('/posts/{slug:slug}',     BlogPost);      // url-safe slug
+router.add('/files/{hash:hash}',     FileView);      // hash string
+router.add('/lang/{code:locale}',    LocalePage);    // fr, en-US
 ```
 
-### History Navigation
-
-Navigate through browser history:
+You can also extend `RouteParamPatterns` with your own:
 
 ```javascript
-const HistoryControls = Div([
-    Button('Go Back').nd.onClick(() => Router.back()), // Default router
-    Button('Go Forward').nd.onClick(() => Router.forward()), // Default router
-    
-    // Navigate specific router's history
-    Button('Back in Main').nd.onClick(() => Router.back('main')),
-    Button('Forward in Admin').nd.onClick(() => Router.forward('admin'))
-]);
+RouteParamPatterns.year  = '[0-9]{4}';
+RouteParamPatterns.color = '[0-9a-fA-F]{6}';
+
+router.add('/archive/{year:year}', ArchivePage);
 ```
 
-## Named Routes
+---
 
-Name routes for easier URL generation and maintenance:
+## Query Parameters
 
 ```javascript
-const router = Router.create({ mode: 'history' }, (router) => {
-    router.add('/', HomePage, { name: 'home' });
-    router.add('/users/{id}', UserProfile, { name: 'user.profile' });
-    router.add('/posts/{category}/{slug}', BlogPost, { name: 'blog.post' });
+router.add('/search', ({ query }) => {
+    const { term, category, page = '1' } = query;
+    return SearchResults({ term, category, page: parseInt(page) });
 });
-
-// Generate URLs by name
-const userUrl = router.generateUrl('user.profile', { id: 123 });
-// Result: '/users/123'
-
-const blogUrl = router.generateUrl('blog.post', { category: 'javascript', slug: 'getting-started' }, { ref: 'newsletter' });
-// Result: '/posts/javascript/getting-started?ref=newsletter'
+// URL: /search?term=javascript&category=tutorials&page=2
 ```
 
-### Navigation with Named Routes
-
-```javascript
-const navigation = Div([
-    Button('Home').nd.onClick(() => 
-        Router.push({ name: 'home' }) // Uses router containing this route
-    ),
-    
-    Button('My Profile').nd.onClick(() => 
-        Router.push({ 
-            name: 'user.profile', 
-            params: { id: currentUser.id } 
-        }, 'main') // Specify router if needed
-    ),
-    
-    Button('Latest Post').nd.onClick(() => 
-        Router.push({
-            name: 'blog.post',
-            params: { category: 'news', slug: 'latest-update' },
-            query: { highlight: 'new-features' }
-        }, 'blog') // Navigate in blog router
-    )
-]);
-```
+---
 
 ## Route Groups
 
 Organize related routes with shared configuration:
 
 ```javascript
-const router = Router.create({ mode: 'history' }, (router) => {
-    // Admin routes with auth middleware
-    router.group('/admin', { middlewares: [requireAuth, requireAdmin] }, () => {
-        router.add('/', AdminDashboard, { name: 'admin.dashboard' });
-        router.add('/users', AdminUsers, { name: 'admin.users' });
-        router.add('/settings', AdminSettings, { name: 'admin.settings' });
+Router.create({ name: 'app', mode: 'history' }, (router) => {
+
+    // Group with layout
+    router.group('', { layout: DefaultLayout }, () => {
+        router.add('/', HomePage, { name: 'home' });
+        router.add('/about', AboutPage, { name: 'about' });
     });
-    
-    // User dashboard with nested naming
-    router.group('/dashboard', { name: 'dashboard' }, () => {
-        router.add('/', UserDashboard, { name: 'home' }); // dashboard.home
-        router.add('/profile', UserProfile, { name: 'profile' }); // dashboard.profile
-        router.add('/settings', UserSettings, { name: 'settings' }); // dashboard.settings
+
+    // Group with middleware and name prefix
+    router.group('/admin', { middlewares: [requireAuth], name: 'admin' }, () => {
+        router.add('/', AdminDashboard, { name: 'dashboard' }); // admin.dashboard
+        router.add('/users', AdminUsers, { name: 'users' });    // admin.users
     });
+
 });
 ```
 
-## Middleware
+---
 
-Add logic that runs before route components are rendered:
+## Named Routes
 
-### Authentication Middleware
+Naming routes lets you generate URLs and navigate without hardcoding paths:
 
 ```javascript
-const requireAuth = (context, next) => {
-    const { route, params, query, path } = context;
-    
-    if (!isUserAuthenticated()) {
-        // Redirect to login with return path
-        Router.replace({
-            name: 'auth.login',
-            query: { redirect: path }
-        });
-        return;
-    }
-    
-    // Continue to route component
-    next();
-};
-
-const requireAdmin = (context, next) => {
-    if (!isUserAdmin()) {
-        Router.replace({ name: 'errors.forbidden' });
-        return;
-    }
-    next();
-};
-```
+Router.create({ name: 'app', mode: 'history' }, (router) => {
+    router.add('/', HomePage,                      { name: 'home' });
+    router.add('/users/{id}', UserProfile,         { name: 'user.profile' });
+    router.add('/posts/{category}/{slug}', BlogPost, { name: 'blog.post' });
+});
 
-### Loading States
+// Generate a URL by name
+const router = Router.get('app');
+router.generateUrl('user.profile', { id: 123 });
+// -> '/users/123'
 
-```javascript
-const loadingMiddleware = (context, next) => {
-    // Show loading indicator
-    showGlobalLoader();
-    
-    // Continue to route component
-    next();
-    
-    // Hide loading indicator
-    setTimeout(() => hideGlobalLoader(), 100);
-};
+router.generateUrl('blog.post',
+    { category: 'javascript', slug: 'getting-started' },
+    { ref: 'newsletter' }
+);
+// -> '/posts/javascript/getting-started?ref=newsletter'
 ```
 
-### Analytics Tracking
-
-```javascript
-const analyticsMiddleware = (context, next) => {
-    const { route, params, path } = context;
-    
-    // Track page view
-    analytics.track('page_view', {
-        path: path,
-        route_name: route.name(),
-        timestamp: Date.now()
-    });
-    
-    next();
-};
-```
+---
 
-## Link Component
+## Navigation
 
-Create navigational links that integrate with the router:
+### `Router.push(target, routerName?)`
 
-### Basic Links
+Add a new entry to the browser history:
 
 ```javascript
-import { Link } from 'native-document/router';
+Router.push('/about');              // path - uses default router
+Router.push('/about', 'app');       // path - named router
 
-const Navigation = Nav([
-    Link({ to: '/' }, 'Home'),
-    Link({ to: '/about' }, 'About'),
-    Link({ to: '/contact' }, 'Contact'),
-    
-    // External links open in new tab
-    Link.blank({ href: 'https://example.com' }, 'External Site')
-]);
+Router.push({ name: 'home' });      // named route
+Router.push({ name: 'user.profile', params: { id: 42 } }, 'app');
+Router.push({ name: 'search', query: { term: 'laptop' } });
 ```
 
-### Links with Router Specification
+### `Router.replace(target, routerName?)`
 
-```javascript
-const UserMenu = Div([
-    Link({ 
-        to: { 
-            name: 'user.profile', 
-            params: { id: currentUser.id },
-            router: 'main' // Specify which router to use
-        } 
-    }, 'My Profile'),
-    
-    Link({
-        to: {
-            name: 'user.settings',
-            params: { id: currentUser.id },
-            query: { tab: 'preferences' },
-            router: 'main'
-        }
-    }, 'Settings'),
-    
-    // Cross-router navigation
-    Link({
-        to: {
-            name: 'admin.dashboard',
-            router: 'admin'
-        }
-    }, 'Admin Panel')
-]);
-```
-
-### Active Link Styling
+Replace the current history entry without adding to the stack:
 
 ```javascript
-const NavItem = (path, text, routerName = null) => {
-    const router = Router.get(routerName);
-    const isActive = Observable(router.currentState().path === path);
-    router.subscribe((state) => {
-        isActive.set(state.path === path);
-    });
-
-    return Link({
-        to: path,
-        class: { 'nav-link': true, 'active': isActive }
-    }, text);
-};
-
-const MainNav = Nav([
-    NavItem('/', 'Home', 'main'),
-    NavItem('/products', 'Products', 'main'),
-    NavItem('/services', 'Services', 'main')
-]);
-
-// Multi-router navigation
-const AppNav = Nav([
-    NavItem('/', 'Main App', 'main'),
-    NavItem('/admin', 'Admin', 'admin'),
-    NavItem('/blog', 'Blog', 'blog')
-]);
-
+Router.replace('/dashboard');
+Router.replace({ name: 'login', query: { redirect: '/dashboard' } });
 ```
 
-## Multiple Routers
+### `Router.redirectTo(pathOrRouteName, params?, routerName?)`
 
-Create separate router instances for different application areas. **Always name your routers** to avoid conflicts and enable proper navigation.
+Redirect to a path or named route. If a route name is found, it navigates by name; otherwise it treats the argument as a path:
 
 ```javascript
-// Main application router (named)
-const mainRouter = Router.create(
-    { mode: 'history', name: 'main' },
-    (router) => {
-        router.add('/', HomePage);
-        router.add('/products', ProductList);
-        router.add('/admin', AdminApp);
-    }
-);
-
-// Admin-specific router (named)
-const adminRouter = Router.create(
-    { mode: 'history', name: 'admin', entry: '/admin' },
-    (router) => {
-        router.add('/', AdminDashboard);
-        router.add('/users', AdminUsers);
-        router.add('/reports', AdminReports);
-    }
-);
-
-// Access routers by name
-const mainRouter = Router.get('main');
-const adminRouter = Router.get('admin');
-
-// Or access via routers object
-const mainRouter = Router.routers.main;
-const adminRouter = Router.routers.admin;
-
-// Cross-router navigation
-Button('Go to Admin').nd.onClick(() => {
-    Router.push('/admin/users', 'admin'); // Specify router name
-});
-
-Button('Back to Main').nd.onClick(() => {
-    Router.push('/', 'main'); // Navigate in main router
-});
+Router.redirectTo('home');
+Router.redirectTo('user.profile', { id: 42 });
+Router.redirectTo('/legacy-path');
 ```
 
-### Router Naming Best Practices
+### `Router.back(routerName?)` / `Router.forward(routerName?)`
 
-**Always name your routers** to prevent conflicts and enable reliable navigation:
+Navigate through browser history:
 
 ```javascript
-// ❌ BAD: Unnamed router (becomes default)
-const router1 = Router.create({ mode: 'history' }, (router) => {
-    // This becomes the default router
-});
-
-// ❌ BAD: Multiple unnamed routers cause conflicts
-const router2 = Router.create({ mode: 'history' }, (router) => {
-    // This overwrites the default router!
-});
-
-// ✅ GOOD: Named routers
-const appRouter = Router.create({ mode: 'history', name: 'app' }, (router) => {
-    router.add('/', HomePage);
-});
-
-const modalRouter = Router.create({ mode: 'memory', name: 'modal' }, (router) => {
-    router.add('/confirm', ConfirmDialog);
-});
+Button('Back').nd.onClick(() => Router.back());
+Button('Forward').nd.onClick(() => Router.forward('app'));
 ```
 
-### Default Router Access
+---
 
-When no name is specified, Router.get() returns the router named "default":
-
-```javascript
-// Create default router
-Router.create({ mode: 'history' }, (router) => {
-    router.add('/', HomePage);
-});
+## Link Component
 
-// Access default router (named "default" internally)
-const defaultRouter = Router.get(); // Returns router named "default"
-const defaultRouter = Router.get('default'); // Same as above
-const defaultRouter = Router.routers.default; // Direct access
+`to` takes a route **name** (string) or an object with `name`, `params`, `query`, and `router`. Use `href` for direct path links:
 
-// Navigate using default router
-Router.push('/'); // Uses "default" router
-Router.push('/', 'default'); // Explicitly use default router
-```
+```javascript
+import { Link } from 'native-document/router';
 
-### Router Naming Best Practices
+// Named route
+Link({ to: 'home' }, 'Home')
 
-**Always name your routers explicitly** to avoid relying on the default:
+// Named route with params
+Link({ to: { name: 'user.profile', params: { id: 42 } } }, 'Profile')
 
-```javascript
-// ❌ BAD: Unnamed router (becomes "default")
-const router1 = Router.create({ mode: 'history' }, (router) => {
-    // This is stored as Router.routers.default
-});
+// Named route with query
+Link({ to: { name: 'search', query: { term: 'js' } } }, 'Search')
 
-// ❌ BAD: Multiple unnamed routers cause conflicts
-const router2 = Router.create({ mode: 'history' }, (router) => {
-    // This overwrites Router.routers.default!
-});
+// Named route on a specific router
+Link({ to: { name: 'admin.dashboard', router: 'admin' } }, 'Admin')
 
-// ✅ GOOD: Named routers
-const appRouter = Router.create({ mode: 'history', name: 'app' }, (router) => {
-    router.add('/', HomePage);
-    // Stored as Router.routers.app
-});
+// Direct path link
+Link({ href: '/about' }, 'About')
 
-const modalRouter = Router.create({ mode: 'memory', name: 'modal' }, (router) => {
-    router.add('/confirm', ConfirmDialog);
-    // Stored as Router.routers.modal
-});
+// External link - opens in new tab
+Link.blank({ href: 'https://example.com' }, 'External')
 ```
 
-## Route Guards and Data Loading
+---
 
-Implement route guards and data preloading:
+## Middleware
 
-### Route-Specific Data Loading
+Middleware runs before the route component is rendered. It receives a `context` object and a `next` function:
 
 ```javascript
-const UserProfile = ({ params }) => {
-    const userId = params.id;
-    const user = Observable(null);
-    const loading = Observable(true);
-    const error = Observable(null);
-    
-    // Load user data
-    fetchUser(userId)
-        .then(userData => {
-            user.set(userData);
-            loading.set(false);
-        })
-        .catch(err => {
-            error.set(err.message);
-            loading.set(false);
-        });
-    
-    return Match(loading, {
-        true: LoadingSpinner,
-        false: () => Switch(error, ErrorMessage(error), UserProfileView(user) )
-    });
+const requireAuth = (context, next) => {
+    const { path } = context;
+    if (!isAuthenticated()) {
+        Router.replace({ name: 'login', query: { redirect: path } });
+        return; // stop - don't call next()
+    }
+    next();
 };
 
-router.add('/users/{id}', UserProfile, { name: 'user.profile' });
+const analytics = (context, next) => {
+    trackPageView(context.path);
+    next();
+};
 ```
 
-### Global Route Guards
+Apply middleware to a group or individual route:
 
 ```javascript
-const authGuard = (context, next) => {
-    const { route } = context;
-    const protectedRoutes = ['dashboard', 'profile', 'settings'];
-    
-    if (protectedRoutes.includes(route.name()) && !isAuthenticated()) {
-        Router.replace({ 
-            name: 'login', 
-            query: { redirect: context.path } 
-        });
-        return;
-    }
-    
-    next();
-};
+Router.create({ name: 'app', mode: 'history' }, (router) => {
+
+    router.add('/', HomePage, { name: 'home' });
+
+    router.group('/dashboard', { middlewares: [requireAuth, analytics] }, () => {
+        router.add('/', Dashboard, { name: 'dashboard' });
+        router.add('/settings', Settings, { name: 'settings' });
+    });
+
+    // Route-level middleware
+    router.add('/admin', AdminPage, {
+        name: 'admin',
+        middlewares: [requireAuth, requireAdmin]
+    });
 
-// Add to all routes that need protection
-router.group('/', { middlewares: [authGuard] }, () => {
-    router.add('/dashboard', Dashboard, { name: 'dashboard' });
-    router.add('/profile', Profile, { name: 'profile' });
-    router.add('/settings', Settings, { name: 'settings' });
 });
 ```
 
-## Error Handling
+---
 
-Handle routing errors gracefully:
+## Multiple Routers
 
-### 404 - Route Not Found
+Always name your routers to avoid conflicts:
 
 ```javascript
-const router = Router.create({ mode: 'history' }, (router) => {
+Router.create({ name: 'main', mode: 'history' }, (router) => {
     router.add('/', HomePage);
-    router.add('/about', AboutPage);
-    
-    // Catch-all route for 404s (must be last)
-    router.add('.*', ({ params }) => 
-        NotFoundPage({ attemptedPath: params.path })
-    );
+    router.add('/products', ProductList);
 });
 
-const NotFoundPage = ({ attemptedPath }) => Div([
-    H1('Page Not Found'),
-    P(['The page "', attemptedPath, '" could not be found.']),
-    Link({ to: '/' }, 'Return Home')
-]);
-```
+Router.create({ name: 'admin', mode: 'history', entry: '/admin' }, (router) => {
+    router.add('/', AdminDashboard);
+    router.add('/users', AdminUsers);
+});
 
-### Error Boundaries
+// Access by name
+const main  = Router.get('main');
+const admin = Router.get('admin');
 
-```javascript
-const errorHandler = (context, next) => {
-    try {
-        next();
-    } catch (error) {
-        console.error('Route error:', error);
-        
-        // Navigate to error page
-        Router.replace({
-            name: 'error',
-            query: { message: error.message }
-        });
-    }
-};
+// Or via the routers object (plain object, not reactive)
+Router.routers.main;
+Router.routers.admin;
 
-router.add('/error', ({ query }) => 
-    ErrorPage({ message: query.message })
-);
+// Navigate in a specific router
+Button('Go to admin').nd.onClick(() => Router.push('/admin/users', 'admin'));
 ```
 
-## Real-World Examples
+> Two unnamed routers would both be stored as `Router.routers.default` - the second would overwrite the first.
 
-### E-commerce Application
+---
+
+## Current State
 
 ```javascript
-const ecommerceRouter = Router.create({ mode: 'history' }, (router) => {
-    // Public routes
-    router.add('/', HomePage, { name: 'home' });
-    router.add('/products', ProductCatalog, { name: 'products' });
-    router.add('/products/{category}', CategoryPage, { name: 'category' });
-    router.add('/products/{category}/{id}', ProductDetail, { name: 'product' });
-    
-    // User account routes
-    router.group('/account', { middlewares: [requireAuth] }, () => {
-        router.add('/', AccountDashboard, { name: 'account.dashboard' });
-        router.add('/orders', OrderHistory, { name: 'account.orders' });
-        router.add('/profile', UserProfile, { name: 'account.profile' });
-        router.add('/addresses', AddressBook, { name: 'account.addresses' });
-    });
-    
-    // Shopping cart
-    router.add('/cart', ShoppingCart, { name: 'cart' });
-    router.add('/checkout', CheckoutProcess, { name: 'checkout', middlewares: [requireAuth] });
-    
-    // Search and filters
-    router.add('/search', SearchResults, { name: 'search' });
-    // URL: /search?q=laptop&category=electronics&price_min=100&price_max=1000
-});
+const router = Router.get('app');
 
-// Product component with category navigation
-const ProductDetail = ({ params, query }) => {
-    const { category, id } = params;
-    const product = Observable(null);
-    
-    loadProduct(id).then(data => product.set(data));
-    
-    return ShowIf(product, () => {
-        const p = product.val();
-        return Div([
-            // Breadcrumb navigation
-            Nav([
-                Link({ to: { name: 'home' } }, 'Home'),
-                ' > ',
-                Link({ to: { name: 'category', params: { category } } }, category),
-                ' > ',
-                Span(p.name)
-            ]),
-            
-            // Product details
-            H1(p.name),
-            Div({ class: 'price' }, p.price),
-            P(p.description),
-            
-            // Add to cart with redirect to login if needed
-            Button('Add to Cart').nd.onClick(() => {
-                if (!isAuthenticated()) {
-                    Router.push({
-                        name: 'login',
-                        query: { 
-                            redirect: Router.get().currentState().path 
-                        }
-                    });
-                } else {
-                    addToCart(p.id);
-                    Router.push({ name: 'cart' });
-                }
-            })
-        ]);
-    });
-};
+// Read current state
+const { route, params, query, path, hash } = router.currentState();
+
+// Subscribe to navigation changes
+router.subscribe(state => {
+    console.log('Navigated to:', state.path);
+});
 ```
 
-### Multi-Step Form with Navigation
+---
+
+## Error Handling
 
 ```javascript
-const formRouter = Router.create({ mode: 'hash' }, (router) => {
-    const formData = Observable.object({
-        step1: { name: '', email: '' },
-        step2: { address: '', city: '' },
-        step3: { payment: '', terms: false }
-    });
-    
-    router.add('/form/personal', () => 
-        PersonalInfoStep(formData), 
-        { name: 'form.personal' }
-    );
-    
-    router.add('/form/address', () => 
-        AddressStep(formData), 
-        { name: 'form.address', middlewares: [validateStep1] }
-    );
-    
-    router.add('/form/payment', () => 
-        PaymentStep(formData), 
-        { name: 'form.payment', middlewares: [validateStep1, validateStep2] }
-    );
-    
-    router.add('/form/review', () => 
-        ReviewStep(formData), 
-        { name: 'form.review', middlewares: [validateAllSteps] }
-    );
-});
+Router.create({ name: 'app', mode: 'history' }, (router) => {
+    router.add('/', HomePage);
 
-const FormNavigation = (currentStep, formData) => {
-    const steps = ['personal', 'address', 'payment', 'review'];
-    const currentIndex = steps.indexOf(currentStep);
-    
-    return Div({ class: 'form-navigation' }, [
-        // Step indicator
-        Div({ class: 'step-indicator' }, 
-            steps.map((step, index) => 
-                Span({ 
-                    class: index <= currentIndex ? 'step active' : 'step'
-                }, step)
-            )
-        ),
-        
-        // Navigation buttons
-        Div({ class: 'nav-buttons' }, [
-            ShowIf(Observable(currentIndex > 0), 
-                Button('Previous').nd.onClick(() => {
-                    const prevStep = steps[currentIndex - 1];
-                    Router.push({ name: `form.${prevStep}` });
-                })
-            ),
-            
-            ShowIf(Observable(currentIndex < steps.length - 1),
-                Button('Next').nd.onClick(() => {
-                    const nextStep = steps[currentIndex + 1];
-                    Router.push({ name: `form.${nextStep}` });
-                })
-            ),
-            
-            ShowIf(Observable(currentIndex === steps.length - 1),
-                Button('Submit').nd.onClick(() => {
-                    submitForm(formData.$value);
-                })
-            )
+    // Catch-all - must be last
+    router.add('{*}', ({ params }) =>
+        Div([
+            H1('Page not found'),
+            Link({ href: '/' }, 'Go home')
         ])
-    ]);
-};
+    );
+});
 ```
 
+---
+
 ## Best Practices
 
-1. **Use named routes** for maintainable URL generation
-2. **Group related routes** with shared middleware
-3. **Validate parameters** to prevent runtime errors
-4. **Handle loading states** in data-dependent routes
-5. **Implement proper error boundaries** for robust navigation
-6. **Use middleware** for cross-cutting concerns like authentication
-7. **Keep route components focused** - extract complex logic to separate modules
-8. **Test navigation flows** with different router modes
+1. Always name your routers - unnamed routers default to `'default'` and will conflict
+2. Use named routes for all `Link` and `push` calls - avoids hardcoded paths
+3. Use `router.group()` for shared middleware and layout
+4. Use `Router.replace()` after login or form submission to avoid back-button issues
+5. Define the catch-all `{*}` route last
 
-## Next Steps
+---
 
-Explore these related topics to build complete applications:
+## Next Steps
 
-- **[State Management](state-management.md)** - Global state patterns
-- **[Lifecycle Events](lifecycle-events.md)** - Lifecycle events
-- **[NDElement](native-document-element.md)** - Native Document Element
-- **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
-- **[Args Validation](validation.md)** - Function Argument Validation
-- **[Memory Management](memory-management.md)** - Memory management
-- **[Anchor](anchor.md)** - Anchor
+- **[State Management](./state-management.md)** - Global state patterns
+- **[Lifecycle Events](./lifecycle-events.md)** - Lifecycle events
+- **[NDElement](./native-document-element.md)** - Native Document Element
+- **[Anchor](./anchor.md)** - Anchor
 
 ## Utilities
 
-- **[Cache](docs/utils/cache.md)** - Lazy initialization and singleton patterns
-- **[NativeFetch](docs/utils/native-fetch.md)** - HTTP client with interceptors
-- **[Filters](docs/utils/filters.md)** - Data filtering helpers
+- **[Cache](./cache.md)** - Lazy initialization and singleton patterns
+- **[NativeFetch](./native-fetch.md)** - HTTP client with interceptors
+- **[Filters](./filters.md)** - Data filtering helpers