@flight-framework/router 0.0.1 → 0.0.3

package/README.md

@@ -1,13 +1,15 @@
 # @flight-framework/router
 
-Agnostic client-side routing primitives for Flight Framework.
+Universal client-side routing primitives for Flight Framework. Zero external dependencies. Works with any UI framework.
 
-## Philosophy
+## Features
 
-- Zero external runtime dependencies
-- Works with React, Vue, Svelte, or vanilla JS
-- SSR-safe (works on server and client)
-- No vendor lock-in
+- Multiple prefetch strategies (none, intent, render, viewport)
+- SSR-safe implementation
+- Framework-agnostic with React adapters
+- TypeScript-first design
+- IntersectionObserver for viewport prefetching
+- Backwards compatible API
 
 ## Installation
 
@@ -15,14 +17,13 @@ Agnostic client-side routing primitives for Flight Framework.
 npm install @flight-framework/router
 ```
 
-## Usage
+## Quick Start
 
 ### With React
 
 ```tsx
 import { RouterProvider, Link, useRouter } from '@flight-framework/router';
 
-// Wrap your app
 function App() {
     return (
         <RouterProvider initialPath={url}>
@@ -32,21 +33,19 @@ function App() {
     );
 }
 
-// Use Link for navigation
 function Navigation() {
     return (
         <nav>
             <Link href="/">Home</Link>
-            <Link href="/docs" prefetch>Docs</Link>
+            <Link href="/docs" prefetch="intent">Docs</Link>
             <Link href="/about">About</Link>
         </nav>
     );
 }
 
-// Use hooks to access router state
 function Content() {
     const { path, navigate } = useRouter();
-    
+
     return (
         <main>
             <p>Current path: {path}</p>
@@ -58,7 +57,89 @@ function Content() {
 }
 ```
 
-### Hooks
+## Prefetch Strategies
+
+Flight Router supports multiple prefetch strategies to optimize navigation performance:
+
+| Strategy | Behavior | Best For |
+|----------|----------|----------|
+| `'none'` | No prefetching (default) | Low-priority links |
+| `'intent'` | Prefetch on hover/focus | Most navigation links |
+| `'render'` | Prefetch immediately | Critical paths (checkout) |
+| `'viewport'` | Prefetch when visible | Mobile, infinite scroll |
+
+### Usage Examples
+
+```tsx
+// No prefetching (default)
+<Link href="/docs">Docs</Link>
+<Link href="/docs" prefetch="none">Docs</Link>
+
+// Prefetch on hover/focus (recommended for most cases)
+<Link href="/docs" prefetch="intent">Docs</Link>
+<Link href="/docs" prefetch>Docs</Link>  // boolean true = "intent"
+
+// Prefetch immediately when link renders
+<Link href="/checkout" prefetch="render">Checkout</Link>
+
+// Prefetch when link enters viewport (good for mobile)
+<Link href="/products" prefetch="viewport">Products</Link>
+```
+
+## Programmatic Prefetching
+
+```typescript
+import {
+    prefetch,
+    prefetchAll,
+    prefetchWhenIdle,
+    isPrefetched,
+} from '@flight-framework/router';
+
+// Basic prefetch
+prefetch('/docs');
+
+// High priority prefetch
+prefetch('/checkout', { priority: 'high' });
+
+// Prefetch with data loaders
+prefetch('/products', { includeData: true });
+
+// Prefetch multiple pages
+prefetchAll(['/page1', '/page2', '/page3']);
+
+// Prefetch when browser is idle
+prefetchWhenIdle('/dashboard');
+
+// Check if already prefetched
+if (!isPrefetched('/docs')) {
+    prefetch('/docs');
+}
+```
+
+## PrefetchPageLinks Component
+
+For proactive prefetching based on user behavior (search results, autocomplete):
+
+```tsx
+import { PrefetchPageLinks } from '@flight-framework/router';
+
+function SearchResults({ results }) {
+    return (
+        <>
+            {results.map(result => (
+                <div key={result.id}>
+                    {/* Prefetch as soon as result renders */}
+                    <PrefetchPageLinks page={result.url} />
+                    <Link href={result.url}>{result.title}</Link>
+                </div>
+            ))}
+        </>
+    );
+}
+```
+
+## Hooks
 
 ```tsx
 // Get current path and navigation functions
@@ -74,9 +155,9 @@ const [searchParams, setSearchParams] = useSearchParams();
 const pathname = usePathname();
 ```
 
-### Programmatic Navigation
+## Programmatic Navigation
 
-```ts
+```typescript
 import { navigate, prefetch } from '@flight-framework/router';
 
 // Navigate to a path
@@ -90,14 +171,11 @@ navigate('/next-page', { scroll: false });
 
 // Pass state data
 navigate('/dashboard', { state: { from: '/login' } });
-
-// Prefetch a route
-prefetch('/heavy-page');
 ```
 
-### Route Matching
+## Route Matching
 
-```ts
+```typescript
 import { matchRoute, parseParams, generatePath } from '@flight-framework/router';
 
 // Check if a path matches a pattern
@@ -113,16 +191,45 @@ const path = generatePath('/docs/:slug', { slug: 'api-routes' });
 // '/docs/api-routes'
 ```
 
-### Link Props
+## Link Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `href` | `string` | required | Target URL path |
-| `prefetch` | `boolean` | `false` | Prefetch target on hover |
+| `prefetch` | `boolean \| PrefetchStrategy` | `'none'` | Prefetch strategy |
 | `replace` | `boolean` | `false` | Replace history entry |
 | `scroll` | `boolean` | `true` | Scroll to top on navigate |
 | `target` | `string` | - | Link target (_blank, etc) |
 | `className` | `string` | - | CSS class |
+| `aria-label` | `string` | - | Accessibility label |
+
+## Vue Integration
+
+```vue
+<script setup>
+import { useLinkProps } from '@flight-framework/router';
+
+const docsLink = useLinkProps('/docs', { prefetch: 'intent' });
+</script>
+
+<template>
+    <a v-bind="docsLink">Documentation</a>
+</template>
+```
+
+## Vanilla JavaScript
+
+```typescript
+import { createLink, prefetch } from '@flight-framework/router';
+
+const link = createLink({
+    href: '/docs',
+    children: 'Documentation',
+    prefetch: 'intent',
+});
+
+document.body.appendChild(link);
+```
 
 ## SSR Support
 
@@ -139,6 +246,28 @@ export function render(url: string) {
 }
 ```
 
+## Build Integration
+
+For optimal prefetching, Flight generates a route manifest during build that maps routes to their JS modules. This enables `prefetch` to preload the correct chunks.
+
+```typescript
+// flight.config.ts
+export default defineConfig({
+    router: {
+        // Generates __FLIGHT_MANIFEST__ at build time
+        generateManifest: true,
+    },
+});
+```
+
+## Browser Support
+
+| Feature | Chrome | Firefox | Safari | Edge |
+|---------|--------|---------|--------|------|
+| Prefetch | All | All | All | All |
+| Viewport (IntersectionObserver) | 51+ | 55+ | 12.1+ | 15+ |
+| fetchPriority | 101+ | No | No | 101+ |
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -27,6 +27,30 @@ interface RouterProviderProps {
     /** Base path for the router (e.g., '/app') */
     basePath?: string;
 }
+/**
+ * Prefetch strategy for Link component
+ *
+ * - 'none': No prefetching (default)
+ * - 'intent': Prefetch on hover or focus (recommended for most cases)
+ * - 'render': Prefetch immediately when link renders
+ * - 'viewport': Prefetch when link enters the viewport (good for mobile)
+ */
+type PrefetchStrategy = 'none' | 'intent' | 'render' | 'viewport';
+/**
+ * Priority level for prefetch requests
+ */
+type PrefetchPriority = 'high' | 'low' | 'auto';
+/**
+ * Options for programmatic prefetching
+ */
+interface PrefetchOptions {
+    /** Priority of the prefetch request */
+    priority?: PrefetchPriority;
+    /** Include data prefetch (loaders) */
+    includeData?: boolean;
+    /** Include module prefetch (JS chunks) */
+    includeModules?: boolean;
+}
 /**
  * Props for Link component
  */
@@ -41,8 +65,17 @@ interface LinkProps {
     target?: string;
     /** Link relationship */
     rel?: string;
-    /** Prefetch the target page */
-    prefetch?: boolean;
+    /**
+     * Prefetch strategy for the target page.
+     *
+     * - `true` or `'intent'`: Prefetch on hover/focus
+     * - `'render'`: Prefetch when link renders
+     * - `'viewport'`: Prefetch when link enters viewport
+     * - `false` or `'none'`: No prefetching (default)
+     *
+     * @default 'none'
+     */
+    prefetch?: boolean | PrefetchStrategy;
     /** Replace current history entry instead of pushing */
     replace?: boolean;
     /** Scroll to top after navigation */
@@ -71,6 +104,51 @@ type RouteParams<T extends string = string> = Record<T, string>;
  * Search params as key-value pairs
  */
 type SearchParams = Record<string, string | string[]>;
+/**
+ * Route definition for automatic route generation
+ */
+interface RouteDefinition {
+    /** Route path pattern (e.g., '/docs/:slug') */
+    path: string;
+    /** Dynamic import for component */
+    component: () => Promise<{
+        default: unknown;
+    }>;
+    /** Dynamic imports for layouts (in order, root first) */
+    layouts?: Array<() => Promise<{
+        default: unknown;
+    }>>;
+    /** Dynamic import for loader function */
+    loader?: () => Promise<{
+        loader: LoaderFunction;
+    }>;
+}
+/**
+ * Loader function signature
+ */
+type LoaderFunction = (context: LoaderContext) => Promise<unknown> | unknown;
+/**
+ * Context passed to loader functions
+ */
+interface LoaderContext {
+    /** Route parameters */
+    params: RouteParams;
+    /** Request object (available on server) */
+    request?: Request;
+    /** URL search params */
+    searchParams: URLSearchParams;
+}
+/**
+ * Route match result
+ */
+interface RouteMatch {
+    /** Matched route definition */
+    route: RouteDefinition;
+    /** Extracted parameters */
+    params: RouteParams;
+    /** Matched path */
+    pathname: string;
+}
 
 /**
  * Router Context and Provider
@@ -88,13 +166,101 @@ declare let RouterProvider: unknown;
 declare let useRouter: () => RouterContextValue;
 
 /**
- * Link Component
+ * @flight-framework/router - Link Component
+ *
+ * Universal client-side navigation link with advanced prefetching support.
+ * Works with React, Vue, Svelte, Solid, and vanilla JavaScript.
  *
- * Client-side navigation link with prefetching support.
- * Works with React or as a vanilla function.
+ * Features:
+ * - Multiple prefetch strategies (none, intent, render, viewport)
+ * - SSR-safe implementation
+ * - Accessibility compliant
+ * - Framework-agnostic core with React adapter
  */
 
+/**
+ * @deprecated Use `prefetch` from '@flight-framework/router' instead.
+ */
+declare function prefetchRoute(href: string): void;
 declare let Link: unknown;
+/**
+ * Create a link element with SPA navigation support (vanilla JS).
+ *
+ * For Vue, Svelte, Solid, and other frameworks, use this function
+ * or implement framework-specific wrappers.
+ *
+ * @example
+ * ```typescript
+ * const link = createLink({
+ *     href: '/docs',
+ *     children: 'Documentation',
+ *     prefetch: 'intent',
+ * });
+ * document.body.appendChild(link);
+ * ```
+ */
+declare function createLink(props: LinkProps): HTMLAnchorElement;
+/**
+ * Get link props for Vue template usage.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useLinkProps } from '@flight-framework/router';
+ * const linkProps = useLinkProps('/docs', { prefetch: 'intent' });
+ * </script>
+ *
+ * <template>
+ *   <a v-bind="linkProps">Documentation</a>
+ * </template>
+ * ```
+ */
+declare function useLinkProps(href: string, options?: Partial<Omit<LinkProps, 'href' | 'children'>>): {
+    href: string;
+    onClick: (e: MouseEvent) => void;
+    onMouseenter?: () => void;
+    onFocus?: () => void;
+};
+
+/**
+ * @flight-framework/router - PrefetchPageLinks Component
+ *
+ * Renders prefetch link tags for a page. Useful for proactively
+ * prefetching pages based on user behavior (e.g., search results).
+ *
+ * This is the Flight equivalent of React Router's PrefetchPageLinks.
+ */
+
+declare let PrefetchPageLinks: unknown;
+/**
+ * Prefetch multiple pages at once.
+ *
+ * Useful for prefetching a list of search results or related pages.
+ *
+ * @example
+ * ```typescript
+ * // Prefetch top 5 search results
+ * prefetchPages([
+ *     '/products/1',
+ *     '/products/2',
+ *     '/products/3',
+ * ]);
+ * ```
+ */
+declare function prefetchPages(pages: string[], options?: PrefetchOptions): void;
+/**
+ * Prefetch a page when idle.
+ *
+ * Uses requestIdleCallback if available, otherwise falls back
+ * to setTimeout.
+ *
+ * @example
+ * ```typescript
+ * // Prefetch after initial render settles
+ * prefetchWhenIdle('/dashboard');
+ * ```
+ */
+declare function prefetchWhenIdle(page: string, options?: PrefetchOptions): void;
 
 /**
  * Router Hooks
@@ -124,16 +290,6 @@ declare let usePathname: () => string;
  * ```
  */
 declare function navigate(to: string, options?: NavigateOptions): void;
-/**
- * Prefetch a route's assets
- * Creates a prefetch link for the target URL
- *
- * @example
- * ```ts
- * prefetch('/docs'); // Prefetch when user hovers
- * ```
- */
-declare function prefetch(href: string): void;
 /**
  * Match a pathname against a route pattern
  *
@@ -157,5 +313,100 @@ declare function matchRoute(pathname: string, pattern: string): {
  * ```
  */
 declare function parseParams(pathname: string, pattern: string): RouteParams;
+/**
+ * Find the best matching route from a list of route definitions
+ */
+declare function findRoute(pathname: string, routes: RouteDefinition[]): RouteMatch | null;
+/**
+ * Generate a URL from a route pattern and params
+ *
+ * @example
+ * ```ts
+ * generatePath('/docs/:slug', { slug: 'routing' });
+ * // Returns: '/docs/routing'
+ * ```
+ */
+declare function generatePath(pattern: string, params?: RouteParams): string;
+/**
+ * Check if current path matches a pattern
+ */
+declare function isActive(pattern: string): boolean;
+/**
+ * Redirect to a new URL (full page navigation)
+ * Use this for external redirects or when you need to break out of SPA
+ */
+declare function redirect(url: string): never;
+
+/**
+ * @flight-framework/router - Prefetch Utilities
+ *
+ * Universal prefetch system for Flight Framework.
+ * Works across all UI frameworks and runtimes.
+ *
+ * Features:
+ * - Multiple prefetch strategies (intent, render, viewport)
+ * - Priority-based prefetching
+ * - Module and data prefetching
+ * - IntersectionObserver for viewport detection
+ * - SSR-safe implementation
+ */
+
+/**
+ * Prefetch a URL with the specified options.
+ *
+ * This is the main programmatic prefetch API for Flight Framework.
+ * It creates appropriate link elements for prefetching resources.
+ *
+ * @param href - The URL to prefetch
+ * @param options - Prefetch configuration options
+ *
+ * @example
+ * ```typescript
+ * // Basic prefetch
+ * prefetch('/docs');
+ *
+ * // High priority prefetch (for critical navigation paths)
+ * prefetch('/checkout', { priority: 'high' });
+ *
+ * // Prefetch with data loaders
+ * prefetch('/products', { includeData: true });
+ * ```
+ */
+declare function prefetch(href: string, options?: PrefetchOptions): void;
+/**
+ * Prefetch multiple URLs at once.
+ *
+ * @param hrefs - Array of URLs to prefetch
+ * @param options - Prefetch configuration options
+ */
+declare function prefetchAll(hrefs: string[], options?: PrefetchOptions): void;
+/**
+ * Check if a URL has been prefetched.
+ *
+ * @param href - The URL to check
+ * @returns True if the URL has been prefetched
+ */
+declare function isPrefetched(href: string): boolean;
+/**
+ * Clear all prefetch state (useful for testing or memory management).
+ */
+declare function clearPrefetchCache(): void;
+/**
+ * Observe an element for viewport entry and trigger prefetch.
+ *
+ * @param element - The link element to observe
+ * @param href - The URL to prefetch when visible
+ * @returns Cleanup function to stop observing
+ */
+declare function observeForPrefetch(element: Element, href: string): () => void;
+/**
+ * Setup intent-based prefetching for an element.
+ * Prefetches on mouseenter or focus.
+ *
+ * @param element - The link element
+ * @param href - The URL to prefetch
+ * @returns Cleanup function to remove listeners
+ */
+declare function setupIntentPrefetch(element: HTMLElement, href: string): () => void;
 
-export { Link, type LinkProps, type NavigateOptions, type RouteParams, RouterContext, type RouterContextValue, RouterProvider, type RouterProviderProps, type SearchParams, matchRoute, navigate, parseParams, prefetch, useParams, usePathname, useRouter, useSearchParams };
+export { Link, type LinkProps, type LoaderContext, type LoaderFunction, type NavigateOptions, type PrefetchOptions, PrefetchPageLinks, type PrefetchPriority, type PrefetchStrategy, type RouteDefinition, type RouteMatch, type RouteParams, RouterContext, type RouterContextValue, RouterProvider, type RouterProviderProps, type SearchParams, clearPrefetchCache, createLink, findRoute, generatePath, isActive, isPrefetched, matchRoute, navigate, observeForPrefetch, parseParams, prefetch, prefetchAll, prefetchPages, prefetchRoute, prefetchWhenIdle, redirect, setupIntentPrefetch, useLinkProps, useParams, usePathname, useRouter, useSearchParams };

package/dist/index.js

@@ -104,26 +104,192 @@ if (typeof globalThis !== "undefined") {
   }
 }
 
-// src/link.ts
+// src/prefetch.ts
 var isBrowser2 = typeof window !== "undefined";
+var supportsIntersectionObserver = isBrowser2 && "IntersectionObserver" in window;
+var prefetchedUrls = /* @__PURE__ */ new Set();
+var prefetchingUrls = /* @__PURE__ */ new Set();
+var viewportObservers = /* @__PURE__ */ new Map();
+function prefetch(href, options = {}) {
+  if (!isBrowser2) return;
+  const {
+    priority = "auto",
+    includeModules = true,
+    includeData = false
+  } = options;
+  const url = normalizeUrl(href);
+  if (prefetchedUrls.has(url) || prefetchingUrls.has(url)) {
+    return;
+  }
+  prefetchingUrls.add(url);
+  createPrefetchLink(url, "document", priority);
+  if (includeModules) {
+    prefetchModules(url, priority);
+  }
+  if (includeData) {
+    prefetchData(url, priority);
+  }
+  prefetchedUrls.add(url);
+  prefetchingUrls.delete(url);
+}
+function prefetchAll(hrefs, options = {}) {
+  for (const href of hrefs) {
+    prefetch(href, options);
+  }
+}
+function isPrefetched(href) {
+  return prefetchedUrls.has(normalizeUrl(href));
+}
+function clearPrefetchCache() {
+  prefetchedUrls.clear();
+  prefetchingUrls.clear();
+}
+function createPrefetchLink(href, as, priority) {
+  if (!isBrowser2) return null;
+  const existing = document.querySelector(
+    `link[rel="prefetch"][href="${href}"], link[rel="modulepreload"][href="${href}"]`
+  );
+  if (existing) return existing;
+  const link = document.createElement("link");
+  if (as === "script") {
+    link.rel = "modulepreload";
+  } else {
+    link.rel = "prefetch";
+    link.as = as;
+  }
+  link.href = href;
+  if (priority !== "auto" && "fetchPriority" in link) {
+    link.fetchPriority = priority;
+  }
+  if (priority === "low" && "requestIdleCallback" in window) {
+    window.requestIdleCallback(() => {
+      document.head.appendChild(link);
+    });
+  } else {
+    document.head.appendChild(link);
+  }
+  return link;
+}
+function prefetchModules(href, priority) {
+  const manifest = window.__FLIGHT_MANIFEST__;
+  if (!manifest?.routes) return;
+  const routeModules = manifest.routes[href];
+  if (!routeModules) return;
+  for (const module of routeModules) {
+    createPrefetchLink(module, "script", priority);
+  }
+}
+function prefetchData(href, priority) {
+  const dataUrl = `/_flight/data${href === "/" ? "/index" : href}.json`;
+  createPrefetchLink(dataUrl, "fetch", priority);
+}
+var sharedObserver = null;
+var observerCallbacks = /* @__PURE__ */ new Map();
+function getViewportObserver() {
+  if (!supportsIntersectionObserver) return null;
+  if (!sharedObserver) {
+    sharedObserver = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            const callback = observerCallbacks.get(entry.target);
+            if (callback) {
+              callback();
+              sharedObserver?.unobserve(entry.target);
+              observerCallbacks.delete(entry.target);
+            }
+          }
+        }
+      },
+      {
+        // Start prefetching when link is 25% visible or within 100px of viewport
+        rootMargin: "100px",
+        threshold: 0.25
+      }
+    );
+  }
+  return sharedObserver;
+}
+function observeForPrefetch(element, href) {
+  if (!supportsIntersectionObserver) {
+    return () => {
+    };
+  }
+  const observer = getViewportObserver();
+  if (!observer) return () => {
+  };
+  const callback = () => {
+    prefetch(href, { priority: "low" });
+  };
+  observerCallbacks.set(element, callback);
+  observer.observe(element);
+  const cleanup = () => {
+    observer.unobserve(element);
+    observerCallbacks.delete(element);
+    viewportObservers.delete(element);
+  };
+  viewportObservers.set(element, cleanup);
+  return cleanup;
+}
+function setupIntentPrefetch(element, href) {
+  if (!isBrowser2) return () => {
+  };
+  let prefetchTriggered = false;
+  const handleIntent = () => {
+    if (!prefetchTriggered) {
+      prefetchTriggered = true;
+      prefetch(href, { priority: "auto" });
+    }
+  };
+  element.addEventListener("mouseenter", handleIntent, { passive: true });
+  element.addEventListener("focus", handleIntent, { passive: true });
+  element.addEventListener("touchstart", handleIntent, { passive: true });
+  return () => {
+    element.removeEventListener("mouseenter", handleIntent);
+    element.removeEventListener("focus", handleIntent);
+    element.removeEventListener("touchstart", handleIntent);
+  };
+}
+function normalizeUrl(href) {
+  if (isBrowser2 && !href.startsWith("http")) {
+    try {
+      const url = new URL(href, window.location.origin);
+      return url.pathname + url.search;
+    } catch {
+      return href;
+    }
+  }
+  return href;
+}
+
+// src/link.ts
+var isBrowser3 = typeof window !== "undefined";
 function handleLinkClick(href, options, event) {
   if (event && (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)) {
     return;
   }
+  if (event && event.button !== 0) {
+    return;
+  }
   event?.preventDefault();
   const { navigate: navigate2 } = getRouterContext();
   navigate2(href, options);
 }
 function isExternalUrl(href) {
   if (!href) return false;
-  return href.startsWith("http://") || href.startsWith("https://") || href.startsWith("//") || href.startsWith("mailto:") || href.startsWith("tel:");
+  return href.startsWith("http://") || href.startsWith("https://") || href.startsWith("//") || href.startsWith("mailto:") || href.startsWith("tel:") || href.startsWith("javascript:") || href.startsWith("#");
+}
+function normalizePrefetchStrategy(prefetchProp) {
+  if (prefetchProp === true) {
+    return "intent";
+  }
+  if (prefetchProp === false || prefetchProp === void 0) {
+    return "none";
+  }
+  return prefetchProp;
 }
 function prefetchRoute(href) {
-  if (!isBrowser2) return;
-  const link = document.createElement("link");
-  link.rel = "prefetch";
-  link.href = href;
-  document.head.appendChild(link);
+  prefetch(href);
 }
 var Link = null;
 if (typeof globalThis !== "undefined") {
@@ -137,58 +303,196 @@ if (typeof globalThis !== "undefined") {
         className,
         target,
         rel,
-        prefetch: prefetch2 = false,
+        prefetch: prefetchProp = "none",
         replace = false,
         scroll = true,
         onClick,
+        "aria-label": ariaLabel,
         ...props
       }) {
         const linkRef = useRef(null);
         const isExternal = isExternalUrl(href);
-        const handleClick = useCallback((e) => {
-          if (onClick) {
-            onClick(e);
-            if (e.defaultPrevented) return;
-          }
-          if (isExternal || target === "_blank") return;
-          handleLinkClick(href, { replace, scroll }, e);
-        }, [href, isExternal, target, replace, scroll, onClick]);
+        const prefetchStrategy = normalizePrefetchStrategy(prefetchProp);
+        const handleClick = useCallback(
+          (e) => {
+            if (onClick) {
+              onClick(e);
+              if (e.defaultPrevented) return;
+            }
+            if (isExternal || target === "_blank") return;
+            handleLinkClick(href, { replace, scroll }, e);
+          },
+          [href, isExternal, target, replace, scroll, onClick]
+        );
         useEffect(() => {
-          if (!prefetch2 || isExternal || !isBrowser2) return;
+          if (isExternal || !isBrowser3 || prefetchStrategy === "none") {
+            return;
+          }
           const link = linkRef.current;
           if (!link) return;
-          let prefetched = false;
-          const doPrefetch = () => {
-            if (!prefetched) {
-              prefetched = true;
-              prefetchRoute(href);
-            }
-          };
-          link.addEventListener("mouseenter", doPrefetch);
-          link.addEventListener("focus", doPrefetch);
-          return () => {
-            link.removeEventListener("mouseenter", doPrefetch);
-            link.removeEventListener("focus", doPrefetch);
-          };
-        }, [href, prefetch2, isExternal]);
+          switch (prefetchStrategy) {
+            case "render":
+              prefetch(href, { priority: "low" });
+              break;
+            case "viewport":
+              return observeForPrefetch(link, href);
+            case "intent":
+            default:
+              return setupIntentPrefetch(link, href);
+          }
+        }, [href, prefetchStrategy, isExternal]);
         const computedRel = isExternal && target === "_blank" ? rel || "noopener noreferrer" : rel;
