@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

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,6 +129,7 @@ interface RscPayload {
     matched?: string[];
     pathname?: string;
     params?: Record<string, string>;
+    basename?: string;
     themeConfig?: ResolvedThemeConfig | null;
     initialTheme?: Theme;
     version?: string;
@@ -139,11 +154,22 @@ 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 handleState = {
+    data: opts.handleData ?? {},
+    segmentOrder: filterSegmentOrder(opts.matched ?? []),
+  };
   const state: DerivedNavigationState = {
     state: "idle",
     isStreaming: false,
+    isNavigating: false,
     location,
     pendingUrl: null,
     inflightActions: [],
@@ -163,9 +189,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");
@@ -177,6 +205,7 @@ function createSsrEventController(pathname: string): EventController {
     abortAllActions: () => {},
     getCurrentNavigation: () => null,
     getInflightActions: () => new Map(),
+    hadAnyConcurrentActions: () => false,
   };
 }
 
@@ -218,7 +247,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:
@@ -234,35 +263,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.
@@ -290,6 +316,13 @@ 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!}>
@@ -310,6 +343,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

@@ -82,6 +82,13 @@ export function Static<TParams extends Record<string, any>>(
     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
@@ -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

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