@rangojs/router 0.5.1 → 0.6.0

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(
     {

package/src/rsc/render-pipeline.ts

@@ -7,6 +7,7 @@ import type { RenderMode, RenderPhase } from "../router/timeout.js";
 import type { HandlerContext } from "./handler-context.js";
 import { createResponseWithMergedHeaders } from "./helpers.js";
 import type { RscPayload } from "./types.js";
+import type { RoutineTrace, RoutineTraceEntry } from "./routine-plan.js";
 
 // Canonical unions live in router/timeout.ts (the dependency-free leaf); these
 // aliases keep the render-pipeline names stable for existing importers.
@@ -191,6 +192,34 @@ function expectCommandResult(
   return result.value;
 }
 
+/**
+ * Step helpers: each yields one command and returns its narrowed result, so a
+ * plan body reads imperatively while the yielded value stays the plain command
+ * the driver interprets (yield-before-execute, exact identity — see
+ * docs/design/render-stage-driver.md).
+ */
+function* flightStep<TEnv>(
+  execute: () => RscFlightStage,
+  recordSerializeMetric: boolean,
+): Generator<RscRenderCommand<TEnv>, RscFlightStage, RscRenderCommandResult> {
+  return expectCommandResult(
+    yield { type: "flight", execute, recordSerializeMetric },
+    "flight",
+  );
+}
+
+function* htmlStep<TEnv>(
+  prepare: () => RscPreparedHtmlRender | Promise<RscPreparedHtmlRender>,
+): Generator<RscRenderCommand<TEnv>, RscHtmlResult, RscRenderCommandResult> {
+  return expectCommandResult(yield { type: "html", prepare }, "html");
+}
+
+function* responseStep<TEnv>(
+  execute: () => Response,
+): Generator<RscRenderCommand<TEnv>, Response, RscRenderCommandResult> {
+  return expectCommandResult(yield { type: "response", execute }, "response");
+}
+
 /**
  * Describe the foreground response-construction work without executing it.
  * Each command is yielded before its work starts; the driver owns execution,
@@ -200,36 +229,24 @@ export function* createRscRenderPlan<TEnv>(
   input: RscRenderInput<TEnv>,
   options: RscRenderOptions = {},
 ): RscRenderPlan<TEnv> {
-  const flight = expectCommandResult(
-    yield {
-      type: "flight",
-      recordSerializeMetric: input.recordSerializeMetric ?? true,
-      execute: () => createFlightStage(input, input.init),
-    },
-    "flight",
+  const flight = yield* flightStep<TEnv>(
+    () => createFlightStage(input, input.init),
+    input.recordSerializeMetric ?? true,
   );
 
-  let body: BodyInit | null = flight.stream;
-  let init = input.init;
-
   if (options.html) {
-    const html = expectCommandResult(
-      yield {
-        type: "html",
-        prepare: () => options.html!(flight),
-      },
-      "html",
+    const html = options.html;
+    const page = yield* htmlStep<TEnv>(() => html(flight));
+    return yield* responseStep<TEnv>(() =>
+      createResponseWithMergedHeaders(page.body, {
+        ...input.init,
+        ...page.init,
+      }),
     );
-    body = html.body;
-    init = { ...init, ...html.init };
   }
 
-  return expectCommandResult(
-    yield {
-      type: "response",
-      execute: () => createResponseWithMergedHeaders(body, init),
-    },
-    "response",
+  return yield* responseStep<TEnv>(() =>
+    createResponseWithMergedHeaders(flight.stream, input.init),
   );
 }
 
@@ -546,6 +563,33 @@ export function renderRscFlightStage<TEnv>(
   }
 }
 
+/**
+ * Feed this driver's stage events (flight/html/response) into a routine flow
+ * trace as child entries of the currently running plan step. Stages are
+ * strictly sequential, so one `current` slot suffices. Depth is captured at
+ * creation: the bridge is built while the caller's render step executes, so
+ * children sit one level under it.
+ */
+export function createRenderStageTraceBridge(
+  trace: RoutineTrace,
+): (event: RscRenderStageEvent) => void {
+  const depth = trace.currentDepth() + 1;
+  let current: RoutineTraceEntry | undefined;
+  return (event) => {
+    if (event.type === "stage:start") {
+      current = trace.begin(event.context.phase, "step", depth);
+      return;
+    }
+    if (!current) return;
+    if (event.type === "stage:complete") {
+      trace.end(current);
+    } else {
+      trace.fail(current, event.error);
+    }
+    current = undefined;
+  };
+}
+
 export function createRscStageDebugSink(
   log: (message: string, details?: Record<string, unknown>) => void = (
     message,