@rangojs/router 0.31.0 → 0.33.0

package/src/browser/react/use-navigation.ts

@@ -27,7 +27,7 @@ interface Snapshot<T> {
 /**
  * A notification while React holds a page: work that starts shows at once
  * (loading, streaming, a newer click's URL), what settles waits for the
- * page's commit (rango-d152), and location moves only with the notification
+ * page's commit, and location moves only with the notification
  * that moves it (the page on screen until the next one shows).
  */
 function hold(

package/src/browser/rsc-router.tsx

@@ -27,7 +27,11 @@ import type { EventController } from "./event-controller.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 import { expandPayloadFragments } from "../segment-fragments.js";
 import { initRangoState } from "./rango-state.js";
-import { registerNavigationStore } from "./navigation-store-handle.js";
+import {
+  committedPageOf,
+  registerCommittedPageReader,
+  registerNavigationStore,
+} from "./navigation-store-handle.js";
 import { initPrefetchCache } from "./prefetch/cache.js";
 import {
   auditTreeCause,
@@ -47,6 +51,7 @@ import {
 import { createAppShellRef } from "./app-shell.js";
 import { bootLog, IS_BROWSER_DEBUG } from "./logging.js";
 import {
+  applyDocumentLocationState,
   clearLocationStateOnDocumentLoad,
   stripShellMissMarker,
 } from "./history-state.js";
@@ -274,8 +279,10 @@ export async function initBrowserApp(
     setSuspenseAuditStreamProbe(() => eventController.getState().isStreaming);
   }
 
-  // The document's entry, after the clearOnReload pass and under the version
-  // set above: what readers get once they have hydrated.
+  // The state the document response carried, after the clearOnReload pass
+  // and under the version set above.
+  applyDocumentLocationState(initialPayload.metadata?.locationState);
+  // The document's entry: what readers get once they have hydrated.
   eventController.commitLocationState(window.history.state);
 
   // Initialize event controller with segment order (even without handles)
@@ -283,6 +290,9 @@ export async function initBrowserApp(
 
   // Initialize route params
   eventController.setParams(initialPayload.metadata?.params ?? {});
+  // The page a prefetch is sent from, read by the prefetch cache at request
+  // time (browser/prefetch/cache.ts paramsCandidateKeys).
+  registerCommittedPageReader(committedPageOf(eventController, store));
 
   // Initialize handle data from initial payload BEFORE hydration
   // This ensures useHandle returns correct data during hydration to avoid mismatch

package/src/browser/server-action-bridge.ts

@@ -271,7 +271,7 @@ export function createServerActionBridge(
    * - Never over an intercept: a request holding no segments drops the page
    *   under it (match-result.ts buildMatchResult). Checked when it would run,
    *   against the page then on screen; the debt is dropped there.
-   * - Never supersedes a navigation the user started (dc-t114): it waits for
+   * - Never supersedes a navigation the user started: it waits for
    *   NavigationEntry.settled, then looks again. A navigation that failed
    *   keeps its error on screen, and the debt is dropped.
    * - Runs again when it is left before its commit (a navigation, or an action
@@ -322,7 +322,7 @@ export function createServerActionBridge(
    * R6: an action that starts while the follow-up has not committed leaves
    * it, and the batch's end owes it again. Its request may predate that
    * action's write, and its commit could land after the action's own,
-   * moving data on screen backwards (dc-t110). Through the controller, so
+   * moving data on screen backwards. Through the controller, so
    * the navigation it started stops being current.
    */
   function leaveFollowUp(): void {
@@ -339,7 +339,7 @@ export function createServerActionBridge(
    * repairs. Resolves with whether it started and the error of a loader
    * that threw on it. Never starts while a navigation the user started may
    * be superseded (unsettledUserNavigation): its startNavigation would
-   * abort it (dc-t114). A repair that cannot start is owed at the batch's
+   * abort it. A repair that cannot start is owed at the batch's
    * end instead (finalizeAction). `run` (the follow-up's) is handed the
    * refetch's navigation, and told once whether it ended left before its
    * commit.

package/src/browser/types.ts

@@ -703,7 +703,15 @@ export interface NavigationStore {
    */
   getPageHistoryKeys(historyKey: string): string[];
   markHistoryCacheStale(): void;
+  /**
+   * Mark history entries and prefetches stale without a broadcast: a cookie
+   * read saw another write (rango-state.ts setRangoStateWriteObserver).
+   */
+  markCachesStaleAfterWrite(): void;
+  /** A server action without a directive: mark stale, soft broadcast. */
   markCacheAsStaleAndBroadcast(): void;
+  /** The client seat of invalidateClientCache(): flush, rotate, broadcast. */
+  invalidateCacheAndBroadcast(): void;
   clearHistoryCache(): void;
 
   // Cross-tab refresh callback (set by navigation bridge)
@@ -753,6 +761,16 @@ export interface FetchPartialOptions {
    * to a prefetch cache or the HTTP cache, and it cancels no prefetch.
    */
   fill?: boolean;
+  /**
+   * Whether a prefetch a server action marked stale (prefetch/cache.ts
+   * isPrefetchStale) may answer this navigation. Only a click sets it: it
+   * revalidates its page once it settled (navigation-bridge.ts navigate,
+   * partial-update.ts onStalePrefetch). For any other caller (Back/Forward on
+   * a history-cache miss, leaving an intercept) a stale stored entry is a
+   * miss, and a stale in-flight one is dropped and fetched again, so no path
+   * that never revalidates commits pre-write data.
+   */
+  acceptStalePrefetch?: boolean;
 }
 
 /**
@@ -771,6 +789,13 @@ export interface FetchPartialResult {
    * fallbacks stream as usual.
    */
   fullyPrefetched?: boolean;
+  /**
+   * True when the payload is a prefetch a server action marked stale after it
+   * was fetched (prefetch/cache.ts isPrefetchStale). The click commits it as
+   * any prefetch; the navigation then revalidates its page once it settled,
+   * as Back onto a stale history entry does (navigation-bridge.ts navigate).
+   */
+  stalePrefetch?: boolean;
 }
 
 /**

package/src/build/generate-route-types.ts

@@ -34,6 +34,7 @@ export {
   formatNestedRouterConflictError,
   findRouterFiles,
   findHostRouterFiles,
+  isRoutableSourceFile,
   writeCombinedRouteTypes,
   genFileTsPath,
   resolveSearchSchemas,

package/src/build/route-types/include-resolution.ts

@@ -13,7 +13,8 @@ export type UnresolvableReason =
   | "dynamic-expression"
   | "unresolvable-import"
   | "file-not-found"
-  | "unresolvable-basename";
+  | "unresolvable-basename"
+  | "unresolvable-routes";
 
 export interface UnresolvableInclude {
   pathPrefix: string;
@@ -78,14 +79,50 @@ function readSourceMemoized(
   return source;
 }
 
-function isUrlsDefinitionCall(node: ts.CallExpression): boolean {
+export function isUrlsDefinitionCall(
+  node: ts.CallExpression,
+  aliases?: ReadonlySet<string>,
+): boolean {
   const callee = node.expression;
   return (
     ts.isIdentifier(callee) &&
-    (callee.text === "urls" || callee.text === "clientUrls")
+    (callee.text === "urls" ||
+      callee.text === "clientUrls" ||
+      aliases?.has(callee.text) === true)
   );
 }
 
+/**
+ * Local names that `import { urls as u, clientUrls as cu } from
+ * "@rangojs/router"` (or `/client`) binds to urls()/clientUrls(), so a renamed
+ * import is read like the plain name. Other modules' exports are not guessed
+ * at: a `urls` from elsewhere is read only under its own name.
+ */
+export function collectUrlsImportAliases(
+  sourceFile: ts.SourceFile,
+): ReadonlySet<string> {
+  const aliases = new Set<string>();
+  for (const stmt of sourceFile.statements) {
+    if (
+      !ts.isImportDeclaration(stmt) ||
+      !ts.isStringLiteral(stmt.moduleSpecifier) ||
+      (stmt.moduleSpecifier.text !== "@rangojs/router" &&
+        stmt.moduleSpecifier.text !== "@rangojs/router/client")
+    ) {
+      continue;
+    }
+    const bindings = stmt.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    for (const el of bindings.elements) {
+      const imported = (el.propertyName ?? el.name).text;
+      if (imported === "urls" || imported === "clientUrls") {
+        aliases.add(el.name.text);
+      }
+    }
+  }
+  return aliases;
+}
+
 // ---------------------------------------------------------------------------
 // AST-based include() parsing
 // ---------------------------------------------------------------------------

package/src/build/route-types/router-processing.ts

@@ -21,6 +21,8 @@ import {
   resolveImportPath,
   buildCombinedRouteMapWithSearch,
   createScanMemo,
+  isUrlsDefinitionCall,
+  collectUrlsImportAliases,
   type ScanMemo,
   type UnresolvableInclude,
 } from "./include-resolution.js";
@@ -46,7 +48,9 @@ const ROUTER_CALL_PATTERN = /\bcreateRouter\s*[<(]/;
 // Global variant for the code-region scan (firstCodeMatchIndex sets lastIndex).
 const ROUTER_CALL_PATTERN_G = /\bcreateRouter\s*[<(]/g;
 
-function isRoutableSourceFile(name: string): boolean {
+// Test files build their own routers (a Flight test's `*.rsc-test.tsx` usually
+// mounts `createRouter({}).routes(urls(...))`); none is an app's router root.
+export function isRoutableSourceFile(name: string): boolean {
   return (
     (name.endsWith(".ts") ||
       name.endsWith(".tsx") ||
@@ -54,6 +58,7 @@ function isRoutableSourceFile(name: string): boolean {
       name.endsWith(".jsx")) &&
     !name.includes(".gen.") &&
     !name.includes(".test.") &&
+    !name.includes(".rsc-test.") &&
     !name.includes(".spec.")
   );
 }
@@ -205,13 +210,19 @@ function isCreateRouterCall(node: ts.Node): boolean {
 }
 
 function extractUrlsArgument(
-  node: ts.Expression,
+  arg: ts.Expression,
   sourceFile: ts.SourceFile,
+  urlsAliases: ReadonlySet<string>,
 ): UrlsExtractionResult | null {
+  const node = unwrapTypeOperators(arg);
   if (ts.isIdentifier(node)) {
     return { kind: "variable", name: node.text };
   }
-  if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+  if (
+    ts.isArrowFunction(node) ||
+    ts.isFunctionExpression(node) ||
+    (ts.isCallExpression(node) && isUrlsDefinitionCall(node, urlsAliases))
+  ) {
     return { kind: "inline", block: node.getText(sourceFile) };
   }
   return null;
@@ -234,24 +245,135 @@ function collectCreateRouterCallChain(
   }
 }
 
-// The first createRouter chain (in source order) that mounts urls, with its
-// extractions in runtime order. Route types and basename both come from it.
+// Local names a file exports other than by an `export` modifier on their own
+// declaration: `export { a, b as c }`, `export default a`, `export = a` and
+// `export const x = a` (a one-hop alias).
+function collectExportedLocalNames(sourceFile: ts.SourceFile): Set<string> {
+  const names = new Set<string>();
+  const addIdentifier = (expr: ts.Expression | undefined) => {
+    const node = expr && unwrapTypeOperators(expr);
+    if (node && ts.isIdentifier(node)) names.add(node.text);
+  };
+  for (const statement of sourceFile.statements) {
+    if (ts.isExportAssignment(statement)) {
+      addIdentifier(statement.expression);
+    } else if (
+      ts.isExportDeclaration(statement) &&
+      !statement.moduleSpecifier &&
+      !statement.isTypeOnly &&
+      statement.exportClause &&
+      ts.isNamedExports(statement.exportClause)
+    ) {
+      for (const element of statement.exportClause.elements) {
+        if (!element.isTypeOnly) {
+          names.add((element.propertyName ?? element.name).text);
+        }
+      }
+    } else if (
+      ts.isVariableStatement(statement) &&
+      hasModifier(statement, ts.SyntaxKind.ExportKeyword)
+    ) {
+      for (const decl of statement.declarationList.declarations) {
+        addIdentifier(decl.initializer);
+      }
+    }
+  }
+  return names;
+}
+
+// Whether a createRouter chain is the value a module exports: the initializer
+// of an exported top-level variable (or of one an export list or default
+// export names), or the `export default` / `export =` expression itself,
+// through `as`, `satisfies` and parentheses. A chain inside a function or class
+// body, an argument of another call or a property of an object literal is not
+// exported even when the enclosing declaration is.
+function isExportedChain(
+  chainEnd: ts.CallExpression,
+  exportedNames: ReadonlySet<string>,
+): boolean {
+  let current: ts.Node = chainEnd;
+  while (
+    current.parent &&
+    (ts.isAsExpression(current.parent) ||
+      ts.isSatisfiesExpression(current.parent) ||
+      ts.isParenthesizedExpression(current.parent))
+  ) {
+    current = current.parent;
+  }
+  const parent = current.parent;
+  if (!parent) return false;
+  if (ts.isExportAssignment(parent))
+    return parent.parent === current.getSourceFile();
+  if (
+    !ts.isVariableDeclaration(parent) ||
+    parent.initializer !== current ||
+    !ts.isIdentifier(parent.name)
+  ) {
+    return false;
+  }
+  const statement = parent.parent.parent;
+  if (
+    !ts.isVariableStatement(statement) ||
+    !ts.isSourceFile(statement.parent)
+  ) {
+    return false;
+  }
+  return (
+    hasModifier(statement, ts.SyntaxKind.ExportKeyword) ||
+    exportedNames.has(parent.name.text)
+  );
+}
+
+// The createRouter chain whose urls the route types and basename come from,
+// with its extractions in runtime order. A file may hold several chains (a
+// helper router beside the app's): an exported chain always wins over one that
+// is not exported, so a helper never supplies the app's routes or basename. Only when no chain is exported (a lone router in a test file)
+// does a non-exported one count. Among the candidates, the first (in source
+// order) that mounts a readable urls wins.
+// `unreadable` holds the source of each mount the static parser cannot follow
+// (`.routes(buildUrls())`, `urls: mod.tree`): its routes are missing from the
+// extractions, so detectUnresolvableIncludes reports it rather than letting
+// the gen file silently lose them. A chain with only unreadable
+// mounts is returned only when no candidate has a readable one. An exported
+// chain that mounts nothing still hides the non-exported ones.
 function findRouterUrls(sourceFile: ts.SourceFile): {
   createRouterCall: ts.CallExpression;
   extractions: UrlsExtractionResult[];
+  unreadable: string[];
 } | null {
-  let result: {
+  type RouterUrls = {
     createRouterCall: ts.CallExpression;
     extractions: UrlsExtractionResult[];
-  } | null = null;
+    unreadable: string[];
+  };
+  const exported: RouterUrls[] = [];
+  const local: RouterUrls[] = [];
+  let anyExported = false;
+  const seen = new Set<ts.CallExpression>();
+  const urlsAliases = collectUrlsImportAliases(sourceFile);
+  const exportedNames = collectExportedLocalNames(sourceFile);
 
   function visit(node: ts.Node) {
-    if (result) return;
     if (ts.isCallExpression(node)) {
       const chain = collectCreateRouterCallChain(node);
-      if (chain) {
+      if (chain && !seen.has(chain[0])) {
         const extracted: UrlsExtractionResult[] = [];
+        const unreadable: string[] = [];
         const createRouterCall = chain[0];
+        seen.add(createRouterCall);
+        // `mount` wraps the argument's source for the diagnostic; the text is
+        // only built for an argument the parser cannot read.
+        const addMount = (
+          arg: ts.Expression,
+          mount: (text: string) => string,
+        ) => {
+          const urls = extractUrlsArgument(arg, sourceFile, urlsAliases);
+          if (urls) extracted.push(urls);
+          else
+            unreadable.push(
+              mount(arg.getText(sourceFile).replace(/\s+/g, " ")),
+            );
+        };
 
         for (const callArg of createRouterCall.arguments) {
           if (!ts.isObjectLiteralExpression(callArg)) continue;
@@ -263,8 +385,7 @@ function findRouterUrls(sourceFile: ts.SourceFile): {
             ) {
               continue;
             }
-            const urls = extractUrlsArgument(prop.initializer, sourceFile);
-            if (urls) extracted.push(urls);
+            addMount(prop.initializer, (text) => `urls: ${text}`);
             break;
           }
         }
@@ -277,13 +398,17 @@ function findRouterUrls(sourceFile: ts.SourceFile): {
           ) {
             continue;
           }
-          const urls = extractUrlsArgument(call.arguments[0], sourceFile);
-          if (urls) extracted.push(urls);
+          addMount(call.arguments[0], (text) => `.routes(${text})`);
         }
 
-        if (extracted.length > 0) {
-          result = { createRouterCall, extractions: extracted };
-          return;
+        const isExported = isExportedChain(node, exportedNames);
+        if (isExported) anyExported = true;
+        if (extracted.length > 0 || unreadable.length > 0) {
+          (isExported ? exported : local).push({
+            createRouterCall,
+            extractions: extracted,
+            unreadable,
+          });
         }
       }
     }
@@ -291,27 +416,34 @@ function findRouterUrls(sourceFile: ts.SourceFile): {
   }
 
   visit(sourceFile);
-  return result;
+  const candidates = anyExported ? exported : local;
+  return (
+    candidates.find((c) => c.extractions.length > 0) ?? candidates[0] ?? null
+  );
 }
 
-function extractAllUrlsFromRouter(code: string): UrlsExtractionResult[] {
-  const sourceFile = ts.createSourceFile(
+function parseRouterSource(code: string): ts.SourceFile {
+  return ts.createSourceFile(
     "router.tsx",
     code,
     ts.ScriptTarget.Latest,
     true,
     ts.ScriptKind.TSX,
   );
-  return findRouterUrls(sourceFile)?.extractions ?? [];
+}
+
+function extractAllUrlsFromRouter(code: string): UrlsExtractionResult[] {
+  return findRouterUrls(parseRouterSource(code))?.extractions ?? [];
 }
 
 /**
  * Extract the url patterns from a router file using AST.
- * Detects four patterns:
+ * Detects these patterns, in either mount (`.routes(x)` or `urls: x`):
  *   1. createRouter(...).routes(variableName)
  *   2. createRouter({ urls: variableName, ... })
  *   3. createRouter(...).routes(({ path, ... }) => [...])
  *   4. createRouter({ urls: ({ path, ... }) => [...], ... })
+ *   5. createRouter(...).routes(urls(({ path, ... }) => [...])), and clientUrls()
  * Returns either a variable name or an inline code block.
  */
 export function extractUrlsFromRouter(
@@ -322,7 +454,11 @@ export function extractUrlsFromRouter(
 }
 
 function unwrapTypeOperators(expr: ts.Expression): ts.Expression {
-  while (ts.isAsExpression(expr) || ts.isSatisfiesExpression(expr)) {
+  while (
+    ts.isAsExpression(expr) ||
+    ts.isSatisfiesExpression(expr) ||
+    ts.isParenthesizedExpression(expr)
+  ) {
     expr = expr.expression;
   }
   return expr;
@@ -699,12 +835,21 @@ export function detectUnresolvableIncludes(
     return [];
   }
 
-  const extractions = extractAllUrlsFromRouter(source);
-  if (extractions.length === 0) return [];
+  const routerUrls = findRouterUrls(parseRouterSource(source));
+  if (!routerUrls) return [];
 
   const diagnostics: UnresolvableInclude[] = [];
+  for (const mount of routerUrls.unreadable) {
+    diagnostics.push({
+      pathPrefix: "/",
+      namePrefix: null,
+      reason: "unresolvable-routes",
+      sourceFile: realPath,
+      detail: `\`${mount}\` is not a urls() call (as imported from @rangojs/router), a builder function or a variable; its routes would be missing`,
+    });
+  }
   const memo = createScanMemo();
-  for (const extraction of extractions) {
+  for (const extraction of routerUrls.extractions) {
     resolveRouterUrlsExtraction(
       realPath,
       source,

package/src/build/route-types/scan-filter.ts

@@ -10,6 +10,7 @@ export const DEFAULT_EXCLUDE_PATTERNS: string[] = [
   "**/dist/**",
   "**/coverage/**",
   "**/*.test.{ts,tsx,js,jsx}",
+  "**/*.rsc-test.{ts,tsx,js,jsx}",
   "**/*.spec.{ts,tsx,js,jsx}",
 ];
 

package/src/build/runtime-discovery.ts

@@ -37,10 +37,12 @@ export async function discoverAndWriteRouteTypes(
   outputFiles: string[];
 }> {
   let loadConfigFromFile: typeof import("vite").loadConfigFromFile;
+  let resolveConfig: typeof import("vite").resolveConfig;
 
   try {
     const vite = await import("vite");
     loadConfigFromFile = vite.loadConfigFromFile;
+    resolveConfig = vite.resolveConfig;
   } catch {
     throw new Error(
       "Runtime discovery requires 'vite'. Install it with: pnpm add -D vite",
@@ -59,14 +61,19 @@ export async function discoverAndWriteRouteTypes(
   const { createDiscoveryState } = await import("../vite/discovery/state.js");
   const { discoverClientUrlProjections } =
     await import("../vite/discovery/client-urls-projection.js");
-  const { pickForwardedRunnerConfig, selectForwardableResolvePlugins } =
-    await import("../vite/utils/forward-user-plugins.js");
+  const {
+    isFrameworkPlugin,
+    pickForwardedRunnerConfig,
+    selectForwardableResolvePlugins,
+  } = await import("../vite/utils/forward-user-plugins.js");
 
   // The discovery temp server of `vite dev/build` (expose-internal-ids, the
   // cloudflare:* stubs, the user's resolver plugins and resolve/define/oxc).
-  // The config stays unresolved: resolving it would run rango()'s
-  // configResolved, which writes the static gen files. Forwarded resolvers
-  // therefore run without their own config/configResolved hooks.
+  // Resolver plugins are forwarded from a resolved config, as `vite dev` does:
+  // vite-tsconfig-paths and the like build their matchers in config /
+  // configResolved, and resolving drops `apply: "build"` plugins. The
+  // framework plugins are left out of that resolve: rango()'s configResolved
+  // writes the static gen files.
   const entryPath = resolve(opts.entry);
   const state = createDiscoveryState(entryPath, undefined);
   state.projectRoot = opts.root;
@@ -80,9 +87,40 @@ export async function discoverAndWriteRouteTypes(
       );
       if (loaded) {
         state.userRunnerConfig = pickForwardedRunnerConfig(loaded.config);
-        state.userResolvePlugins = selectForwardableResolvePlugins(
-          await flattenPluginOptions(loaded.config.plugins),
-        );
+        const userPlugins = (
+          await flattenPluginOptions(loaded.config.plugins)
+        ).filter((p) => !isFrameworkPlugin(p.name ?? ""));
+        try {
+          // The temp server's root, so a resolver's root-relative state
+          // matches the server it runs in.
+          const resolved = await resolveConfig(
+            {
+              ...loaded.config,
+              root: opts.root,
+              configFile: false,
+              plugins: userPlugins,
+            },
+            "serve",
+            "development",
+          );
+          state.userResolvePlugins = selectForwardableResolvePlugins(
+            resolved.plugins,
+          );
+        } catch (err: any) {
+          console.warn(
+            `[rango] Could not resolve the Vite config (${err?.message ?? err}); forwarding its resolver plugins without their config hooks. rango() and rsc() are left out of that resolve, so a plugin that needs the rsc environment fails there`,
+          );
+          // The resolve would have applied `apply`; do the same for the serve
+          // pass, including the function form.
+          const serveEnv = { command: "serve", mode: "development" } as const;
+          state.userResolvePlugins = selectForwardableResolvePlugins(
+            userPlugins.filter((p) =>
+              typeof p.apply === "function"
+                ? p.apply(loaded.config, serveEnv)
+                : p.apply !== "build",
+            ),
+          );
+        }
       }
     } catch (err: any) {
       // Discovery without the app's resolvers fails later on an unrelated

package/src/cache/cache-key-utils.ts

@@ -187,9 +187,10 @@ export const KEY_PART_PREFIX = "key:";
  * (CacheScope.resolveKeyFrom, CacheScope.resolvePartition): the `key()`
  * results of the scope's cache() chain, outermost first, then its default
  * parts: the keyGenerator results of enclosing scopes on another store
- * (#974) and, for a route record key, the scope's own part: without a
+ * (#974) and, for a route record key, the scope's own parts: without a
  * `key()` of its own, its default key (or its store's keyGenerator result,
- * #970); with one, the default key's request kind (`doc`, `partial` or
+ * #970, then the request kind when that result does not start with it,
+ * #1298); with one, the default key's request kind (`doc`, `partial` or
  * `intercept:<intercept>`, routeRecordKind in cache-scope.ts).
  *
  * Key scheme invariant (#975). A `key()` result is often request input,
@@ -209,7 +210,9 @@ export const KEY_PART_PREFIX = "key:";
  * - one `key()` part is the key; two or more parts are joined by `|`,
  *   `key()` parts first;
  * - a lone default part stays raw: with no `key()` on the chain the record
- *   key is the default key or the store's keyGenerator result, unchanged.
+ *   key is the default key or the store's keyGenerator result, unchanged
+ *   when that result starts with its request kind, else that result and
+ *   the kind composed (`items|doc`).
  *
  * Why nothing collides: the router's default keys (`doc:`, `partial:`,
  * `intercept:`, `response:<type>:`) never start with `key:` and hold a `:`.
@@ -218,11 +221,12 @@ export const KEY_PART_PREFIX = "key:";
  * Among composed keys, splitting on `|` recovers each part, a part's kind
  * (a `key:` prefix, or no `:` at all) and its value. A request kind part is
  * a default key's prefix without the URL after it, so it never equals a
- * default key part; a keyGenerator part can equal it (`doc`) only when the
- * keyGenerator returns a constant, which already gives every URL one record.
- * Pinned by the collision probe in
- * src/cache/__tests__/cache-scope-chain.test.ts. A keyGenerator result is
- * the store's own namespace, as before.
+ * default key part. A raw keyGenerator record key starts with its kind and
+ * holds a `:`, so it never equals a composed one, and two kinds' prefixes
+ * differ; a result without its kind is composed with it, never prefixed,
+ * since `doc:` + `x` would be the raw result `doc:x`. Pinned by the
+ * collision probes in src/cache/__tests__/cache-scope-chain.test.ts. A
+ * keyGenerator result is the store's own namespace, as before.
  *
  * Shared with the testing helper `shellCacheKey`, so a test builds the
  * production partition.

package/src/cache/cache-runtime.ts

@@ -25,6 +25,7 @@ import {
   runAsBackgroundWork,
   type RequestContext,
 } from "../server/request-context.js";
+import { segmentPinOf } from "../server/context.js";
 import { isUnderTestRunner } from "../runtime-env.js";
 import {
   isTainted,
@@ -505,8 +506,11 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         if (ctx.body !== undefined || ctx.formData !== undefined) {
           hasBodyCtx = true;
         }
+        // Only an argument with a pin (a handler or loader ctx, or its copy)
+        // is the caller: a request context before it has no claim.
         if (callerSegmentId === undefined) {
-          callerSegmentId = ctx._currentSegmentId;
+          callerSegmentId =
+            ctx._currentSegmentId === undefined ? undefined : segmentPinOf(ctx);
           claimLoaderPushes = ctx._claimLoaderPushes;
         }
         if (ctx.params && typeof ctx.params === "object") {