@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.25dbaac3

package/src/server.ts

@@ -11,6 +11,12 @@
 // Router registry (used by Vite plugin for build-time discovery)
 export { RSC_ROUTER_BRAND, RouterRegistry } from "./router.js";
 
+// Host router registry (used by Vite plugin for host-router lazy discovery)
+export {
+  HostRouterRegistry,
+  type HostRouterRegistryEntry,
+} from "./host/router.js";
+
 // Route map builder (Vite plugin injects these via virtual modules)
 export {
   registerRouteMap,

package/src/ssr/index.tsx

@@ -1,9 +1,8 @@
 import React from "react";
 import { renderSegments } from "../segment-system.js";
-import { initHandleDataSync } from "../browser/react/use-handle.js";
-import { initSegmentsSync } from "../browser/react/use-segments.js";
-import { initThemeConfigSync } from "../theme/theme-context.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";
@@ -34,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
  */
@@ -50,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;
 }
 
 /**
@@ -69,7 +83,7 @@ export interface SSRDependencies<TEnv = unknown> {
   renderToReadableStream: (
     element: React.ReactNode,
     options?: RenderToReadableStreamOptions,
-  ) => Promise<ReadableStream<Uint8Array>>;
+  ) => Promise<ReactDOMReadableStream>;
 
   /**
    * injectRSCPayload from rsc-html-stream/server
@@ -115,8 +129,10 @@ interface RscPayload {
     matched?: string[];
     pathname?: string;
     params?: Record<string, string>;
+    basename?: string;
     themeConfig?: ResolvedThemeConfig | null;
     initialTheme?: Theme;
+    version?: string;
   };
 }
 
@@ -138,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: [],
@@ -150,6 +181,7 @@ function createSsrEventController(pathname: string): EventController {
 
   return {
     getState: () => state,
+    getLocation: () => location,
     subscribe: () => () => {},
     getActionState: () => ({
       state: "idle",
@@ -161,9 +193,11 @@ function createSsrEventController(pathname: string): EventController {
     subscribeToAction: () => () => {},
     subscribeToHandles: () => () => {},
     setHandleData: () => {},
-    getHandleState: () => ({ data: {}, segmentOrder: [] }),
-    setParams: () => {},
-    getParams: () => ({}),
+    getHandleState: () => handleState,
+    setParams: (nextParams) => {
+      params = nextParams;
+    },
+    getParams: () => params,
     setLocation: () => {},
     startNavigation: () => {
       throw new Error("Navigation not supported during SSR");
@@ -175,6 +209,7 @@ function createSsrEventController(pathname: string): EventController {
     abortAllActions: () => {},
     getCurrentNavigation: () => null,
     getInflightActions: () => new Map(),
+    hadAnyConcurrentActions: () => false,
   };
 }
 
@@ -216,7 +251,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
     rscStream: ReadableStream<Uint8Array>,
     options?: SSRRenderOptions,
   ): Promise<ReadableStream<Uint8Array>> {
-    const { nonce, formState } = options ?? {};
+    const { nonce, formState, streamMode } = options ?? {};
 
     try {
       // Tee the stream:
@@ -232,34 +267,32 @@ 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,
-          resolved.metadata?.params,
-        );
-
-        // 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 from segments.
@@ -287,9 +320,16 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
           );
         }
 
+        // 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>
         );
@@ -307,6 +347,13 @@ 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) {

package/src/static-handler.ts

@@ -32,11 +32,21 @@
  */
 import type { ReactNode } from "react";
 import type { Handler } from "./types.js";
-import type { PrerenderOptions, StaticBuildContext } from "./prerender.js";
+import type { StaticBuildContext } from "./prerender.js";
+import type { UseItems, HandlerUseItem } from "./route-types.js";
 import { isCachedFunction } from "./cache/taint.js";
 
 // -- Types ------------------------------------------------------------------
 
