@rangojs/router 0.0.0-experimental.122 → 0.0.0-experimental.125

package/src/cache/read-through-swr.ts

@@ -13,10 +13,15 @@
 
 import type { CacheItemResult, CacheItemOptions } from "./types.js";
 import { runBackground } from "./background-task.js";
+import { reportCacheError } from "./cache-error.js";
+import type { CacheErrorReporter } from "./cache-error.js";
 
-interface WaitUntilHost {
+// The host carries both the optional waitUntil (for background scheduling) and
+// the CacheErrorReporter seam (for routing degradation errors through onError).
+// loader-cache.ts passes the request context, which provides both.
+type WaitUntilHost = {
   waitUntil?: (fn: () => Promise<void>) => void;
-}
+} & CacheErrorReporter;
 
 export interface ReadThroughItemConfig<T> {
   /** Retrieve a cached item by key */
@@ -74,11 +79,20 @@ export async function readThroughItem<T>(
     host,
   } = config;
 
-  // Cache lookup
+  // Cache lookup. An infra read failure (getItem) is reported by the store
+  // itself, so here we just degrade to a miss. A deserialize failure is a
+  // corrupt/truncated stored entry, which this layer owns: report it LOUD as
+  // cache-corrupt, then fall through to a fresh execution (the miss-path write
+  // self-heals the bad entry).
+  let cached: CacheItemResult | null = null;
   try {
-    const cached = await getItem(key);
+    cached = await getItem(key);
+  } catch {
+    cached = null;
+  }
 
-    if (cached) {
+  if (cached) {
+    try {
       const data = await deserialize(cached.value);
 
       if (!cached.shouldRevalidate) {
@@ -97,16 +111,27 @@ export async function readThroughItem<T>(
             if (serialized !== null) {
               await setItem(key, serialized, storeOptions);
             }
-          } catch {
-            // Background revalidation failed silently
+          } catch (error) {
+            reportCacheError(
+              error,
+              "stale-revalidation",
+              "[read-through] background revalidation",
+              host ?? undefined,
+            );
           }
         },
         true,
       );
       return data;
+    } catch (error) {
+      reportCacheError(
+        error,
+        "cache-corrupt",
+        "[read-through] deserialize stored entry",
+        host ?? undefined,
+      );
+      // fall through to fresh execution
     }
-  } catch {
-    // Cache lookup failed, fall through to fresh execution
   }
 
   // Cache miss
@@ -123,8 +148,13 @@ export async function readThroughItem<T>(
           await setItem(key, serialized, storeOptions);
           onCached?.();
         }
-      } catch {
-        // Cache write failed silently
+      } catch (error) {
+        reportCacheError(
+          error,
+          "cache-write",
+          "[read-through] cache write",
+          host ?? undefined,
+        );
       }
     },
     true,

package/src/cache/segment-codec.ts

@@ -16,10 +16,6 @@ import {
 } from "@vitejs/plugin-rsc/rsc";
 import { createFromReadableStream } from "@vitejs/plugin-rsc/rsc";
 
-// ============================================================================
-// Stream Utilities (internal)
-// ============================================================================
-
 /**
  * Convert a ReadableStream to a string.
  */
@@ -55,10 +51,6 @@ export function stringToStream(str: string): ReadableStream<Uint8Array> {
   });
 }
 
-// ============================================================================
-// RSC Serialization Primitives (internal)
-// ============================================================================
-
 /**
  * RSC-serialize a value using React Server Components stream.
  * Used for serializing loaderData, layout, loading components etc.
@@ -90,10 +82,6 @@ export async function rscDeserialize<T>(
   return createFromReadableStream<T>(stream, { temporaryReferences });
 }
 
-// ============================================================================
-// Null-Preserving RSC Serialization (for caching)
-// ============================================================================
-
 /**
  * RSC-serialize any value including null.
  * Unlike rscSerialize(), this does NOT skip null — it serializes it through
@@ -122,10 +110,6 @@ export async function deserializeResult<T>(encoded: string): Promise<T> {
   return createFromReadableStream<T>(stream, { temporaryReferences });
 }
 
-// ============================================================================
-// Public API
-// ============================================================================
-
 /**
  * RSC-deserialize a single encoded component string back to a React element.
  * Used by the static handler runtime to revive pre-rendered components.

package/src/cache/types.ts

@@ -12,10 +12,6 @@
 import type { ResolvedSegment } from "../types.js";
 import type { RequestContext } from "../server/request-context.js";
 
-// ============================================================================
-// Segment Cache Store (low-level storage interface)
-// ============================================================================
-
 /**
  * Result from cache get() including data and revalidation status
  */