-        return React.createElement("a", {
-          ref: linkRef,
-          href,
-          className,
-          target,
-          rel: computedRel,
-          onClick: handleClick,
-          ...props
-        }, children);
+        return React.createElement(
+          "a",
+          {
+            ref: linkRef,
+            href,
+            className,
+            target,
+            rel: computedRel,
+            "aria-label": ariaLabel,
+            onClick: handleClick,
+            ...props
+          },
+          children
+        );
       };
     }
   } catch {
   }
 }
+function createLink(props) {
+  const {
+    href,
+    children,
+    className,
+    target,
+    rel,
+    prefetch: prefetchProp = "none",
+    replace = false,
+    scroll = true
+  } = props;
+  const anchor = document.createElement("a");
+  anchor.href = href;
+  anchor.className = className || "";
+  if (target) anchor.target = target;
+  if (rel) anchor.rel = rel;
+  if (typeof children === "string") {
+    anchor.textContent = children;
+  }
+  const isExternal = isExternalUrl(href);
+  const prefetchStrategy = normalizePrefetchStrategy(prefetchProp);
+  if (!isExternal && target !== "_blank") {
+    anchor.addEventListener("click", (e) => {
+      handleLinkClick(href, { replace, scroll }, e);
+    });
+  }
+  if (!isExternal && prefetchStrategy !== "none") {
+    switch (prefetchStrategy) {
+      case "render":
+        prefetch(href, { priority: "low" });
+        break;
+      case "viewport":
+        observeForPrefetch(anchor, href);
+        break;
+      case "intent":
+      default:
+        setupIntentPrefetch(anchor, href);
+        break;
+    }
+  }
+  return anchor;
+}
+function useLinkProps(href, options = {}) {
+  const { replace = false, scroll = true, prefetch: prefetchProp = "none" } = options;
+  const isExternal = isExternalUrl(href);
+  const prefetchStrategy = normalizePrefetchStrategy(prefetchProp);
+  const result = {
+    href,
+    onClick: (e) => {
+      if (!isExternal) {
+        handleLinkClick(href, { replace, scroll }, e);
+      }
+    }
+  };
+  if (prefetchStrategy === "intent" && !isExternal) {
+    let prefetched = false;
+    const doPrefetch = () => {
+      if (!prefetched) {
+        prefetched = true;
+        prefetch(href);
+      }
+    };
+    result.onMouseenter = doPrefetch;
+    result.onFocus = doPrefetch;
+  }
+  if (prefetchStrategy === "render" && !isExternal && isBrowser3) {
+    prefetch(href, { priority: "low" });
+  }
+  return result;
+}
+
+// src/prefetch-links.ts
+var isBrowser4 = typeof window !== "undefined";
+var PrefetchPageLinks = null;
+if (typeof globalThis !== "undefined") {
+  try {
+    const React = globalThis.React;
+    if (React?.createElement && "useEffect" in React) {
+      const { useEffect, useState } = React;
+      PrefetchPageLinks = function FlightPrefetchPageLinks({
+        page,
+        options = {}
+      }) {
+        const [shouldRender, setShouldRender] = useState(false);
+        useEffect(() => {
+          if (!isBrowser4) return;
+          if (isPrefetched(page)) {
+            return;
+          }
+          prefetch(page, {
+            priority: "low",
+            includeModules: true,
+            ...options
+          });
+          setShouldRender(false);
+        }, [page, options]);
+        return null;
+      };
+    }
+  } catch {
+  }
+}
+function prefetchPages(pages, options = {}) {
+  if (!isBrowser4) return;
+  for (const page of pages) {
+    if (!isPrefetched(page)) {
+      prefetch(page, {
+        priority: "low",
+        ...options
+      });
+    }
+  }
+}
+function prefetchWhenIdle(page, options = {}) {
+  if (!isBrowser4) return;
+  const doPrefetch = () => {
+    if (!isPrefetched(page)) {
+      prefetch(page, {
+        priority: "low",
+        ...options
+      });
+    }
+  };
+  if ("requestIdleCallback" in window) {
+    window.requestIdleCallback(doPrefetch, { timeout: 3e3 });
+  } else {
+    setTimeout(doPrefetch, 100);
+  }
+}
 
 // src/hooks.ts
