@rangojs/router 0.5.1 → 0.5.2

package/src/cache/segment-codec.ts

@@ -18,6 +18,12 @@ import {
 } from "@vitejs/plugin-rsc/rsc";
 import { createFromReadableStream } from "@vitejs/plugin-rsc/rsc";
 
+// Preserve embedded server references on a cache/prerender HIT so they
+// re-serialize to the client instead of resolving to a raw function React
+// refuses to pass to a Client Component. Shared across the deserialize sites so
+// the decode policy has a single owner.
+const PRESERVE_SERVER_REFS = { preserveServerReferences: true } as const;
+
 /**
  * Convert a ReadableStream to a string.
  */
@@ -81,7 +87,11 @@ export async function rscDeserialize<T>(
 
   const temporaryReferences = createTemporaryReferenceSet();
   const stream = stringToStream(encoded);
-  return createFromReadableStream<T>(stream, { temporaryReferences });
+  return createFromReadableStream<T>(
+    stream,
+    { temporaryReferences },
+    PRESERVE_SERVER_REFS,
+  );
 }
 
 /**
@@ -116,7 +126,11 @@ export async function serializeResult(value: unknown): Promise<string | null> {
 export async function deserializeResult<T>(encoded: string): Promise<T> {
   const temporaryReferences = createTemporaryReferenceSet();
   const stream = stringToStream(encoded);
-  return createFromReadableStream<T>(stream, { temporaryReferences });
+  return createFromReadableStream<T>(
+    stream,
+    { temporaryReferences },
+    PRESERVE_SERVER_REFS,
+  );
 }
 
 /**
@@ -271,9 +285,11 @@ export async function deserializeSegments(
 
       const [component, layout, loaderData, loaderDataPromise, loadingData] =
         await Promise.all([
-          createFromReadableStream(stringToStream(item.encoded), {
-            temporaryReferences,
-          }),
+          createFromReadableStream(
+            stringToStream(item.encoded),
+            { temporaryReferences },
+            PRESERVE_SERVER_REFS,
+          ),
           rscDeserialize(item.encodedLayout),
           rscDeserialize(item.encodedLoaderData),
           rscDeserialize(item.encodedLoaderDataPromise),

package/src/handles/is-thenable.ts

@@ -1,8 +1,6 @@
 /**
- * Single thenable predicate for the resolve-by-default handle machinery
- * (`handles/deferred-resolution.ts`, its sole owner) — it decides which top-level
- * handle entries are deferred (`Promise`) values to await before any consumer
- * sees them, and which pass through verbatim.
+ * Shared thenable predicate for framework orchestration. It decides which values
+ * participate in promise lifecycles and which pass through synchronously.
  *
  * Requires a CALLABLE `then` (`typeof obj.then === "function"`), not merely a
  * `"then" in obj` membership check, so a non-promise carrying a `then` field

package/src/router/match-middleware/cache-lookup.ts

@@ -450,21 +450,30 @@ export function withCacheLookup<TEnv>(
       resolveLoadersOnly,
     } = getRouterContext<TEnv>();
 
-    if (
-      !ctx.isAction &&
-      prerenderStoreShortCircuits(ctx.matched.pr, ctx.request)
-    ) {
-      await ensurePrerenderDeps();
-      if (prerenderStoreInstance) {
-        const served = yield* tryPrerenderLookup(
-          ctx,
-          state,
-          pipelineStart,
-          pipelineReqCtx,
-          resolveLoadersOnly,
-          resolveLoadersOnlyWithRevalidation,
-        );
-        if (served) return;
+    if (prerenderStoreShortCircuits(ctx.matched.pr, ctx.request)) {
+      // Actions normally re-render fresh and skip the prerender store. But a pure
+      // Prerender route's handler is evicted at build, so there is no fresh
+      // handler to run on an action re-render -- without the fallback the
+      // re-render falls through to the evicted handler and throws "No prerender
+      // data found". Serve the prerendered entry instead (the action ran already;
+      // its result is applied client-side via useActionState). Passthrough routes
+      // keep a liveHandler, so they still re-render fresh on actions.
+      const isPassthroughPrerenderRoute = ctx.entries.some(
+        (entry) => entry.type === "route" && entry.isPassthrough === true,
+      );
+      if (!ctx.isAction || !isPassthroughPrerenderRoute) {
+        await ensurePrerenderDeps();
+        if (prerenderStoreInstance) {
+          const served = yield* tryPrerenderLookup(
+            ctx,
+            state,
+            pipelineStart,
+            pipelineReqCtx,
+            resolveLoadersOnly,
+            resolveLoadersOnlyWithRevalidation,
+          );
+          if (served) return;
+        }
       }
     }
 

package/src/rsc/handler.ts

@@ -110,6 +110,7 @@ import {
   type RequestPlan,
   type ExecutableRequestPlan,
 } from "../router/request-classification.js";
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 
 /**
  * Create an RSC request handler.
@@ -247,7 +248,8 @@ export function createRSCHandler<
     actionId?: string,
   ): Promise<Response> {
     const timeoutError = new RouterTimeoutError(phase, durationMs);
-    const cursor = _getRequestContext<TEnv>()?._renderForeground;
+    const requestContext = _getRequestContext<TEnv>();
+    const cursor = requestContext?._renderForeground;
     const render: RenderTimeoutContext | undefined =
       phase === "render-start" && cursor
         ? {
@@ -261,11 +263,29 @@ export function createRSCHandler<
             }),
           }
         : undefined;
+    const trace =
+      phase === "render-start" ? requestContext?._activeRoutine : undefined;
+    const activeEntries = trace?.active() ?? [];
+    const activeStep = activeEntries.at(-1);
+    const activeAt = performance.now();
+    const routineSnapshot =
+      trace && activeStep
+        ? {
+            name: trace.name,
+            path: activeEntries.map((entry) => entry.name),
+            durationMs: activeAt - activeStep.startedAt,
+          }
+        : undefined;
+
+    if (INTERNAL_RANGO_DEBUG && trace && activeStep) {
+      console.log(
+        `[routine] TIMEOUT ${request.method} ${url.pathname} (${trace.name})\n${trace.formatActive(activeEntries, activeAt)}`,
+      );
+    }
 
-    // Each surface gets its OWN shallow copy of the snapshot. onError, telemetry,
-    // and onTimeout are independent consumers; a consumer that mutates its
-    // `render` (e.g. an onError redacting metadata) must not corrupt what the
-    // other two observe.
+    // Each surface gets its OWN shallow render snapshot. A consumer that mutates
+    // its copy must not corrupt what the other two observe. The internal-debug
+    // routine snapshot is bounded metadata sent only to onError.
     callOnError(timeoutError, phase === "action" ? "action" : "handler", {
       request,
       url,
@@ -278,6 +298,7 @@ export function createRSCHandler<
         phase,
         durationMs,
         ...(render && { render: { ...render } }),
+        ...(routineSnapshot && { routine: routineSnapshot }),
       },
     });
 

package/src/rsc/helpers.ts

@@ -7,6 +7,7 @@
 import {
   _getRequestContext,
   getLocationState,
+  setRequestContextParams,
 } from "../server/request-context.js";
 import type { RequestContext } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
@@ -23,6 +24,7 @@ import {
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
 import { formatCacheSignalHeader } from "../router/telemetry.js";
 import type { RscPayload } from "./types.js";
+import type { HandlerContext } from "./handler-context.js";
 
 /**
  * DEVELOPMENT/TEST ONLY. When the debug cache signal gate is on,
@@ -381,3 +383,14 @@ export function finalizeResponse(response: Response): Response {
   if (!ctx) return response;
   return drainOnResponseCallbacks(ctx, response);
 }
+
+/** Match and stamp params/routeName on the request context as one operation. */
+export async function matchAndRecordParams<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+): Promise<Awaited<ReturnType<HandlerContext<TEnv>["router"]["match"]>>> {
+  const match = await ctx.router.match(request, { env });
+  setRequestContextParams(match.params, match.routeName);
+  return match;
+}

