fimo 0.8.0 → 0.9.0-experimental.1

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

@@ -0,0 +1,132 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { decodeJsxEntities, KeyAllocator, 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 id = allocator.allocate(scope || 'shared', slugify(collapsed));
+        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] = decodeJsxEntities(collapsed);
+        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 {};
+        }
+    })();
+    const allocator = new KeyAllocator([...Object.keys(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)) {
+            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;
+}

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

@@ -0,0 +1,46 @@
+import { type WrappableItem } from './scan-wrappable.js';
+export interface AppliedTransform {
+    kind: 'text' | 'image' | 'file-link';
+    file: string;
+    line: number;
+    id: string;
+    preview: string;
+}
+export interface ApplyWrapResult {
+    applied: AppliedTransform[];
+    skipped: Array<{
+        item: WrappableItem;
+        reason: string;
+    }>;
+    labels: Record<string, string>;
+    filesChanged: string[];
+}
+export declare function decodeJsxEntities(text: string): string;
+/** Deterministic scope from the file path: app/about/page.tsx -> about. */
+export declare function keyScope(file: string): string;
+export declare function slugify(text: string): string;
+export declare class KeyAllocator {
+    private readonly used;
+    constructor(existing: Iterable<string>);
+    allocate(scope: string, slug: string): string;
+}
+/**
+ * Merge the fimo/next import with an existing one, or insert a new one AFTER
+ * the last import statement — positioned via the AST, never line matching
+ * (a multiline `import {\n …` opening line is not the end of the imports,
+ * as a real portfolio migration proved).
+ */
+export declare function ensureFimoImport(code: string, specifiers: string[], importModule?: string): string;
+export declare function applyWrapToFile(code: string, items: WrappableItem[], allocator: KeyAllocator, importModule?: string): {
+    code: string;
+    applied: AppliedTransform[];
+    skipped: Array<{
+        item: WrappableItem;
+        reason: string;
+    }>;
+    labels: Record<string, string>;
+};
+export declare function applyWrap(rootDir: string, opts?: {
+    excludePrefixes?: string[];
+    importModule?: string;
+}): ApplyWrapResult;

package/dist/scripts/apply-wrap.js

@@ -0,0 +1,278 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { parseSync } from 'oxc-parser';
+import { scanWrappable } from './scan-wrappable.js';
+/**
+ * The --apply codemod: performs the PROVABLY-SAFE wrap transforms
+ * deterministically, leaving every judgment call to the agent.
+ *
+ * In scope:  plain JSX text -> FimoText, <img src="literal"> -> FimoMediaImage,
+ *            <a href="/file.pdf"> -> FimoFileLink.
+ * Out of scope (agent work): attributes (useLabels crosses the RSC boundary),
+ *            formatted text (marks -> FimoRichTextBlock), next/image <Image>
+ *            (framework-specific props), collections, layout wiring.
+ *
+ * Correctness is enforced by the gates, not assumed: the render-parity
+ * baseline is captured BEFORE applying, and `fimo migrate wrap --check`
+ * verifies the result like any other actor's work.
+ */
+/** Elements whose children cannot contain a <span> wrapper. */
+const NO_ELEMENT_CHILDREN = new Set(['option', 'title', 'textarea', 'script', 'style', 'select']);
+function collapse(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+// JSX text carries HTML entities (&apos;, &amp;, …). The FALLBACK keeps the
+// original source form, but the label VALUE is rendered literally by
+// FimoText — seeding the raw entity re-escapes it on screen (the remix
+// dogfood shipped "What&apos;s next?"). Decode when generating values.
+const JSX_ENTITIES = {
+    '&amp;': '&',
+    '&lt;': '<',
+    '&gt;': '>',
+    '&quot;': '"',
+    '&apos;': "'",
+    '&nbsp;': ' ',
+    '&copy;': '©',
+};
+export function decodeJsxEntities(text) {
+    return text
+        .replace(/&(amp|lt|gt|quot|apos|nbsp|copy);/g, (entity) => JSX_ENTITIES[entity] ?? entity)
+        .replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)))
+        .replace(/&#x([0-9a-f]+);/gi, (_, code) => String.fromCodePoint(parseInt(code, 16)));
+}
+/** Deterministic scope from the file path: app/about/page.tsx -> about. */
+export function keyScope(file) {
+    const normalized = file.replace(/\\/g, '/');
+    const appMatch = normalized.match(/(?:^|\/)app\/(.*)\/?page\.[jt]sx?$/);
+    if (appMatch) {
+        const dir = appMatch[1].replace(/\/$/, '');
+        if (!dir) {
+            return 'home';
+        }
+        const segments = dir
+            .split('/')
+            .filter((segment) => !segment.startsWith('(') && !segment.startsWith('@'))
+            .map((segment) => segment.replace(/^\[+|\]+$/g, '').replace(/^\.\.\./, ''));
+        return segments.join('.') || 'home';
+    }
+    if (/(?:^|\/)app\/layout\.[jt]sx?$/.test(normalized)) {
+        return 'layout';
+    }
+    const stem = basename(normalized).replace(/\.[jt]sx?$/, '');
+    return slugify(stem) || 'shared';
+}
+export function slugify(text) {
+    return collapse(text)
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/[̀-ͯ]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .split('-')
+        .slice(0, 4)
+        .join('-');
+}
+export class KeyAllocator {
+    used = new Set();
+    constructor(existing) {
+        for (const key of existing) {
+            this.used.add(key);
+        }
+    }
+    allocate(scope, slug) {
+        const base = `${scope}.${slug || 'item'}`;
+        let candidate = base;
+        let counter = 2;
+        while (this.used.has(candidate)) {
+            candidate = `${base}-${counter++}`;
+        }
+        this.used.add(candidate);
+        return candidate;
+    }
+}
+/**
+ * Merge the fimo/next import with an existing one, or insert a new one AFTER
+ * the last import statement — positioned via the AST, never line matching
+ * (a multiline `import {\n …` opening line is not the end of the imports,
+ * as a real portfolio migration proved).
+ */
+export function ensureFimoImport(code, specifiers, importModule = 'fimo/next') {
+    if (specifiers.length === 0) {
+        return code;
+    }
+    const moduleRe = importModule.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+    const importMatch = code.match(new RegExp(`import\\s*\\{([^}]*)\\}\\s*from\\s*(['\"])${moduleRe}\\2\\s*;?`));
+    if (importMatch) {
+        const existing = importMatch[1]
+            .split(',')
+            .map((token) => token.trim())
+            .filter(Boolean);
+        const merged = [...new Set([...existing, ...specifiers])].sort();
+        return code.replace(importMatch[0], `import { ${merged.join(', ')} } from "${importModule}";`);
+    }
+    const statement = `import { ${[...new Set(specifiers)].sort().join(', ')} } from "${importModule}";`;
+    let insertAt = 0;
+    try {
+        const program = parseSync('module.tsx', code).program;
+        for (const node of program.body ?? []) {
+            if (node.type === 'ImportDeclaration') {
+                insertAt = node.end;
+            }
+        }
+    }
+    catch {
+        insertAt = 0;
+    }
+    if (insertAt === 0) {
+        return `${statement}\n${code}`;
+    }
+    return `${code.slice(0, insertAt)}\n${statement}${code.slice(insertAt)}`;
+}
+export function applyWrapToFile(code, items, allocator, importModule = 'fimo/next') {
+    const applied = [];
+    const skipped = [];
+    const labels = {};
+    const edits = [];
+    const specifiers = new Set();
+    for (const item of items) {
+        const span = item.span;
+        if (!span) {
+            skipped.push({ item, reason: 'no span info' });
+            continue;
+        }
+        const scope = keyScope(item.file);
+        if (item.kind === 'text') {
+            if (span.parentTag && NO_ELEMENT_CHILDREN.has(span.parentTag.toLowerCase())) {
+                skipped.push({ item, reason: `<${span.parentTag}> cannot contain a wrapper element` });
+                continue;
+            }
+            const raw = code.slice(span.start, span.end);
+            const core = raw.trim();
+            if (!core) {
+                skipped.push({ item, reason: 'whitespace only' });
+                continue;
+            }
+            const lead = raw.slice(0, raw.indexOf(core));
+            const trail = raw.slice(raw.indexOf(core) + core.length);
+            const id = allocator.allocate(scope, slugify(core));
+            edits.push({
+                start: span.start,
+                end: span.end,
+                replacement: `${lead}<FimoText id="${id}">${core}</FimoText>${trail}`,
+            });
+            specifiers.add('FimoText');
+            labels[id] = decodeJsxEntities(collapse(core));
+            applied.push({ kind: 'text', file: item.file, line: item.line, id, preview: item.preview });
+            continue;
+        }
+        if (item.kind === 'image') {
+            if (span.openNameStart === undefined ||
+                span.openNameEnd === undefined ||
+                code.slice(span.openNameStart, span.openNameEnd) !== 'img') {
+                skipped.push({ item, reason: 'next/image and custom components stay agent work' });
+                continue;
+            }
+            const id = allocator.allocate(scope, slugify(basename(item.preview).replace(/\.[a-z0-9]+$/i, '')));
+            edits.push({
+                start: span.openNameStart,
+                end: span.openNameEnd,
+                replacement: `FimoMediaImage id="${id}"`,
+            });
+            specifiers.add('FimoMediaImage');
+            applied.push({ kind: 'image', file: item.file, line: item.line, id, preview: item.preview });
+            continue;
+        }
+        if (item.kind === 'file-link') {
+            if (span.openNameStart === undefined ||
+                span.openNameEnd === undefined ||
+                span.closeNameStart === undefined ||
+                span.closeNameEnd === undefined) {
+                skipped.push({ item, reason: 'self-closing or unparsable anchor' });
+                continue;
+            }
+            const id = allocator.allocate(scope, slugify(basename(item.preview).replace(/\.[a-z0-9]+$/i, '')));
+            edits.push({ start: span.openNameStart, end: span.openNameEnd, replacement: `FimoFileLink id="${id}"` });
+            edits.push({ start: span.closeNameStart, end: span.closeNameEnd, replacement: 'FimoFileLink' });
+            specifiers.add('FimoFileLink');
+            applied.push({ kind: 'file-link', file: item.file, line: item.line, id, preview: item.preview });
+            continue;
+        }
+        skipped.push({ item, reason: `${item.kind} stays agent work` });
+    }
+    let next = code;
+    for (const edit of edits.sort((a, b) => b.start - a.start)) {
+        next = next.slice(0, edit.start) + edit.replacement + next.slice(edit.end);
+    }
+    next = ensureFimoImport(next, [...specifiers], importModule);
+    return { code: next, applied, skipped, labels };
+}
+/**
+ * Apply the safe transforms across the project. Mutates source files and
+ * merges generated labels into `.fimo/migration/labels.json` (never
+ * overwriting existing keys).
+ */
+/** Recorded coverage exemptions the codemod must NOT wrap — items the user
+ *  deliberately kept out (dev-only UI, OG-image markup, …). Matched by the
+ *  same (file, kind, preview) triple the coverage gate uses, so "record the
+ *  exemption first, then --apply auto-wraps the rest" holds. */
+function readApplyExemptions(rootDir) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(rootDir, '.fimo', 'migration', 'manifest.json'), 'utf8'));
+        const raw = manifest?.wrap?.exemptions;
+        return Array.isArray(raw)
+            ? raw.filter((entry) => typeof entry?.file === 'string' &&
+                typeof entry?.kind === 'string' &&
+                typeof entry?.preview === 'string')
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function applyWrap(rootDir, 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: the codemod skips them so the coverage gate's
+    // exemption and the codemod stay consistent — otherwise --apply would wrap
+    // an item the user just exempted and the gate would flag the drift.
+    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]);
+    const byFile = new Map();
+    for (const item of scan.items) {
+        if (isExempt(item)) {
+            continue;
+        }
+        const list = byFile.get(item.file) ?? [];
+        list.push(item);
+        byFile.set(item.file, list);
+    }
+    const result = { applied: [], skipped: [], labels: {}, filesChanged: [] };
+    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 = applyWrapToFile(code, items, allocator, opts.importModule ?? 'fimo/next');
+        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);
+        }
+    }
+    return result;
+}

