@rangojs/router 0.16.0 → 0.18.0

package/dist/testing/vitest.js

@@ -1,6 +1,233 @@
 // src/testing/vitest.ts
 import { createRequire } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
+
+// src/vite/plugins/use-cache-transform.ts
+import path2 from "node:path";
+
+// src/vite/plugins/expose-id-utils.ts
+import path from "node:path";
+import crypto from "node:crypto";
+function normalizePath(p) {
+  return p.split(path.sep).join("/");
+}
+function hashId(filePath, exportName) {
+  const input = `${filePath}#${exportName}`;
+  const hash = crypto.createHash("sha256").update(input).digest("hex");
+  return `${hash.slice(0, 8)}#${exportName}`;
+}
+
+// src/vite/plugins/use-cache-transform.ts
+var CACHE_RUNTIME_IMPORT = "@rangojs/router/cache-runtime";
+var LAYOUT_TEMPLATE_PATTERN = /\/(layout|template)\.(tsx?|jsx?)$/;
+var USE_CACHE_DIRECTIVE_RE = /^use cache(:\s*[\w-]+)?$/;
+function isUseCacheCandidate(code, id) {
+  return (
+    // Quick bail: no "use cache" in source
+    code.includes("use cache") && // Skip node_modules and virtual modules
+    !id.includes("/node_modules/") && !id.startsWith("\0") && // Only JS/TS files
+    /\.(tsx?|jsx?|mjs)$/.test(id)
+  );
+}
+var rscTransforms = null;
+async function transformUseCache(code, id, options) {
+  if (!rscTransforms) {
+    try {
+      rscTransforms = await import("@vitejs/plugin-rsc/transforms");
+    } catch (error) {
+      options.onTransformsError?.(error);
+      return;
+    }
+  }
+  const { hasDirective, transformWrapExport, transformHoistInlineDirective } = rscTransforms;
+  let ast;
+  try {
+    const { parseAst } = await import("vite");
+    ast = parseAst(code, { lang: "tsx" });
+  } catch {
+    return;
+  }
+  stripNullDirectiveFields(ast);
+  const filePath = normalizePath(path2.relative(options.root, id));
+  const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
+  if (hasDirective(ast.body, "use cache")) {
+    return transformFileLevelUseCache(
+      code,
+      ast,
+      filePath,
+      id,
+      options.isBuild,
+      isLayoutOrTemplate,
+      transformWrapExport,
+      hasDirective
+    );
+  }
+  const functionResult = transformFunctionLevelUseCache(
+    code,
+    ast,
+    filePath,
+    id,
+    options.isBuild,
+    transformHoistInlineDirective
+  );
+  warnOnNearMissDirectives(ast, id, options.warn);
+  if (functionResult) return functionResult;
+}
+async function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLayoutOrTemplate, transformWrapExport, hasDirective) {
+  const unconfirmedExports = [];
+  const { exportNames, output } = transformWrapExport(code, ast, {
+    runtime: (value, name) => {
+      const funcId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
+      return `__rango_registerCachedFunction(${value}, ${JSON.stringify(funcId)}, "default")`;
+    },
+    rejectNonAsyncFunction: false,
+    filter: (name, meta) => {
+      if (name === "default" && isLayoutOrTemplate) return false;
+      if (name.startsWith("$$hoist_")) return false;
+      if (isHoistedServerReferenceRebind(meta.valueNode)) return false;
+      if (functionHasUseServerDirective(meta.valueNode, hasDirective)) {
+        return false;
+      }
+      if (meta.isFunction !== true) {
+        unconfirmedExports.push(name);
+        return false;
+      }
+      return true;
+    }
+  });
+  if (unconfirmedExports.length > 0) {
+    const plural = unconfirmedExports.length > 1;
+    throw new Error(
+      `[rango:use-cache] File-level "use cache" in ${sourceId} only wraps exports that are statically-confirmed functions. ${plural ? "These exports are" : "This export is"} not: ${unconfirmedExports.map((n) => `"${n}"`).join(", ")}. Declare them directly (export async function foo() {} or export const foo = async () => {}). A factory or otherwise statically-indeterminate initializer (export const foo = makeCached(fn)) is rejected even if it returns a function at runtime -- rewrite it as a direct async function, or move non-function exports to a separate module.`
+    );
+  }
+  if (exportNames.length === 0) {
+    const { default: MagicString } = await import("magic-string");
+    const s = new MagicString(code);
+    const directive2 = findFileLevelDirective(ast);
+    if (directive2) {
+      s.overwrite(
+        directive2.start,
+        directive2.end,
+        `/* "use cache" -- wrapped by rango */`
+      );
+      return {
+        code: s.toString(),
+        map: s.generateMap({ source: sourceId, hires: "boundary" })
+      };
+    }
+    return;
+  }
+  output.prepend(
+    `import { registerCachedFunction as __rango_registerCachedFunction } from ${JSON.stringify(CACHE_RUNTIME_IMPORT)};
+`
+  );
+  const directive = findFileLevelDirective(ast);
+  if (directive) {
+    output.overwrite(
+      directive.start,
+      directive.end,
+      `/* "use cache" -- wrapped by rango */`
+    );
+  }
+  return {
+    code: output.toString(),
+    map: output.generateMap({ source: sourceId, hires: "boundary" })
+  };
+}
+function transformFunctionLevelUseCache(code, ast, filePath, sourceId, isBuild, transformHoistInlineDirective) {
+  try {
+    const { output, names } = transformHoistInlineDirective(code, ast, {
+      directive: USE_CACHE_DIRECTIVE_RE,
+      runtime: (value, name, meta) => {
+        const funcId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
+        const profileMatch = meta.directiveMatch[1];
+        const profileName = profileMatch ? profileMatch.replace(/^:\s*/, "").trim() : "default";
+        return `__rango_registerCachedFunction(${value}, ${JSON.stringify(funcId)}, ${JSON.stringify(profileName)})`;
+      },
+      rejectNonAsyncFunction: false
+    });
+    if (names.length === 0) return;
+    output.prepend(
+      `import { registerCachedFunction as __rango_registerCachedFunction } from ${JSON.stringify(CACHE_RUNTIME_IMPORT)};
+`
+    );
+    return {
+      code: output.toString(),
+      map: output.generateMap({ source: sourceId, hires: "boundary" })
+    };
+  } catch {
+    return;
+  }
+}
+function stripNullDirectiveFields(node) {
+  if (!node || typeof node !== "object") return;
+  const rec = node;
+  if (rec.type === "ExpressionStatement" && typeof rec.directive !== "string") {
+    delete rec.directive;
+  }
+  for (const value of Object.values(rec)) {
+    if (Array.isArray(value)) {
+      for (const item of value) stripNullDirectiveFields(item);
+    } else if (value && typeof value === "object" && "type" in value) {
+      stripNullDirectiveFields(value);
+    }
+  }
+}
+function isHoistedServerReferenceRebind(valueNode) {
+  if (!valueNode || valueNode.type !== "CallExpression") return false;
+  const first = valueNode.arguments[0];
+  return first !== void 0 && first.type === "Identifier" && first.name.startsWith("$$hoist_");
+}
+function functionHasUseServerDirective(valueNode, hasDirective) {
+  if (!valueNode || !("body" in valueNode)) return false;
+  const { body } = valueNode;
+  if (!body || Array.isArray(body) || body.type !== "BlockStatement") {
+    return false;
+  }
+  return hasDirective(
+    body.body,
+    "use server"
+  );
+}
+function findFileLevelDirective(ast) {
+  for (const node of ast.body ?? []) {
+    if (node.type === "ExpressionStatement" && node.expression?.type === "Literal" && typeof node.expression.value === "string" && node.expression.value.startsWith("use cache")) {
+      return { start: node.start, end: node.end };
+    }
+  }
+  return null;
+}
+var NEAR_MISS_RE = /^use cache:\s*.+$/;
+function warnOnNearMissDirectives(ast, fileId, warn) {
+  const visit = (node) => {
+    if (!node || typeof node !== "object") return;
+    if (node.type === "ExpressionStatement" && node.expression?.type === "Literal" && typeof node.expression.value === "string") {
+      const value = node.expression.value;
+      if (value.startsWith("use cache") && NEAR_MISS_RE.test(value) && !USE_CACHE_DIRECTIVE_RE.test(value)) {
+        const profilePart = value.slice("use cache:".length).trim();
+        warn(
+          `[rango:use-cache] "${value}" in ${fileId} has an invalid profile name "${profilePart}". Profile names must match [a-zA-Z0-9_-]+. This directive will be ignored.`
+        );
+      }
+    }
+    for (const key of Object.keys(node)) {
+      const child = node[key];
+      if (Array.isArray(child)) {
+        for (const item of child) {
+          visit(item);
+        }
+      } else if (child && typeof child === "object" && child.type) {
+        visit(child);
+      }
+    }
+  };
+  for (const node of ast.body ?? []) {
+    visit(node);
+  }
+}
+
+// src/testing/vitest.ts
 function here(relativeFromRoot) {
   return fileURLToPath(new URL(`../../${relativeFromRoot}`, import.meta.url));
 }
