@rangojs/router 0.0.0-experimental.29 → 0.0.0-experimental.2c0cb8a1

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/href-client.ts

@@ -186,7 +186,10 @@ export function href<T extends ValidPaths>(path: T, mount?: string): string {
     const normalizedMount = mount.endsWith("/") ? mount.slice(0, -1) : mount;
     return normalizedMount + path;
   }
-  return path;
+  // ValidPaths is built from template literals so T does extend string at
+  // runtime, but the inference can fail past a certain route-union complexity
+  // and TypeScript reports T as not assignable to string.
+  return path as string;
 }
 
 /**

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)
@@ -153,17 +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(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "prerenderHandler" as const, $$id: id };
+}
+
+/**
+ * SSR/client stub for server-only `Passthrough` function.
  */
-export function Prerender(): never {
-  throw serverOnlyStubError("Prerender");
+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 };
 }
 
 /**
@@ -194,20 +223,6 @@ export function createReverse(): never {
   throw serverOnlyStubError("createReverse");
 }
 
-/**
- * Error-throwing stub for server-only `enableMatchDebug` function.
- */
-export function enableMatchDebug(): never {
-  throw serverOnlyStubError("enableMatchDebug");
-}
-
-/**
- * Error-throwing stub for server-only `getMatchDebugStats` function.
- */
-export function getMatchDebugStats(): never {
-  throw serverOnlyStubError("getMatchDebugStats");
-}
-
 // Error-throwing stubs for server-only route helpers
 export function layout(): never {
   throw serverOnlyStubError("layout");
@@ -249,6 +264,9 @@ export function transition(): never {
 // 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,
@@ -256,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";
@@ -286,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

@@ -121,10 +121,11 @@ export function createPrerenderStore(): PrerenderStore | null {
         if (!mod) return null;
         const specifier = mod.default[key];
         if (!specifier) return null;
-        return mod
-          .loadPrerenderAsset(specifier)
-          .then((asset) => asset.default)
-          .catch(() => 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;