@rangojs/router 0.0.0-experimental.12 → 0.0.0-experimental.120

package/src/server.ts

@@ -1,98 +1,30 @@
 /**
- * rsc-router/server
+ * @rangojs/router/server — Internal subpath
  *
- * Server-only exports for route definition and building
- * These should only be imported in server-side handler files
+ * This module is NOT user-facing. Import from "@rangojs/router" instead.
+ *
+ * Exports here are consumed by the Vite plugin (discovery, manifest injection,
+ * virtual modules) and the RSC handler internals. They are not part of the
+ * public API and may change without notice.
  */
 
-// Route definition helpers (server-only)
-export {
-  createLoader,
-  redirect,
-  type RouteHelpers,
-  type RouteHandlers,
-} from "./route-definition.js";
-
-// Django-style URL patterns (server-only)
-export {
-  urls,
-  RESPONSE_TYPE,
-  type PathHelpers,
-  type PathOptions,
-  type UrlPatterns,
-  type IncludeOptions,
-  type ResponseHandler,
-  type ResponseHandlerContext,
-  type JsonResponseHandler,
-  type TextResponseHandler,
-  type JsonValue,
-  type ResponsePathFn,
-  type JsonResponsePathFn,
-  type TextResponsePathFn,
-  type RouteResponse,
-  type ResponseError,
-  type ResponseEnvelope,
-} from "./urls.js";
-
-// Re-export IncludeItem from route-types
-export type { IncludeItem } from "./route-types.js";
-
-// Core router (server-only)
-export {
-  createRouter,
-  RSC_ROUTER_BRAND,
-  RouterRegistry,
-  type RSCRouter,
-  type RSCRouterOptions,
-  type RootLayoutProps,
-} from "./router.js";
-
-// Type-safe reverse utilities (Django-style URL reversal)
-export {
-  createReverse,
-  type ReverseFunction,
-  type PrefixedRoutes,
-  type PrefixRoutePatterns,
-  type ParamsFor,
-  type SanitizePrefix,
-  type MergeRoutes,
-} from "./reverse.js";
-
-// Segment system (server-only)
-export { renderSegments } from "./segment-system.js";
-
-// Performance tracking (server-only)
-export { track } from "./server/context.js";
+// Router registry (used by Vite plugin for build-time discovery)
+export { RSC_ROUTER_BRAND, RouterRegistry } from "./router.js";
 
-// Handle API (works in both server and client contexts)
-export { createHandle, isHandle, type Handle } from "./handle.js";
-
-// Pre-render handler API
+// Host router registry (used by Vite plugin for host-router lazy discovery)
 export {
-  Prerender,
-  isPrerenderHandler,
-  type PrerenderHandlerDefinition,
-  type PrerenderOptions,
-  type BuildContext,
-} from "./prerender.js";
+  HostRouterRegistry,
+  type HostRouterRegistryEntry,
+} from "./host/router.js";
 
