fimo 0.8.0 → 0.9.0-experimental.10

package/dist/runtime/wrapped/content-fetch.pure.js

@@ -0,0 +1,106 @@
+// Wrapped-content fetching, PURE core: fetch/URL/AbortController only — no
+// node builtins, importable from client-bundled code (the SPA provider) and
+// from the server loaders alike. The plumbing types (WrappedRichText,
+// WrappedMedia) hold ALL of a site's wrapped rich text and media, so the
+// fetch PAGINATES to the end — the tenant API caps limit at 100 and a real
+// site exceeds it (the Fimo site carries 147 rich-text entries).
+import { fetchWithTimeout } from '../shared/labels-fetch.pure.js';
+const PAGE_LIMIT = 100;
+const MAX_ROWS = 5000;
+function readString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function readNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/** Every published row of a content type, paginated to the end. Returns []
+ *  when the API is unreachable so wrapped sites keep their fallbacks. */
+export async function fetchAllWrappedRows(apiUrl, typeName) {
+    const rows = [];
+    try {
+        for (let offset = 0; offset < MAX_ROWS; offset += PAGE_LIMIT) {
+            const url = new URL(`/entries/${typeName}`, apiUrl);
+            url.searchParams.set('limit', String(PAGE_LIMIT));
+            url.searchParams.set('offset', String(offset));
+            const response = await fetchWithTimeout(url, 4000);
+            if (!response.ok) {
+                break;
+            }
+            const body = (await response.json());
+            const page = Array.isArray(body.data) ? body.data : [];
+            for (const row of page) {
+                if (!row || typeof row !== 'object') {
+                    continue;
+                }
+                const record = row;
+                const id = String(record.id ?? record.documentId ?? '');
+                if (id.length === 0) {
+                    continue;
+                }
+                rows.push({
+                    id,
+                    data: (record.data && typeof record.data === 'object' ? record.data : record),
+                });
+            }
+            const hasMore = body.meta?.hasMore === true || page.length === PAGE_LIMIT;
+            if (!hasMore) {
+                break;
+            }
+        }
+    }
+    catch {
+        // Unreachable API mid-pagination: return what we have (possibly []).
+    }
+    return rows;
+}
+/** WrappedMedia rows → key → media entry (the FimoMediaImage/Video id map). */
+export function mapWrappedMedia(rows) {
+    const map = {};
+    for (const entry of rows) {
+        const key = readString(entry.data.key) ?? readString(entry.data.slug);
+        const asset = entry.data.image;
+        if (!key || !asset || typeof asset !== 'object') {
+            continue;
+        }
+        const assetRecord = asset;
+        const url = readString(assetRecord.url);
+        if (!url) {
+            continue;
+        }
+        map[key] = {
+            url,
+            alt: readString(assetRecord.alt) ?? readString(entry.data.alt),
+            name: readString(assetRecord.name),
+            mime: readString(assetRecord.mime) ?? readString(assetRecord.mimeType),
+            width: readNumber(assetRecord.width),
+            height: readNumber(assetRecord.height),
+            source: `WrappedMedia.${entry.id}.image`,
+        };
+    }
+    return map;
+}
+/** WrappedRichText rows → key → TipTap content (the FimoRichTextBlock map). */
+export function mapWrappedRichText(rows) {
+    const map = {};
+    for (const entry of rows) {
+        const key = readString(entry.data.key) ?? readString(entry.data.slug);
+        const body = entry.data.body;
+        if (!key || !body || typeof body !== 'object') {
+            continue;
+        }
+        map[key] = {
+            content: body,
+            source: `WrappedRichText.${entry.id}.body`,
+        };
+    }
+    return map;
+}
+/** Both plumbing maps in one round: what a client-rendered wrapped app needs
+ *  so Studio edits to rich text and media are LIVE, not fallback-only. */
+export async function fetchWrappedContent(apiUrl) {
+    const [mediaRows, richTextRows] = await Promise.all([
+        fetchAllWrappedRows(apiUrl, 'WrappedMedia'),
+        fetchAllWrappedRows(apiUrl, 'WrappedRichText'),
+    ]);
+    return { media: mapWrappedMedia(mediaRows), richText: mapWrappedRichText(richTextRows) };
+}

