@rangojs/router 0.0.0-experimental.3 → 0.0.0-experimental.30

package/src/server.ts

@@ -1,135 +1,51 @@
 /**
- * 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";
+// Router registry (used by Vite plugin for build-time discovery)
+export { RSC_ROUTER_BRAND, RouterRegistry } from "./router.js";
 
-// Django-style URL patterns (server-only)
+// Host router registry (used by Vite plugin for host-router lazy discovery)
 export {
-  urls,
-  type PathHelpers,
-  type PathOptions,
-  type UrlPatterns,
-  type IncludeOptions,
-} from "./urls.js";
+  HostRouterRegistry,
+  type HostRouterRegistryEntry,
+} from "./host/router.js";
 
-// Re-export IncludeItem from route-types
-export type { IncludeItem } from "./route-types.js";
-
-// Core router (server-only)
+// Route map builder (Vite plugin injects these via virtual modules)
 export {
-  createRouter,
-  type RSCRouter,
-  type RSCRouterOptions,
-  type RootLayoutProps,
-} from "./router.js";
-
-// Type-safe href utilities
+  registerRouteMap,
+  setCachedManifest,
+  clearCachedManifest,
+  clearAllRouterData,
+  getGlobalRouteMap,
+  getRouterManifest,
+  setPrecomputedEntries,
+  setRouteTrie,
+  setManifestReadyPromise,
+  setRouterManifest,
+  setRouterTrie,
+  setRouterPrecomputedEntries,
+  registerRouterManifestLoader,
+  ensureRouterManifest,
+} from "./route-map-builder.js";
+
+// Loader registry (Vite plugin registers lazy loader imports)
 export {
-  createHref,
-  type HrefFunction,
-  type PrefixedRoutes,
-  type PrefixRoutePatterns,
-  type ParamsFor,
-  type SanitizePrefix,
-  type MergeRoutes,
-} from "./href.js";
-
-// Segment system (server-only)
-export { renderSegments } from "./segment-system.js";
-
-// Performance tracking (server-only)
-export { track } from "./server/context.js";
-
-// Handle API (works in both server and client contexts)
-export { createHandle, isHandle, type Handle } from "./handle.js";
-
-// Built-in handles
-export { Meta } from "./handles/meta.js";
+  registerLoaderById,
+  setLoaderImports,
+} from "./server/loader-registry.js";
 
-// Loader registry (for GET-based loader fetching)
-export { registerLoaderById, setLoaderImports } from "./server/loader-registry.js";
-
-// Request context (for accessing request data in server components/actions)
+// 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,
-} from "./errors.js";
-
-// Component utilities
-export {
-  isClientComponent,
-  assertClientComponent,
-} from "./component-utils.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";
+// Component utilities (used internally for server/client boundary checks)
+export { isClientComponent, assertClientComponent } from "./component-utils.js";

package/src/ssr/index.tsx

@@ -1,11 +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";
 
 /**
  * Options for injectRSCPayload
@@ -26,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
  */