package/src/rsc/progressive-enhancement.ts

@@ -22,12 +22,23 @@ import {
   finalizeResponse,
   buildRouteMiddlewareEntries,
 } from "./helpers.js";
-import { renderRscResponse } from "./render-pipeline.js";
+import {
+  createRenderStageTraceBridge,
+  renderRscResponse,
+} from "./render-pipeline.js";
+import {
+  createRoutineTrace,
+  runRoutine,
+  step,
+  type RoutinePlan,
+  type RoutineTrace,
+} from "./routine-plan.js";
 import type { HandlerContext } from "./handler-context.js";
 import {
   extractRedirectResponse,
   warnNonRedirectPeResponse,
 } from "./runtime-warnings.js";
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 
 export interface PeRouteMiddlewareInfo {
   routeMiddleware?: Array<{
@@ -61,6 +72,40 @@ export async function handleProgressiveEnhancement<TEnv>(
     return null;
   }
 
+  // Flow trace: shared by every plan this request drives (error-boundary
+  // renders and the re-render), so a PE request prints ONE tree. A non-PE form
+  // POST (no $ACTION fields) drives no plan and stays silent.
+  const trace = INTERNAL_RANGO_DEBUG ? createRoutineTrace("pe") : undefined;
+  try {
+    return await handleProgressiveEnhancementInner(
+      ctx,
+      request,
+      env,
+      url,
+      handleStore,
+      nonce,
+      routeMwInfo,
+      trace,
+    );
+  } finally {
+    if (trace && trace.entries.length > 0) {
+      console.log(
+        `[routine] ${request.method} ${url.pathname} (${trace.name})\n${trace.format()}`,
+      );
+    }
+  }
+}
+
+async function handleProgressiveEnhancementInner<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
+  nonce: string | undefined,
+  routeMwInfo: PeRouteMiddlewareInfo | undefined,
+  trace: RoutineTrace | undefined,
+): Promise<Response | null> {
   // Clone the request to read FormData without consuming it.
   // Wrap in try-catch so malformed POST bodies are reported as action
   // errors, not routing errors from the outer catch in handler.ts.
@@ -77,6 +122,7 @@ export async function handleProgressiveEnhancement<TEnv>(
       error,
       handleStore,
       nonce,
+      trace,
     );
     if (errorHtml) {
       ctx.callOnError(error, "action", {
@@ -154,6 +200,7 @@ export async function handleProgressiveEnhancement<TEnv>(
         error,
         handleStore,
         nonce,
+        trace,
         useActionStateId,
         true, // an action ran and threw
       );
@@ -208,6 +255,7 @@ export async function handleProgressiveEnhancement<TEnv>(
         error,
         handleStore,
         nonce,
+        trace,
         directActionId,
         true, // an action ran and threw
       );
@@ -287,79 +335,20 @@ export async function handleProgressiveEnhancement<TEnv>(
     peReqCtx._gateActionResult = actionResult;
     peReqCtx._gateFormData = formData;
 
-    const match = await ctx.router.match(renderRequest, { env });
-
-    if (match.redirect) {
-      return createResponseWithMergedHeaders(null, {
-        status: 308,
-        headers: { Location: match.redirect },
-      });
-    }
-
-    const payload: RscPayload = {
-      metadata: {
-        pathname: url.pathname,
-        routerId: ctx.router.id,
-        basename: ctx.router.basename,
-        segments: gateTransitions(
-          match.segments,
-          getRequestContext(),
-          ctx.router.onError,
-        ),
-        matched: match.matched,
-        diff: match.diff,
-        resolvedIds: match.resolvedIds,
-        params: match.params,
-        isPartial: false,
-        rootLayout: ctx.router.rootLayout,
-        // PE full render: resolve deferred handle values server-side.
-        handles: resolvedHandleStream(handleStore),
-        version: ctx.version,
-        stateCookieName: ctx.router.resolvedStateCookieName,
-        themeConfig: ctx.router.themeConfig,
-        warmupEnabled: ctx.router.warmupEnabled,
-        strictMode: ctx.router.strictMode,
-        initialTheme: getRequestContext().theme,
-      },
-    };
-
-    const stageTracking = {
-      mode: "progressive-enhancement" as const,
-      routeKey: getRequestContext()._routeName,
-      actionId: directActionId ?? undefined,
-    };
-    return renderRscResponse(
-      {
+    return runRoutine(
+      peRenderPlan({
         ctx,
         request,
         env,
         url,
-        payload,
-        init: {
-          // boundarylessErrorStatus is set only when the action threw and no error
-          // boundary matched; it makes the re-render carry 500 like the JS path.
-          // The redirect branch above returns before this, so a redirect re-render
-          // keeps its 308 and is never overridden.
-          ...(boundarylessErrorStatus !== undefined
-            ? { status: boundarylessErrorStatus }
-            : {}),
-          headers: { "content-type": "text/html;charset=utf-8" },
-        },
-        tracking: stageTracking,
-      },
-      {
-        // metricsStore=undefined is safe: the handler already stashed the early
-        // SSR setup promise, so this reuses it instead of starting setup again.
-        // reactFormState travels through the SSR option, not RscPayload.
-        html: createSsrHtmlStage({
-          ctx,
-          request,
-          env,
-          url,
-          metricsStore: undefined,
-          render: { formState: reactFormState, nonce },
-        }),
-      },
+        renderRequest,
+        handleStore,
+        nonce,
+        reactFormState,
+        boundarylessErrorStatus,
+        directActionId,
+      }),
+      { trace, owner: getRequestContext() },
     );
   };
 
@@ -382,6 +371,142 @@ export async function handleProgressiveEnhancement<TEnv>(
   return renderPage();
 }
 
+interface PeRenderInput<TEnv> {
+  ctx: HandlerContext<TEnv>;
+  request: Request;
+  env: TEnv;
+  url: URL;
+  renderRequest: Request;
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"];
+  nonce: string | undefined;
+  reactFormState: ReactFormState | null;
+  boundarylessErrorStatus: number | undefined;
+  directActionId: string | null;
+}
+
+/** PE re-render: match the bodyless GET mirror, then render full HTML. */
+function* peRenderPlan<TEnv>(
+  input: PeRenderInput<TEnv>,
+): RoutinePlan<Response> {
+  const { ctx, env, renderRequest } = input;
+
+  const match = yield* step("match", () =>
+    ctx.router.match(renderRequest, { env }),
+  );
+
+  if (match.redirect) {
+    return createResponseWithMergedHeaders(null, {
+      status: 308,
+      headers: { Location: match.redirect },
+    });
+  }
+
+  return yield* step("render", () => renderPeResponse(input, match));
+}
+
+/** Build the PE full-document payload and render it through the stage driver. */
+function renderPeResponse<TEnv>(
+  input: PeRenderInput<TEnv>,
+  match: Awaited<ReturnType<HandlerContext<TEnv>["router"]["match"]>>,
+): Promise<Response> {
+  const {
+    ctx,
+    request,
+    env,
+    url,
+    handleStore,
+    nonce,
+    reactFormState,
+    boundarylessErrorStatus,
+    directActionId,
+  } = input;
+
+  const payload: RscPayload = {
+    metadata: {
+      pathname: url.pathname,
+      routerId: ctx.router.id,
+      basename: ctx.router.basename,
+      segments: gateTransitions(
+        match.segments,
+        getRequestContext(),
+        ctx.router.onError,
+      ),
+      matched: match.matched,
+      diff: match.diff,
+      resolvedIds: match.resolvedIds,
+      params: match.params,
+      isPartial: false,
+      rootLayout: ctx.router.rootLayout,
+      // PE full render: resolve deferred handle values server-side.
+      handles: resolvedHandleStream(handleStore),
+      version: ctx.version,
+      stateCookieName: ctx.router.resolvedStateCookieName,
+      themeConfig: ctx.router.themeConfig,
+      warmupEnabled: ctx.router.warmupEnabled,
+      strictMode: ctx.router.strictMode,
+      initialTheme: getRequestContext().theme,
+    },
+  };
+
+  const trace = getRequestContext()._activeRoutine;
+
+  const stageTracking = {
+    mode: "progressive-enhancement" as const,
+    routeKey: getRequestContext()._routeName,
+    actionId: directActionId ?? undefined,
+    onEvent: trace && createRenderStageTraceBridge(trace),
+  };
+  return renderRscResponse(
+    {
+      ctx,
+      request,
+      env,
+      url,
+      payload,
+      init: {
+        // boundarylessErrorStatus is set only when the action threw and no error
+        // boundary matched; it makes the re-render carry 500 like the JS path.
+        // The redirect branch in peRenderPlan returns before this, so a redirect
+        // re-render keeps its 308 and is never overridden.
+        ...(boundarylessErrorStatus !== undefined
+          ? { status: boundarylessErrorStatus }
+          : {}),
+        headers: { "content-type": "text/html;charset=utf-8" },
+      },
+      tracking: stageTracking,
+    },
+    {
+      // metricsStore=undefined is safe: the handler already stashed the early
+      // SSR setup promise, so this reuses it instead of starting setup again.
+      // reactFormState travels through the SSR option, not RscPayload.
+      html: createSsrHtmlStage({
+        ctx,
+        request,
+        env,
+        url,
+        metricsStore: undefined,
+        render: { formState: reactFormState, nonce },
+      }),
+    },
+  );
+}
+
+interface PeErrorBoundaryInput<TEnv> {
+  ctx: HandlerContext<TEnv>;
+  request: Request;
+  env: TEnv;
+  url: URL;
+  error: unknown;
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"];
+  nonce: string | undefined;
+  actionId: string | null | undefined;
+  actionRan: boolean;
+}
+
+type PeErrorMatch<TEnv> = NonNullable<
+  Awaited<ReturnType<HandlerContext<TEnv>["router"]["matchError"]>>
+>;
+
 /**
  * Attempt to render an error boundary as full HTML for the PE path.
  * Returns null if no error boundary is found (caller falls through to
@@ -395,6 +520,7 @@ async function renderPeErrorBoundary<TEnv>(
   error: unknown,
   handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
   nonce: string | undefined,
+  trace: RoutineTrace | undefined,
   actionId?: string | null,
   // True when an action actually ran and threw (vs a malformed form body, where
   // no action executed). Drives _inActionRevalidation for JS/PE parity — it must
@@ -402,6 +528,44 @@ async function renderPeErrorBoundary<TEnv>(
   // and throw with no $$id (actionId === undefined) yet still be an action error.
   actionRan = false,
 ): Promise<Response | null> {
+  return runRoutine(
+    peErrorBoundaryPlan({
+      ctx,
+      request,
+      env,
+      url,
+      error,
+      handleStore,
+      nonce,
+      actionId,
+      actionRan,
+    }),
+    { trace, owner: getRequestContext() },
+  );
+}
+
+/** PE error boundary: match a boundary for the thrown error, then render it. */
+function* peErrorBoundaryPlan<TEnv>(
+  input: PeErrorBoundaryInput<TEnv>,
+): RoutinePlan<Response | null> {
+  const boundary = yield* step("match:error", () =>
+    matchPeErrorBoundary(input),
+  );
+  if (!boundary) return null;
+  return yield* step("render", () => renderPeErrorResponse(input, boundary));
+}
+
+/**
+ * Match an error boundary for the PE path, owning the reporting protocol:
+ * a matchError failure reports the ORIGINAL error as unhandled and rethrows
+ * the match failure; a miss returns null; a hit reports handled and stamps
+ * params + action gate context before the render.
+ */
+async function matchPeErrorBoundary<TEnv>(
+  input: PeErrorBoundaryInput<TEnv>,
+): Promise<PeErrorMatch<TEnv> | null> {
+  const { ctx, request, env, url, error, actionId, actionRan } = input;
+
   // JS/PE parity for an action-triggered error re-render: a stale
   // `foregroundOnAction` cache entry inside the error boundary must foreground
   // too, exactly as the JS path (revalidateAfterAction sets this unconditionally
@@ -448,6 +612,16 @@ async function renderPeErrorBoundary<TEnv>(
     peErrCtx._gateActionUrl = new URL(url);
   }
 
+  return errorResult;
+}
+
+/** Render the matched PE error boundary as a full HTML document. */
+function renderPeErrorResponse<TEnv>(
+  input: PeErrorBoundaryInput<TEnv>,
+  errorResult: PeErrorMatch<TEnv>,
+): Promise<Response> {
+  const { ctx, request, env, url, handleStore, nonce, actionId } = input;
+
   const payload: RscPayload = {
     metadata: {
       pathname: url.pathname,
@@ -476,10 +650,13 @@ async function renderPeErrorBoundary<TEnv>(
     },
   };
 
+  const trace = getRequestContext()._activeRoutine;
+
   const stageTracking = {
     mode: "progressive-enhancement-error" as const,
     routeKey: getRequestContext()._routeName,
     actionId: actionId ?? undefined,
+    onEvent: trace && createRenderStageTraceBridge(trace),
   };
   return renderRscResponse(
     {