@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/src/router/segment-resolution/static-store.ts

@@ -8,20 +8,41 @@
 import type { ReactNode } from "react";
 import { _getRequestContext } from "../../server/request-context.js";
 import type { StaticStore } from "../../prerender/store.js";
+import type { SegmentHandleData } from "../../cache/types.js";
 
 // Lazy-initialized static store for production Static handler interception.
-// Remains undefined until first check; null means checked but no manifest.
-// When no __STATIC_MANIFEST exists (dev mode), set to null eagerly to avoid
-// the dynamic import() in ensureStaticDeps() which disrupts AsyncLocalStorage
-// in workerd/Cloudflare runtime.
-let _staticStore: StaticStore | null | undefined =
-  typeof globalThis !== "undefined" && globalThis.__STATIC_MANIFEST
-    ? undefined
-    : null;
+// undefined = not yet checked; null = checked, no manifest (dev mode, or an
+// app without Static handlers) — a permanent SYNCHRONOUS fast path: no await
+// may ever run on that path (an await per lookup disrupts AsyncLocalStorage
+// in workerd/Cloudflare runtime).
+//
+// The check happens on the FIRST LOOKUP, not at module eval: the manifest
+// loader global (__loadStaticManifestModule, bundle-postprocess.ts) is
+// assigned by the RSC entry's BODY, which runs after hoisted module imports
+// evaluate this file — an eval-time read here could never see it. The
+// pre-#760 eager `import "./__static-manifest.js"` existed precisely to beat
+// that hoisting; deferring the manifest module keeps its O(#Static handlers)
+// thunk table off the worker's cold-start path.
+let _staticStore: StaticStore | null | undefined = undefined;
 let _deserializeComponent: ((encoded: string) => Promise<unknown>) | undefined;
+let _decodeHandleValue:
+  | typeof import("../../cache/handle-snapshot.js").decodeHandleValue
+  | undefined;
 
 async function ensureStaticDeps(): Promise<void> {
   if (_staticStore === undefined) {
+    // Evaluate the deferred manifest module (it assigns __STATIC_MANIFEST);
+    // support a pre-set __STATIC_MANIFEST too (tests, non-postprocess embeds).
+    if (
+      !globalThis.__STATIC_MANIFEST &&
+      globalThis.__loadStaticManifestModule
+    ) {
+      await globalThis.__loadStaticManifestModule();
+    }
+    if (!globalThis.__STATIC_MANIFEST) {
+      _staticStore = null;
+      return;
+    }
     const { createStaticStore } = await import("../../prerender/store.js");
     _staticStore = createStaticStore();
   }
@@ -29,6 +50,9 @@ async function ensureStaticDeps(): Promise<void> {
     const { deserializeComponent } =
       await import("../../cache/segment-codec.js");
     _deserializeComponent = deserializeComponent;
+    const { decodeHandleValue } =
+      await import("../../cache/handle-snapshot.js");
+    _decodeHandleValue = decodeHandleValue;
   }
 }
 
