@rangojs/router 0.24.4 → 0.25.0

package/README.md

@@ -540,6 +540,7 @@ Use it when you need it:
 | multi-column layouts, independent slots         | [`/parallel`](./skills/parallel/SKILL.md)                                                    |
 | open a route as a modal on soft navigation      | [`/intercept`](./skills/intercept/SKILL.md)                                                  |
 | compose route modules / sub-apps                | [`/route`](./skills/route/SKILL.md), [`/composability`](./skills/composability/SKILL.md)     |
+| lay out a whole app                             | [`/app-structure`](./skills/app-structure/SKILL.md)                                          |
 | cache a single function or component            | [`/use-cache`](./skills/use-cache/SKILL.md), [`/cache-guide`](./skills/cache-guide/SKILL.md) |
 | feed live loaders from a cached shell           | [`/shell-manifest`](./skills/shell-manifest/SKILL.md)                                        |
 | edge caching with Cache-Control                 | [`/document-cache`](./skills/document-cache/SKILL.md)                                        |

package/dist/bin/rango.js

@@ -160,7 +160,9 @@ function generatePerModuleTypesSource(routes) {
     }
     deduped.set(name, { pattern, params, search });
   }
-  const sorted = [...deduped.entries()].sort(([a], [b]) => a.localeCompare(b));
+  const sorted = [...deduped.entries()].sort(
+    ([a], [b]) => a.localeCompare(b, "en")
+  );
   const body = sorted.map(([name, { pattern, params, search }]) => {
     const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `"${name}"`;
     return formatRouteEntry(key, pattern, params, search);
@@ -173,7 +175,7 @@ export type routes = typeof routes;
 `;
 }
 function generateRouteTypesSource(routeManifest, searchSchemas) {
-  const entries = Object.entries(routeManifest).filter(([name]) => !isAutoGeneratedRouteName(name)).sort(([a], [b]) => a.localeCompare(b));
+  const entries = Object.entries(routeManifest).filter(([name]) => !isAutoGeneratedRouteName(name)).sort(([a], [b]) => a.localeCompare(b, "en"));
   const filteredSearchSchemas = searchSchemas ? Object.fromEntries(
     Object.entries(searchSchemas).filter(
       ([name]) => !isAutoGeneratedRouteName(name)
@@ -817,51 +819,68 @@ function findUrlsVariableNames(code) {
   visit(sourceFile);
   return names;
 }
-function writePerModuleRouteTypesForFile(filePath) {
-  try {
-    const source = readFileSync2(filePath, "utf-8");
-    if (!source.includes("urls(") && !source.includes("clientUrls(")) return;
-    const varNames = findUrlsVariableNames(source);
-    let routes;
-    if (varNames.length > 0) {
-      routes = [];
-      const memo = createScanMemo();
-      for (const varName of varNames) {
-        const { routes: routeMap, searchSchemas } = buildCombinedRouteMapWithSearch(
-          filePath,
-          varName,
-          void 0,
-          void 0,
-          void 0,
-          memo
-        );
-        for (const [name, pattern] of Object.entries(routeMap)) {
-          const params = extractParamsFromPattern(pattern);
-          routes.push({
-            name,
-            pattern,
-            ...params ? { params } : {},
-            ...searchSchemas[name] ? { search: searchSchemas[name] } : {}
-          });
-        }
+function planPerModuleRouteTypesForFile(filePath) {
+  const source = readFileSync2(filePath, "utf-8");
+  if (!source.includes("urls(") && !source.includes("clientUrls(")) return null;
+  const varNames = findUrlsVariableNames(source);
+  let routes;
+  if (varNames.length > 0) {
+    routes = [];
+    const memo = createScanMemo();
+    for (const varName of varNames) {
+      const { routes: routeMap, searchSchemas } = buildCombinedRouteMapWithSearch(
+        filePath,
+        varName,
+        void 0,
+        void 0,
+        void 0,
+        memo
+      );
+      for (const [name, pattern] of Object.entries(routeMap)) {
+        const params = extractParamsFromPattern(pattern);
+        routes.push({
+          name,
+          pattern,
+          ...params ? { params } : {},
+          ...searchSchemas[name] ? { search: searchSchemas[name] } : {}
+        });
       }
-    } else {
-      routes = extractRoutesFromSource(source);
     }
-    const genPath = filePath.replace(/\.(tsx?|jsx?)$/, ".gen.ts");
-    if (routes.length === 0) {
-      if (varNames.length > 0 && !existsSync2(genPath)) {
-        writeFileSync(genPath, generatePerModuleTypesSource([]));
+  } else {
+    routes = extractRoutesFromSource(source);
+  }
+  const genPath = filePath.replace(/\.(tsx?|jsx?)$/, ".gen.ts");
+  if (routes.length === 0) {
+    if (varNames.length === 0) return null;
+    return {
+      genPath,
+      isPlaceholder: true,
+      content: generatePerModuleTypesSource([])
+    };
+  }
+  return {
+    genPath,
+    isPlaceholder: false,
+    content: generatePerModuleTypesSource(routes)
+  };
+}
+function writePerModuleRouteTypesForFile(filePath) {
+  try {
+    const plan = planPerModuleRouteTypesForFile(filePath);
+    if (!plan) return;
+    const { genPath, isPlaceholder, content } = plan;
+    const exists = existsSync2(genPath);
+    if (isPlaceholder) {
+      if (!exists) {
+        writeFileSync(genPath, content);
         console.log(
           `[rango] Generated route types (placeholder) -> ${genPath}`
         );
       }
       return;
     }
-    const genSource = generatePerModuleTypesSource(routes);
-    const existing = existsSync2(genPath) ? readFileSync2(genPath, "utf-8") : null;
-    if (existing !== genSource) {
-      writeFileSync(genPath, genSource);
+    if (!exists || readFileSync2(genPath, "utf-8") !== content) {
+      writeFileSync(genPath, content);
       console.log(`[rango] Generated route types -> ${genPath}`);
     }
   } catch (err) {
@@ -1619,15 +1638,315 @@ var init_router_versions = __esm({
   }
 });
 
+// package.json
+var package_default;
+var init_package = __esm({
+  "package.json"() {
+    package_default = {
+      name: "@rangojs/router",
+      version: "0.25.0",
+      description: "Django-inspired RSC router with composable URL patterns",
+      keywords: [
+        "react",
+        "react-server-components",
+        "router",
+        "rsc",
+        "vite"
+      ],
+      homepage: "https://github.com/rangojs/rango#readme",
+      bugs: {
+        url: "https://github.com/rangojs/rango/issues"
+      },
+      license: "MIT",
+      author: "Ivo Todorov",
+      repository: {
+        type: "git",
+        url: "git+https://github.com/rangojs/rango.git",
+        directory: "packages/rangojs-router"
+      },
+      bin: {
+        rango: "./dist/bin/rango.js"
+      },
+      files: [
+        "src",
+        "!src/**/__tests__",
+        "!src/**/__mocks__",
+        "!src/**/*.test.ts",
+        "!src/**/*.test.tsx",
+        "dist",
+        "skills",
+        "AGENTS.md",
+        "README.md",
+        "LICENSE"
+      ],
+      type: "module",
+      exports: {
+        ".": {
+          types: "./dist/types/index.rsc.d.ts",
+          "react-server": "./src/index.rsc.ts",
+          default: "./src/index.ts"
+        },
+        "./server": {
+          types: "./dist/types/server.d.ts",
+          import: "./src/server.ts"
+        },
+        "./client": {
+          types: "./dist/types/client.d.ts",
+          "react-server": "./src/client.rsc.tsx",
+          default: "./src/client.tsx"
+        },
+        "./browser": {
+          types: "./dist/types/browser/index.d.ts",
+          default: "./src/browser/index.ts"
+        },
+        "./ssr": {
+          types: "./dist/types/ssr/index.d.ts",
+          default: "./src/ssr/index.tsx"
+        },
+        "./rsc": {
+          types: "./dist/types/rsc/index.d.ts",
+          "react-server": "./src/rsc/index.ts",
+          default: "./src/rsc/index.ts"
+        },
+        "./vite": {
+          types: "./dist/types/vite/index.d.ts",
+          import: "./dist/vite/index.js"
+        },
+        "./types": {
+          types: "./src/vite/plugins/version.d.ts"
+        },
+        "./__internal": {
+          types: "./dist/types/__internal.d.ts",
+          default: "./src/__internal.ts"
+        },
+        "./internal/deps/browser": {
+          types: "./dist/types/deps/browser.d.ts",
+          default: "./src/deps/browser.ts"
+        },
+        "./internal/deps/ssr": {
+          types: "./dist/types/deps/ssr.d.ts",
+          default: "./src/deps/ssr.ts"
+        },
+        "./internal/deps/rsc": {
+          types: "./dist/types/deps/rsc.d.ts",
+          "react-server": "./src/deps/rsc.ts",
+          default: "./src/deps/rsc.ts"
+        },
+        "./internal/deps/rsc-client": {
+          types: "./dist/types/deps/rsc-client.d.ts",
+          "react-server": "./src/deps/rsc-client.ts",
+          default: "./src/deps/rsc-client.ts"
+        },
+        "./internal/deps/html-stream-client": {
+          types: "./dist/types/deps/html-stream-client.d.ts",
+          default: "./src/deps/html-stream-client.ts"
+        },
+        "./internal/deps/html-stream-server": {
+          types: "./dist/types/deps/html-stream-server.d.ts",
+          default: "./src/deps/html-stream-server.ts"
+        },
+        "./internal/rsc-handler": {
+          types: "./dist/types/rsc/handler.d.ts",
+          "react-server": "./src/rsc/handler.ts",
+          default: "./src/rsc/handler.ts"
+        },
+        "./internal/browser/dev-discovery": {
+          types: "./dist/types/browser/dev-discovery.d.ts",
+          default: "./src/browser/dev-discovery.ts"
+        },
+        "./cache": {
+          types: "./dist/types/cache/index.d.ts",
+          "react-server": "./src/cache/index.ts",
+          default: "./src/cache/index.ts"
+        },
+        "./cache-runtime": {
+          types: "./dist/types/cache/cache-runtime.d.ts",
+          "react-server": "./src/cache/cache-runtime.ts",
+          default: "./src/cache/cache-runtime.ts"
+        },
+        "./cloudflare": {
+          types: "./dist/types/cloudflare/index.d.ts",
+          "react-server": "./src/cloudflare/index.ts",
+          default: "./src/cloudflare/index.ts"
+        },
+        "./prerender": {
+          types: "./dist/types/prerender/index.d.ts",
+          "react-server": "./src/prerender/index.ts",
+          default: "./src/prerender/index.ts"
+        },
+        "./prerender/cloudflare": {
+          types: "./dist/types/prerender/cloudflare.d.ts",
+          "react-server": "./src/prerender/cloudflare.ts",
+          default: "./src/prerender/cloudflare.ts"
+        },
+        "./vercel": {
+          types: "./dist/types/vercel/index.d.ts",
+          "react-server": "./src/vercel/index.ts",
+          default: "./src/vercel/index.ts"
+        },
+        "./theme": {
+          types: "./dist/types/theme/index.d.ts",
+          default: "./src/theme/index.ts"
+        },
+        "./build": {
+          types: "./dist/types/build/index.d.ts",
+          import: "./src/build/index.ts"
+        },
+        "./build/shell-capture": {
+          types: "./dist/types/prerender/build-shell-capture.d.ts",
+          "react-server": "./src/prerender/build-shell-capture.ts",
+          import: "./src/prerender/build-shell-capture.ts"
+        },
+        "./host": {
+          types: "./dist/types/host/index.d.ts",
+          "react-server": "./src/host/index.ts",
+          default: "./src/host/index.ts"
+        },
+        "./host/testing": {
+          types: "./dist/types/host/testing.d.ts",
+          default: "./src/host/testing.ts"
+        },
+        "./testing": {
+          types: "./dist/types/testing/index.d.ts",
+          default: "./src/testing/index.ts"
+        },
+        "./testing/vitest": {
+          types: "./dist/types/testing/vitest.d.ts",
+          default: "./dist/testing/vitest.js"
+        },
+        "./testing/dom": {
+          types: "./dist/types/testing/dom.entry.d.ts",
+          default: "./src/testing/dom.entry.ts"
+        },
+        "./testing/e2e": {
+          types: "./dist/types/testing/e2e/index.d.ts",
+          default: "./src/testing/e2e/index.ts"
+        },
+        "./testing/flight": {
+          types: "./dist/types/testing/flight.entry.d.ts",
+          "react-server": "./src/testing/flight.entry.ts",
+          default: "./src/testing/flight.entry.ts"
+        },
+        "./testing/flight-matchers": {
+          types: "./dist/types/testing/flight-matchers.d.ts",
+          default: "./src/testing/flight-matchers.ts"
+        }
+      },
+      publishConfig: {
+        access: "public",
+        tag: "latest"
+      },
+      scripts: {
+        build: "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+        "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
+        prepublishOnly: "pnpm build",
+        typecheck: "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
+        test: "playwright test",
+        "test:preload": "playwright test --config=playwright.preload.config.ts",
+        "test:ui": "playwright test --ui",
+        "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+        "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+        "test:unit": "pnpm run build:types && vitest run",
+        "test:unit:watch": "vitest",
+        "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
+      },
+      dependencies: {
+        "@types/debug": "^4.1.12",
+        "@vitejs/plugin-rsc": "^0.5.36",
+        debug: "^4.4.1",
+        "magic-string": "^0.30.17",
+        picomatch: "^4.0.4",
+        "rsc-html-stream": "^0.0.7",
+        srvx: "^0.11.15",
+        tinyexec: "^0.3.2",
+        typescript: "^5.3.0 || ^6.0.0"
+      },
+      devDependencies: {
+        "@opentelemetry/api": "^1.9.0",
+        "@opentelemetry/context-async-hooks": "^2.9.0",
+        "@opentelemetry/sdk-trace-base": "^2.9.0",
+        "@playwright/test": "^1.62.0",
+        "@shared/e2e": "workspace:*",
+        "@testing-library/dom": "^10.4.1",
+        "@testing-library/react": "^16.3.2",
+        "@types/node": "^24.10.1",
+        "@types/react": "catalog:",
+        "@types/react-dom": "catalog:",
+        esbuild: "^0.28.1",
+        "happy-dom": "^20.10.1",
+        jiti: "^2.7.0",
+        react: "catalog:",
+        "react-dom": "catalog:",
+        vitest: "^4.1.11"
+      },
+      peerDependencies: {
+        "@cloudflare/vite-plugin": "^1.42.1",
+        "@opentelemetry/api": "^1.9.0",
+        "@playwright/test": "^1.49.1",
+        "@testing-library/react": ">=16",
+        "@vercel/functions": "^3.0.0",
+        react: ">=19.2.8 <20",
+        "react-dom": ">=19.2.8 <20",
+        vite: "^8.0.16",
+        vitest: ">=3"
+      },
+      peerDependenciesMeta: {
+        "@cloudflare/vite-plugin": {
+          optional: true
+        },
+        "@opentelemetry/api": {
+          optional: true
+        },
+        "@playwright/test": {
+          optional: true
+        },
+        "@testing-library/react": {
+          optional: true
+        },
+        "@vercel/functions": {
+          optional: true
+        },
+        vite: {
+          optional: true
+        },
+        vitest: {
+          optional: true
+        }
+      },
+      engines: {
+        node: ">=24.0.0"
+      }
+    };
+  }
+});
+
+// src/vite/utils/banner.ts
+var rangoVersion;
+var init_banner = __esm({
+  "src/vite/utils/banner.ts"() {
+    "use strict";
+    init_package();
+    rangoVersion = package_default.version;
+  }
+});
+
 // src/vite/plugins/virtual-entries.ts
+function getPackageVersionExport() {
+  return `export const PACKAGE_VERSION = ${JSON.stringify(rangoVersion)};`;
+}
+function getVirtualPackageVersionContent() {
+  return getPackageVersionExport();
+}
 function getVirtualVersionContent(version) {
   return [
+    getPackageVersionExport(),
     `export const VERSION = ${JSON.stringify(version)};`,
     `export const ROUTER_VERSIONS = undefined;`
   ].join("\n");
 }
 function getVirtualBuildVersionContent() {
   return [
+    getPackageVersionExport(),
     `export const ROUTER_VERSIONS = ${ROUTER_VERSIONS_PLACEHOLDER};`,
     `export const VERSION = ROUTER_VERSIONS[${JSON.stringify(DEFAULT_ROUTER_VERSIONS_KEY)}][1];`
   ].join("\n");
@@ -1637,6 +1956,7 @@ var init_virtual_entries = __esm({
   "src/vite/plugins/virtual-entries.ts"() {
     "use strict";
     init_router_versions();
+    init_banner();
     VIRTUAL_ENTRY_BROWSER = `
 import {
   createFromReadableStream,
@@ -1851,6 +2171,10 @@ function createVersionPlugin() {
     },
     load(id) {
       if (id === "\0" + VIRTUAL_IDS.version) {
+        const environment = this?.environment?.name;
+        if (environment === "client") {
+          return getVirtualPackageVersionContent();
+        }
         return isDev ? getVirtualVersionContent(currentVersion) : getVirtualBuildVersionContent();
       }
       return null;

package/dist/testing/vitest.js

@@ -1,7 +1,15 @@
 // src/testing/vitest.ts
+import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+// src/vite/plugins/hoist/literal.ts
+function parseLang(file) {
+  if (/\.[cm]?ts$/.test(file)) return "ts";
+  if (/\.[cm]?jsx?$/.test(file)) return "jsx";
+  return "tsx";
+}
+
 // src/vite/plugins/use-cache-transform.ts
 import path2 from "node:path";
 
@@ -251,6 +259,22 @@ var CLIENT_ENTRY_RSC_PATH = here("src/client.rsc.tsx").replaceAll(
 var CLIENT_URLS_INSTALLER_PATH = here(
   "src/testing/internal/client-urls-projection.ts"
 ).replaceAll("\\", "/");
+async function loadsAsSource(code, file) {
+  if (!code.includes("use client") && !code.includes("export")) return false;
+  const { parseAstAsync } = await import("vite");
+  const { hasDirective } = await import("@vitejs/plugin-rsc/transforms");
+  let body;
+  try {
+    body = (await parseAstAsync(code, { lang: parseLang(file) })).body;
+  } catch {
+    return false;
+  }
+  if (hasDirective(body, "use client")) return true;
+  const nodes = body;
+  return nodes.some((node) => node.type !== "ImportDeclaration") && nodes.every(
+    (node) => node.type === "ImportDeclaration" || node.type === "ExportAllDeclaration" || node.type === "ExportNamedDeclaration" && node.source != null
+  );
+}
 function clientUrlsProjectionInstall(id) {
   const source = `${id}${id.includes("?") ? "&" : "?"}${CLIENT_URLS_SOURCE_QUERY}`;
   return `
@@ -309,11 +333,20 @@ function rangoUseClientTransform() {
     resolveId: {
       // Before Vite's resolver, which resolves the bare specifier first.
       order: "pre",
-      handler(source, importer) {
-        if (source === "@rangojs/router/client" && importer?.includes(CLIENT_URLS_SOURCE_QUERY)) {
-          return CLIENT_ENTRY_RSC_PATH;
+      async handler(source, importer) {
+        if (!importer?.includes(CLIENT_URLS_SOURCE_QUERY)) return void 0;
+        if (source === "@rangojs/router/client") return CLIENT_ENTRY_RSC_PATH;
+        const resolved = await this.resolve(source, importer, {
+          skipSelf: true
+        });
+        if (!resolved || resolved.external) return void 0;
+        const { id } = resolved;
+        const file = id.split("?", 1)[0];
+        if (id.startsWith("\0") || id.includes("/node_modules/") || id.includes(CLIENT_URLS_SOURCE_QUERY) || !/\.[cm]?[jt]sx?$/.test(file)) {
+          return void 0;
         }
-        return void 0;
+        const code = await readFile(file, "utf-8").catch(() => "");
+        return await loadsAsSource(code, file) ? `${id}${id.includes("?") ? "&" : "?"}${CLIENT_URLS_SOURCE_QUERY}` : void 0;
       }
     },
     async transform(code, id) {

package/dist/types/browser/event-controller.d.ts

@@ -39,6 +39,8 @@ export interface ActionEntry {
     result?: unknown;
     /** Error from action (set on failure) */
     error?: unknown;
+    /** A loader that failed while it re-ran after the action (set on success) */
+    revalidationError?: unknown;
     /** Segment IDs that were revalidated by this action */
     revalidatedSegments: string[];
     /** Timestamp when action started */
@@ -79,9 +81,14 @@ export type StateListener = () => void;
  */
 export type ActionStateListener = (state: TrackedActionState) => void;
 /**
- * Handle state listener
+ * Handle state listener. `signal`, from a payload update: "anchor" when it
+ * hands React a page in a transition (route state on screen until it
+ * commits), "release" when it hands one urgently; "release" again once the
+ * page committed (useCommitAnchoredState, react/use-handle.ts).
  */
-export type HandleListener = () => void;
+export type HandleListener = (signal?: RouteStateSignal) => void;
+/** See HandleListener. */
+export type RouteStateSignal = "anchor" | "release";
 /**
  * Internal handle state stored in controller.
  *
@@ -158,8 +165,8 @@ export interface ActionHandle extends Disposable {
      * later-initiated winner's response lands and overwrites it.
      */
     claimLocationState(state: Record<string, unknown>): Record<string, unknown>;
-    /** Complete the action with result */
-    complete(result?: unknown): void;
+    /** Complete the action with result, and a loader rerun's error, if any */
+    complete(result?: unknown, revalidationError?: unknown): void;
     /** Fail the action with error */
     fail(error: unknown): void;
     /** Whether action was completed (success or failure) */
@@ -200,8 +207,18 @@ export interface EventController {
      * Deliver queued location, params, navigation, and handle notifications now.
      * NavigationProvider calls this inside the payload update so React assigns
      * every route-state hook update to the same normal or transition lane.
+     * `signal`: handle readers learn how the page is handed over. After
+     * "anchor" (a page in a transition) values that arrive before
+     * releaseRouteState() wait for it (useCommitAnchoredState,
+     * react/use-handle.ts).
      */
-    flushRouteState(): void;
+    flushRouteState(signal?: RouteStateSignal): void;
+    /**
+     * The page the last flushRouteState("anchor") announced has committed:
+     * NavigationProvider calls this from its layout effect, and handle readers
+     * apply what waited, in that task.
+     */
+    releaseRouteState(): void;
     setHandleData(data: HandleData, matched?: string[], isPartial?: boolean, 
     /**
      * Segment ids that were re-resolved on the server this request (the
@@ -269,6 +286,8 @@ export interface EventController {
 type LocationChangeController = Pick<EventController, "getState" | "subscribe">;
 /** Share one controller subscription across all location-change consumers. */
 export declare function subscribeToLocationChange(eventController: LocationChangeController, listener: (href: string) => void): () => void;
+/** An action with no tracked entry: idle, nothing reported. */
+export declare const DEFAULT_ACTION_STATE: TrackedActionState;
 export interface EventControllerConfig {
     initialLocation?: NavigationLocation;
 }

package/dist/types/browser/intercept-utils.d.ts

@@ -3,10 +3,13 @@ import type { SlotState } from "../types.js";
 /**
  * Check if a segment is an intercept segment.
  * Intercept segments have namespace starting with "intercept:" — both the
- * parallel container (@modal) and its content children receive this namespace
+ * parallel container (@modal) and its loader segments receive this namespace
  * from intercept-resolution.ts. Regular parallel segments like @sidebar do not.
+ * Server-safe: the cache and match pipeline share it.
  */
-export declare function isInterceptSegment(s: ResolvedSegment): boolean;
+export declare function isInterceptSegment(s: {
+    namespace?: string;
+}): boolean;
 /**
  * Split an array of segments into main and intercept groups.
  * Intercept segments are separated for explicit injection into the render tree

package/dist/types/browser/merge-segment-loaders.d.ts

@@ -1,27 +1,4 @@
 import type { ResolvedSegment } from "./types.js";
-/**
- * Merge partial loader data from server with cached loader data.
- *
- * During partial revalidation (stale or action), the server may return only
- * some loaders that pass the revalidation check, none when every one is held.
- * The component still needs all loader data, so we merge fresh data with
- * cached data. Two settled aggregates merge into the array itself: a fresh
- * Promise.all over settled parts is a promise React has not read, and content
- * on screen handed one suspends (docs/internal/suspense-contract.md, rule 2).
- *
- * @param fromServer - Segment returned from server with partial loaders
- * @param fromCache - Cached segment with full loader data
- * @returns Merged segment with complete loader data
- */
-export declare function mergeSegmentLoaders(fromServer: ResolvedSegment, fromCache: ResolvedSegment): ResolvedSegment;
-/**
- * Check if segments need loader merging during partial revalidation.
- *
- * Returns true when:
- * - Server returned fewer loaders than cached (partial revalidation)
- * - Both segments have loader data promises
- */
-export declare function needsLoaderMerge(fromServer: ResolvedSegment, fromCache: ResolvedSegment | undefined): fromCache is ResolvedSegment;
 /**
  * Insert diff segments that aren't in the matched array into allSegments.
  *

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

@@ -1,4 +1,4 @@
-import type { NavigateOptionsInternal, NavigationStore, ResolvedSegment, StreamingToken } from "./types.js";
+import type { NavigateOptionsInternal, NavigationStore, ResolvedSegment, ShownEntry, StreamingToken } from "./types.js";
 import type { EventController, NavigationHandle } from "./event-controller.js";
 export { resolveNavigationState } from "./history-state.js";
 /**
@@ -28,8 +28,8 @@ interface CommitOptions {
      * merged in. The page left was saved by handleTraversalStart.
      */
     traversal?: boolean;
-    /** The committed route's name (payload metadata), remembered per history entry. */
-    routeName?: string;
+    /** The payload's metadata: its route name and rewrite target, remembered per history entry. */
+    metadata?: ShownEntry;
     /**
      * transition({ when }) decision already made at this navigation's first
      * presentation (the optimistic clientUrls() swap). Not a commit input: the
@@ -60,8 +60,8 @@ interface BoundCommitOverrides {
     cacheOnly?: boolean;
     /** Server-set location state to merge into history.pushState */
     serverState?: Record<string, unknown>;
-    /** The committed route's name (payload metadata), remembered per history entry. */
-    routeName?: string;
+    /** The payload's metadata: its route name and rewrite target, remembered per history entry. */
+    metadata?: ShownEntry;
     /** No payload follows this commit (CommitOptions.treeless). */
     treeless?: boolean;
 }