@rangojs/router 0.32.0 → 0.33.1

package/src/cache/document-cache-policy.ts

@@ -71,6 +71,7 @@ export function shouldCacheResponse(
     RequestContext,
     | "_payloadVisitorTheme"
     | "_payloadDeferred"
+    | "_payloadSourceScoped"
     | "_payloadVisitorLocation"
     | "_documentLocationState"
   >,
@@ -118,10 +119,36 @@ export function shouldCacheResponse(
     return null;
   }
 
+  // A partial scoped to its source page: this cache keys it by
+  // URL and the ids the client holds, so it would answer another page with
+  // the same ids. rsc-rendering.ts sends it NOT_REUSED; a middleware can
+  // replace that after next().
+  if (requestCtx?._payloadSourceScoped) {
+    return null;
+  }
+
   const cacheControl = response.headers.get("Cache-Control");
   return parseCacheControl(cacheControl);
 }
 
+/**
+ * Whether a response carries one client's state, which a stored copy would
+ * replay to that client's later requests: a per-client signal header (a state
+ * cookie rotation, `x-rango-keep-cache`) or location state. The stored
+ * prefetch Cache-Control (rsc/request-stages.ts) is not sent on
+ * one.
+ */
+export function carriesClientState(
+  response: Response,
+  requestCtx: Pick<RequestContext, "_locationState" | "_documentLocationState">,
+): boolean {
+  return (
+    hasPerClientSignal(response.headers) ||
+    (requestCtx._locationState?.length ?? 0) > 0 ||
+    requestCtx._documentLocationState === true
+  );
+}
+
 /**
  * Whether this cache will store the response the current render produces, as
  * far as the render can tell: the middleware runs it (a MISS or a stale

package/src/cache/document-cache.ts

@@ -357,6 +357,11 @@ export function createDocumentCacheMiddleware<TEnv = any>(
         if (!cached.shouldRevalidate) {
           // Fresh hit - return immediately
           log(`[DocumentCache] HIT ${typeLabel}: ${url.pathname}`);
+          // Nothing in it runs: its loaders' output is replayed, and no
+          // failed render is ever stored (throwIfRenderErrored). A prefetch
+          // answered with it leaves with the router's prefetch Cache-Control
+          // (rsc/request-stages.ts).
+          requestCtx._servedFromStorage = true;
           return drainOnResponseCallbacks(
             addCacheStatusHeader(cached.response, "HIT"),
             requestCtx,

package/src/cache/memory-segment-store.ts

@@ -120,13 +120,14 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
 
   /**
    * Custom key generator applied to all cache operations.
-   * Receives the full RequestContext and the default-generated key.
+   * Receives the full RequestContext and the default-generated key. A route
+   * record keeps its request kind (see SegmentCacheStore.keyGenerator).
    *
    * @example
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
    *   const locale = cookies().get('locale')?.value || 'en';
-   *   return `${locale}:${defaultKey}`;
+   *   return `${defaultKey}|${locale}`;
    * }
    * ```
    */

package/src/cache/segment-codec.ts

@@ -309,8 +309,8 @@ export async function serializeSegments(
  * cached with the route record).
  *
  * The loading "null" sentinel decodes here (not on the consumer): loading:null