package/dist/scripts/cms/discover.d.ts

@@ -0,0 +1,2 @@
+import type { CmsConnector } from './types.js';
+export declare function detectCms(frontendDir: string): CmsConnector | null;

package/dist/scripts/cms/discover.js

@@ -0,0 +1,17 @@
+import { strapiConnector } from './strapi/index.js';
+/**
+ * CMS-connector registry. Add a connector factory here to support a new
+ * headless CMS; each returns its `CmsConnector` when it recognizes the
+ * frontend, or null. First match wins. This is the ONLY CMS-neutral file that
+ * enumerates the supported CMSs (the analogue of `frameworks/discover.ts`).
+ */
+const CONNECTORS = [strapiConnector];
+export function detectCms(frontendDir) {
+    for (const factory of CONNECTORS) {
+        const connector = factory(frontendDir);
+        if (connector) {
+            return connector;
+        }
+    }
+    return null;
+}

package/dist/scripts/cms/example-content.d.ts

@@ -0,0 +1,33 @@
+import type { CmsCollectionSchema } from './types.js';
+/**
+ * Generate example content for a CMS schema WITHOUT connecting to the CMS. The
+ * shapes match `api.importEntries`: media fields get a self-contained
+ * placeholder, references point at the first example of the target type
+ * (`<target>-example-1`) so they resolve against the co-seeded data, blocks
+ * (components / dynamic zones) get a filled array so page-builder pages render
+ * instead of showing empty, and localized types get per-locale string variance
+ * so the per-language editability is visible in Fimo. This is CMS-neutral: it
+ * consumes the mapped Fimo schema only.
+ */
+export interface ExampleSeed {
+    /** Fimo type name. */
+    readonly name: string;
+    readonly isSingleton: boolean;
+    readonly localized: boolean;
+    /** Entry data rows (slug lives inside data for collections). */
+    readonly rows: Array<Record<string, unknown>>;
+    /** Reference descriptor for `importEntries`. */
+    readonly references: Record<string, {
+        target?: string;
+        targets?: string[];
+        by: 'slug';
+        many?: boolean;
+    }>;
+}
+export interface ExampleOptions {
+    /** Rows per collection type (singletons always get exactly one). */
+    readonly count?: number;
+    /** Locale suffix on string values + the batch locale (for localized types). */
+    readonly locale?: string;
+}
+export declare function generateExampleSeed(schema: CmsCollectionSchema, options?: ExampleOptions): ExampleSeed;

