@rangojs/router 0.17.0 → 0.18.0

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

@@ -107,6 +107,7 @@ import {
   createShellImplicitDocScope,
   type CacheScope,
 } from "../../cache/cache-scope.js";
+import { ShellRecordUnavailableError } from "../../cache/shell-snapshot.js";
 import { prerenderStoreShortCircuits } from "../navigation-snapshot.js";
 import { paramsEqual } from "../params-util.js";
 
@@ -508,6 +509,15 @@ export function withCacheLookup<TEnv>(
       }
     }
 
+    // A document HIT tail replays the handler layer through the implicit doc
+    // scope and never runs a handler: without that scope (a context that lost
+    // the marker before the scope resolved), fail like a lookup miss instead
+    // of falling through to the handlers below.
+    const tailMarker = pipelineReqCtx?._shellImplicitCache;
+    if (tailMarker?.docTail && !ctx.cacheScope?.isShellImplicitDocScope) {
+      throw new ShellRecordUnavailableError(tailMarker.fixedDocKey);
+    }
+
     if (ctx.isAction || !ctx.cacheScope?.enabled) {
       yield* source;
       if (ms) {
@@ -585,6 +595,13 @@ export function withCacheLookup<TEnv>(
     }
 
     if (!cacheResult) {
+      // A document shell HIT tail replays the handler layer from the entry's
+      // doc record and must never run a handler behind the committed prelude:
+      // a record that did not hit (it failed to decode, or the entry lost it)
+      // ends the tail here; serveShellHit degrades the response.
+      if (replayMarker?.docTail) {
+        throw new ShellRecordUnavailableError(replayMarker.fixedDocKey);
+      }
       yield* source;
       if (ms) {
         ms.metrics.push({

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

@@ -106,7 +106,11 @@ import {
   type RequestContext,
 } from "../../server/request-context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
-import { createShellImplicitDocScope } from "../../cache/cache-scope.js";
+import {
+  createShellImplicitDocScope,
+  resolveCacheTags,
+} from "../../cache/cache-scope.js";
+import { recordSegmentTags } from "../../cache/cache-tag.js";
 import { getRouterContext } from "../router-context.js";
 import { debugLog, debugWarn, getOrCreateRequestId } from "../logging.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
@@ -316,9 +320,10 @@ export function withCacheStore<TEnv>(
  * store) on the no-eligible-snapshot path, so the lookup's own refusal is
  * still surfaced while the fallback has nothing to serve.
  *
- * Wrapped in requestCtx.waitUntil — during a capture that is the tracked-write
- * override, so captureAndStoreShell's settleWrites awaits the record before
- * draining the snapshot.
+ * Registered through requestCtx.onResponse, which a capture fires only after
+ * the handler pushes settle (settleCaptureRecord), and wrapped in
+ * requestCtx.waitUntil — during a capture that is the tracked-write override,
+ * so settleWrites awaits the record before the capture reads it.
  */
 function recordShellCaptureDocRecord<TEnv>(
   ctx: MatchContext<TEnv>,
@@ -336,12 +341,27 @@ function recordShellCaptureDocRecord<TEnv>(
   if (!scope.allowsCache("write")) return;
 
   const docScope = createShellImplicitDocScope(marker);
-  requestCtx.waitUntil(() =>
-    docScope.cacheRoute(
-      ctx.pathname,
-      ctx.matched.params,
-      segments,
-      ctx.isIntercept,
-    ),
+  // The route scope's cache({ tags }) describe these segments too: on its
+  // HIT they arrive with the replayed record (recordSegmentTags in
+  // lookupRouteDetailed); on a fresh render they are recorded here, so the
+  // doc record, and the shell taking its tags, carries them either way.
+  recordSegmentTags(
+    segments.map((s) => s.id),
+    resolveCacheTags(scope.config, requestCtx),
+    requestCtx,
   );
+  // Through onResponse, like the implicit scope's own write: the capture
+  // fires these callbacks (settleCaptureRecord) only after the handler
+  // pushes settled, so the record's handle encode never races them.
+  requestCtx.onResponse((response) => {
+    requestCtx.waitUntil(() =>
+      docScope.cacheRoute(
+        ctx.pathname,
+        ctx.matched.params,
+        segments,
+        ctx.isIntercept,
+      ),
+    );
+    return response;
+  });
 }

package/src/router/middleware-types.ts

@@ -68,7 +68,12 @@ export interface MiddlewareContext<
 
   debugPerformance(): void;
 
-  theme?: Theme;
+  /**
+   * The visitor's theme (cookie or default); undefined without theme config.
+   * Guarded like `cookies()`: a read inside a `"use cache"` function throws
+   * (#971).
+   */
+  readonly theme?: Theme;
 
   setTheme?: (theme: Theme) => void;
 

package/src/router/middleware.ts

@@ -31,6 +31,8 @@ import {
 } from "../cache/taint.js";
 import { getCacheExecScope } from "../cache/cache-exec-scope.js";
 import { assertNonCacheableReadAllowed } from "../server/context.js";
+import { assertThemeReadAllowed } from "../server/cookie-store.js";
+import type { Theme } from "../theme/types.js";
 
 // Re-export types consumed through this module's path.
 export type {
@@ -40,6 +42,25 @@ export type {
   MiddlewareFn,
 } from "./middleware-types.js";
 
+/**
+ * Middleware ctx.theme: the visitor's theme cookie, guarded like the handler
+ * ctx.theme and cookies() (#971, #946), so a read inside a "use cache"
+ * function the middleware calls throws. Non-enumerable like the handler and
+ * request-context getters: a spread of the ctx (inside a "use cache"
+ * function, say) does not read it. One shared descriptor, so every ctx keeps
+ * the same property shape.
+ */
+const MIDDLEWARE_THEME_DESCRIPTOR: PropertyDescriptor = {
+  get(): Theme | undefined {
+    const reqCtx = _getRequestContext();
+    if (!reqCtx?._themeConfig) return undefined;
+    assertThemeReadAllowed(reqCtx, "ctx.theme");
+    return reqCtx._readTheme();
+  },
+  enumerable: false,
+  configurable: true,
+};
+
 const MIDDLEWARE_METRIC_DEPTH = 1;
 const POST_METRIC_MIN_DURATION_MS = 0.01;
 
@@ -320,10 +341,7 @@ export function createMiddlewareContext<TEnv>(
       responseHolder.response.headers.set(name, value);
     },
 
-    get theme(): MiddlewareContext<TEnv>["theme"] {
-      return _getRequestContext()?.theme;
-    },
-
+    // theme: MIDDLEWARE_THEME_DESCRIPTOR, defined after this literal.
     get setTheme(): MiddlewareContext<TEnv>["setTheme"] {
       return _getRequestContext()?.setTheme;
     },
@@ -361,6 +379,7 @@ export function createMiddlewareContext<TEnv>(
       }
     },
   };
+  Object.defineProperty(ctx, "theme", MIDDLEWARE_THEME_DESCRIPTOR);
   (ctx as any)[NOCACHE_SYMBOL] = true;
   return ctx;
 }

package/src/router/prerender-match.ts

@@ -230,6 +230,7 @@ export async function matchForPrerender<TEnv = any>(
       _setStatus: () => {},
       _rotateStateCookie: () => {},
       _setKeepCacheDirective: () => {},
+      _setFreshReadsCookie: () => {},
       use: (() => {
         throw new Error("use() not available during pre-rendering");
       }) as any,
@@ -239,6 +240,8 @@ export async function matchForPrerender<TEnv = any>(
       waitUntil: () => {},
       onResponse: () => {},
       _onResponseCallbacks: [],
+      // No theme at build time: no request cookie.
+      _readTheme: () => undefined,
       setLocationState() {},
       _locationState: undefined,
       _renderBarrier: Promise.resolve(),
@@ -530,6 +533,7 @@ export async function renderStaticSegment<TEnv = any>(
     _setStatus: () => {},
     _rotateStateCookie: () => {},
     _setKeepCacheDirective: () => {},
+    _setFreshReadsCookie: () => {},
     use: (() => {
       throw new Error("use() not available during static pre-rendering");
     }) as any,
@@ -539,6 +543,8 @@ export async function renderStaticSegment<TEnv = any>(
     waitUntil: () => {},
     onResponse: () => {},
     _onResponseCallbacks: [],
+    // No theme at build time: no request cookie.
+    _readTheme: () => undefined,
     setLocationState() {},
     _locationState: undefined,
     _renderBarrier: Promise.resolve(),

package/src/router/segment-resolution/fresh.ts

@@ -37,7 +37,7 @@ import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { _getRequestContext } from "../../server/request-context.js";
 import { getRouterContext } from "../router-context.js";
 import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
-import { observeHandler } from "../instrument.js";
+import { observeSegmentHandler } from "../instrument.js";
 import {
   track,
   RangoContext,
@@ -173,9 +173,7 @@ export async function resolveLoaders<TEnv>(
               // bakes at capture regardless of the entry's loading() lane
               // (loader-cache.ts capture branch) and its HIT-tail seed
               // overlay needs the same key.
-              bakeLane || loaderEntry.awaitBeforeFlush === true
-                ? segmentId
-                : null,
+              bakeLane || loaderEntry.bake === true ? segmentId : null,
             ),
           ),
           entry,
@@ -223,7 +221,7 @@ export async function resolveLoaders<TEnv>(
           loaderEntry,
           ctx,
           ctx.pathname,
-          bakeLane || loaderEntry.awaitBeforeFlush === true ? segmentId : null,
+          bakeLane || loaderEntry.bake === true ? segmentId : null,
         ),
       ),
       entry,
@@ -396,7 +394,7 @@ export async function resolveSegment<TEnv>(
       const doneRouteHandler = track(`handler:${entry.id}`, 2);
       if (entry.loading) {
         const result = handleHandlerResult(
-          observeHandler(entry.id, handler, context),
+          observeSegmentHandler(entry.shortCode, entry.id, handler, context),
         );
         if (result instanceof Promise) {
           warnOnStreamedResponse(result, entry.id);
@@ -420,7 +418,12 @@ export async function resolveSegment<TEnv>(
         }
       } else {
         component = handleHandlerResult(
-          await observeHandler(entry.id, handler, context),
+          await observeSegmentHandler(
+            entry.shortCode,
+            entry.id,
+            handler,
+            context,
+          ),
         );
         doneRouteHandler();
       }
@@ -670,7 +673,12 @@ export async function resolveParallelEntry<TEnv>(
       if (hasLoadingFallback) {
         const result =
           typeof handler === "function"
-            ? observeHandler(`${parallelEntry.id}.${slot}`, handler, context)
+            ? observeSegmentHandler(
+                `${parentShortCode}.${slot}`,
+                `${parallelEntry.id}.${slot}`,
+                handler,
+                context,
+              )
             : handler;
         if (result instanceof Promise) {
           result.finally(doneParallelHandler).catch(() => {});
@@ -694,7 +702,8 @@ export async function resolveParallelEntry<TEnv>(
       } else {
         component =
           typeof handler === "function"
-            ? await observeHandler(
+            ? await observeSegmentHandler(
+                `${parentShortCode}.${slot}`,
                 `${parallelEntry.id}.${slot}`,
                 handler,
                 context,

package/src/router/segment-resolution/helpers.ts

@@ -29,7 +29,7 @@ import type {
 import type { SegmentResolutionDeps } from "../types.js";
 import { debugLog } from "../logging.js";
 import { tryStaticLookup } from "./static-store.js";
-import { observeHandler } from "../instrument.js";
+import { observeSegmentHandler } from "../instrument.js";
 import type { TelemetrySink } from "../telemetry.js";
 import { resolveSink, safeEmit, getRequestId } from "../telemetry.js";
 
@@ -175,7 +175,9 @@ export async function resolveLayoutComponent<TEnv>(
   // by track("handler:<id>") at the call site). handleHandlerResult stays OUTSIDE
   // the span so a handler that returns a Response (redirect control flow, which it
   // rethrows) is not recorded as a span error — mirrors the route-handler sites.
-  return handleHandlerResult(await observeHandler(entry.id, handler, context));
+  return handleHandlerResult(
+    await observeSegmentHandler(entry.shortCode, entry.id, handler, context),
+  );
 }
 
 // ---------------------------------------------------------------------------