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

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;

package/dist/scripts/lib/humanize.js

@@ -0,0 +1,54 @@
+/**
+ * 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.
+ */
+const ACRONYMS = new Set([
+    'ai',
+    'api',
+    'cd',
+    'ci',
+    'cli',
+    'cms',
+    'cta',
+    'faq',
+    'geo',
+    'llm',
+    'sdk',
+    'seo',
+    'spa',
+    'ssg',
+    'ssr',
+    'ui',
+    'url',
+    'ux',
+]);
+/** "ai-stack" → "AI Stack"; "agenticCms" → "Agentic CMS"; "blog" → "Blog". */
+export function humanizeSegment(segment) {
+    return segment
+        .replace(/[_\-]+/g, ' ')
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((word) => ACRONYMS.has(word.toLowerCase()) ? word.toUpperCase() : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+        .join(' ');
+}
+/**
+ * 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 function discoveredRouteLabel(path) {
+    if (path === '/') {
+        return 'Home';
+    }
+    const parts = path.split('/').filter(Boolean);
+    const lastStatic = [...parts].reverse().find((part) => !part.startsWith(':'));
+    const base = humanizeSegment(lastStatic ?? parts[parts.length - 1]?.replace(/^:/, '') ?? path);
+    const lastPart = parts[parts.length - 1];
+    if (lastPart?.startsWith(':') && lastStatic) {
+        return `${base} ${humanizeSegment(lastPart.replace(/^:|\*$/g, ''))}`;
+    }
+    return base;
+}

package/dist/scripts/render-parity/capture.d.ts

@@ -26,6 +26,13 @@ export declare class CaptureError extends Error {
     readonly stderrTail: string;
     constructor(message: string, stderrTail?: string);
 }
+/**
+ * pnpm's minimumReleaseAge setting refuses freshly published packages —
+ * exactly what a just-published fimo experimental is. The refusal surfaces
+ * deep in install/boot output; detect it and hand back the one-line fix
+ * instead of leaving an opaque boot failure.
+ */
+export declare function pnpmReleaseAgeHint(output: string): string | null;
 export declare function findFreePort(): Promise<number>;
 /**
  * Build workspace packages the app needs BEFORE booting its dev server. Fimo

package/dist/scripts/render-parity/capture.js

@@ -22,6 +22,20 @@ export class CaptureError extends Error {
         this.stderrTail = stderrTail;
     }
 }
+/**
+ * pnpm's minimumReleaseAge setting refuses freshly published packages —
+ * exactly what a just-published fimo experimental is. The refusal surfaces
+ * deep in install/boot output; detect it and hand back the one-line fix
+ * instead of leaving an opaque boot failure.
+ */
+export function pnpmReleaseAgeHint(output) {
+    if (!/minimumReleaseAge|ERR_PNPM_.*RELEASE/i.test(output)) {
+        return null;
+    }
+    return ('pnpm is refusing a freshly published package (minimumReleaseAge). ' +
+        'Add `minimumReleaseAgeExclude: ["fimo"]` to pnpm-workspace.yaml (or set `minimumReleaseAge: 0`), ' +
+        're-run your install, then re-run `npx fimo migrate`.');
+}
 export function findFreePort() {
     return new Promise((resolve, reject) => {
         const server = net.createServer();
@@ -206,7 +220,10 @@ export async function startDevServer(opts) {
     // Dev scripts that hardcode their own port are handled by sniffing stdout.
     const probe = async (origin) => {
         try {
-            const response = await fetch(origin, { signal: AbortSignal.timeout(2_000) });
+            // A generous per-attempt cap: connection-refused fails instantly, so
+            // this only holds when a server is LISTENING but slow (first SSR
+            // compile) — the exact case a short timeout misclassified as down.
+            const response = await fetch(origin, { signal: AbortSignal.timeout(15_000) });
             return response.status < 500;
         }
         catch {
@@ -273,10 +290,21 @@ export async function captureParityBaseline(opts) {
     if (opts.serverOrigin) {
         const origin = opts.serverOrigin.replace(/\/+$/, '');
         opts.onProgress?.(`using the running dev server at ${origin}`);
-        try {
-            await fetch(origin, { signal: AbortSignal.timeout(5_000) });
+        // Retry across a mid-recompile stall (Turbopack holds requests for
+        // seconds) — one short-timeout attempt misread a busy server as down.
+        let answered = false;
+        for (let attempt = 0; attempt < 3 && !answered; attempt++) {
+            try {
+                await fetch(origin, { signal: AbortSignal.timeout(10_000) });
+                answered = true;
+            }
+            catch {
+                if (attempt < 2) {
+                    await sleep(2_000);
+                }
+            }
         }
-        catch {
+        if (!answered) {
             throw new CaptureError(`No dev server answered at ${origin} — start it (e.g. \`${opts.packageManager} run dev\`) or drop --server to boot one.`);
         }
         server = { origin, stderrTail: () => '', stop: async () => { } };

package/dist/scripts/routes/label-prefixes.d.ts

@@ -0,0 +1,49 @@
+import { type RouteFileResolution, type RouteLike } from './module-resolve.js';
+/**
+ * The route ↔ file ↔ label-keys join. A page's Studio view resolves its
+ * labels by key prefix, defaulting to `<pageId>.` — but wrapped keys derive
+ * from FILE names (AiCms.tsx → ai-cms.*), which can diverge from the
+ * URL-derived page id (agentic-cms). Every divergence left unmapped is an
+ * EMPTY page in the Studio and an orphan pile in Labels & Text, so migrate
+ * prefills `labelPrefixes` wherever the join is provable and reports every
+ * staged prefix no page claims.
+ *
+ * Evidence rule: a page claims a prefix only when one of that prefix's
+ * staged keys appears VERBATIM in the page's own component file — never by
+ * name similarity. Shared prefixes (data files, chrome) match no page file
+ * and surface in the unclaimed report for the agent/user to place.
+ *
+ * This module is CORE: it never tests a framework name. The per-framework
+ * route-file resolvers live in `scripts/frameworks/<name>/routes.ts` behind
+ * the `frameworkRouteFiles` registry.
+ */
+export { componentImports, resolveModuleFile, type RouteFileResolution } from './module-resolve.js';
+export interface UnclaimedPrefix {
+    prefix: string;
+    exampleKey: string;
+    keys: number;
+    /** Shared site chrome (header/footer/nav/…) — belongs in a Single Type,
+     *  never on a page and never left as loose labels. */
+    chrome: boolean;
+}
+export declare function isChromePrefix(prefix: string): boolean;
+export declare function resolveRouteFiles(cwd: string, framework: string | null, routes: Record<string, RouteLike>): RouteFileResolution[];
+/**
+ * For each resolved page file, the staged prefixes whose keys appear verbatim
+ * in it. Returns only the routes whose evidence DIFFERS from the default
+ * (`{routeId}`) — and never touches a route that already declares prefixes.
+ */
+export declare function collectPageLabelPrefixes(resolutions: RouteFileResolution[], stagedKeys: Iterable<string>, routes: Record<string, RouteLike>): Map<string, string[]>;
+/**
+ * Staged prefixes no page claims (neither as its id nor via labelPrefixes) —
+ * each is either shared content (leave in Labels & Text) or a missed page
+ * mapping the agent must place with `fimo pages set --label-prefix`.
+ */
+export declare function unclaimedLabelPrefixes(stagedKeys: Iterable<string>, routes: Record<string, RouteLike>): UnclaimedPrefix[];
+/**
+ * Page ↔ Single Type claims, by verbatim read evidence: a page owns single S
+ * only when its component file provably READS S's document (`documents/S`,
+ * `useFimoSingle('S')`, `fetchDocument('S')`). Claimed singles edit inline
+ * in the Studio's page view; unclaimed ones stay in the Singles tab.
+ */
+export declare function collectPageSingles(resolutions: RouteFileResolution[], singletonUids: string[], routes: Record<string, RouteLike>): Map<string, string[]>;

package/dist/scripts/routes/label-prefixes.js

@@ -0,0 +1,136 @@
+import { readFileSync } from 'node:fs';
+import { frameworkRouteFiles } from '../frameworks/discover.js';
+/**
+ * The route ↔ file ↔ label-keys join. A page's Studio view resolves its
+ * labels by key prefix, defaulting to `<pageId>.` — but wrapped keys derive
+ * from FILE names (AiCms.tsx → ai-cms.*), which can diverge from the
+ * URL-derived page id (agentic-cms). Every divergence left unmapped is an
+ * EMPTY page in the Studio and an orphan pile in Labels & Text, so migrate
+ * prefills `labelPrefixes` wherever the join is provable and reports every
+ * staged prefix no page claims.
+ *
+ * Evidence rule: a page claims a prefix only when one of that prefix's
+ * staged keys appears VERBATIM in the page's own component file — never by
+ * name similarity. Shared prefixes (data files, chrome) match no page file
+ * and surface in the unclaimed report for the agent/user to place.
+ *
+ * This module is CORE: it never tests a framework name. The per-framework
+ * route-file resolvers live in `scripts/frameworks/<name>/routes.ts` behind
+ * the `frameworkRouteFiles` registry.
+ */
+export { componentImports, resolveModuleFile } from './module-resolve.js';
+const CHROME_PREFIX = /(header|footer|nav|menu|topbar|sidebar|banner|cookie|breadcrumb|social)/i;
+export function isChromePrefix(prefix) {
+    return CHROME_PREFIX.test(prefix);
+}
+export function resolveRouteFiles(cwd, framework, routes) {
+    return frameworkRouteFiles(framework)?.(cwd, routes) ?? [];
+}
+function keyPrefix(key) {
+    const dot = key.indexOf('.');
+    return dot > 0 ? key.slice(0, dot) : null;
+}
+function groupKeysByPrefix(stagedKeys) {
+    const groups = new Map();
+    for (const key of stagedKeys) {
+        const prefix = keyPrefix(key);
+        if (!prefix) {
+            continue;
+        }
+        groups.set(prefix, [...(groups.get(prefix) ?? []), key]);
+    }
+    return groups;
+}
+/**
+ * For each resolved page file, the staged prefixes whose keys appear verbatim
+ * in it. Returns only the routes whose evidence DIFFERS from the default
+ * (`{routeId}`) — and never touches a route that already declares prefixes.
+ */
+export function collectPageLabelPrefixes(resolutions, stagedKeys, routes) {
+    const groups = groupKeysByPrefix(stagedKeys);
+    const updates = new Map();
+    for (const { routeId, file } of resolutions) {
+        const route = routes[routeId];
+        if (!route || (Array.isArray(route.labelPrefixes) && route.labelPrefixes.length > 0)) {
+            continue;
+        }
+        let code;
+        try {
+            code = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const matched = [];
+        for (const [prefix, keys] of groups) {
+            if (keys.some((key) => code.includes(key))) {
+                matched.push(prefix);
+            }
+        }
+        matched.sort();
+        if (matched.length > 0 && (matched.length > 1 || matched[0] !== routeId)) {
+            updates.set(routeId, matched);
+        }
+    }
+    return updates;
+}
+/**
+ * Staged prefixes no page claims (neither as its id nor via labelPrefixes) —
+ * each is either shared content (leave in Labels & Text) or a missed page
+ * mapping the agent must place with `fimo pages set --label-prefix`.
+ */
+export function unclaimedLabelPrefixes(stagedKeys, routes) {
+    const claimed = new Set();
+    for (const [routeId, route] of Object.entries(routes)) {
+        claimed.add(routeId);
+        if (Array.isArray(route?.labelPrefixes)) {
+            for (const prefix of route.labelPrefixes) {
+                if (typeof prefix === 'string') {
+                    claimed.add(prefix.replace(/\.$/, ''));
+                }
+            }
+        }
+    }
+    return [...groupKeysByPrefix(stagedKeys)]
+        .filter(([prefix]) => !claimed.has(prefix))
+        .map(([prefix, keys]) => ({ prefix, exampleKey: keys[0], keys: keys.length, chrome: isChromePrefix(prefix) }))
+        .sort((a, b) => a.prefix.localeCompare(b.prefix));
+}
+/**
+ * Page ↔ Single Type claims, by verbatim read evidence: a page owns single S
+ * only when its component file provably READS S's document (`documents/S`,
+ * `useFimoSingle('S')`, `fetchDocument('S')`). Claimed singles edit inline
+ * in the Studio's page view; unclaimed ones stay in the Singles tab.
+ */
+export function collectPageSingles(resolutions, singletonUids, routes) {
+    const updates = new Map();
+    if (singletonUids.length === 0) {
+        return updates;
+    }
+    for (const { routeId, file } of resolutions) {
+        const route = routes[routeId];
+        if (!route || (Array.isArray(route.singles) && route.singles.length > 0)) {
+            continue;
+        }
+        let code;
+        try {
+            code = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const claimed = singletonUids
+            .filter((uid) => [
+            `documents/${uid}`,
+            `useFimoSingle('${uid}'`,
+            `useFimoSingle("${uid}"`,
+            `fetchDocument('${uid}'`,
+            `fetchDocument("${uid}"`,
+        ].some((marker) => code.includes(marker)))
+            .sort();
+        if (claimed.length > 0) {
+            updates.set(routeId, claimed);
+        }
+    }
+    return updates;
+}

package/dist/scripts/routes/module-resolve.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Framework-agnostic source-tree helpers shared by the per-framework route
+ * resolvers and the page-structure drafter: file walking, import maps, and
+ * module-specifier resolution. No framework name may appear here — framework
+ * knowledge lives in `scripts/frameworks/<name>/` behind the registry.
+ */
+export interface RouteFileResolution {
+    routeId: string;
+    file: string;
+}
+export interface RouteLike {
+    path?: string;
+    labelPrefixes?: unknown;
+    [key: string]: unknown;
+}
+export declare const DEFAULT_COMPONENT_EXTENSIONS: string[];
+export declare function walkFiles(dir: string, matches: (name: string) => boolean, out: string[]): void;
+/** Import map of a routes file: local component name → module specifier. */
+export declare function componentImports(code: string): Map<string, string>;
+export declare function resolveModuleFile(cwd: string, fromFile: string, spec: string, extensions?: readonly string[]): string | null;

package/dist/scripts/routes/module-resolve.js

@@ -0,0 +1,78 @@
+import { readdirSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', '.git', '.next', '.fimo']);
+export const DEFAULT_COMPONENT_EXTENSIONS = ['.tsx', '.jsx', '.ts', '.js'];
+export function walkFiles(dir, matches, out) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (SKIP_DIRS.has(entry)) {
+            continue;
+        }
+        const full = join(dir, entry);
+        let isDir = false;
+        try {
+            isDir = statSync(full).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (isDir) {
+            walkFiles(full, matches, out);
+        }
+        else if (matches(entry)) {
+            out.push(full);
+        }
+    }
+}
+/** Import map of a routes file: local component name → module specifier. */
+export function componentImports(code) {
+    const imports = new Map();
+    for (const match of code.matchAll(/import\s+(\w+)\s*(?:,\s*\{[^}]*\})?\s+from\s+['"]([^'"]+)['"]/g)) {
+        imports.set(match[1], match[2]);
+    }
+    for (const match of code.matchAll(/import\s*\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g)) {
+        for (const token of match[1].split(',')) {
+            const name = token.replace(/\s+as\s+(\w+)\s*$/, '$1').trim();
+            if (/^\w+$/.test(name)) {
+                imports.set(name, match[2]);
+            }
+        }
+    }
+    for (const match of code.matchAll(/(?:const|let)\s+(\w+)\s*=\s*(?:React\.)?lazy\(\s*(?:async\s*)?\(\)\s*=>\s*import\(\s*['"]([^'"]+)['"]\s*\)/g)) {
+        imports.set(match[1], match[2]);
+    }
+    return imports;
+}
+export function resolveModuleFile(cwd, fromFile, spec, extensions = DEFAULT_COMPONENT_EXTENSIONS) {
+    let base;
+    if (spec.startsWith('.')) {
+        base = join(dirname(fromFile), spec);
+    }
+    else if (spec.startsWith('~/') || spec.startsWith('@/')) {
+        base = join(cwd, 'src', spec.slice(2));
+    }
+    else {
+        return null;
+    }
+    for (const candidate of [
+        ...extensions.map((ext) => `${base}${ext}`),
+        ...extensions.map((ext) => join(base, `index${ext}`)),
+        base,
+    ]) {
+        try {
+            if (statSync(candidate).isFile()) {
+                return candidate;
+            }
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return null;
+}

package/dist/scripts/routes/page-structure.d.ts

@@ -0,0 +1,72 @@
+import type { CollectionCandidate } from '../scan-wrappable.js';
+/**
+ * Page-structure drafts — the machine's proposed NESTED model of a page.
+ * The scanner already sees everything the model needs: the page file's
+ * section components (capitalized JSX children, in document order), each
+ * section's label keys (its file-derived prefix) and its in-code collection
+ * candidates (typed rows). Joined, that IS the page's Single: one nested
+ * block field per section, recursing into the section's own components so
+ * deep structure (a Features grid whose groups live in their own files)
+ * surfaces too. The agent refines names and shapes — it no longer decides
+ * WHETHER to model, and real marketing copy stops dying as "page furniture"
+ * exemptions.
+ */
+export interface PageSectionDraft {
+    /** Proposed field key on the page Single (camelCase of the component). */
+    key: string;
+    component: string;
+    file: string;
+    /** The section's label-key prefix (file-derived). */
+    prefix: string;
+    /** Staged label keys the section owns — its scalar copy fields. */
+    labelKeys: string[];
+    /** In-code collection candidates found in the section's file — its
+     *  repeated block items (cards, quotes, logos), with their source rows so
+     *  the Single's document can be assembled without reopening the code. */
+    collections: Array<{
+        name: string;
+        fields: string[];
+        count: number;
+        rows?: Array<Record<string, unknown>>;
+    }>;
+    /** Content-bearing components the section renders — nested blocks. */
+    children?: PageSectionDraft[];
+    /** The same file drafts on several pages — chrome. Model it ONCE as a
+     *  Single Type, never as a per-page block. */
+    shared?: boolean;
+}
+export interface PageStructureDraft {
+    pageId: string;
+    /** Proposed Single uid (PascalCase of the page id). */
+    single: string;
+    sections: PageSectionDraft[];
+}
+export declare function draftPageStructures(args: {
+    cwd: string;
+    framework: string | null;
+    routes: Record<string, {
+        path?: string;
+        labelPrefixes?: unknown;
+        [key: string]: unknown;
+    }>;
+    stagedKeys: Iterable<string>;
+    collections: CollectionCandidate[];
+}): PageStructureDraft[];
+/** Flat section count across the nesting — the summary's visibility number. */
+export declare function countDraftSections(draft: PageStructureDraft): number;
+/**
+ * The machine-BUILT page Single: a ready-to-push singleton schema plus its
+ * filled document, assembled from the draft's non-shared sections (shared
+ * sections are chrome — modeled once elsewhere). One `max: 1` block per
+ * section; the section's labels become scalar fields carrying the staged
+ * values, its repeated arrays become nested blocks carrying the source
+ * rows, its child components nest the same way. The agent renames fields
+ * to editorial names and rewires reads — it no longer composes anything.
+ */
+export interface PageSingleDraft {
+    uid: string;
+    pageId: string;
+    schema: Record<string, unknown>;
+    document: Record<string, unknown>;
+}
+export declare function buildPageSingleDraft(draft: PageStructureDraft, labelValues: Record<string, string>): PageSingleDraft | null;