@rangojs/router 0.0.0-experimental.88a3b2f7 → 0.0.0-experimental.8bd1b239

package/src/build/route-trie.ts

@@ -98,8 +98,14 @@ export function buildRouteTrie(
 }
 
 /**
- * Insert a route into the trie, handling optional params by forking
- * the insertion path (one terminal without the param, one with).
+ * Insert a route into the trie. Optional params expand into two branches at
+ * registration time (skip-first, then present), so each terminal lives at the
+ * correct depth for its number of bound params and carries a branch-local
+ * `pa` listing only those names. The trie's single-slot `node.p` is reused
+ * across branches because matching ignores `node.p.n` — the leaf's `pa` is
+ * the source of truth for naming. Skip-first ordering lets `mergeLeaf`'s
+ * last-wins rule produce greedy-leftmost semantics for free at any shared
+ * terminal depth.
  */
 function insertRoute(
   node: TrieNode,
@@ -107,14 +113,13 @@ function insertRoute(
   index: number,
   leaf: Omit<TrieLeaf, "op" | "cv" | "pa">,
 ): void {
-  // Collect param names, optional param names, and constraints across all segments
-  const paramNames: string[] = [];
+  // op (full optional list) and cv (full constraint map) are route-level and
+  // identical on every terminal, so compute them once on the shared base.
   const optionalParams: string[] = [];
   const constraints: Record<string, string[]> = {};
 
   for (const seg of segments) {
     if (seg.type === "param") {
-      paramNames.push(seg.value);
       if (seg.optional) {
         optionalParams.push(seg.value);
       }
@@ -124,21 +129,15 @@ function insertRoute(
     }
   }
 
-  const fullLeaf: TrieLeaf = {
+  const leafBase: Omit<TrieLeaf, "pa"> = {
     ...leaf,
-    ...(paramNames.length > 0 ? { pa: paramNames } : {}),
     ...(optionalParams.length > 0 ? { op: optionalParams } : {}),
     ...(Object.keys(constraints).length > 0 ? { cv: constraints } : {}),
   };
 
-  insertSegments(node, segments, index, fullLeaf);
+  insertSegments(node, segments, index, leafBase, []);
 }
 
-/**
- * Recursively insert segments into the trie.
- * For optional params, we add a terminal at the current node (param absent)
- * AND continue inserting into the param child (param present).
- */
 /**
  * Extract ancestry map from a built trie by visiting all leaf nodes.
  * Returns { routeName: ancestryShortCodes[] } for every route in the trie.
@@ -218,15 +217,25 @@ function mergeLeaf(node: TrieNode, leaf: TrieLeaf): void {
   node.r = mergeLeaves(node.r, leaf);
 }
 
+function buildLeaf(
+  leafBase: Omit<TrieLeaf, "pa">,
+  paramNames: string[],
+): TrieLeaf {
+  return paramNames.length > 0
+    ? { ...leafBase, pa: [...paramNames] }
+    : { ...leafBase };
+}
+
 function insertSegments(
   node: TrieNode,
   segments: ParsedSegment[],
   index: number,
-  leaf: TrieLeaf,
+  leafBase: Omit<TrieLeaf, "pa">,
+  paramNames: string[],
 ): void {
-  // Base case: all segments consumed, add terminal
+  // Base case: all segments consumed, add terminal with branch-local pa
   if (index >= segments.length) {
-    mergeLeaf(node, leaf);
+    mergeLeaf(node, buildLeaf(leafBase, paramNames));
     return;
   }
 
@@ -235,12 +244,19 @@ function insertSegments(
   if (segment.type === "static") {
     if (!node.s) node.s = {};
     if (!node.s[segment.value]) node.s[segment.value] = {};
-    insertSegments(node.s[segment.value], segments, index + 1, leaf);
+    insertSegments(
+      node.s[segment.value],
+      segments,
+      index + 1,
+      leafBase,
+      paramNames,
+    );
   } else if (segment.type === "param") {
     if (segment.optional) {
-      // Optional param: add terminal at current node (param absent)
-      mergeLeaf(node, leaf);
-      // AND continue with param child (param present)
+      // SKIP first: continue at the same node without binding this name.
+      // Skip-first ordering means the present-branch's TAKE overwrites any
+      // shared terminal later, giving greedy-leftmost semantics.
+      insertSegments(node, segments, index + 1, leafBase, paramNames);
     }
     if (segment.suffix) {
       // Suffix param: keyed by suffix string (e.g., ".html")
@@ -248,16 +264,26 @@ function insertSegments(
       if (!node.xp[segment.suffix]) {
         node.xp[segment.suffix] = { n: segment.value, c: {} };
       }
-      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leaf);
+      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leafBase, [
+        ...paramNames,
+        segment.value,
+      ]);
     } else {
       if (!node.p) {
         node.p = { n: segment.value, c: {} };
       }
-      insertSegments(node.p.c, segments, index + 1, leaf);
+      insertSegments(node.p.c, segments, index + 1, leafBase, [
+        ...paramNames,
+        segment.value,
+      ]);
     }
   } else if (segment.type === "wildcard") {
-    // Wildcard consumes all remaining segments
-    const wildLeaf = { ...leaf, pn: "*" };
+    // Wildcard consumes all remaining segments. Carry any params bound before
+    // the wildcard in pa so they zip correctly against paramValues at match.
+    const wildLeaf: TrieLeaf & { pn: string } = {
+      ...buildLeaf(leafBase, paramNames),
+      pn: "*",
+    };
     const existing = node.w ? ({ ...node.w } as TrieLeaf) : undefined;
     const merged = mergeLeaves(existing, wildLeaf);
     node.w = merged as TrieLeaf & { pn: string };

package/src/client.tsx

@@ -13,7 +13,6 @@ import {
   type ClientErrorBoundaryFallbackProps,
   type ErrorInfo,
   type LoaderDefinition,
-  type LoaderFn,
   type ResolvedSegment,
 } from "./types";
 import {
@@ -22,6 +21,83 @@ import {
 } from "./route-content-wrapper.js";
 import { OutletProvider } from "./outlet-provider.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
+import { getMemoizedContentPromise } from "./segment-content-promise.js";
+
+/**
+ * Render the content for a named parallel/intercept slot segment.
+ *
+ * Shared by Outlet (with `name` prop) and ParallelOutlet — both resolve a
+ * segment from context.parallel by slot name and then render it through the
+ * same layout/loader/mountPath wrapping pipeline.
+ */
+function renderSlotContent(segment: ResolvedSegment | null): ReactNode {
+  if (!segment) return null;
+
+  const content: ReactNode =
+    segment.loading || segment.component instanceof Promise ? (
+      <RouteContentWrapper
+        content={getMemoizedContentPromise(segment.component)}
+        fallback={segment.loading}
+        segmentId={segment.id}
+      />
+    ) : (
+      (segment.component ?? null)
+    );
+
+  const hasOwnLoaders = !!(segment.loaderDataPromise && segment.loaderIds);
+  const loaderWrapped = hasOwnLoaders ? (
+    <LoaderBoundary
+      loaderDataPromise={segment.loaderDataPromise!}
+      loaderIds={segment.loaderIds!}
+      fallback={segment.loading}
+      outletKey={segment.id + "-loader"}
+      outletContent={null}
+      segment={segment}
+    >
+      {content}
+    </LoaderBoundary>
+  ) : null;
+
+  let result: ReactNode;
+  if (segment.layout) {
+    // Layout renders immediately; if loaders exist, the LoaderBoundary becomes
+    // the outlet content so layout's <Outlet /> suspends until loaders resolve.
+    result = (
+      <OutletProvider
+        content={hasOwnLoaders ? loaderWrapped : content}
+        segment={segment}
+      >
+        {segment.layout}
+      </OutletProvider>
+    );
+  } else if (hasOwnLoaders) {
+    // No layout but has loaders — wrap content with LoaderBoundary for useLoader context.
+    // Common for intercept routes that use useLoader without a custom layout.
+    result = loaderWrapped;
+  } else {
+    result = content;
+  }
+
+  if (segment.mountPath) {
+    return (
+      <MountContextProvider value={segment.mountPath}>
+        {result}
+      </MountContextProvider>
+    );
+  }
+
+  return result;
+}
+
+function useSlotSegment(
+  context: OutletContextValue | null,
+  name: `@${string}` | undefined,
+): ResolvedSegment | null {
+  return useMemo(() => {
+    if (!name || !context?.parallel) return null;
+    return context.parallel.find((seg) => seg.slot === name) ?? null;
+  }, [context, name]);
+}
 
 /**
  * Outlet component - renders child content in layouts
@@ -62,95 +138,10 @@ import { MountContextProvider } from "./browser/react/mount-context.js";
  */
 export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
   const context = useContext(OutletContext);
+  const namedSegment = useSlotSegment(context, name);
 
-  // If name provided, render parallel/intercept content for that slot
   if (name) {
-    const segment = context?.parallel?.find((seg) => seg.slot === name) ?? null;
-
-    if (!segment) return null;
-
-    // Determine the content to render
-    let content: ReactNode;
-    if (segment.loading || segment.component instanceof Promise) {
-      // Use RouteContentWrapper to handle Suspense wrapping properly
-      content = (
-        <RouteContentWrapper
-          content={
-            segment.component instanceof Promise
-              ? segment.component
-              : Promise.resolve(segment.component)
-          }
-          fallback={segment.loading}
-          segmentId={segment.id}
-        />
-      );
-    } else {
-      content = segment.component ?? null;
-    }
-
-    let result: ReactNode;
-
-    // If segment has a layout, wrap appropriately
-    if (segment.layout) {
-      // Check if this segment has loaders that need streaming
-      // The layout renders immediately, LoaderBoundary becomes the outlet content
-      // When layout renders <Outlet />, it gets the LoaderBoundary which suspends
-      if (segment.loaderDataPromise && segment.loaderIds) {
-        const loaderAwareContent = (
-          <LoaderBoundary
-            loaderDataPromise={segment.loaderDataPromise}
-            loaderIds={segment.loaderIds}
-            fallback={segment.loading}
-            outletKey={segment.id + "-loader"}
-            outletContent={null}
-            segment={segment}
-          >
-            {content}
-          </LoaderBoundary>
-        );
-
-        result = (
-          <OutletProvider content={loaderAwareContent} segment={segment}>
-            {segment.layout}
-          </OutletProvider>
-        );
-      } else {
-        // No loaders - wrap in OutletProvider so layout can use <Outlet />
-        result = (
-          <OutletProvider content={content} segment={segment}>
-            {segment.layout}
-          </OutletProvider>
-        );
-      }
-    } else if (segment.loaderDataPromise && segment.loaderIds) {
-      // No layout but has loaders - wrap content with LoaderBoundary for useLoader context
-      // This is common for intercept routes that use useLoader without a custom layout
-      result = (
-        <LoaderBoundary
-          loaderDataPromise={segment.loaderDataPromise}
-          loaderIds={segment.loaderIds}
-          fallback={segment.loading}
-          outletKey={segment.id + "-loader"}
-          outletContent={null}
-          segment={segment}
-        >
-          {content}
-        </LoaderBoundary>
-      );
-    } else {
-      result = content;
-    }
-
-    // Wrap with MountContextProvider for include() scoped parallel/intercept slots
-    if (segment.mountPath) {
-      return (
-        <MountContextProvider value={segment.mountPath}>
-          {result}
-        </MountContextProvider>
-      );
-    }
-
-    return result;
+    return renderSlotContent(namedSegment);
   }
 
   // Default: render child content
@@ -164,6 +155,7 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
 
   return content;
 }
+
 /**
  * ParallelOutlet component - renders content for a named parallel slot
  *
@@ -188,94 +180,9 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
  */
 export function ParallelOutlet({ name }: { name: `@${string}` }): ReactNode {
   const context = useContext(OutletContext);
-  const segment = useMemo(() => {
-    if (!context?.parallel) return null;
-    return context.parallel.find((seg) => seg.slot === name) ?? null;
-  }, [context, name]);
+  const segment = useSlotSegment(context, name);
 
-  if (!segment) return null;
-
-  // Determine the content to render
-  let content: ReactNode;
-  if (segment.loading || segment.component instanceof Promise) {
-    // Use RouteContentWrapper to handle Suspense wrapping properly
-    content = (
-      <RouteContentWrapper
-        content={
-          segment.component instanceof Promise
-            ? segment.component
-            : Promise.resolve(segment.component)
-        }
-        fallback={segment.loading}
-        segmentId={segment.id}
-      />
-    );
-  } else {
-    content = segment.component ?? null;
-  }
-
-  let result: ReactNode;
-
-  // If segment has a layout, wrap appropriately
-  if (segment.layout) {
-    // Check if this segment has loaders that need streaming
-    // The layout renders immediately, LoaderBoundary becomes the outlet content
-    if (segment.loaderDataPromise && segment.loaderIds) {
-      const loaderAwareContent = (
-        <LoaderBoundary
-          loaderDataPromise={segment.loaderDataPromise}
-          loaderIds={segment.loaderIds}
-          fallback={segment.loading}
-          outletKey={segment.id + "-loader"}
-          outletContent={null}
-          segment={segment}
-        >
-          {content}
-        </LoaderBoundary>
-      );
-
-      result = (
-        <OutletProvider content={loaderAwareContent} segment={segment}>
-          {segment.layout}
-        </OutletProvider>
-      );
-    } else {
-      // No loaders - wrap in OutletProvider so layout can use <Outlet />
-      result = (
-        <OutletProvider content={content} segment={segment}>
-          {segment.layout}
-        </OutletProvider>
-      );
-    }
-  } else if (segment.loaderDataPromise && segment.loaderIds) {
-    // No layout but has loaders - wrap content with LoaderBoundary for useLoader context
-    // This is common for intercept routes that use useLoader without a custom layout
-    result = (
-      <LoaderBoundary
-        loaderDataPromise={segment.loaderDataPromise}
-        loaderIds={segment.loaderIds}
-        fallback={segment.loading}
-        outletKey={segment.id + "-loader"}
-        outletContent={null}
-        segment={segment}
-      >
-        {content}
-      </LoaderBoundary>
-    );
-  } else {
-    result = content;
-  }
-
-  // Wrap with MountContextProvider for include() scoped parallel/intercept slots
-  if (segment.mountPath) {
-    return (
-      <MountContextProvider value={segment.mountPath}>
-        {result}
-      </MountContextProvider>
-    );
-  }
-
-  return result;
+  return renderSlotContent(segment);
 }
 
 // OutletProvider is defined in outlet-provider.tsx to break a circular
@@ -313,57 +220,6 @@ export {
   type UseLoaderOptions,
 } from "./use-loader.js";
 
-/**
- * Client-safe createLoader factory
- *
- * Creates a loader definition that can be used with useLoader().
- * This is the client-side version that only stores the $$id - the function
- * is ignored since loaders only execute on the server.
- *
- * The $$id is injected by the exposeLoaderId Vite plugin. In most cases,
- * you should import the loader directly from the server file rather than
- * creating a reference manually.
- *
- * @param fn - Loader function (ignored on client, kept for API compatibility)
- * @param _fetchable - Optional fetchable flag (ignored on client)
- * @param __injectedId - $$id injected by Vite plugin
- *
- * @example
- * ```tsx
- * "use client";
- * import { useLoader } from "rsc-router/client";
- * import { CartLoader } from "../loaders/cart"; // Import from server file
- *
- * export function CartIcon() {
- *   const cart = useLoader(CartLoader);
- *   return <span>Cart ({cart?.items.length ?? 0})</span>;
- * }
- * ```
- */
-// Overload 1: With function only (not fetchable)
-export function createLoader<T>(
-  fn: LoaderFn<T, Record<string, string | undefined>, any>,
-): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
-
-// Overload 2: With function and fetchable flag
-export function createLoader<T>(
-  fn: LoaderFn<T, Record<string, string | undefined>, any>,
-  fetchable: true,
-): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
-
-// Implementation - function is ignored at runtime on client
-// The $$id is injected by Vite plugin as hidden third parameter
-export function createLoader(
-  _fn: LoaderFn<any, Record<string, string | undefined>, any>,
-  _fetchable?: true,
-  __injectedId?: string,
-): LoaderDefinition<any, Record<string, string | undefined>> {
-  return {
-    __brand: "loader",
-    $$id: __injectedId || "",
-  };
-}
-
 /**
  * Props for the ErrorBoundary component
  */
@@ -534,10 +390,8 @@ export {
   type ScrollRestorationProps,
 } from "./browser/react/ScrollRestoration.js";
 
-// Handle API - for accumulating data across route segments
-export { createHandle, isHandle, type Handle } from "./handle.js";
-
-// Handle data hook
+// Handle data hook (client-side only — createHandle/isHandle are server APIs from the root export)
+export { type Handle } from "./handle.js";
 export { useHandle } from "./browser/react/use-handle.js";
 
 // Built-in handles

package/src/index.ts

@@ -147,24 +147,52 @@ export { createVar, type ContextVar } from "./context-var.js";
 export { nonce } from "./rsc/nonce.js";
 
 /**
- * Error-throwing stub for server-only `Prerender` function.
+ * SSR/client stub for server-only `Prerender` function.
+ *
+ * Returns a lightweight stub object instead of throwing so that the
+ * production SSR build can safely bundle the RSC entry chunk — the SSR
+ * bundler resolves `@rangojs/router` to this (SSR) entry, so Prerender
+ * calls in RSC code must not crash at module-evaluation time.
  */
-export function Prerender(): never {
-  throw serverOnlyStubError("Prerender");
+export function Prerender(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "prerenderHandler" as const, $$id: id };
 }
 
 /**
- * Error-throwing stub for server-only `Passthrough` function.
+ * SSR/client stub for server-only `Passthrough` function.
  */
-export function Passthrough(): never {
-  throw serverOnlyStubError("Passthrough");
+export function Passthrough(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "passthroughHandler" as const, $$id: id };
 }
 
 /**
- * Error-throwing stub for server-only `Static` function.
+ * SSR/client stub for server-only `Static` function.
+ *
+ * Returns a lightweight stub object instead of throwing so that the
+ * production SSR build can safely bundle the RSC entry chunk — the SSR
+ * bundler resolves `@rangojs/router` to this (SSR) entry, so Static
+ * calls in RSC code must not crash at module-evaluation time.
  */
-export function Static(): never {
-  throw serverOnlyStubError("Static");
+export function Static(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "staticHandler" as const, $$id: id };
 }
 
 /**
@@ -243,6 +271,10 @@ export type {
   ReadonlyHeaders,
 } from "./server/cookie-store.js";
 
+// Built-in handles (universal — work on both server and client)
+export { Meta } from "./handles/meta.js";
+export { Breadcrumbs } from "./handles/breadcrumbs.js";
+
 // Meta types
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 

package/src/reverse.ts

@@ -311,7 +311,10 @@ export function createReverse<TRoutes extends Record<string, string>>(
         /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
         (_, key, _constraint, optional) => {
           const value = params[key];
-          if (value === undefined) {
+          // Empty string is treated as omitted — the trie matcher fills
+          // unmatched optional params with "" (not undefined), so reverse
+          // must collapse those segments instead of leaving empty slots.
+          if (value === undefined || value === "") {
             hadOmittedOptional = true;
             return "";
           }