fimo 0.8.0 → 0.9.0-experimental.10

package/dist/scripts/render-parity/normalize-html.js

@@ -0,0 +1,223 @@
+import * as cheerio from 'cheerio';
+// `title` included: Next dev streams document metadata into the body end
+// until the shell settles — title text is never visible page content, and
+// whether it lands in head or body depends on layout asyncness (a wrap
+// migration legitimately makes the root layout async).
+const REMOVED_TAGS = new Set([
+    'script',
+    'style',
+    'noscript',
+    'template',
+    'link',
+    'meta',
+    'svg',
+    'iframe',
+    'head',
+    'title',
+]);
+const BLOCK_TAGS = new Set([
+    'p',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'li',
+    'td',
+    'th',
+    'dt',
+    'dd',
+    'blockquote',
+    'figcaption',
+    'pre',
+    'button',
+    'label',
+    'summary',
+    'caption',
+    'option',
+]);
+const FALLBACK_BLOCK_TAGS = new Set(['div', 'section', 'article', 'main', 'aside', 'header', 'footer', 'nav', 'body']);
+const MARK_KIND = {
+    strong: 'strong',
+    b: 'strong',
+    em: 'em',
+    i: 'em',
+    u: 'u',
+    s: 's',
+    del: 's',
+    strike: 's',
+    code: 'code',
+    a: 'a',
+};
+function collapse(text) {
+    return text.replace(/ /g, ' ').replace(/\s+/g, ' ').trim();
+}
+/** Strip the capture origin so differing ports between runs compare equal. */
+export function normalizeHref(href, origin) {
+    if (href.startsWith(origin)) {
+        const stripped = href.slice(origin.length);
+        return stripped.startsWith('/') ? stripped : `/${stripped}`;
+    }
+    return href;
+}
+/**
+ * Media src normalization: origin strip + Next image-optimizer decode, so a
+ * pre-wrap `next/image` (`/_next/image?url=…&w=…`) and a post-wrap plain
+ * `<img src>` of the same asset compare equal.
+ */
+export function normalizeMediaSrc(src, origin) {
+    let value = normalizeHref(src, origin);
+    const optimizerMatch = value.match(/^\/_next\/image\?(.+)$/);
+    if (optimizerMatch) {
+        const params = new URLSearchParams(optimizerMatch[1]);
+        const url = params.get('url');
+        if (url) {
+            value = url;
+        }
+    }
+    return value;
+}
+function isExcluded(node) {
+    const tag = node.name?.toLowerCase() ?? '';
+    if (REMOVED_TAGS.has(tag)) {
+        return true;
+    }
+    // Hidden elements are not visible content — except Next streaming
+    // containers (div[hidden][id^="S:"]), whose content replaces Suspense
+    // holes; kept in document order so streamed content is captured
+    // symmetrically between baseline and check.
+    if (node.attribs && 'hidden' in node.attribs) {
+        const isStreamingContainer = tag === 'div' && (node.attribs.id ?? '').startsWith('S:');
+        if (!isStreamingContainer) {
+            return true;
+        }
+    }
+    return false;
+}
+function nearestBlock(node) {
+    let current = node.parent;
+    let fallback = null;
+    while (current) {
+        const tag = current.name?.toLowerCase();
+        if (tag && BLOCK_TAGS.has(tag)) {
+            return current;
+        }
+        if (!fallback && tag && FALLBACK_BLOCK_TAGS.has(tag)) {
+            fallback = current;
+        }
+        current = current.parent;
+    }
+    return fallback;
+}
+function collectText(node) {
+    if (node.type === 'text') {
+        return String(node.data ?? '');
+    }
+    if (node.type !== 'tag' || isExcluded(node)) {
+        return '';
+    }
+    return (node.children ?? []).map(collectText).join('');
+}
+export function extractRouteSignature(html, opts) {
+    const $ = cheerio.load(html);
+    const bodyNode = $('body').get(0);
+    const blocks = [];
+    const blockIndex = new Map();
+    const images = [];
+    const videos = [];
+    const links = [];
+    const visit = (node) => {
+        if (node.type === 'text') {
+            const text = collapse(String(node.data ?? ''));
+            if (!text) {
+                return;
+            }
+            const block = nearestBlock(node);
+            if (!block) {
+                return;
+            }
+            const existing = blockIndex.get(block);
+            if (existing === undefined) {
+                blockIndex.set(block, blocks.length);
+                blocks.push({ tag: block.name?.toLowerCase() ?? 'div', text, marks: [] });
+            }
+            else {
+                blocks[existing].text = collapse(`${blocks[existing].text} ${text}`);
+            }
+            return;
+        }
+        if (node.type !== 'tag' && node.type !== 'root') {
+            return;
+        }
+        if (node.type === 'tag' && isExcluded(node)) {
+            return;
+        }
+        const tag = node.name?.toLowerCase() ?? '';
+        const attribs = node.attribs ?? {};
+        // Inline-marks signature: the formatting that must survive wrapping and
+        // the TipTap seed round-trip. Attached to the nearest block.
+        const markKind = MARK_KIND[tag];
+        if (markKind) {
+            const text = collapse(collectText(node));
+            if (text) {
+                const block = nearestBlock(node);
+                if (block) {
+                    if (!blockIndex.has(block)) {
+                        blockIndex.set(block, blocks.length);
+                        blocks.push({ tag: block.name?.toLowerCase() ?? 'div', text: '', marks: [] });
+                    }
+                    const mark = { kind: markKind, text };
+                    if (markKind === 'a') {
+                        if (attribs.href) {
+                            mark.href = normalizeHref(attribs.href, opts.origin);
+                            blocks[blockIndex.get(block)].marks.push(mark);
+                        }
+                    }
+                    else {
+                        blocks[blockIndex.get(block)].marks.push(mark);
+                    }
+                }
+            }
+        }
+        if (tag === 'img' && attribs.src) {
+            images.push(normalizeMediaSrc(attribs.src, opts.origin));
+        }
+        if (tag === 'source' && attribs.src) {
+            const parentTag = node.parent?.name?.toLowerCase();
+            if (parentTag === 'picture') {
+                images.push(normalizeMediaSrc(attribs.src, opts.origin));
+            }
+            else if (parentTag === 'video') {
+                videos.push(normalizeMediaSrc(attribs.src, opts.origin));
+            }
+        }
+        if (tag === 'video') {
+            if (attribs.src) {
+                videos.push(normalizeMediaSrc(attribs.src, opts.origin));
+            }
+            if (attribs.poster) {
+                videos.push(normalizeMediaSrc(attribs.poster, opts.origin));
+            }
+        }
+        if (tag === 'a' && attribs.href) {
+            links.push({ href: normalizeHref(attribs.href, opts.origin), text: collapse(collectText(node)) });
+        }
+        for (const child of node.children ?? []) {
+            visit(child);
+        }
+    };
+    if (bodyNode) {
+        for (const child of bodyNode.children ?? []) {
+            visit(child);
+        }
+    }
+    // Blocks created empty by a mark preceding any direct text (e.g. a <p>
+    // starting with <strong>) get their text from the block's full content.
+    for (const [block, index] of blockIndex) {
+        if (!blocks[index].text) {
+            blocks[index].text = collapse(collectText(block));
+        }
+    }
+    return { status: opts.status, blocks: blocks.filter((block) => block.text.length > 0), images, videos, links };
+}

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

