@rangojs/router 0.26.1 → 0.26.3

package/src/testing/render-route.tsx

@@ -384,7 +384,12 @@ export interface RenderRouteOptions {
    * - Content that suspends in the server pass (`lazy`, a pending or untracked
    *   `use()` promise) is emitted as its fallback and client-rendered, not
    *   hydrated; React reports the boundary in `recoverableErrors`. Outside any
-   *   `<Suspense>` it rejects.
+   *   `<Suspense>` it rejects: production's server waits for it, this
+   *   synchronous pass cannot.
+   * - An error the server pass throws outside any `<Suspense>` fails the
+   *   shell. Production answers a recovery document and the browser renders
+   *   the tree with `createRoot` instead of hydrating it; so does this mode,
+   *   and the result's `shellError` holds the error.
    * - Needs @testing-library/react >= 16.2.0; throws on older versions.
    */
   hydrate?: boolean;
@@ -479,6 +484,14 @@ export type RenderRouteHydrateResult = RenderRouteResult & {
    * with `console.error` in development.
    */
   recoverableErrors: string[];
+  /**
+   * The error the server pass threw outside any `<Suspense>` (a shell error),
+   * or undefined. When set, the tree was rendered with `createRoot`, as the
+   * browser renders production's recovery document, so the router's error
+   * boundaries ran on the client: assert what they show. `serverHtml` is then
+   * empty.
+   */
+  shellError: unknown;
 };
 
 interface ResolvedMatch {
@@ -1015,6 +1028,8 @@ export async function renderRoute(
   );
 
   let serverHtml: string | undefined;
+  let shellError: unknown;
+  let shellFailed = false;
   const recoverableErrors: string[] = [];
   if (options.hydrate) {
     // RTL forwards onRecoverableError to hydrateRoot from 16.2.0. 16.0-16.1
@@ -1035,7 +1050,14 @@ export async function renderRoute(
     ) : (
       ui
     );
-    serverHtml = withoutBrowserGlobals(() => renderToString(serverUi));
+    try {
+      serverHtml = withoutBrowserGlobals(() => renderToString(serverUi));
+    } catch (error) {
+      if (isSynchronousSuspension(error)) throw error;
+      shellFailed = true;
+      shellError = error;
+      serverHtml = "";
+    }
   }
 
   // Wrap render in an awaited async act so a tree that suspends (async loaders,
@@ -1051,14 +1073,15 @@ export async function renderRoute(
     result = render(ui, {
       baseElement: document.body,
       container,
-      ...(serverHtml !== undefined && {
-        hydrate: true,
-        onRecoverableError: (error: unknown) => {
-          recoverableErrors.push(
-            error instanceof Error ? error.message : String(error),
-          );
-        },
-      }),
+      ...(serverHtml !== undefined &&
+        !shellFailed && {
+          hydrate: true,
+          onRecoverableError: (error: unknown) => {
+            recoverableErrors.push(
+              error instanceof Error ? error.message : String(error),
+            );
+          },
+        }),
     });
   });
 
@@ -1081,7 +1104,25 @@ export async function renderRoute(
   };
 
   if (serverHtml === undefined) return Object.assign(result, { router });
-  return Object.assign(result, { router, serverHtml, recoverableErrors });
+  return Object.assign(result, {
+    router,
+    serverHtml,
+    recoverableErrors,
+    shellError,
+  });
+}
+
+/**
+ * renderToString's error for a root that suspended: Fizz waits for that
+ * promise in production, so it is no shell error.
+ */
+function isSynchronousSuspension(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    error.message.startsWith(
+      "A component suspended while responding to synchronous input",
+    )
+  );
 }
 
 /**

package/src/theme/ThemeProvider.tsx

@@ -14,6 +14,7 @@
 import React, {
   useCallback,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useState,
   useRef,
@@ -65,6 +66,19 @@ function readThemeFromStorage(storageKey: string): string | null {
   }
 }
 
+/**
+ * The visitor's explicit stored theme: the first VALID of the cookie and
+ * localStorage. An empty/garbage cookie value (e.g. a deleted cookie leaving
+ * "theme=") must not shadow a valid localStorage value behind a bare
+ * null-coalesce.
+ */
+function readStoredTheme(config: ResolvedThemeConfig): Theme | null {
+  return ([
+    readThemeFromCookie(config.storageKey),
+    readThemeFromStorage(config.storageKey),
+  ].find((v) => v !== null && isValidTheme(v, config)) ?? null) as Theme | null;
+}
+
 function writeThemeToCookie(storageKey: string, theme: Theme): void {
   if (typeof document === "undefined") return;
 
@@ -97,15 +111,16 @@ function applyThemeToDocument(theme: Theme, config: ResolvedThemeConfig): void {
   if (config.attribute === "class") {
     for (const t of config.themes) {
       const v = config.value[t] || t;
-      el.classList.remove(v);
+      if (v !== value && el.classList.contains(v)) el.classList.remove(v);
     }
-    el.classList.add(value);
+    // Applying the active theme again mutates nothing (a hydrated page).
+    if (!el.classList.contains(value)) el.classList.add(value);
   } else {
     el.setAttribute(config.attribute, value);
   }
 
   if (config.enableColorScheme) {
-    el.style.colorScheme = resolved;
+    if (el.style.colorScheme !== resolved) el.style.colorScheme = resolved;
   }
 }
 
@@ -129,6 +144,16 @@ export function ThemeProvider({
 
   const [systemTheme, setSystemTheme] = useState<ResolvedTheme>("light");
 
+  // A document rendered with createRoot instead of hydrated (the recovery
+  // document a server-render shell error answers, ssr/shell-error-document.tsx)
+  // mounts <html> fresh: React drops every attribute the head's theme script
+  // set. Apply the theme again before the first paint. On a hydrated document
+  // this writes what the script already applied.
+  useLayoutEffect(() => {
+    applyThemeToDocument(readStoredTheme(config) ?? theme, config);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   useEffect(() => {
     setSystemTheme(getSystemTheme());
     // Re-sync state from an EXPLICITLY stored theme after mount. initialTheme
@@ -143,17 +168,10 @@ export function ThemeProvider({
     // Only an explicit cookie/localStorage value re-syncs — a defaultTheme
     // fallback must not override a server-provided initialTheme when the
     // visitor never chose a theme.
-    // First VALID candidate wins — an empty/garbage cookie value (e.g. a
-    // deleted cookie leaving "theme=") must not shadow a valid localStorage
-    // value behind a bare null-coalesce.
-    const explicit =
-      [
-        readThemeFromCookie(config.storageKey),
-        readThemeFromStorage(config.storageKey),
-      ].find((v) => v !== null && isValidTheme(v, config)) ?? null;
+    const explicit = readStoredTheme(config);
     if (explicit !== null && explicit !== theme) {
-      setThemeState(explicit as Theme);
-      applyThemeToDocument(explicit as Theme, config);
+      setThemeState(explicit);
+      applyThemeToDocument(explicit, config);
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);

package/src/types/boundaries.ts

@@ -90,9 +90,15 @@ export type LoaderDataResult<T = unknown> =
        * resolved `redirect(url, { state })` record (`__rsc_ls_*` keys) — it
        * travels on the marker because a streaming loader settles after
        * payload metadata flushed; the redirect navigation merges it at the
-       * target entry.
+       * target entry. `status` is the redirect's own: a document whose shell
+       * the read fails answers it as a real redirect when there is no state
+       * (ssr/shell-error-document.tsx).
        */
-      redirect?: { to: string; state?: Record<string, unknown> };
+      redirect?: {
+        to: string;
+        status?: number;
+        state?: Record<string, unknown>;
+      };
     };
 
 export function isLoaderDataResult(value: unknown): value is LoaderDataResult {

package/src/vite/plugins/virtual-entries.ts

@@ -11,7 +11,7 @@ import {
   createTemporaryReferenceSet,
 } from "@rangojs/router/internal/deps/browser";
 import { createElement, StrictMode } from "react";
-import { hydrateRoot } from "react-dom/client";
+import { createRoot, hydrateRoot } from "react-dom/client";
 import { rscStream } from "@rangojs/router/internal/deps/html-stream-client";
 import { initBrowserApp, Rango } from "@rangojs/router/browser";
 
@@ -47,11 +47,15 @@ async function initializeApp() {
   }
 
   const app = createElement(Rango);
-  hydrateRoot(
-    document,
-    strictMode === false ? app : createElement(StrictMode, null, app),
-    formState ? { formState } : undefined
-  );
+  const root = strictMode === false ? app : createElement(StrictMode, null, app);
+  // The server render failed its shell and answered a recovery document
+  // (ssr/shell-error-document.tsx): nothing to hydrate, so render it, and the
+  // router's error boundaries run as on a client navigation.
+  if (document.documentElement.hasAttribute("data-rango-ssr-error")) {
+    createRoot(document).render(root);
+  } else {
+    hydrateRoot(document, root, formState ? { formState } : undefined);
+  }
 }
 
 initializeApp().catch(console.error);