package/dist/scripts/cms/example-content.js

@@ -0,0 +1,162 @@
+const DEFAULT_COUNT = 3;
+/** Variants seeded per dynamic-zone (`oneOf`) field — a representative page, not
+ *  all N components. Real content (the pull) exercises the rest. */
+const EXAMPLE_BLOCK_VARIANTS = 5;
+/** Items seeded for a repeatable fixed-shape block. */
+const EXAMPLE_REPEATABLE_ITEMS = 2;
+/** Recursion cap for nested blocks — the schema is already depth-bounded; this
+ *  keeps generation finite even for pathological nesting. */
+const MAX_FILL_DEPTH = 3;
+function kebabCase(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .toLowerCase()
+        .replace(/^-+|-+$/g, '');
+}
+function humanize(field) {
+    return field
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .replace(/^\w/, (c) => c.toUpperCase());
+}
+function richTextDoc(text) {
+    return {
+        type: 'doc',
+        content: [{ type: 'paragraph', content: [{ type: 'text', text }] }],
+    };
+}
+/** A self-contained placeholder image (inline SVG data-URI) in the media
+ *  envelope shape the wrap runtime already understands — no external host, no
+ *  CSP surprises, so cards/heroes render instead of showing broken images. */
+function placeholderMedia(label) {
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630"><rect width="100%" height="100%" fill="#e5e7eb"/><text x="50%" y="50%" font-family="sans-serif" font-size="44" fill="#9ca3af" text-anchor="middle" dominant-baseline="middle">${label}</text></svg>`;
+    return {
+        source: 'local',
+        url: `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`,
+        alt: `${label} placeholder`,
+        width: 1200,
+        height: 630,
+        mime: 'image/svg+xml',
+        name: 'placeholder.svg',
+    };
+}
+/** Deterministic ISO date (no wall clock): 2024-01-01 + (n-1) days. */
+function exampleDate(n) {
+    return new Date(Date.UTC(2024, 0, n)).toISOString().slice(0, 10);
+}
+function exampleReferenceSlug(field) {
+    const targetName = field.target ?? field.targets?.[0];
+    if (!targetName) {
+        return undefined;
+    }
+    const slug = `${kebabCase(targetName)}-example-1`;
+    return field.many ? [slug] : slug;
+}
+/**
+ * Fill a NON-reference field value from its Fimo def (scalars, blocks, and any
+ * baked default such as a block variant's `__component` discriminator).
+ * Reference fields return `undefined` here: the top-level pass owns them, and
+ * server-side slug resolution does not reach references nested inside blocks.
+ */
+function fillFieldValue(field, def, ctx) {
+    const baked = def.default;
+    if (baked !== undefined) {
+        return baked;
+    }
+    switch (def.type) {
+        case 'string':
+            return `${humanize(field)} example ${ctx.index}${ctx.localeSuffix}`;
+        case 'richtext':
+            return richTextDoc(`Example ${humanize(ctx.schemaName).toLowerCase()} content ${ctx.index}${ctx.localeSuffix}.`);
+        case 'number':
+            return ctx.index;
+        case 'boolean':
+            return ctx.index % 2 === 1;
+        case 'date':
+            return exampleDate(ctx.index);
+        case 'json':
+            return {};
+        case 'media':
+            return placeholderMedia(humanize(field));
+        case 'blocks':
+            return fillBlocks(def, ctx);
+        default:
+            // reference (nested) — omitted; the frontend accesses relations defensively.
+            return undefined;
+    }
+}
+/**
+ * Fill a blocks value — always an array so page builders can `.map()` it. A
+ * dynamic zone (`oneOf`) seeds one item per variant (representative subset,
+ * each tagged with its `_type` discriminator); a fixed component (`fields`)
+ * seeds one item (single) or a few (repeatable).
+ */
+function fillBlocks(def, ctx) {
+    if (ctx.depth >= MAX_FILL_DEPTH) {
+        return [];
+    }
+    const childCtx = { ...ctx, depth: ctx.depth + 1 };
+    const schema = def.schema;
+    if ('oneOf' in schema) {
+        return schema.oneOf.slice(0, EXAMPLE_BLOCK_VARIANTS).map((variant) => ({
+            _type: variant.uid,
+            ...fillItem(variant.fields, childCtx),
+        }));
+    }
+    const itemCount = def.max === 1 ? 1 : EXAMPLE_REPEATABLE_ITEMS;
+    return Array.from({ length: itemCount }, () => fillItem(schema.fields, childCtx));
+}
+/** Fill every non-reference field of a block item. */
+function fillItem(fields, ctx) {
+    const item = {};
+    for (const [name, def] of Object.entries(fields)) {
+        const value = fillFieldValue(name, def, ctx);
+        if (value !== undefined) {
+            item[name] = value;
+        }
+    }
+    return item;
+}
+export function generateExampleSeed(schema, options = {}) {
+    const locale = options.locale;
+    const localeSuffix = locale ? ` (${locale})` : '';
+    const count = schema.isSingleton ? 1 : Math.max(1, options.count ?? DEFAULT_COUNT);
+    const references = {};
+    const rows = [];
+    for (let i = 1; i <= count; i += 1) {
+        const row = {};
+        if (!schema.isSingleton) {
+            row.slug = `${kebabCase(schema.name)}-example-${i}`;
+        }
+        for (const [field, def] of Object.entries(schema.fields)) {
+            // A connector-supplied example (dynamic zones, components) wins over the
+            // type-driven default — critical for dynamic zones, which must be arrays.
+            if (schema.examples && field in schema.examples) {
+                row[field] = schema.examples[field];
+                continue;
+            }
+            // References are top-level only: record the descriptor so the import
+            // endpoint resolves the slug to a documentId server-side.
+            if (def.type === 'reference') {
+                const value = exampleReferenceSlug(def);
+                if (value !== undefined) {
+                    row[field] = value;
+                    references[field] = {
+                        ...(def.target ? { target: def.target } : {}),
+                        ...(def.targets ? { targets: def.targets } : {}),
+                        by: 'slug',
+                        ...(def.many ? { many: true } : {}),
+                    };
+                }
+                continue;
+            }
+            const value = fillFieldValue(field, def, { localeSuffix, index: i, schemaName: schema.name, depth: 0 });
+            if (value !== undefined) {
+                row[field] = value;
+            }
+        }
+        rows.push(row);
+    }
+    return { name: schema.name, isSingleton: schema.isSingleton, localized: schema.localized, rows, references };
+}

package/dist/scripts/cms/strapi/detect.d.ts

@@ -0,0 +1,2 @@
+import type { CmsDetection } from '../types.js';
+export declare function detectStrapi(frontendDir: string): CmsDetection | null;