@zenithcore/core/src/core/router/README.md

Core functionality for ZenithKernel framework

# 🌊 ZenithRouter - Advanced Quantum-Safe Routing System

**The world's most advanced TypeScript router with zero-knowledge proof integration, ECS data binding, and quantum consensus support.**

## 🚀 Overview

ZenithRouter transcends traditional routing by integrating:

- **🔐 Zero-Knowledge Proof Authentication** - Route-level ZKP verification
- **⚛️ Quantum Consensus Integration** - Distributed decision making for route access
- **🧠 ECS Data Binding** - Direct Entity Component System integration
- **🏝️ Hydra Component Support** - Decentralized UI component hydration
- **🦀 WASM Security** - Sandboxed WebAssembly module execution
- **📊 Real-time State Management** - RxJS + Signals integration
- **🚄 Performance Optimized** - Compile-time route optimization and SWR caching

## 📦 Installation

```bash
npm install @zenithkernel/router
# or
pnpm add @zenithkernel/router
```

## 🎯 Quick Start

### Basic Setup

```typescript
import { createZenithRouter, RouterProvider, RouterOutlet } from '@zenithkernel/router';
import { ZenithKernel } from '@zenithkernel/core';

// Initialize kernel and router
const kernel = new ZenithKernel();
const routerIntegration = createZenithRouter(kernel);
const router = routerIntegration.getRouter();

// Define routes
const routes = [
  {
    path: '/',
    component: () => import('./pages/Home')
  },
  {
    path: '/profile/:userId',
    component: () => import('./pages/Profile'),
    loader: async (params) => ({
      user: await fetchUser(params.userId)
    })
  }
];

router.register(routes);

// App component
function App() {
  return (
    <RouterProvider router={router}>
      <RouterOutlet />
    </RouterProvider>
  );
}
```

### Type-Safe Navigation

```typescript
// Create type-safe navigators
const navigateToProfile = router.createNavigator('/profile/:userId');

// Navigate with compile-time parameter validation
await navigateToProfile({ userId: '123' });

// Hook-based navigation
function MyComponent() {
  const navigate = useNavigate();
  const params = useParams<{ userId: string }>();
  const query = useQuery<{ tab?: string }>();
  
  return (
    <div>
      <h1>User: {params.userId}</h1>
      <button onClick={() => navigate('/dashboard')}>
        Go to Dashboard
      </button>
    </div>
  );
}
```

## 🔐 Zero-Knowledge Proof Routes

### ZK-Protected Routes

```typescript
import { CommonGuards } from '@zenithkernel/router';

// Register routes with ZK verification
routerIntegration.registerHydraRoutes([
  {
    path: '/secure/vault',
    hydraId: 'SecureVault',
    execType: 'edge',
    zkRequired: true,
    trustLevel: 'verified',
    meta: {
      title: 'Secure Vault',
      requiresAuth: true
    }
  }
]);
```

### Secure Navigation with ZK

```typescript
// Navigate with ZK proof verification
await routerIntegration.navigateSecure(
  '/secure/vault',
  { peerId: 'user123' },
  {
    zkProof: 'zk:verified:abc123',
    trustLevel: 'verified'
  }
);

// Check ZK status
const zkStatus = routerIntegration.getZKStatus();
// 'pending' | 'verified' | 'failed' | null
```

## 🔮 Future Roadmap

- **🌍 P2P Route Discovery** - Decentralized route sharing via qDHT
- **🧬 Genetic Route Optimization** - AI-powered route performance optimization
- **🔄 Time-Travel Debugging** - Route state time-travel for debugging
- **🌐 Multi-Dimensional Routing** - Quantum superposition route states
- **🚀 Instant Route Materialization** - Zero-latency route transitions

## 📚 API Reference

Detailed API documentation available at [docs.zenithkernel.dev/router](https://docs.zenithkernel.dev/router)

## 🤝 Contributing

Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

## 📄 License

MIT License - see [LICENSE.md](./LICENSE.md)

---

**Built with ❤️ for the quantum-decentralized future** 🌊⚡🔮