@@ -116,12 +112,6 @@ export interface SegmentCacheStore<TEnv = unknown> {
    */
   clear?(): Promise<void>;
 
-  // ============================================================================
-  // Document Cache Methods (optional)
-  // ============================================================================
-  // These methods are for caching full HTTP responses (document-level caching).
-  // Stores that support response caching should implement these methods.
-
   /**
    * Get a cached Response by key.
    * Returns the response and whether it should be revalidated (SWR).
@@ -146,12 +136,6 @@ export interface SegmentCacheStore<TEnv = unknown> {
     tags?: string[],
   ): Promise<void>;
 
-  // ============================================================================
-  // Function Cache Methods (optional, for "use cache" directive)
-  // ============================================================================
-  // These methods cache individual function/component return values.
-  // Stores that support "use cache" should implement these methods.
-
   /**
    * Get a cached function result by key.
    * Returns the serialized value, optional handle data, and staleness flag.
@@ -170,10 +154,6 @@ export interface SegmentCacheStore<TEnv = unknown> {
     options?: CacheItemOptions,
   ): Promise<void>;
 
-  // ============================================================================
-  // Tag-based Invalidation (optional)
-  // ============================================================================
-
   /**
    * Invalidate every cache entry (segment, response, item) tagged with any of
    * `tags`. Store-level primitive that the public updateTag()/revalidateTag()
@@ -264,10 +244,6 @@ export interface CachedEntryData {
   taggedAt?: number;
 }
 
-// ============================================================================
-// Cache Configuration
-// ============================================================================
-
 /**
  * Default cache options applied to all cache() boundaries.
  * Individual cache() calls can override any of these values.
@@ -292,82 +268,8 @@ export interface CacheDefaults {
   swr?: number;
 }
 
-/**
- * Cache configuration for RSC handler
- */
-export interface CacheConfig {
-  /** Cache store implementation (includes defaults) */
-  store: SegmentCacheStore;
-  /** Enable/disable caching (default: true) */
-  enabled?: boolean;
-}
-
-/**
- * Cache configuration - can be static or a function receiving env
- */
-export type CacheConfigOrFactory<TEnv> =
-  | CacheConfig
-  | ((env: TEnv) => CacheConfig);
-
-// ============================================================================
-// Segment Cache Provider (request-level interface)
-// ============================================================================
-
 /**
  * Handle data for a single segment
  * Structure: { handleName: [values...] }
  */
 export type SegmentHandleData = Record<string, unknown[]>;
-
-/**
- * Result from cache get() including segments and their handle data
- * Each entry can produce multiple segments (main + parallels)
- */
-export interface CachedEntryResult {
-  /** All segments for this entry (main segment + parallels) */
-  segments: ResolvedSegment[];
-  /** Handle data keyed by segment ID */
-  handles: Record<string, SegmentHandleData>;
-}
-
-/**
- * Segment cache provider interface
- *
- * Used by router to check/store segment cache during matching.
- * Accessed via request context - if not present, caching is disabled.
- *
- * @internal Not currently implemented - CacheScope is used directly.
- * Reserved for future extensibility.
- */
-export interface SegmentCacheProvider {
-  /** Whether caching is enabled for this request */
-  readonly enabled: boolean;
-
-  /**
-   * Get cached segments and restore handles/loaders.
-   *
-   * Combines cache get with handle replay and loader data restoration.
-   * Returns tuple of [segments, segmentIds] if cache hit, null if miss or disabled.
-   *
-   * @param cacheKey - Cache key to look up
-   * @param params - Route params for cache key generation
-   * @param loaderPromises - Map to restore loader data into
-   * @returns Tuple of [segments, segmentIds] or null if miss
-   */
-  restore(
-    cacheKey: string,
-    params: Record<string, string>,
-    loaderPromises: Map<string, Promise<any>>,
-  ): Promise<[ResolvedSegment[], string[]] | null>;
-
-  /**
-   * Cache entry with automatic handle collection (non-blocking).
-   *
-   * Schedules caching via waitUntil - handles are collected after they settle.
-   * Validates segments have actual components before caching.
-   *
-   * @param cacheKey - The cache key to store under
-   * @param segments - All resolved segments for this entry
-   */
-  cacheEntry(cacheKey: string, segments: ResolvedSegment[]): void;
-}

package/src/client.rsc.tsx

@@ -14,60 +14,43 @@
 export {
   Outlet,
   ParallelOutlet,
-  OutletProvider,
   useOutlet,
   useLoader,
   ErrorBoundary,
   type ErrorBoundaryProps,
 } from "./client.js";
 
-// Re-export the server's createLoader for RSC context
-// This version includes the actual loader function
 export { createLoader } from "./route-definition.js";
 
-// Re-export Link component (can be used in server components)
 export {
   Link,
   type LinkProps,
   type PrefetchStrategy,
 } from "./browser/react/Link.js";
 
-// Re-export ScrollRestoration (can be used in server components)
 export {
   ScrollRestoration,
   type ScrollRestorationProps,
 } from "./browser/react/ScrollRestoration.js";
 
-// Re-export NavigationProvider (needed for setup)
 export {
   NavigationProvider,
   type NavigationProviderProps,
 } from "./browser/react/NavigationProvider.js";
 
-// Re-export href function (can be used in server components)
 export { href } from "./href-client.js";
 
-// Mount context re-exports (useMount is client-only, but MountContext can be referenced)
 export { MountContext } from "./browser/react/mount-context.js";
 
-// Note: useNavigation, useAction, useClientCache are NOT re-exported here
-// because they use client-side state and should only be used in client components
+// useNavigation and useAction are NOT re-exported here because they use client-side state
 
-// Handle API - for accumulating data across route segments
-// Works in both RSC and client contexts
 export { createHandle, isHandle, type Handle } from "./handle.js";
 
-// Built-in handles
-// Meta handle works in RSC context
 export { Meta } from "./handles/meta.js";
-// MetaTags is a "use client" component that can be imported from RSC
 export { MetaTags } from "./handles/MetaTags.js";
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
-// Breadcrumbs handle works in RSC context
 export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 
-// Location state - createLocationState works in RSC (just creates definition)
-// useLocationState is NOT exported here as it uses client hooks
 export {
   createLocationState,
   type LocationStateDefinition,
@@ -75,14 +58,10 @@ export {
   type LocationStateOptions,
 } from "./browser/react/location-state-shared.js";
 
-// Re-export useHref - it's a "use client" hook
 export { useHref } from "./browser/react/use-href.js";
 
-// Re-export useReverse - it's a "use client" hook
 export { useReverse } from "./browser/react/use-reverse.js";
 
-// Re-export useHandle - it's a "use client" hook
 export { useHandle } from "./browser/react/use-handle.js";
 
-// Re-export useLocationState - it's a "use client" hook
 export { useLocationState } from "./browser/react/location-state.js";

package/src/client.tsx

@@ -111,6 +111,11 @@ function useSlotSegment(
  * the parallel segment with that slot name instead of the default content.
  * This is used for parallel routes and intercepting routes.
  *
+ * For a named slot, `<Outlet name="@x" />` is equivalent to
+ * `<ParallelOutlet name="@x" />` — both run the same resolution + wrapping
+ * pipeline. Convention: use bare `<Outlet />` for default content and
+ * `<ParallelOutlet name="@x" />` for named slots.
+ *
  * @param name - Optional slot name for parallel/intercept content (must start with @)
  *
  * @example
@@ -163,6 +168,9 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
  * is wrapped in Suspense with the loading component as fallback.
  * This enables streaming and navigation loading states for parallels.
  *
+ * Equivalent to `<Outlet name="@x" />` for a named slot; ParallelOutlet
+ * requires `name` and is named-slot-only, which reads clearer at the call site.
+ *
  * @param name - The slot name (must start with @, e.g., "@modal", "@sidebar")
  *
  * @example
@@ -186,10 +194,9 @@ export function ParallelOutlet({ name }: { name: `@${string}` }): ReactNode {
 }
 
 // OutletProvider is defined in outlet-provider.tsx to break a circular
-// dependency between client.tsx and route-content-wrapper.tsx.
-// Imported at the top of this file for local use in Outlet/ParallelOutlet,
-// and re-exported here for backwards compatibility.
-export { OutletProvider };
+// dependency between client.tsx and route-content-wrapper.tsx. It is imported
+// at the top of this file for local use in Outlet/ParallelOutlet only; it is an
+// internal component and is intentionally not part of the public ./client API.
 
 /**
  * Hook to access outlet content programmatically
@@ -210,7 +217,6 @@ export function useOutlet(): ReactNode {
   return context?.content ?? null;
 }
 
-// Loader hooks - re-exported from dedicated file
 export {
   useLoader,
   useFetchLoader,
@@ -329,12 +335,6 @@ export class ErrorBoundary extends Component<
   }
 }
 
-// ============================================================================
-// Re-exports from browser/react for convenience
-// These are the most commonly used client-side navigation utilities
-// ============================================================================
-
-// Navigation hooks
 export { useNavigation } from "./browser/react/use-navigation.js";
 export { useRouter } from "./browser/react/use-router.js";
 export { usePathname } from "./browser/react/use-pathname.js";
@@ -346,62 +346,48 @@ export type {
   ReadonlyURLSearchParams,
 } from "./browser/types.js";
 
-// Action state tracking hook
 export {
   useAction,
   type ServerActionFunction,
 } from "./browser/react/use-action.js";
 
-// Segments state hook
 export {
   useSegments,
   type SegmentsState,
 } from "./browser/react/use-segments.js";
 
-// Client cache controls hook
-export {
-  useClientCache,
-  type ClientCacheControls,
-} from "./browser/react/use-client-cache.js";
-
-// Provider
 export {
   NavigationProvider,
   type NavigationProviderProps,
 } from "./browser/react/NavigationProvider.js";
 
-// Link component
 export {
   Link,
   type LinkProps,
   type PrefetchStrategy,
   type StateOrGetter,
+  type LinkState,
 } from "./browser/react/Link.js";
 
-// Link status hook
 export {
   useLinkStatus,
   type LinkStatus,
 } from "./browser/react/use-link-status.js";
 
-// Scroll restoration
 export {
   ScrollRestoration,
   useScrollRestoration,
   type ScrollRestorationProps,
 } from "./browser/react/ScrollRestoration.js";
 
-// Handle data hook (client-side only — createHandle/isHandle are server APIs from the root export)
 export { type Handle } from "./handle.js";
 export { useHandle } from "./browser/react/use-handle.js";
 
-// Built-in handles
 export { Meta } from "./handles/meta.js";
 export { MetaTags } from "./handles/MetaTags.js";
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 
-// Location state - type-safe navigation state
 export {
   createLocationState,
   useLocationState,
@@ -410,29 +396,19 @@ export {
   type LocationStateOptions,
 } from "./browser/react/location-state.js";
 
-// Type-safe href for client-side path validation. The path and response types
-// are ambient as `Rango.Path` / `Rango.PathResponse` (declared in
-// href-client.ts) — no import needed.
+// Ambient Rango.Path / Rango.PathResponse types (declared in href-client.ts)
 export { href, type PatternToPath } from "./href-client.js";
 
-// Problem Details (RFC 9457) error body type for consuming JSON response routes.
-// On a non-2xx response, `await res.json()` yields this shape; on success the
-// body is the bare value (no envelope). Discriminate on `res.ok` / status.
+// RFC 9457 error type for JSON response routes
 export type { ProblemDetails } from "./urls.js";
 
-// Mount context for include() scoped components
 export { useMount } from "./browser/react/use-mount.js";
 export { MountContext } from "./browser/react/mount-context.js";
 
-// Mount-aware href hook - auto-prefixes paths with include() mount
 export { useHref } from "./browser/react/use-href.js";
 
-// Mount-aware reverse hook - resolves dot-prefixed names against an imported
-// generated routes map (from a urls() module's .gen.ts).
 export { useReverse } from "./browser/react/use-reverse.js";
 
-// Type-safe scoped reverse function for scopedReverse<typeof patterns>()
 export type { ScopedReverseFunction, LocalReverseFunction } from "./reverse.js";
 
-// Loader definition type - for typing loader props in client components
 export type { LoaderDefinition } from "./types.js";

package/src/component-utils.ts

@@ -5,6 +5,7 @@
  */
 
 import type { ComponentType } from "react";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 /**
  * Symbol used by React to mark client component references.
@@ -48,11 +49,21 @@ export function isClientComponent(
  *
  * @param component - The component to check
  * @param name - Name to use in error message (e.g., "document")
+ * @param opts.allowServerInTest - When true AND running under a test runner
+ *   (`isUnderTestRunner()`), relax ONLY the "use client" requirement: a server
+ *   component is accepted. The plugin's "use client" transform does not run in a
+ *   bare unit test, so a real exported `document` (almost every app sets one) has
+ *   no client marker and would otherwise throw at `createRouter`, blocking
+ *   `dispatch`/`assertGeneratedRoutesMatch` against the real router. The document
+ *   reference is irrelevant to those (no Flight render). The "not a JSX element"
+ *   guard still fires, and a real dev/build still throws (mirrors the runtime
+ *   fallback-id gating in handle.ts/loader.ts).
  * @throws Error if the component is not a client component
  */
 export function assertClientComponent(
   component: ComponentType<unknown> | unknown,
   name: string,
+  opts?: { allowServerInTest?: boolean },
 ): asserts component is ComponentType<unknown> {
   if (typeof component !== "function") {
     throw new Error(
@@ -62,6 +73,14 @@ export function assertClientComponent(
     );
   }
 
+  // Under a test runner the "use client" transform did not run, so a real
+  // server-rendered `document` has no client marker; accept it (the reference is
+  // never serialized in dispatch/route-map checks). Outside a test runner this
+  // still throws — the build-time safety net is preserved.
+  if (opts?.allowServerInTest && isUnderTestRunner()) {
+    return;
+  }
+
   if (!isClientComponent(component)) {
     throw new Error(
       `${name} must be a client component with "use client" directive at the top of the file. ` +

package/src/deps/ssr.ts

@@ -1,2 +1 @@
-// Re-export @vitejs/plugin-rsc/ssr for internal use by virtual entries
 export { createFromReadableStream } from "@vitejs/plugin-rsc/ssr";

package/src/handle.ts

@@ -1,4 +1,5 @@
 import { missingInjectedIdError } from "./missing-id-error.js";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 /**
  * Handle definition for accumulating data across route segments.
@@ -45,10 +46,10 @@ function defaultCollect<T>(segments: T[][]): T[] {
 // Used by useHandle() to recover collect when handle is deserialized from RSC prop.
 const collectRegistry = new Map<string, (segments: unknown[][]) => unknown>();
 
-/**
- * Look up a collect function from the registry by handle $$id.
- * Returns undefined if not registered (falls back to defaultCollect in useHandle).
- */
+// Monotonic counter for runtime fallback ids (see createHandle). Only used
+// when no build id was injected (a bare unit test).
+let runtimeHandleIdCounter = 0;
+
 export function getCollectFn(
   id: string,
 ): ((segments: unknown[][]) => unknown) | undefined {
@@ -95,24 +96,36 @@ export function createHandle<TData, TAccumulated = TData[]>(
   collect?: (segments: TData[][]) => TAccumulated,
   __injectedId?: string,
 ): Handle<TData, TAccumulated> {
-  const handleId = __injectedId ?? "";
+  let handleId = __injectedId ?? "";
 
-  if (!handleId && process.env.NODE_ENV === "development") {
-    throw missingInjectedIdError("Handle", "createHandle");
+  // No build-injected id. Under a test runner: fall back to a synthetic id so the
+  // collect registers below and the handle is exercisable in tests (useHandle,
+  // collectHandle, renderRoute's `handles` run the REAL collect). Otherwise (dev
+  // or a real build) it means an UNSUPPORTED handler shape the plugin skipped —
+  // fail loud. The rich, stack-parsing diagnostic stays behind the NODE_ENV check
+  // so a production build folds it away and tree-shakes missing-id-error.ts out,
+  // shipping the small throw instead. isUnderTestRunner() is runtime-safe.
+  if (!handleId) {
+    if (isUnderTestRunner()) {
+      handleId = `__rango_runtime_handle_${runtimeHandleIdCounter++}`;
+    } else if (process.env.NODE_ENV !== "production") {
+      throw missingInjectedIdError("Handle", "createHandle");
+    } else {
+      throw new Error(
+        "[rango] Handle is missing $$id — the build plugin did not inject one. " +
+          "Export it as `export const X = createHandle(...)`.",
+      );
+    }
   }
 
   const collectFn =
     collect ??
     (defaultCollect as unknown as (segments: TData[][]) => TAccumulated);
 
-  // Register collect in module-level registry so useHandle() can recover it
-  // when the handle is deserialized from RSC props (toJSON strips collect).
-  if (handleId) {
-    collectRegistry.set(
-      handleId,
-      collectFn as (segments: unknown[][]) => unknown,
-    );
-  }
+  collectRegistry.set(
+    handleId,
+    collectFn as (segments: unknown[][]) => unknown,
+  );
 
   return {
     __brand: "handle" as const,
@@ -120,9 +133,6 @@ export function createHandle<TData, TAccumulated = TData[]>(
   };
 }
 
-/**
- * Type guard to check if a value is a Handle.
- */
 export function isHandle(value: unknown): value is Handle<unknown, unknown> {
   return (
     typeof value === "object" &&