@rangojs/router 0.0.0-experimental.760a71d9 → 0.0.0-experimental.77

package/src/context-var.ts

@@ -12,6 +12,9 @@
  * interface PaginationData { current: number; total: number }
  * export const Pagination = createVar<PaginationData>();
  *
+ * // Non-cacheable var — throws if set/get inside cache() or "use cache"
+ * export const User = createVar<UserData>({ cache: false });
+ *
  * // handler
  * ctx.set(Pagination, { current: 1, total: 4 });
  *
@@ -23,18 +26,36 @@
 export interface ContextVar<T> {
   readonly __brand: "context-var";
   readonly key: symbol;
+  /** When false, the var is non-cacheable — throws inside cache() / "use cache" */
+  readonly cache: boolean;
   /** Phantom field to carry the type parameter. Never set at runtime. */
   readonly __type?: T;
 }
 
+export interface ContextVarOptions {
+  /**
+   * When false, marks this variable as non-cacheable.
+   * Setting or getting this var inside a cache() boundary or "use cache"
+   * function will throw. Use for inherently request-specific data (user
+   * sessions, auth tokens, etc.) that must never be baked into cached segments.
+   *
+   * @default true
+   */
+  cache?: boolean;
+}
+
 /**
  * Create a typed context variable token.
  *
  * The returned object is used with ctx.set(token, value) and ctx.get(token)
  * for compile-time-checked data flow between handlers, layouts, and middleware.
  */
