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

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 and useAction 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,56 +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";
 
-// 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,
@@ -404,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/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

@@ -46,15 +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>();
 
-// Monotonic counter for runtime fallback ids (see createHandle). Module-scoped
-// and deterministic, so each createHandle() call gets a stable, unique id within
-// the process. Only used when no build id was injected (a bare unit test).
+// Monotonic counter for runtime fallback ids (see createHandle). Only used
+// when no build id was injected (a bare unit test).
 let runtimeHandleIdCounter = 0;
 
-/**
- * Look up a collect function from the registry by handle $$id.
- * Returns undefined if not registered (falls back to defaultCollect in useHandle).
- */
 export function getCollectFn(
   id: string,
 ): ((segments: unknown[][]) => unknown) | undefined {
@@ -127,8 +122,6 @@ export function createHandle<TData, TAccumulated = TData[]>(
     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).
   collectRegistry.set(
     handleId,
     collectFn as (segments: unknown[][]) => unknown,
@@ -140,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" &&

package/src/handles/MetaTags.tsx

@@ -97,24 +97,18 @@ function isPromise(value: unknown): value is Promise<unknown> {
   return value !== null && typeof value === "object" && "then" in value;
 }
 
-/**
- * Render a single meta descriptor as a React element.
- */
 function renderMetaDescriptor(
   descriptor: MetaDescriptorBase,
   index: number,
 ): React.ReactNode {
-  // charset
   if (hasCharSet(descriptor)) {
     return <meta key="charSet" charSet={descriptor.charSet} />;
   }
 
-  // title
   if (hasTitle(descriptor)) {
     return <title key="title">{descriptor.title}</title>;
   }
 
-  // name + content (description, viewport, etc.)
   if (hasNameContent(descriptor)) {
     return (
       <meta
@@ -125,7 +119,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // property + content (Open Graph, etc.)
   if (hasPropertyContent(descriptor)) {
     return (
       <meta
@@ -136,7 +129,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // http-equiv + content
   if (hasHttpEquivContent(descriptor)) {
     return (
       <meta
@@ -147,7 +139,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // JSON-LD structured data
   if (hasScriptLdJson(descriptor)) {
     const json = JSON.stringify(descriptor["script:ld+json"]);
     return (
@@ -159,7 +150,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // Custom tagName (meta or link with arbitrary attributes)
   if (hasTagName(descriptor)) {
     const { tagName, ...rest } = descriptor;
     if (tagName === "link") {
@@ -180,7 +170,6 @@ function renderMetaDescriptor(
     }
   }
 
-  // Fallback: treat as meta attributes
   return (
     <meta
       key={`meta-fallback-${index}`}
@@ -189,9 +178,6 @@ function renderMetaDescriptor(
   );
 }
 
-/**
- * Wrapper component to resolve a Promise<MetaDescriptorBase> using use().
- */
 function AsyncMetaTag({
   promise,
   index,

package/src/handles/meta.ts

@@ -35,9 +35,6 @@ import type {
   UnsetDescriptor,
 } from "../router/types.js";
 
-/**
- * Type guard for unset descriptor
- */
 function isUnsetDescriptor(
   descriptor: MetaDescriptor,
 ): descriptor is UnsetDescriptor {
@@ -49,9 +46,6 @@ function isUnsetDescriptor(
   );
 }
 
-/**
- * Type guard for title descriptor (any form)
- */
 function isTitleDescriptor(
   descriptor: MetaDescriptor,
 ): descriptor is { title: TitleDescriptor } {
@@ -62,9 +56,6 @@ function isTitleDescriptor(
   );
 }
 
-/**
- * Type guard for title template descriptor
- */
 function isTitleTemplate(
   title: TitleDescriptor,
 ): title is { template: string; default: string } {
@@ -76,21 +67,13 @@ function isTitleTemplate(
   );
 }
 
-/**
- * Type guard for absolute title descriptor
- */
 function isAbsoluteTitle(
   title: TitleDescriptor,
 ): title is { absolute: string } {
   return typeof title === "object" && title !== null && "absolute" in title;
 }
 
-/**
- * Get a unique key for a meta descriptor for deduplication.
- * Returns undefined for descriptors that shouldn't be deduplicated.
- */
 function getMetaKey(descriptor: MetaDescriptor): string | undefined {
-  // Skip unset descriptors - they are processed separately
   if (isUnsetDescriptor(descriptor)) {
     return undefined;
   }
@@ -110,13 +93,10 @@ function getMetaKey(descriptor: MetaDescriptor): string | undefined {
     return `httpEquiv:${descriptor.httpEquiv}`;
   }
   if ("script:ld+json" in descriptor) {
-    // JSON-LD scripts can have multiple, don't dedupe by default
     return undefined;
   }
   if ("tagName" in descriptor) {
-    // For link tags, dedupe by rel if present
     if (descriptor.tagName === "link" && "rel" in descriptor) {
-      // Some link rels should be unique (canonical), others not (stylesheet)
       const uniqueRels = ["canonical", "icon", "apple-touch-icon"];
       if (uniqueRels.includes(descriptor.rel as string)) {
         return `link:${descriptor.rel}`;
@@ -136,9 +116,6 @@ const defaultMetaDescriptors: MetaDescriptor[] = [
   { name: "viewport", content: "width=device-width, initial-scale=1" },
 ];
 
-/**
- * Helper to add or replace a descriptor in the result array
- */
 function addOrReplace(
   result: MetaDescriptor[],
   keyToIndex: Map<string, number>,
@@ -155,9 +132,6 @@ function addOrReplace(
   }
 }
 
-/**
- * Helper to update indices after removing an element
- */
 function updateIndicesAfterRemoval(
   keyToIndex: Map<string, number>,
   removedIndex: number,
@@ -169,17 +143,11 @@ function updateIndicesAfterRemoval(
   }
 }
 
-/**
- * Collect function for Meta handle.
- * Includes default meta descriptors, then deduplicates by key with later routes overriding earlier ones.
- * Supports title templates, absolute titles, and unset descriptors.
- */
 function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
   const result: MetaDescriptor[] = [];
   const keyToIndex = new Map<string, number>();
   let titleTemplate: string | undefined;
 
-  // Add defaults first so they can be overridden
   for (const descriptor of defaultMetaDescriptors) {
     const key = getMetaKey(descriptor);
     if (key !== undefined) {
@@ -190,7 +158,6 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
 
   for (const descriptors of segments) {
     for (const descriptor of descriptors) {
-      // Handle unset descriptors
       if (isUnsetDescriptor(descriptor)) {
         const keyToRemove = descriptor.unset;
         if (keyToIndex.has(keyToRemove)) {
@@ -202,14 +169,11 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
         continue;
       }
 
-      // Handle title descriptors with template/absolute support
       if (isTitleDescriptor(descriptor)) {
         const titleValue = descriptor.title;
 
         if (isTitleTemplate(titleValue)) {
-          // Store template for subsequent title descriptors in child segments
           titleTemplate = titleValue.template;
-          // Set the default title
           addOrReplace(
             result,
             keyToIndex,
@@ -220,7 +184,6 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
         }
 
         if (isAbsoluteTitle(titleValue)) {
-          // Absolute title bypasses any template
           addOrReplace(
             result,
             keyToIndex,
@@ -230,7 +193,6 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
           continue;
         }
 
-        // String title - apply template if one exists
         const finalTitle = titleTemplate
           ? titleTemplate.replace("%s", titleValue as string)
           : titleValue;
@@ -243,7 +205,6 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
         continue;
       }
 
-      // Handle all other descriptors
       const key = getMetaKey(descriptor);
       addOrReplace(result, keyToIndex, descriptor, key);
     }