@zenithbuild/router 1.0.1

package/README.md

@@ -0,0 +1,127 @@
+# @zenithbuild/router
+
+File-based SPA router for Zenith framework with **deterministic, compile-time route resolution**.
+
+## Features
+
+- 📁 **File-based routing** — Pages in `pages/` directory become routes automatically
+- ⚡ **Compile-time resolution** — Route manifest generated at build time, not runtime
+- 🔗 **ZenLink component** — Declarative navigation with prefetching
+- 🧭 **Programmatic navigation** — `navigate()`, `prefetch()`, `isActive()` APIs
+- 🎯 **Type-safe** — Full TypeScript support with route parameter inference
+- 🚀 **Hydration-safe** — No runtime hacks, works seamlessly with SSR/SSG
+
+## Installation
+
+```bash
+bun add @zenithbuild/router
+```
+
+## Usage
+
+### Programmatic Navigation
+
+```ts
+import { navigate, prefetch, isActive, getRoute } from '@zenithbuild/router'
+
+// Navigate to a route
+navigate('/about')
+
+// Navigate with replace (no history entry)
+navigate('/dashboard', { replace: true })
+
+// Prefetch a route for faster navigation
+prefetch('/blog')
+
+// Check if a route is active
+if (isActive('/blog')) {
+  console.log('Currently on blog section')
+}
+
+// Get current route state
+const { path, params, query } = getRoute()
+```
+
+### ZenLink Component (in .zen files)
+
+```html
+<ZenLink href="/about">About Us</ZenLink>
+
+<!-- With prefetching on hover -->
+<ZenLink href="/blog" preload>Blog</ZenLink>
+
+<!-- External links automatically open in new tab -->
+<ZenLink href="https://github.com">GitHub</ZenLink>
+```
+
+### Build-time Route Manifest
+
+The router generates a route manifest at compile time:
+
+```ts
+import { generateRouteManifest, discoverPages } from '@zenithbuild/router/manifest'
+
+const pagesDir = './src/pages'
+const manifest = generateRouteManifest(pagesDir)
+
+// manifest contains:
+// - path: Route pattern (e.g., /blog/:id)
+// - regex: Compiled RegExp for matching
+// - paramNames: Dynamic segment names
+// - score: Priority for deterministic matching
+```
+
+## Route Patterns
+
+| File Path | Route Pattern |
+|-----------|---------------|
+| `pages/index.zen` | `/` |
+| `pages/about.zen` | `/about` |
+| `pages/blog/index.zen` | `/blog` |
+| `pages/blog/[id].zen` | `/blog/:id` |
+| `pages/posts/[...slug].zen` | `/posts/*slug` |
+| `pages/[[...all]].zen` | `/*all?` (optional) |
+
+## Architecture
+
+```
+@zenithbuild/router
+├── src/
+│   ├── index.ts          # Main exports
+│   ├── types.ts          # Core types
+│   ├── manifest.ts       # Build-time manifest generation
+│   ├── runtime.ts        # Client-side SPA router
+│   └── navigation/
+│       ├── index.ts      # Navigation exports
+│       ├── zen-link.ts   # Navigation API
+│       └── ZenLink.zen   # Declarative component
+```
+
+## API Reference
+
+### Navigation Functions
+
+- `navigate(path, options?)` — Navigate to a path
+- `prefetch(path)` — Prefetch a route for faster navigation
+- `isActive(path, exact?)` — Check if path is currently active
+- `getRoute()` — Get current route state
+- `back()`, `forward()`, `go(delta)` — History navigation
+
+### Manifest Generation
+
+- `discoverPages(pagesDir)` — Find all .zen files in pages directory
+- `generateRouteManifest(pagesDir)` — Generate complete route manifest
+- `filePathToRoutePath(filePath, pagesDir)` — Convert file path to route
+- `routePathToRegex(routePath)` — Compile route to RegExp
+
+### Types
+
+- `RouteState` — Current route state (path, params, query)
+- `RouteRecord` — Compiled route definition
+- `NavigateOptions` — Options for navigation
+- `ZenLinkProps` — Props for ZenLink component
+
+## License
+
+MIT
+# zenith-router

package/index.d.ts