-// Static handler API
-export {
-  Static,
-  isStaticHandler,
-  type StaticHandlerDefinition,
-} from "./static-handler.js";
-
-// Built-in handles
-export { Meta } from "./handles/meta.js";
-
-// Loader registry (for GET-based loader fetching)
-export { registerLoaderById, setLoaderImports } from "./server/loader-registry.js";
-
-// Route map builder (for build-time manifest registration)
+// Route map builder (Vite plugin injects these via virtual modules)
 export {
   registerRouteMap,
   setCachedManifest,
+  clearCachedManifest,
+  clearAllRouterData,
+  getGlobalRouteMap,
+  getRouterManifest,
   setPrecomputedEntries,
   setRouteTrie,
   setManifestReadyPromise,
@@ -103,87 +35,17 @@ export {
   ensureRouterManifest,
 } from "./route-map-builder.js";
 
-// Request context (for accessing request data in server components/actions)
+// Loader registry (Vite plugin registers lazy loader imports)
+export {
+  registerLoaderById,
+  setLoaderImports,
+} from "./server/loader-registry.js";
+
+// Request context creation (used by RSC handler, not user-facing)
 export {
-  getRequestContext,
-  requireRequestContext,
   createRequestContext,
-  type RequestContext,
   type CreateRequestContextOptions,
 } from "./server/request-context.js";
 
-// Meta types
-export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
-
-// Middleware context types (Middleware type is exported from types.ts)
-export type {
-  MiddlewareContext,
-  CookieOptions,
-} from "./router/middleware.js";
-
-// Error classes and utilities
-export {
-  RouteNotFoundError,
-  DataNotFoundError,
-  notFound,
-  MiddlewareError,
-  HandlerError,
-  BuildError,
-  InvalidHandlerError,
-  sanitizeError,
-  RouterError,
-} from "./errors.js";
-
-// Component utilities
-export {
-  isClientComponent,
-  assertClientComponent,
-} from "./component-utils.js";
-
-// Debug utilities for route matching (development only)
-export {
-  enableMatchDebug,
-  getMatchDebugStats,
-} from "./router/pattern-matching.js";
-
-// Types (re-exported for convenience - user-facing only)
-export type {
-  // Configuration types
-  RouterEnv,
-  DefaultEnv,
-  RouteDefinition,
-  RouteConfig,
-  RouteDefinitionOptions,
-  TrailingSlashMode,
-  // Handler types
-  Handler,            // Supports params object, path pattern, or route name
-  HandlerContext,
-  ExtractParams,
-  GenericParams,
-  // Middleware types (also exported from router/middleware.js above)
-  Middleware,         // Supports env type and optional route name for params
-  // Revalidation types
-  RevalidateParams,
-  Revalidate,
-  RouteKeys,
-  // Loader types
-  LoaderDefinition,
-  LoaderFn,
-  LoaderContext,
-  // Error boundary types
-  ErrorInfo,
-  ErrorBoundaryFallbackProps,
-  ErrorBoundaryHandler,
-  ClientErrorBoundaryFallbackProps,
-  // NotFound boundary types
-  NotFoundInfo,
-  NotFoundBoundaryFallbackProps,
-  NotFoundBoundaryHandler,
-  // Error handling callback types
-  ErrorPhase,
-  OnErrorContext,
-  OnErrorCallback,
-} from "./types.js";
-
-// Path-based response type lookup from RegisteredRoutes
-export type { PathResponse } from "./href-client.js";
+// Component utilities (used internally for server/client boundary checks)
+export { isClientComponent, assertClientComponent } from "./component-utils.js";

package/src/ssr/index.tsx

@@ -1,14 +1,18 @@
 import React from "react";
-import { initHandleDataSync } from "../browser/react/use-handle.js";
-import { initSegmentsSync } from "../browser/react/use-segments.js";
-import { initThemeConfigSync } from "../theme/theme-context.js";
+import { renderSegments } from "../segment-system.js";
+import { filterSegmentOrder } from "../browser/react/filter-segment-order.js";
 import { ThemeProvider } from "../theme/ThemeProvider.js";
+import { NonceContext } from "../browser/react/nonce-context.js";
 import { NavigationStoreContext } from "../browser/react/context.js";
 import type { NavigationStoreContextValue } from "../browser/react/context.js";
 import type { HandleData } from "../browser/types.js";
 import type { ErrorPhase } from "../types.js";
+import type { ResolvedSegment } from "../types.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
-import type { EventController, DerivedNavigationState } from "../browser/event-controller.js";
+import type {
+  EventController,
+  DerivedNavigationState,
+} from "../browser/event-controller.js";
 
 /**
  * Options for injectRSCPayload
@@ -29,6 +33,13 @@ interface RenderToReadableStreamOptions {
   formState?: unknown;
 }
 
+/**
+ * ReadableStream with the allReady promise added by react-dom/server.edge.
+ */
+interface ReactDOMReadableStream extends ReadableStream<Uint8Array> {
+  allReady: Promise<void>;
+}
+
 /**
  * Options for the renderHTML function
  */
@@ -45,6 +56,14 @@ export interface SSRRenderOptions {
    * Nonce for Content Security Policy (CSP)
    */
   nonce?: string;
+
+  /**
+   * SSR stream mode.
+   *
+   * - `"stream"` (default) — start flushing HTML immediately.
+   * - `"allReady"` — await `stream.allReady` before returning.
+   */
+  streamMode?: import("../router/router-options.js").SSRStreamMode;
 }
 
 /**
@@ -54,22 +73,24 @@ export interface SSRDependencies<TEnv = unknown> {
   /**
    * createFromReadableStream from @vitejs/plugin-rsc/ssr
    */
-  createFromReadableStream: <T>(stream: ReadableStream<Uint8Array>) => Promise<T>;
+  createFromReadableStream: <T>(
+    stream: ReadableStream<Uint8Array>,
+  ) => Promise<T>;
 
   /**
    * renderToReadableStream from react-dom/server.edge
    */
   renderToReadableStream: (
     element: React.ReactNode,
-    options?: RenderToReadableStreamOptions
-  ) => Promise<ReadableStream<Uint8Array>>;
+    options?: RenderToReadableStreamOptions,
+  ) => Promise<ReactDOMReadableStream>;
 
   /**
    * injectRSCPayload from rsc-html-stream/server
    */
   injectRSCPayload: (
     rscStream: ReadableStream<Uint8Array>,
-    options?: InjectRSCPayloadOptions
+    options?: InjectRSCPayloadOptions,
   ) => TransformStream<Uint8Array, Uint8Array>;
 
   /**
@@ -101,13 +122,17 @@ export interface SSRDependencies<TEnv = unknown> {
  * RSC payload type (minimal interface for SSR)
  */
 interface RscPayload {
-  root: React.ReactNode;
   metadata?: {
+    segments?: ResolvedSegment[];
+    rootLayout?: React.ComponentType<{ children: React.ReactNode }>;
     handles?: AsyncGenerator<HandleData, void, unknown>;
     matched?: string[];
     pathname?: string;
+    params?: Record<string, string>;
+    basename?: string;
     themeConfig?: ResolvedThemeConfig | null;
     initialTheme?: Theme;
+    version?: string;
   };
 }
 