-var isBrowser3 = typeof window !== "undefined";
+var isBrowser5 = typeof window !== "undefined";
 var useParams = () => ({});
 var useSearchParams = () => [new URLSearchParams(), () => {
 }];
@@ -210,10 +514,10 @@ if (typeof globalThis !== "undefined") {
       };
       useSearchParams = function useFlightSearchParams() {
         const [searchParams, setSearchParamsState] = useState(
-          () => isBrowser3 ? new URLSearchParams(window.location.search) : new URLSearchParams()
+          () => isBrowser5 ? new URLSearchParams(window.location.search) : new URLSearchParams()
         );
         useEffect(() => {
-          if (!isBrowser3) return;
+          if (!isBrowser5) return;
           const handleChange = () => {
             setSearchParamsState(new URLSearchParams(window.location.search));
           };
@@ -221,7 +525,7 @@ if (typeof globalThis !== "undefined") {
           return () => window.removeEventListener("popstate", handleChange);
         }, []);
         const setSearchParams = useCallback((newParams) => {
-          if (!isBrowser3) return;
+          if (!isBrowser5) return;
           let params;
           if (newParams instanceof URLSearchParams) {
             params = newParams;
@@ -245,7 +549,7 @@ if (typeof globalThis !== "undefined") {
         const { path } = getRouterContext();
         const [pathname, setPathname] = useState(path);
         useEffect(() => {
-          if (!isBrowser3) return;
+          if (!isBrowser5) return;
           const handleChange = () => {
             setPathname(window.location.pathname);
           };
@@ -260,20 +564,11 @@ if (typeof globalThis !== "undefined") {
 }
 
 // src/navigate.ts
-var isBrowser4 = typeof window !== "undefined";
+var isBrowser6 = typeof window !== "undefined";
 function navigate(to, options = {}) {
   const { navigate: routerNavigate } = getRouterContext();
   routerNavigate(to, options);
 }
-function prefetch(href) {
-  if (!isBrowser4) return;
-  const existing = document.querySelector(`link[rel="prefetch"][href="${href}"]`);
-  if (existing) return;
-  const link = document.createElement("link");
-  link.rel = "prefetch";
-  link.href = href;
-  document.head.appendChild(link);
-}
 function patternToRegex(pattern) {
   const paramNames = [];
   let regexStr = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\\\[\.\.\.(\w+)\\\]/g, (_, name) => {
@@ -308,14 +603,63 @@ function parseParams(pathname, pattern) {
   const { params } = matchRoute(pathname, pattern);
   return params;
 }
+function findRoute(pathname, routes) {
+  for (const route of routes) {
+    const { matched, params } = matchRoute(pathname, route.path);
+    if (matched) {
+      return {
+        route,
+        params,
+        pathname
+      };
+    }
+  }
+  return null;
+}
+function generatePath(pattern, params = {}) {
+  let path = pattern;
+  path = path.replace(/\[(\w+)\]/g, (_, name) => {
+    return params[name] || "";
+  });
+  path = path.replace(/:(\w+)/g, (_, name) => {
+    return params[name] || "";
+  });
+  return path;
+}
+function isActive(pattern) {
+  const { path } = getRouterContext();
+  const { matched } = matchRoute(path, pattern);
+  return matched;
+}
+function redirect(url) {
+  if (isBrowser6) {
+    window.location.href = url;
+  }
+  throw new Error(`Redirect to: ${url}`);
+}
 export {
   Link,
+  PrefetchPageLinks,
   RouterContext,
   RouterProvider,
+  clearPrefetchCache,
+  createLink,
+  findRoute,
+  generatePath,
+  isActive,
+  isPrefetched,
   matchRoute,
   navigate,
+  observeForPrefetch,
   parseParams,
   prefetch,
+  prefetchAll,
+  prefetchPages,
+  prefetchRoute,
+  prefetchWhenIdle,
+  redirect,
+  setupIntentPrefetch,
+  useLinkProps,
   useParams,
   usePathname,
   useRouter,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@flight-framework/router",
-    "version": "0.0.1",
+    "version": "0.0.3",
     "description": "Agnostic client-side routing primitives for Flight Framework",
     "type": "module",
     "main": "./dist/index.js",
@@ -45,4 +45,4 @@
             "optional": true
         }
     }
-}
+}