@@ -0,0 +1,41 @@
+export declare const PARITY_BASELINE_VERSION = 1;
+export interface InlineMark {
+    kind: 'strong' | 'em' | 'u' | 's' | 'code' | 'a';
+    text: string;
+    href?: string;
+}
+export interface TextBlock {
+    tag: string;
+    text: string;
+    marks: InlineMark[];
+}
+export interface RouteSignature {
+    status: number;
+    blocks: TextBlock[];
+    images: string[];
+    videos: string[];
+    links: Array<{
+        href: string;
+        text: string;
+    }>;
+}
+export type RouteCapture = {
+    signature: RouteSignature;
+} | {
+    skipped: 'dynamic-params' | 'fetch-failed';
+    error?: string;
+};
+/**
+ * Normalized pre-wrap snapshot of every route's rendered content. Written to
+ * `.fimo/migration/parity-baseline.json`; `fimo migrate wrap --check`
+ * recaptures with the identical pipeline and compares.
+ */
+export interface ParityBaseline {
+    version: typeof PARITY_BASELINE_VERSION;
+    capturedAt: string;
+    engine: 'dev-server';
+    framework: string | null;
+    command: string;
+    unwrappedAtCapture?: number;
+    routes: Record<string, RouteCapture>;
+}

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

@@ -0,0 +1 @@
+export const PARITY_BASELINE_VERSION = 1;

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;