fimo 0.9.0-experimental.1 → 0.9.0-experimental.11

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,
@@ -69,8 +72,29 @@ export function writeRowsStaging(rootDir, scan, drafts) {
         return 0;
     }
     const bySourceLabel = new Map(drafts.map((draft) => [draft.source, draft]));
-    const provisionalByName = new Map(drafts.map((draft) => [draft.sourceName, draft.uid]));
+    // First occurrence wins — the same deterministic choice writeSchemaDrafts
+    // makes for reference targets of collided source names.
+    const provisionalByName = new Map();
+    for (const draft of drafts) {
+        if (!provisionalByName.has(draft.sourceName)) {
+            provisionalByName.set(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 +102,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/draft-schemas.js

@@ -3,10 +3,34 @@ import { join } from 'node:path';
 const ISO_DATE = /^\d{4}-\d{2}-\d{2}([T ].*)?$/;
 const MEDIA_PATH = /^\/(images|img|videos|video|media|assets|files|docs|documents)\//i;
 const MEDIA_EXT = /\.(png|jpe?g|gif|webp|avif|svg|mp4|webm|mov|mp3|wav|pdf|zip|docx?)$/i;
-function singularPascal(name) {
-    const base = name
+function pascalize(name) {
+    // SCREAMING_CASE sources (const arrays like ENTRIES, TEAM_MEMBERS) lowercase
+    // first so the word structure survives — "ENTRIES" reads as "Entries", not
+    // the case-mangled "ENTRIES" verbatim.
+    const normalized = /[a-z]/.test(name) ? name : name.toLowerCase();
+    return normalized
         .replace(/[^a-zA-Z0-9]+(.)/g, (_, c) => c.toUpperCase())
-        .replace(/^(.)/, (c) => c.toUpperCase());
+        .replace(/^(.)/, (c) => c.toUpperCase())
+        .replace(/[^a-zA-Z0-9]/g, '');
+}
+/** File-derived qualifier for colliding draft names: `app/pricing/page.tsx:12`
+ *  → `Pricing`. Generic stems (page, index, data) and stems that ARE the
+ *  collection name (`pricing/faqItems.json` for FaqItem) defer to their
+ *  directory — the qualifier must add information the base name lacks. */
+function sourceQualifier(sourceLabel, base) {
+    const segments = sourceLabel
+        .replace(/:\d+$/, '')
+        .split('/')
+        .filter(Boolean);
+    const generic = new Set(['page', 'index', 'data', 'content', 'constants', 'src', 'app', 'pages']);
+    let pick = (segments.pop() ?? '').replace(/\.[a-z0-9]+$/i, '');
+    while ((generic.has(pick.toLowerCase()) || singularPascal(pick) === base) && segments.length > 0) {
+        pick = segments.pop();
+    }
+    return pascalize(pick);
+}
+function singularPascal(name) {
+    const base = pascalize(name);
     if (/ies$/i.test(base)) {
         return base.replace(/ies$/i, 'y');
     }
@@ -113,13 +137,48 @@ export function writeSchemaDrafts(rootDir, scan) {
         return [];
     }
     mkdirSync(draftsDir, { recursive: true });
+    // Same-named sources (a FAQ_ITEMS array per page) must NOT collapse into
+    // one draft that keeps only the last-seen rows — a real dogfood silently
+    // dropped 92 of 98 FAQ rows this way. Every source keeps its own draft;
+    // colliding names are qualified by their source file (FaqItemPricing).
+    const byBase = new Map();
+    for (const source of sources) {
+        const base = singularPascal(source.sourceName);
+        byBase.set(base, [...(byBase.get(base) ?? []), source]);
+    }
+    const uidBySource = new Map();
+    const taken = new Set();
+    for (const [base, group] of byBase) {
+        if (group.length === 1) {
+            uidBySource.set(group[0], base);
+            taken.add(base);
+        }
+    }
+    for (const [base, group] of byBase) {
+        if (group.length === 1) {
+            continue;
+        }
+        for (const source of group) {
+            const qualified = `${base}${sourceQualifier(source.sourceLabel, base)}`;
+            let candidate = qualified;
+            for (let counter = 2; taken.has(candidate); counter++) {
+                candidate = `${qualified}${counter}`;
+            }
+            taken.add(candidate);
+            uidBySource.set(source, candidate);
+        }
+    }
+    // Reference targets resolve by source name; for a collided name the FIRST
+    // source's uid wins (deterministic — adopt-drafts settles names anyway).
     const provisionalNames = new Map();
     for (const source of sources) {
-        provisionalNames.set(source.sourceName, singularPascal(source.sourceName));
+        if (!provisionalNames.has(source.sourceName)) {
+            provisionalNames.set(source.sourceName, uidBySource.get(source));
+        }
     }
     const drafts = [];
     for (const source of sources) {
-        const uid = provisionalNames.get(source.sourceName);
+        const uid = uidBySource.get(source);
         const referenceByField = new Map(source.references.map((reference) => [reference.field, reference]));
         const fields = {};
         // candidate.fields only lists STRING fields; booleans and numbers live

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 = [];
@@ -38,15 +22,20 @@ export function discoverAstroRoutes(pagesDir) {
             catch {
                 continue;
             }
+            // Astro's convention: underscore-prefixed files AND directories are
+            // excluded from routing (component folders inside src/pages).
+            if (entry.startsWith('_')) {
+                continue;
+            }
             if (isDir) {
                 walk(full, [...segments, toSegment(entry)]);
                 continue;
             }
-            if (!PAGE_EXT.test(entry) || entry.startsWith('_')) {
+            if (!PAGE_EXT.test(entry)) {
                 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 [
@@ -66,6 +76,11 @@ export function frameworkJsxWrapperModule(detection) {
             return 'fimo/next';
         case 'remix':
             return 'fimo/remix';
+        case 'react-router':
+            // Library-mode React Router SPAs (react-router dep on Vite) wrap with
+            // the client-side fimo/react primitives — same shape as vite+react.
+            // Proven on the Fimo marketing site (1211 items auto-wrapped).
+            return 'fimo/react';
         case 'vite':
             return detection.react ? 'fimo/react' : null;
         default:
@@ -97,10 +112,97 @@ 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':
             return (cwd) => ensureNextLayoutWiring(cwd, detection);
+        case 'react-router':
+            // Same createRoot(...).render entry shape as vite+react; framework-mode
+            // RR apps have no src/main.* and bail with a reason (agent §0).
+            return ensureSpaEntryWiring;
         case 'vite':
             return detection.react ? ensureSpaEntryWiring : null;
         default:
@@ -160,6 +262,14 @@ export function frameworkWiringMarker(detection, cwd) {
                 marker: /FimoSpaProviders/,
                 hint: 'wrap the root render with FimoSpaProviders from fimo/react (agent prompt section 0)',
             };
+        case 'react-router':
+            // Accept either provider: FimoSpaProviders (the vite+react codemod) or
+            // FimoProviders (the fimo/react-router adapter, hand-wired on RR sites).
+            return {
+                files: ['src/main.tsx', 'src/main.jsx', 'src/index.tsx', 'src/index.jsx', 'app/root.tsx', 'app/root.jsx'],
+                marker: /Fimo(Spa)?Providers/,
+                hint: 'wrap the root render with FimoSpaProviders (fimo/react) or FimoProviders (fimo/react-router) — agent prompt section 0',
+            };
         case 'remix':
             return {
                 files: ['app/root.tsx', 'app/root.jsx'],

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/rewire.d.ts

@@ -17,11 +17,24 @@ import type { WrapScanResult } from '../../scan-wrappable.js';
  * Uids are the PROVISIONAL draft names; `schemas adopt-drafts` rewrites the
  * call sites through its renames.
  */
+export interface RewiredPage {
+    file: string;
+    /** Collection uid the page reads through `wrapCollection` (provisional until
+     *  `adopt-drafts` renames it). */
+    uid: string;
+    /** The page's registry route path (`:param` normalized), null when the file
+     *  sits in a non-routable location. Joins the page back to the page registry
+     *  as binding evidence. */
+    routePath: string | null;
+}
 export interface CollectionRewireResult {
     changes: string[];
     warnings: string[];
     /** Pages successfully rewired. */
     rewired: number;
+    /** Every page known to read a collection through `wrapCollection` — rewired
+     *  this run or found already wired on a re-run. */
+    pages: RewiredPage[];
 }
 export declare function rewireNextCollectionPages(cwd: string, detection: Pick<FrameworkDetection, 'appDir'>, scan: WrapScanResult, drafts: Array<{
     uid: string;

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

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseSync } from 'oxc-parser';
 import { ensureFimoImport } from '../../apply-wrap.js';
+import { routePathForAppPage } from './routes.js';
 function applyEdits(code, edits) {
     let next = code;
     for (const edit of [...edits].sort((a, b) => b.start - a.start)) {
@@ -85,9 +86,10 @@ function pageFilesUnder(dir) {
 export function rewireNextCollectionPages(cwd, detection, scan, drafts) {
     const changes = [];
     const warnings = [];
+    const pages = [];
     let rewired = 0;
     if (!detection.appDir) {
-        return { changes, warnings: ['Collection pages not rewired: pages-router project.'], rewired };
+        return { changes, warnings: ['Collection pages not rewired: pages-router project.'], rewired, pages };
     }
     const appDirAbs = path.join(cwd, detection.appDir);
     const uidBySourceName = new Map(drafts.map((draft) => [draft.sourceName, draft.uid]));
@@ -100,6 +102,24 @@ export function rewireNextCollectionPages(cwd, detection, scan, drafts) {
     const bail = (page, reason) => {
         warnings.push(`Page not rewired (${page}): ${reason} — wire it with wrapCollection per the prompt recipe.`);
     };
+    const recordPage = (fileAbs, uid) => {
+        pages.push({ file: path.relative(cwd, fileAbs), uid, routePath: routePathForAppPage(appDirAbs, fileAbs) });
+    };
+    // Pages wired on a PREVIOUS run still carry binding evidence (the uid in the
+    // call site is final once `adopt-drafts` renamed it) — collect them before
+    // rewiring so re-runs keep feeding the page registry.
+    for (const pageAbs of pageFilesUnder(appDirAbs)) {
+        let code;
+        try {
+            code = fs.readFileSync(pageAbs, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const match of code.matchAll(/wrapCollection\(\s*['"]([^'"]+)['"]/g)) {
+            recordPage(pageAbs, match[1]);
+        }
+    }
     // ── In-code array literals: extract to src/data/<name>.json + wire ──
     for (const candidate of scan.collections) {
         const pageAbs = path.join(cwd, candidate.file);
@@ -173,6 +193,7 @@ export function rewireNextCollectionPages(cwd, detection, scan, drafts) {
         next = ensureFimoImport(next, ['wrapCollection'], 'fimo/next/server');
         fs.writeFileSync(pageAbs, next);
         rewired += 1;
+        recordPage(pageAbs, uid);
         changes.push(`rewired ${candidate.file}: \`${candidate.name}\` extracted to src/data/${candidate.name}.json and read through wrapCollection('${uid}')`);
     }
     // ── Data-file default imports: wire the importing pages ──
@@ -251,8 +272,11 @@ export function rewireNextCollectionPages(cwd, detection, scan, drafts) {
             next = ensureFimoImport(next, ['wrapCollection'], 'fimo/next/server');
             fs.writeFileSync(pageAbs, next);
             rewired += 1;
+            for (const target of targets) {
+                recordPage(pageAbs, target.uid);
+            }
             changes.push(`rewired ${rel}: ${targets.map((target) => `wrapCollection('${target.uid}')`).join(', ')} over the imported source rows`);
         }
     }
-    return { changes, warnings, rewired };
+    return { changes, warnings, rewired, pages };
 }

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

@@ -1,8 +1,18 @@
+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;
 }
+/**
+ * Route path for ONE app-router page file, using the same segment
+ * normalization as discovery — so a rewired page can be joined back to its
+ * registry route. Returns null for non-routable locations (`@slot`, `_lib`).
+ */
+export declare function routePathForAppPage(appDir: string, pageFile: string): string | null;
 /**
  * Discover page routes of a Next.js app-router directory (`app/` or
  * `src/app/`). Returns display routes for `fimo-config.json#routes` so the
@@ -15,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 { join } from 'node:path';
+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.
@@ -27,6 +22,29 @@ function segmentToPath(segment) {
     }
     return segment;
 }
+/**
+ * Route path for ONE app-router page file, using the same segment
+ * normalization as discovery — so a rewired page can be joined back to its
+ * registry route. Returns null for non-routable locations (`@slot`, `_lib`).
+ */
+export function routePathForAppPage(appDir, pageFile) {
+    const rel = relative(appDir, pageFile);
+    if (rel.startsWith('..')) {
+        return null;
+    }
+    const segments = rel.split(sep).slice(0, -1);
+    const parts = [];
+    for (const segment of segments) {
+        const mapped = segmentToPath(segment);
+        if (mapped === null) {
+            return null;
+        }
+        if (mapped.length > 0) {
+            parts.push(mapped);
+        }
+    }
+    return `/${parts.join('/')}`.replace(/\/+/g, '/');
+}
 /**
  * Discover page routes of a Next.js app-router directory (`app/` or
  * `src/app/`). Returns display routes for `fimo-config.json#routes` so the
@@ -45,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) {
@@ -120,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),
             });
         }
     };
@@ -132,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;
+}