@@ -116,7 +141,7 @@ interface RscPayload {
  * Used for SSR where we need to await all handle data before rendering.
  */
 async function consumeAsyncGenerator(
-  generator: AsyncGenerator<HandleData, void, unknown>
+  generator: AsyncGenerator<HandleData, void, unknown>,
 ): Promise<HandleData> {
   let lastData: HandleData = {};
   for await (const data of generator) {
@@ -129,11 +154,26 @@ async function consumeAsyncGenerator(
  * Create a minimal event controller for SSR.
  * This provides the correct pathname so useNavigation returns the right value during SSR.
  */
-function createSsrEventController(pathname: string): EventController {
-  const location = new URL(pathname, "http://localhost");
+function createSsrEventController(opts: {
+  pathname: string;
+  params?: Record<string, string>;
+  handleData?: HandleData;
+  matched?: string[];
+}): EventController {
+  const location = new URL(opts.pathname, "http://localhost");
+  let params = opts.params ?? {};
+  const rawMatched = opts.matched ?? [];
+  const handleState = {
+    data: opts.handleData ?? {},
+    segmentOrder: filterSegmentOrder(rawMatched),
+    routeSegmentIds: rawMatched.filter(
+      (id) => !id.includes(".@") && !/D\d+\./.test(id),
+    ),
+  };
   const state: DerivedNavigationState = {
     state: "idle",
     isStreaming: false,
+    isNavigating: false,
     location,
     pendingUrl: null,
     inflightActions: [],
@@ -141,6 +181,7 @@ function createSsrEventController(pathname: string): EventController {
 
   return {
     getState: () => state,
+    getLocation: () => location,
     subscribe: () => () => {},
     getActionState: () => ({
       state: "idle",
@@ -152,7 +193,11 @@ function createSsrEventController(pathname: string): EventController {
     subscribeToAction: () => () => {},
     subscribeToHandles: () => () => {},
     setHandleData: () => {},
-    getHandleState: () => ({ data: {}, segmentOrder: [] }),
+    getHandleState: () => handleState,
+    setParams: (nextParams) => {
+      params = nextParams;
+    },
+    getParams: () => params,
     setLocation: () => {},
     startNavigation: () => {
       throw new Error("Navigation not supported during SSR");
@@ -164,6 +209,7 @@ function createSsrEventController(pathname: string): EventController {
     abortAllActions: () => {},
     getCurrentNavigation: () => null,
     getInflightActions: () => new Map(),
+    hadAnyConcurrentActions: () => false,
   };
 }
 
@@ -203,9 +249,9 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
    */
   return async function renderHTML(
     rscStream: ReadableStream<Uint8Array>,
-    options?: SSRRenderOptions
+    options?: SSRRenderOptions,
   ): Promise<ReadableStream<Uint8Array>> {
-    const { nonce, formState } = options ?? {};
+    const { nonce, formState, streamMode } = options ?? {};
 
     try {
       // Tee the stream:
@@ -221,46 +267,69 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
         payload ??= createFromReadableStream<RscPayload>(rscStream1);
         const resolved = React.use(payload);
 
-        // Initialize segments state before children render (for useSegments hook)
-        initSegmentsSync(resolved.metadata?.matched, resolved.metadata?.pathname);
-
-        // Initialize theme config for MetaTags to render theme script
         const themeConfig = resolved.metadata?.themeConfig ?? null;
-        initThemeConfigSync(themeConfig);
+        const pathname = resolved.metadata?.pathname ?? "/";
 
-        // Await handles and initialize state before children render
+        // Await handles before creating SSR event controller so hooks can
+        // read request-local handle data via NavigationStoreContext.
         // The handles property is an async generator that yields on each push
         // Memoize the promise since async generators can only be iterated once
+        let handleData: HandleData = {};
         if (resolved.metadata?.handles) {
           handlesPromise ??= consumeAsyncGenerator(resolved.metadata.handles);
-          const handleData = React.use(handlesPromise);
-          initHandleDataSync(handleData, resolved.metadata.matched);
+          handleData = React.use(handlesPromise);
         }
 
-        // Create SSR context with correct pathname for useNavigation
+        // Create SSR context with request-local pathname/params/handles.
         ssrContextValue ??= {
           store: null as any,
-          eventController: createSsrEventController(resolved.metadata?.pathname ?? "/"),
+          eventController: createSsrEventController({
+            pathname,
+            params: resolved.metadata?.params,
+            handleData,
+            matched: resolved.metadata?.matched,
+          }),
           navigate: async () => {},
           refresh: async () => {},
+          version: resolved.metadata?.version,
+          basename: resolved.metadata?.basename,
         };
 
-        // Build content tree with all necessary providers
+        // Build content tree from segments.
         // Order must match NavigationProvider: NavigationStoreContext > ThemeProvider > content
-        let content: React.ReactNode = resolved.root;
+        const reconstructedRoot = renderSegments(
+          resolved.metadata?.segments ?? [],
+          {
+            rootLayout: resolved.metadata?.rootLayout,
+          },
+        );
+        let content: React.ReactNode =
+          reconstructedRoot instanceof Promise
+            ? React.use(reconstructedRoot)
+            : reconstructedRoot;
 
         // Wrap content with ThemeProvider if theme is enabled
         if (themeConfig) {
           content = (
-            <ThemeProvider config={themeConfig} initialTheme={resolved.metadata?.initialTheme}>
+            <ThemeProvider
+              config={themeConfig}
+              initialTheme={resolved.metadata?.initialTheme}
+            >
               {content}
             </ThemeProvider>
           );
         }
 
+        // Wrap with NonceContext so client components (e.g. MetaTags) can
+        // apply CSP nonces to inline scripts during SSR. Always present to
+        // match the browser-side NavigationProvider tree shape for hydration.
+        content = (
+          <NonceContext.Provider value={nonce}>{content}</NonceContext.Provider>
+        );
+
         // Wrap with NavigationStoreContext for useNavigation hook
         return (
-          <NavigationStoreContext.Provider value={ssrContextValue}>
+          <NavigationStoreContext.Provider value={ssrContextValue!}>
             {content}
           </NavigationStoreContext.Provider>
         );
@@ -278,12 +347,20 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
         nonce,
       });
 
+      // Wait for all Suspense boundaries to resolve when streamMode is "allReady".
+      // This buffers the entire HTML before flushing — used for bots that
+      // cannot process streamed HTML.
+      if (streamMode === "allReady") {
+        await htmlStream.allReady;
+      }
+
       // Inject RSC payload into HTML as <script nonce="...">__FLIGHT_DATA__</script>
       return htmlStream.pipeThrough(injectRSCPayload(rscStream2, { nonce }));
     } catch (error) {
       // Invoke onError callback if provided
       if (onError) {
-        const errorObj = error instanceof Error ? error : new Error(String(error));
+        const errorObj =
+          error instanceof Error ? error : new Error(String(error));
         try {
           onError(errorObj, { phase: "rendering" });
         } catch (callbackError) {

package/src/static-handler.ts

@@ -31,26 +31,41 @@
  * ```
  */
 import type { ReactNode } from "react";
-import type { Handler, HandlerContext } from "./types.js";
-import type { PrerenderOptions } from "./prerender.js";
+import type { Handler } from "./types.js";
+import type { StaticBuildContext } from "./prerender.js";
+import type { UseItems, HandlerUseItem } from "./route-types.js";
+import { isCachedFunction } from "./cache/taint.js";
 
 // -- Types ------------------------------------------------------------------
 
-export interface StaticHandlerDefinition<TParams extends Record<string, any> = any> {
+export interface StaticHandlerOptions {
+  /**
+   * Keep handler in server bundle for live fallback (default: false).
+   * false: handler replaced with stub, source-only APIs excluded from bundle.
+   * true: handler stays in bundle, renders live at request time.
+   */
+  passthrough?: boolean;
+}
+
+export interface StaticHandlerDefinition<
+  TParams extends Record<string, any> = any,
+> {
   readonly __brand: "staticHandler";
   /** Auto-generated unique ID (injected by Vite plugin). */
   $$id: string;
   /** In dev mode, the actual handler function that layout/path/parallel can call. */
   handler: Handler<TParams>;
   /** Static handler options (passthrough support). */
-  options?: PrerenderOptions;
+  options?: StaticHandlerOptions;
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<HandlerUseItem>;
 }
 
 // -- Function ---------------------------------------------------------------
 
 export function Static<TParams extends Record<string, any> = {}>(
-  handler: (ctx: HandlerContext<TParams>) => ReactNode | Promise<ReactNode>,
-  options?: PrerenderOptions,
+  handler: (ctx: StaticBuildContext) => ReactNode | Promise<ReactNode>,
+  options?: StaticHandlerOptions,
   __injectedId?: string,
 ): StaticHandlerDefinition<TParams>;
 
@@ -58,19 +73,34 @@ export function Static<TParams extends Record<string, any> = {}>(
 
 export function Static<TParams extends Record<string, any>>(
   handler: Function,
-  optionsOrId?: PrerenderOptions | string,
+  optionsOrId?: StaticHandlerOptions | string,
   maybeId?: string,
 ): StaticHandlerDefinition<TParams> {
-  let options: PrerenderOptions | undefined;
+  if (isCachedFunction(handler)) {
+    throw new Error(
+      'A "use cache" function cannot be used as a Static() handler. ' +
+        "Static handlers are rendered once at build time. Remove the " +
+        '"use cache" directive — Static already provides caching.',
+    );
+  }
+
+  let options: StaticHandlerOptions | undefined;
   let id: string;
 
   if (typeof optionsOrId === "string") {
     id = optionsOrId;
   } else {
-    options = optionsOrId as PrerenderOptions | undefined;
+    options = optionsOrId as StaticHandlerOptions | undefined;
     id = maybeId ?? "";
   }
 
+  if (!id) {
+    throw new Error(
+      "[rango] Static: missing $$id. " +
+        "Ensure the exposeInternalIds Vite plugin is configured.",
+    );
+  }
+
   return {
     __brand: "staticHandler" as const,
     $$id: id,

package/src/theme/ThemeProvider.tsx

@@ -11,7 +11,13 @@
  * - Handles SSR hydration by deferring system theme detection
  */
 
-import React, { useCallback, useEffect, useMemo, useState, useRef } from "react";
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+  useRef,
+} from "react";
 import { ThemeContext } from "./theme-context.js";
 import type {
   ResolvedTheme,
@@ -44,7 +50,12 @@ function readThemeFromCookie(storageKey: string): string | null {
   for (const cookie of cookies) {
     const [name, ...rest] = cookie.trim().split("=");
     if (name === storageKey) {
-      return decodeURIComponent(rest.join("="));
+      const raw = rest.join("=");
+      try {
+        return decodeURIComponent(raw);
+      } catch {
+        return raw;
+      }
     }
   }
   return null;
@@ -90,15 +101,13 @@ function writeThemeToStorage(storageKey: string, theme: Theme): void {
 /**
  * Apply theme to HTML element
  */
-function applyThemeToDocument(
-  theme: Theme,
-  config: ResolvedThemeConfig
-): void {
+function applyThemeToDocument(theme: Theme, config: ResolvedThemeConfig): void {
   if (typeof document === "undefined") return;
 
-  const resolved = theme === "system" && config.enableSystem
-    ? getSystemTheme()
-    : (theme as ResolvedTheme);
+  const resolved =
+    theme === "system" && config.enableSystem
+      ? getSystemTheme()
+      : (theme as ResolvedTheme);
 
   const value = config.value[resolved] || resolved;
   const el = document.documentElement;
@@ -188,7 +197,7 @@ export function ThemeProvider({
       writeThemeToStorage(config.storageKey, newTheme);
       applyThemeToDocument(newTheme, config);
     },
-    [config]
+    [config],
   );
 
   // Listen for system preference changes
@@ -227,10 +236,7 @@ export function ThemeProvider({
       if (!newTheme) return;
 
       // Validate and apply
-      if (
-        newTheme === "system" ||
-        config.themes.includes(newTheme)
-      ) {
+      if (newTheme === "system" || config.themes.includes(newTheme)) {
         setThemeState(newTheme as Theme);
         applyThemeToDocument(newTheme as Theme, config);
       }
@@ -280,7 +286,7 @@ export function ThemeProvider({
       themes,
       config,
     }),
-    [theme, setTheme, resolvedTheme, systemTheme, themes, config, mounted]
+    [theme, setTheme, resolvedTheme, systemTheme, themes, config, mounted],
   );
 
   return (

package/src/theme/ThemeScript.tsx

@@ -49,13 +49,13 @@ export interface ThemeScriptProps {
  * This renders a synchronous inline script that applies the theme
  * to the HTML element before React hydration, preventing FOUC.
  */
-export function ThemeScript({ config, nonce }: ThemeScriptProps): React.ReactNode {
+export function ThemeScript({
+  config,
+  nonce,
+}: ThemeScriptProps): React.ReactNode {
   const scriptContent = generateThemeScript(config);
 
   return (
-    <script
-      nonce={nonce}
-      dangerouslySetInnerHTML={{ __html: scriptContent }}
-    />
+    <script nonce={nonce} dangerouslySetInnerHTML={{ __html: scriptContent }} />
   );
 }