fimo 0.9.0-experimental.7 → 0.9.0-experimental.8

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[];
+};

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

@@ -33,52 +33,53 @@ export function ensureSpaEntryWiring(cwd) {
     catch {
         return bail('entry file could not be parsed', rel);
     }
-    // The JSX argument of the root render call, found structurally: a call
-    // whose callee property is `render` with a JSX element first argument
-    // (covers `createRoot(…).render(<X/>)` and `ReactDOM.render(<X/>, node)`).
-    const renderArg = (function find(node) {
+    // EVERY root-mount JSX argument, found structurally: `render(<X/>)` calls
+    // (createRoot/ReactDOM) AND `hydrateRoot(container, <X/>)` — a prerendered
+    // SPA mounts through BOTH branches, and wiring only the createRoot one
+    // left the production hydrate path without providers (run-5 finding).
+    const renderArgs = [];
+    (function find(node) {
         if (!node || typeof node !== 'object') {
-            return null;
+            return;
         }
         const candidate = node;
-        if (candidate.type === 'CallExpression' &&
-            candidate.callee?.type === 'MemberExpression' &&
-            candidate.callee?.property?.name === 'render' &&
-            (candidate.arguments?.[0]?.type === 'JSXElement' || candidate.arguments?.[0]?.type === 'JSXFragment')) {
-            return candidate.arguments[0];
+        if (candidate.type === 'CallExpression') {
+            const isRender = candidate.callee?.type === 'MemberExpression' && candidate.callee?.property?.name === 'render';
+            const isHydrate = candidate.callee?.name === 'hydrateRoot' ||
+                (candidate.callee?.type === 'MemberExpression' && candidate.callee?.property?.name === 'hydrateRoot');
+            const arg = isRender ? candidate.arguments?.[0] : isHydrate ? candidate.arguments?.[1] : undefined;
+            if (arg && (arg.type === 'JSXElement' || arg.type === 'JSXFragment')) {
+                renderArgs.push(arg);
+            }
         }
         for (const value of Object.values(candidate)) {
             if (Array.isArray(value)) {
                 for (const entry of value) {
-                    const found = find(entry);
-                    if (found) {
-                        return found;
-                    }
+                    find(entry);
                 }
             }
             else if (value && typeof value === 'object') {
-                const found = find(value);
-                if (found) {
-                    return found;
-                }
+                find(value);
             }
         }
-        return null;
     })(program);
-    if (!renderArg) {
+    if (renderArgs.length === 0) {
         return bail('no root render call with a JSX argument found', rel);
     }
     const configImportPath = path
         .relative(path.dirname(entryFile), path.join(cwd, 'fimo-config.json'))
         .split(path.sep)
         .join('/');
-    const jsx = code.slice(renderArg.start, renderArg.end);
     const open = '<FimoSpaProviders\n' +
         '    config={fimoConfig}\n' +
         '    apiUrl={import.meta.env.VITE_API_URL}\n' +
         '    previewScriptUrl={import.meta.env.DEV ? import.meta.env.VITE_FIMO_PREVIEW_SCRIPT_URL : undefined}\n' +
         '  >';
-    let next = code.slice(0, renderArg.start) + `${open}\n    ${jsx}\n  </FimoSpaProviders>` + code.slice(renderArg.end);
+    let next = code;
+    for (const renderArg of [...renderArgs].sort((a, b) => b.start - a.start)) {
+        const jsx = next.slice(renderArg.start, renderArg.end);
+        next = next.slice(0, renderArg.start) + `${open}\n    ${jsx}\n  </FimoSpaProviders>` + next.slice(renderArg.end);
+    }
     // AST-positioned like ensureFimoImport: a multiline import's first line is
     // not the end of the imports.
     const importBlock = `import { FimoSpaProviders } from 'fimo/react';\nimport fimoConfig from '${configImportPath.startsWith('.') ? configImportPath : `./${configImportPath}`}';`;
@@ -95,5 +96,49 @@ export function ensureSpaEntryWiring(cwd) {
             ? `${next.slice(0, lastImportEnd)}\n${importBlock}${next.slice(lastImportEnd)}`
             : `${importBlock}\n${next}`;
     fs.writeFileSync(entryFile, next);
-    return { changes: [`wired FimoSpaProviders into ${rel}`], warnings: [], wired: true };
+    const changes = [`wired FimoSpaProviders into ${rel} (${renderArgs.length} mount point(s))`];
+    const pluginResult = ensureViteFimoPlugin(cwd);
+    return {
+        changes: [...changes, ...pluginResult.changes],
+        warnings: pluginResult.warnings,
+        wired: true,
+    };
+}
+/**
+ * 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 function ensureViteFimoPlugin(cwd) {
+    const configFile = ['vite.config.ts', 'vite.config.js', 'vite.config.mts', 'vite.config.mjs']
+        .map((candidate) => path.join(cwd, candidate))
+        .find((candidate) => fs.existsSync(candidate));
+    if (!configFile) {
+        return { changes: [], warnings: ['No vite.config found — add the fimo() plugin per the agent-prompt recipe.'] };
+    }
+    const rel = path.relative(cwd, configFile);
+    const code = fs.readFileSync(configFile, 'utf8');
+    if (/\bfimo\s*\(/.test(code) && code.includes('fimo/vite')) {
+        return { changes: [], warnings: [] };
+    }
+    const pluginsMatch = code.match(/\bplugins\s*:\s*\[/);
+    if (!pluginsMatch || pluginsMatch.index === undefined) {
+        return {
+            changes: [],
+            warnings: [`No plugins array found in ${rel} — add the fimo() plugin per the agent-prompt recipe.`],
+        };
+    }
+    const insertAt = pluginsMatch.index + pluginsMatch[0].length;
+    let next = `${code.slice(0, insertAt)}fimo(), ${code.slice(insertAt)}`;
+    const importLine = `import { fimo } from 'fimo/vite';`;
+    const lastImport = [...next.matchAll(/^import .*$/gm)].pop();
+    next =
+        lastImport && lastImport.index !== undefined
+            ? `${next.slice(0, lastImport.index + lastImport[0].length)}\n${importLine}${next.slice(lastImport.index + lastImport[0].length)}`
+            : `${importLine}\n${next}`;
+    fs.writeFileSync(configFile, next);
+    return { changes: [`added the fimo() plugin to ${rel}`], warnings: [] };
 }

package/dist/scripts/lib/humanize.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Human-facing names derived from slugs and identifiers — route labels, page
+ * names, field titles. One rule set so "ai-stack" reads "AI Stack" and
+ * "agentic-cms" reads "Agentic CMS" everywhere the machine writes a name.
+ */
+/** "ai-stack" → "AI Stack"; "agenticCms" → "Agentic CMS"; "blog" → "Blog". */
+export declare function humanizeSegment(segment: string): string;
+/**
+ * The discovery-time label for a route path. Dynamic templates never share
+ * the parent index page's name (the run-4 tree showed "Blog" twice): the
+ * param joins the label ("/blog/:slug" → "Blog Slug") until a schema
+ * binding upgrades it to the schema's name ("Blog Post").
+ */
+export declare function discoveredRouteLabel(path: string): string;