@rangojs/router 0.0.0-experimental.20 → 0.0.0-experimental.20dbba0c

package/src/debug.ts

@@ -2,7 +2,7 @@
  * Debug utilities for manifest inspection and comparison
  */
 
-import type { EntryData } from "./server/context";
+import { getParallelSlotCount, type EntryData } from "./server/context";
 
 /**
  * Serialized entry for debug output
@@ -64,7 +64,7 @@ export function serializeManifest(
       hasLoader: entry.loader?.length > 0,
       hasMiddleware: entry.middleware?.length > 0,
       hasErrorBoundary: entry.errorBoundary?.length > 0,
-      parallelCount: entry.parallel?.length ?? 0,
+      parallelCount: getParallelSlotCount(entry.parallel),
       interceptCount: entry.intercept?.length ?? 0,
     };
 

package/src/handle.ts

@@ -133,3 +133,43 @@ export function isHandle(value: unknown): value is Handle<unknown, unknown> {
     (value as { __brand: unknown }).__brand === "handle"
   );
 }
+
+/**
+ * Collect handle data from a HandleData map, applying the handle's collect
+ * function over segments in order. Shared between server-side rendered()
+ * reads and client-side useHandle().
+ *
+ * @param handle - The handle to collect data for
+ * @param data - Full handle data map (handleName -> segmentId -> entries[])
+ * @param segmentOrder - Segment IDs in parent -> child resolution order
+ */
+export function collectHandleData<TData, TAccumulated>(
+  handle: Handle<TData, TAccumulated>,
+  data: Record<string, Record<string, unknown[]>>,
+  segmentOrder: string[],
+): TAccumulated {
+  const collectFn = getCollectFn(handle.$$id);
+  if (!collectFn && process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[rsc-router] Handle "${handle.$$id}" has no registered collect function. ` +
+        `Falling back to flat array. Ensure the handle module is imported so ` +
+        `createHandle() runs and registers the collect function.`,
+    );
+  }
+  const collect = (collectFn ??
+    (defaultCollect as unknown as (segments: unknown[][]) => unknown)) as (
+    segments: TData[][],
+  ) => TAccumulated;
+
+  const segmentData = data[handle.$$id];
+  if (!segmentData) return collect([]);
+
+  const segmentArrays: TData[][] = [];
+  for (const segmentId of segmentOrder) {
+    const entries = segmentData[segmentId];
+    if (entries && entries.length > 0) {
+      segmentArrays.push(entries as TData[]);
+    }
+  }
+  return collect(segmentArrays);
+}

package/src/handles/breadcrumbs.ts

@@ -0,0 +1,66 @@
+/**
+ * Built-in Breadcrumbs handle for accumulating breadcrumb items across route segments.
+ *
+ * Each layout/route pushes breadcrumb items via `ctx.use(Breadcrumbs)`.
+ * Items are collected in parent-to-child order with automatic deduplication
+ * by `href` (last item for each href wins).
+ *
+ * @example
+ * ```tsx
+ * // In route handler
+ * route("/blog/:slug", (ctx) => {
+ *   const breadcrumb = ctx.use(Breadcrumbs);
+ *   breadcrumb({ label: "Blog", href: "/blog" });
+ *   breadcrumb({ label: post.title, href: `/blog/${ctx.params.slug}` });
+ * });
+ *
+ * // In client component (consume with useHandle)
+ * const crumbs = useHandle(Breadcrumbs);
+ * crumbs.map((c) => <a href={c.href}>{c.label}</a>);
+ * ```
+ */
+
+import type { ReactNode } from "react";
+import { createHandle, type Handle } from "../handle.js";
+
+/**
+ * A single breadcrumb item.
+ *
+ * @property label - Display text for the breadcrumb
+ * @property href - URL the breadcrumb links to
+ * @property content - Optional extra content (sync or async) rendered alongside the label
+ */
+export interface BreadcrumbItem {
+  label: string;
+  href: string;
+  content?: ReactNode | Promise<ReactNode>;
+}
+
+/**
+ * Collect function for Breadcrumbs handle.
+ * Flattens segments in parent-to-child order with deduplication by href
+ * (last item for each href wins).
+ */
+function collectBreadcrumbs(segments: BreadcrumbItem[][]): BreadcrumbItem[] {
+  const all = segments.flat();
+  const seen = new Map<string, number>();
+
+  for (let i = 0; i < all.length; i++) {
+    seen.set(all[i].href, i);
+  }
+
+  // Return items in order, keeping only the last occurrence per href
+  return all.filter((item, index) => seen.get(item.href) === index);
+}
+
+/**
+ * Built-in handle for accumulating breadcrumb navigation items.
+ *
+ * Use `ctx.use(Breadcrumbs)` in route handlers to push breadcrumb items.
+ * Use `useHandle(Breadcrumbs)` in client components to consume them.
+ */
+export const Breadcrumbs: Handle<BreadcrumbItem, BreadcrumbItem[]> =
+  createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+    collectBreadcrumbs,
+    "__rsc_router_breadcrumbs__",
+  );

package/src/handles/index.ts

@@ -4,3 +4,4 @@
 
 export { Meta } from "./meta.ts";
 export { MetaTags } from "./MetaTags.tsx";
+export { Breadcrumbs, type BreadcrumbItem } from "./breadcrumbs.ts";

package/src/host/index.ts

@@ -25,9 +25,6 @@
 // Core router
 export { createHostRouter } from "./router.js";
 
-// Host router registry for build-time discovery
-export { HostRouterRegistry, type HostRouterRegistryEntry } from "./router.js";
-
 // Utilities
 export { defineHosts } from "./utils.js";
 

package/src/index.rsc.ts

@@ -11,8 +11,6 @@
 
 // Re-export all universal exports from index.ts
 export {
-  // Universal rendering utilities
-  renderSegments,
   // Error classes
   RouteNotFoundError,
   DataNotFoundError,
@@ -21,9 +19,6 @@ export {
   HandlerError,
   BuildError,
   InvalidHandlerError,
-  NetworkError,
-  isNetworkError,
-  sanitizeError,
   RouterError,
   Skip,
   isSkip,
@@ -40,7 +35,6 @@ export type {
   TrailingSlashMode,
   // Handler types
   Handler,
-  ScopedRouteMap,
   HandlerContext,
   ExtractParams,
   GenericParams,
@@ -106,6 +100,7 @@ export type {
   LayoutUseItem,
   AllUseItems,
   UseItems,
+  HandlerUseItem,
 } from "./route-types.js";
 
 // Handle API
@@ -120,9 +115,9 @@ export { nonce } from "./rsc/nonce.js";
 // Pre-render handler API
 export {
   Prerender,
-  isPrerenderHandler,
+  Passthrough,
   type PrerenderHandlerDefinition,
-  type PrerenderPassthroughContext,
+  type PassthroughHandlerDefinition,
   type PrerenderOptions,
   type BuildContext,
   type StaticBuildContext,
@@ -130,16 +125,11 @@ export {
 } from "./prerender.js";
 
 // Static handler API
-export {
-  Static,
-  isStaticHandler,
-  type StaticHandlerDefinition,
-} from "./static-handler.js";
+export { Static, type StaticHandlerDefinition } from "./static-handler.js";
 
 // Django-style URL patterns (RSC/server context)
 export {
   urls,
-  RESPONSE_TYPE,
   type PathHelpers,
   type PathOptions,
   type UrlPatterns,
@@ -171,6 +161,7 @@ export type { HandlerCacheConfig } from "./rsc/types.js";
 
 // Built-in handles (server-side)
 export { Meta } from "./handles/meta.js";
+export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 
 // Request context (for accessing request data in server actions/components).
 // Re-exported with a narrowed return type so that public consumers only see
@@ -181,6 +172,9 @@ export type { PublicRequestContext as RequestContext } from "./server/request-co
 import type { PublicRequestContext } from "./server/request-context.js";
 import type { DefaultEnv } from "./types/global-namespace.js";
 
+// Shared base for every user-facing request context (mirrors index.ts).
+export type { RequestScope, ExecutionContext } from "./types/request-scope.js";
+
 export const getRequestContext: <
   TEnv = DefaultEnv,
 >() => PublicRequestContext<TEnv> = _getRequestContextInternal;
@@ -206,8 +200,6 @@ export type {
   ReverseFunction,
   ExtractLocalRoutes,
   ParamsFor,
-  SanitizePrefix,
-  MergeRoutes,
 } from "./reverse.js";
 export { scopedReverse, createReverse } from "./reverse.js";
 
@@ -220,12 +212,6 @@ export type {
   RouteParams,
 } from "./search-params.js";
 
-// Debug utilities for route matching (development only)
-export {
-  enableMatchDebug,
-  getMatchDebugStats,
-} from "./router/pattern-matching.js";
-
 // Location state (universal)
 export {
   createLocationState,
@@ -241,20 +227,7 @@ export type { PathResponse } from "./href-client.js";
 export { createConsoleSink } from "./router/telemetry.js";
 export { createOTelSink } from "./router/telemetry-otel.js";
 export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
-export type {
-  TelemetrySink,
-  TelemetryEvent,
-  RequestStartEvent,
-  RequestEndEvent,
-  RequestErrorEvent,
-  RequestTimeoutEvent,
-  LoaderStartEvent,
-  LoaderEndEvent,
-  LoaderErrorEvent,
-  HandlerErrorEvent,
-  CacheDecisionEvent,
-  RevalidationDecisionEvent,
-} from "./router/telemetry.js";
+export type { TelemetrySink, TelemetryEvent } from "./router/telemetry.js";
 
 // Timeout types and error class
 export { RouterTimeoutError } from "./router/timeout.js";

package/src/index.ts

@@ -10,9 +10,6 @@
  *   import from "@rangojs/router/client"
  */
 
-// Universal rendering utilities (work on both server and client)
-export { renderSegments } from "./segment-system.js";
-
 // Error classes (can be used on both server and client)
 export {
   RouteNotFoundError,
@@ -22,9 +19,6 @@ export {
   HandlerError,
   BuildError,
   InvalidHandlerError,
-  NetworkError,
-  isNetworkError,
-  sanitizeError,
   RouterError,
   Skip,
   isSkip,
@@ -41,7 +35,6 @@ export type {
   TrailingSlashMode,
   // Handler types
   Handler, // Supports params object, path pattern, or route name
-  ScopedRouteMap, // Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>
   HandlerContext,
   ExtractParams,
   GenericParams,
@@ -95,6 +88,7 @@ export type {
   LayoutUseItem,
   AllUseItems,
   UseItems,
+  HandlerUseItem,
 } from "./route-types.js";
 
 // Response route types (usable in both server and client contexts)
@@ -115,25 +109,32 @@ export type {
 // Middleware context types
 export type { MiddlewareContext, CookieOptions } from "./router/middleware.js";
 
+function serverOnlyStubError(name: string): Error {
+  return new Error(
+    `${name}() is only available from "@rangojs/router" in a react-server/RSC environment. ` +
+      `For client hooks and components, import from "@rangojs/router/client".`,
+  );
+}
+
 /**
  * Error-throwing stub for server-only `urls` function.
  */
 export function urls(): never {
-  throw new Error("urls() is server-only and requires RSC context.");
+  throw serverOnlyStubError("urls");
 }
 
 /**
  * Error-throwing stub for server-only `createRouter` function.
  */
 export function createRouter(): never {
-  throw new Error("createRouter() is server-only and requires RSC context.");
+  throw serverOnlyStubError("createRouter");
 }
 
 /**
  * Error-throwing stub for server-only `redirect` function.
  */
 export function redirect(): never {
-  throw new Error("redirect() is server-only and requires RSC context.");
+  throw serverOnlyStubError("redirect");
 }
 
 // Handle API (universal - works on both server and client)
@@ -146,110 +147,126 @@ 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 new Error("Prerender() is server-only and requires RSC context.");
+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 `Static` function.
+ * SSR/client stub for server-only `Passthrough` function.
  */
-export function Static(): never {
-  throw new Error("Static() is server-only and requires RSC context.");
+export function Passthrough(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "passthroughHandler" as const, $$id: id };
+}
+
+/**
+ * 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(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "staticHandler" as const, $$id: id };
 }
 
 /**
  * Error-throwing stub for server-only `getRequestContext` function.
  */
 export function getRequestContext(): never {
-  throw new Error(
-    "getRequestContext() is server-only and requires RSC context.",
-  );
+  throw serverOnlyStubError("getRequestContext");
 }
 
 /**
  * Error-throwing stub for server-only `cookies` function.
  */
 export function cookies(): never {
-  throw new Error("cookies() is server-only and requires RSC context.");
+  throw serverOnlyStubError("cookies");
 }
 
 /**
  * Error-throwing stub for server-only `headers` function.
  */
 export function headers(): never {
-  throw new Error("headers() is server-only and requires RSC context.");
+  throw serverOnlyStubError("headers");
 }
 
 /**
  * Error-throwing stub for server-only `createReverse` function.
  */
 export function createReverse(): never {
-  throw new Error("createReverse() is server-only and requires RSC context.");
-}
-
-/**
- * Error-throwing stub for server-only `enableMatchDebug` function.
- */
-export function enableMatchDebug(): never {
-  throw new Error(
-    "enableMatchDebug() is server-only and requires RSC context.",
-  );
-}
-
-/**
- * Error-throwing stub for server-only `getMatchDebugStats` function.
- */
-export function getMatchDebugStats(): never {
-  throw new Error(
-    "getMatchDebugStats() is server-only and requires RSC context.",
-  );
+  throw serverOnlyStubError("createReverse");
 }
 
 // Error-throwing stubs for server-only route helpers
 export function layout(): never {
-  throw new Error("layout() is server-only and requires RSC context.");
+  throw serverOnlyStubError("layout");
 }
 export function cache(): never {
-  throw new Error("cache() is server-only and requires RSC context.");
+  throw serverOnlyStubError("cache");
 }
 export function middleware(): never {
-  throw new Error("middleware() is server-only and requires RSC context.");
+  throw serverOnlyStubError("middleware");
 }
 export function revalidate(): never {
-  throw new Error("revalidate() is server-only and requires RSC context.");
+  throw serverOnlyStubError("revalidate");
 }
 export function loader(): never {
-  throw new Error("loader() is server-only and requires RSC context.");
+  throw serverOnlyStubError("loader");
 }
 export function loading(): never {
-  throw new Error("loading() is server-only and requires RSC context.");
+  throw serverOnlyStubError("loading");
 }
 export function parallel(): never {
-  throw new Error("parallel() is server-only and requires RSC context.");
+  throw serverOnlyStubError("parallel");
 }
 export function intercept(): never {
-  throw new Error("intercept() is server-only and requires RSC context.");
+  throw serverOnlyStubError("intercept");
 }
 export function when(): never {
-  throw new Error("when() is server-only and requires RSC context.");
+  throw serverOnlyStubError("when");
 }
 export function errorBoundary(): never {
-  throw new Error("errorBoundary() is server-only and requires RSC context.");
+  throw serverOnlyStubError("errorBoundary");
 }
 export function notFoundBoundary(): never {
-  throw new Error(
-    "notFoundBoundary() is server-only and requires RSC context.",
-  );
+  throw serverOnlyStubError("notFoundBoundary");
 }
 export function transition(): never {
-  throw new Error("transition() is server-only and requires RSC context.");
+  throw serverOnlyStubError("transition");
 }
 
 // Request context type (safe for client)
 export type { PublicRequestContext as RequestContext } from "./server/request-context.js";
 
+// Shared base for every user-facing request context.
+export type { RequestScope, ExecutionContext } from "./types/request-scope.js";
+
 // Cookie store types (safe for client)
 export type {
   CookieStore,
@@ -257,17 +274,22 @@ 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";
 
+// Breadcrumb types
+export type { BreadcrumbItem } from "./handles/breadcrumbs.js";
+
 // Reverse type utilities for type-safe URL generation (Django-style URL reversal)
 export type {
   ScopedReverseFunction,
   ReverseFunction,
   ExtractLocalRoutes,
   ParamsFor,
-  SanitizePrefix,
-  MergeRoutes,
 } from "./reverse.js";
 // scopedReverse() helper for handlers to get locally-typed reverse
 export { scopedReverse } from "./reverse.js";
@@ -287,20 +309,7 @@ export type { PathResponse } from "./href-client.js";
 export { createConsoleSink } from "./router/telemetry.js";
 export { createOTelSink } from "./router/telemetry-otel.js";
 export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
-export type {
-  TelemetrySink,
-  TelemetryEvent,
-  RequestStartEvent,
-  RequestEndEvent,
-  RequestErrorEvent,
-  RequestTimeoutEvent,
-  LoaderStartEvent,
-  LoaderEndEvent,
-  LoaderErrorEvent,
-  HandlerErrorEvent,
-  CacheDecisionEvent,
-  RevalidationDecisionEvent,
-} from "./router/telemetry.js";
+export type { TelemetrySink, TelemetryEvent } from "./router/telemetry.js";
 
 // Timeout types and error class
 export { RouterTimeoutError } from "./router/timeout.js";

package/src/outlet-context.ts

@@ -1,4 +1,4 @@
-import { Context, createContext, type ReactNode } from "react";
+import { type Context, createContext, type ReactNode } from "react";
 import type { ResolvedSegment } from "./types";
 
 export interface OutletContextValue {

package/src/prerender/store.ts

@@ -2,9 +2,10 @@
  * Prerender Store
  *
  * Reads pre-rendered segment data from the worker bundle at build time.
- * The data is stored as globalThis.__PRERENDER_MANIFEST, a map of
- * "<routeName>/<paramHash>" to dynamic import functions that resolve
- * individual prerender entry modules.
+ * The manifest module is lazily loaded via globalThis.__loadPrerenderManifestModule,
+ * a function injected into the RSC entry that returns the manifest module
+ * containing a key-to-specifier map and a `loadPrerenderAsset` function
+ * that anchors import() resolution relative to the manifest file.
  */
 
 import type {
@@ -34,11 +35,20 @@ export interface StaticStore {
   get(handlerId: string): Promise<StaticEntry | null>;
 }
 
+interface PrerenderManifestModule {
+  default: Record<string, string>;
+  loadPrerenderAsset: (
+    specifier: string,
+  ) => Promise<{ default: PrerenderEntry }>;
+}
+
 declare global {
-  // Injected by closeBundle post-processing: map of key -> () => import("./assets/__pr-*.js")
+  // Injected by closeBundle post-processing: lazy loader for the prerender
+  // manifest module. The module exports a key→specifier map and a
+  // loadPrerenderAsset function that anchors import() relative to the manifest.
   // eslint-disable-next-line no-var
-  var __PRERENDER_MANIFEST:
-    | Record<string, () => Promise<{ default: PrerenderEntry }>>
+  var __loadPrerenderManifestModule:
+    | (() => Promise<PrerenderManifestModule>)
     | undefined;
   // Injected by closeBundle post-processing: map of handlerId -> () => import("./assets/__st-*.js")
   // Asset default export is either a string (no handles) or { encoded, handles } object.
@@ -78,17 +88,28 @@ export function createDevPrerenderStore(devUrl: string): PrerenderStore {
 /**
  * Create a prerender store.
  * Dev mode: on-demand fetch from Vite dev server (node:fs works there).
- * Production: backed by globalThis.__PRERENDER_MANIFEST injected at build time.
+ * Production: backed by globalThis.__loadPrerenderManifestModule which lazily
+ * loads the manifest module on first access.
  * Returns null if no prerender data is available.
  */
 export function createPrerenderStore(): PrerenderStore | null {
   if (globalThis.__PRERENDER_DEV_URL) {
     return createDevPrerenderStore(globalThis.__PRERENDER_DEV_URL);
   }
-  const manifest = globalThis.__PRERENDER_MANIFEST;
-  if (!manifest || Object.keys(manifest).length === 0) return null;
+  if (!globalThis.__loadPrerenderManifestModule) return null;
 
   const cache = new Map<string, Promise<PrerenderEntry | null>>();
+  let manifestModulePromise: Promise<PrerenderManifestModule | null> | null =
+    null;
+
+  function loadManifestModule(): Promise<PrerenderManifestModule | null> {
+    if (!manifestModulePromise) {
+      manifestModulePromise = globalThis.__loadPrerenderManifestModule!().catch(
+        () => null,
+      );
+    }
+    return manifestModulePromise;
+  }
 
   return {
     get(routeName: string, paramHash: string): Promise<PrerenderEntry | null> {
@@ -96,18 +117,39 @@ export function createPrerenderStore(): PrerenderStore | null {
       const cached = cache.get(key);
       if (cached) return cached;
 
-      const loader = manifest[key];
-      if (!loader) return Promise.resolve(null);
-
-      const promise = loader()
-        .then((mod) => mod.default)
-        .catch(() => null);
+      const promise = loadManifestModule().then((mod) => {
+        if (!mod) return null;
+        const specifier = mod.default[key];
+        if (!specifier) return null;
+        // Let asset load errors propagate — a missing/corrupted artifact
+        // for a key that exists in the manifest is a build/deploy error
+        // and should surface as a 500, not be silently swallowed as null
+        // (which the handler stub would misreport as a 404).
+        return mod.loadPrerenderAsset(specifier).then((asset) => asset.default);
+      });
       cache.set(key, promise);
       return promise;
     },
   };
 }
 
+/**
+ * Load the prerender manifest index for test introspection.
+ * Returns the key→specifier map or null if unavailable.
+ */
+export async function loadPrerenderManifestIndex(): Promise<Record<
+  string,
+  string
+> | null> {
+  if (!globalThis.__loadPrerenderManifestModule) return null;
+  try {
+    const mod = await globalThis.__loadPrerenderManifestModule();
+    return mod.default;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Create a static segment store.
  * Production only: backed by globalThis.__STATIC_MANIFEST injected at build time.