-export function createVar<T>(): ContextVar<T> {
-  return { __brand: "context-var" as const, key: Symbol() };
+export function createVar<T>(options?: ContextVarOptions): ContextVar<T> {
+  return {
+    __brand: "context-var" as const,
+    key: Symbol(),
+    cache: options?.cache !== false,
+  };
 }
 
 /**
@@ -49,6 +70,36 @@ export function isContextVar(value: unknown): value is ContextVar<unknown> {
   );
 }
 
+/**
+ * Symbol used as a Set stored on the variables object to track
+ * which keys hold non-cacheable values (from write-level { cache: false }).
+ */
+const NON_CACHEABLE_KEYS: unique symbol = Symbol.for(
+  "rango:non-cacheable-keys",
+) as any;
+
+function getNonCacheableKeys(variables: any): Set<string | symbol> {
+  if (!variables[NON_CACHEABLE_KEYS]) {
+    variables[NON_CACHEABLE_KEYS] = new Set();
+  }
+  return variables[NON_CACHEABLE_KEYS];
+}
+
+/**
+ * Check if a variable value is non-cacheable (either var-level or write-level).
+ */
+export function isNonCacheable(
+  variables: any,
+  keyOrVar: string | ContextVar<any>,
+): boolean {
+  if (typeof keyOrVar !== "string" && !keyOrVar.cache) {
+    return true; // var-level policy
+  }
+  const key = typeof keyOrVar === "string" ? keyOrVar : keyOrVar.key;
+  const set = variables[NON_CACHEABLE_KEYS] as Set<string | symbol> | undefined;
+  return set?.has(key) ?? false; // write-level policy
+}
+
 /**
  * Read a variable from the variables store.
  * Accepts either a string key (legacy) or a ContextVar token (typed).
@@ -64,6 +115,17 @@ export function contextGet(
 /** Keys that must never be used as string variable names */
 const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 
+export interface ContextSetOptions {
+  /**
+   * When false, marks this specific write as non-cacheable.
+   * "Least cacheable wins" — if either the var definition or this option
+   * says cache: false, the value is non-cacheable.
+   *
+   * @default true (inherits from createVar)
+   */
+  cache?: boolean;
+}
+
 /**
  * Write a variable to the variables store.
  * Accepts either a string key (legacy) or a ContextVar token (typed).
@@ -72,6 +134,7 @@ export function contextSet(
   variables: any,
   keyOrVar: string | ContextVar<any>,
   value: any,
+  options?: ContextSetOptions,
 ): void {
   if (typeof keyOrVar === "string") {
     if (FORBIDDEN_KEYS.has(keyOrVar)) {
@@ -80,7 +143,14 @@ export function contextSet(
       );
     }
     variables[keyOrVar] = value;
+    if (options?.cache === false) {
+      getNonCacheableKeys(variables).add(keyOrVar);
+    }
   } else {
     variables[keyOrVar.key] = value;
+    // Track write-level non-cacheable (var-level is checked via keyOrVar.cache)
+    if (options?.cache === false) {
+      getNonCacheableKeys(variables).add(keyOrVar.key);
+    }
   }
 }

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/index.rsc.ts

@@ -100,6 +100,7 @@ export type {
   LayoutUseItem,
   AllUseItems,
   UseItems,
+  HandlerUseItem,
 } from "./route-types.js";
 
 // Handle API
@@ -114,8 +115,9 @@ export { nonce } from "./rsc/nonce.js";
 // Pre-render handler API
 export {
   Prerender,
+  Passthrough,
   type PrerenderHandlerDefinition,
-  type PrerenderPassthroughContext,
+  type PassthroughHandlerDefinition,
   type PrerenderOptions,
   type BuildContext,
   type StaticBuildContext,

package/src/index.ts

@@ -88,6 +88,7 @@ export type {
   LayoutUseItem,
   AllUseItems,
   UseItems,
+  HandlerUseItem,
 } from "./route-types.js";
 
 // Response route types (usable in both server and client contexts)
@@ -146,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(): 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 `Static` function.
+ * SSR/client stub for server-only `Passthrough` function.
  */
-export function Static(): never {
-  throw serverOnlyStubError("Static");
+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 };
 }
 
 /**
@@ -235,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/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;

package/src/prerender.ts

@@ -36,6 +36,7 @@ import type { Handle } from "./handle.js";
 import type { ContextVar } from "./context-var.js";
 import type { ReverseFunction } from "./reverse.js";
 import type { DefaultReverseRouteMap } from "./types/global-namespace.js";
+import type { UseItems, HandlerUseItem } from "./route-types.js";
 import { isCachedFunction } from "./cache/taint.js";
 
 // -- Named route resolution types -------------------------------------------
@@ -105,13 +106,6 @@ type ResolvePrerenderParams<
 // -- Types ------------------------------------------------------------------
 
 export interface PrerenderOptions {
-  /**
-   * Keep handler in server bundle for live fallback (default: false).
-   * false: handler replaced with stub, source-only APIs excluded from bundle.
-   * true: handler stays in bundle, unknown params render live at request time.
-   */
-  passthrough?: boolean;
-
   /**
    * Maximum number of param sets to render in parallel (default: 1).
    * Only applies to dynamic Prerender handlers with getParams().
@@ -131,8 +125,8 @@ export interface PrerenderOptions {
 
 /**
  * Context passed to Prerender() handlers at build time.
- * Has a synthetic URL from getParams, params, and pathname.
- * No request, env, headers, cookies.
+ * Has a synthetic URL from getParams, params, pathname, and optionally env.
+ * No request, headers, cookies.
  */
 export interface BuildContext<TParams> {
   /** Params extracted from the route pattern (populated from getParams). */
@@ -141,6 +135,23 @@ export interface BuildContext<TParams> {
   /** True during build-time pre-rendering, false during passthrough live render. */
   build: true;
 
+  /**
+   * True when running in Vite dev mode (on-demand prerender), false during
+   * production `vite build`. Use this to branch on runtime mode without
+   * changing build semantics.
+   */
+  dev: boolean;
+
+  /**
+   * Build-time environment bindings (KV, D1, etc.) supplied by the Vite plugin.
+   * Only available when `buildEnv` is configured in rango() options.
+   * Throws with a clear error if not configured.
+   *
+   * This is NOT the live request env — it is shared across all prerender
+   * invocations for the build.
+   */
+  env: DefaultEnv;
+
   /** Read a variable set by getParams or a parent handler. */
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;
@@ -173,8 +184,8 @@ export interface BuildContext<TParams> {
 
   /**
    * Signal that this param set should not produce a local prerender artifact.
-   * At runtime the handler runs live instead. Only valid on routes declared
-   * with `{ passthrough: true }`.
+   * At runtime the live handler runs instead. Only valid on routes wrapped
+   * with `Passthrough()`.
    */
   passthrough: () => PrerenderPassthroughResult;
 }
@@ -187,6 +198,17 @@ export interface StaticBuildContext {
   /** Always true for Static handlers at build time. */
   build: true;
 
+  /**
+   * True when running in Vite dev mode, false during production build.
+   */
+  dev: boolean;
+
+  /**
+   * Build-time environment bindings supplied by the Vite plugin.
+   * Only available when `buildEnv` is configured in rango() options.
+   */
+  env: DefaultEnv;
+
   /** Read a variable (available for type consistency with BuildContext). */
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;
@@ -214,6 +236,17 @@ export interface GetParamsContext {
   /** Always true during build-time getParams execution. */
   build: true;
 
+  /**
+   * True when running in Vite dev mode, false during production build.
+   */
+  dev: boolean;
+
+  /**
+   * Build-time environment bindings supplied by the Vite plugin.
+   * Only available when `buildEnv` is configured in rango() options.
+   */
+  env: DefaultEnv;
+
   /** Set a variable that will be available to each handler invocation via ctx.get(). */
   set: {
     <T>(contextVar: ContextVar<T>, value: T): void;
@@ -224,23 +257,6 @@ export interface GetParamsContext {
   reverse: BuildReverseFunction;
 }
 
-/**
- * Context type for passthrough Prerender handlers.
- *
- * When `passthrough: true`, the handler runs both at build time and at request
- * time. The context is a full `HandlerContext` with `build: boolean`:
- * - `ctx.build === true`: build-time, env/request/res throw at runtime
- * - `ctx.build === false`: live request, full context available
- *
- * For `passthrough: false` (default), handlers receive `BuildContext` only.
- */
-export type PrerenderPassthroughContext<
-  TParams = {},
-  TEnv = DefaultEnv,
-> = HandlerContext<TParams, TEnv> & {
-  passthrough: () => PrerenderPassthroughResult;
-};
-
 export interface PrerenderHandlerDefinition<
   TParams extends Record<string, any> = any,
 > {
@@ -253,6 +269,8 @@ export interface PrerenderHandlerDefinition<
   getParams?: (ctx: GetParamsContext) => Promise<TParams[]> | TParams[];
   /** Pre-render options. */
   options?: PrerenderOptions;
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<HandlerUseItem>;
 }
 
 // -- Overloads --------------------------------------------------------------
@@ -263,7 +281,7 @@ export interface PrerenderHandlerDefinition<
 // Explicit params work as before:
 //   Prerender<{ slug: string }> → params = { slug: string }
 
-// Overload 1: Static handler, no passthrough (build-time only)
+// Overload 1: Static handler (build-time only)
 export function Prerender<
   T extends
     | keyof DefaultPrerenderRouteMap
@@ -273,34 +291,15 @@ export function Prerender<
 >(
   handler: (
     ctx: BuildContext<ResolvePrerenderParams<T, TRouteMap>>,
-  ) => ReactNode | Promise<ReactNode>,
-  options?: PrerenderOptions & { passthrough?: false },
-  __injectedId?: string,
-): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
-
-// Overload 2: Static handler, passthrough (build + live — full HandlerContext)
-export function Prerender<
-  T extends
-    | keyof DefaultPrerenderRouteMap
-    | `.${keyof TRouteMap & string}`
-    | Record<string, any> = {},
-  TRouteMap extends {} = DefaultPrerenderRouteMap,
-  TEnv = DefaultEnv,
->(
-  handler: (
-    ctx: PrerenderPassthroughContext<
-      ResolvePrerenderParams<T, TRouteMap>,
-      TEnv
-    >,
   ) =>
     | ReactNode
     | PrerenderPassthroughResult
     | Promise<ReactNode | PrerenderPassthroughResult>,
-  options: PrerenderOptions & { passthrough: true },
+  options?: PrerenderOptions,
   __injectedId?: string,
 ): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
 
-// Overload 3: Dynamic handler, no passthrough (build-time only)
+// Overload 2: Dynamic handler (build-time only)
 export function Prerender<
   T extends
     | keyof DefaultPrerenderRouteMap
@@ -315,35 +314,11 @@ export function Prerender<
     | ResolvePrerenderParams<T, TRouteMap>[],
   handler: (
     ctx: BuildContext<ResolvePrerenderParams<T, TRouteMap>>,
-  ) => ReactNode | Promise<ReactNode>,
-  options?: PrerenderOptions & { passthrough?: false },
-  __injectedId?: string,
-): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
-
-// Overload 4: Dynamic handler, passthrough (build + live — full HandlerContext)
-export function Prerender<
-  T extends
-    | keyof DefaultPrerenderRouteMap
-    | `.${keyof TRouteMap & string}`
-    | Record<string, any>,
-  TRouteMap extends {} = DefaultPrerenderRouteMap,
-  TEnv = DefaultEnv,
->(
-  getParams: (
-    ctx: GetParamsContext,
-  ) =>
-    | Promise<ResolvePrerenderParams<T, TRouteMap>[]>
-    | ResolvePrerenderParams<T, TRouteMap>[],
-  handler: (
-    ctx: PrerenderPassthroughContext<
-      ResolvePrerenderParams<T, TRouteMap>,
-      TEnv
-    >,
   ) =>
     | ReactNode
     | PrerenderPassthroughResult
     | Promise<ReactNode | PrerenderPassthroughResult>,
-  options: PrerenderOptions & { passthrough: true },
+  options?: PrerenderOptions,
   __injectedId?: string,
 ): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
 
@@ -422,7 +397,7 @@ export function Prerender<TParams extends Record<string, any>>(
 /**
  * Sentinel returned by `ctx.passthrough()` to signal that a specific param set
  * should not produce a local prerender artifact. The build skips writing the
- * entry; at runtime the handler runs live (requires `{ passthrough: true }`).
+ * entry; at runtime the Passthrough live handler runs instead.
  */
 export const PRERENDER_PASSTHROUGH: Readonly<{
   __brand: "prerenderPassthrough";
@@ -446,7 +421,7 @@ export function isPrerenderPassthrough(
   );
 }
 
-// -- Type guard -------------------------------------------------------------
+// -- Type guards ------------------------------------------------------------
 
 /**
  * Type guard to check if a value is a PrerenderHandlerDefinition.
@@ -461,3 +436,89 @@ export function isPrerenderHandler(
     (value as { __brand: unknown }).__brand === "prerenderHandler"
   );
 }
+
+// -- Passthrough wrapper ----------------------------------------------------
+
+/**
+ * A prerender route with a live fallback handler for unknown params at runtime.
+ *
+ * Wraps a `Prerender(...)` definition with a separate handler that runs at
+ * request time for params not covered by `getParams()`.
+ *
+ * - Build time: `prerenderDef` provides getParams + build handler.
+ * - Runtime: `liveHandler` runs for unknown params with full HandlerContext.
+ *
+ * @example
+ * ```ts
+ * const BlogPrerender = Prerender(
+ *   async () => [{ slug: "getting-started" }, { slug: "api-reference" }],
+ *   async (ctx) => <BlogPost slug={ctx.params.slug} />,
+ * );
+ *
+ * // In route definition:
+ * path("/blog/:slug", Passthrough(BlogPrerender, async (ctx) => {
+ *   const post = await ctx.env.DB.get(ctx.params.slug);
+ *   return <BlogPost slug={ctx.params.slug} post={post} />;
+ * }))
+ * ```
+ */
+export interface PassthroughHandlerDefinition<
+  TParams extends Record<string, any> = any,
+  TEnv = DefaultEnv,
+> {
+  readonly __brand: "passthroughHandler";
+  /** The underlying prerender definition (build-time rendering). */
+  prerenderDef: PrerenderHandlerDefinition<TParams>;
+  /** Live handler for runtime fallback on unknown params. */
+  liveHandler: (
+    ctx: HandlerContext<TParams, TEnv>,
+  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>;
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<HandlerUseItem>;
+}
+
+export function Passthrough<
+  TParams extends Record<string, any>,
+  TEnv = DefaultEnv,
+>(
+  prerenderDef: PrerenderHandlerDefinition<TParams>,
+  liveHandler: (
+    ctx: HandlerContext<TParams, TEnv>,
+  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>,
+): PassthroughHandlerDefinition<TParams, TEnv>;
+
+// Implementation
+export function Passthrough<
+  TParams extends Record<string, any>,
+  TEnv = DefaultEnv,
+>(
+  prerenderDef: PrerenderHandlerDefinition<TParams>,
+  liveHandler: (
+    ctx: HandlerContext<TParams, TEnv>,
+  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>,
+): PassthroughHandlerDefinition<TParams, TEnv> {
+  if (!isPrerenderHandler(prerenderDef)) {
+    throw new Error(
+      "[rsc-router] Passthrough: first argument must be a Prerender() definition.",
+    );
+  }
+  return {
+    __brand: "passthroughHandler" as const,
+    prerenderDef,
+    liveHandler,
+  };
+}
+
+/**
+ * Type guard to check if a value is a PassthroughHandlerDefinition.
+ */
+export function isPassthroughHandler(
+  value: unknown,
+): value is PassthroughHandlerDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__brand" in value &&
+    (value as { __brand: unknown }).__brand === "passthroughHandler"
+  );
+}

package/src/reverse.ts

@@ -305,8 +305,25 @@ export function createReverse<TRoutes extends Record<string, string>>(
     if (params) {
       // Replace :param placeholders with actual values
       // Strip constraint syntax: :param(a|b) -> use "param" as key
+      // Optional params (:param?) are omitted when not provided
+      let hadOmittedOptional = false;
       result = result.replace(
-        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?\??/g,
+        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
+        (_, key, _constraint, optional) => {
+          const value = params[key];
+          // 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 "";
+          }
+          return encodeURIComponent(value);
+        },
+      );
+      // Second pass: required params (no trailing ?)
+      result = result.replace(
+        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(?!\?)/g,
         (_, key) => {
           const value = params[key];
           if (value === undefined) {
@@ -315,6 +332,13 @@ export function createReverse<TRoutes extends Record<string, string>>(
           return encodeURIComponent(value);
         },
       );
+      // Clean up slashes only when an optional param was actually omitted,
+      // so intentional trailing-slash patterns like "/blog/" are preserved.
+      if (hadOmittedOptional) {
+        const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+        result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
+        if (hadTrailingSlash && !result.endsWith("/")) result += "/";
+      }
     }
 
     // Append search params as query string