@@ -45,21 +69,37 @@ export async function tryStaticLookup(
   handlerId: string,
   segmentId: string,
 ): Promise<ReactNode | undefined> {
-  // Fast path: already checked and no manifest available (dev mode or no Static handlers).
-  // Avoids await which can disrupt AsyncLocalStorage in workerd/Cloudflare runtime.
+  // Fast path: no manifest available (dev mode or no Static handlers).
+  // Latched SYNCHRONOUSLY — including on the very first call — so this path
+  // never awaits (an await here disrupts AsyncLocalStorage in
+  // workerd/Cloudflare runtime).
+  if (
+    _staticStore === undefined &&
+    !globalThis.__STATIC_MANIFEST &&
+    !globalThis.__loadStaticManifestModule
+  ) {
+    _staticStore = null;
+  }
   if (_staticStore === null) return undefined;
   await ensureStaticDeps();
   if (!_staticStore || !_deserializeComponent) return undefined;
   const entry = await _staticStore.get(handlerId);
   if (!entry) return undefined;
 
-  // Replay handle data captured during build-time rendering.
-  // The data was keyed by handlerId at build time; replay under segmentId
-  // so it matches the segment order used by useHandle on the client.
-  if (entry.handles && Object.keys(entry.handles).length > 0) {
+  // Replay handle data captured during build-time rendering. entry.handles is a
+  // Flight-encoded string ("" when none) — decode before replay so
+  // Promise/ReactNode handle values are revived. The data was keyed by handlerId
+  // at build time; replay under segmentId so it matches the segment order used
+  // by useHandle on the client.
+  if (entry.handles && _decodeHandleValue) {
     const handleStore = _getRequestContext()?._handleStore;
     if (handleStore) {
-      handleStore.replaySegmentData(segmentId, entry.handles);
+      const segHandles = await _decodeHandleValue<SegmentHandleData>(
+        entry.handles,
+      );
+      if (segHandles) {
+        handleStore.replaySegmentData(segmentId, segHandles);
+      }
     }
   }
 

package/src/router/segment-resolution/streamed-handler-telemetry.ts

@@ -0,0 +1,52 @@
+/**
+ * Streamed Handler Telemetry
+ *
+ * Shared fire-and-forget rejection observer for streamed handler promises,
+ * used by both the fresh and revalidation segment-resolution paths. Lives in
+ * its own module (never mocked) so the resolution unit tests that mock
+ * helpers.js / telemetry.js with explicit export lists do not resolve it to
+ * undefined.
+ */
+
+import type { ReactNode } from "react";
+import { getRouterContext } from "../router-context.js";
+import { resolveSink, safeEmit } from "../telemetry.js";
+
+/**
+ * Attach a fire-and-forget rejection observer to a streamed handler promise.
+ * React catches the actual error via its error boundary; this only emits
+ * the handler.error telemetry event.
+ */
+export function observeStreamedHandler(
+  promise: Promise<ReactNode>,
+  segmentId: string,
+  segmentType: string,
+  pathname?: string,
+  routeKey?: string,
+  params?: Record<string, string>,
+): void {
+  let routerCtx;
+  try {
+    routerCtx = getRouterContext();
+  } catch {
+    return;
+  }
+  if (!routerCtx?.telemetry) return;
+  const sink = resolveSink(routerCtx.telemetry);
+  const reqId = routerCtx.requestId;
+  promise.catch((err: unknown) => {
+    const errorObj = err instanceof Error ? err : new Error(String(err));
+    safeEmit(sink, {
+      type: "handler.error",
+      timestamp: performance.now(),
+      requestId: reqId,
+      segmentId,
+      segmentType,
+      error: errorObj,
+      handledByBoundary: true,
+      pathname,
+      routeKey,
+      params,
+    });
+  });
+}

package/src/router/segment-resolution/view-transition-default.ts

@@ -0,0 +1,60 @@
+/**
+ * View-transition boundary default resolution.
+ *
+ * Kept in its own module (rather than helpers.ts) because several resolution
+ * tests mock helpers.ts with an explicit export list; a shared util here is
+ * never mocked, so the fresh and revalidation paths always get the real
+ * implementation.
+ */
+
+import type { EntryData } from "../../server/context";
+import { getRequestContext } from "../../server/request-context.js";
+
+/**
+ * Resolve a segment's transition config: stamp the `viewTransition` default and
+ * peel off a transition({ when }) predicate.
+ *
+ * `viewTransition`: the per-segment value (set via the transition() DSL) always
+ * wins. When it is unset, the router-level createRouter({ viewTransition })
+ * default is stamped in so the render gate reads the boundary decision off the
+ * segment — server and client, via the serialized segment — without the router
+ * option being threaded to the client. Only `false` is ever stamped; an unset
+ * (or "auto") value is left untouched because it already means "wrap" at the
+ * gate, which also avoids needless object allocation and payload growth.
+ *
+ * `when`: a server-only predicate. It is STRIPPED from the returned config (a
+ * function cannot cross Flight or the segment cache). PPR routes evaluate it
+ * from the manifest before the pipeline; other routes record it here for the
+ * existing post-handler gate. Used by both fresh and revalidation resolution.
+ */
+export function applyViewTransitionDefault(
+  transition: EntryData["transition"],
+  viewTransitionDefault: "auto" | false | undefined,
+  segmentId?: string,
+): EntryData["transition"] {
+  if (!transition) return transition;
+  let result = transition;
+  if (result.when) {
+    if (segmentId !== undefined) {
+      try {
+        const ctx = getRequestContext();
+        if (!ctx._pprTransitionDecisions?.has(segmentId)) {
+          (ctx._transitionWhen ??= []).push({
+            id: segmentId,
+            when: result.when,
+          });
+        }
+      } catch {
+        // No active request context (e.g. a unit test calling this util
+        // directly). Skip collection; the strip below still applies so the
+        // serialized config never carries the function.
+      }
+    }
+    const { when: _when, ...rest } = result;
+    result = rest;
+  }
+  if (result.viewTransition === undefined && viewTransitionDefault === false) {
+    return { ...result, viewTransition: false };
+  }
+  return result;
+}

package/src/router/segment-resolution.ts

@@ -1,5 +1,9 @@
 // Barrel re-export -- see segment-resolution/ for implementations.
-export { handleHandlerResult } from "./segment-resolution/helpers.js";
+export {
+  handleHandlerResult,
+  warnOnStreamedResponse,
+  buildLoaderErrorContext,
+} from "./segment-resolution/helpers.js";
 export {
   resolveLoaders,
   type ResolveSegmentOptions,

package/src/router/segment-wrappers.ts

@@ -5,6 +5,7 @@ import type {
   ShouldRevalidateFn,
 } from "../types";
 import type { SegmentResolutionDeps } from "./types.js";
+import type { ResolveSegmentOptions } from "./segment-resolution.js";
 
 import {
   resolveAllSegments as _resolveAllSegments,
@@ -29,7 +30,7 @@ export interface SegmentWrappers<TEnv = any> {
     params: Record<string, string>,
     context: HandlerContext<any, TEnv>,
     loaderPromises: Map<string, Promise<any>>,
-    options?: { skipLoaders?: boolean },
+    options?: ResolveSegmentOptions,
   ) => Promise<ResolvedSegment[]>;
   resolveLoadersOnly: (
     entries: EntryData[],
@@ -68,7 +69,6 @@ export interface SegmentWrappers<TEnv = any> {
     request: Request,
     prevUrl: URL,
     nextUrl: URL,
-    loaderPromises: Map<string, Promise<any>>,
     actionContext:
       | {
           actionId?: string;
@@ -94,6 +94,7 @@ export interface SegmentWrappers<TEnv = any> {
     context: HandlerContext<any, TEnv>,
     belongsToRoute?: boolean,
     revalidationContext?: any,
+    options?: { skipMiddleware?: boolean },
   ) => Promise<ResolvedSegment[]>;
   resolveInterceptLoadersOnly: (
     interceptEntry: InterceptEntry,
@@ -124,7 +125,7 @@ export function createSegmentWrappers<TEnv = any>(
     params: Record<string, string>,
     context: HandlerContext<any, TEnv>,
     loaderPromises: Map<string, Promise<any>>,
-    options?: { skipLoaders?: boolean },
+    options?: ResolveSegmentOptions,
   ): ReturnType<typeof _resolveAllSegments> {
     return _resolveAllSegments(
       entries,
@@ -192,7 +193,6 @@ export function createSegmentWrappers<TEnv = any>(
     request: Request,
     prevUrl: URL,
     nextUrl: URL,
-    loaderPromises: Map<string, Promise<any>>,
     actionContext:
       | {
           actionId?: string;
@@ -216,7 +216,6 @@ export function createSegmentWrappers<TEnv = any>(
       request,
       prevUrl,
       nextUrl,
-      loaderPromises,
       actionContext,
       interceptResult,
       localRouteName,
@@ -247,6 +246,7 @@ export function createSegmentWrappers<TEnv = any>(
     context: HandlerContext<any, TEnv>,
     belongsToRoute: boolean = true,
     revalidationContext?: any,
+    options?: { skipMiddleware?: boolean },
   ): ReturnType<typeof _resolveInterceptEntry> {
     return _resolveInterceptEntry(
       interceptEntry,
@@ -256,6 +256,7 @@ export function createSegmentWrappers<TEnv = any>(
       belongsToRoute,
       segmentDeps,
       revalidationContext,
+      options,
     );
   }
 

package/src/router/state-cookie-name.ts

@@ -0,0 +1,33 @@
+import { DEFAULT_STATE_COOKIE_PREFIX } from "../browser/cookie-name.js";
+
+/**
+ * Resolve the rango state cookie name once, server-side, at router init. The
+ * resolved string is shipped in payload metadata and the client reads it
+ * verbatim, so composition happens in exactly one place.
+ *
+ * Shape: `{sanitizedPrefix}_{sanitizedRouterId}`. The prefix charset excludes
+ * `_` so the FIRST `_` is always the prefix/routerId boundary; that keeps the
+ * name injective even though a routerId may legitimately contain `_` (the
+ * counter fallback is `router_{n}`). Without that exclusion, prefix
+ * `rango-state` + id `router_0` and prefix `rango-state_router` + id `0` would
+ * both resolve to `rango-state_router_0` and silently share a cache key.
+ */
+
+// Prefix excludes `_` so it can never collide with the separator.
+function sanitizePrefix(prefix: string): string {
+  return prefix.replace(/[^A-Za-z0-9-]/g, "");
+}
+
+// routerId keeps `_` (so `router_0` survives); other illegal chars are dropped.
+function sanitizeRouterId(routerId: string): string {
+  return routerId.replace(/[^A-Za-z0-9_-]/g, "");
+}
+
+export function resolveStateCookieName(
+  prefix: string | undefined,
+  routerId: string,
+): string {
+  const sanitized = sanitizePrefix(prefix ?? DEFAULT_STATE_COOKIE_PREFIX);
+  const finalPrefix = sanitized || DEFAULT_STATE_COOKIE_PREFIX;
+  return `${finalPrefix}_${sanitizeRouterId(routerId)}`;
+}

package/src/router/substitute-pattern-params.ts

@@ -0,0 +1,75 @@
+import { encodePathSegment, encodePathRemainder } from "./url-params.js";
+import { parsePattern } from "./parse-pattern.js";
+
+/**
+ * Substitute `:param` placeholders in a route pattern with values from
+ * `params`, producing a URL. Built by walking the SAME parsed segments the
+ * matcher uses (`parsePattern`) and emitting one piece per segment — so a
+ * substituted value is never re-scanned as if it were another placeholder (a
+ * catch-all value like `sha:abc/x` used to make the "required" pass read `:abc`
+ * and throw). Constraint syntax (`:name(en|gb)`) is stripped; trailing-slash
+ * patterns like `/blog/` are preserved unless an optional segment was omitted.
+ *
+ * Semantics per segment:
+ * - static             -> emitted verbatim.
+ * - `:name`            -> required; `undefined` throws, `""` yields an empty segment.
+ * - `:name?`           -> optional; `undefined`/`""` omitted.
+ * - `:name*` / `:name+`-> catch-all; the value is multi-segment, so each segment
+ *                         is encoded and the `/` separators are preserved. `+`
+ *                         (one-or-more) throws when absent; `*` (and bare `*`)
+ *                         omit when absent.
+ *
+ * Shared by `ctx.reverse()` (server), `createReverse()` (typed runtime
+ * helper), and `useReverse()` (client hook). The behavior must stay
+ * identical across all three call sites.
+ */
+export function substitutePatternParams(
+  pattern: string,
+  params: Record<string, string | undefined>,
+  routeName: string,
+): string {
+  const hasTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+  const normalized = hasTrailingSlash ? pattern.slice(0, -1) : pattern;
+  const segments = parsePattern(normalized);
+
+  const parts: string[] = [];
+  for (const seg of segments) {
+    if (seg.type === "static") {
+      parts.push("/" + seg.value);
+    } else if (seg.type === "wildcard") {
+      const value = params[seg.value];
+      if (value === undefined || value === "") {
+        // `:name+` requires at least one segment; bare `*` / `:name*` collapse.
+        if (seg.oneOrMore) {
+          throw new Error(
+            `Missing param "${seg.value}" for route "${routeName}"`,
+          );
+        }
+      } else {
+        parts.push("/" + encodePathRemainder(value));
+      }
+    } else {
+      // Plain param. Constraint (`seg.constraint`) is intentionally not re-emitted.
+      const value = params[seg.value];
+      const suffix = seg.suffix ?? "";
+      if (seg.optional) {
+        // The matcher omits absent optionals (`undefined`); callers/getParams()
+        // may pass `""` explicitly — treat both as absent.
+        if (value !== undefined && value !== "") {
+          parts.push("/" + encodePathSegment(value) + suffix);
+        }
+      } else {
+        if (value === undefined) {
+          throw new Error(
+            `Missing param "${seg.value}" for route "${routeName}"`,
+          );
+        }
+        parts.push("/" + encodePathSegment(value) + suffix);
+      }
+    }
+  }
+
+  let result = parts.join("") || "/";
+  if (hasTrailingSlash && !result.endsWith("/")) result += "/";
+  return result;
+}