- * must survive as null, and shipping the raw sentinel would change the
- * deduplicateLoaderSegments loading-presence check.
+ * must survive as null, and shipping the raw sentinel would hand renderSegments
+ * a truthy `loading`, the fallback tree shape (docs/tree-structure.md).
  */
 export async function fragmentSegments(
   data: SerializedSegmentData[],

package/src/cache/shell-snapshot.ts

@@ -407,7 +407,7 @@ const PIN_KEY_PREFIX = /^[^D.]*D\d+\./;
  * Deserializations run in parallel; a record that fails to decode is skipped
  * and reported to `onUndecodable`: its loader runs instead, which a document
  * HIT has already committed a prelude against, so serveShellHit retires the
- * entry (dc-t89). Returns undefined when the snapshot carries no loader
+ * entry. Returns undefined when the snapshot carries no loader
  * records, without touching the Flight codec (kept lazy for cold paths and
  * non-RSC configs).
  */

package/src/cache/types.ts

@@ -93,16 +93,21 @@ export interface SegmentCacheStore<TEnv = unknown> {
   /**
    * Custom key generator applied to all cache operations using this store.
    * Receives the full RequestContext and the default-generated key.
-   * Return value becomes the final cache key (unless route overrides with `key` option).
+   * The return value is the cache key (unless route overrides with `key`
+   * option), with a route record's request kind appended when it does not
+   * start with that kind (below).
    *
    * Resolution priority:
    * 1. Route-level `key` function (replaces the URL part; the request kind stays)
    * 2. Store-level `keyGenerator` (modifies default key)
    * 3. Default key generation (prefix:pathname:params)
    *
-   * Keep `defaultKey` in the result: its prefix names the request kind (a
-   * document, a navigation or an intercept navigation), whose records hold
-   * different segments. A result without it gives every kind one record.
+   * A route record keeps its request kind (a document, a navigation or an
+   * intercept navigation), whose records hold different segments: the kind
+   * is `defaultKey`'s prefix (`doc:`, `partial:`, `intercept:<intercept>:`),
+   * and a result that does not start with it gets the kind appended as a
+   * key part of its own. Build on `defaultKey` (`${defaultKey}|${segment}`)
+   * and the result is the record key byte for byte.
    *
    * Return `defaultKey` unchanged to leave a request unpartitioned. An empty
    * string is not a key: where the result partitions a nested cache() on
@@ -114,7 +119,7 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
    *   const segment = ctx.request.headers.get('x-user-segment') || 'default';
-   *   return `${segment}:${defaultKey}`;
+   *   return `${defaultKey}|${segment}`;
    * }
    * ```
    *
@@ -122,7 +127,7 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
    *   const region = ctx.env.REGION || 'us';
-   *   return `${region}:${defaultKey}`;
+   *   return `${defaultKey}|${region}`;
    * }
    * ```
    *
@@ -130,7 +135,7 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
    *   const locale = cookies().get('locale')?.value || 'en';
-   *   return `${locale}:${defaultKey}`;
+   *   return `${defaultKey}|${locale}`;
    * }
    * ```
    */

package/src/cache/vercel/vercel-cache-store.ts

@@ -356,7 +356,8 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
 
   /**
    * Custom key generator applied to all cache operations (region/locale/user
-   * segmentation). Receives the request context and the default key.
+   * segmentation). Receives the request context and the default key. A route
+   * record keeps its request kind (see SegmentCacheStore.keyGenerator).
    */
   keyGenerator?: (
     ctx: RequestContext<TEnv>,

package/src/client-urls/types.ts

@@ -85,8 +85,9 @@ export interface ClientUrlLoaderRecord {
    */
   readonly ssr?: false;
   /**
-   * loader(Def, { prefetch: false }): a prefetch of the route, or of an
-   * intercept's target from its source, defers this loader and the click
+   * loader(Def, { prefetch: false }): a viewport or render prefetch of the
+   * route, or of an intercept's target from its source, defers this loader
+   * (a hover prefetch runs it) and the click
    * that adopts it runs it in its fill request (see {@link LoaderOptions}).
    * Projected onto the materialized stub.
    */
@@ -169,12 +170,13 @@ export interface ClientUrlHelpers {
    * holes).
    *
    * Pass `{ prefetch: false }` to keep this loader out of the route's
-   * prefetches (see {@link LoaderOptions}): an in-group click still shows
+   * viewport and render prefetches; a hover prefetch runs it (see
+   * {@link LoaderOptions}). An in-group click still shows
    * the destination at once, commits the adopted prefetch with the other
    * loaders' data, and runs only the flagged loaders in its one fill
    * request. A `layout()` loader with the flag is flagged on every route
-   * below it. Inside intercept() it defers the loader in a prefetch of the
-   * intercept from its source, as in urls().
+   * below it. Inside intercept() it defers the loader in a viewport or
+   * render prefetch of the intercept from its source, as in urls().
    */
   readonly loader: <TData>(
     definition: LoaderDefinition<TData>,

package/src/prefetch-markers.ts

@@ -9,6 +9,16 @@
 /** Request header of a `<Link>` prefetch (browser/prefetch/fetch.ts). */
 export const PREFETCH_HEADER = "X-Rango-Prefetch";
 
+/**
+ * PREFETCH_HEADER's value on an intent prefetch: a hover or an explicit
+ * `prefetch()` call (browser/prefetch/fetch.ts prefetchDirect). The server
+ * defers nothing in it: `prefetch: false` loaders and the work behind a
+ * flagged `loading()` run, as in the navigation it starts early. A
+ * speculative prefetch (viewport, render) sends `1`, and any value other than
+ * this one reads as speculative.
+ */
+export const PREFETCH_INTENT = "intent";
+
 /**
  * The last row of a prefetch whose render reported an error
  * (rsc/prefetch-render-error.ts): a Flight hint with a code React does not

package/src/prefetch-source-scope.ts

@@ -0,0 +1,137 @@
+/**
+ * The source group of a prefetch answer a revalidate() rule kept from the
+ * page being left (#1331). Shared by the server, which reports
+ * the group in `x-rsc-prefetch-scope: params; <label>` (rsc/rsc-rendering.ts),
+ * and the browser, which stores the answer under that label and rebuilds it
+ * from the page on screen to look it up (browser/prefetch/cache.ts).
+ * Dependency free, like prefetch-markers.ts: the browser must not import the
+ * server modules that record the reads (router/source-reads.ts).
+ *
+ * Why a label is enough: a rule's decision depends on the source page only
+ * through what it read. Two pages with equal values of everything the kept
+ * rules read run every rule the same way, so one answer serves both.
+ */
+
+/** What the revalidate() rules that kept a segment read of the source page. */
+export interface SourceReads {
+  /**
+   * `currentParams` was read. Its key set is then part of the group: a rule
+   * can test a key's presence (`in`, `Object.keys`) without reading a value.
+   */
+  keys: boolean;
+  /**
+   * Each `currentParams` value read; a spread or JSON.stringify reads all.
+   * Non-empty only with `keys`: a value is read through `currentParams`.
+   */
+  params: Set<string>;
+  /** `fromRouteName` was read. */
+  route: boolean;
+  /** `currentUrl` was read: the answer is the exact page's. */
+  url: boolean;
+}
+
+/** The page a label describes: the source on the server, the screen in the browser. */
+export interface SourcePage {
+  params: Readonly<Record<string, string | undefined>>;
+  /** The public route name (route-name.ts publicRouteName). */
+  routeName: string | undefined;
+}
+
+/** What a label reads, without the values: one per kind of rule set. */
+export interface SourceShape {
+  keys: boolean;
+  route: boolean;
+  /** Sorted. */
+  names: readonly string[];
+}
+
+/** `x-rsc-prefetch-scope` value prefix of a params-grouped answer. */
+export const PARAMS_SCOPE_PREFIX = "params; ";
+
+export function createSourceReads(): SourceReads {
+  return { keys: false, params: new Set(), route: false, url: false };
+}
+
+export function hasSourceReads(reads: SourceReads): boolean {
+  return reads.keys || reads.route || reads.url || reads.params.size > 0;
+}
+
+/** Union `from` into `into`. */
+export function mergeSourceReads(into: SourceReads, from: SourceReads): void {
+  into.keys ||= from.keys;
+  into.route ||= from.route;
+  into.url ||= from.url;
+  for (const name of from.params) into.params.add(name);
+}
+
+export function shapeOfReads(reads: SourceReads): SourceShape {
+  return {
+    keys: reads.keys,
+    route: reads.route,
+    names: [...reads.params].sort(),
+  };
+}
+
+/**
+ * The label of `page` under `shape`: `&`-joined, `$k=<keys>` first, then
+ * `$r[=<route>]`, then `<name>[=<value>]` per read param, sorted. A missing
+ * value has no `=`. Names and values are URI-encoded, so a `$` entry never
+ * collides with a param (encodeURIComponent encodes `$`).
+ */
+export function formatSourceLabel(
+  shape: SourceShape,
+  page: SourcePage,
+): string {
+  const parts: string[] = [];
+  if (shape.keys) {
+    parts.push(
+      "$k=" + Object.keys(page.params).sort().map(encodeURIComponent).join(","),
+    );
+  }
+  if (shape.route) parts.push(entry("$r", page.routeName));
+  for (const name of shape.names) {
+    parts.push(entry(encodeURIComponent(name), page.params[name]));
+  }
+  return parts.join("&");
+}
+
+function entry(name: string, value: string | undefined): string {
+  return value === undefined ? name : name + "=" + encodeURIComponent(value);
+}
+
+/**
+ * The label of an `x-rsc-prefetch-scope` value, or undefined when the value
+ * is not a params scope.
+ */
+export function paramsScopeLabel(
+  header: string | null | undefined,
+): string | undefined {
+  if (!header?.startsWith(PARAMS_SCOPE_PREFIX)) return undefined;
+  return header.slice(PARAMS_SCOPE_PREFIX.length);
+}
+
+/** The shape of a label formatSourceLabel wrote. */
+export function parseSourceShape(label: string): SourceShape {
+  let keys = false;
+  let route = false;
+  const names: string[] = [];
+  for (const part of label.split("&")) {
+    if (part === "") continue;
+    const eq = part.indexOf("=");
+    const name = eq === -1 ? part : part.slice(0, eq);
+    if (name === "$k") keys = true;
+    else if (name === "$r") route = true;
+    else names.push(decodeURIComponent(name));
+  }
+  return { keys, route, names: names.sort() };
+}
+
+/** A stable id of a shape, for indexing. */
+export function sourceShapeId(shape: SourceShape): string {
+  return (
+    (shape.keys ? "k" : "") +
+    (shape.route ? "r" : "") +
+    ":" +
+    shape.names.map(encodeURIComponent).join(",")
+  );
+}

package/src/route-definition/helpers-types.ts

@@ -333,9 +333,10 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * loader(RecommendationsLoader),  // still streams behind loading()
    * ```
    *
-   * Pass `{ prefetch: false }` to keep the loader out of prefetches: a
-   * prefetch skips it and the click that adopts the prefetch fetches it in
-   * one follow-up request (see {@link LoaderOptions}). Only on a segment the
+   * Pass `{ prefetch: false }` to keep the loader out of speculative
+   * prefetches (viewport, render): such a prefetch skips it and the click
+   * that adopts it fetches it in one follow-up request; a hover prefetch runs
+   * it (see {@link LoaderOptions}). Only on a segment the
    * client does not have yet: a loader the client already holds runs in the
    * prefetch when it revalidates.
    *
@@ -361,14 +362,16 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * // Skip loading on SSR, only show on client navigation
    * loading(<Skeleton />, { ssr: false })
    *
-   * // Keep everything behind this fallback out of prefetches
+   * // Keep everything behind this fallback out of viewport and render
+   * // prefetches (a hover prefetch runs it)
    * loading(<Skeleton />, { prefetch: false })
    * ```
    * @param component - The loading UI to show during navigation
    * @param options - Configuration options
    * @param options.ssr - If false, skip showing loading on document requests (SSR)
    * @param options.prefetch - If false, the flag applies when this entry's
-   *   segment is new to the client. A prefetch then skips the whole unit: the
+   *   segment is new to the client. A viewport or render prefetch then skips
+   *   the whole unit (a hover prefetch runs it): the
    *   handler, its loaders, its orphan layouts and parallel slots and, for a
    *   layout, every deeper entry; the click that adopts the prefetch shows
    *   this fallback and fetches them in one follow-up request, which reads

package/src/router/intercept-resolution.ts

@@ -26,11 +26,12 @@ import {
 } from "./segment-resolution/revalidation.js";
 import { fillSends } from "./segment-resolution/prefetch-deferral.js";
 import type { ResolutionPass } from "./segment-resolution/resolution-pass.js";
-import { getRouterContext } from "./router-context.js";
+import { getRouterContext, type InterceptResult } from "./router-context.js";
 import { runInSegmentTagScope } from "../cache/cache-tag.js";
 import {
   RangoContext,
   latchPprHeaderScopeForEntries,
+  runAsSegment,
 } from "../server/context.js";
 import { _getRequestContext } from "../server/request-context.js";
 
@@ -60,18 +61,11 @@ function latchPprHeaderScopeForInterceptTarget(
  * If no when() conditions are defined, the intercept always activates.
  * A selector that throws yields the conservative default, no intercept (the
  * full page renders), and is logged; it never fails the request.
- *
- * During action revalidation, when() is NOT evaluated.
  */
 export function evaluateInterceptWhen(
   intercept: InterceptEntry,
   selectorContext: InterceptSelectorContext | null,
-  isAction: boolean,
 ): boolean {
-  if (isAction) {
-    return true;
-  }
-
   if (!intercept.when || intercept.when.length === 0) {
     return true;
   }
@@ -92,9 +86,34 @@ export function evaluateInterceptWhen(
 }
 
 /**
- * Find an intercept for the target route by walking up the entry chain.
- * Returns the first (innermost) matching intercept along with the entry that defines it.
+ * Walk the intercepts declared along `fromEntry`'s chain in selection order,
+ * an entry's own and then its orphans' (nested ones included) in render
+ * order, from `fromEntry` up, until `pick` returns a value. Tolerates partial
+ * entries (unit-test mocks omit the arrays); real registration always
+ * populates layout/intercept.
  */
+function findOnChain<T>(
+  fromEntry: EntryData | null,
+  pick: (intercept: InterceptEntry, entry: EntryData) => T | undefined,
+): T | undefined {
+  const visit = (entry: EntryData): T | undefined => {
+    for (const intercept of entry.intercept ?? []) {
+      const found = pick(intercept, entry);
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  };
+  let current: EntryData | null = fromEntry;
+  let prev: EntryData | null = null;
+  while (current) {
+    const found = visit(current) ?? findInOrphans(current, visit, prev);
+    if (found !== undefined) return found;
+    prev = current;
+    current = current.parent;
+  }
+  return undefined;
+}
+
 /**
  * Collect every intercept TARGET route name reachable from an origin entry —
  * the same chain walk findInterceptForRoute() performs when this location is
@@ -110,55 +129,78 @@ export function collectInterceptTargetNames(
   fromEntry: EntryData | null,
 ): string[] {
   const names = new Set<string>();
-  // Tolerate partial entries (unit-test mocks omit the arrays); real
-  // registration always populates layout/intercept.
-  const add = (source: EntryData): undefined => {
-    for (const intercept of source.intercept ?? []) {
-      names.add(intercept.routeName);
-    }
+  findOnChain(fromEntry, (intercept) => {
+    names.add(intercept.routeName);
     return undefined;
-  };
-  let current: EntryData | null = fromEntry;
-  let prev: EntryData | null = null;
-  while (current) {
-    add(current);
-    findInOrphans(current, add, prev);
-    prev = current;
-    current = current.parent;
-  }
+  });
   return [...names];
 }
 
+/**
+ * The intercept for the target route, with the entry that declares it.
+ * `targetRouteKeys` are the names it may be declared for, in precedence
+ * order: the route's own name, then its local name inside include()
+ * (match-api.ts). A navigation, or an action with no `held`, takes the first
+ * along the chain from `fromEntry` up under the first name that has one: on a
+ * navigation, the first whose when() passes; on an action, the first, when()
+ * not evaluated.
+ *
+ * An action given `held` (the request's segment ids) re-renders the intercept
+ * on screen: one whose slot id the client holds, null when it holds none. Its
+ * candidates are collected under every name in one walk, the route's own
+ * name's first: a held id under the own name (a parallel() default of the
+ * slot's name) must not win before the local name is looked at. One held:
+ * that one, when() not evaluated, so an open intercept stays open when its
+ * when() would now reject. Several held (intercepts on one entry that fill one
+ * slot share its id, as does a parallel() slot of that name): the ones whose
+ * slot has no parallel() default on their entry, if any (a default holds its
+ * slot id whether or not an intercept is open there). One left: that one,
+ * when() not evaluated. Else the first whose when() passes against the
+ * action's intercept source, else the first.
+ */
 export function findInterceptForRoute(
-  targetRouteKey: string,
+  targetRouteKeys: string | readonly string[],
   fromEntry: EntryData | null,
   selectorContext: InterceptSelectorContext | null = null,
   isAction: boolean = false,
-): { intercept: InterceptEntry; entry: EntryData } | null {
-  const match = (source: EntryData) => {
-    for (const intercept of source.intercept) {
-      if (
-        intercept.routeName === targetRouteKey &&
-        evaluateInterceptWhen(intercept, selectorContext, isAction)
-      ) {
-        return { intercept, entry: source };
-      }
+  held?: ReadonlySet<string>,
+): InterceptResult | null {
+  const names =
+    typeof targetRouteKeys === "string" ? [targetRouteKeys] : targetRouteKeys;
+  if (!isAction || !held) {
+    for (const name of names) {
+      const found = findOnChain(fromEntry, (intercept, entry) =>
+        intercept.routeName === name &&
+        (isAction || evaluateInterceptWhen(intercept, selectorContext))
+          ? { intercept, entry }
+          : undefined,
+      );
+      if (found) return found;
     }
-    return undefined;
-  };
-  let current: EntryData | null = fromEntry;
-  let prev: EntryData | null = null;
-
-  while (current) {
-    // current first, then its orphans (nested ones included) in render order.
-    const found = match(current) ?? findInOrphans(current, match, prev);
-    if (found) return found;
-
-    prev = current;
-    current = current.parent;
+    return null;
   }
-
-  return null;
+  const byName: InterceptResult[][] = names.map(() => []);
+  findOnChain(fromEntry, (intercept, entry) => {
+    const rank = names.indexOf(intercept.routeName);
+    if (rank !== -1 && held.has(interceptSlotId(entry, intercept))) {
+      byName[rank]!.push({ intercept, entry });
+    }
+    return undefined;
+  });
+  const open = byName.flat();
+  if (open.length < 2) return open[0] ?? null;
+  // A parallel() default of the slot's name holds its slot id whichever
+  // intercept is open, so a candidate that has one proves nothing about what
+  // is on screen: among several, the ones without a default are the open ones.
+  const unshadowed = open.filter(
+    (c) => !c.entry.parallel?.[c.intercept.slotName],
+  );
+  const pool = unshadowed.length > 0 ? unshadowed : open;
+  if (pool.length === 1) return pool[0]!;
+  return (
+    pool.find((c) => evaluateInterceptWhen(c.intercept, selectorContext)) ??
+    pool[0]!
+  );
 }
 
 /**
@@ -357,7 +399,9 @@ export async function resolveInterceptEntry<TEnv>(
     handlerResult =
       typeof handler === "function"
         ? handleHandlerResult(
-            runInSegmentTagScope(slotSegmentId, handler, context),
+            runAsSegment(slotSegmentId, () =>
+              runInSegmentTagScope(slotSegmentId, handler, context),
+            ),
           )
         : handler;
   } catch (error) {

package/src/router/loader-resolution.ts

@@ -70,6 +70,8 @@ import {
   scopeReverse,
   runInsideLoaderBodyScope,
   runInsideLoaderRun,
+  runAsSegment,
+  segmentPinOf,
   isInsidePushCallbackScope,
   runInsidePushCallbackScope,
   type LoaderRunIdentity,
@@ -871,8 +873,10 @@ function createLoaderExecutor<TEnv>(
       Promise.resolve(
         runInsideLoaderBodyScope(
           () =>
-            runInsideLoaderRun(identity, () =>
-              loaderFn(loaderCtx as LoaderContext<any, TEnv>),
+            runAsSegment(owningSegmentId, () =>
+              runInsideLoaderRun(identity, () =>
+                loaderFn(loaderCtx as LoaderContext<any, TEnv>),
+              ),
             ),
           loader.$$id,
           recordedTags,
@@ -982,8 +986,7 @@ export function setupLoaderAccess<TEnv>(
     if (isHandle(item)) {
       const handle = item;
       const store = handleStoreRef;
-      const segmentId = (ctx as InternalHandlerContext<any, TEnv>)
-        ._currentSegmentId;
+      const segmentId = segmentPinOf(ctx as InternalHandlerContext<any, TEnv>);
 
       if (!segmentId) {
         throw new Error(
@@ -1057,8 +1060,7 @@ export function setupBuildUse<TEnv>(ctx: HandlerContext<any, TEnv>): void {
     if (isHandle(item)) {
       const handle = item;
       const store = handleStoreRef;
-      const segmentId = (ctx as InternalHandlerContext<any, TEnv>)
-        ._currentSegmentId;
+      const segmentId = segmentPinOf(ctx as InternalHandlerContext<any, TEnv>);
 
       if (!segmentId) {
         throw new Error(