+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,
 > {
@@ -46,14 +56,16 @@ export interface StaticHandlerDefinition<
   /** 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: StaticBuildContext) => ReactNode | Promise<ReactNode>,
-  options?: PrerenderOptions,
+  options?: StaticHandlerOptions,
   __injectedId?: string,
 ): StaticHandlerDefinition<TParams>;
 
@@ -61,7 +73,7 @@ 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> {
   if (isCachedFunction(handler)) {
@@ -72,16 +84,23 @@ export function Static<TParams extends Record<string, any>>(
     );
   }
 
-  let options: PrerenderOptions | undefined;
+  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(
+      "[rsc-router] Static: missing $$id. " +
+        "Ensure the exposeInternalIds Vite plugin is configured.",
+    );
+  }
+
   return {
     __brand: "staticHandler" as const,
     $$id: id,

package/src/theme/ThemeProvider.tsx

@@ -50,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;

package/src/theme/index.ts

@@ -1,9 +1,10 @@
 /**
  * Theme module exports for @rangojs/router/theme
  *
- * This module provides theme management for rsc-router:
+ * This module provides the public theme API:
  * - useTheme: Hook for accessing theme state in client components
  * - ThemeProvider: Component for manual theme provider setup (typically not needed)
+ * - ThemeScript: FOUC-prevention script component for document/head usage
  * - Types for theme configuration
  *
  * @example
@@ -43,20 +44,5 @@ export type {
   ThemeContextValue,
 } from "./types.js";
 
-// Constants (for advanced use cases)
-export {
-  THEME_DEFAULTS,
-  THEME_COOKIE,
-  resolveThemeConfig,
-} from "./constants.js";
-
-// Script generation (for advanced SSR use cases)
-export { generateThemeScript, getNonceAttribute } from "./theme-script.js";
-
-// Context (for advanced use cases)
-export {
-  ThemeContext,
-  useThemeContext,
-  initThemeConfigSync,
-  getSSRThemeConfig,
-} from "./theme-context.js";
+// Constants
+export { THEME_DEFAULTS, THEME_COOKIE } from "./constants.js";

package/src/theme/theme-context.ts

@@ -10,7 +10,7 @@
  */
 
 import { createContext, useContext, type Context } from "react";
-import type { ResolvedThemeConfig, ThemeContextValue } from "./types.js";
+import type { ThemeContextValue } from "./types.js";
 
 /**
  * React context for theme state
@@ -19,33 +19,6 @@ import type { ResolvedThemeConfig, ThemeContextValue } from "./types.js";
 export const ThemeContext: Context<ThemeContextValue | null> =
   createContext<ThemeContextValue | null>(null);
 
-/**
- * SSR module-level state for theme config.
- * Populated by initThemeConfigSync before React renders.
- * Used by MetaTags during SSR to render the theme script.
- */
-let ssrThemeConfig: ResolvedThemeConfig | null = null;
-
-/**
- * Initialize theme config synchronously for SSR.
- * Called before rendering to populate state for MetaTags.
- *
- * @param config - Theme config from router, or null if theme is disabled
- */
-export function initThemeConfigSync(config: ResolvedThemeConfig | null): void {
-  ssrThemeConfig = config;
-}
-
-/**
- * Get theme config for SSR/hydration.
- * Used by MetaTags to render the theme script.
- *
- * @returns Theme config if available, null otherwise
- */
-export function getSSRThemeConfig(): ResolvedThemeConfig | null {
-  return ssrThemeConfig;
-}
-
 /**
  * Get theme context (internal use)
  * Returns null if theme is not enabled

package/src/theme/theme-script.ts

@@ -40,7 +40,8 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
     for (var i = 0; i < cookies.length; i++) {
       var cookie = cookies[i].trim();
       if (cookie.indexOf(storageKey + '=') === 0) {
-        return decodeURIComponent(cookie.substring(storageKey.length + 1));
+        try { return decodeURIComponent(cookie.substring(storageKey.length + 1)); }
+        catch (e) { return cookie.substring(storageKey.length + 1); }
       }
     }
     // Fall back to localStorage

package/src/types/cache-types.ts

@@ -5,8 +5,8 @@
  * during cache key generation (before middleware runs).
  *
  * Note: While the full RequestContext is passed, middleware-set variables
- * (ctx.var, ctx.get()) may not be populated yet since cache lookup
- * happens before middleware execution.
+ * read via `ctx.get()` may not be populated yet since cache lookup happens
+ * before middleware execution.
  */
 export type { RequestContext as CacheContext } from "../server/request-context.js";
 
@@ -101,7 +101,7 @@ export interface CacheOptions<TEnv = unknown> {
    * Return false to skip cache for this request (always fetch fresh).
    *
    * Has access to full RequestContext including env, request, params, cookies, etc.
-   * Note: Middleware-set variables (ctx.var) may not be populated yet.
+   * Note: Middleware-set variables read via `ctx.get()` may not be populated yet.
    *
    * @example
    * ```typescript
@@ -123,7 +123,7 @@ export interface CacheOptions<TEnv = unknown> {
    * Bypasses default key generation AND store's keyGenerator.
    *
    * Has access to full RequestContext including env, request, params, cookies, etc.
-   * Note: Middleware-set variables (ctx.var) may not be populated yet.
+   * Note: Middleware-set variables read via `ctx.get()` may not be populated yet.
    *
    * @example
    * ```typescript
@@ -134,7 +134,7 @@ export interface CacheOptions<TEnv = unknown> {
    * key: (ctx) => `${ctx.env.REGION}:product:${ctx.params.id}`
    *
    * // Include cookies
-   * key: (ctx) => `${ctx.cookie('locale')}:${ctx.pathname}`
+   * key: (ctx) => `${cookies().get('locale')?.value ?? 'en'}:${ctx.pathname}`
    * ```
    */
   key?: (
@@ -145,6 +145,11 @@ export interface CacheOptions<TEnv = unknown> {
    * Tags for cache invalidation.
    * Can be a static array or a function that returns tags.
    *
+   * Note: Tags are passed through to the store but built-in stores
+   * (MemorySegmentCacheStore, CFCacheStore) do not yet index or
+   * invalidate by tag. Effective tag-based invalidation requires a
+   * custom store implementation with secondary indices.
+   *
    * @example
    * ```typescript
    * // Static tags

package/src/types/error-types.ts

@@ -10,6 +10,7 @@
  * - "rendering": Invoked during SSR rendering errors (ssr/index.tsx, separate callback)
  * - "action": Invoked when server action execution fails (rsc/handler.ts, router.ts)
  * - "revalidation": Invoked when revalidation fails (router.ts, conditional with action)
+ * - "origin": Invoked when cross-origin request validation rejects a request (rsc/handler.ts)
  * - "unknown": Fallback for unclassified errors (not currently invoked)
  */
 export type ErrorPhase =
@@ -21,8 +22,10 @@ export type ErrorPhase =
   | "rendering" // During RSC/SSR rendering (SSR handler uses separate callback)
   | "action" // During server action execution
   | "revalidation" // During revalidation evaluation
+  | "cache" // During "use cache" background operations (stale revalidation, async cache writes)
   | "prerender" // During build-time pre-rendering (Vite closeBundle)
   | "static" // During build-time static handler rendering (Vite closeBundle)
+  | "origin" // During cross-origin request validation (CSRF protection)
   | "unknown"; // Fallback for unclassified errors
 
 /**

package/src/types/global-namespace.ts

@@ -52,6 +52,19 @@ export type GetRegisteredRoutes = keyof RSCRouter.RegisteredRoutes extends never
   ? Record<string, string>
   : RSCRouter.RegisteredRoutes;
 
+/**
+ * Default route map for reverse() surfaces.
+ * Prefers GeneratedRouteMap to avoid router.tsx -> urls.tsx -> types -> router.tsx
+ * cycles, but falls back to RegisteredRoutes for manual augmentation and then to
+ * a permissive record when no route types are available.
+ */
+export type DefaultReverseRouteMap =
+  keyof RSCRouter.GeneratedRouteMap extends never
+    ? keyof RSCRouter.RegisteredRoutes extends never
+      ? Record<string, string>
+      : RSCRouter.RegisteredRoutes
+    : RSCRouter.GeneratedRouteMap;
+
 /**
  * Default route map for Handler type.
  * Uses GeneratedRouteMap (from gen file) instead of RegisteredRoutes to avoid
@@ -76,3 +89,12 @@ export type DefaultEnv = keyof RSCRouter.Env extends never
 export type DefaultVars = keyof RSCRouter.Vars extends never
   ? Record<string, any>
   : RSCRouter.Vars;
+
+/**
+ * Default route name type for public `routeName` on contexts.
+ * When GeneratedRouteMap is augmented, narrows to the known route names.
+ * Otherwise falls back to `string` for untyped usage.
+ */
+export type DefaultRouteName = keyof RSCRouter.GeneratedRouteMap extends never
+  ? string
+  : keyof RSCRouter.GeneratedRouteMap & string;