package/dist/runtime/wrapped/dom.d.ts

@@ -0,0 +1,4 @@
+export declare const FIMO_SOURCE_ATTR = "data-fimo-source";
+export declare function fimoLabelAttrs(key: string, locale?: string): Record<string, string>;
+export declare function fimoMediaAttrs(source: string): Record<string, string>;
+//# sourceMappingURL=dom.d.ts.map

package/dist/runtime/wrapped/dom.js

@@ -0,0 +1,23 @@
+// Framework-agnostic DOM contract for wrapped content in NON-React
+// frameworks (Astro templates, Vue SFCs, Svelte components). The edit-mode
+// preview client selects elements by these attributes; rendering the value +
+// attributes is all a template needs:
+//
+//   Astro:  <h1 {...fimoLabelAttrs('home.title')}>{t('home.title', 'Hello')}</h1>
+//   Vue:    <h1 v-bind="fimoLabelAttrs('home.title')">{{ t('home.title', 'Hello') }}</h1>
+//   Svelte: <h1 {...fimoLabelAttrs('home.title')}>{tv}</h1>
+//
+// Values come from the server loaders (loadFimoT / loadWrappedMedia) — after
+// an edit, the page refetches on reload; live DOM patching is handled by the
+// preview client via these same attributes.
+// NOTE: this must be the literal DOM attribute the preview client queries
+// (`document.querySelectorAll('[data-fimo-source]')`) — NOT the FIMO_SOURCE
+// Symbol from the React primitives: a symbol key vanishes in a template
+// attribute spread and in JSON, silently breaking editability.
+export const FIMO_SOURCE_ATTR = 'data-fimo-source';
+export function fimoLabelAttrs(key, locale = 'en') {
+    return { [FIMO_SOURCE_ATTR]: `__labels.${locale}.${key}.value` };
+}
+export function fimoMediaAttrs(source) {
+    return { [FIMO_SOURCE_ATTR]: source };
+}

package/dist/runtime/wrapped/server.d.ts

