fimo 0.17.0 → 0.19.0

package/dist/runtime/sveltekit/preview.js

@@ -1,4 +1,4 @@
-import { getPreviewLocationChange, getPreviewParentOrigin } from '../shared/preview-location.js';
+import { getDocumentLocale, getPreviewLocationChange, getPreviewParentOrigin } from '../shared/preview-location.js';
 /** Load the platform preview script once. Empty configuration keeps preview disabled. */
 export function ensurePreviewScript(src) {
     if (!src) {
@@ -13,14 +13,19 @@ export function ensurePreviewScript(src) {
     }
     return true;
 }
-/** Report where the app is now. Studio keeps its URL and route selector in sync from this. */
-export function sendPreviewLocation() {
+/**
+ * Report where the app is now, and in which locale. Studio keeps its URL,
+ * route selector and content locale in sync from this.
+ *
+ * `locale` defaults to the locale the SvelteKit shell rendered into
+ * `<html lang>`; pass one explicitly when the app resolves it somewhere the
+ * document does not show, for example a cookie or a user preference.
+ */
+export function sendPreviewLocation(locale) {
     const parentOrigin = getPreviewParentOrigin();
-    const locationChange = getPreviewLocationChange(window.location);
     window.parent.postMessage({
         type: 'nav/locationChange',
-        // Query and hash state only travels to an established parent origin.
-        payload: parentOrigin ? locationChange : { path: locationChange.path },
+        payload: getPreviewLocationChange(window.location, locale ?? getDocumentLocale(document, 'en'), parentOrigin),
     }, parentOrigin ?? '*');
 }
 /** Reliable-delivery reply: the parent retries an unacknowledged message forever. */
@@ -48,7 +53,7 @@ async function refreshContent(message, invalidateAll) {
  * Only messages from the established parent origin are honored. History stays
  * native, so Studio's back/forward controls need no protocol of their own.
  */
-export function connectPreview({ goto, invalidateAll }) {
+export function connectPreview({ goto, invalidateAll, locale }) {
     const onMessage = (event) => {
         const parentOrigin = getPreviewParentOrigin();
         if (event.source !== window.parent || !parentOrigin || event.origin !== parentOrigin) {
@@ -63,7 +68,7 @@ export function connectPreview({ goto, invalidateAll }) {
                 return;
             case 'nav/read-routes':
                 // The app owns its route table; answer with where it actually is.
-                sendPreviewLocation();
+                sendPreviewLocation(locale?.());
                 return;
             case 'content/refresh':
                 void refreshContent(message, invalidateAll);

package/dist/runtime/templates.d.ts

@@ -62,6 +62,25 @@ interface PkgWithDeps {
     dependencies?: Record<string, string>;
     devDependencies?: Record<string, string>;
 }
+interface PkgWithScripts {
+    scripts?: Record<string, string>;
+}
+/**
+ * Point the build script's `fimo validate` at the exact CLI that scaffolded the
+ * project.
+ *
+ * Inside an npm script a bare `fimo` resolves to whatever is installed in the
+ * project, which is normally the pinned dependency — but only when the install
+ * is current. The hosted build installs the tree itself and then runs this
+ * script, and `validate` is an API client: resolving it from install state
+ * means a project can be checked by a different version than the one it pins,
+ * which is how a project can look clean locally and fail on publish.
+ *
+ * Only an exact npm version is pinned. A source checkout resolves to
+ * `file:<path>`, which is not an npx spec — and there a bare `fimo` already
+ * runs the very binary being developed, which is the point of that flow.
+ */
+export declare function rewriteFimoValidateCommand(pkg: PkgWithScripts, pin?: string | null): boolean;
 /**
  * Rewrite `fimo` (in dependencies + devDependencies) to the current pin. Only
  * touches entries that look like a value we own: the template's dist-tag, an old

package/dist/runtime/templates.js

@@ -164,6 +164,39 @@ function findDevJson(startPath) {
         current = parent;
     }
 }
+/**
+ * Point the build script's `fimo validate` at the exact CLI that scaffolded the
+ * project.
+ *
+ * Inside an npm script a bare `fimo` resolves to whatever is installed in the
+ * project, which is normally the pinned dependency — but only when the install
+ * is current. The hosted build installs the tree itself and then runs this
+ * script, and `validate` is an API client: resolving it from install state
+ * means a project can be checked by a different version than the one it pins,
+ * which is how a project can look clean locally and fail on publish.
+ *
+ * Only an exact npm version is pinned. A source checkout resolves to
+ * `file:<path>`, which is not an npx spec — and there a bare `fimo` already
+ * runs the very binary being developed, which is the point of that flow.
+ */
+export function rewriteFimoValidateCommand(pkg, pin = resolveFimoPin()) {
+    if (!pin || !/^\d+\.\d+\.\d+/.test(pin)) {
+        return false;
+    }
+    const build = pkg.scripts?.build;
+    if (typeof build !== 'string') {
+        return false;
+    }
+    // Only the validate invocation. Anything else the script runs through `fimo`
+    // is local file work, not an API client, and pinning it would add a fetch for
+    // no reason.
+    const pinned = build.replace(/\bfimo validate\b/, `npx fimo@${pin} validate`);
+    if (pinned === build) {
+        return false;
+    }
+    pkg.scripts.build = pinned;
+    return true;
+}
 /**
  * Rewrite `fimo` (in dependencies + devDependencies) to the current pin. Only
  * touches entries that look like a value we own: the template's dist-tag, an old

package/dist/scripts/sync-forms.js

@@ -41,7 +41,7 @@ function frameworkFormsTarget(framework) {
         return 'next';
     if (framework === 'astro')
         return 'astro';
-    if (framework === 'sveltekit' || framework === 'sveltekit-1')
+    if (framework === 'sveltekit')
         return 'sveltekit';
     return null;
 }

package/dist/scripts/sync-schemas.js

@@ -120,10 +120,7 @@ function contentRuntimeImportFor(framework) {
     if (framework === 'astro') {
         return 'fimo/astro';
     }
-    // @vercel/frameworks reports SvelteKit as `sveltekit-1`, while Fimo's
-    // public runtime profile is `sveltekit`. Both describe the same codegen
-    // target; callers may supply either the detector evidence or the profile.
-    if (framework === 'sveltekit' || framework === 'sveltekit-1') {
+    if (framework === 'sveltekit') {
         return 'fimo/sveltekit';
     }
     return 'fimo/ui';

package/dist/scripts/validate-fimo-config.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { FimoAppConfigSchema } from '@fimo/api-contracts';
 import { resolveFimoConfigPath } from '../runtime/shared/fimo-config.server.js';
+import { validatePageRegistrySchemaReferences } from './validate-page-registry.js';
 export function validateFimoConfig(cwd) {
     const configPath = resolveFimoConfigPath(cwd);
     if (!fs.existsSync(configPath)) {
@@ -17,7 +18,10 @@ export function validateFimoConfig(cwd) {
     }
     const parsed = FimoAppConfigSchema.safeParse(value);
     if (parsed.success) {
-        return { errors: [], configChecked: true };
+        return {
+            errors: validatePageRegistrySchemaReferences(cwd, value, displayPath),
+            configChecked: true,
+        };
     }
     return {
         errors: parsed.error.issues.map((issue) => {

package/dist/scripts/validate-page-registry.d.ts

@@ -0,0 +1,2 @@
+/** Cross-check Page config references against the project's schema source files. */
+export declare function validatePageRegistrySchemaReferences(cwd: string, config: Record<string, unknown>, displayPath: string): string[];

package/dist/scripts/validate-page-registry.js

@@ -0,0 +1,167 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pageSourceParamExpressions, parsePageParamExpression, } from '@fimo/api-contracts';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function fieldList(value) {
+    if (typeof value === 'string') {
+        return [value];
+    }
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function queryFields(query) {
+    if (!isRecord(query)) {
+        return [];
+    }
+    const fields = new Set();
+    if (isRecord(query.where)) {
+        for (const field of Object.keys(query.where)) {
+            if (!field.startsWith('$')) {
+                fields.add(field.split('.')[0]);
+            }
+        }
+    }
+    for (const sort of fieldList(query.sort)) {
+        fields.add(sort.replace(/^-/, '').split('.')[0]);
+    }
+    for (const field of [...fieldList(query.fields), ...fieldList(query.populate)]) {
+        fields.add(field.split('.')[0]);
+    }
+    return [...fields];
+}
+function readSchemas(cwd) {
+    const directory = path.join(cwd, 'src/schemas');
+    if (!fs.existsSync(directory)) {
+        return null;
+    }
+    const schemas = new Map();
+    for (const file of fs.readdirSync(directory).filter((name) => name.endsWith('.json'))) {
+        const fallbackUid = path.basename(file, '.json');
+        let value;
+        try {
+            value = JSON.parse(fs.readFileSync(path.join(directory, file), 'utf8'));
+        }
+        catch {
+            schemas.set(fallbackUid, { fields: {}, isSingleton: false, valid: false });
+            continue;
+        }
+        if (!isRecord(value)) {
+            schemas.set(fallbackUid, { fields: {}, isSingleton: false, valid: false });
+            continue;
+        }
+        const uid = typeof value.uid === 'string' && value.uid ? value.uid : fallbackUid;
+        schemas.set(uid, {
+            fields: isRecord(value.fields) ? value.fields : {},
+            isSingleton: value.isSingleton === true,
+            valid: true,
+        });
+    }
+    return schemas;
+}
+function schemaFields(schema) {
+    return new Set([...Object.keys(schema.fields), 'id', 'slug']);
+}
+function queryableFields(schema) {
+    return new Set([...schemaFields(schema), 'createdAt', 'updatedAt']);
+}
+function validateQuery(query, pointer, schema, params, schemas) {
+    const errors = [];
+    const unknownField = queryFields(query).find((field) => !queryableFields(schema).has(field));
+    if (unknownField) {
+        errors.push(`${pointer}: Query field "${unknownField}" does not exist on the referenced schema.`);
+    }
+    for (const expression of pageSourceParamExpressions(query)) {
+        const parsed = parsePageParamExpression(expression);
+        const binding = parsed ? params[parsed.param] : undefined;
+        if (!parsed || !binding || typeof binding.schema !== 'string') {
+            continue;
+        }
+        const boundSchema = schemas.get(binding.schema);
+        const field = parsed.field.split('.')[0];
+        if (boundSchema?.valid && !schemaFields(boundSchema).has(field)) {
+            errors.push(`${pointer}: ${expression} reads missing field "${field}" from schema "${binding.schema}".`);
+        }
+    }
+    return errors;
+}
+/** Cross-check Page config references against the project's schema source files. */
+export function validatePageRegistrySchemaReferences(cwd, config, displayPath) {
+    const schemas = readSchemas(cwd);
+    if (!schemas || !isRecord(config.routes)) {
+        return [];
+    }
+    const errors = [];
+    for (const [routeId, rawRoute] of Object.entries(config.routes)) {
+        if (!isRecord(rawRoute)) {
+            continue;
+        }
+        const params = isRecord(rawRoute.params) ? rawRoute.params : {};
+        for (const [param, binding] of Object.entries(params)) {
+            const pointer = `${displayPath}#routes.${routeId}.params.${param}`;
+            if (typeof binding.schema !== 'string') {
+                continue;
+            }
+            const schema = schemas.get(binding.schema);
+            if (!schema) {
+                errors.push(`${pointer}.schema: Unknown schema "${binding.schema}".`);
+                continue;
+            }
+            if (!schema.valid) {
+                continue;
+            }
+            if (schema.isSingleton) {
+                errors.push(`${pointer}.schema: Page params require a Collection, but "${binding.schema}" is a Single.`);
+            }
+            const fields = schemaFields(schema);
+            for (const key of ['queryField', 'displayField']) {
+                const field = binding[key];
+                if (typeof field === 'string' && !fields.has(field)) {
+                    errors.push(`${pointer}.${key}: Field "${field}" does not exist on schema "${binding.schema}".`);
+                }
+            }
+            if (typeof binding.queryField === 'string' && !['id', 'slug'].includes(binding.queryField)) {
+                const definition = schema.fields[binding.queryField];
+                if (isRecord(definition)) {
+                    if (definition.required !== true) {
+                        errors.push(`${pointer}.queryField: Custom URL field "${binding.queryField}" must set "required": true.`);
+                    }
+                    if (definition.unique !== true) {
+                        errors.push(`${pointer}.queryField: Custom URL field "${binding.queryField}" must set "unique": true.`);
+                    }
+                }
+            }
+            errors.push(...validateQuery(binding.query, `${pointer}.query`, schema, params, schemas));
+        }
+        if (!isRecord(rawRoute.sources)) {
+            continue;
+        }
+        for (const [sourceName, source] of Object.entries(rawRoute.sources)) {
+            if (!isRecord(source) || (source.type !== 'single' && source.type !== 'collection')) {
+                continue;
+            }
+            const pointer = `${displayPath}#routes.${routeId}.sources.${sourceName}`;
+            if (typeof source.schema !== 'string') {
+                continue;
+            }
+            const schema = schemas.get(source.schema);
+            if (!schema) {
+                errors.push(`${pointer}.schema: Unknown schema "${source.schema}".`);
+                continue;
+            }
+            if (!schema.valid) {
+                continue;
+            }
+            if (source.type === 'single' && !schema.isSingleton) {
+                errors.push(`${pointer}.schema: Source expects a Single, but "${source.schema}" is a Collection.`);
+            }
+            if (source.type === 'collection' && schema.isSingleton) {
+                errors.push(`${pointer}.schema: Source expects a Collection, but "${source.schema}" is a Single.`);
+            }
+            if (source.type === 'collection') {
+                errors.push(...validateQuery(source.query, `${pointer}.query`, schema, params, schemas));
+            }
+        }
+    }
+    return errors;
+}

package/dist/scripts/validate-route-metadata.js

@@ -1,5 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { pageSourceParamExpressions } from '@fimo/api-contracts';
+import { FIMO_LOCALE_PARAM, resolveRouteContract } from '../runtime/routes/index.js';
 import { resolveFimoConfigPath } from '../runtime/shared/fimo-config.server.js';
 import { parseRoutesSource } from './lib/parse-routes-file.js';
 function readJson(filePath) {
@@ -10,20 +12,15 @@ function readJson(filePath) {
         return {};
     }
 }
-function getParamNamesFromPath(routePath) {
-    const normalized = routePath === '/' ? '/' : routePath.replace(/\/+$/, '');
-    const segments = normalized.split('/').filter(Boolean);
-    return segments.filter((segment) => segment.startsWith(':')).map((segment) => segment.slice(1));
-}
 function loadConfigRoutes(config) {
     const configRoutes = config.routes ?? {};
     return Object.entries(configRoutes).map(([id, route]) => ({
         id,
         path: route.path ?? '/',
         label: route.label ?? null,
-        paramNames: getParamNamesFromPath(route.path ?? '/'),
-        params: route.params ?? null,
+        sources: route.sources ?? null,
         seo: route.seo ?? null,
+        contract: resolveRouteContract(id, route),
     }));
 }
 export function validateRouteMetadata(options = {}) {
@@ -47,26 +44,26 @@ export function validateRouteMetadata(options = {}) {
     const pathToFile = new Map();
     for (const fr of fileRoutes) {
         if (fr.path && fr.file) {
-            pathToFile.set(fr.path, fr.file);
+            pathToFile.set(normalizeLocaleSpelling(fr.path), fr.file);
         }
     }
     const i18n = validateI18nConfig(config);
     errors.push(...i18n.errors);
     const configRoutes = loadConfigRoutes(config);
     // Cross-validate: non-layout routes in routes.ts should have matching fimo-config entries
-    const configPaths = new Set(configRoutes.map((r) => r.path));
+    const configPaths = new Set(configRoutes.flatMap(registrablePaths));
     for (const fileRoute of fileRoutes) {
         if (fileRoute.isLayout) {
             continue;
         }
-        if (fileRoute.path && !configPaths.has(fileRoute.path)) {
+        if (fileRoute.path && !configPaths.has(normalizeLocaleSpelling(fileRoute.path))) {
             errors.push(`Route with path "${fileRoute.path}" (file: "${fileRoute.file}") exists in src/routes.ts but has no matching entry in ${configDisplayPath}.\nFix: add a route entry to ${configDisplayPath} "routes" with a matching "path".`);
         }
     }
     // Cross-validate: fimo-config routes should have matching routes.ts entries
-    const filePaths = new Set(fileRoutes.filter((r) => !r.isLayout && r.path).map((r) => r.path));
+    const filePaths = new Set(fileRoutes.filter((r) => !r.isLayout && r.path).map((r) => normalizeLocaleSpelling(r.path)));
     for (const route of configRoutes) {
-        if (!filePaths.has(route.path)) {
+        if (!registrablePaths(route).some((candidate) => filePaths.has(candidate))) {
             errors.push(`Route "${route.id}" (${route.path}) exists in ${configDisplayPath} but is not registered in src/routes.ts.\nFix: add the route to src/routes.ts. Example: route('${route.path.replace(/^\//, '')}', './pages/YourPage.tsx')`);
         }
     }
@@ -76,7 +73,7 @@ export function validateRouteMetadata(options = {}) {
             fileRoutes,
             i18n,
             configDisplayPath,
-            routesSourceUsesFimoRoutes: sourceUsesFimoRoutes(fileRoutes, routesFilePath),
+            routesSourceUsesLegacyHelper: sourceUsesLegacyFimoRoutes(routesFilePath),
         }));
     }
     const routeById = new Map();
@@ -88,9 +85,18 @@ export function validateRouteMetadata(options = {}) {
         }
         routeById.set(route.id, route);
     }
+    for (const route of configRoutes) {
+        for (const issue of route.contract.issues) {
+            errors.push(`Route "${route.id}" (${route.path}): ${issue.message}\nFix: ${issue.fix}`);
+        }
+        errors.push(...validatePageSources(route));
+    }
+    errors.push(...validateRouteShapeCollisions(configRoutes));
     // Validate route modules (exports, loaders, meta)
     for (const route of configRoutes) {
-        const file = pathToFile.get(route.path);
+        const file = registrablePaths(route)
+            .map((candidate) => pathToFile.get(candidate))
+            .find(Boolean);
         if (!file) {
             continue;
         }
@@ -99,22 +105,6 @@ export function validateRouteMetadata(options = {}) {
             errors.push(`Route "${route.id}" (${route.path}) references missing module "${file}".\nFix: create the file at src/${file}.`);
             continue;
         }
-        if (route.paramNames.length > 0) {
-            if (!route.params) {
-                errors.push(`Dynamic route "${route.id}" (${route.path}) needs \`params\` metadata to generate prerender URLs.\nFix: add to the route in ${configDisplayPath}: \`"params": { "${route.paramNames[0] || 'param'}": { "schema": "SchemaName", "queryField": "${route.paramNames[0] || 'slug'}", "displayField": "title" } }\``);
-            }
-            else {
-                for (const paramName of route.paramNames) {
-                    const paramInfo = route.params[paramName];
-                    if (!paramInfo || typeof paramInfo !== 'object') {
-                        errors.push(`Dynamic route "${route.id}" (${route.path}): param "${paramName}" must be an object with "schema" and "queryField".\nFix: \`"params": { "${paramName}": { "schema": "SchemaName", "queryField": "${paramName}" } }\``);
-                    }
-                    else if (!paramInfo.schema || !paramInfo.queryField) {
-                        errors.push(`Dynamic route "${route.id}" (${route.path}): param "${paramName}" is missing ${!paramInfo.schema ? '"schema"' : '"queryField"'}.\nFix: \`"${paramName}": { "schema": "SchemaName", "queryField": "${paramName}" }\``);
-                    }
-                }
-            }
-        }
         if (route.seo) {
             const GLOBAL_VARIABLES = new Set(['siteName', 'label']);
             const seoFields = [
@@ -132,15 +122,17 @@ export function validateRouteMetadata(options = {}) {
                     if (GLOBAL_VARIABLES.has(variable)) {
                         continue;
                     }
+                    // Only entry params carry data a template can read; the locale
+                    // segment resolves to a tag, never to an entry.
+                    const entryParamNames = route.contract.entryParams.map((param) => param.name);
+                    const availableParams = entryParamNames.length > 0 ? entryParamNames.join(', ') : 'none';
                     if (variable.includes('.')) {
                         const paramKey = variable.split('.')[0];
-                        if (!route.params || !route.params[paramKey]) {
-                            const availableParams = route.params ? Object.keys(route.params).join(', ') : 'none';
-                            errors.push(`Route "${route.id}" (${route.path}): SEO ${field.name} references "{{${variable}}}" but "${paramKey}" is not a declared param. Available params: ${availableParams}.`);
+                        if (!entryParamNames.includes(paramKey)) {
+                            errors.push(`Route "${route.id}" (${route.path}): SEO ${field.name} references "{{${variable}}}" but "${paramKey}" is not a declared entry param. Available params: ${availableParams}.`);
                         }
                     }
                     else {
-                        const availableParams = route.params ? Object.keys(route.params).join(', ') : 'none';
                         errors.push(`Route "${route.id}" (${route.path}): SEO ${field.name} references "{{${variable}}}" which is not a global variable (siteName, label) and not a dotted param reference (e.g., "{{param.field}}"). Available params: ${availableParams}.`);
                     }
                 }
@@ -149,6 +141,52 @@ export function validateRouteMetadata(options = {}) {
     }
     return { errors, routesChecked: configRoutes.length };
 }
+function validatePageSources(route) {
+    if (!route.sources) {
+        return [];
+    }
+    const errors = [];
+    const entryParamNames = new Set(route.contract.entryParams.map((param) => param.name));
+    for (const [sourceName, rawSource] of Object.entries(route.sources)) {
+        if (!/^[A-Za-z][\w-]*$/.test(sourceName) || !isRecord(rawSource)) {
+            errors.push(`Route "${route.id}" (${route.path}): source "${sourceName}" is not a valid named source.`);
+            continue;
+        }
+        if (rawSource.type === 'labels') {
+            const match = rawSource.match;
+            if (!Array.isArray(match) ||
+                match.length === 0 ||
+                match.some((pattern) => {
+                    if (typeof pattern !== 'string')
+                        return true;
+                    const wildcard = pattern.indexOf('*');
+                    return wildcard !== -1 && !(pattern.length > 2 && pattern.endsWith('.*') && wildcard === pattern.length - 1);
+                })) {
+                errors.push(`Route "${route.id}" (${route.path}): Labels source "${sourceName}" needs exact keys or prefixes ending in .*.`);
+            }
+            continue;
+        }
+        if (rawSource.type !== 'single' && rawSource.type !== 'collection') {
+            errors.push(`Route "${route.id}" (${route.path}): source "${sourceName}" type must be labels, single, or collection.`);
+            continue;
+        }
+        if (typeof rawSource.schema !== 'string' || !rawSource.schema) {
+            errors.push(`Route "${route.id}" (${route.path}): source "${sourceName}" needs a schema.`);
+        }
+        if (rawSource.type === 'collection' && rawSource.query !== undefined && !isRecord(rawSource.query)) {
+            errors.push(`Route "${route.id}" (${route.path}): Collection source "${sourceName}" query must be an object.`);
+            continue;
+        }
+        for (const expression of pageSourceParamExpressions(rawSource.query)) {
+            const match = /^\$params\.([A-Za-z_][\w-]*)\.([A-Za-z_][\w.-]*)$/.exec(expression);
+            const param = match?.[1];
+            if (!param || !entryParamNames.has(param)) {
+                errors.push(`Route "${route.id}" (${route.path}): source "${sourceName}" references undeclared param "${param ?? expression}". Fix: use $params.<declared-entry-param>.<field>.`);
+            }
+        }
+    }
+    return errors;
+}
 function validateI18nConfig(config) {
     const rawI18n = isRecord(config.i18n) ? config.i18n : {};
     const errors = [];
@@ -192,37 +230,90 @@ function validateI18nConfig(config) {
         defaultLocale: effectiveDefaultLocale,
         locales,
         routingStrategy,
-        prefixDefaultLocale: rawRouting.prefixDefaultLocale === true,
         errors,
     };
 }
+/**
+ * Two routes that produce the same URL are only detectable once the locale
+ * segment is stripped: `/pricing` and `/:locale/pricing` both answer
+ * `/pricing`, and nothing downstream can decide which one owns it.
+ */
+function validateRouteShapeCollisions(configRoutes) {
+    const errors = [];
+    const byShape = new Map();
+    for (const route of configRoutes) {
+        const shape = route.contract.canonicalPath
+            .split('/')
+            .map((segment) => (segment.startsWith(':') ? ':param' : segment))
+            .join('/');
+        const previous = byShape.get(shape);
+        if (previous && (previous.contract.localeParam || route.contract.localeParam)) {
+            errors.push(`Routes "${previous.id}" (${previous.path}) and "${route.id}" (${route.path}) both answer "${route.contract.canonicalPath}".\nFix: keep one of them, or give them distinct paths — a locale segment does not make two routes distinct.`);
+            continue;
+        }
+        if (!previous) {
+            byShape.set(shape, route);
+        }
+    }
+    return errors;
+}
 function validateLocaleRouteCollisions(args) {
     const errors = [];
     const reservedPrefixes = new Set(args.i18n.locales.map((locale) => locale.toLowerCase()));
     for (const route of args.configRoutes) {
         const first = firstPathSegment(route.path);
         if (first && reservedPrefixes.has(first.toLowerCase())) {
-            errors.push(`Route "${route.id}" (${route.path}) uses reserved locale prefix "${first}". Keep ${args.configDisplayPath} routes canonical and unlocalized, for example "/pricing"; let fimoRoutes() or custom locale routing produce "/${first}/...".`);
+            errors.push(`Route "${route.id}" (${route.path}) uses reserved locale prefix "${first}". Declare the locale as "/:locale/..." in ${args.configDisplayPath} and as ":locale?/..." in React Router so the default locale remains unprefixed.`);
         }
     }
-    if (!args.routesSourceUsesFimoRoutes) {
+    if (!args.routesSourceUsesLegacyHelper) {
         for (const route of args.fileRoutes) {
             if (!route.path || route.isLayout) {
                 continue;
             }
             const first = firstPathSegment(route.path);
+            // `:locale` is the declared locale segment, not an accidental catch-all.
+            if (first && normalizeLocaleSpelling(first) === `:${FIMO_LOCALE_PARAM}`) {
+                continue;
+            }
             if (first?.startsWith(':') || first === '*') {
-                errors.push(`Route "${route.path}" is a top-level dynamic route in a multi-locale path-prefix project. It can capture locale URLs like "/${args.i18n.locales[0]}". Use fimoRoutes(routes) from "fimo/react-router/routes" or implement explicit custom locale routing.`);
+                errors.push(`Route "${route.path}" is a top-level dynamic route in a multi-locale project. It can capture locale URLs like "/${args.i18n.locales[0]}". Put an explicit optional ":locale?" segment first in the React Router path, or keep this route outside the localized route boundary.`);
             }
         }
     }
     return errors;
 }
-function sourceUsesFimoRoutes(fileRoutes, routesFilePath) {
-    if (fileRoutes.length === 0 || !fs.existsSync(routesFilePath)) {
+function sourceUsesLegacyFimoRoutes(routesFilePath) {
+    if (!fs.existsSync(routesFilePath)) {
         return false;
     }
-    return fs.readFileSync(routesFilePath, 'utf-8').includes('fimoRoutes(');
+    const source = fs.readFileSync(routesFilePath, 'utf-8');
+    const importMatch = source.match(/import\s*\{(?<imports>[^}]*)\}\s*from\s*['"]fimo\/react-router\/routes['"]/s);
+    const importedName = importMatch?.groups?.imports
+        ?.split(',')
+        .map((specifier) => specifier.trim().match(/^fimoRoutes(?:\s+as\s+(?<alias>[A-Za-z_$][\w$]*))?$/)?.groups?.alias ??
+        (specifier.trim() === 'fimoRoutes' ? 'fimoRoutes' : null))
+        .find((name) => Boolean(name));
+    return importedName ? new RegExp(`\\b${importedName}\\s*\\(`).test(source) : false;
+}
+/**
+ * React Router spells an omittable segment `:locale?`; the config spells the
+ * same thing `:locale`. Compare the two worlds in one spelling.
+ */
+function normalizeLocaleSpelling(routePath) {
+    return routePath.replace(`:${FIMO_LOCALE_PARAM}?`, `:${FIMO_LOCALE_PARAM}`);
+}
+/**
+ * The `src/routes.ts` paths that legitimately register one config route. A
+ * route with an optional locale answers two URL shapes, so an app may register
+ * one optional-segment route or one route per shape.
+ */
+function registrablePaths(route) {
+    const declared = normalizeLocaleSpelling(route.contract.path);
+    if (!route.contract.localeParam?.optional) {
+        return [declared];
+    }
+    return [declared, route.contract.canonicalPath];
 }
 function firstPathSegment(routePath) {
     return routePath.split('/').filter(Boolean)[0] ?? null;