fimo 0.9.0-experimental.7 → 0.9.0-experimental.9

package/dist/scripts/draft-rows.js

@@ -1,6 +1,9 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import YAML from 'yaml';
+import { slugify } from './apply-wrap.js';
+/** Display fields tried, in order, when deriving a human entry slug. */
+const DISPLAY_SLUG_FIELDS = ['title', 'name', 'question', 'q', 'label', 'heading'];
 /**
  * Machine-staged entry ROWS for every drafted collection: the deterministic
  * transformation agents kept re-implementing by hand (media envelopes,
@@ -71,6 +74,20 @@ export function writeRowsStaging(rootDir, scan, drafts) {
     const bySourceLabel = new Map(drafts.map((draft) => [draft.source, draft]));
     const provisionalByName = new Map(drafts.map((draft) => [draft.sourceName, draft.uid]));
     const toProvisional = (name) => provisionalByName.get(name) ?? name;
+    // Types other rows REFERENCE resolve by slug server-side — their slugs must
+    // stay whatever identity the source carries. Every other type gets a HUMAN
+    // slug derived from its display field (never `faq-item-<hash>`).
+    const referencedUids = new Set();
+    for (const draft of drafts) {
+        for (const def of Object.values(draft.fields)) {
+            const field = def;
+            if (field?.type === 'reference') {
+                for (const target of field.targets ?? (field.target ? [field.target] : [])) {
+                    referencedUids.add(target);
+                }
+            }
+        }
+    }
     let written = 0;
     const stage = (draft, source, rawRows, references) => {
         const fieldTypes = new Map(Object.entries(draft.fields).map(([name, def]) => [
@@ -78,12 +95,31 @@ export function writeRowsStaging(rootDir, scan, drafts) {
             def && typeof def === 'object' ? (def.type ?? 'string') : 'string',
         ]));
         const referenceFields = new Set(references.map((reference) => reference.field));
+        const usedSlugs = new Set();
         const rows = rawRows.map((row) => {
             const out = {};
             for (const [key, value] of Object.entries(row)) {
                 // Reference values stay as SOURCE values for later resolution.
                 out[key] = referenceFields.has(key) ? value : transformValue(fieldTypes.get(key), value);
             }
+            if (typeof out.slug === 'string' && out.slug) {
+                usedSlugs.add(out.slug);
+            }
+            else if (!referencedUids.has(draft.uid)) {
+                // Human slug from the display field ("who-is-behind-fimo", never
+                // "faq-item-<hash>"). Referenced types keep their source identity —
+                // the server resolves references by target slug.
+                const display = DISPLAY_SLUG_FIELDS.map((field) => row[field]).find((candidate) => typeof candidate === 'string' && candidate.trim().length > 0);
+                const base = display ? slugify(display) : '';
+                if (base) {
+                    let candidate = base;
+                    for (let counter = 2; usedSlugs.has(candidate); counter++) {
+                        candidate = `${base}-${counter}`;
+                    }
+                    usedSlugs.add(candidate);
+                    out.slug = candidate;
+                }
+            }
             return out;
         });
         const descriptor = {};

package/dist/scripts/frameworks/astro/routes.js

@@ -1,23 +1,7 @@
 import { readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-const titleCase = (seg) => seg
-    .replace(/[_\-]+/g, ' ')
-    .replace(/([a-z])([A-Z])/g, '$1 $2')
-    .split(/\s+/)
-    .filter(Boolean)
-    .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
-    .join(' ');
-function pushRoute(routes, parts) {
-    const routePath = `/${parts.join('/')}`.replace(/\/+/g, '/');
-    const lastStatic = [...parts].reverse().find((part) => !part.startsWith(':'));
-    routes.push({
-        id: routePath === '/' ? 'home' : parts.map((part) => part.replace(/^:/, '')).join('-'),
-        path: routePath,
-        label: routePath === '/' ? 'Home' : titleCase(lastStatic ?? parts[parts.length - 1] ?? routePath),
-    });
-}
+import { pushRoute, toSegment } from '../discovered-route.js';
 const PAGE_EXT = /\.(astro|md|mdx|html)$/;
-const toSegment = (name) => name.replace(/^\[\.\.\.(.+)\]$/, ':$1').replace(/^\[(.+)\]$/, ':$1');
 /** Astro file-based routes under src/pages (index files map to the dir path). */
 export function discoverAstroRoutes(pagesDir) {
     const routes = [];
@@ -46,7 +30,7 @@ export function discoverAstroRoutes(pagesDir) {
                 continue;
             }
             const base = entry.replace(PAGE_EXT, '');
-            pushRoute(routes, base === 'index' ? segments : [...segments, toSegment(base)]);
+            pushRoute(routes, base === 'index' ? segments : [...segments, toSegment(base)], full);
         }
     };
     walk(pagesDir, []);

