@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.131

package/src/theme/theme-context.ts

@@ -10,52 +10,22 @@
  */
 
 import { createContext, useContext, type Context } from "react";
-import type { ResolvedThemeConfig, ThemeContextValue } from "./types.js";
+import type { ThemeContextValue } from "./types.js";
 
 /**
  * React context for theme state
  * null when theme is not enabled in router config
  */
-export const ThemeContext: Context<ThemeContextValue | null> = createContext<ThemeContextValue | null>(null);
+export const ThemeContext: Context<ThemeContextValue | null> =
+  createContext<ThemeContextValue | null>(null);
 
-/**
- * SSR module-level state for theme config.
- * Populated by initThemeConfigSync before React renders.
- * Used by MetaTags during SSR to render the theme script.
- */
-let ssrThemeConfig: ResolvedThemeConfig | null = null;
-
-/**
- * Initialize theme config synchronously for SSR.
- * Called before rendering to populate state for MetaTags.
- *
- * @param config - Theme config from router, or null if theme is disabled
- */
-export function initThemeConfigSync(config: ResolvedThemeConfig | null): void {
-  ssrThemeConfig = config;
-}
-
-/**
- * Get theme config for SSR/hydration.
- * Used by MetaTags to render the theme script.
- *
- * @returns Theme config if available, null otherwise
- */
-export function getSSRThemeConfig(): ResolvedThemeConfig | null {
-  return ssrThemeConfig;
-}
-
-/**
- * Get theme context (internal use)
- * Returns null if theme is not enabled
- */
 export function useThemeContext(): ThemeContextValue | null {
   return useContext(ThemeContext);
 }
 
 /**
  * Get theme context, throwing if not available
- * Use this in useTheme hook
+ * Used by useTheme hook
  */
 export function requireThemeContext(): ThemeContextValue {
   const ctx = useContext(ThemeContext);
@@ -63,7 +33,7 @@ export function requireThemeContext(): ThemeContextValue {
     throw new Error(
       "useTheme must be used within a ThemeProvider. " +
         "Make sure theme is enabled in your router config: " +
-        "createRouter({ theme: { ... } })"
+        "createRouter({ theme: { ... } })",
     );
   }
   return ctx;

package/src/theme/theme-script.ts

@@ -22,7 +22,6 @@ import type { ResolvedThemeConfig } from "./types.js";
  * - Handle all edge cases (no localStorage, no cookie, etc.)
  */
 export function generateThemeScript(config: ResolvedThemeConfig): string {
-  // Build the script as a string, then minify
   const script = `
 (function() {
   var storageKey = ${JSON.stringify(config.storageKey)};
@@ -33,17 +32,15 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
   var valueMap = ${JSON.stringify(config.value)};
   var themes = ${JSON.stringify(config.themes)};
 
-  // Read theme from cookie or localStorage
   function getStoredTheme() {
-    // Try cookie first (for SSR consistency)
     var cookies = document.cookie.split(';');
     for (var i = 0; i < cookies.length; i++) {
       var cookie = cookies[i].trim();
       if (cookie.indexOf(storageKey + '=') === 0) {
-        return decodeURIComponent(cookie.substring(storageKey.length + 1));
+        try { return decodeURIComponent(cookie.substring(storageKey.length + 1)); }
+        catch (e) { return cookie.substring(storageKey.length + 1); }
       }
     }
-    // Fall back to localStorage
     try {
       return localStorage.getItem(storageKey);
     } catch (e) {
@@ -51,7 +48,6 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
     }
   }
 
-  // Get system preference
   function getSystemTheme() {
     if (typeof window !== 'undefined' && window.matchMedia) {
       return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
@@ -59,7 +55,6 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
     return 'light';
   }
 
-  // Resolve "system" to actual theme
   function resolveTheme(theme) {
     if (theme === 'system' && enableSystem) {
       return getSystemTheme();
@@ -67,15 +62,12 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
     return theme;
   }
 
-  // Apply theme to HTML element
   function applyTheme(theme) {
     var resolved = resolveTheme(theme);
     var value = valueMap[resolved] || resolved;
     var el = document.documentElement;
 
-    // Apply attribute
     if (attribute === 'class') {
-      // Remove all theme classes, then add current
       for (var i = 0; i < themes.length; i++) {
         var v = valueMap[themes[i]] || themes[i];
         el.classList.remove(v);
@@ -85,22 +77,18 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
       el.setAttribute(attribute, value);
     }
 
-    // Set color-scheme for native dark mode support
     if (enableColorScheme) {
       el.style.colorScheme = resolved;
     }
   }
 
-  // Get stored theme or use default
   var stored = getStoredTheme();
   var theme = stored && (stored === 'system' || themes.indexOf(stored) !== -1)
     ? stored
     : defaultTheme;
 
-  // Apply immediately
   applyTheme(theme);
 
-  // Listen for system preference changes (for "system" theme)
   if (enableSystem && typeof window !== 'undefined' && window.matchMedia) {
     try {
       window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function() {
@@ -116,7 +104,6 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
 })();
 `;
 
-  // Minify by removing comments, extra whitespace, and newlines
   return minifyScript(script);
 }
 
@@ -125,23 +112,25 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
  * Removes comments, extra whitespace, and unnecessary newlines
  */
 function minifyScript(script: string): string {
-  return script
-    // Remove single-line comments
-    .replace(/\/\/.*$/gm, "")
-    // Remove multi-line comments
-    .replace(/\/\*[\s\S]*?\*\//g, "")
-    // Remove leading/trailing whitespace from lines
-    .split("\n")
-    .map((line) => line.trim())
-    .filter((line) => line.length > 0)
-    .join("")
-    // Collapse multiple spaces to single space
-    .replace(/\s+/g, " ")
-    // Remove spaces around operators and punctuation
-    .replace(/\s*([{};,=!<>()[\]+\-*/&|?:])\s*/g, "$1")
-    // Add back necessary spaces (e.g., "var x")
-    .replace(/(var|function|return|if|for|try|catch|typeof|else)\(/g, "$1 (")
-    .replace(/\)([a-zA-Z])/g, ") $1");
+  return (
+    script
+      // Remove single-line comments
+      .replace(/\/\/.*$/gm, "")
+      // Remove multi-line comments
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      // Remove leading/trailing whitespace from lines
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0)
+      .join("")
+      // Collapse multiple spaces to single space
+      .replace(/\s+/g, " ")
+      // Remove spaces around operators and punctuation
+      .replace(/\s*([{};,=!<>()[\]+\-*/&|?:])\s*/g, "$1")
+      // Add back necessary spaces (e.g., "var x")
+      .replace(/(var|function|return|if|for|try|catch|typeof|else)\(/g, "$1 (")
+      .replace(/\)([a-zA-Z])/g, ") $1")
+  );
 }
 
 /**

package/src/theme/use-theme.ts

@@ -27,9 +27,6 @@ import type { UseThemeReturn } from "./types.js";
  *
  * Must be used within a ThemeProvider (which is automatically included
  * in NavigationProvider when theme is enabled in router config).
- *
- * @returns Theme state and methods
- * @throws Error if used outside ThemeProvider
  */
 export function useTheme(): UseThemeReturn {
   const ctx = requireThemeContext();

package/src/types/boundaries.ts

@@ -0,0 +1,123 @@
+import type { ReactNode } from "react";
+
+export interface ErrorInfo {
+  message: string;
+  name: string;
+  code?: string;
+  stack?: string;
+  cause?: unknown;
+  segmentId: string;
+  segmentType:
+    | "layout"
+    | "route"
+    | "parallel"
+    | "loader"
+    | "middleware"
+    | "cache";
+}
+
+/**
+ * Props passed to server-side error boundary fallback components
+ *
+ * Server error boundaries don't have a reset function since the error
+ * occurred during server rendering. Users can navigate away or refresh.
+ *
+ * @example
+ * ```typescript
+ * function ProductErrorFallback({ error }: ErrorBoundaryFallbackProps) {
+ *   return (
+ *     <div>
+ *       <h2>Something went wrong loading the product</h2>
+ *       <p>{error.message}</p>
+ *       <a href="/">Go home</a>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export interface ErrorBoundaryFallbackProps {
+  error: ErrorInfo;
+}
+
+export type ErrorBoundaryHandler = (
+  props: ErrorBoundaryFallbackProps,
+) => ReactNode;
+
+/**
+ * Props passed to client-side error boundary fallback components
+ *
+ * Client error boundaries have a reset function that clears the error state
+ * and re-renders the children.
+ *
+ * @example
+ * ```typescript
+ * function ClientErrorFallback({ error, reset }: ClientErrorBoundaryFallbackProps) {
+ *   return (
+ *     <div>
+ *       <h2>Something went wrong</h2>
+ *       <p>{error.message}</p>
+ *       <button onClick={reset}>Try again</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export interface ClientErrorBoundaryFallbackProps {
+  error: ErrorInfo;
+  reset: () => void;
+}
+
+export type LoaderDataResult<T = unknown> =
+  | { __loaderResult: true; ok: true; data: T }
+  | {
+      __loaderResult: true;
+      ok: false;
+      error: ErrorInfo;
+      fallback: ReactNode | null;
+    };
+
+export function isLoaderDataResult(value: unknown): value is LoaderDataResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__loaderResult" in value &&
+    (value as any).__loaderResult === true
+  );
+}
+
+export interface NotFoundInfo {
+  message: string;
+  segmentId: string;
+  segmentType:
+    | "layout"
+    | "route"
+    | "parallel"
+    | "loader"
+    | "middleware"
+    | "cache";
+  pathname?: string;
+}
+
+/**
+ * Props passed to notFound boundary fallback components
+ *
+ * @example
+ * ```typescript
+ * function ProductNotFound({ notFound }: NotFoundBoundaryFallbackProps) {
+ *   return (
+ *     <div>
+ *       <h2>Product Not Found</h2>
+ *       <p>{notFound.message}</p>
+ *       <a href="/products">Browse all products</a>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export interface NotFoundBoundaryFallbackProps {
+  notFound: NotFoundInfo;
+}
+
+export type NotFoundBoundaryHandler = (
+  props: NotFoundBoundaryFallbackProps,
+) => ReactNode;

package/src/types/cache-types.ts

@@ -0,0 +1,207 @@
+/**
+ * Context passed to cache condition/key/tags functions.
+ *
+ * This is a subset of RequestContext that's guaranteed to be available
+ * during cache key generation (before middleware runs).
+ *
+ * Note: While the full RequestContext is passed, middleware-set variables
+ * read via `ctx.get()` may not be populated yet since cache lookup happens
+ * before middleware execution.
+ */
+export type { RequestContext as CacheContext } from "../server/request-context.js";
+
+/**
+ * Cache configuration options for cache() DSL
+ *
+ * Controls how segments, layouts, and loaders are cached.
+ * Cache configuration inherits down the route tree unless overridden.
+ *
+ * @example
+ * ```typescript
+ * // Basic caching with TTL
+ * cache({ ttl: 60 }, () => [
+ *   layout(<BlogLayout />),
+ *   route("post/:slug"),
+ * ])
+ *
+ * // With stale-while-revalidate
+ * cache({ ttl: 60, swr: 300 }, () => [
+ *   route("product/:id"),
+ * ])
+ *
+ * // Conditional caching
+ * cache({
+ *   ttl: 300,
+ *   condition: (ctx) => !ctx.request.headers.get('x-preview'),
+ * }, () => [...])
+ *
+ * // Custom cache key
+ * cache({
+ *   ttl: 300,
+ *   key: (ctx) => `product-${ctx.params.id}-${ctx.searchParams.get('variant')}`,
+ * }, () => [...])
+ *
+ * // With tags for invalidation
+ * cache({
+ *   ttl: 300,
+ *   tags: (ctx) => [`product:${ctx.params.id}`, 'products'],
+ * }, () => [...])
+ * ```
+ */
+export interface CacheOptions<TEnv = unknown> {
+  /**
+   * Time-to-live in seconds.
+   * After this period, cached content is considered stale.
+   */
+  ttl: number;
+
+  /**
+   * Stale-while-revalidate window in seconds (after TTL).
+   * During this window, stale content is served immediately while
+   * fresh content is fetched in the background via waitUntil.
+   *
+   * @example
+   * // TTL: 60s, SWR: 300s
+   * // 0-60s: FRESH (serve from cache)
+   * // 60-360s: STALE (serve from cache, revalidate in background)
+   * // 360s+: EXPIRED (cache miss, fetch fresh)
+   */
+  swr?: number;
+
+  /**
+   * Override the cache store for this boundary.
+   * When specified, this boundary and its children use this store
+   * instead of the app-level store from handler config.
+   *
+   * Useful for:
+   * - Different backends per route section (memory vs KV vs Redis)
+   * - Loader-specific caching strategies
+   * - Hot data in fast cache, cold data in larger/slower cache
+   *
+   * Tag invalidation caveat: a per-boundary store becomes reachable by
+   * `updateTag()` / `revalidateTag()` once this boundary is resolved in the
+   * current process. If the store is *durable* (shared across processes) and the
+   * very first request to a fresh worker is an `updateTag`/`revalidateTag` for a
+   * tag held only in this store - before this boundary is matched - that
+   * invalidation can miss it. For data you invalidate by tag, prefer the
+   * app-level store (always reachable), or ensure the boundary is warmed.
+   *
+   * @example
+   * ```typescript
+   * const kvStore = new CloudflareKVStore(env.CACHE_KV);
+   * const memoryStore = new MemorySegmentCacheStore({ defaults: { ttl: 10 } });
+   *
+   * // Fast memory cache for hot data
+   * cache({ store: memoryStore }, () => [
+   *   route("dashboard"),
+   * ])
+   *
+   * // KV for larger, less frequently accessed data
+   * cache({ store: kvStore, ttl: 3600 }, () => [
+   *   route("archive/:year"),
+   * ])
+   * ```
+   */
+  store?: import("../cache/types.js").SegmentCacheStore;
+
+  /**
+   * Conditional cache read function.
+   * Return false to skip cache for this request (always fetch fresh).
+   *
+   * Has access to full RequestContext including env, request, params, cookies, etc.
+   * Note: Middleware-set variables read via `ctx.get()` may not be populated yet.
+   *
+   * @example
+   * ```typescript
+   * condition: (ctx) => {
+   *   // Skip cache for preview mode
+   *   if (ctx.request.headers.get('x-preview')) return false;
+   *   // Skip cache for authenticated users
+   *   if (ctx.request.headers.has('authorization')) return false;
+   *   return true;
+   * }
+   * ```
+   */
+  condition?: (
+    ctx: import("../server/request-context.js").RequestContext<TEnv>,
+  ) => boolean;
+
+  /**
+   * Custom cache key function - FULL OVERRIDE.
+   * Bypasses default key generation AND store's keyGenerator.
+   *
+   * Has access to full RequestContext including env, request, params, cookies, etc.
+   * Note: Middleware-set variables read via `ctx.get()` may not be populated yet.
+   *
+   * @example
+   * ```typescript
+   * // Include query params in cache key
+   * key: (ctx) => `product-${ctx.params.id}-${ctx.searchParams.get('variant')}`
+   *
+   * // Include env bindings
+   * key: (ctx) => `${ctx.env.REGION}:product:${ctx.params.id}`
+   *
+   * // Include cookies
+   * key: (ctx) => `${cookies().get('locale')?.value ?? 'en'}:${ctx.pathname}`
+   * ```
+   */
+  key?: (
+    ctx: import("../server/request-context.js").RequestContext<TEnv>,
+  ) => string | Promise<string>;
+
+  /**
+   * Tags for cache invalidation.
+   * Can be a static array or a function that returns tags.
+   *
+   * The built-in `MemorySegmentCacheStore` and `CFCacheStore` index by tag.
+   * Invalidate on demand with `updateTag(...tags)` (awaitable, read-your-own-writes;
+   * for server actions) or `revalidateTag(...tags)` (background hard-purge, not
+   * awaited; for route handlers / webhooks). For `CFCacheStore`, distributed
+   * invalidation requires a `kv` namespace (markers live in that same namespace).
+   *
+   * @example
+   * ```typescript
+   * // Static tags
+   * tags: ['products', 'catalog']
+   *
+   * // Dynamic tags
+   * tags: (ctx) => [`product:${ctx.params.id}`, 'products']
+   * ```
+   */
+  tags?:
+    | string[]
+    | ((
+        ctx: import("../server/request-context.js").RequestContext<TEnv>,
+      ) => string[]);
+}
+
+/**
+ * Partial cache options for cache() DSL.
+ *
+ * When `ttl` is not specified, it will use the default from cache config.
+ * This allows cache() calls to inherit app-level defaults:
+ *
+ * @example
+ * ```typescript
+ * // App-level default (in handler config)
+ * cache: { store: myStore, defaults: { ttl: 60 } }
+ *
+ * // Route-level (inherits ttl from defaults)
+ * cache(() => [
+ *   route("products"),
+ * ])
+ *
+ * // Override with explicit ttl
+ * cache({ ttl: 300 }, () => [...])
+ * ```
+ */
+export type PartialCacheOptions<TEnv = unknown> = Partial<CacheOptions<TEnv>>;
+
+/**
+ * Cache entry configuration stored in EntryData.
+ * Represents the resolved cache config for a segment.
+ */
+export interface EntryCacheConfig {
+  /** Cache options (false means caching disabled for this entry) - ttl is optional, uses defaults */
+  options: PartialCacheOptions | false;
+}

package/src/types/error-types.ts

@@ -0,0 +1,132 @@
+/**
+ * Phase where the error occurred during request handling.
+ *
+ * Coverage notes:
+ * - "routing": Invoked when route matching fails (router.ts, rsc/handler.ts)
+ * - "manifest": Reserved for manifest loading errors (not currently invoked)
+ * - "middleware": Reserved for middleware execution errors (errors propagate to handler phase)
+ * - "loader": Invoked when loader execution fails (router.ts via wrapLoaderWithErrorHandling, rsc/handler.ts)
+ * - "handler": Invoked when route/layout handler execution fails (router.ts)
+ * - "rendering": Invoked during SSR rendering errors (ssr/index.tsx, separate callback)
+ * - "action": Invoked when server action execution fails (rsc/handler.ts, router.ts)
+ * - "revalidation": Invoked when revalidation fails (router.ts, conditional with action)
+ * - "origin": Invoked when cross-origin request validation rejects a request (rsc/handler.ts)
+ * - "unknown": Fallback for unclassified errors (not currently invoked)
+ */
+export type ErrorPhase =
+  | "routing"
+  | "manifest"
+  | "middleware"
+  | "loader"
+  | "handler"
+  | "rendering"
+  | "action"
+  | "revalidation"
+  | "cache"
+  | "prerender"
+  | "static"
+  | "origin"
+  | "unknown";
+
+/**
+ * Comprehensive context passed to onError callback
+ *
+ * Provides all available information about where and when an error occurred
+ * during request handling. The callback can use this for logging, monitoring,
+ * error tracking services, or custom error responses.
+ *
+ * @example
+ * ```typescript
+ * const router = createRouter<AppEnv>({
+ *   onError: (context) => {
+ *     // Log to error tracking service
+ *     errorTracker.capture({
+ *       error: context.error,
+ *       phase: context.phase,
+ *       url: context.request.url,
+ *       route: context.routeKey,
+ *       userId: context.env?.user?.id,
+ *     });
+ *
+ *     // Log to console with context
+ *     console.error(`[${context.phase}] Error in ${context.routeKey}:`, {
+ *       message: context.error.message,
+ *       segment: context.segmentId,
+ *       duration: context.duration,
+ *     });
+ *   },
+ * });
+ * ```
+ */
+export interface OnErrorContext<TEnv = any> {
+  error: Error;
+  phase: ErrorPhase;
+  request: Request;
+  url: URL;
+  pathname: string;
+  method: string;
+  /** Matched route key (if available) e.g., "shop.products.detail" */
+  routeKey?: string;
+  /** Route params (if available) e.g., { slug: "headphones" } */
+  params?: Record<string, string>;
+  /** Segment ID where error occurred (if available) e.g., "M1L0" for a layout, "M1R0" for a route */
+  segmentId?: string;
+  /** Segment type where error occurred (if available) */
+  segmentType?: "layout" | "route" | "parallel" | "loader" | "middleware";
+  /** Loader name (if error occurred in a loader) */
+  loaderName?: string;
+  /** Middleware name/id (if error occurred in middleware) */
+  middlewareId?: string;
+  /** Action ID (if error occurred during server action) e.g., "src/actions.ts#addToCart" */
+  actionId?: string;
+  /** Environment/bindings (platform context) */
+  env?: TEnv;
+  /** Duration from request start to error (milliseconds) */
+  duration?: number;
+  /** Whether this is a partial/navigation request */
+  isPartial?: boolean;
+  /** Whether an error boundary caught the error */
+  handledByBoundary?: boolean;
+  /** Stack trace (if available) */
+  stack?: string;
+
+  /**
+   * Additional metadata specific to the error phase. For the `cache` phase,
+   * `metadata.category` is a `CacheErrorCategory` (exported from
+   * `@rangojs/router/cache`) identifying the failure kind, e.g. `cache-read`
+   * (transient outage, degraded to a miss) vs `cache-corrupt` (faulty entry
+   * self-healed) vs `cache-invalidate` (a failed background revalidateTag).
+   */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Callback function for error handling
+ *
+ * Called whenever an error occurs during request handling.
+ * The callback is for notification/logging purposes - it cannot
+ * modify the error handling flow (use errorBoundary for that).
+ *
+ * @param context - Comprehensive error context
+ *
+ * @example
+ * ```typescript
+ * const onError: OnErrorCallback = (context) => {
+ *   // Send to error tracking service
+ *   Sentry.captureException(context.error, {
+ *     tags: {
+ *       phase: context.phase,
+ *       route: context.routeKey,
+ *     },
+ *     extra: {
+ *       url: context.url.toString(),
+ *       params: context.params,
+ *       duration: context.duration,
+ *     },
+ *   });
+ * };
+ * ```
+ */
+export type OnErrorCallback<TEnv = any> = (
+  context: OnErrorContext<TEnv>,
+) => void | Promise<void>;