@rangojs/router 0.32.0 → 0.33.1

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.
@@ -885,14 +885,19 @@ export function createServerActionBridge(
         throw new Error("No matched segments in response");
       }
 
-      // Reconcile server segments with cached segments (single source of truth)
-      const reconciled = reconcileSegments({
-        actor: "action",
-        matched,
-        diff: diff || [],
-        serverSegments: segments || [],
-        cachedSegments,
-      });
+      // Reconcile server segments with cached segments (single source of
+      // truth). A page that left commits nothing (navigated-away), and the
+      // cache on screen is another page's: reconciling would report missing
+      // segments.
+      const reconciled = navigatedSince()
+        ? { segments: [], mainSegments: [], interceptSegments: [] }
+        : reconcileSegments({
+            actor: "action",
+            matched,
+            diff: diff || [],
+            serverSegments: segments || [],
+            cachedSegments,
+          });
       const fullSegments = reconciled.segments;
 
       const returnData = returnValue?.data;

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/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") {

package/src/cache/cache-scope.ts

@@ -235,6 +235,22 @@ function positionalParts(parts: readonly (string | null)[]): string[] {
     : parts.map((part) => part ?? "");
 }
 
+/**
+ * A route record key's own parts (CacheScope.resolveKeyFrom): `own`, the
+ * scope's default key or its store's keyGenerator result (undefined under a
+ * `key()` of its own), then the request `kind` unless `own` starts with
+ * `{kind}:`. A default key does, and so does a keyGenerator result built on
+ * `defaultKey` (`${defaultKey}|x`), which stays byte for byte. One that
+ * ignores `defaultKey` (a constant, the pathname) gave a document, a
+ * navigation and each intercept navigation one record, so a document GET
+ * rendered an intercept's. The kind is a part, never a `{kind}:` prefix: a
+ * prefix would give the results `x` and `doc:x` one record.
+ */
+function ownParts(own: string | undefined, kind: string | undefined): string[] {
+  if (own === undefined) return kind === undefined ? [] : [kind];
+  return kind === undefined || own.startsWith(`${kind}:`) ? [own] : [own, kind];
+}
+
 /**
  * One key resolution per request, resolver (`by`: a `key()` or a store's
  * keyGenerator) and `slot`, held on the request context (`_resolvedCacheKeys`,
@@ -530,8 +546,10 @@ export class CacheScope {
    * replaces the URL part, and its store's keyGenerator does not run. It
    * appends `kind` instead (routeRecordKind): the `key()` decides which
    * requests of one kind share a record, never that a document, a
-   * navigation and an intercept navigation do. With no partition part it is
-   * resolveDefaultKey alone. With a `key()` on the chain but no request
+   * navigation and an intercept navigation do. A keyGenerator result that
+   * does not start with its kind gets `kind` after it too (ownParts). With
+   * no partition part it is resolveDefaultKey alone, or that result and
+   * `kind` composed. With a `key()` on the chain but no request
    * context it rejects (keyWithoutContextError). `partitionedPrefix`
    * prefixes a key built from partition parts only (the response family's
    * `response:`, which passes no `kind`: a response route answers every
@@ -556,7 +574,9 @@ export class CacheScope {
     if (!requestCtx || !this.mayPartition) {
       return this.keyFns.length > 0
         ? Promise.reject(keyWithoutContextError())
-        : this.resolveDefaultKey(requestCtx, defaultKey);
+        : this.resolveDefaultKey(requestCtx, defaultKey).then((own) =>
+            composeCacheKeys([], ownParts(own, kind)),
+          );
     }
     return Promise.all([
       this.resolvePartitionParts(requestCtx, defaultKey),
@@ -565,10 +585,11 @@ export class CacheScope {
         : this.resolveDefaultKey(requestCtx, defaultKey),
     ]).then(([[keys, storeParts], ownDefault]) => {
       const generated = positionalParts(storeParts);
-      if (keys.length === 0 && generated.length === 0) return ownDefault!;
-      const last = ownDefault ?? kind;
-      if (last !== undefined) generated.push(last);
-      return partitionedPrefix + composeCacheKeys(keys, generated);
+      const own = ownParts(ownDefault, kind);
+      if (keys.length === 0 && generated.length === 0) {
+        return composeCacheKeys([], own);
+      }
+      return partitionedPrefix + composeCacheKeys(keys, [...generated, ...own]);
     });
   }
 

package/src/cache/cf/cf-cache-types.ts

@@ -419,19 +419,23 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
   /**
    * Custom key generator applied to all cache operations.
    * Receives the full RequestContext (including env) 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), except that a route record keeps its request kind: a result that
+   * does not start with `defaultKey`'s prefix (`doc:`, `partial:`,
+   * `intercept:<intercept>:`) gets the kind appended (see
+   * SegmentCacheStore.keyGenerator).
    *
    * Reserved prefixes: tag-invalidation markers live in the SAME KV namespace as
    * data, keyed `__tag__/<tag>` (and `__tagmarker__/<tag>` for the L1 cache). A
    * returned key must NOT begin with `__tag__/` or `__tagmarker__/`, or it can
    * collide with a tag marker and corrupt invalidation. The documented
-   * prepend-style generators below are safe.
+   * generators below start with `defaultKey` and are safe.
    *
    * @example Using headers for user segmentation
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
    *   const segment = ctx.request.headers.get('x-user-segment') || 'default';
-   *   return `${segment}:${defaultKey}`;
+   *   return `${defaultKey}|${segment}`;
    * }
    * ```
    *
@@ -439,7 +443,7 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
    *   const region = ctx.env.REGION || 'us';
-   *   return `${region}:${defaultKey}`;
+   *   return `${defaultKey}|${region}`;
    * }
    * ```
    *
@@ -447,7 +451,7 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
    *   const locale = cookies().get('locale')?.value || 'en';
-   *   return `${locale}:${defaultKey}`;
+   *   return `${defaultKey}|${locale}`;
    * }
    * ```
    */