@bleedingdev/modern-js-plugin-tanstack 3.2.0-ultramodern.119 → 3.2.0-ultramodern.120

package/dist/cjs/cli/index.js

@@ -52,6 +52,7 @@ var __webpack_exports__ = {};
 (()=>{
     __webpack_require__.r(__webpack_exports__);
     __webpack_require__.d(__webpack_exports__, {
+        collectCanonicalRoutesForEntry: ()=>external_tanstackTypes_js_namespaceObject.collectCanonicalRoutesForEntry,
         createTanstackRsbuildRouteSplittingProfile: ()=>external_routeSplitting_js_namespaceObject.createTanstackRsbuildRouteSplittingProfile,
         default: ()=>src_cli,
         generateTanstackRouterTypesSourceForEntry: ()=>external_tanstackTypes_js_namespaceObject.generateTanstackRouterTypesSourceForEntry,
@@ -90,6 +91,14 @@ var __webpack_exports__ = {};
     function createRegisterDtsContent(opts) {
         const importStatements = opts.entries.map((entryName, index)=>`import type { router as router${index} } from './${entryName}/router.gen';`).join('\n');
         const routerUnionType = opts.entries.map((_, index)=>`typeof router${index}`).join(' | ');
+        const canonicalEntries = Object.entries(opts.canonicalRoutes ?? {});
+        const canonicalRoutesAugmentation = canonicalEntries.length > 0 ? `
+declare module '${opts.i18nRuntimeModule || '@modern-js/plugin-i18n/runtime'}' {
+  interface UltramodernCanonicalRoutes {
+${canonicalEntries.map(([routePath, paramsType])=>`    '${routePath}': ${paramsType};`).join('\n')}
+  }
+}
+` : '';
         return `// This file is auto-generated by Modern.js. Do not edit manually.
 
 ${importStatements}
@@ -99,15 +108,17 @@ declare module '${opts.runtimeModule}' {
     router: ${routerUnionType};
   }
 }
-`;
+${canonicalRoutesAugmentation}`;
     }
     async function writeTanstackRegisterFile(opts) {
-        const { entries, generatedDirName = DEFAULT_GENERATED_DIR_NAME, runtimeModule = '@modern-js/plugin-tanstack/runtime', srcDirectory } = opts;
+        const { entries, generatedDirName = DEFAULT_GENERATED_DIR_NAME, runtimeModule = '@modern-js/plugin-tanstack/runtime', srcDirectory, canonicalRoutes, i18nRuntimeModule } = opts;
         if (0 === entries.length) return;
         const registerDtsPath = external_node_path_default().join(srcDirectory, generatedDirName, 'register.gen.d.ts');
         await writeFileIfChanged(registerDtsPath, createRegisterDtsContent({
             entries,
-            runtimeModule
+            runtimeModule,
+            canonicalRoutes,
+            i18nRuntimeModule
         }));
     }
     async function writeTanstackRouterTypesForEntries(opts) {
@@ -128,10 +139,19 @@ declare module '${opts.runtimeModule}' {
             if (mainEntryName && b === mainEntryName) return 1;
             return a.localeCompare(b);
         });
+        let canonicalRoutes = null;
+        for (const entryName of registerEntries){
+            const entryCanonicalRoutes = (0, external_tanstackTypes_js_namespaceObject.collectCanonicalRoutesForEntry)(routesByEntry[entryName]);
+            if (entryCanonicalRoutes) canonicalRoutes = {
+                ...entryCanonicalRoutes,
+                ...canonicalRoutes ?? {}
+            };
+        }
         await writeTanstackRegisterFile({
             entries: registerEntries,
             generatedDirName,
-            srcDirectory: appContext.srcDirectory
+            srcDirectory: appContext.srcDirectory,
+            canonicalRoutes
         });
     }
     function tanstackRouterPlugin(options = {}) {
@@ -256,6 +276,7 @@ declare module '${opts.runtimeModule}' {
     }
     const src_cli = tanstackRouterPlugin;
 })();
+exports.collectCanonicalRoutesForEntry = __webpack_exports__.collectCanonicalRoutesForEntry;
 exports.createTanstackRsbuildRouteSplittingProfile = __webpack_exports__.createTanstackRsbuildRouteSplittingProfile;
 exports["default"] = __webpack_exports__["default"];
 exports.generateTanstackRouterTypesSourceForEntry = __webpack_exports__.generateTanstackRouterTypesSourceForEntry;
@@ -266,6 +287,7 @@ exports.tanstackRouterPlugin = __webpack_exports__.tanstackRouterPlugin;
 exports.writeTanstackRegisterFile = __webpack_exports__.writeTanstackRegisterFile;
 exports.writeTanstackRouterTypesForEntries = __webpack_exports__.writeTanstackRouterTypesForEntries;
 for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "collectCanonicalRoutesForEntry",
     "createTanstackRsbuildRouteSplittingProfile",
     "default",
     "generateTanstackRouterTypesSourceForEntry",

package/dist/cjs/cli/tanstackTypes.js

@@ -37,6 +37,7 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
+    collectCanonicalRoutesForEntry: ()=>collectCanonicalRoutesForEntry,
     generateTanstackRouterTypesSourceForEntry: ()=>generateTanstackRouterTypesSourceForEntry,
     isTanstackRouterFrameworkEnabled: ()=>isTanstackRouterFrameworkEnabled
 });
@@ -120,6 +121,78 @@ function createRouteStaticDataSnippet(opts) {
     if (!staticDataLines.length) return null;
     return `staticData: createRouteStaticData({\n    ${staticDataLines.join('\n    ')}\n  }),`;
 }
+const LOCALE_PARAM_SEGMENTS = new Set([
+    ':lang',
+    ':locale',
+    ':language',
+    '$lang',
+    '$locale',
+    '$language'
+]);
+function paramsTypeForCanonicalPath(canonicalPath) {
+    const fields = [];
+    for (const segment of canonicalPath.split('/'))if (segment) {
+        if ('*' === segment || '$' === segment) {
+            fields.push("'_splat'?: string");
+            continue;
+        }
+        if (segment.startsWith('{-$') && segment.endsWith('}')) {
+            fields.push(`${JSON.stringify(segment.slice(3, -1))}?: string`);
+            continue;
+        }
+        if (segment.startsWith('$')) {
+            fields.push(`${JSON.stringify(segment.slice(1))}: string`);
+            continue;
+        }
+        if (segment.startsWith(':')) {
+            const optional = segment.endsWith('?');
+            const name = segment.slice(1, optional ? void 0 : segment.length);
+            fields.push(`${JSON.stringify(optional ? name.slice(0, -1) : name)}${optional ? '?' : ''}: string`);
+        }
+    }
+    return fields.length > 0 ? `{ ${fields.join('; ')} }` : 'Record<string, never>';
+}
+function collectCanonicalRoutesForEntry(routes) {
+    const canonicalParams = new Map();
+    let hasI18nSurface = false;
+    const normalizeJoined = (joined)=>{
+        const collapsed = joined.replace(/\/+/g, '/');
+        const withLeading = collapsed.startsWith('/') ? collapsed : `/${collapsed}`;
+        return withLeading.length > 1 ? withLeading.replace(/\/+$/, '') : withLeading;
+    };
+    const record = (canonicalPath)=>{
+        const normalized = normalizeJoined(canonicalPath || '/');
+        const key = toTanstackPath(normalized);
+        if (!canonicalParams.has(key)) canonicalParams.set(key, paramsTypeForCanonicalPath(normalized));
+    };
+    const visit = (route, parentPath)=>{
+        let currentPath = parentPath;
+        if ('string' == typeof route.modernCanonicalPath) {
+            hasI18nSurface = true;
+            currentPath = normalizeJoined(route.modernCanonicalPath);
+        } else if ('string' == typeof route.path && route.path.length > 0) {
+            const segments = route.path.replace(/\[(.+?)\]/g, ':$1').split('/').filter(Boolean);
+            if ('' === parentPath && LOCALE_PARAM_SEGMENTS.has(segments[0])) {
+                hasI18nSurface = true;
+                segments.shift();
+            }
+            currentPath = segments.length ? normalizeJoined(`${parentPath}/${segments.join('/')}`) : parentPath;
+        }
+        const children = route.children;
+        if (children && children.length > 0) {
+            for (const child of children)visit(child, currentPath);
+            return;
+        }
+        record(currentPath || '/');
+    };
+    const rootModern = routes.find((route)=>route.isRoot);
+    const topLevel = rootModern ? rootModern.children ?? [] : routes;
+    for (const route of topLevel)visit(route, '');
+    if (!hasI18nSurface || 0 === canonicalParams.size) return null;
+    return Object.fromEntries([
+        ...canonicalParams.entries()
+    ].sort(([a], [b])=>a.localeCompare(b)));
+}
 async function isTanstackRouterFrameworkEnabled(appContext) {
     const runtimeConfigBase = external_path_default().join(appContext.srcDirectory, appContext.runtimeConfigFile);
     const runtimeConfigFile = (0, utils_namespaceObject.findExists)(JS_OR_TS_EXTS.map((ext)=>`${runtimeConfigBase}${ext}`));
@@ -469,9 +542,11 @@ export const router = createRouter({
         routerGenTs
     };
 }
+exports.collectCanonicalRoutesForEntry = __webpack_exports__.collectCanonicalRoutesForEntry;
 exports.generateTanstackRouterTypesSourceForEntry = __webpack_exports__.generateTanstackRouterTypesSourceForEntry;
 exports.isTanstackRouterFrameworkEnabled = __webpack_exports__.isTanstackRouterFrameworkEnabled;
 for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "collectCanonicalRoutesForEntry",
     "generateTanstackRouterTypesSourceForEntry",
     "isTanstackRouterFrameworkEnabled"
 ].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];

package/dist/esm/cli/index.mjs

@@ -1,7 +1,7 @@
 import node_path from "node:path";
 import { NESTED_ROUTE_SPEC_FILE, filterRoutesForServer, fs } from "@modern-js/utils";
 import { createTanstackRsbuildRouteSplittingProfile, isTanstackStartRouteModuleSource, resolveTanstackRouteCodeSplittingEnabled } from "./routeSplitting.mjs";
-import { generateTanstackRouterTypesSourceForEntry, isTanstackRouterFrameworkEnabled } from "./tanstackTypes.mjs";
+import { collectCanonicalRoutesForEntry, generateTanstackRouterTypesSourceForEntry, isTanstackRouterFrameworkEnabled } from "./tanstackTypes.mjs";
 import { __webpack_require__ } from "../rslib-runtime.mjs";
 import * as __rspack_external__modern_js_runtime_cli_401ee077 from "@modern-js/runtime/cli";
 __webpack_require__.add({
@@ -32,6 +32,14 @@ async function writeFileIfChanged(filePath, content) {
 function createRegisterDtsContent(opts) {
     const importStatements = opts.entries.map((entryName, index)=>`import type { router as router${index} } from './${entryName}/router.gen';`).join('\n');
     const routerUnionType = opts.entries.map((_, index)=>`typeof router${index}`).join(' | ');
+    const canonicalEntries = Object.entries(opts.canonicalRoutes ?? {});
+    const canonicalRoutesAugmentation = canonicalEntries.length > 0 ? `
+declare module '${opts.i18nRuntimeModule || '@modern-js/plugin-i18n/runtime'}' {
+  interface UltramodernCanonicalRoutes {
+${canonicalEntries.map(([routePath, paramsType])=>`    '${routePath}': ${paramsType};`).join('\n')}
+  }
+}
+` : '';
     return `// This file is auto-generated by Modern.js. Do not edit manually.
 
 ${importStatements}
@@ -41,15 +49,17 @@ declare module '${opts.runtimeModule}' {
     router: ${routerUnionType};
   }
 }
-`;
+${canonicalRoutesAugmentation}`;
 }
 async function writeTanstackRegisterFile(opts) {
-    const { entries, generatedDirName = DEFAULT_GENERATED_DIR_NAME, runtimeModule = '@modern-js/plugin-tanstack/runtime', srcDirectory } = opts;
+    const { entries, generatedDirName = DEFAULT_GENERATED_DIR_NAME, runtimeModule = '@modern-js/plugin-tanstack/runtime', srcDirectory, canonicalRoutes, i18nRuntimeModule } = opts;
     if (0 === entries.length) return;
     const registerDtsPath = node_path.join(srcDirectory, generatedDirName, 'register.gen.d.ts');
     await writeFileIfChanged(registerDtsPath, createRegisterDtsContent({
         entries,
-        runtimeModule
+        runtimeModule,
+        canonicalRoutes,
+        i18nRuntimeModule
     }));
 }
 async function writeTanstackRouterTypesForEntries(opts) {
@@ -70,10 +80,19 @@ async function writeTanstackRouterTypesForEntries(opts) {
         if (mainEntryName && b === mainEntryName) return 1;
         return a.localeCompare(b);
     });
+    let canonicalRoutes = null;
+    for (const entryName of registerEntries){
+        const entryCanonicalRoutes = collectCanonicalRoutesForEntry(routesByEntry[entryName]);
+        if (entryCanonicalRoutes) canonicalRoutes = {
+            ...entryCanonicalRoutes,
+            ...canonicalRoutes ?? {}
+        };
+    }
     await writeTanstackRegisterFile({
         entries: registerEntries,
         generatedDirName,
-        srcDirectory: appContext.srcDirectory
+        srcDirectory: appContext.srcDirectory,
+        canonicalRoutes
     });
 }
 function tanstackRouterPlugin(options = {}) {
@@ -198,4 +217,4 @@ function tanstackRouterPlugin(options = {}) {
 }
 const src_cli = tanstackRouterPlugin;
 export default src_cli;
-export { createTanstackRsbuildRouteSplittingProfile, generateTanstackRouterTypesSourceForEntry, isTanstackRouterFrameworkEnabled, isTanstackStartRouteModuleSource, resolveTanstackRouteCodeSplittingEnabled, tanstackRouterPlugin, writeTanstackRegisterFile, writeTanstackRouterTypesForEntries };
+export { collectCanonicalRoutesForEntry, createTanstackRsbuildRouteSplittingProfile, generateTanstackRouterTypesSourceForEntry, isTanstackRouterFrameworkEnabled, isTanstackStartRouteModuleSource, resolveTanstackRouteCodeSplittingEnabled, tanstackRouterPlugin, writeTanstackRegisterFile, writeTanstackRouterTypesForEntries };

package/dist/esm/cli/tanstackTypes.mjs

@@ -77,6 +77,78 @@ function createRouteStaticDataSnippet(opts) {
     if (!staticDataLines.length) return null;
     return `staticData: createRouteStaticData({\n    ${staticDataLines.join('\n    ')}\n  }),`;
 }
+const LOCALE_PARAM_SEGMENTS = new Set([
+    ':lang',
+    ':locale',
+    ':language',
+    '$lang',
+    '$locale',
+    '$language'
+]);
+function paramsTypeForCanonicalPath(canonicalPath) {
+    const fields = [];
+    for (const segment of canonicalPath.split('/'))if (segment) {
+        if ('*' === segment || '$' === segment) {
+            fields.push("'_splat'?: string");
+            continue;
+        }
+        if (segment.startsWith('{-$') && segment.endsWith('}')) {
+            fields.push(`${JSON.stringify(segment.slice(3, -1))}?: string`);
+            continue;
+        }
+        if (segment.startsWith('$')) {
+            fields.push(`${JSON.stringify(segment.slice(1))}: string`);
+            continue;
+        }
+        if (segment.startsWith(':')) {
+            const optional = segment.endsWith('?');
+            const name = segment.slice(1, optional ? void 0 : segment.length);
+            fields.push(`${JSON.stringify(optional ? name.slice(0, -1) : name)}${optional ? '?' : ''}: string`);
+        }
+    }
+    return fields.length > 0 ? `{ ${fields.join('; ')} }` : 'Record<string, never>';
+}
+function collectCanonicalRoutesForEntry(routes) {
+    const canonicalParams = new Map();
+    let hasI18nSurface = false;
+    const normalizeJoined = (joined)=>{
+        const collapsed = joined.replace(/\/+/g, '/');
+        const withLeading = collapsed.startsWith('/') ? collapsed : `/${collapsed}`;
+        return withLeading.length > 1 ? withLeading.replace(/\/+$/, '') : withLeading;
+    };
+    const record = (canonicalPath)=>{
+        const normalized = normalizeJoined(canonicalPath || '/');
+        const key = toTanstackPath(normalized);
+        if (!canonicalParams.has(key)) canonicalParams.set(key, paramsTypeForCanonicalPath(normalized));
+    };
+    const visit = (route, parentPath)=>{
+        let currentPath = parentPath;
+        if ('string' == typeof route.modernCanonicalPath) {
+            hasI18nSurface = true;
+            currentPath = normalizeJoined(route.modernCanonicalPath);
+        } else if ('string' == typeof route.path && route.path.length > 0) {
+            const segments = route.path.replace(/\[(.+?)\]/g, ':$1').split('/').filter(Boolean);
+            if ('' === parentPath && LOCALE_PARAM_SEGMENTS.has(segments[0])) {
+                hasI18nSurface = true;
+                segments.shift();
+            }
+            currentPath = segments.length ? normalizeJoined(`${parentPath}/${segments.join('/')}`) : parentPath;
+        }
+        const children = route.children;
+        if (children && children.length > 0) {
+            for (const child of children)visit(child, currentPath);
+            return;
+        }
+        record(currentPath || '/');
+    };
+    const rootModern = routes.find((route)=>route.isRoot);
+    const topLevel = rootModern ? rootModern.children ?? [] : routes;
+    for (const route of topLevel)visit(route, '');
+    if (!hasI18nSurface || 0 === canonicalParams.size) return null;
+    return Object.fromEntries([
+        ...canonicalParams.entries()
+    ].sort(([a], [b])=>a.localeCompare(b)));
+}
 async function isTanstackRouterFrameworkEnabled(appContext) {
     const runtimeConfigBase = path.join(appContext.srcDirectory, appContext.runtimeConfigFile);
     const runtimeConfigFile = findExists(JS_OR_TS_EXTS.map((ext)=>`${runtimeConfigBase}${ext}`));
@@ -426,4 +498,4 @@ export const router = createRouter({
         routerGenTs
     };
 }
-export { generateTanstackRouterTypesSourceForEntry, isTanstackRouterFrameworkEnabled };
+export { collectCanonicalRoutesForEntry, generateTanstackRouterTypesSourceForEntry, isTanstackRouterFrameworkEnabled };

package/dist/esm-node/cli/index.mjs

@@ -2,7 +2,7 @@ import "node:module";
 import node_path from "node:path";
 import { NESTED_ROUTE_SPEC_FILE, filterRoutesForServer, fs } from "@modern-js/utils";
 import { createTanstackRsbuildRouteSplittingProfile, isTanstackStartRouteModuleSource, resolveTanstackRouteCodeSplittingEnabled } from "./routeSplitting.mjs";
-import { generateTanstackRouterTypesSourceForEntry, isTanstackRouterFrameworkEnabled } from "./tanstackTypes.mjs";
+import { collectCanonicalRoutesForEntry, generateTanstackRouterTypesSourceForEntry, isTanstackRouterFrameworkEnabled } from "./tanstackTypes.mjs";
 import { __webpack_require__ } from "../rslib-runtime.mjs";
 import { fileURLToPath as __rspack_fileURLToPath } from "node:url";
 import { dirname as __rspack_dirname } from "node:path";
@@ -36,6 +36,14 @@ async function writeFileIfChanged(filePath, content) {
 function createRegisterDtsContent(opts) {
     const importStatements = opts.entries.map((entryName, index)=>`import type { router as router${index} } from './${entryName}/router.gen';`).join('\n');
     const routerUnionType = opts.entries.map((_, index)=>`typeof router${index}`).join(' | ');
+    const canonicalEntries = Object.entries(opts.canonicalRoutes ?? {});
+    const canonicalRoutesAugmentation = canonicalEntries.length > 0 ? `
+declare module '${opts.i18nRuntimeModule || '@modern-js/plugin-i18n/runtime'}' {
+  interface UltramodernCanonicalRoutes {
+${canonicalEntries.map(([routePath, paramsType])=>`    '${routePath}': ${paramsType};`).join('\n')}
+  }
+}
+` : '';
     return `// This file is auto-generated by Modern.js. Do not edit manually.
 
 ${importStatements}
@@ -45,15 +53,17 @@ declare module '${opts.runtimeModule}' {
     router: ${routerUnionType};
   }
 }
-`;
+${canonicalRoutesAugmentation}`;
 }
 async function writeTanstackRegisterFile(opts) {
-    const { entries, generatedDirName = DEFAULT_GENERATED_DIR_NAME, runtimeModule = '@modern-js/plugin-tanstack/runtime', srcDirectory } = opts;
+    const { entries, generatedDirName = DEFAULT_GENERATED_DIR_NAME, runtimeModule = '@modern-js/plugin-tanstack/runtime', srcDirectory, canonicalRoutes, i18nRuntimeModule } = opts;
     if (0 === entries.length) return;
     const registerDtsPath = node_path.join(srcDirectory, generatedDirName, 'register.gen.d.ts');
     await writeFileIfChanged(registerDtsPath, createRegisterDtsContent({
         entries,
-        runtimeModule
+        runtimeModule,
+        canonicalRoutes,
+        i18nRuntimeModule
     }));
 }
 async function writeTanstackRouterTypesForEntries(opts) {
@@ -74,10 +84,19 @@ async function writeTanstackRouterTypesForEntries(opts) {
         if (mainEntryName && b === mainEntryName) return 1;
         return a.localeCompare(b);
     });
+    let canonicalRoutes = null;
+    for (const entryName of registerEntries){
+        const entryCanonicalRoutes = collectCanonicalRoutesForEntry(routesByEntry[entryName]);
+        if (entryCanonicalRoutes) canonicalRoutes = {
+            ...entryCanonicalRoutes,
+            ...canonicalRoutes ?? {}
+        };
+    }
     await writeTanstackRegisterFile({
         entries: registerEntries,
         generatedDirName,
-        srcDirectory: appContext.srcDirectory
+        srcDirectory: appContext.srcDirectory,
+        canonicalRoutes
     });
 }
 function tanstackRouterPlugin(options = {}) {
@@ -202,4 +221,4 @@ function tanstackRouterPlugin(options = {}) {
 }
 const src_cli = tanstackRouterPlugin;
 export default src_cli;
-export { createTanstackRsbuildRouteSplittingProfile, generateTanstackRouterTypesSourceForEntry, isTanstackRouterFrameworkEnabled, isTanstackStartRouteModuleSource, resolveTanstackRouteCodeSplittingEnabled, tanstackRouterPlugin, writeTanstackRegisterFile, writeTanstackRouterTypesForEntries };
+export { collectCanonicalRoutesForEntry, createTanstackRsbuildRouteSplittingProfile, generateTanstackRouterTypesSourceForEntry, isTanstackRouterFrameworkEnabled, isTanstackStartRouteModuleSource, resolveTanstackRouteCodeSplittingEnabled, tanstackRouterPlugin, writeTanstackRegisterFile, writeTanstackRouterTypesForEntries };

package/dist/esm-node/cli/tanstackTypes.mjs

@@ -78,6 +78,78 @@ function createRouteStaticDataSnippet(opts) {
     if (!staticDataLines.length) return null;
     return `staticData: createRouteStaticData({\n    ${staticDataLines.join('\n    ')}\n  }),`;
 }
+const LOCALE_PARAM_SEGMENTS = new Set([
+    ':lang',
+    ':locale',
+    ':language',
+    '$lang',
+    '$locale',
+    '$language'
+]);
+function paramsTypeForCanonicalPath(canonicalPath) {
+    const fields = [];
+    for (const segment of canonicalPath.split('/'))if (segment) {
+        if ('*' === segment || '$' === segment) {
+            fields.push("'_splat'?: string");
+            continue;
+        }
+        if (segment.startsWith('{-$') && segment.endsWith('}')) {
+            fields.push(`${JSON.stringify(segment.slice(3, -1))}?: string`);
+            continue;
+        }
+        if (segment.startsWith('$')) {
+            fields.push(`${JSON.stringify(segment.slice(1))}: string`);
+            continue;
+        }
+        if (segment.startsWith(':')) {
+            const optional = segment.endsWith('?');
+            const name = segment.slice(1, optional ? void 0 : segment.length);
+            fields.push(`${JSON.stringify(optional ? name.slice(0, -1) : name)}${optional ? '?' : ''}: string`);
+        }
+    }
+    return fields.length > 0 ? `{ ${fields.join('; ')} }` : 'Record<string, never>';
+}
+function collectCanonicalRoutesForEntry(routes) {
+    const canonicalParams = new Map();
+    let hasI18nSurface = false;
+    const normalizeJoined = (joined)=>{
+        const collapsed = joined.replace(/\/+/g, '/');
+        const withLeading = collapsed.startsWith('/') ? collapsed : `/${collapsed}`;
+        return withLeading.length > 1 ? withLeading.replace(/\/+$/, '') : withLeading;
+    };
+    const record = (canonicalPath)=>{
+        const normalized = normalizeJoined(canonicalPath || '/');
+        const key = toTanstackPath(normalized);
+        if (!canonicalParams.has(key)) canonicalParams.set(key, paramsTypeForCanonicalPath(normalized));
+    };
+    const visit = (route, parentPath)=>{
+        let currentPath = parentPath;
+        if ('string' == typeof route.modernCanonicalPath) {
+            hasI18nSurface = true;
+            currentPath = normalizeJoined(route.modernCanonicalPath);
+        } else if ('string' == typeof route.path && route.path.length > 0) {
+            const segments = route.path.replace(/\[(.+?)\]/g, ':$1').split('/').filter(Boolean);
+            if ('' === parentPath && LOCALE_PARAM_SEGMENTS.has(segments[0])) {
+                hasI18nSurface = true;
+                segments.shift();
+            }
+            currentPath = segments.length ? normalizeJoined(`${parentPath}/${segments.join('/')}`) : parentPath;
+        }
+        const children = route.children;
+        if (children && children.length > 0) {
+            for (const child of children)visit(child, currentPath);
+            return;
+        }
+        record(currentPath || '/');
+    };
+    const rootModern = routes.find((route)=>route.isRoot);
+    const topLevel = rootModern ? rootModern.children ?? [] : routes;
+    for (const route of topLevel)visit(route, '');
+    if (!hasI18nSurface || 0 === canonicalParams.size) return null;
+    return Object.fromEntries([
+        ...canonicalParams.entries()
+    ].sort(([a], [b])=>a.localeCompare(b)));
+}
 async function isTanstackRouterFrameworkEnabled(appContext) {
     const runtimeConfigBase = path.join(appContext.srcDirectory, appContext.runtimeConfigFile);
     const runtimeConfigFile = findExists(JS_OR_TS_EXTS.map((ext)=>`${runtimeConfigBase}${ext}`));
@@ -427,4 +499,4 @@ export const router = createRouter({
         routerGenTs
     };
 }
-export { generateTanstackRouterTypesSourceForEntry, isTanstackRouterFrameworkEnabled };
+export { collectCanonicalRoutesForEntry, generateTanstackRouterTypesSourceForEntry, isTanstackRouterFrameworkEnabled };

package/dist/types/cli/index.d.ts

@@ -3,7 +3,7 @@ import type { NestedRouteForCli, PageRoute } from '@modern-js/types';
 import { type TanstackRouteCodeSplittingOption } from './routeSplitting';
 export type { TanstackRouteCodeSplittingOption, TanstackRsbuildRouteSplittingProfile, } from './routeSplitting';
 export { createTanstackRsbuildRouteSplittingProfile, isTanstackStartRouteModuleSource, resolveTanstackRouteCodeSplittingEnabled, } from './routeSplitting';
-export { generateTanstackRouterTypesSourceForEntry, isTanstackRouterFrameworkEnabled, } from './tanstackTypes';
+export { collectCanonicalRoutesForEntry, generateTanstackRouterTypesSourceForEntry, isTanstackRouterFrameworkEnabled, } from './tanstackTypes';
 export type TanstackRouterPluginOptions = {
     routesDir?: string;
     generatedDirName?: string;
@@ -14,6 +14,8 @@ export declare function writeTanstackRegisterFile(opts: {
     generatedDirName?: string;
     runtimeModule?: string;
     srcDirectory: string;
+    canonicalRoutes?: Record<string, string> | null;
+    i18nRuntimeModule?: string;
 }): Promise<void>;
 export declare function writeTanstackRouterTypesForEntries(opts: {
     appContext: AppToolsContext;

package/dist/types/cli/tanstackTypes.d.ts

@@ -1,5 +1,14 @@
 import type { AppToolsContext } from '@modern-js/app-tools';
 import type { NestedRouteForCli, PageRoute } from '@modern-js/types';
+/**
+ * Derive the canonical (language-agnostic) route map for an entry: the
+ * leading locale param is stripped and localized physical variants (routes
+ * carrying `modernCanonicalPath` metadata from `@modern-js/plugin-i18n`)
+ * collapse to their canonical pattern. Returns `null` when the entry has no
+ * i18n routing surface (no locale param and no localized variants), so plain
+ * TanStack apps never get a `@modern-js/plugin-i18n` module augmentation.
+ */
+export declare function collectCanonicalRoutesForEntry(routes: (NestedRouteForCli | PageRoute)[]): Record<string, string> | null;
 export declare function isTanstackRouterFrameworkEnabled(appContext: AppToolsContext): Promise<boolean>;
 export declare function generateTanstackRouterTypesSourceForEntry(opts: {
     appContext: AppToolsContext;

package/package.json

@@ -18,7 +18,7 @@
     "modern.js",
     "tanstack-router"
   ],
-  "version": "3.2.0-ultramodern.119",
+  "version": "3.2.0-ultramodern.120",
   "engines": {
     "node": ">=20"
   },
@@ -88,29 +88,29 @@
     "@swc/helpers": "^0.5.23",
     "@tanstack/react-router": "1.170.15",
     "@tanstack/router-core": "1.171.13",
-    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.2.0-ultramodern.119",
-    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.2.0-ultramodern.119",
-    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.2.0-ultramodern.119",
-    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.2.0-ultramodern.119"
+    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.2.0-ultramodern.120",
+    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.2.0-ultramodern.120",
+    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.2.0-ultramodern.120",
+    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.2.0-ultramodern.120"
   },
   "peerDependencies": {
-    "@modern-js/runtime": "3.2.0-ultramodern.119",
+    "@modern-js/runtime": "3.2.0-ultramodern.120",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   },
   "devDependencies": {
-    "@rslib/core": "0.21.5",
+    "@rslib/core": "0.22.0",
     "@tanstack/history": "1.162.0",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
-    "@types/node": "^25.9.1",
+    "@types/node": "^25.9.3",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "@typescript/native-preview": "7.0.0-dev.20260606.1",
+    "@typescript/native-preview": "7.0.0-dev.20260610.1",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
-    "@modern-js/app-tools": "npm:@bleedingdev/modern-js-app-tools@3.2.0-ultramodern.119",
-    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.2.0-ultramodern.119",
+    "@modern-js/app-tools": "npm:@bleedingdev/modern-js-app-tools@3.2.0-ultramodern.120",
+    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.2.0-ultramodern.120",
     "@scripts/rstest-config": "2.66.0"
   },
   "sideEffects": false,

package/src/cli/index.ts

@@ -23,6 +23,7 @@ import {
   type TanstackRouteCodeSplittingOption,
 } from './routeSplitting';
 import {
+  collectCanonicalRoutesForEntry,
   generateTanstackRouterTypesSourceForEntry,
   isTanstackRouterFrameworkEnabled,
 } from './tanstackTypes';
@@ -37,6 +38,7 @@ export {
   resolveTanstackRouteCodeSplittingEnabled,
 } from './routeSplitting';
 export {
+  collectCanonicalRoutesForEntry,
   generateTanstackRouterTypesSourceForEntry,
   isTanstackRouterFrameworkEnabled,
 } from './tanstackTypes';
@@ -124,6 +126,8 @@ async function writeFileIfChanged(filePath: string, content: string) {
 function createRegisterDtsContent(opts: {
   entries: string[];
   runtimeModule: string;
+  canonicalRoutes?: Record<string, string> | null;
+  i18nRuntimeModule?: string;
 }) {
   const importStatements = opts.entries
     .map(
@@ -135,6 +139,20 @@ function createRegisterDtsContent(opts: {
     .map((_, index) => `typeof router${index}`)
     .join(' | ');
 
+  const canonicalEntries = Object.entries(opts.canonicalRoutes ?? {});
+  const canonicalRoutesAugmentation =
+    canonicalEntries.length > 0
+      ? `
+declare module '${opts.i18nRuntimeModule || '@modern-js/plugin-i18n/runtime'}' {
+  interface UltramodernCanonicalRoutes {
+${canonicalEntries
+  .map(([routePath, paramsType]) => `    '${routePath}': ${paramsType};`)
+  .join('\n')}
+  }
+}
+`
+      : '';
+
   return `// This file is auto-generated by Modern.js. Do not edit manually.
 
 ${importStatements}
@@ -144,7 +162,7 @@ declare module '${opts.runtimeModule}' {
     router: ${routerUnionType};
   }
 }
-`;
+${canonicalRoutesAugmentation}`;
 }
 
 export async function writeTanstackRegisterFile(opts: {
@@ -152,12 +170,16 @@ export async function writeTanstackRegisterFile(opts: {
   generatedDirName?: string;
   runtimeModule?: string;
   srcDirectory: string;
+  canonicalRoutes?: Record<string, string> | null;
+  i18nRuntimeModule?: string;
 }) {
   const {
     entries,
     generatedDirName = DEFAULT_GENERATED_DIR_NAME,
     runtimeModule = '@modern-js/plugin-tanstack/runtime',
     srcDirectory,
+    canonicalRoutes,
+    i18nRuntimeModule,
   } = opts;
 
   if (entries.length === 0) {
@@ -172,7 +194,12 @@ export async function writeTanstackRegisterFile(opts: {
 
   await writeFileIfChanged(
     registerDtsPath,
-    createRegisterDtsContent({ entries, runtimeModule }),
+    createRegisterDtsContent({
+      entries,
+      runtimeModule,
+      canonicalRoutes,
+      i18nRuntimeModule,
+    }),
   );
 }
 
@@ -225,10 +252,23 @@ export async function writeTanstackRouterTypesForEntries(opts: {
     return a.localeCompare(b);
   });
 
+  // Merge the canonical (language-agnostic) route maps of every entry so the
+  // typed i18n Link covers all routes the app can navigate to.
+  let canonicalRoutes: Record<string, string> | null = null;
+  for (const entryName of registerEntries) {
+    const entryCanonicalRoutes = collectCanonicalRoutesForEntry(
+      routesByEntry[entryName],
+    );
+    if (entryCanonicalRoutes) {
+      canonicalRoutes = { ...entryCanonicalRoutes, ...(canonicalRoutes ?? {}) };
+    }
+  }
+
   await writeTanstackRegisterFile({
     entries: registerEntries,
     generatedDirName,
     srcDirectory: appContext.srcDirectory,
+    canonicalRoutes,
   });
 }
 

package/src/cli/tanstackTypes.ts

@@ -137,6 +137,137 @@ function createRouteStaticDataSnippet(opts: {
   )}\n  }),`;
 }
 
+const LOCALE_PARAM_SEGMENTS = new Set([
+  ':lang',
+  ':locale',
+  ':language',
+  '$lang',
+  '$locale',
+  '$language',
+]);
+
+type CanonicalAwareRoute = (NestedRouteForCli | PageRoute) & {
+  modernCanonicalPath?: string;
+  index?: boolean;
+  isRoot?: boolean;
+  children?: CanonicalAwareRoute[];
+};
+
+function paramsTypeForCanonicalPath(canonicalPath: string): string {
+  const fields: string[] = [];
+
+  for (const segment of canonicalPath.split('/')) {
+    if (!segment) {
+      continue;
+    }
+    if (segment === '*' || segment === '$') {
+      fields.push(`'_splat'?: string`);
+      continue;
+    }
+    if (segment.startsWith('{-$') && segment.endsWith('}')) {
+      fields.push(`${JSON.stringify(segment.slice(3, -1))}?: string`);
+      continue;
+    }
+    if (segment.startsWith('$')) {
+      fields.push(`${JSON.stringify(segment.slice(1))}: string`);
+      continue;
+    }
+    if (segment.startsWith(':')) {
+      const optional = segment.endsWith('?');
+      const name = segment.slice(1, optional ? undefined : segment.length);
+      fields.push(
+        `${JSON.stringify(optional ? name.slice(0, -1) : name)}${
+          optional ? '?' : ''
+        }: string`,
+      );
+    }
+  }
+
+  return fields.length > 0
+    ? `{ ${fields.join('; ')} }`
+    : 'Record<string, never>';
+}
+
+/**
+ * Derive the canonical (language-agnostic) route map for an entry: the
+ * leading locale param is stripped and localized physical variants (routes
+ * carrying `modernCanonicalPath` metadata from `@modern-js/plugin-i18n`)
+ * collapse to their canonical pattern. Returns `null` when the entry has no
+ * i18n routing surface (no locale param and no localized variants), so plain
+ * TanStack apps never get a `@modern-js/plugin-i18n` module augmentation.
+ */
+export function collectCanonicalRoutesForEntry(
+  routes: (NestedRouteForCli | PageRoute)[],
+): Record<string, string> | null {
+  const canonicalParams = new Map<string, string>();
+  let hasI18nSurface = false;
+
+  const normalizeJoined = (joined: string): string => {
+    const collapsed = joined.replace(/\/+/g, '/');
+    const withLeading = collapsed.startsWith('/') ? collapsed : `/${collapsed}`;
+    return withLeading.length > 1
+      ? withLeading.replace(/\/+$/, '')
+      : withLeading;
+  };
+
+  const record = (canonicalPath: string) => {
+    const normalized = normalizeJoined(canonicalPath || '/');
+    const key = toTanstackPath(normalized);
+    if (!canonicalParams.has(key)) {
+      canonicalParams.set(key, paramsTypeForCanonicalPath(normalized));
+    }
+  };
+
+  const visit = (route: CanonicalAwareRoute, parentPath: string) => {
+    let currentPath = parentPath;
+
+    if (typeof route.modernCanonicalPath === 'string') {
+      hasI18nSurface = true;
+      currentPath = normalizeJoined(route.modernCanonicalPath);
+    } else if (typeof route.path === 'string' && route.path.length > 0) {
+      const segments = route.path
+        .replace(/\[(.+?)\]/g, ':$1')
+        .split('/')
+        .filter(Boolean);
+      if (parentPath === '' && LOCALE_PARAM_SEGMENTS.has(segments[0])) {
+        hasI18nSurface = true;
+        segments.shift();
+      }
+      currentPath = segments.length
+        ? normalizeJoined(`${parentPath}/${segments.join('/')}`)
+        : parentPath;
+    }
+
+    const children = route.children;
+    if (children && children.length > 0) {
+      for (const child of children) {
+        visit(child, currentPath);
+      }
+      return;
+    }
+
+    // Leaf page or index route: a navigable target.
+    record(currentPath || '/');
+  };
+
+  const rootModern = routes.find(
+    route => (route as CanonicalAwareRoute).isRoot,
+  ) as CanonicalAwareRoute | undefined;
+  const topLevel = rootModern ? (rootModern.children ?? []) : routes;
+
+  for (const route of topLevel) {
+    visit(route as CanonicalAwareRoute, '');
+  }
+
+  if (!hasI18nSurface || canonicalParams.size === 0) {
+    return null;
+  }
+
+  return Object.fromEntries(
+    [...canonicalParams.entries()].sort(([a], [b]) => a.localeCompare(b)),
+  );
+}
+
 export async function isTanstackRouterFrameworkEnabled(
   appContext: AppToolsContext,
 ): Promise<boolean> {

package/tests/router/cli.test.ts

@@ -123,6 +123,82 @@ describe('tanstack router cli plugin', () => {
     );
   });
 
+  test('writes plugin-i18n module augmentation when canonicalRoutes are provided', async () => {
+    tempDir = await mkdtemp(path.join(tmpdir(), 'modern-tanstack-cli-'));
+    const srcDirectory = path.join(tempDir, 'src');
+
+    await writeTanstackRegisterFile({
+      entries: ['main'],
+      generatedDirName: 'tanstack',
+      srcDirectory,
+      canonicalRoutes: {
+        '/': 'Record<string, never>',
+        '/products/$slug': '{ "slug": string }',
+      },
+    });
+
+    const register = await readFile(
+      path.join(srcDirectory, 'tanstack', 'register.gen.d.ts'),
+      'utf-8',
+    );
+
+    expect(register).toContain(
+      "declare module '@modern-js/plugin-i18n/runtime'",
+    );
+    expect(register).toContain('interface UltramodernCanonicalRoutes');
+    expect(register).toContain("'/': Record<string, never>;");
+    expect(register).toContain('\'/products/$slug\': { "slug": string };');
+  });
+
+  test('does not emit plugin-i18n augmentation when canonicalRoutes is absent (back-compat)', async () => {
+    tempDir = await mkdtemp(path.join(tmpdir(), 'modern-tanstack-cli-'));
+    const srcDirectory = path.join(tempDir, 'src');
+
+    await writeTanstackRegisterFile({
+      entries: ['main'],
+      generatedDirName: 'tanstack',
+      srcDirectory,
+      // No canonicalRoutes provided at all — plain TanStack app
+    });
+
+    const register = await readFile(
+      path.join(srcDirectory, 'tanstack', 'register.gen.d.ts'),
+      'utf-8',
+    );
+
+    expect(register).not.toContain('plugin-i18n');
+    expect(register).not.toContain('UltramodernCanonicalRoutes');
+    // But the standard TanStack runtime augmentation must still be present.
+    expect(register).toContain(
+      "declare module '@modern-js/plugin-tanstack/runtime'",
+    );
+  });
+
+  test('uses a custom i18nRuntimeModule when specified', async () => {
+    tempDir = await mkdtemp(path.join(tmpdir(), 'modern-tanstack-cli-'));
+    const srcDirectory = path.join(tempDir, 'src');
+
+    await writeTanstackRegisterFile({
+      entries: ['main'],
+      generatedDirName: 'tanstack',
+      srcDirectory,
+      canonicalRoutes: {
+        '/talks': 'Record<string, never>',
+      },
+      i18nRuntimeModule: '@my-org/i18n/runtime',
+    });
+
+    const register = await readFile(
+      path.join(srcDirectory, 'tanstack', 'register.gen.d.ts'),
+      'utf-8',
+    );
+
+    expect(register).toContain("declare module '@my-org/i18n/runtime'");
+    expect(register).not.toContain(
+      "declare module '@modern-js/plugin-i18n/runtime'",
+    );
+  });
+
   test('claims custom routes, injects runtime plugin, and merges route specs', async () => {
     tempDir = await mkdtemp(path.join(tmpdir(), 'modern-tanstack-cli-'));
     const srcDirectory = path.join(tempDir, 'src');

package/tests/router/tanstackTypes.test.ts

@@ -3,7 +3,10 @@ import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
-import { generateTanstackRouterTypesSourceForEntry } from '../../src/cli/tanstackTypes';
+import {
+  collectCanonicalRoutesForEntry,
+  generateTanstackRouterTypesSourceForEntry,
+} from '../../src/cli/tanstackTypes';
 
 const execFileAsync = promisify(execFile);
 
@@ -244,3 +247,230 @@ describe('tanstack router type generation', () => {
     expect(routerGenTs).not.toContain('route__lang__layout.addChildren([');
   });
 });
+
+describe('collectCanonicalRoutesForEntry', () => {
+  test('returns null for a route tree with no locale param and no canonical metadata', () => {
+    const result = collectCanonicalRoutesForEntry([
+      {
+        type: 'nested',
+        id: 'layout',
+        isRoot: true,
+        children: [
+          {
+            type: 'nested',
+            id: 'about/page',
+            path: 'about',
+          },
+          {
+            type: 'nested',
+            id: 'contact/page',
+            path: 'contact',
+          },
+        ],
+      },
+    ] as any);
+
+    expect(result).toBeNull();
+  });
+
+  test('strips leading :lang param and maps index under :lang to "/"', () => {
+    const result = collectCanonicalRoutesForEntry([
+      {
+        type: 'nested',
+        id: 'layout',
+        isRoot: true,
+        children: [
+          {
+            type: 'nested',
+            id: '(lang)/layout',
+            path: ':lang',
+            children: [
+              {
+                type: 'nested',
+                id: '(lang)/page',
+                index: true,
+              },
+              {
+                type: 'nested',
+                id: '(lang)/about/page',
+                path: 'about',
+              },
+            ],
+          },
+        ],
+      },
+    ] as any);
+
+    expect(result).not.toBeNull();
+    expect(result!['/']).toBe('Record<string, never>');
+    expect(result!['/about']).toBe('Record<string, never>');
+  });
+
+  test('converts :slug to $slug with required params type', () => {
+    const result = collectCanonicalRoutesForEntry([
+      {
+        type: 'nested',
+        id: 'layout',
+        isRoot: true,
+        children: [
+          {
+            type: 'nested',
+            id: '(lang)/layout',
+            path: ':lang',
+            children: [
+              {
+                type: 'nested',
+                id: '(lang)/products/(slug)/page',
+                path: 'products/:slug',
+              },
+            ],
+          },
+        ],
+      },
+    ] as any);
+
+    expect(result).not.toBeNull();
+    expect(result!['/products/$slug']).toBe('{ "slug": string }');
+  });
+
+  test('converts :slug? to optional {-$slug} with optional params type', () => {
+    const result = collectCanonicalRoutesForEntry([
+      {
+        type: 'nested',
+        id: 'layout',
+        isRoot: true,
+        children: [
+          {
+            type: 'nested',
+            id: '(lang)/layout',
+            path: ':lang',
+            children: [
+              {
+                type: 'nested',
+                id: '(lang)/optional/(slug$)/page',
+                path: 'optional/:slug?',
+              },
+            ],
+          },
+        ],
+      },
+    ] as any);
+
+    expect(result).not.toBeNull();
+    expect(result!['/optional/{-$slug}']).toBe('{ "slug"?: string }');
+  });
+
+  test('converts * splat to $ with optional _splat param', () => {
+    const result = collectCanonicalRoutesForEntry([
+      {
+        type: 'nested',
+        id: 'layout',
+        isRoot: true,
+        children: [
+          {
+            type: 'nested',
+            id: '(lang)/layout',
+            path: ':lang',
+            children: [
+              {
+                type: 'nested',
+                id: '(lang)/files/page',
+                path: 'files/*',
+              },
+            ],
+          },
+        ],
+      },
+    ] as any);
+
+    expect(result).not.toBeNull();
+    expect(result!['/files/$']).toBe("{ '_splat'?: string }");
+  });
+
+  test('collapses localized variants with shared modernCanonicalPath to one canonical key', () => {
+    // This reuses the same fixture shape as the 'preserves typed child trees'
+    // test but adds modernCanonicalPath fields as plugin-i18n now emits.
+    const result = collectCanonicalRoutesForEntry([
+      {
+        type: 'nested',
+        id: 'layout',
+        isRoot: true,
+        children: [
+          {
+            type: 'nested',
+            id: '(lang)/layout',
+            path: ':lang',
+            children: [
+              {
+                type: 'nested',
+                id: '(lang)/products/(slug)/page',
+                path: 'products/:slug',
+                modernCanonicalPath: '/products/:slug',
+              },
+              {
+                type: 'nested',
+                id: '(lang)/products/(slug)/page__localised_produkty_slug',
+                path: 'produkty/:slug',
+                modernCanonicalPath: '/products/:slug',
+              },
+              {
+                type: 'nested',
+                id: '(lang)/optional/(slug$)/page__localised_volitelne_slug',
+                path: 'volitelne/:slug?',
+                modernCanonicalPath: '/optional/:slug?',
+              },
+            ],
+          },
+        ],
+      },
+    ] as any);
+
+    expect(result).not.toBeNull();
+    // Two physical variants share the same canonical path — only one entry.
+    const keys = Object.keys(result!);
+    // /products/$slug and /optional/{-$slug} — exactly 2 keys with params
+    expect(keys.filter(k => k.startsWith('/products'))).toHaveLength(1);
+    expect(result!['/products/$slug']).toBe('{ "slug": string }');
+    expect(result!['/optional/{-$slug}']).toBe('{ "slug"?: string }');
+    // The Czech localized path must not appear as a separate key.
+    expect('/produkty/$slug' in result!).toBe(false);
+  });
+
+  test('output is sorted alphabetically by canonical key', () => {
+    const result = collectCanonicalRoutesForEntry([
+      {
+        type: 'nested',
+        id: 'layout',
+        isRoot: true,
+        children: [
+          {
+            type: 'nested',
+            id: '(lang)/layout',
+            path: ':lang',
+            children: [
+              {
+                type: 'nested',
+                id: '(lang)/products/(slug)/page',
+                path: 'products/:slug',
+              },
+              {
+                type: 'nested',
+                id: '(lang)/about/page',
+                path: 'about',
+              },
+              {
+                type: 'nested',
+                id: '(lang)/page',
+                index: true,
+              },
+            ],
+          },
+        ],
+      },
+    ] as any);
+
+    expect(result).not.toBeNull();
+    const keys = Object.keys(result!);
+    expect(keys).toEqual([...keys].sort((a, b) => a.localeCompare(b)));
+  });
+});