fimo 0.9.0-experimental.1 → 0.9.0-experimental.10

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();
@@ -76,6 +90,29 @@ function workspaceRoot(cwd) {
     }
     return null;
 }
+/** Every relative path target in an exports map (conditions and subpaths
+ *  flattened; `require`/`import`/`types`/`default` values alike). */
+function exportsTargets(exportsMap) {
+    if (typeof exportsMap === 'string') {
+        return exportsMap.startsWith('./') ? [exportsMap] : [];
+    }
+    if (Array.isArray(exportsMap)) {
+        return exportsMap.flatMap(exportsTargets);
+    }
+    if (exportsMap && typeof exportsMap === 'object') {
+        return Object.values(exportsMap).flatMap(exportsTargets);
+    }
+    return [];
+}
+/** A target file (or, for a `*` pattern, its base directory) exists. */
+function exportsTargetExists(depDir, target) {
+    const star = target.indexOf('*');
+    if (star === -1) {
+        return fs.existsSync(path.join(depDir, target));
+    }
+    const base = target.slice(0, star).replace(/\/[^/]*$/, '');
+    return fs.existsSync(path.join(depDir, base || '.'));
+}
 /** Internal workspace packages this app depends on (`workspace:` / `catalog:`
  *  protocol) whose build output is missing — a bare `next dev` fails on
  *  `Cannot find module '@repo/…/dist/…'` until they are built. */