package/dist/scripts/frameworks/discover.d.ts

@@ -1,5 +1,6 @@
 import type { TemplateWrapStyle } from '../apply-wrap-templates.js';
 import type { FrameworkDetection } from '../detect-framework.js';
+import { type RouteFileResolution, type RouteLike } from '../routes/module-resolve.js';
 import { type CollectionRewireResult } from './next/rewire.js';
 import { type DiscoveredRoute } from './next/routes.js';
 import { type RootWiringResult } from './next/wiring.js';
@@ -31,14 +32,26 @@ export declare function frameworkJsxWrapperModule(detection: Pick<FrameworkDetec
  * server data path there is no deterministic t() wiring to inject.
  */
 export declare function frameworkTemplateWrapStyle(framework: string | null | undefined): TemplateWrapStyle | null;
+export declare function frameworkRouteFiles(framework: string | null): ((cwd: string, routes: Record<string, RouteLike>) => RouteFileResolution[]) | null;
+export interface SectionStyle {
+    /** Module extensions a section import may resolve to. */
+    extensions: string[];
+    /** Wrapped-key scope for a component file (must match the wrap codemod's
+     *  own scoping so drafted sections join their staged keys). */
+    fileScope: (relFile: string) => string;
+    /** Directories tried for auto-imported components (Nuxt convention) when
+     *  a section tag has no import statement. */
+    fallbackComponentDirs: string[];
+}
 /**
- * The one-time root-wiring codemod for frameworks whose providers mount in a
- * single well-known file (Next.js app router: the root layout; Vite React
- * SPA: the entry). Runs during --apply, AFTER the baseline capture — the
- * pre-wrap dev-server boot must not require the fimo package, and providers
- * are render-transparent so the parity check stays clean. Template
- * frameworks wire through their TemplateWrapStyle.ensureWiring hooks instead.
+ * How to read a page's SECTION STRUCTURE for this framework — the seam the
+ * page-structure drafter builds on. Template frameworks share the ES-import
+ * + capitalized-tag shape, differing only in extensions and key scoping.
  */
+export declare function frameworkSectionStyle(framework: string | null): SectionStyle;
+/** Client-rendered frameworks: no server pass — reads happen in the browser
+ *  (the prompt's collection recipe and the SPA providers key off this). */
+export declare function isClientRenderedFramework(framework: string | null | undefined): boolean;
 export declare function frameworkRootWiring(detection: Pick<FrameworkDetection, 'framework' | 'react' | 'appDir'>): ((cwd: string) => RootWiringResult) | null;
 /**
  * Collection-page rewiring: pages that render a machine-staged collection get

package/dist/scripts/frameworks/discover.js

@@ -1,15 +1,18 @@
-import { join, relative } from 'node:path';
+import { existsSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+import { keyScope, slugify } from '../apply-wrap.js';
+import { DEFAULT_COMPONENT_EXTENSIONS } from '../routes/module-resolve.js';
 import { discoverAstroRoutes } from './astro/routes.js';
 import { astroTemplateWrapStyle } from './astro/template-style.js';
 import { rewireNextCollectionPages } from './next/rewire.js';
-import { discoverNextPagesRoutes, discoverNextRoutes } from './next/routes.js';
+import { discoverNextPagesRoutes, discoverNextRoutes, resolveNextRouteFiles, } from './next/routes.js';
 import { ensureNextLayoutWiring, nextRootLayoutFiles } from './next/wiring.js';
 import { discoverNuxtRoutes } from './nuxt/routes.js';
 import { nuxtTemplateWrapStyle } from './nuxt/template-style.js';
 import { discoverRemixRoutes } from './remix/routes.js';
 import { discoverSvelteKitRoutes } from './sveltekit/routes.js';
 import { svelteTemplateWrapStyle } from './sveltekit/template-style.js';
-import { discoverReactRouterDomRoutes } from './vite/routes.js';
+import { discoverReactRouterDomRoutes, resolveSpaRouteFiles } from './vite/routes.js';
 import { ensureSpaEntryWiring } from './vite/wiring.js';
 /**
  * Route discovery for any detected framework — the single registry generic
@@ -20,6 +23,13 @@ export function discoverFrameworkRoutes(cwd, detection) {
     if (detection.framework === 'vite' && detection.react) {
         return discoverReactRouterDomRoutes(cwd);
     }
+    // Library-mode React Router (react-router dep on Vite, no app/ convention)
+    // declares routes in code exactly like a vite+react SPA — the Fimo-site
+    // dogfood detected `react-router` and fell to `default: []`, forcing 22
+    // manual `pages set` calls while the SPA scanner would have found them all.
+    if (detection.framework === 'react-router' && !detection.pagesDir) {
+        return discoverReactRouterDomRoutes(cwd);
+    }
     switch (detection.framework) {
         case 'next':
             return [
@@ -102,6 +112,89 @@ export function frameworkTemplateWrapStyle(framework) {
  * are render-transparent so the parity check stays clean. Template
  * frameworks wire through their TemplateWrapStyle.ensureWiring hooks instead.
  */
+/**
+ * Registry route ids → the component files that render them — the join the
+ * label-ownership prefill and the page-structure drafter build on. Framework
+ * knowledge stays HERE: core modules call this and never test a framework
+ * name themselves. File-based frameworks resolve straight from their
+ * discovery output (the walk knows every route's file); code-declared
+ * routers (SPA) resolve through import analysis.
+ */
+function resolveByDiscovery(discover, conventionalDirs) {
+    return (cwd, routes) => {
+        const pagesDir = conventionalDirs.map((dir) => join(cwd, dir)).find((dir) => existsSync(dir));
+        if (!pagesDir) {
+            return [];
+        }
+        const byPath = new Map();
+        for (const [routeId, route] of Object.entries(routes)) {
+            if (typeof route?.path === 'string') {
+                byPath.set(route.path, routeId);
+            }
+        }
+        const resolutions = [];
+        for (const discovered of discover(pagesDir)) {
+            const routeId = byPath.get(discovered.path);
+            if (routeId && discovered.file) {
+                resolutions.push({ routeId, file: discovered.file });
+            }
+        }
+        return resolutions;
+    };
+}
+export function frameworkRouteFiles(framework) {
+    switch (framework) {
+        case 'next':
+            return resolveNextRouteFiles;
+        case 'react-router':
+        case 'vite':
+            return resolveSpaRouteFiles;
+        case 'astro':
+            return resolveByDiscovery(discoverAstroRoutes, ['src/pages', 'pages']);
+        case 'nuxt':
+            return resolveByDiscovery(discoverNuxtRoutes, ['pages', 'src/pages']);
+        case 'sveltekit':
+            return resolveByDiscovery(discoverSvelteKitRoutes, ['src/routes']);
+        case 'remix':
+            return resolveByDiscovery(discoverRemixRoutes, ['app/routes']);
+        default:
+            return null;
+    }
+}
+/**
+ * How to read a page's SECTION STRUCTURE for this framework — the seam the
+ * page-structure drafter builds on. Template frameworks share the ES-import
+ * + capitalized-tag shape, differing only in extensions and key scoping.
+ */
+export function frameworkSectionStyle(framework) {
+    const templateScope = (relFile) => {
+        const style = frameworkTemplateWrapStyle(framework);
+        return style?.fileScope?.(relFile) ?? slugify(basename(relFile).replace(/\.[a-z0-9]+$/i, '')) ?? 'shared';
+    };
+    switch (framework) {
+        case 'astro':
+            return {
+                extensions: ['.astro', '.tsx', '.jsx', '.ts', '.js'],
+                fileScope: templateScope,
+                fallbackComponentDirs: [],
+            };
+        case 'nuxt':
+            return {
+                extensions: ['.vue', '.ts', '.js'],
+                fileScope: templateScope,
+                fallbackComponentDirs: ['components'],
+            };
+        case 'sveltekit':
+            return { extensions: ['.svelte', '.ts', '.js'], fileScope: templateScope, fallbackComponentDirs: [] };
+        default:
+            return { extensions: DEFAULT_COMPONENT_EXTENSIONS.slice(), fileScope: keyScope, fallbackComponentDirs: [] };
+    }
+}
+/** Client-rendered frameworks: no server pass — reads happen in the browser
+ *  (the prompt's collection recipe and the SPA providers key off this). */
+export function isClientRenderedFramework(framework) {
+    return framework === 'vite' || framework === 'react-router';
+}
 export function frameworkRootWiring(detection) {
     switch (detection.framework) {
         case 'next':

package/dist/scripts/frameworks/discovered-route.d.ts

@@ -0,0 +1,9 @@
+import type { DiscoveredRoute } from './next/routes.js';
+/**
+ * Shared helpers for file-based route discovery — one implementation of the
+ * segment→route push and the bracket-param normalization that astro, nuxt,
+ * sveltekit, and remix previously each carried a copy of.
+ */
+export declare function pushRoute(routes: DiscoveredRoute[], parts: string[], file?: string): void;
+/** `[slug]` → `:slug`, `[...rest]` → `:rest` (bracket file conventions). */
+export declare const toSegment: (name: string) => string;

package/dist/scripts/frameworks/discovered-route.js

@@ -0,0 +1,17 @@
+import { discoveredRouteLabel } from '../lib/humanize.js';
+/**
+ * Shared helpers for file-based route discovery — one implementation of the
+ * segment→route push and the bracket-param normalization that astro, nuxt,
+ * sveltekit, and remix previously each carried a copy of.
+ */
+export function pushRoute(routes, parts, file) {
+    const routePath = `/${parts.join('/')}`.replace(/\/+/g, '/');
+    routes.push({
+        id: routePath === '/' ? 'home' : parts.map((part) => part.replace(/^:/, '')).join('-'),
+        path: routePath,
+        label: discoveredRouteLabel(routePath),
+        ...(file ? { file } : {}),
+    });
+}
+/** `[slug]` → `:slug`, `[...rest]` → `:rest` (bracket file conventions). */
+export const toSegment = (name) => name.replace(/^\[\.\.\.(.+)\]$/, ':$1').replace(/^\[(.+)\]$/, ':$1');

package/dist/scripts/frameworks/next/routes.d.ts

@@ -1,6 +1,10 @@
+import { type RouteFileResolution, type RouteLike } from '../../routes/module-resolve.js';
 export interface DiscoveredRoute {
     id: string;
     path: string;
+    /** The source file that renders this route (file-based frameworks set it;
+     *  code-declared routers resolve files separately). */
+    file?: string;
     label: string;
 }
 /**
@@ -21,3 +25,6 @@ export declare function discoverNextRoutes(appDir: string): DiscoveredRoute[];
  * `:param` (the parity capture skips dynamic routes, same as app router).
  */
 export declare function discoverNextPagesRoutes(pagesDir: string): DiscoveredRoute[];
+/** Registry-routed (frameworkRouteFiles): registry route ids → the app-dir
+ *  page files that render them, joined by routePathForAppPage. */
+export declare function resolveNextRouteFiles(cwd: string, routes: Record<string, RouteLike>): RouteFileResolution[];

package/dist/scripts/frameworks/next/routes.js

@@ -1,13 +1,8 @@
-import { readdirSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, statSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
+import { discoveredRouteLabel } from '../../lib/humanize.js';
+import { walkFiles } from '../../routes/module-resolve.js';
 const PAGE_FILES = new Set(['page.tsx', 'page.jsx', 'page.ts', 'page.js', 'page.mdx']);
-const titleCase = (seg) => seg
-    .replace(/[_\-]+/g, ' ')
-    .replace(/([a-z])([A-Z])/g, '$1 $2')
-    .split(/\s+/)
-    .filter(Boolean)
-    .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
-    .join(' ');
 function segmentToPath(segment) {
     // Route groups `(marketing)` don't contribute URL segments. Parallel-route
     // slots `@modal` and private folders `_lib` are not standalone pages.
@@ -68,11 +63,10 @@ export function discoverNextRoutes(appDir) {
         if (entries.some((entry) => PAGE_FILES.has(entry))) {
             const parts = segments.filter((s) => s.length > 0);
             const routePath = `/${parts.join('/')}`.replace(/\/+/g, '/');
-            const lastStatic = [...parts].reverse().find((p) => !p.startsWith(':'));
             routes.push({
                 id: routePath === '/' ? 'home' : parts.map((p) => p.replace(/^:/, '')).join('-'),
                 path: routePath,
-                label: routePath === '/' ? 'Home' : titleCase(lastStatic ?? parts[parts.length - 1] ?? routePath),
+                label: discoveredRouteLabel(routePath),
             });
         }
         for (const entry of entries) {
@@ -143,11 +137,10 @@ export function discoverNextPagesRoutes(pagesDir) {
             }
             const parts = base === 'index' ? segments : [...segments, toSegment(base)];
             const routePath = `/${parts.join('/')}`.replace(/\/+/g, '/');
-            const lastStatic = [...parts].reverse().find((part) => !part.startsWith(':'));
             routes.push({
                 id: routePath === '/' ? 'home' : parts.map((part) => part.replace(/^:/, '')).join('-'),
                 path: routePath,
-                label: routePath === '/' ? 'Home' : titleCase(lastStatic ?? parts[parts.length - 1] ?? routePath),
+                label: discoveredRouteLabel(routePath),
             });
         }
     };
@@ -155,3 +148,29 @@ export function discoverNextPagesRoutes(pagesDir) {
     routes.sort((a, b) => a.path.localeCompare(b.path));
     return routes;
 }
+/** Registry-routed (frameworkRouteFiles): registry route ids → the app-dir
+ *  page files that render them, joined by routePathForAppPage. */
+export function resolveNextRouteFiles(cwd, routes) {
+    const appDir = [join(cwd, 'app'), join(cwd, 'src', 'app')].find((dir) => existsSync(dir));
+    if (!appDir) {
+        return [];
+    }
+    const PAGE_FILE = /^page\.(?:tsx|jsx|ts|js|mdx)$/;
+    const pageFiles = [];
+    walkFiles(appDir, (name) => PAGE_FILE.test(name), pageFiles);
+    const byPath = new Map();
+    for (const [routeId, route] of Object.entries(routes)) {
+        if (typeof route?.path === 'string') {
+            byPath.set(route.path, routeId);
+        }
+    }
+    const resolutions = [];
+    for (const file of pageFiles) {
+        const routePath = routePathForAppPage(appDir, file);
+        const routeId = routePath ? byPath.get(routePath) : undefined;
+        if (routeId) {
+            resolutions.push({ routeId, file });
+        }
+    }
+    return resolutions;
+}

package/dist/scripts/frameworks/nuxt/routes.js

@@ -1,22 +1,6 @@
 import { readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-const titleCase = (seg) => seg
-    .replace(/[_\-]+/g, ' ')
-    .replace(/([a-z])([A-Z])/g, '$1 $2')
-    .split(/\s+/)
-    .filter(Boolean)
-    .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
-    .join(' ');
-function pushRoute(routes, parts) {
-    const routePath = `/${parts.join('/')}`.replace(/\/+/g, '/');
-    const lastStatic = [...parts].reverse().find((part) => !part.startsWith(':'));
-    routes.push({
-        id: routePath === '/' ? 'home' : parts.map((part) => part.replace(/^:/, '')).join('-'),
-        path: routePath,
-        label: routePath === '/' ? 'Home' : titleCase(lastStatic ?? parts[parts.length - 1] ?? routePath),
-    });
-}
-const toSegment = (name) => name.replace(/^\[\.\.\.(.+)\]$/, ':$1').replace(/^\[(.+)\]$/, ':$1');
+import { pushRoute, toSegment } from '../discovered-route.js';
 /** Nuxt file-based routes under pages/ (index.vue maps to the dir path). */
 export function discoverNuxtRoutes(pagesDir) {
     const routes = [];
@@ -45,7 +29,7 @@ export function discoverNuxtRoutes(pagesDir) {
                 continue;
             }
             const base = entry.replace(/\.vue$/, '');
-            pushRoute(routes, base === 'index' ? segments : [...segments, toSegment(base)]);
+            pushRoute(routes, base === 'index' ? segments : [...segments, toSegment(base)], full);
         }
     };
     walk(pagesDir, []);

package/dist/scripts/frameworks/remix/routes.js

@@ -1,20 +1,6 @@
 import { readdirSync } from 'node:fs';
-const titleCase = (seg) => seg
-    .replace(/[_\-]+/g, ' ')
-    .replace(/([a-z])([A-Z])/g, '$1 $2')
-    .split(/\s+/)
-    .filter(Boolean)
-    .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
-    .join(' ');
-function pushRoute(routes, parts) {
-    const routePath = `/${parts.join('/')}`.replace(/\/+/g, '/');
-    const lastStatic = [...parts].reverse().find((part) => !part.startsWith(':'));
-    routes.push({
-        id: routePath === '/' ? 'home' : parts.map((part) => part.replace(/^:/, '')).join('-'),
-        path: routePath,
-        label: routePath === '/' ? 'Home' : titleCase(lastStatic ?? parts[parts.length - 1] ?? routePath),
-    });
-}
+import { join } from 'node:path';
+import { pushRoute } from '../discovered-route.js';
 const FILE_EXT = /\.(tsx|jsx|ts|js|mdx)$/;
 /** Remix v2 flat routes under app/routes: dots are slashes, $param is dynamic. */
 export function discoverRemixRoutes(routesDir) {
@@ -32,7 +18,7 @@ export function discoverRemixRoutes(routesDir) {
         }
         const base = entry.replace(FILE_EXT, '');
         if (base === '_index') {
-            pushRoute(routes, []);
+            pushRoute(routes, [], join(routesDir, entry));
             continue;
         }
         // Pathless layout segments start with _ ; trailing ._index maps to the parent.
@@ -42,7 +28,7 @@ export function discoverRemixRoutes(routesDir) {
             .filter((seg) => !seg.startsWith('_'))
             .map((seg) => (seg.startsWith('$') ? `:${seg.slice(1) || 'splat'}` : seg));
         if (parts.length > 0) {
-            pushRoute(routes, parts);
+            pushRoute(routes, parts, join(routesDir, entry));
         }
     }
     routes.sort((a, b) => a.path.localeCompare(b.path));

package/dist/scripts/frameworks/sveltekit/routes.js

@@ -1,22 +1,6 @@
 import { readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-const titleCase = (seg) => seg
-    .replace(/[_\-]+/g, ' ')
-    .replace(/([a-z])([A-Z])/g, '$1 $2')
-    .split(/\s+/)
-    .filter(Boolean)
-    .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
-    .join(' ');
-function pushRoute(routes, parts) {
-    const routePath = `/${parts.join('/')}`.replace(/\/+/g, '/');
-    const lastStatic = [...parts].reverse().find((part) => !part.startsWith(':'));
-    routes.push({
-        id: routePath === '/' ? 'home' : parts.map((part) => part.replace(/^:/, '')).join('-'),
-        path: routePath,
-        label: routePath === '/' ? 'Home' : titleCase(lastStatic ?? parts[parts.length - 1] ?? routePath),
-    });
-}
-const toSegment = (name) => name.replace(/^\[\.\.\.(.+)\]$/, ':$1').replace(/^\[(.+)\]$/, ':$1');
+import { pushRoute, toSegment } from '../discovered-route.js';
 /** SvelteKit routes: every directory under src/routes holding a +page file. */
 export function discoverSvelteKitRoutes(routesDir) {
     const routes = [];
@@ -28,9 +12,10 @@ export function discoverSvelteKitRoutes(routesDir) {
         catch {
             return;
         }
-        if (entries.some((entry) => /^\+page\.(svelte|md)$/.test(entry))) {
+        const pageFile = entries.find((entry) => /^\+page\.(svelte|md)$/.test(entry));
+        if (pageFile) {
             // Route groups (parens) are layout-only segments.
-            pushRoute(routes, segments.filter((seg) => !seg.startsWith('(')));
+            pushRoute(routes, segments.filter((seg) => !seg.startsWith('(')), join(dir, pageFile));
         }
         for (const entry of entries) {
             const full = join(dir, entry);

package/dist/scripts/frameworks/vite/routes.d.ts

@@ -1,3 +1,4 @@
+import { type RouteFileResolution, type RouteLike } from '../../routes/module-resolve.js';
 import type { DiscoveredRoute } from '../next/routes.js';
 /**
  * Route discovery for Vite React SPAs: there is no file convention, so the
@@ -13,3 +14,7 @@ import type { DiscoveredRoute } from '../next/routes.js';
  * anything the scan cannot see, and scanned routes only ever ADD to it.
  */
 export declare function discoverReactRouterDomRoutes(rootDir: string): DiscoveredRoute[];
+/** Registry-routed (frameworkRouteFiles): registry route ids → the SPA
+ *  component files that render them, via <Route element>/object-form route
+ *  declarations and import resolution (lazy() included). */
+export declare function resolveSpaRouteFiles(cwd: string, routes: Record<string, RouteLike>): RouteFileResolution[];

package/dist/scripts/frameworks/vite/routes.js

@@ -1,12 +1,7 @@
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-const titleCase = (seg) => seg
-    .replace(/[_\-]+/g, ' ')
-    .replace(/([a-z])([A-Z])/g, '$1 $2')
-    .split(/\s+/)
-    .filter(Boolean)
-    .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
-    .join(' ');
+import { discoveredRouteLabel } from '../../lib/humanize.js';
+import { componentImports, resolveModuleFile, walkFiles, } from '../../routes/module-resolve.js';
 const ROUTE_SOURCE = /\.(tsx|jsx|ts|js)$/;
 const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', '.git']);
 /**
@@ -81,13 +76,68 @@ export function discoverReactRouterDomRoutes(rootDir) {
                 continue;
             }
             const parts = path.split('/').filter(Boolean);
-            const lastStatic = [...parts].reverse().find((part) => !part.startsWith(':'));
             routes.set(path, {
                 id: path === '/' ? 'home' : parts.map((part) => part.replace(/^:/, '')).join('-'),
                 path,
-                label: path === '/' ? 'Home' : titleCase(lastStatic ?? parts[parts.length - 1] ?? path),
+                label: discoveredRouteLabel(path),
             });
         }
     }
     return [...routes.values()].sort((a, b) => a.path.localeCompare(b.path));
 }
+/** Registry-routed (frameworkRouteFiles): registry route ids → the SPA
+ *  component files that render them, via <Route element>/object-form route
+ *  declarations and import resolution (lazy() included). */
+export function resolveSpaRouteFiles(cwd, routes) {
+    const srcDir = join(cwd, 'src');
+    const files = [];
+    walkFiles(srcDir, (name) => ROUTE_SOURCE.test(name), files);
+    const byPath = new Map();
+    for (const [routeId, route] of Object.entries(routes)) {
+        if (typeof route?.path === 'string') {
+            byPath.set(route.path, routeId);
+        }
+    }
+    const resolutions = new Map();
+    for (const file of files) {
+        let code;
+        try {
+            code = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (!/from\s+['"]react-router(?:-dom)?['"]/.test(code)) {
+            continue;
+        }
+        const imports = componentImports(code);
+        const pairs = [];
+        // JSX shape: one <Route …> tag carries both path and element, in either
+        // attribute order.
+        for (const tag of code.matchAll(/<Route\b((?:"[^"]*"|'[^']*'|\{[^{}]*\}|[^>"'{}])*)\/?>/g)) {
+            const attrs = tag[1];
+            const routePath = attrs.match(/\bpath\s*=\s*(?:"([^"]+)"|'([^']+)')/);
+            const element = attrs.match(/\belement\s*=\s*\{\s*<(\w+)[\s/>]/) ?? attrs.match(/\bComponent\s*=\s*\{(\w+)\}/);
+            if (routePath && element) {
+                pairs.push({ path: routePath[1] ?? routePath[2], component: element[1] });
+            }
+        }
+        // Object shape: { path: '/x', element: <X …/> } or { path: '/x', Component: X }.
+        for (const entry of code.matchAll(/path\s*:\s*(?:"([^"]+)"|'([^']+)')\s*,\s*(?:element\s*:\s*<(\w+)[\s/>]|Component\s*:\s*(\w+))/g)) {
+            pairs.push({ path: entry[1] ?? entry[2], component: entry[3] ?? entry[4] });
+        }
+        for (const pair of pairs) {
+            const normalized = pair.path !== '/' && pair.path.endsWith('/') ? pair.path.slice(0, -1) : pair.path;
+            const routeId = byPath.get(normalized);
+            if (!routeId || resolutions.has(routeId)) {
+                continue;
+            }
+            const spec = imports.get(pair.component);
+            const componentFile = spec ? resolveModuleFile(cwd, file, spec) : null;
+            if (componentFile) {
+                resolutions.set(routeId, componentFile);
+            }
+        }
+    }
+    return [...resolutions.entries()].map(([routeId, file]) => ({ routeId, file }));
+}

package/dist/scripts/frameworks/vite/wiring.d.ts

@@ -8,3 +8,15 @@ import type { RootWiringResult } from '../next/wiring.js';
  * Anything else bails with the reason and stays agent work via the recipe.
  */
 export declare function ensureSpaEntryWiring(cwd: string): RootWiringResult;
+/**
+ * The `fimo()` Vite plugin serves the virtual modules the generated content
+ * clients import (`virtual:fimo-config`, …). Without it, the first
+ * dependency re-optimization 500s every page the moment an agent uses a
+ * generated client — both run-5 agents had to discover and add it by hand.
+ * Insert `fimo()` into the config's plugins array; unusual configs bail
+ * with the recipe.
+ */
+export declare function ensureViteFimoPlugin(cwd: string): {
+    changes: string[];
+    warnings: string[];
+};