@@ -0,0 +1,38 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+export declare function generateRouteManifestNative(pagesDir: string): Array<RouteRecord>
+export declare function renderRouteNative(inputJson: string): string
+export declare function resolveRouteNative(path: string, routes: Array<RouteRecord>): RouteState | null
+export declare function generateRuntimeRouterNative(): string
+export const enum SegmentType {
+  Static = 0,
+  Dynamic = 1,
+  CatchAll = 2,
+  OptionalCatchAll = 3
+}
+export interface ParsedSegment {
+  segmentType: SegmentType
+  paramName?: string
+  raw: string
+}
+export interface RouteRecord {
+  path: string
+  regex: string
+  paramNames: Array<string>
+  score: number
+  filePath: string
+}
+export interface RouteState {
+  path: string
+  params: Record<string, string>
+  query: Record<string, string>
+  matched?: RouteRecord
+}
+export interface RouteManifest {
+  routes: Array<RouteRecord>
+  generatedAt: number
+}
+export declare function routerBridge(): string

package/index.js

@@ -0,0 +1,5 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const native = require('./zenith-router.node');
+export const { generateRouteManifestNative, renderRouteNative, resolveRouteNative, generateRuntimeRouterNative, SegmentType, routerBridge } = native;
+export default native;

package/package.json