@@ -42,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;
 }
 
 /**
@@ -51,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>;
 
   /**
@@ -98,13 +122,16 @@ 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>;
     themeConfig?: ResolvedThemeConfig | null;
     initialTheme?: Theme;
+    version?: string;
   };
 }
 
@@ -113,7 +140,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) {
@@ -122,6 +149,64 @@ async function consumeAsyncGenerator(
   return lastData;
 }
 
+/**
+ * Create a minimal event controller for SSR.
+ * This provides the correct pathname so useNavigation returns the right value during SSR.
+ */
+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 handleState = {
+    data: opts.handleData ?? {},
+    segmentOrder: filterSegmentOrder(opts.matched ?? []),
+  };
+  const state: DerivedNavigationState = {
+    state: "idle",
+    isStreaming: false,
+    location,
+    pendingUrl: null,
+    inflightActions: [],
+  };
+
+  return {
+    getState: () => state,
+    getLocation: () => location,
+    subscribe: () => () => {},
+    getActionState: () => ({
+      state: "idle",
+      actionId: null,
+      payload: null,
+      error: null,
+      result: null,
+    }),
+    subscribeToAction: () => () => {},
+    subscribeToHandles: () => () => {},
+    setHandleData: () => {},
+    getHandleState: () => handleState,
+    setParams: (nextParams) => {
+      params = nextParams;
+    },
+    getParams: () => params,
+    setLocation: () => {},
+    startNavigation: () => {
+      throw new Error("Navigation not supported during SSR");
+    },
+    abortNavigation: () => {},
+    startAction: () => {
+      throw new Error("Actions not supported during SSR");
+    },
+    abortAllActions: () => {},
+    getCurrentNavigation: () => null,
+    getInflightActions: () => new Map(),
+    hadAnyConcurrentActions: () => false,
+  };
+}
+
 /**
  * Create an SSR handler that converts RSC streams to HTML.
  *
@@ -158,9 +243,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:
@@ -171,37 +256,75 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       // Deserialize RSC stream to React tree
       let payload: Promise<RscPayload> | undefined;
       let handlesPromise: Promise<HandleData> | undefined;
+      let ssrContextValue: NavigationStoreContextValue | undefined;
       function SsrRoot() {
         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 request-local pathname/params/handles.
+        ssrContextValue ??= {
+          store: null as any,
+          eventController: createSsrEventController({
+            pathname,
+            params: resolved.metadata?.params,
+            handleData,
+            matched: resolved.metadata?.matched,
+          }),
+          navigate: async () => {},
+          refresh: async () => {},
+          version: resolved.metadata?.version,
+        };
+
+        // Build content tree from segments.
+        // Order must match NavigationProvider: NavigationStoreContext > ThemeProvider > content
+        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
-        // This provides the theme context for client components that use useTheme
         if (themeConfig) {
-          return (
-            <ThemeProvider config={themeConfig} initialTheme={resolved.metadata?.initialTheme}>
-              {resolved.root}
+          content = (
+            <ThemeProvider
+              config={themeConfig}
+              initialTheme={resolved.metadata?.initialTheme}
+            >
+              {content}
             </ThemeProvider>
           );
         }
 
-        return resolved.root;
+        // 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!}>
+            {content}
+          </NavigationStoreContext.Provider>
+        );
       }
 
       // Get bootstrap script content
@@ -216,12 +339,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

@@ -0,0 +1,114 @@
+/**
+ * Static handler definition for build-time rendering of individual segments.
+ *
+ * Static wraps a handler so that in production the segment is
+ * rendered once at build time. The handler is then replaced with a static
+ * asset import -- no runtime store lookup needed.
+ *
+ * In dev mode, Static behaves as a normal handler: the wrapped
+ * function runs on every request, identical to a regular layout/path handler.
+ *
+ * The $$id is auto-generated by the Vite exposeInternalIds plugin based on
+ * file path and export name. No manual naming required.
+ *
+ * Key difference from Prerender:
+ *   - Prerender: route-scoped, produces URLs via getParams, renders subtree per-params
+ *   - Static: segment-scoped, renders once, no URLs, no params
+ *
+ * Works on: layout(), parallel(), and path().
+ *
+ * @example
+ * ```ts
+ * export const DocsNav = Static((ctx) => <Nav docs={readDocsSync()} />);
+ * export const DocShell = Static((ctx) => <Shell />);
+ *
+ * urls(({ path, layout }) => [
+ *   layout(DocsNav, () => [
+ *     path("/getting-started", DocShell, { name: "doc.gs" }),
+ *     path("/:slug", Prerender(getParams, DocPageHandler)),
+ *   ]),
+ * ]);
+ * ```
+ */
+import type { ReactNode } from "react";
+import type { Handler } from "./types.js";
+import type { PrerenderOptions, StaticBuildContext } from "./prerender.js";
+import { isCachedFunction } from "./cache/taint.js";
+
+// -- Types ------------------------------------------------------------------
+
+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;
+}
+
+// -- Function ---------------------------------------------------------------
+
+export function Static<TParams extends Record<string, any> = {}>(
+  handler: (ctx: StaticBuildContext) => ReactNode | Promise<ReactNode>,
+  options?: PrerenderOptions,
+  __injectedId?: string,
+): StaticHandlerDefinition<TParams>;
+
+// -- Implementation ---------------------------------------------------------
+
+export function Static<TParams extends Record<string, any>>(
+  handler: Function,
+  optionsOrId?: PrerenderOptions | string,
+  maybeId?: string,
+): StaticHandlerDefinition<TParams> {
+  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: PrerenderOptions | undefined;
+  let id: string;
+
+  if (typeof optionsOrId === "string") {
+    id = optionsOrId;
+  } else {
+    options = optionsOrId as PrerenderOptions | undefined;
+    id = maybeId ?? "";
+  }
+
+  if (!id) {
+    throw new Error(
+      "[rsc-router] Static: missing $$id. " +
+        "Ensure the exposeInternalIds Vite plugin is configured.",
+    );
+  }
+
+  return {
+    __brand: "staticHandler" as const,
+    $$id: id,
+    handler: handler as Handler<TParams>,
+    ...(options ? { options } : {}),
+  };
+}
+
+// -- Type guard -------------------------------------------------------------
+
+/**
+ * Type guard to check if a value is a StaticHandlerDefinition.
+ */
+export function isStaticHandler(
+  value: unknown,
+): value is StaticHandlerDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__brand" in value &&
+    (value as { __brand: unknown }).__brand === "staticHandler"
+  );
+}

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 }} />
   );
 }