@@ -94,9 +321,34 @@ function rangoUseClientTransform() {
     }
   };
 }
+function rangoUseCacheTransform() {
+  let root = process.cwd();
+  return {
+    name: "rango:testing-use-cache",
+    enforce: "post",
+    configResolved(config) {
+      root = config.root;
+    },
+    async transform(code, id) {
+      if (!isUseCacheCandidate(code, id)) return void 0;
+      return transformUseCache(code, id, {
+        root,
+        isBuild: false,
+        warn: (message) => this.warn(message),
+        onTransformsError: (error) => {
+          throw new Error(
+            `rangoUseCacheTransform: @vitejs/plugin-rsc/transforms failed to load, so "use cache" functions in ${id} would run unwrapped.`,
+            { cause: error }
+          );
+        }
+      });
+    }
+  };
+}
 export {
   rangoInlineDeps,
   rangoTestAliases,
   rangoTestConfig,
+  rangoUseCacheTransform,
   rangoUseClientTransform
 };

package/dist/types/browser/cookie-name.d.ts

@@ -12,6 +12,12 @@
  */
 /** Default prefix when `stateCookiePrefix` is unset or empty after sanitization. */
 export declare const DEFAULT_STATE_COOKIE_PREFIX = "rango-state";
+/**
+ * The fresh-reads cookie name for a router's resolved state cookie name
+ * (`{prefix}_{routerId}`; the prefix never contains `_`, see
+ * router/state-cookie-name.ts).
+ */
+export declare function freshReadsCookieName(stateCookieName: string): string;
 /** Internal response header carrying the keepClientCache() directive. */
 export declare const KEEP_CACHE_HEADER = "x-rango-keep-cache";
 /** True for a per-client signal header. */