@@ -0,0 +1,65 @@
+{
+    "name": "@zenithbuild/router",
+    "version": "1.0.1",
+    "description": "File-based SPA router for Zenith framework with deterministic, compile-time route resolution",
+    "license": "MIT",
+    "type": "module",
+    "main": "./src/index.ts",
+    "files": [
+        "src",
+        "dist",
+        "tsconfig.json",
+        "index.js",
+        "index.d.ts"
+    ],
+    "napi": {
+        "name": "zenith-router",
+        "package": {
+            "name": "@zenithbuild/router"
+        }
+    },
+    "exports": {
+        ".": "./src/index.ts",
+        "./manifest": "./src/manifest.ts",
+        "./runtime": "./src/runtime.ts",
+        "./navigation": "./src/navigation/index.ts",
+        "./types": "./src/types.ts"
+    },
+    "keywords": [
+        "zenith",
+        "router",
+        "spa",
+        "file-based-routing",
+        "compile-time"
+    ],
+    "author": "Zenith Team",
+    "repository": {
+        "type": "git",
+        "url": "git+ssh://git@github.com/zenithbuild/zenith-router.git"
+    },
+    "scripts": {
+        "format": "prettier --write \"**/*.ts\"",
+        "format:check": "prettier --check \"**/*.ts\"",
+        "typecheck": "tsc --noEmit",
+        "build": "napi build --release",
+        "build:debug": "napi build",
+        "release": "bun run scripts/release.ts",
+        "release:dry": "bun run scripts/release.ts --dry-run",
+        "release:patch": "bun run scripts/release.ts --bump=patch",
+        "release:minor": "bun run scripts/release.ts --bump=minor",
+        "release:major": "bun run scripts/release.ts --bump=major"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "private": false,
+    "devDependencies": {
+        "@napi-rs/cli": "^2.18.4",
+        "@types/bun": "latest",
+        "@types/node": "latest",
+        "prettier": "^3.7.4"
+    },
+    "peerDependencies": {
+        "typescript": "^5"
+    }
+}

package/src/index.ts

@@ -0,0 +1,108 @@
+/**
+ * @zenithbuild/router
+ * 
+ * File-based SPA router for Zenith framework.
+ * Includes routing, navigation, and ZenLink components.
+ * 
+ * Features:
+ * - Deterministic, compile-time route resolution
+ * - File-based routing (pages/ directory → routes)
+ * - SPA navigation with prefetching
+ * - ZenLink component for declarative links
+ * - Type-safe route parameters
+ * - Hydration-safe, no runtime hacks
+ * 
+ * @example
+ * ```ts
+ * import { navigate, isActive, prefetch } from '@zenithbuild/router'
+ * 
+ * // Navigate programmatically
+ * navigate('/about')
+ * 
+ * // Check active state
+ * if (isActive('/blog')) {
+ *   console.log('On blog section')
+ * }
+ * ```
+ * 
+ * @example
+ * ```ts
+ * // Build-time manifest generation
+ * import { generateRouteManifest, discoverPages } from '@zenithbuild/router/manifest'
+ * 
+ * const manifest = generateRouteManifest('./src/pages')
+ * ```
+ */
+
+// ============================================
+// Core Types
+// ============================================
+
+export * from "./types"
+
+// ============================================
+// Build-time Manifest Generation
+// ============================================
+
+export {
+    generateRouteManifest,
+    generateRouteManifestCode
+} from "./manifest"
+
+// ============================================
+// Runtime Router
+// ============================================
+
+export {
+    initRouter,
+    resolveRoute,
+    navigate,
+    getRoute,
+    onRouteChange,
+    isActive,
+    prefetch,
+    isPrefetched,
+    generateRuntimeRouterCode
+} from "./runtime"
+
+// ============================================
+// Navigation Utilities
+// ============================================
+
+export {
+    // Navigation API (zen* prefixed names)
+    zenNavigate,
+    zenBack,
+    zenForward,
+    zenGo,
+    zenIsActive,
+    zenPrefetch,
+    zenIsPrefetched,
+    zenGetRoute,
+    zenGetParam,
+    zenGetQuery,
+    createZenLink,
+    zenLink,
+    // Additional navigation utilities
+    back,
+    forward,
+    go,
+    getParam,
+    getQuery,
+    isExternalUrl,
+    shouldUseSPANavigation,
+    normalizePath,
+    setGlobalTransition,
+    getGlobalTransition,
+    createTransitionContext
+} from "./navigation/index"
+
+// ============================================
+// Navigation Types
+// ============================================
+
+export type {
+    ZenLinkProps,
+    TransitionContext,
+    TransitionHandler
+} from "./navigation/index"

package/src/lib.rs

@@ -0,0 +1,18 @@
+use napi_derive::napi;
+
+pub mod manifest;
+pub mod render;
+pub mod resolve;
+pub mod runtime_gen;
+pub mod types;
+
+pub use manifest::*;
+pub use render::*;
+pub use resolve::*;
+pub use runtime_gen::*;
+pub use types::*;
+
+#[napi]
+pub fn router_bridge() -> String {
+    "Zenith Router Native Bridge Connected".to_string()
+}

package/src/manifest.rs

@@ -0,0 +1,189 @@
+use crate::types::{ParsedSegment, RouteRecord, SegmentType};
+use napi_derive::napi;
+use std::path::Path;
+use walkdir::WalkDir;
+
+const STATIC_SCORE: i32 = 10;
+const DYNAMIC_SCORE: i32 = 5;
+const CATCH_ALL_SCORE: i32 = 1;
+const OPTIONAL_CATCH_ALL_SCORE: i32 = 0;
+
+pub fn discover_pages(pages_dir: &str) -> Vec<String> {
+    let mut pages = Vec::new();
+    for entry in WalkDir::new(pages_dir)
+        .into_iter()
+        .filter_map(|e| e.ok())
+        .filter(|e| {
+            e.file_type().is_file() && e.path().extension().map_or(false, |ext| ext == "zen")
+        })
+    {
+        pages.push(entry.path().to_string_lossy().to_string());
+    }
+    pages
+}
+
+pub fn file_path_to_route_path(file_path: &str, pages_dir: &str) -> String {
+    let base = Path::new(pages_dir);
+    let path = Path::new(file_path);
+    let relative = path.strip_prefix(base).unwrap_or(path);
+
+    let without_ext = relative.with_extension("");
+    let components: Vec<String> = without_ext
+        .components()
+        .map(|c| c.as_os_str().to_string_lossy().to_string())
+        .collect();
+
+    let mut route_segments = Vec::new();
+    for segment in components {
+        if segment == "index" {
+            continue;
+        }
+
+        if segment.starts_with("[[...") && segment.ends_with("]]") {
+            let param = &segment[5..segment.len() - 2];
+            route_segments.push(format!("*{}?", param));
+            continue;
+        }
+
+        if segment.starts_with("[...") && segment.ends_with("]") {
+            let param = &segment[4..segment.len() - 1];
+            route_segments.push(format!("*{}", param));
+            continue;
+        }
+
+        if segment.starts_with("[") && segment.ends_with("]") {
+            let param = &segment[1..segment.len() - 1];
+            route_segments.push(format!(":{}", param));
+            continue;
+        }
+
+        route_segments.push(segment);
+    }
+
+    let mut route_path = format!("/{}", route_segments.join("/"));
+    if route_path.len() > 1 && route_path.ends_with("/") {
+        route_path.pop();
+    }
+    route_path
+}
+
+pub fn parse_route_segments(route_path: &str) -> Vec<ParsedSegment> {
+    if route_path == "/" {
+        return Vec::new();
+    }
+
+    let segments = route_path[1..].split('/');
+    let mut parsed = Vec::new();
+
+    for segment in segments {
+        if segment.is_empty() {
+            continue;
+        }
+
+        if segment.starts_with('*') && segment.ends_with('?') {
+            parsed.push(ParsedSegment {
+                segment_type: SegmentType::OptionalCatchAll,
+                param_name: Some(segment[1..segment.len() - 1].to_string()),
+                raw: segment.to_string(),
+            });
+        } else if segment.starts_with('*') {
+            parsed.push(ParsedSegment {
+                segment_type: SegmentType::CatchAll,
+                param_name: Some(segment[1..].to_string()),
+                raw: segment.to_string(),
+            });
+        } else if segment.starts_with(':') {
+            parsed.push(ParsedSegment {
+                segment_type: SegmentType::Dynamic,
+                param_name: Some(segment[1..].to_string()),
+                raw: segment.to_string(),
+            });
+        } else {
+            parsed.push(ParsedSegment {
+                segment_type: SegmentType::Static,
+                param_name: None,
+                raw: segment.to_string(),
+            });
+        }
+    }
+    parsed
+}
+
+pub fn calculate_route_score(segments: &[ParsedSegment]) -> i32 {
+    if segments.is_empty() {
+        return 100;
+    }
+
+    let mut score = 0;
+    let mut static_count = 0;
+
+    for segment in segments {
+        score += match segment.segment_type {
+            SegmentType::Static => {
+                static_count += 1;
+                STATIC_SCORE
+            }
+            SegmentType::Dynamic => DYNAMIC_SCORE,
+            SegmentType::CatchAll => CATCH_ALL_SCORE,
+            SegmentType::OptionalCatchAll => OPTIONAL_CATCH_ALL_SCORE,
+        };
+    }
+
+    score += static_count * 2;
+    score
+}
+
+pub fn route_path_to_regex_pattern(route_path: &str) -> String {
+    if route_path == "/" {
+        return r"^\/$".to_string();
+    }
+
+    let segments: Vec<&str> = route_path[1..]
+        .split('/')
+        .filter(|s| !s.is_empty())
+        .collect();
+    let mut regex_parts = Vec::new();
+
+    for segment in segments {
+        if segment.starts_with('*') && segment.ends_with('?') {
+            regex_parts.push(r"(?:\/(.*))?".to_string());
+        } else if segment.starts_with('*') {
+            regex_parts.push(r"\/(.+)".to_string());
+        } else if segment.starts_with(':') {
+            regex_parts.push(r"\/([^/]+)".to_string());
+        } else {
+            let escaped = regex::escape(segment);
+            regex_parts.push(format!(r"\/{}", escaped));
+        }
+    }
+
+    format!(r"^{}\/?$", regex_parts.join(""))
+}
+
+#[napi]
+pub fn generate_route_manifest_native(pages_dir: String) -> Vec<RouteRecord> {
+    let pages = discover_pages(&pages_dir);
+    let mut definitions = Vec::new();
+
+    for file_path in pages {
+        let route_path = file_path_to_route_path(&file_path, &pages_dir);
+        let segments = parse_route_segments(&route_path);
+        let param_names = segments
+            .iter()
+            .filter_map(|s| s.param_name.clone())
+            .collect();
+        let score = calculate_route_score(&segments);
+        let regex = route_path_to_regex_pattern(&route_path);
+
+        definitions.push(RouteRecord {
+            path: route_path,
+            regex,
+            param_names,
+            score,
+            file_path,
+        });
+    }
+
+    definitions.sort_by(|a, b| b.score.cmp(&a.score));
+    definitions
+}