@rangojs/router 0.0.0-experimental.0da83ed6 → 0.0.0-experimental.0e02cd4e

package/src/route-types.ts

@@ -257,3 +257,14 @@ export type LoaderUseItem = RevalidateItem | CacheItem;
  * runtime via .flat(3).
  */
 export type UseItems<T> = (T | readonly T[])[];
+
+/**
+ * Union of all items that handler.use() may return.
+ * A handler doesn't know its mount site at definition time, so the type
+ * is intentionally broad — validation happens per-mount-site at runtime.
+ */
+export type HandlerUseItem =
+  | RouteUseItem
+  | LayoutUseItem
+  | ParallelUseItem
+  | InterceptUseItem;

package/src/router/content-negotiation.ts

@@ -2,10 +2,18 @@
  * Content Negotiation Utilities
  *
  * Pure functions for HTTP Accept header parsing and response type matching.
- * Used by createRouter's previewMatch for content negotiation between
+ * Used by previewMatch and classifyRequest for content negotiation between
  * RSC routes and response routes (JSON, text, image, stream, etc.).
  */
 
+import type { EntryData } from "../server/context.js";
+import type { CollectedMiddleware } from "./middleware-types.js";
+import { collectRouteMiddleware } from "./middleware.js";
+import { loadManifest } from "./manifest.js";
+import { traverseBack } from "./pattern-matching.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
+import type { RouteSnapshot } from "./route-snapshot.js";
+
 // Response type -> MIME type used for Accept header matching
 export const RESPONSE_TYPE_MIME: Record<string, string> = {
   json: "application/json",
@@ -114,3 +122,94 @@ export function pickNegotiateVariant(
   // No match -- use first candidate as default
   return candidates[0]!;
 }
+
+/**
+ * Result of content negotiation for a route with negotiate variants.
+ */
+export interface NegotiationResult {
+  /** The winning response type */
+  responseType: string;
+  /** Handler function for the winning variant */
+  handler: Function;
+  /** Manifest entry for the winning variant (may differ from primary) */
+  manifestEntry: EntryData;
+  /** Route middleware for the winning variant */
+  routeMiddleware: CollectedMiddleware[];
+  /** Always true — negotiation occurred */
+  negotiated: true;
+}
+
+/**
+ * Perform content negotiation for a route with negotiate variants.
+ *
+ * Returns a NegotiationResult when a response route wins negotiation.
+ * Returns null when RSC wins or no negotiation is needed.
+ *
+ * Shared by previewMatch and classifyRequest to avoid duplicating
+ * the candidate-building and variant-loading logic.
+ */
+export async function negotiateRoute(
+  request: Request,
+  pathname: string,
+  snapshot: RouteSnapshot,
+): Promise<NegotiationResult | null> {
+  const { matched, manifestEntry, routeMiddleware, responseType } = snapshot;
+  if (!matched.negotiateVariants || matched.negotiateVariants.length === 0) {
+    return null;
+  }
+
+  const acceptEntries = parseAcceptTypes(request.headers.get("accept") || "");
+
+  // Build candidate list preserving definition order.
+  const variants = matched.negotiateVariants;
+  let candidates: Array<{ routeKey: string; responseType: string }>;
+  if (responseType) {
+    candidates = [...variants, { routeKey: matched.routeKey, responseType }];
+  } else {
+    const rscCandidate = {
+      routeKey: matched.routeKey,
+      responseType: RSC_RESPONSE_TYPE,
+    };
+    candidates = matched.rscFirst
+      ? [rscCandidate, ...variants]
+      : [...variants, rscCandidate];
+  }
+
+  const variant = pickNegotiateVariant(acceptEntries, candidates);
+
+  // RSC won negotiation
+  if (variant.responseType === RSC_RESPONSE_TYPE) {
+    return null;
+  }
+
+  // Primary response-type won — use existing manifest entry and middleware
+  if (responseType && variant.routeKey === matched.routeKey) {
+    return {
+      responseType,
+      handler: manifestEntry.handler as Function,
+      manifestEntry,
+      routeMiddleware,
+      negotiated: true,
+    };
+  }
+
+  // Different variant won — load its manifest entry
+  const negotiateEntry = await loadManifest(
+    matched.entry,
+    variant.routeKey,
+    pathname,
+    undefined,
+    false,
+  );
+  const variantMiddleware = collectRouteMiddleware(
+    traverseBack(negotiateEntry),
+    matched.params,
+  );
+  return {
+    responseType: variant.responseType,
+    handler: negotiateEntry.handler as Function,
+    manifestEntry: negotiateEntry,
+    routeMiddleware: variantMiddleware,
+    negotiated: true,
+  };
+}

package/src/router/handler-context.ts

@@ -114,9 +114,9 @@ function createPrerenderPassthroughFn(
     }
     if (!isPassthroughRoute) {
       throw new Error(
-        "ctx.passthrough() is only available on routes declared with " +
-          "{ passthrough: true }. Remove the passthrough() call or add " +
-          "{ passthrough: true } to the Prerender options.",
+        "ctx.passthrough() is only available on routes wrapped with " +
+          "Passthrough(). Remove the passthrough() call or wrap the " +
+          "Prerender definition with Passthrough(prerenderDef, liveHandler).",
       );
     }
     return PRERENDER_PASSTHROUGH;
@@ -166,9 +166,24 @@ export function createReverseFunction(
       : hrefParams;
 
     // Substitute params (strip constraint and optional syntax: :param(a|b)? -> value)
+    // Optional params (:param?) are omitted when not provided
     if (effectiveParams) {
+      let hadOmittedOptional = false;
+      // First pass: optional params (trailing ?)
       result = result.replace(
-        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?\??/g,
+        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
+        (_, key) => {
+          const value = effectiveParams[key];
+          if (value === undefined) {
+            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 = effectiveParams[key];
           if (value === undefined) {
@@ -177,6 +192,13 @@ export function createReverseFunction(
           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
@@ -207,7 +229,7 @@ export function createHandlerContext<TEnv>(
   // Get variables from request context - this is the unified context
   // shared between middleware and route handlers
   const requestContext = _getRequestContext();
-  const variables: any = requestContext?.var ?? {};
+  const variables: any = requestContext?._variables ?? {};
 
   // If route has a search schema, parse URLSearchParams into typed object
   const searchSchema = routeName ? getSearchSchema(routeName) : undefined;
@@ -250,6 +272,7 @@ export function createHandlerContext<TEnv>(
   ctx = {
     params,
     build: false,
+    dev: false,
     request,
     searchParams,
     search: searchSchema ? resolvedSearchParams : {},
@@ -257,7 +280,7 @@ export function createHandlerContext<TEnv>(
     url,
     originalUrl: new URL(request.url),
     env: bindings,
-    var: variables,
+    _variables: variables,
     get: ((keyOrVar: any) => {
       // Read-time guard: non-cacheable var inside cache() → throw.
       // Works for both ContextVar tokens and string keys.
@@ -320,7 +343,7 @@ export function createHandlerContext<TEnv>(
  *
  * Returns an InternalHandlerContext where params, pathname, url, searchParams,
  * search, reverse, and use(handle) work. Request-time properties
- * (request, env, headers, cookies, var, get, set, res) throw with a clear error.
+ * (request, env, headers, cookies, get, set, res) throw with a clear error.
  */
 export function createPrerenderContext<TEnv>(
   params: Record<string, string>,
@@ -329,6 +352,8 @@ export function createPrerenderContext<TEnv>(
   routeName?: string,
   buildVars?: Record<string, any>,
   isPassthroughRoute?: boolean,
+  buildEnv?: TEnv,
+  devMode?: boolean,
 ): InternalHandlerContext<any, TEnv> {
   const syntheticUrl = new URL(`http://prerender${pathname}`);
   const variables = buildVars ?? {};
@@ -343,6 +368,7 @@ export function createPrerenderContext<TEnv>(
   return {
     params,
     build: true,
+    dev: devMode ?? false,
     get request(): Request {
       return throwUnavailable("request");
     },
@@ -352,11 +378,13 @@ export function createPrerenderContext<TEnv>(
     url: syntheticUrl,
     originalUrl: syntheticUrl,
     get env(): TEnv {
-      return throwUnavailable("env");
-    },
-    get var(): any {
-      return throwUnavailable("var");
+      if (buildEnv !== undefined) return buildEnv;
+      throw new Error(
+        "ctx.env is not available during pre-rendering. " +
+          "Configure buildEnv in your rango() plugin options to enable build-time env access.",
+      );
     },
+    _variables: variables,
     get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
     set: ((keyOrVar: any, value: any) => {
       contextSet(variables, keyOrVar, value);
@@ -402,6 +430,8 @@ export function createPrerenderContext<TEnv>(
 export function createStaticContext<TEnv>(
   routeMap: Record<string, string>,
   routeName?: string,
+  buildEnv?: TEnv,
+  devMode?: boolean,
 ): InternalHandlerContext<any, TEnv> {
   const variables: Record<string, any> = {};
 
@@ -417,6 +447,7 @@ export function createStaticContext<TEnv>(
       return throwUnavailable("params");
     },
     build: true,
+    dev: devMode ?? false,
     get request(): Request {
       return throwUnavailable("request");
     },
@@ -436,11 +467,13 @@ export function createStaticContext<TEnv>(
       return throwUnavailable("originalUrl");
     },
     get env(): TEnv {
-      return throwUnavailable("env");
-    },
-    get var(): any {
-      return throwUnavailable("var");
+      if (buildEnv !== undefined) return buildEnv;
+      throw new Error(
+        "ctx.env is not available in Static() handlers. " +
+          "Configure buildEnv in your rango() plugin options to enable build-time env access.",
+      );
     },
+    _variables: variables,
     get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
     set: ((keyOrVar: any, value: any) => {
       contextSet(variables, keyOrVar, value);

package/src/router/intercept-resolution.ts

@@ -11,7 +11,11 @@ import type {
   InterceptEntry,
   InterceptSelectorContext,
 } from "../server/context";
-import type { HandlerContext, ResolvedSegment } from "../types";
+import type {
+  HandlerContext,
+  InternalHandlerContext,
+  ResolvedSegment,
+} from "../types";
 import { evaluateRevalidation } from "./revalidation.js";
 import { getRequestContext } from "../server/request-context.js";
 import { executeInterceptMiddleware } from "./middleware.js";
@@ -20,6 +24,7 @@ import { getGlobalRouteMap } from "../route-map-builder.js";
 import { handleHandlerResult } from "./segment-resolution.js";
 import type { SegmentResolutionDeps } from "./types.js";
 import { debugLog } from "./logging.js";
+import { runInsideLoaderScope } from "../server/context.js";
 
 /**
  * Check if an intercept's when conditions are satisfied.
@@ -133,7 +138,7 @@ export async function resolveInterceptEntry<TEnv>(
       context.request,
       context.env,
       params,
-      context.var as Record<string, any>,
+      (context as InternalHandlerContext<any, TEnv>)._variables,
       requestCtx.res,
       createReverseFunction(getGlobalRouteMap()),
     );
@@ -207,7 +212,7 @@ export async function resolveInterceptEntry<TEnv>(
     loaderIds.push(loader.$$id);
     loaderPromises.push(
       deps.wrapLoaderPromise(
-        context.use(loader),
+        runInsideLoaderScope(() => context.use(loader)),
         parentEntry,
         segmentId,
         context.pathname,
@@ -374,7 +379,7 @@ export async function resolveInterceptLoadersOnly<TEnv>(
     loaderIds.push(loader.$$id);
     loaderPromises.push(
       deps.wrapLoaderPromise(
-        context.use(loader),
+        runInsideLoaderScope(() => context.use(loader)),
         parentEntry,
         segmentId,
         context.pathname,

package/src/router/loader-resolution.ts

@@ -20,10 +20,11 @@ import type {
   ErrorInfo,
 } from "../types";
 import type { LoaderRevalidationResult, ActionContext } from "./types";
-import { isHandle, type Handle } from "../handle.js";
-import type { HandleStore } from "../server/handle-store.js";
+import { isHandle, collectHandleData, type Handle } from "../handle.js";
+import { buildHandleSnapshot } from "../server/handle-store.js";
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
 import { _getRequestContext } from "../server/request-context.js";
+import { isInsideLoaderScope } from "../server/context.js";
 import { debugLog } from "./logging.js";
 
 /**
@@ -242,6 +243,16 @@ function createLoaderExecutor<TEnv>(
     pendingLoaders.add(loader.$$id);
 
     const currentLoaderId = loader.$$id;
+    const variables = (ctx as InternalHandlerContext<any, TEnv>)._variables;
+
+    // Capture whether this loader is being started from a DSL loader scope
+    // (runInsideLoaderScope in fresh.ts). Handler-invoked loaders are NOT
+    // inside loader scope. This determines whether rendered() is allowed.
+    const isDslLoader = isInsideLoaderScope();
+
+    let renderedResolved = false;
+    let renderedPromise: Promise<void> | null = null;
+
     // Loader functions are always fresh (never cached), so they get an
     // unguarded get that bypasses non-cacheable read guards. This applies
     // to ALL loaders — DSL and handler-called — because the loader
@@ -256,16 +267,86 @@ function createLoaderExecutor<TEnv>(
       pathname: ctx.pathname,
       url: ctx.url,
       env: ctx.env,
-      var: ctx.var,
-      get: ((keyOrVar: any) => contextGet(ctx.var, keyOrVar)) as typeof ctx.get,
-      use: <TDep, TDepParams = any>(
-        dep: LoaderDefinition<TDep, TDepParams>,
-      ): Promise<TDep> => {
-        return useLoader(dep, currentLoaderId);
-      },
+      get: ((keyOrVar: any) =>
+        contextGet(variables, keyOrVar)) as typeof ctx.get,
+      use: ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
+        if (isHandle(item)) {
+          if (!renderedResolved) {
+            throw new Error(
+              `ctx.use(handle) in a loader requires "await ctx.rendered()" first. ` +
+                `Handle "${item.$$id}" cannot be read until the render tree has settled.`,
+            );
+          }
+          const reqCtx = reqCtxRef ?? _getRequestContext();
+          if (!reqCtx) {
+            throw new Error(
+              `ctx.use(handle) failed: request context not available.`,
+            );
+          }
+          const segmentOrder = reqCtx._renderBarrierSegmentOrder ?? [];
+          const snapshot =
+            reqCtx._renderBarrierHandleSnapshot ??
+            buildHandleSnapshot(reqCtx._handleStore, segmentOrder);
+          return collectHandleData(item, snapshot, segmentOrder);
+        }
+
+        // Loader case
+        return useLoader(item as LoaderDefinition<any, any>, currentLoaderId);
+      }) as LoaderContext["use"],
       method: "GET",
       body: undefined,
       reverse: ctx.reverse as LoaderContext["reverse"],
+      rendered: (): Promise<void> => {
+        // Guard: only DSL loaders may use rendered()
+        if (!isDslLoader) {
+          throw new Error(
+            `ctx.rendered() is only available in DSL loaders (registered via loader() in urls()). ` +
+              `Handler-invoked loaders (ctx.use(Loader) inside a handler) cannot use rendered().`,
+          );
+        }
+
+        // Guard: reject streaming trees
+        const reqCtx = reqCtxRef ?? _getRequestContext();
+        if (reqCtx?._treeHasStreaming) {
+          throw new Error(
+            `ctx.rendered() is not supported when the matched route tree uses loading(). ` +
+              `Streaming handlers may not have settled when rendered() resolves. ` +
+              `Remove loading() from the route tree or restructure to avoid rendered().`,
+          );
+        }
+
+        if (renderedPromise) return renderedPromise;
+
+        if (!reqCtx) {
+          throw new Error(
+            `ctx.rendered() failed: request context not available.`,
+          );
+        }
+
+        // Bidirectional deadlock check: if a handler already started
+        // awaiting this loader, calling rendered() would deadlock.
+        if (reqCtx._handlerLoaderDeps?.has(currentLoaderId)) {
+          throw new Error(
+            `Deadlock: loader "${currentLoaderId}" called ctx.rendered() but a handler ` +
+              `is already awaiting this loader via ctx.use(). The handler blocks ` +
+              `segment resolution, which blocks the barrier, which blocks this loader. ` +
+              `Move the data dependency to a loader-to-loader pattern instead.`,
+          );
+        }
+
+        // Register this loader as waiting for the barrier so that
+        // setupLoaderAccess can detect deadlocks when a handler
+        // tries to await the same loader via ctx.use().
+        if (!reqCtx._renderBarrierWaiters) {
+          reqCtx._renderBarrierWaiters = new Set();
+        }
+        reqCtx._renderBarrierWaiters.add(currentLoaderId);
+
+        renderedPromise = reqCtx._renderBarrier.then(() => {
+          renderedResolved = true;
+        });
+        return renderedPromise;
+      },
     };
 
     const doneLoader = track(`loader:${loader.$$id}`, 2);
@@ -296,15 +377,22 @@ export function setupLoaderAccess<TEnv>(
   ctx: HandlerContext<any, TEnv>,
   loaderPromises: Map<string, Promise<any>>,
 ): void {
-  // Eagerly capture the HandleStore at setup time (before pipeline async ops).
-  // In workerd/Cloudflare, dynamic imports and fetch() in the match pipeline
-  // can disrupt AsyncLocalStorage, causing getRequestContext() to return
-  // undefined when handlers later call ctx.use(handle). Capturing early
-  // ensures the store reference survives ALS disruption.
-  const handleStoreRef = _getRequestContext()?._handleStore;
+  // Eagerly capture the request context and HandleStore at setup time
+  // (before pipeline async ops). In workerd/Cloudflare, dynamic imports and
+  // fetch() in the match pipeline can disrupt AsyncLocalStorage, causing
+  // getRequestContext() to return undefined when handlers later call
+  // ctx.use(handle). Capturing early ensures references survive ALS disruption.
+  const reqCtxRef = _getRequestContext();
+  const handleStoreRef = reqCtxRef?._handleStore;
 
   const useLoader = createLoaderExecutor(ctx, loaderPromises);
 
+  // Track whether we're inside a handle push callback. Loaders started
+  // from push callbacks (e.g. push(async () => ctx.use(Loader))) do NOT
+  // block segment resolution, so they must not be registered as handler
+  // dependencies for deadlock detection.
+  let insideHandlePush = false;
+
   ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
     if (isHandle(item)) {
       const handle = item;
@@ -324,16 +412,57 @@ export function setupLoaderAccess<TEnv>(
       ) => {
         if (!store) return;
 
-        const valueOrPromise =
-          typeof dataOrFn === "function"
-            ? (dataOrFn as () => Promise<unknown>)()
-            : dataOrFn;
+        if (typeof dataOrFn === "function") {
+          // Mark scope so ctx.use(loader) calls inside the callback
+          // are not registered as handler-to-loader deps.
+          insideHandlePush = true;
+          try {
+            const result = (dataOrFn as () => Promise<unknown>)();
+            store.push(handle.$$id, segmentId, result);
+          } finally {
+            insideHandlePush = false;
+          }
+          return;
+        }
 
-        store.push(handle.$$id, segmentId, valueOrPromise);
+        store.push(handle.$$id, segmentId, dataOrFn);
       };
     }
 
-    return useLoader(item as LoaderDefinition<any, any>, null);
+    // Deadlock guard and handler-to-loader dependency tracking.
+    // Skip when inside a DSL loader scope (resolveLoaderData also calls
+    // ctx.use() but that's DSL-to-DSL, not handler-to-loader) or when
+    // inside a handle push callback (push callbacks don't block segment
+    // resolution so they can't cause rendered() deadlocks).
+    const loader = item as LoaderDefinition<any, any>;
+    if (!isInsideLoaderScope() && !insideHandlePush) {
+      const reqCtx = reqCtxRef ?? _getRequestContext();
+      if (reqCtx) {
+        // Direction 1: handler awaits loader that already called rendered()
+        if (
+          loaderPromises.has(loader.$$id) &&
+          reqCtx._renderBarrierWaiters?.has(loader.$$id)
+        ) {
+          throw new Error(
+            `Deadlock: handler is awaiting loader "${loader.$$id}" which called ctx.rendered(). ` +
+              `The loader is waiting for segment resolution, but the handler blocks resolution. ` +
+              `Move the data dependency to a loader-to-loader pattern instead.`,
+          );
+        }
+        // Direction 2: track dep so rendered() can detect the deadlock
+        // if the loader calls it later. Skip when the barrier has already
+        // resolved — no deadlock is possible (rendered() resolves immediately).
+        // _renderBarrierSegmentOrder is undefined before resolution, string[]
+        // after. This also prevents false positives from handle push callbacks
+        // that resume after their first await (post-barrier-resolution).
+        if (reqCtx._renderBarrierSegmentOrder === undefined) {
+          if (!reqCtx._handlerLoaderDeps) reqCtx._handlerLoaderDeps = new Set();
+          reqCtx._handlerLoaderDeps.add(loader.$$id);
+        }
+      }
+    }
+
+    return useLoader(loader, null);
   }) as typeof ctx.use;
 }