@zenithbuild/router 0.6.13 → 0.7.0

package/README.md

@@ -1,136 +1,20 @@
 # @zenith/router
 
-> **⚠️ Internal API:** This package is an internal implementation detail of the Zenith framework. It is not intended for public use and its API may break without warning. Please use `@zenithbuild/core` instead.
-
-
-File-based SPA router for Zenith framework with **deterministic, compile-time route resolution**.
+> Internal Zenith package. The generated router runtime is the authoritative surface here, not a general SPA framework API.
 
 ## Canonical Docs
 
-- Routing contract: `../zenith-docs/documentation/contracts/routing.md`
-- Navigation contract: `../zenith-docs/documentation/contracts/navigation.md`
-- Router contract: `../zenith-docs/documentation/contracts/router-contract.md`
-
-## 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 @zenith/router
-```
-
-## Usage
-
-### Programmatic Navigation
-
-```ts
-import { navigate, prefetch, isActive, getRoute } from '@zenith/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 '@zenith/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
-
-```
-@zenith/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
+- [Routing Contract](../../docs/documentation/contracts/routing.md)
+- [Navigation Contract](../../docs/documentation/contracts/navigation.md)
+- [Router Contract](../../docs/documentation/contracts/router-contract.md)
+- [Navigation Lifecycle Contract](../../docs/documentation/contracts/navigation-lifecycle.md)
 
-## License
+## Phase 2 Runtime Summary
 
-MIT
-# zenith-router
+- Plain anchors hard navigate by default.
+- Soft navigation is opt-in only through `a[data-zen-link]`.
+- `ZenLink` is a thin anchor wrapper over the same marker contract.
+- Soft navigation fetches fresh same-origin HTML before committing history.
+- Redirects, denies, unmatched routes, non-HTML responses, and runtime failures fall back to browser navigation.
+- Client routing mirrors server route precedence and pathname-based identity.
+- Phase 2 adds awaited lifecycle barriers at `navigation:before-leave`, `navigation:before-swap`, and `navigation:before-enter`.

package/dist/ZenLink.zen

@@ -1,7 +1,70 @@
-<script setup="ts">
-    export const props = { href: "", class: "", target: "", rel: "" };
+<script lang="ts">
+export interface Props {
+  href?: string;
+  class?: string;
+  target?: string;
+  rel?: string;
+  id?: string;
+  title?: string;
+  ariaLabel?: string;
+  ariaCurrent?: string;
+  ariaDisabled?: string;
+  elementRef?: any;
+  onClick?: (event: MouseEvent) => void;
+  onHoverIn?: (event: PointerEvent) => void;
+  onHoverOut?: (event: PointerEvent) => void;
+  onFocus?: (event: FocusEvent) => void;
+  onBlur?: (event: FocusEvent) => void;
+}
+
+const zenLinkProps = props as Props;
+const zenLinkHref = typeof zenLinkProps.href === "string" ? zenLinkProps.href : "";
+const zenLinkClass = typeof zenLinkProps.class === "string" ? zenLinkProps.class : "";
+const zenLinkTarget = typeof zenLinkProps.target === "string" ? zenLinkProps.target : "";
+const zenLinkRel = typeof zenLinkProps.rel === "string" ? zenLinkProps.rel : "";
+const zenLinkId = typeof zenLinkProps.id === "string" ? zenLinkProps.id : "";
+const zenLinkTitle = typeof zenLinkProps.title === "string" ? zenLinkProps.title : "";
+const zenLinkAriaLabel = typeof zenLinkProps.ariaLabel === "string" ? zenLinkProps.ariaLabel : "";
+const zenLinkAriaCurrent = typeof zenLinkProps.ariaCurrent === "string" ? zenLinkProps.ariaCurrent : "";
+const zenLinkAriaDisabled = typeof zenLinkProps.ariaDisabled === "string" ? zenLinkProps.ariaDisabled : "";
+const zenLinkElementRef = zenLinkProps.elementRef;
+const zenLinkRef = ref<HTMLAnchorElement>();
+const zenLinkClick = typeof zenLinkProps.onClick === "function" ? zenLinkProps.onClick : undefined;
+const zenLinkHoverIn = typeof zenLinkProps.onHoverIn === "function" ? zenLinkProps.onHoverIn : undefined;
+const zenLinkHoverOut = typeof zenLinkProps.onHoverOut === "function" ? zenLinkProps.onHoverOut : undefined;
+const zenLinkFocus = typeof zenLinkProps.onFocus === "function" ? zenLinkProps.onFocus : undefined;
+const zenLinkBlur = typeof zenLinkProps.onBlur === "function" ? zenLinkProps.onBlur : undefined;
+
+zenMount((ctx) => {
+  if (zenLinkElementRef) {
+    zenLinkElementRef.current = zenLinkRef.current;
+  }
+
+  ctx.cleanup(() => {
+    if (zenLinkElementRef) {
+      zenLinkElementRef.current = null;
+    }
+  });
+});
 </script>
 
-<a data-zen-link="true" href={props.href} class={props.class} target={props.target} rel={props.rel}>
+<a
+  ref={zenLinkRef}
+  data-zen-link="true"
+  href={zenLinkHref || undefined}
+  class={zenLinkClass || undefined}
+  target={zenLinkTarget || undefined}
+  rel={zenLinkRel || undefined}
+  id={zenLinkId || undefined}
+  title={zenLinkTitle || undefined}
+  aria-label={zenLinkAriaLabel || undefined}
+  aria-current={zenLinkAriaCurrent || undefined}
+  aria-disabled={zenLinkAriaDisabled || undefined}
+  on:click={zenLinkClick}
+  on:hoverin={zenLinkHoverIn}
+  on:hoverout={zenLinkHoverOut}
+  on:focus={zenLinkFocus}
+  on:blur={zenLinkBlur}
+>
   <slot></slot>
 </a>

package/dist/events.d.ts

@@ -5,10 +5,12 @@ type RouteChangeDetail = {
     matched: boolean;
 };
 type RouteProtectionPolicy = {
-    beforeResolve?: boolean;
-    emitRedirects?: boolean;
+    onDeny?: 'stay' | 'redirect' | 'render403' | ((ctx: any) => void);
+    defaultLoginPath?: string;
+    deny401RedirectToLogin?: boolean;
+    forbiddenPath?: string;
 };
-type RouteEventHandler = (payload: unknown) => void;
+type RouteEventHandler = (payload: unknown) => void | Promise<void>;
 export declare function onRouteChange(callback: (detail: RouteChangeDetail) => void): () => void;
 export declare function _dispatchRouteChange(detail: RouteChangeDetail): void;
 export declare function _clearSubscribers(): void;
@@ -18,4 +20,6 @@ export declare function _getRouteProtectionPolicy(): RouteProtectionPolicy;
 export declare function on(eventName: string, handler: RouteEventHandler): void;
 export declare function off(eventName: string, handler: RouteEventHandler): void;
 export declare function _dispatchRouteEvent(eventName: string, payload: unknown): void;
+export declare function _dispatchRouteEventAsync(eventName: string, payload: unknown): Promise<void>;
+export declare function _clearRouteEventListeners(): void;
 export {};

package/dist/events.js

@@ -34,7 +34,17 @@ const ROUTE_EVENT_NAMES = [
     'route-check:end',
     'route-check:error',
     'route:deny',
-    'route:redirect'
+    'route:redirect',
+    'navigation:request',
+    'navigation:before-leave',
+    'navigation:leave-complete',
+    'navigation:data-ready',
+    'navigation:before-swap',
+    'navigation:content-swapped',
+    'navigation:before-enter',
+    'navigation:enter-complete',
+    'navigation:abort',
+    'navigation:error'
 ];
 function getRouteProtectionScope() {
     return typeof globalThis === 'object' && globalThis
@@ -80,6 +90,27 @@ export function off(eventName, handler) {
         eventListeners.delete(handler);
     }
 }
+function dispatchRouteEventError(eventName, payload, error) {
+    console.error(`[Zenith Router] Error in ${eventName} listener:`, error);
+    if (eventName === 'navigation:error' ||
+        !payload ||
+        typeof payload !== 'object' ||
+        typeof payload.navigationId !== 'number') {
+        return;
+    }
+    _dispatchRouteEvent('navigation:error', {
+        navigationId: payload.navigationId,
+        navigationType: payload.navigationType,
+        to: payload.to,
+        from: payload.from,
+        routeId: payload.routeId,
+        params: payload.params,
+        stage: payload.stage ?? 'listener',
+        reason: 'listener-error',
+        hook: eventName,
+        error
+    });
+}
 export function _dispatchRouteEvent(eventName, payload) {
     const eventListeners = ensureRouteProtectionState().listeners[eventName];
     if (!(eventListeners instanceof Set)) {
@@ -87,10 +118,38 @@ export function _dispatchRouteEvent(eventName, payload) {
     }
     for (const handler of eventListeners) {
         try {
-            handler(payload);
+            const result = handler(payload);
+            if (result && typeof result.catch === 'function') {
+                result.catch((error) => {
+                    dispatchRouteEventError(eventName, payload, error);
+                });
+            }
+        }
+        catch (error) {
+            dispatchRouteEventError(eventName, payload, error);
+        }
+    }
+}
+export async function _dispatchRouteEventAsync(eventName, payload) {
+    const eventListeners = ensureRouteProtectionState().listeners[eventName];
+    if (!(eventListeners instanceof Set)) {
+        return;
+    }
+    const handlers = Array.from(eventListeners);
+    for (const handler of handlers) {
+        try {
+            await handler(payload);
         }
         catch (error) {
-            console.error(`[Zenith Router] Error in ${eventName} listener:`, error);
+            dispatchRouteEventError(eventName, payload, error);
+        }
+    }
+}
+export function _clearRouteEventListeners() {
+    const listeners = ensureRouteProtectionState().listeners;
+    for (const eventName of Object.keys(listeners)) {
+        if (listeners[eventName] instanceof Set) {
+            listeners[eventName].clear();
         }
     }
 }

package/index.d.ts

@@ -1,7 +1,7 @@
 export type RouteResult =
     | { kind: "allow" }
     | { kind: "redirect"; location: string; status?: number }
-    | { kind: "deny"; status: 401 | 403 | 500; message?: string }
+    | { kind: "deny"; status: 401 | 403 | 404; message?: string }
     | { kind: "data"; data: any };
 
 export type GuardResult = Extract<RouteResult, { kind: "allow" | "redirect" | "deny" }>;
@@ -22,7 +22,7 @@ export interface RouteContext {
     };
     allow(): { kind: "allow" };
     redirect(location: string, status?: number): { kind: "redirect"; location: string; status: number };
-    deny(status: 401 | 403 | 500, message?: string): { kind: "deny"; status: 401 | 403 | 500; message?: string };
+    deny(status: 401 | 403 | 404, message?: string): { kind: "deny"; status: 401 | 403 | 404; message?: string };
     data(payload: any): { kind: "data"; data: any };
 }
 
@@ -41,6 +41,38 @@ export interface RouteProtectionPolicy {
     forbiddenPath?: string;
 }
 
+export type NavigationType = "push" | "pop";
+
+export interface NavigationLifecyclePayload {
+    navigationId: number;
+    navigationType: NavigationType;
+    to: URL | null;
+    from: URL | null;
+    routeId: string;
+    params: Record<string, string>;
+    stage: string;
+    document?: {
+        title: string;
+        hasSsrData: boolean;
+        status: number;
+    };
+    scroll?: {
+        mode: "top" | "restore" | "hash";
+        x: number;
+        y: number;
+        hash: string;
+    };
+    reason?: string;
+    hook?: string;
+    location?: string;
+    status?: number;
+    historyCommitted?: boolean;
+    error?: unknown;
+    [key: string]: unknown;
+}
+
+export type RouteEventHandler = (payload: unknown) => void | Promise<void>;
+
 export type RouteEventName =
     | "guard:start"
     | "guard:end"
@@ -48,8 +80,18 @@ export type RouteEventName =
     | "route-check:end"
     | "route-check:error"
     | "route:deny"
-    | "route:redirect";
+    | "route:redirect"
+    | "navigation:request"
+    | "navigation:before-leave"
+    | "navigation:leave-complete"
+    | "navigation:data-ready"
+    | "navigation:before-swap"
+    | "navigation:content-swapped"
+    | "navigation:before-enter"
+    | "navigation:enter-complete"
+    | "navigation:abort"
+    | "navigation:error";
 
 export declare function setRouteProtectionPolicy(policy: RouteProtectionPolicy): void;
-export declare function on(eventName: RouteEventName, handler: (payload: any) => void): void;
-export declare function off(eventName: RouteEventName, handler: (payload: any) => void): void;
+export declare function on(eventName: RouteEventName, handler: RouteEventHandler): void;
+export declare function off(eventName: RouteEventName, handler: RouteEventHandler): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenithbuild/router",
-  "version": "0.6.13",
+  "version": "0.7.0",
   "description": "File-based SPA router for Zenith framework with deterministic, compile-time route resolution",
   "license": "MIT",
   "type": "module",
@@ -8,6 +8,9 @@
   "files": [
     "dist",
     "template.js",
+    "template-core.js",
+    "template-lifecycle.js",
+    "template-navigation.js",
     "index.js",
     "index.d.ts",
     "README.md",
@@ -18,6 +21,7 @@
   "exports": {
     ".": "./dist/index.js",
     "./template": "./template.js",
+    "./events": "./dist/events.js",
     "./ZenLink.zen": "./dist/ZenLink.zen"
   },
   "keywords": [