@rangojs/router 0.0.0-experimental.32 → 0.0.0-experimental.3232cd17

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

@@ -8,6 +8,7 @@
 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.
@@ -19,6 +20,9 @@ let _staticStore: StaticStore | null | undefined =
     ? undefined
     : null;
 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) {
@@ -29,6 +33,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;
   }
 }
 
@@ -53,13 +60,20 @@ export async function tryStaticLookup(
   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,36 @@
+/**
+ * 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";
+
+/**
+ * Resolve the effective `viewTransition` for a segment's transition config.
+ *
+ * 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. Used by both the
+ * fresh and revalidation resolution paths.
+ */
+export function applyViewTransitionDefault(
+  transition: EntryData["transition"],
+  viewTransitionDefault: "auto" | false | undefined,
+): EntryData["transition"] {
+  if (!transition) return transition;
+  if (
+    transition.viewTransition === undefined &&
+    viewTransitionDefault === false
+  ) {
+    return { ...transition, viewTransition: false };
+  }
+  return transition;
+}

package/src/router/segment-resolution.ts

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

package/src/router/segment-wrappers.ts

@@ -68,7 +68,6 @@ export interface SegmentWrappers<TEnv = any> {
     request: Request,
     prevUrl: URL,
     nextUrl: URL,
-    loaderPromises: Map<string, Promise<any>>,
     actionContext:
       | {
           actionId?: string;
@@ -192,7 +191,6 @@ export function createSegmentWrappers<TEnv = any>(
     request: Request,
     prevUrl: URL,
     nextUrl: URL,
-    loaderPromises: Map<string, Promise<any>>,
     actionContext:
       | {
           actionId?: string;
@@ -204,6 +202,7 @@ export function createSegmentWrappers<TEnv = any>(
     interceptResult: { intercept: InterceptEntry; entry: EntryData } | null,
     localRouteName: string,
     pathname: string,
+    stale?: boolean,
   ): ReturnType<typeof _resolveAllSegmentsWithRevalidation> {
     return _resolveAllSegmentsWithRevalidation(
       entries,
@@ -215,12 +214,12 @@ export function createSegmentWrappers<TEnv = any>(
       request,
       prevUrl,
       nextUrl,
-      loaderPromises,
       actionContext,
       interceptResult,
       localRouteName,
       pathname,
       segmentDeps,
+      stale,
     );
   }
 

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,56 @@
+import { encodePathSegment } from "./url-params.js";
+
+/**
+ * Substitute `:param` placeholders in a route pattern with values from
+ * `params`. Two-pass: optional params (`:name?`) first so absent values
+ * collapse cleanly, then required params (throws on missing). Constraint
+ * syntax (`:name(en|gb)`) is stripped from the result. Trailing-slash
+ * patterns like `/blog/` are preserved unless an optional segment was
+ * actually omitted.
+ *
+ * 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 {
+  let result = pattern;
+  let hadOmittedOptional = false;
+
+  result = result.replace(
+    /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
+    (_match, key) => {
+      const value = params[key as string];
+      // The matcher omits absent optional params (so `value` is `undefined`
+      // here), but caller-supplied params or `getParams()` shapes may still
+      // pass `""` explicitly. Treat both as the absent form.
+      if (value === undefined || value === "") {
+        hadOmittedOptional = true;
+        return "";
+      }
+      return encodePathSegment(value);
+    },
+  );
+
+  result = result.replace(
+    /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(?!\?)/g,
+    (_match, key) => {
+      const value = params[key as string];
+      if (value === undefined) {
+        throw new Error(`Missing param "${key}" for route "${routeName}"`);
+      }
+      return encodePathSegment(value);
+    },
+  );
+
+  if (hadOmittedOptional) {
+    const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+    result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
+    if (hadTrailingSlash && !result.endsWith("/")) result += "/";
+  }
+
+  return result;
+}

package/src/router/telemetry-otel.ts

@@ -125,10 +125,6 @@ export function createOTelSink(tracer: OTelTracer): TelemetrySink {
   return {
     emit(event: TelemetryEvent): void {
       switch (event.type) {
-        // -----------------------------------------------------------------
-        // Request lifecycle
-        // -----------------------------------------------------------------
-
         case "request.start": {
           const span = tracer.startSpan("rango.request", {
             attributes: {
@@ -169,10 +165,6 @@ export function createOTelSink(tracer: OTelTracer): TelemetrySink {
           break;
         }
 
-        // -----------------------------------------------------------------
-        // Loader lifecycle
-        // -----------------------------------------------------------------
-
         case "loader.start": {
           const span = tracer.startSpan("rango.loader", {
             attributes: {
@@ -231,10 +223,6 @@ export function createOTelSink(tracer: OTelTracer): TelemetrySink {
           break;
         }
 
-        // -----------------------------------------------------------------
-        // Handler errors (instant span)
-        // -----------------------------------------------------------------
-
         case "handler.error": {
           const attrs: Record<string, string | number | boolean> = {
             "rango.handled_by_boundary": event.handledByBoundary,
@@ -257,10 +245,6 @@ export function createOTelSink(tracer: OTelTracer): TelemetrySink {
           break;
         }
 
-        // -----------------------------------------------------------------
-        // Cache decision (instant span)
-        // -----------------------------------------------------------------
-
         case "cache.decision": {
           const attrs: Record<string, string | number | boolean> = {
             "http.route": event.pathname,
@@ -277,10 +261,6 @@ export function createOTelSink(tracer: OTelTracer): TelemetrySink {
           break;
         }
 
-        // -----------------------------------------------------------------
-        // Revalidation decision (instant span)
-        // -----------------------------------------------------------------
-
         case "revalidation.decision": {
           const span = tracer.startSpan("rango.revalidation.decision", {
             attributes: {

package/src/router/telemetry.ts

@@ -14,10 +14,6 @@
  *   - revalidation.decision          (revalidation evaluation)
  */
 
-// ---------------------------------------------------------------------------
-// Event types
-// ---------------------------------------------------------------------------
-
 interface BaseEvent {
   /** Monotonic timestamp from performance.now() */
   timestamp: number;
@@ -90,6 +86,34 @@ export interface HandlerErrorEvent extends BaseEvent {
   params?: Record<string, string>;
 }
 
+/**
+ * Per-segment (or coarse route-level) cache status carried on the
+ * cache.decision telemetry event and the X-Rango-Cache debug header.
+ *
+ * v1 is COARSE: the router's pipeline tracks cache decisions at the
+ * route/entry level (cacheHit/cacheSource/shouldRevalidate), not per
+ * individual segment. The `segments` array therefore contains a single
+ * route-level entry keyed by the route key. The shape is forward-compatible
+ * with genuine per-segment status if the pipeline later exposes it.
+ */
+export type CacheSegmentStatus =
+  | "hit"
+  | "miss"
+  | "stale"
+  | "prerendered"
+  | "passthrough";
+
+export interface CacheSegmentSignal {
+  /** Segment id (v1: the route key, since status is route-level). */
+  id: string;
+  /** Segment type (v1: "route" for the coarse route-level entry). */
+  type: string;
+  /** Resolved cache status for this segment. */
+  cacheStatus: CacheSegmentStatus;
+  /** Whether stale-while-revalidate was triggered for this segment. */
+  shouldRevalidate?: boolean;
+}
+
 export interface CacheDecisionEvent extends BaseEvent {
   type: "cache.decision";
   pathname: string;
@@ -98,6 +122,12 @@ export interface CacheDecisionEvent extends BaseEvent {
   /** Whether stale-while-revalidate was triggered */
   shouldRevalidate: boolean;
   source?: "runtime" | "prerender";
+  /**
+   * Optional per-segment (v1: coarse route-level) cache status. Present only
+   * when telemetry or the debug cache signal is enabled. Optional so existing
+   * sinks are unaffected.
+   */
+  segments?: CacheSegmentSignal[];
 }
 
 export interface RevalidationDecisionEvent extends BaseEvent {
@@ -141,9 +171,70 @@ export type TelemetryEvent =
   | OriginCheckRejectedEvent;
 
 // ---------------------------------------------------------------------------
-// Sink interface
+// Cache signal derivation (coarse, route-level)
 // ---------------------------------------------------------------------------
 
+/**
+ * Derive the coarse, route-level cache status from pipeline cache state.
+ *
+ * v1 mapping (route-level — see CacheSegmentSignal):
+ *   - prerender hit                         -> "prerendered"
+ *   - runtime hit + shouldRevalidate (SWR)  -> "stale"
+ *   - runtime hit                           -> "hit"
+ *   - no hit                                -> "miss"
+ *
+ * Note: "passthrough" is a build-time prerender concept (a route opts out of
+ * being prerendered for some params). At runtime a passthrough route renders
+ * fresh and is indistinguishable from a normal miss in the pipeline state, so
+ * v1 reports it as "miss". The "passthrough" status remains in the type union
+ * for forward compatibility.
+ */
+export function deriveCacheStatus(state: {
+  cacheHit: boolean;
+  cacheSource?: "runtime" | "prerender";
+  shouldRevalidate?: boolean;
+}): CacheSegmentStatus {
+  if (state.cacheHit) {
+    if (state.cacheSource === "prerender") return "prerendered";
+    if (state.shouldRevalidate) return "stale";
+    return "hit";
+  }
+  return "miss";
+}
+
+/**
+ * Build the coarse route-level cache signal array (a single entry keyed by
+ * the route key). Used for both the cache.decision telemetry event and the
+ * X-Rango-Cache debug header.
+ */
+export function buildCacheSignalSegments(
+  routeKey: string,
+  state: {
+    cacheHit: boolean;
+    cacheSource?: "runtime" | "prerender";
+    shouldRevalidate?: boolean;
+  },
+): CacheSegmentSignal[] {
+  return [
+    {
+      id: routeKey,
+      type: "route",
+      cacheStatus: deriveCacheStatus(state),
+      shouldRevalidate: !!state.shouldRevalidate,
+    },
+  ];
+}
+
+/**
+ * Serialize cache signal segments into the X-Rango-Cache header value:
+ * `<segId>=<status>, <segId2>=<status2>`.
+ */
+export function formatCacheSignalHeader(
+  segments: CacheSegmentSignal[],
+): string {
+  return segments.map((s) => `${s.id}=${s.cacheStatus}`).join(", ");
+}
+
 /**
  * Telemetry sink receives structured lifecycle events from the router.
  * Implement this interface to integrate with any observability backend.
@@ -154,10 +245,6 @@ export interface TelemetrySink {
   emit(event: TelemetryEvent): void;
 }
 
-// ---------------------------------------------------------------------------
-// No-op singleton (zero-cost disabled state)
-// ---------------------------------------------------------------------------
-
 const noopSink: TelemetrySink = {
   emit() {},
 };
@@ -185,12 +272,6 @@ export function safeEmit(sink: TelemetrySink, event: TelemetryEvent): void {
   }
 }
 
-// ---------------------------------------------------------------------------
-// Request ID extraction (for span correlation)
-// ---------------------------------------------------------------------------
-
-// Per-request memoization so the same Request object always maps to the
-// same ID. WeakMap allows GC when the Request is no longer referenced.
 const requestIds = new WeakMap<Request, string>();
 let telemetryRequestCounter = 0;
 
@@ -224,10 +305,6 @@ export function getRequestId(request: Request): string {
   return id;
 }
 
-// ---------------------------------------------------------------------------
-// Console sink (built-in, replaces ad-hoc console.log debug traces)
-// ---------------------------------------------------------------------------
-
 /**
  * Built-in console sink that logs events in a structured format.
  * Designed as the default sink for development / debugging.

package/src/router/timeout.ts

@@ -6,10 +6,6 @@
  * a Promise.race mechanism, returning 504 on expiry.
  */
 
-// ---------------------------------------------------------------------------
-// Public types
-// ---------------------------------------------------------------------------
-
 export interface RouterTimeouts {
   /** Timeout for server action execution (ms). */
   actionMs?: number;
@@ -35,10 +31,6 @@ export type OnTimeoutCallback<TEnv = any> = (
   ctx: TimeoutContext<TEnv>,
 ) => Response | Promise<Response>;
 
-// ---------------------------------------------------------------------------
-// Internal resolved form
-// ---------------------------------------------------------------------------
-
 export interface ResolvedTimeouts {
   actionMs: number | undefined;
   renderStartMs: number | undefined;
@@ -63,10 +55,6 @@ export function resolveTimeouts(
   };
 }
 
-// ---------------------------------------------------------------------------
-// Error class
-// ---------------------------------------------------------------------------
-
 export class RouterTimeoutError extends Error {
   override name = "RouterTimeoutError" as const;
   phase: TimeoutPhase;
@@ -81,10 +69,6 @@ export class RouterTimeoutError extends Error {
   }
 }
 
-// ---------------------------------------------------------------------------
-// Race helper
-// ---------------------------------------------------------------------------
-
 type TimeoutResult<T> =
   | { result: T; timedOut: false }
   | { timedOut: true; durationMs: number };
@@ -129,10 +113,6 @@ export async function withTimeout<T>(
   }
 }
 
-// ---------------------------------------------------------------------------
-// Default response
-// ---------------------------------------------------------------------------
-
 /**
  * Create the default 504 response for a timed-out request.
  * Includes `X-Rango-Timeout-Phase` header for observability.