@rangojs/router 0.0.0-experimental.0b82333f

package/src/server/root-layout.tsx

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+import { Outlet } from "../client.js";
+
+const MapRootLayout = (
+  <>
+    <Outlet />
+  </>
+) as ReactNode;
+
+export default MapRootLayout;

package/src/server/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "lib": ["ES2020"],
+    "types": ["node", "vite/client"],
+    "typeRoots": ["../../node_modules/@types"],
+    "moduleResolution": "bundler",
+    "rootDir": ".",
+    "outDir": "../../dist/server",
+    "composite": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["./**/*"]
+}

package/src/server.ts

@@ -0,0 +1,51 @@
+/**
+ * @rangojs/router/server — Internal subpath
+ *
+ * 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.
+ */
+
+// 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,
+  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 {
+  registerLoaderById,
+  setLoaderImports,
+} from "./server/loader-registry.js";
+
+// Request context creation (used by RSC handler, not user-facing)
+export {
+  createRequestContext,
+  type CreateRequestContextOptions,
+} from "./server/request-context.js";
+
+// Component utilities (used internally for server/client boundary checks)
+export { isClientComponent, assertClientComponent } from "./component-utils.js";

package/src/ssr/index.tsx

@@ -0,0 +1,365 @@
+import React from "react";
+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
+ */
+export interface InjectRSCPayloadOptions {
+  /**
+   * Nonce for Content Security Policy (CSP)
+   */
+  nonce?: string;
+}
+
+/**
+ * Options for renderToReadableStream from react-dom/server
+ */
+interface RenderToReadableStreamOptions {
+  bootstrapScriptContent?: string;
+  nonce?: string;
+  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
+ */
+export interface SSRRenderOptions {
+  /**
+   * Form state for useActionState progressive enhancement.
+   * This is the result of decodeFormState() and should be passed to
+   * react-dom's renderToReadableStream to enable useActionState to
+   * receive the action result during SSR.
+   */
+  formState?: unknown;
+
+  /**
+   * 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;
+}
+
+/**
+ * SSR dependencies from external packages
+ */
+export interface SSRDependencies<TEnv = unknown> {
+  /**
+   * createFromReadableStream from @vitejs/plugin-rsc/ssr
+   */
+  createFromReadableStream: <T>(
+    stream: ReadableStream<Uint8Array>,
+  ) => Promise<T>;
+
+  /**
+   * renderToReadableStream from react-dom/server.edge
+   */
+  renderToReadableStream: (
+    element: React.ReactNode,
+    options?: RenderToReadableStreamOptions,
+  ) => Promise<ReactDOMReadableStream>;
+
+  /**
+   * injectRSCPayload from rsc-html-stream/server
+   */
+  injectRSCPayload: (
+    rscStream: ReadableStream<Uint8Array>,
+    options?: InjectRSCPayloadOptions,
+  ) => TransformStream<Uint8Array, Uint8Array>;
+
+  /**
+   * Function to load bootstrap script content
+   * Typically: () => import.meta.viteRsc.loadBootstrapScriptContent("index")
+   */
+  loadBootstrapScriptContent: () => Promise<string>;
+
+  /**
+   * Optional callback invoked when an error occurs during SSR rendering.
+   *
+   * This callback is for notification/logging purposes.
+   *
+   * @example
+   * ```typescript
+   * export const renderHTML = createSSRHandler({
+   *   // ... other deps
+   *   onError: (error, context) => {
+   *     console.error('[SSR] Rendering error:', error);
+   *     Sentry.captureException(error);
+   *   },
+   * });
+   * ```
+   */
+  onError?: (error: Error, context: { phase: ErrorPhase }) => void;
+}
+
+/**
+ * RSC payload type (minimal interface for SSR)
+ */
+interface RscPayload {
+  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;
+  };
+}
+
+/**
+ * Consume an async generator and return a Promise that resolves with the final value.
+ * Used for SSR where we need to await all handle data before rendering.
+ */
+async function consumeAsyncGenerator(
+  generator: AsyncGenerator<HandleData, void, unknown>,
+): Promise<HandleData> {
+  let lastData: HandleData = {};
+  for await (const data of generator) {
+    lastData = data;
+  }
+  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.
+ *
+ * @example
+ * ```tsx
+ * import { createSSRHandler } from "rsc-router/ssr";
+ * import { createFromReadableStream } from "@vitejs/plugin-rsc/ssr";
+ * import { renderToReadableStream } from "react-dom/server.edge";
+ * import { injectRSCPayload } from "rsc-html-stream/server";
+ *
+ * export const renderHTML = createSSRHandler({
+ *   createFromReadableStream,
+ *   renderToReadableStream,
+ *   injectRSCPayload,
+ *   loadBootstrapScriptContent: () =>
+ *     import.meta.viteRsc.loadBootstrapScriptContent("index"),
+ * });
+ * ```
+ */
+export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
+  const {
+    createFromReadableStream,
+    renderToReadableStream,
+    injectRSCPayload,
+    loadBootstrapScriptContent,
+    onError,
+  } = deps;
+
+  /**
+   * Render RSC stream to HTML stream
+   *
+   * @param rscStream - The RSC stream to render
+   * @param options - Optional render options including formState for useActionState and nonce for CSP
+   */
+  return async function renderHTML(
+    rscStream: ReadableStream<Uint8Array>,
+    options?: SSRRenderOptions,
+  ): Promise<ReadableStream<Uint8Array>> {
+    const { nonce, formState, streamMode } = options ?? {};
+
+    try {
+      // Tee the stream:
+      // - rscStream1: For SSR rendering (deserialize to React VDOM)
+      // - rscStream2: For browser hydration (inject as __FLIGHT_DATA__)
+      const [rscStream1, rscStream2] = rscStream.tee();
+
+      // 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);
+        const themeConfig = resolved.metadata?.themeConfig ?? null;
+        const pathname = resolved.metadata?.pathname ?? "/";
+
+        // 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);
+          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
+        if (themeConfig) {
+          content = (
+            <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!}>
+            {content}
+          </NavigationStoreContext.Provider>
+        );
+      }
+
+      // Get bootstrap script content
+      const bootstrapScriptContent = await loadBootstrapScriptContent();
+
+      // Render React tree to HTML stream
+      // Pass formState for useActionState progressive enhancement if provided
+      // Pass nonce for CSP if provided
+      const htmlStream = await renderToReadableStream(<SsrRoot />, {
+        bootstrapScriptContent,
+        formState,
+        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));
+        try {
+          onError(errorObj, { phase: "rendering" });
+        } catch (callbackError) {
+          console.error("[SSRHandler.onError] Callback error:", callbackError);
+        }
+      }
+      throw error;
+    }
+  };
+}

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"
+  );
+}