fimo 0.8.0 → 0.9.0-experimental.2

package/dist/runtime/wrapped/FimoText.js

@@ -0,0 +1,20 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Text } from '../primitives/components/Text.js';
+import { useLabels } from '../primitives/labels-hook.js';
+/**
+ * Wraps a hardcoded string so it becomes editable in Fimo. The original
+ * string stays in code as the fallback:
+ *
+ *   <h1><FimoText id="home.hero.title">Ship your site in hours</FimoText></h1>
+ *
+ * For attribute strings use the two-argument label function instead:
+ *
+ *   const { t } = useLabels();
+ *   <input placeholder={String(t('home.newsletter.placeholder', 'Your work email'))} />
+ */
+export function FimoText({ id, children, as, ...props }) {
+    const { t } = useLabels();
+    const textProps = { value: t(id, children), as, ...props };
+    return _jsx(Text, { ...textProps });
+}

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

@@ -0,0 +1,28 @@
+import React from 'react';
+import { FIMO_SOURCE, FimoMedia, type FimoRichTextContent } from '../primitives/lib/index.js';
+export interface WrappedMediaEntry {
+    url: string;
+    alt?: string;
+    name?: string;
+    mime?: string;
+    width?: number;
+    height?: number;
+    /** data-fimo-source path, e.g. `WrappedMedia.<entryId>.image` */
+    source: string;
+}
+export interface WrappedRichTextEntry {
+    content: FimoRichTextContent;
+    /** data-fimo-source path, e.g. `WrappedRichText.<entryId>.body` */
+    source: string;
+}
+export interface WrappedContentValue {
+    media: Record<string, WrappedMediaEntry>;
+    richText: Record<string, WrappedRichTextEntry>;
+}
+export declare function WrappedContentProvider({ media, richText, children, }: Partial<WrappedContentValue> & {
+    children?: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useWrappedMedia(id: string): FimoMedia | null;
+export declare function useWrappedRichText(id: string): WrappedRichTextEntry | null;
+export { FIMO_SOURCE };
+//# sourceMappingURL=WrappedContentContext.d.ts.map

package/dist/runtime/wrapped/WrappedContentContext.js

@@ -0,0 +1,30 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from 'react';
+import { FIMO_SOURCE, FimoMedia } from '../primitives/lib/index.js';
+const emptyValue = { media: {}, richText: {} };
+const WrappedContentContext = createContext(emptyValue);
+export function WrappedContentProvider({ media, richText, children, }) {
+    const value = useMemo(() => ({ media: media ?? {}, richText: richText ?? {} }), [media, richText]);
+    return _jsx(WrappedContentContext.Provider, { value: value, children: children });
+}
+export function useWrappedMedia(id) {
+    const { media } = useContext(WrappedContentContext);
+    const entry = media[id];
+    if (!entry) {
+        return null;
+    }
+    return new FimoMedia({
+        url: entry.url,
+        alt: entry.alt ?? '',
+        name: entry.name ?? id,
+        mime: entry.mime ?? '',
+        width: entry.width,
+        height: entry.height,
+    }, entry.source);
+}
+export function useWrappedRichText(id) {
+    const { richText } = useContext(WrappedContentContext);
+    return richText[id] ?? null;
+}
+export { FIMO_SOURCE };

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

@@ -0,0 +1,33 @@
+import React from 'react';
+import type { FimoConfig } from '../shared/fimo-config.types.js';
+import { type WrappedMediaEntry, type WrappedRichTextEntry } from './WrappedContentContext.js';
+export interface WrappedLabels {
+    dictionaries: Record<string, Record<string, string>>;
+    defaultLocale: string;
+    locales?: string[];
+    updatedAt?: string | null;
+    signature: string;
+}
+/** Framework navigation adapter: the ONLY thing an adapter must supply. */
+export interface WrappedNavigation {
+    pathname: string | null;
+    navigate: (to: string) => void;
+}
+export interface WrappedProvidersProps {
+    config: FimoConfig;
+    labels?: WrappedLabels;
+    media?: Record<string, WrappedMediaEntry>;
+    richText?: Record<string, WrappedRichTextEntry>;
+    locale?: string;
+    navigation: WrappedNavigation;
+    children?: React.ReactNode;
+}
+/**
+ * Framework-neutral providers for WRAPPED (adopted) apps. Adapters
+ * (fimo/next, fimo/remix, ...) supply only the navigation hooks; everything
+ * else — label hydration, locale resolution, preview bridge, error boundary —
+ * is shared. Content arrives as serializable props from the wrapped server
+ * loaders.
+ */
+export declare function WrappedProviders({ config, labels, media, richText, locale, navigation, children }: WrappedProvidersProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=WrappedProviders.d.ts.map

package/dist/runtime/wrapped/WrappedProviders.js

@@ -0,0 +1,101 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { Suspense, useCallback, useEffect, useMemo, useState } from 'react';
+import { ErrorBoundary } from 'react-error-boundary';
+import { DataSourcesProvider } from '../content/DataSourcesProvider.js';
+import { AppErrorBoundary, onError } from '../core/AppErrorBoundary.js';
+import { FimoLocaleProvider } from '../i18n/FimoLocaleContext.js';
+import { getFimoTextDirection, resolveFimoLocale, toHtmlLang } from '../i18n/locale.js';
+import { ScreenshotProvider } from '../iframe/ScreenshotProvider.js';
+import { hydrateLabels } from '../primitives/labels-store.js';
+import { getDisplayRoutes } from '../shared/display-routes.js';
+import { WrappedContentProvider } from './WrappedContentContext.js';
+function toLabelState(labels) {
+    return {
+        dictionaries: labels.dictionaries,
+        defaultLocale: labels.defaultLocale,
+        signature: labels.signature,
+        updatedAt: labels.updatedAt ?? null,
+    };
+}
+function PreviewBridge({ config, navigation }) {
+    const { pathname, navigate } = navigation;
+    const localeResolution = useMemo(() => resolveFimoLocale({ pathname: pathname ?? undefined }, config), [pathname, config]);
+    const sendRoutes = useCallback(() => {
+        window.parent.postMessage({ type: 'nav/routes', payload: { routes: getDisplayRoutes(config) } }, '*');
+    }, [config]);
+    const sendLocationChange = useCallback(() => {
+        window.parent.postMessage({
+            type: 'nav/locationChange',
+            payload: {
+                path: pathname,
+                routePath: localeResolution.routePath,
+                locale: localeResolution.locale,
+            },
+        }, '*');
+    }, [pathname, localeResolution.locale, localeResolution.routePath]);
+    useEffect(sendRoutes, [sendRoutes]);
+    useEffect(sendLocationChange, [sendLocationChange]);
+    useEffect(() => {
+        const handleMessage = (event) => {
+            const type = event.data?.type;
+            const payload = event.data?.payload;
+            switch (type) {
+                case 'nav/navigate':
+                    if (payload?.to) {
+                        navigate(payload.to);
+                    }
+                    return;
+                case 'nav/read-routes':
+                    sendRoutes();
+                    sendLocationChange();
+                    return;
+            }
+        };
+        window.addEventListener('message', handleMessage);
+        return () => {
+            window.removeEventListener('message', handleMessage);
+        };
+    }, [navigate, sendRoutes, sendLocationChange]);
+    return null;
+}
+/**
+ * Framework-neutral providers for WRAPPED (adopted) apps. Adapters
+ * (fimo/next, fimo/remix, ...) supply only the navigation hooks; everything
+ * else — label hydration, locale resolution, preview bridge, error boundary —
+ * is shared. Content arrives as serializable props from the wrapped server
+ * loaders.
+ */
+export function WrappedProviders({ config, labels, media, richText, locale, navigation, children }) {
+    // Wrapped apps have no QueryClientProvider of their own; ScreenshotProvider
+    // (and future data-refresh machinery) need one, so the adapter owns it.
+    const [queryClient] = useState(() => new QueryClient());
+    useState(() => {
+        if (labels) {
+            hydrateLabels(toLabelState(labels));
+        }
+        return null;
+    });
+    useEffect(() => {
+        if (labels) {
+            hydrateLabels(toLabelState(labels));
+        }
+    }, [labels]);
+    const pathname = navigation.pathname;
+    const localeResolution = useMemo(() => resolveFimoLocale({ pathname: pathname ?? undefined }, config), [pathname, config]);
+    const activeLocale = locale ?? localeResolution.locale;
+    const activeDir = getFimoTextDirection(activeLocale);
+    useEffect(() => {
+        if (typeof document === 'undefined') {
+            return;
+        }
+        document.documentElement.lang = toHtmlLang(activeLocale);
+        document.documentElement.dir = activeDir;
+    }, [activeDir, activeLocale]);
+    return (_jsx(ErrorBoundary, { FallbackComponent: AppErrorBoundary, onError: onError, children: _jsx(QueryClientProvider, { client: queryClient, children: _jsx(FimoLocaleProvider, { value: {
+                    ...localeResolution,
+                    locale: activeLocale,
+                    dir: activeDir,
+                }, children: _jsx(WrappedContentProvider, { media: media, richText: richText, children: _jsx(DataSourcesProvider, { children: _jsxs(ScreenshotProvider, { children: [_jsx(PreviewBridge, { config: config, navigation: navigation }), _jsx(Suspense, { children: children })] }) }) }) }) }) }));
+}

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,77 @@
+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.
+ */
+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).
+ */
+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,237 @@
+// 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';
+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 [];
+    }
+}
+function readString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function readNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * 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.
+ */
+export async function loadWrappedMedia(options = {}) {
+    const entries = await fetchEntries('WrappedMedia', options);
+    const map = {};
+    for (const entry of entries) {
+        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;
+}
+/**
+ * Load the WrappedRichText entries (key → TipTap JSON) seeded by the wrap
+ * migration for formatted text (bold/italic/underline/links).
+ */
+export async function loadWrappedRichText(options = {}) {
+    const entries = await fetchEntries('WrappedRichText', options);
+    const map = {};
+    for (const entry of entries) {
+        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;
+}
+/** 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;