@@ -98,8 +135,11 @@ function unbuiltWorkspaceDeps(cwd) {
             if (typeof entry === 'string') {
                 return !fs.existsSync(path.join(depDir, entry));
             }
-            // exports-only package: treat a missing dist/ as unbuilt.
-            return Boolean(depPkg.exports) && !fs.existsSync(path.join(depDir, 'dist'));
+            // Exports-only package: unbuilt when a RESOLVED target is missing — an
+            // exports map pointing at checked-in sources (eslint configs, type-only
+            // packages) never produces dist/ and must not be flagged forever.
+            const targets = exportsTargets(depPkg.exports);
+            return targets.length > 0 && targets.some((target) => !exportsTargetExists(depDir, target));
         }
         catch {
             return false; // can't resolve the link → don't force a build
@@ -110,10 +150,11 @@ function unbuiltWorkspaceDeps(cwd) {
  * Build workspace packages the app needs BEFORE booting its dev server. Fimo
  * runs the app's bare `next dev`, but in a Turborepo/pnpm monorepo the
  * internal deps (`@repo/*`) aren't built by that — `turbo dev` would build
- * them first. This detects unbuilt internal deps and runs the monorepo's
- * build once (the root `build` script, else `turbo run build`); turbo's cache
- * makes an already-built repo near-instant. A build failure is surfaced with
- * an actionable message instead of a cryptic `Cannot find module` at boot.
+ * them first. Builds are SCOPED to the flagged packages (turbo/pnpm/npm
+ * filters) — the root build script builds the whole app too and fails for
+ * reasons unrelated to the deps; it is only the last resort when no filter
+ * mechanism exists. A build failure is surfaced with an actionable message
+ * instead of a cryptic `Cannot find module` at boot.
  */
 export function ensureWorkspaceDepsBuilt(cwd, packageManager, onProgress) {
     const root = workspaceRoot(cwd);
@@ -125,30 +166,45 @@ export function ensureWorkspaceDepsBuilt(cwd, packageManager, onProgress) {
         return;
     }
     onProgress?.(`building workspace packages (${unbuilt.slice(0, 3).join(', ')}${unbuilt.length > 3 ? '…' : ''})`);
-    let rootBuild = null;
-    try {
-        const rootPkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
-        if (rootPkg.scripts?.build) {
-            rootBuild = { command: packageManager, args: ['run', 'build'] };
-        }
+    let build = null;
+    if (fs.existsSync(path.join(root, 'turbo.json'))) {
+        build = { command: 'npx', args: ['turbo', 'run', 'build', ...unbuilt.map((name) => `--filter=${name}`)] };
     }
-    catch {
-        // fall through to turbo
+    else if (packageManager === 'pnpm') {
+        build = {
+            command: 'pnpm',
+            args: [...unbuilt.flatMap((name) => ['--filter', name]), 'run', '--if-present', 'build'],
+        };
     }
-    if (!rootBuild && fs.existsSync(path.join(root, 'turbo.json'))) {
-        rootBuild = { command: 'npx', args: ['turbo', 'run', 'build'] };
+    else if (packageManager === 'npm') {
+        build = {
+            command: 'npm',
+            args: ['run', 'build', '--if-present', ...unbuilt.flatMap((name) => ['--workspace', name])],
+        };
     }
-    if (!rootBuild) {
-        throw new CaptureError(`Workspace packages (${unbuilt.join(', ')}) must be built before the dev server can boot, and the monorepo has no root \`build\` script or turbo config to run. Build them yourself, then re-run \`npx fimo migrate\`.`);
+    else {
+        // No filter mechanism (yarn classic, bun) — the root build is the last resort.
+        try {
+            const rootPkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+            if (rootPkg.scripts?.build) {
+                build = { command: packageManager, args: ['run', 'build'] };
+            }
+        }
+        catch {
+            // handled below
+        }
+    }
+    if (!build) {
+        throw new CaptureError(`Workspace packages (${unbuilt.join(', ')}) must be built before the dev server can boot, and the monorepo has no build mechanism the migration can drive. Build them yourself, then re-run \`npx fimo migrate\`.`);
     }
-    const result = spawnSync(rootBuild.command, rootBuild.args, {
+    const result = spawnSync(build.command, build.args, {
         cwd: root,
         timeout: 300_000,
         encoding: 'utf8',
         env: { ...process.env, NEXT_TELEMETRY_DISABLED: '1' },
     });
     if (result.status !== 0) {
-        throw new CaptureError(`Workspace packages (${unbuilt.join(', ')}) need building for the dev server, but \`${rootBuild.command} ${rootBuild.args.join(' ')}\` failed at ${path.relative(cwd, root) || 'the repo root'}. Build them yourself, then re-run \`npx fimo migrate\`.\n${(result.stderr || result.stdout || '').slice(-800)}`);
+        throw new CaptureError(`Workspace packages (${unbuilt.join(', ')}) need building for the dev server, but \`${build.command} ${build.args.join(' ')}\` failed at ${path.relative(cwd, root) || 'the repo root'}. Build them yourself, then re-run \`npx fimo migrate\`.\n${(result.stderr || result.stdout || '').slice(-800)}`);
     }
 }
 export async function startDevServer(opts) {
@@ -206,7 +262,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 +332,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/bindings.d.ts

@@ -0,0 +1,93 @@
+import type { CmsCollectionSchema } from '../cms/types.js';
+/**
+ * Page-binding evidence for the page registry (`fimo-config.json#routes`).
+ * A dynamic page template (`/blog/:slug`) is only navigable in the Studio
+ * preview once its content param carries a binding
+ * `{ schema, queryField, displayField }` — the schema whose entries
+ * materialize the page instances. No binding can be inferred with certainty,
+ * so this module grades evidence: `strong` bindings are written by the
+ * machine, `candidate` ones ship to the agent prompt as ready-to-apply
+ * suggestions. Neutral: evidence comes in as plain route/schema facts; the
+ * framework and CMS specifics stay in their adapters.
+ */
+export interface PageParamBinding {
+    schema: string;
+    queryField: string;
+    displayField: string;
+}
+export interface PageBinding {
+    routeId: string;
+    path: string;
+    param: string;
+    binding: PageParamBinding;
+    confidence: 'strong' | 'candidate';
+    source: 'rewire' | 'cms-wiring';
+}
+export interface UnboundPage {
+    id: string;
+    path: string;
+    candidates: PageBinding[];
+}
+export interface PageBindingsResult {
+    /** Written into the registry by the caller. */
+    strong: PageBinding[];
+    /** Dynamic pages left without params — with any candidate suggestions. */
+    unbound: UnboundPage[];
+    /** Dynamic pages that already carry params (manual or a prior run). */
+    bound: Array<{
+        id: string;
+        path: string;
+    }>;
+}
+/** A list page known to render a collection (the page-rewire join). */
+export interface ListPageEvidence {
+    routePath: string | null;
+    schema: string;
+}
+export interface SchemaFieldsLike {
+    readonly [field: string]: {
+        readonly type?: string;
+    };
+}
+export declare function isLocaleParam(name: string): boolean;
+interface ParsedDynamicPath {
+    /** The trailing content param name (without `:`/`*`). */
+    contentParam: string;
+    /** Route path minus the trailing content-param segment. */
+    parentPath: string;
+}
+/**
+ * A bindable dynamic path = optional locale-ish params + ONE trailing content
+ * param (catch-all or plain). Anything else (multiple content params) needs
+ * judgment beyond a single binding.
+ */
+export declare function parseDynamicPath(path: string): ParsedDynamicPath | null;
+/** First title-ish string field of a schema — the picker label the Studio
+ *  shows. Null when the schema has none (binding downgrades to candidate). */
+export declare function displayFieldFor(fields: SchemaFieldsLike | undefined): string | null;
+/** CMS collections that structurally look like page-builder page types: a
+ *  top-level dynamic-zone (blocks oneOf) field. Structural, never name-based. */
+export declare function cmsPageTypeEvidence(schemas: readonly CmsCollectionSchema[]): Array<{
+    schema: string;
+    fields: SchemaFieldsLike;
+}>;
+export declare function collectPageBindings(options: {
+    routes: Record<string, {
+        path?: string;
+        params?: unknown;
+    }>;
+    /** Rewired list pages (route-space, from the framework adapter). */
+    listPages?: readonly ListPageEvidence[];
+    /** Structural CMS page types (from `cmsPageTypeEvidence`), only when the
+     *  CMS reads are actually wired to Fimo. */
+    cmsPageTypes?: ReadonlyArray<{
+        schema: string;
+        fields: SchemaFieldsLike;
+    }>;
+    /** Uids still provisional (machine drafts not yet adopted) — their bindings
+     *  are candidates: `adopt-drafts` will rename them. */
+    provisionalUids?: ReadonlySet<string>;
+    /** Known fields per schema, for the displayField pick. */
+    schemaFields?: Record<string, SchemaFieldsLike>;
+}): PageBindingsResult;
+export {};

package/dist/scripts/routes/bindings.js

@@ -0,0 +1,117 @@
+/** Params that identify a locale, not content — never schema-bound. The
+ *  Studio preview substitutes content params only; locale params are a known
+ *  limitation documented in the prompt. Mirrors the parity capture's list. */
+const LOCALE_PARAMS = /^(locale|lang|language)$/i;
+export function isLocaleParam(name) {
+    return LOCALE_PARAMS.test(name);
+}
+const TITLE_FIELDS = /^(title|name|label|heading)$/i;
+/**
+ * A bindable dynamic path = optional locale-ish params + ONE trailing content
+ * param (catch-all or plain). Anything else (multiple content params) needs
+ * judgment beyond a single binding.
+ */
+export function parseDynamicPath(path) {
+    const params = [...path.matchAll(/:([^/*]+)\*?/g)].map((match) => match[1]);
+    if (params.length === 0) {
+        return null;
+    }
+    const contentParams = params.filter((param) => !LOCALE_PARAMS.test(param));
+    if (contentParams.length !== 1) {
+        return null;
+    }
+    const contentParam = contentParams[0];
+    if (!new RegExp(`/:${contentParam}\\*?$`).test(path)) {
+        return null; // the content param must be the trailing segment
+    }
+    const parentPath = path.replace(new RegExp(`/:${contentParam}\\*?$`), '') || '/';
+    return { contentParam, parentPath };
+}
+function isCatchAll(path, param) {
+    return path.endsWith(`:${param}*`);
+}
+/** First title-ish string field of a schema — the picker label the Studio
+ *  shows. Null when the schema has none (binding downgrades to candidate). */
+export function displayFieldFor(fields) {
+    for (const [name, def] of Object.entries(fields ?? {})) {
+        if (TITLE_FIELDS.test(name) && (def.type === undefined || def.type === 'string')) {
+            return name;
+        }
+    }
+    return null;
+}
+/** CMS collections that structurally look like page-builder page types: a
+ *  top-level dynamic-zone (blocks oneOf) field. Structural, never name-based. */
+export function cmsPageTypeEvidence(schemas) {
+    return schemas
+        .filter((schema) => !schema.isSingleton &&
+        Object.values(schema.fields).some((field) => field.type === 'blocks' && 'oneOf' in field.schema))
+        .map((schema) => ({ schema: schema.name, fields: schema.fields }));
+}
+export function collectPageBindings(options) {
+    const { routes, listPages = [], cmsPageTypes = [], provisionalUids, schemaFields = {} } = options;
+    const strong = [];
+    const unbound = [];
+    const bound = [];
+    for (const [id, route] of Object.entries(routes)) {
+        const path = route.path;
+        if (typeof path !== 'string' || !path.includes(':')) {
+            continue;
+        }
+        if (route.params && typeof route.params === 'object' && Object.keys(route.params).length > 0) {
+            bound.push({ id, path });
+            continue;
+        }
+        const params = [...path.matchAll(/:([^/*]+)\*?/g)].map((match) => match[1]);
+        if (params.every((param) => isLocaleParam(param))) {
+            continue; // locale-only page — nothing to bind, effectively static
+        }
+        const parsed = parseDynamicPath(path);
+        if (!parsed) {
+            unbound.push({ id, path, candidates: [] });
+            continue;
+        }
+        const candidates = [];
+        const make = (schema, source, baseConfidence) => {
+            const fields = schemaFields[schema] ?? cmsPageTypes.find((type) => type.schema === schema)?.fields;
+            const display = displayFieldFor(fields);
+            const confidence = provisionalUids?.has(schema) || display === null ? 'candidate' : baseConfidence;
+            return {
+                routeId: id,
+                path,
+                param: parsed.contentParam,
+                binding: { schema, queryField: 'slug', displayField: display ?? 'slug' },
+                confidence,
+                source,
+            };
+        };
+        // Rewire join: a list page rendering collection X at the dynamic page's
+        // parent path is strong evidence the detail param resolves against X.
+        const parents = listPages.filter((page) => page.routePath === parsed.parentPath);
+        const parentSchemas = [...new Set(parents.map((page) => page.schema))];
+        if (parentSchemas.length === 1) {
+            candidates.push(make(parentSchemas[0], 'rewire', 'strong'));
+        }
+        else {
+            for (const schema of parentSchemas) {
+                candidates.push(make(schema, 'rewire', 'candidate'));
+            }
+        }
+        // CMS-structural join: a catch-all page of a CMS-wired site renders the
+        // CMS's page-builder type. Unique page-builder type → strong.
+        if (isCatchAll(path, parsed.contentParam) && cmsPageTypes.length > 0) {
+            const unique = cmsPageTypes.length === 1;
+            for (const type of cmsPageTypes) {
+                candidates.push(make(type.schema, 'cms-wiring', unique ? 'strong' : 'candidate'));
+            }
+        }
+        const winner = candidates.find((candidate) => candidate.confidence === 'strong');
+        if (winner && candidates.filter((candidate) => candidate.confidence === 'strong').length === 1) {
+            strong.push(winner);
+        }
+        else {
+            unbound.push({ id, path, candidates });
+        }
+    }
+    return { strong, unbound, bound };
+}

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