@@ -0,0 +1,80 @@
+import type { FimoNextLabels } from '../next/FimoNextProviders.js';
+import type { FimoConfig } from '../shared/fimo-config.types.js';
+import type { WrappedMediaEntry, WrappedRichTextEntry } from './WrappedContentContext.js';
+export interface FimoServerOptions {
+    /** Project root (where fimo-config.json and .env live). Defaults to cwd. */
+    rootDir?: string;
+    /** Tenant API base URL. Defaults to NEXT_PUBLIC_FIMO_API_URL / VITE_API_URL. */
+    apiUrl?: string;
+}
+export declare function loadFimoConfig(rootDir?: string): FimoConfig;
+export declare function loadFimoLabels(options?: FimoServerOptions): Promise<FimoNextLabels>;
+/**
+ * Server-component label accessor: `useLabels()` is client-only, and forcing
+ * a client wrapper for one aria-label in a server component is not a
+ * migration, it is collateral damage. Load once per request scope and read
+ * synchronously: `const t = await loadFimoT(); <a aria-label={t('footer.github', 'GitHub')} …`.
+ */
+export declare function loadFimoT(options?: FimoServerOptions & {
+    locale?: string;
+}): Promise<(key: string, fallback: string) => string>;
+export interface FimoEntry {
+    id: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Fetch published entries of a content type from the public tenant API.
+ * Returns [] when the API is unreachable so the wrapped site keeps rendering
+ * its fallbacks.
+ */
+export declare function fetchEntries(typeName: string, options?: FimoServerOptions & {
+    /** The public API returns newest-first; rendering wants source order.
+     *  Default 'oldest' restores insertion order for migrated collections. */
+    order?: 'oldest' | 'newest';
+    /** Query filter forwarded to the public API (e.g. { slug: { $in: [...] } }). */
+    where?: Record<string, unknown>;
+    /** Row cap forwarded to the public API. */
+    limit?: number;
+}): Promise<FimoEntry[]>;
+/**
+ * Load the WrappedMedia entries (key → media) seeded by the wrap migration.
+ * Each entry has a `key` (the FimoMediaImage/Video/FileLink id) and an
+ * asset-typed `image` field. Paginates to the end — a site's wrapped media
+ * routinely exceeds one API page.
+ */
+export declare function loadWrappedMedia(options?: FimoServerOptions): Promise<Record<string, WrappedMediaEntry>>;
+/**
+ * Load the WrappedRichText entries (key → TipTap JSON) seeded by the wrap
+ * migration for formatted text (bold/italic/underline/links). Paginates to
+ * the end — the Fimo site alone carries 147 entries against a 20-row API
+ * default page.
+ */
+export declare function loadWrappedRichText(options?: FimoServerOptions): Promise<Record<string, WrappedRichTextEntry>>;
+/**
+ * Overlay a wrap-migrated collection onto its retained source rows: fetch the
+ * Fimo entries matching the source rows' keys, merge field-by-field with the
+ * type-matched rule above, and return plain data rows in SOURCE order. The
+ * page keeps its original render logic and its original fallback — edits made
+ * in Fimo show up, everything else stays byte-identical.
+ */
+export declare function wrapCollection<T extends Record<string, unknown>>(typeName: string, sourceRows: readonly T[], options?: FimoServerOptions & {
+    keyField?: string;
+}): Promise<T[]>;
+/**
+ * Load a locale's messages from Fimo for an EXISTING i18n runtime (next-intl,
+ * i18next). Wrap-mode i18n ingestion seeds the app's message store into Fimo
+ * labels (flat dot-keys); this fetches them back and un-flattens them into the
+ * nested shape the app's own i18n loader expects — so the app keeps its
+ * `useTranslations`/`t()` unchanged, now editable from Fimo Studio.
+ *
+ * Deep-merge over the shipped messages (pass them as `fallback`) so any key
+ * not yet in Fimo falls back to the static file instead of showing a missing
+ * key. Wire it in the app's message loader, e.g. next-intl `i18n/request.ts`:
+ *
+ *   const messages = await loadFimoMessages(locale, { fallback: staticMessages });
+ *   return { locale, messages };
+ */
+export declare function loadFimoMessages(locale: string, options?: FimoServerOptions & {
+    fallback?: Record<string, unknown>;
+}): Promise<Record<string, unknown>>;
+//# sourceMappingURL=server.d.ts.map

package/dist/runtime/wrapped/server.js

@@ -0,0 +1,207 @@
+// Server-only loaders for WRAPPED (adopted) apps — framework-neutral.
+// Content resolves at request time from the public tenant API (no Vite
+// virtual modules, no build plugin). Framework adapters re-export these:
+// fimo/next/server today, fimo/astro tomorrow — same loaders, same shapes.
+import { getConfigServer } from '../shared/fimo-config.server.js';
+import { deepMergeMessages, unflattenMessages } from '../shared/i18n-messages.js';
+import { fetchLabelDictionary, fetchWithTimeout, labelSignature, loadLabelBundle, readProjectEnv, resolveTenantApiUrl, } from '../shared/labels-fetch.server.js';
+import { fetchAllWrappedRows, mapWrappedMedia, mapWrappedRichText } from './content-fetch.pure.js';
+export function loadFimoConfig(rootDir = process.cwd()) {
+    return getConfigServer(rootDir);
+}
+export async function loadFimoLabels(options = {}) {
+    const rootDir = options.rootDir ?? process.cwd();
+    const bundle = await loadLabelBundle(rootDir);
+    return { ...bundle, signature: labelSignature(bundle) };
+}
+/**
+ * Server-component label accessor: `useLabels()` is client-only, and forcing
+ * a client wrapper for one aria-label in a server component is not a
+ * migration, it is collateral damage. Load once per request scope and read
+ * synchronously: `const t = await loadFimoT(); <a aria-label={t('footer.github', 'GitHub')} …`.
+ */
+export async function loadFimoT(options = {}) {
+    const labels = await loadFimoLabels(options);
+    const locale = options.locale ?? labels.defaultLocale;
+    const dictionary = labels.dictionaries[locale] ?? labels.dictionaries[labels.defaultLocale] ?? {};
+    return (key, fallback) => {
+        const value = dictionary[key];
+        return typeof value === 'string' && value.length > 0 ? value : fallback;
+    };
+}
+async function resolveApiUrl(options) {
+    if (options.apiUrl) {
+        return options.apiUrl;
+    }
+    const env = await readProjectEnv(options.rootDir ?? process.cwd());
+    return resolveTenantApiUrl(env);
+}
+/**
+ * Fetch published entries of a content type from the public tenant API.
+ * Returns [] when the API is unreachable so the wrapped site keeps rendering
+ * its fallbacks.
+ */
+export async function fetchEntries(typeName, options = {}) {
+    const apiUrl = await resolveApiUrl(options);
+    if (!apiUrl) {
+        return [];
+    }
+    try {
+        const url = new URL(`/entries/${typeName}`, apiUrl);
+        if (options.where) {
+            url.searchParams.set('where', JSON.stringify(options.where));
+        }
+        if (options.limit) {
+            url.searchParams.set('limit', String(options.limit));
+        }
+        const response = await fetchWithTimeout(url, 4000);
+        if (!response.ok) {
+            return [];
+        }
+        const body = (await response.json());
+        const rows = Array.isArray(body.data) ? body.data : [];
+        const entries = rows
+            .filter((row) => Boolean(row) && typeof row === 'object')
+            .map((row) => ({
+            id: String(row.id ?? row.documentId ?? ''),
+            data: (row.data && typeof row.data === 'object' ? row.data : row),
+        }))
+            .filter((row) => row.id.length > 0);
+        return (options.order ?? 'oldest') === 'oldest' ? entries.reverse() : entries;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Load the WrappedMedia entries (key → media) seeded by the wrap migration.
+ * Each entry has a `key` (the FimoMediaImage/Video/FileLink id) and an
+ * asset-typed `image` field. Paginates to the end — a site's wrapped media
+ * routinely exceeds one API page.
+ */
+export async function loadWrappedMedia(options = {}) {
+    const apiUrl = await resolveApiUrl(options);
+    if (!apiUrl) {
+        return {};
+    }
+    return mapWrappedMedia(await fetchAllWrappedRows(apiUrl, 'WrappedMedia'));
+}
+/**
+ * Load the WrappedRichText entries (key → TipTap JSON) seeded by the wrap
+ * migration for formatted text (bold/italic/underline/links). Paginates to
+ * the end — the Fimo site alone carries 147 entries against a 20-row API
+ * default page.
+ */
+export async function loadWrappedRichText(options = {}) {
+    const apiUrl = await resolveApiUrl(options);
+    if (!apiUrl) {
+        return {};
+    }
+    return mapWrappedRichText(await fetchAllWrappedRows(apiUrl, 'WrappedRichText'));
+}
+/** Key fields tried, in order, to align a source row with its Fimo entry. */
+const COLLECTION_KEY_FIELDS = ['slug', 'id', 'key', 'name', 'title', 'question'];
+/** Fimo entries fetched per collection: covers rendered windows and small
+ *  collections entirely; rows beyond it keep rendering their source values. */
+const COLLECTION_FETCH_CAP = 100;
+function collectionKeyField(rows) {
+    for (const field of COLLECTION_KEY_FIELDS) {
+        if (rows.every((row) => typeof row[field] === 'string' && row[field].length > 0)) {
+            return field;
+        }
+    }
+    return null;
+}
+/** A Fimo value replaces its source value only when the SHAPES agree, so a
+ *  page that rendered strings keeps rendering strings: media envelopes,
+ *  richtext docs, reference handles, and nulls all fall back to the source
+ *  value instead of leaking objects into JSX. */
+function preferTypeMatched(fimoValue, sourceValue) {
+    if (fimoValue === null || fimoValue === undefined) {
+        return sourceValue;
+    }
+    if (Array.isArray(sourceValue)) {
+        if (!Array.isArray(fimoValue)) {
+            return sourceValue;
+        }
+        return fimoValue.every((element) => typeof element === typeof (sourceValue[0] ?? '') && typeof element !== 'object')
+            ? fimoValue
+            : sourceValue;
+    }
+    return typeof fimoValue === typeof sourceValue && typeof fimoValue !== 'object' ? fimoValue : sourceValue;
+}
+/**
+ * Overlay a wrap-migrated collection onto its retained source rows: fetch the
+ * Fimo entries matching the source rows' keys, merge field-by-field with the
+ * type-matched rule above, and return plain data rows in SOURCE order. The
+ * page keeps its original render logic and its original fallback — edits made
+ * in Fimo show up, everything else stays byte-identical.
+ */
+export async function wrapCollection(typeName, sourceRows, options = {}) {
+    const rows = sourceRows;
+    if (rows.length === 0) {
+        return [];
+    }
+    const keyField = options.keyField ?? collectionKeyField(rows);
+    if (!keyField) {
+        return sourceRows;
+    }
+    const keys = rows.slice(0, COLLECTION_FETCH_CAP).map((row) => row[keyField]);
+    const entries = await fetchEntries(typeName, {
+        ...options,
+        where: { [keyField]: { $in: keys } },
+        limit: keys.length,
+    });
+    if (entries.length === 0) {
+        return sourceRows;
+    }
+    const byKey = new Map();
+    for (const entry of entries) {
+        const key = entry.data[keyField];
+        if (typeof key === 'string' && !byKey.has(key)) {
+            byKey.set(key, entry.data);
+        }
+    }
+    return rows.map((row) => {
+        const fimoRow = byKey.get(row[keyField]);
+        if (!fimoRow) {
+            return row;
+        }
+        const merged = { ...row };
+        for (const field of Object.keys(row)) {
+            merged[field] = preferTypeMatched(fimoRow[field], row[field]);
+        }
+        return merged;
+    });
+}
+/**
+ * Load a locale's messages from Fimo for an EXISTING i18n runtime (next-intl,
+ * i18next). Wrap-mode i18n ingestion seeds the app's message store into Fimo
+ * labels (flat dot-keys); this fetches them back and un-flattens them into the
+ * nested shape the app's own i18n loader expects — so the app keeps its
+ * `useTranslations`/`t()` unchanged, now editable from Fimo Studio.
+ *
+ * Deep-merge over the shipped messages (pass them as `fallback`) so any key
+ * not yet in Fimo falls back to the static file instead of showing a missing
+ * key. Wire it in the app's message loader, e.g. next-intl `i18n/request.ts`:
+ *
+ *   const messages = await loadFimoMessages(locale, { fallback: staticMessages });
+ *   return { locale, messages };
+ */
+export async function loadFimoMessages(locale, options = {}) {
+    const fallback = options.fallback ?? {};
+    const apiUrl = await resolveApiUrl(options);
+    if (!apiUrl) {
+        return fallback;
+    }
+    try {
+        const { labels } = await fetchLabelDictionary(apiUrl, locale);
+        if (Object.keys(labels).length === 0) {
+            return fallback;
+        }
+        return deepMergeMessages(fallback, unflattenMessages(labels));
+    }
+    catch {
+        return fallback;
+    }
+}

package/dist/scripts/apply-wrap-templates.d.ts

@@ -0,0 +1,61 @@
+import { KeyAllocator, type ApplyWrapResult } from './apply-wrap.js';
+import { type WrappableItem } from './scan-wrappable.js';
+/**
+ * The template half of the --apply codemod: wraps plain TEMPLATE text nodes
+ * with the framework's t() form and injects the per-file wiring head once.
+ * Framework-neutral by contract — everything framework-specific arrives via
+ * a TemplateWrapStyle from the framework registry (frameworks/discover.ts).
+ *
+ * Grown out of the batch-dogfood plan-driven wrapper (392/392 items on a
+ * 201-route site); the lessons it encodes:
+ * - heads go in the INSTANCE script, never a `<script module>` block;
+ * - files that already bind a `t` identifier (i18n libraries, custom
+ *   helpers) are left whole for the agent — renaming foreign t() calls
+ *   broke a real site;
+ * - label VALUES decode HTML entities while the inline fallback keeps the
+ *   source form, so rendering never changes;
+ * - keys are collision-safe via the shared KeyAllocator.
+ *
+ * Anything that is not a plain text node (attributes, media, markup the
+ * preview matcher cannot anchor) stays in the plan for the agent — same
+ * philosophy as the JSX codemod: provably safe or hands off.
+ */
+export interface TemplateWrapStyle {
+    /** File extension this style owns, e.g. '.astro'. */
+    ext: string;
+    /** Wiring lines injected once per file (the t() head). */
+    head: string;
+    /** Marker proving our wiring (or an equivalent manual one) is present. */
+    headMarker: RegExp;
+    /** t() delimiters around `"key", "fallback"`. */
+    open: string;
+    close: string;
+    /**
+     * Insert the head into a file. Return null when the file has no safe
+     * injection point (e.g. an options-API script) — its items stay agent work.
+     */
+    injectHead: (code: string, head: string) => string | null;
+    /** Override the key scope for route-convention filenames (+page.svelte). */
+    fileScope?: (file: string) => string | null;
+    /** One-time project wiring once any file was wrapped. Returns files written. */
+    ensureWiring?: (rootDir: string) => string[];
+}
+/**
+ * Shared injection helper for SFC-style templates: first instance script,
+ * never a `<script module>` block (module scope cannot read page data), or a
+ * fresh script when the file has none.
+ */
+export declare function injectIntoInstanceScript(code: string, head: string, scriptTag: string): string;
+export declare function applyTemplateWrapToFile(code: string, style: TemplateWrapStyle, items: WrappableItem[], allocator: KeyAllocator): {
+    code: string;
+} & Omit<ApplyWrapResult, 'filesChanged'>;
+/**
+ * Apply the template wraps across a project — same contract as applyWrap:
+ * scans, mutates source files, returns the generated labels for staging and
+ * seeding. The style's ensureWiring hook then writes any one-time project
+ * wiring (e.g. a root layout labels loader) when files were wrapped.
+ */
+export declare function applyTemplateWrap(rootDir: string, opts: {
+    style: TemplateWrapStyle;
+    excludePrefixes?: string[];
+}): ApplyWrapResult;

package/dist/scripts/apply-wrap-templates.js

@@ -0,0 +1,137 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { decodeJsxEntities, KeyAllocator, readApplyExemptions, reusableStagedLabels, slugify, } from './apply-wrap.js';
+import { scanWrappable } from './scan-wrappable.js';
+/**
+ * Shared injection helper for SFC-style templates: first instance script,
+ * never a `<script module>` block (module scope cannot read page data), or a
+ * fresh script when the file has none.
+ */
+export function injectIntoInstanceScript(code, head, scriptTag) {
+    const instance = code.match(/<script(?![^>]*\bmodule\b)[^>]*>\r?\n?/);
+    if (instance && instance.index !== undefined) {
+        const at = instance.index + instance[0].length;
+        return `${code.slice(0, at)}\t${head}\n${code.slice(at)}`;
+    }
+    return `${scriptTag}\n\t${head}\n</script>\n\n${code}`;
+}
+/**
+ * A file that already binds `t` (an i18n library, a custom helper) is agent
+ * work: the dogfood proved rewiring foreign t() calls breaks rendering.
+ */
+function bindsForeignT(code) {
+    return (/\buseI18n\s*\(/.test(code) ||
+        /(?:const|let|var)\s+t\s*=/.test(code) ||
+        /import\s*\{[^}]*\bt\b[^}]*\}\s*from/.test(code));
+}
+function previewPattern(preview) {
+    const core = preview
+        .replace(/…$/, '')
+        .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        .replace(/\\? /g, '\\s+');
+    return new RegExp(`>(\\s*)(${core}[^<{]*?)(\\s*)<`);
+}
+export function applyTemplateWrapToFile(code, style, items, allocator) {
+    const applied = [];
+    const skipped = [];
+    const labels = {};
+    const hasHead = style.headMarker.test(code);
+    if (!hasHead && bindsForeignT(code)) {
+        return {
+            code,
+            applied,
+            skipped: items.map((item) => ({ item, reason: 'file binds its own t() — agent work' })),
+            labels,
+        };
+    }
+    if (!hasHead && style.injectHead(code, style.head) === null) {
+        return {
+            code,
+            applied,
+            skipped: items.map((item) => ({ item, reason: 'no safe wiring point in this file — agent work' })),
+            labels,
+        };
+    }
+    const file = items[0]?.file ?? '';
+    const scope = style.fileScope?.(file) ?? slugify(basename(file).replace(/\.[a-z0-9]+$/i, '')) ?? 'shared';
+    let next = code;
+    for (const item of items) {
+        if (item.kind !== 'text') {
+            skipped.push({ item, reason: `${item.kind} stays agent work` });
+            continue;
+        }
+        const match = next.match(previewPattern(item.preview));
+        if (!match || match.index === undefined) {
+            skipped.push({ item, reason: 'text node not matched in source — agent work' });
+            continue;
+        }
+        const collapsed = match[2].replace(/\s+/g, ' ').trim();
+        const value = decodeJsxEntities(collapsed);
+        const id = allocator.allocate(scope || 'shared', slugify(value), value);
+        const escaped = collapsed.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+        const replacement = `>${match[1]}${style.open}"${id}", "${escaped}"${style.close}${match[3]}<`;
+        next = next.slice(0, match.index) + replacement + next.slice(match.index + match[0].length);
+        labels[id] = value;
+        applied.push({ kind: 'text', file: item.file, line: item.line, id, preview: item.preview });
+    }
+    if (applied.length > 0 && !style.headMarker.test(next)) {
+        next = style.injectHead(next, style.head) ?? next;
+    }
+    return { code: next, applied, skipped, labels };
+}
+/**
+ * Apply the template wraps across a project — same contract as applyWrap:
+ * scans, mutates source files, returns the generated labels for staging and
+ * seeding. The style's ensureWiring hook then writes any one-time project
+ * wiring (e.g. a root layout labels loader) when files were wrapped.
+ */
+export function applyTemplateWrap(rootDir, opts) {
+    const { style } = opts;
+    const scan = scanWrappable(rootDir, { excludePrefixes: opts.excludePrefixes });
+    const existingLabels = (() => {
+        try {
+            return JSON.parse(readFileSync(join(rootDir, '.fimo', 'migration', 'labels.json'), 'utf8'));
+        }
+        catch {
+            return {};
+        }
+    })();
+    // Honor recorded exemptions — same contract as the JSX codemod: --apply
+    // must never wrap an item the user deliberately kept out.
+    const exemptions = readApplyExemptions(rootDir);
+    const isExempt = (item) => exemptions.some((exemption) => exemption.file === item.file && exemption.kind === item.kind && exemption.preview === item.preview);
+    const allocator = new KeyAllocator([...Object.keys(existingLabels), ...scan.wrappedIds.labels], reusableStagedLabels(existingLabels, scan.wrappedIds.labels));
+    const result = { applied: [], skipped: [], labels: {}, filesChanged: [] };
+    const byFile = new Map();
+    for (const item of scan.items) {
+        if (!item.file.endsWith(style.ext) || isExempt(item)) {
+            continue;
+        }
+        const list = byFile.get(item.file) ?? [];
+        list.push(item);
+        byFile.set(item.file, list);
+    }
+    for (const [file, items] of byFile) {
+        const filePath = join(rootDir, file);
+        let code;
+        try {
+            code = readFileSync(filePath, 'utf8');
+        }
+        catch {
+            result.skipped.push(...items.map((item) => ({ item, reason: 'unreadable file' })));
+            continue;
+        }
+        const fileResult = applyTemplateWrapToFile(code, style, items, allocator);
+        result.applied.push(...fileResult.applied);
+        result.skipped.push(...fileResult.skipped);
+        Object.assign(result.labels, fileResult.labels);
+        if (fileResult.applied.length > 0) {
+            writeFileSync(filePath, fileResult.code);
+            result.filesChanged.push(file);
+        }
+    }
+    if (result.filesChanged.length > 0 && style.ensureWiring) {
+        result.filesChanged.push(...style.ensureWiring(rootDir));
+    }
+    return result;
+}