package/dist/types/browser/history-state.d.ts

@@ -18,6 +18,22 @@ export declare function buildHistoryState(userState: unknown, routerState?: {
  * relying on the Navigation API.
  */
 export declare function pushHistoryWithIdx(state: Record<string, unknown> | null, url: string, replace: boolean): void;
+/**
+ * The forced-MISS reload marker (`SHELL_MISS_PARAM` in rsc/shell-serve.ts,
+ * which the browser bundle must not import): a degraded PPR shell HIT
+ * reloads the page with it, and the server renders a marked request like a
+ * cache miss.
+ */
+export declare const SHELL_MISS_MARKER: string;
+/**
+ * Drop the forced-MISS marker from the address bar at boot, keeping the
+ * history entry's state (initBrowserApp calls it before any location read).
+ * Left in place, a refresh or a shared link would stay off the shell and the
+ * app's search params would carry it. The server strips the same marker from
+ * the request before rendering (shell-serve.ts withoutShellMissMarker), so
+ * the page was rendered for the clean URL and the hydrating client agrees.
+ */
+export declare function stripShellMissMarker(): void;
 /**
  * Merge server-set location state into the current history entry.
  * Replaces the current history state and dispatches notification event

package/dist/types/browser/navigation-transaction.d.ts

@@ -22,6 +22,12 @@ interface CommitOptions {
     cacheOnly?: boolean;
     /** Server-set location state to merge into history.pushState */
     serverState?: Record<string, unknown>;
+    /**
+     * Back/forward: history is already at this entry. Its state (scroll key,
+     * location state, idx) stays as the browser restored it; serverState is
+     * merged in. The page left was saved by handleTraversalStart.
+     */
+    traversal?: boolean;
 }
 /**
  * Options that can override the pre-configured commit settings

package/dist/types/browser/partial-update.d.ts

@@ -2,6 +2,17 @@ import type { NavigationStore, NavigationClient, UpdateSubscriber, ResolvedSegme
 import type { ReactNode } from "react";
 import type { RenderSegmentsOptions } from "../segment-system.js";
 import type { BoundTransaction } from "./navigation-transaction.js";
+import type { NavigationUpdate } from "./types.js";
+export declare function shouldStartViewTransition(segments: ResolvedSegment[]): boolean;
+/**
+ * Transition commit. Every held commit announces the loader streams the
+ * committed tree is still receiving (loader-store.ts announcePendingStreams)
+ * so held useLoader readers pin isLoading:true until this transition lands;
+ * settled/cached segments make it a no-op. Urgent commits call onUpdate
+ * directly: nothing is held there, a reader of a pending stream suspends to
+ * its fallback. Also used by renderRoute's navigate() (testing/render-route.tsx).
+ */
+export declare function commitInTransition(onUpdate: UpdateSubscriber, segments: readonly ResolvedSegment[], update: NavigationUpdate, transitionTypes: readonly string[]): void;
 /**
  * Configuration for creating a partial updater
  */

package/dist/types/browser/react/ScrollRestoration.d.ts

@@ -1,5 +1,5 @@
 /**
- * Props for ScrollRestoration component
+ * Props for `<Html.ScrollRestoration />`.
  */
 export interface ScrollRestorationProps {
     /**
@@ -20,10 +20,10 @@ export interface ScrollRestorationProps {
      * const byPathname = (location) => location.pathname;
      *
      * // Restore based on pathname (same URL = same scroll)
-     * <ScrollRestoration getKey={byPathname} />
+     * <Html.ScrollRestoration getKey={byPathname} />
      *
      * // Restore based on unique history entry (default)
-     * // <ScrollRestoration /> — omit getKey to use location.key
+     * // <Html.ScrollRestoration /> — omit getKey to use location.key
      * ```
      */
     getKey?: (location: {
@@ -34,7 +34,7 @@ export interface ScrollRestorationProps {
     }) => string;
 }
 /**
- * ScrollRestoration component
+ * Public as `Html.ScrollRestoration` (`@rangojs/router/client`).
  *
  * Enables scroll position restoration across navigations:
  * - Saves scroll positions to sessionStorage
@@ -51,7 +51,7 @@ export interface ScrollRestorationProps {
  *   return (
  *     <html>
  *       <body>
- *         <ScrollRestoration />
+ *         <Html.ScrollRestoration />
  *         {children}
  *       </body>
  *     </html>
@@ -63,7 +63,7 @@ export declare function ScrollRestoration({ getKey }: ScrollRestorationProps): n
 /**
  * Hook to initialize scroll restoration
  *
- * Alternative to the ScrollRestoration component for more control.
+ * Alternative to `<Html.ScrollRestoration />` for more control.
  *
  * @example
  * ```tsx

package/dist/types/browser/rsc-router.d.ts

@@ -126,7 +126,7 @@ export interface RangoProps {
  *
  * @example
  * ```tsx
- * import { initBrowserApp, Rango } from "rsc-router/browser";
+ * import { initBrowserApp, Rango } from "@rangojs/router/browser";
  * import { rscStream } from "rsc-html-stream/client";
  * import * as rscBrowser from "@vitejs/plugin-rsc/browser";
  *

package/dist/types/browser/scroll-restoration.d.ts

@@ -84,6 +84,13 @@ export declare function scrollToTop(): void;
  * - Ensures new history entry has a key
  */
 export declare function handleNavigationStart(): void;
+/**
+ * Handle scroll for a back/forward traversal, at popstate before anything
+ * renders: save the page being left under ITS key (history has already moved,
+ * so saveCurrentScrollPosition would use the destination's key) and track the
+ * destination as the displayed entry.
+ */
+export declare function handleTraversalStart(): void;
 /**
  * Handle scroll after navigation completes.
  * @param options.restore - If true, restore saved position (for popstate)

package/dist/types/cache/cache-exec-scope.d.ts

@@ -22,10 +22,27 @@
  * registration below wires assertNotInsideCacheExec to this scope without
  * taint.ts importing it.
  */
+/**
+ * One "use cache" execution. Identity matters: the execution's handle capture
+ * (cache-runtime.ts) records only pushes from its own chain, including cached
+ * functions it calls (`parent` links them), not concurrent pushes into the
+ * same request store.
+ */
+export interface CacheExecScope {
+    readonly parent?: CacheExecScope;
+}
 /**
  * Run fn with the "use cache" execution scope active. Continuations spawned
  * from fn's synchronous kickoff inherit the scope; parallel chains do not.
+ * Pass `scope` (createCacheExecScope) to test membership with
+ * isInCacheExecChain.
  */
-export declare function runWithCacheExecScope<T>(fn: () => T): T;
+export declare function runWithCacheExecScope<T>(fn: () => T, scope?: CacheExecScope): T;
+/** A scope nested in the calling chain's current one, if any. */
+export declare function createCacheExecScope(): CacheExecScope;
 /** True when the calling async chain is inside a "use cache" body. */
 export declare function isInsideCacheExecScope(): boolean;
+/** The calling chain's innermost "use cache" scope, if any. */
+export declare function getCacheExecScope(): CacheExecScope | undefined;
+/** True when the calling async chain runs inside `scope`, at any depth. */
+export declare function isInCacheExecChain(scope: CacheExecScope): boolean;

package/dist/types/cache/cache-key-utils.d.ts

@@ -2,8 +2,8 @@
  * Shared Cache Key Utilities
  *
  * Deterministic normalization of search params and route params
- * for cache key generation. Used by cache-runtime, cache-scope,
- * document-cache, and loader-cache.
+ * for cache key generation, and the composition of nested cache() keys.
+ * Used by cache-runtime, cache-scope, document-cache, and loader-cache.
  */
 import type { SearchParamsFilter } from "./search-params-filter.js";
 /**
@@ -41,3 +41,18 @@ export declare function sortedRouteParams(params: Record<string, string> | undef
  * tier-specific suffixes (`:rsc`/`:html`, segment hash) after this base.
  */
 export declare function cacheKeyBase(host: string, pathname: string, searchParams?: URLSearchParams, params?: Record<string, string>, filter?: SearchParamsFilter): string;
+/**
+ * The record key, or shell partition, of nested keyed cache() scopes (#970)
+ * from its parts, outermost first: the chain's `key()` results and, for an
+ * inner scope without its own `key()`, that scope's default key
+ * (CacheScope.resolveKeyFrom). One part is returned raw, so a single keyed
+ * scope keeps its key byte for byte. Two or more are joined by `|`, each
+ * URI-encoded (like partitionShellKey, rsc/shell-capture-constants.ts): an
+ * encoded part holds no `|`, so every tuple maps to its own key, of any
+ * depth. Raw, `("a|b", "c")` and `("a", "b|c")` named one record. A composed
+ * key holds no `:` either, so a single raw result with one (a prefixed
+ * `tier:...`, a `doc:` default key) never equals it; an unprefixed raw result
+ * can. Shared with the testing helper `shellCacheKey`, which composes a
+ * nested partition the same way.
+ */
+export declare function composeCacheKeys(parts: readonly string[]): string;

package/dist/types/cache/cache-policy.d.ts

@@ -42,6 +42,23 @@ export declare function resolveTtl(explicit: number | undefined, defaults: Cache
  * non-finite/negative (degrade rather than feed bad math into expiry).
  */
 export declare function resolveSwrWindow(explicit: number | undefined, defaults: CacheDefaults | undefined): number;
+/**
+ * Minimum age (ms) of a stale PPR shell before a HIT schedules its recapture.
+ * A shell capped to a route cache() record inside its swr window is stale
+ * from the start (rsc/shell-capture.ts capShellWindow), so without a floor
+ * every HIT of it recaptured, and a capture's store write is one KV write per
+ * key: Cloudflare KV accepts one per second per key. Inside the floor the
+ * stale shell is still served. Per isolate: each isolate's stale HIT past the
+ * floor can schedule one (stampede-guarded per isolate).
+ */
+export declare const SHELL_MIN_RECAPTURE_INTERVAL_MS = 1000;
+/**
+ * Whether a stale shell HIT schedules its recapture (see the floor above).
+ * Fails open: an entry without a numeric `createdAt` recaptures.
+ */
+export declare function staleShellRecaptureDue(entry: {
+    readonly createdAt?: number;
+}, now: number): boolean;
 /**
  * Compute staleAt and expiresAt timestamps from TTL and SWR window.
  *