fimo 0.8.0 → 0.9.0-experimental.10

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

@@ -0,0 +1,73 @@
+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;
+/** Conservative markdown detection: bold pairs, inline code, links, and a
+ *  leading heading marker — not lone `*`/`[` characters in ordinary copy. */
+export declare function looksLikeMarkdown(text: string): boolean;
+/** 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;
+    private readonly reusable;
+    /**
+     * `reusable` maps staged keys that no longer appear in code (a wrap the
+     * user reverted) to their staged value: re-applying the codemod over the
+     * same text reclaims the ORIGINAL key instead of minting a `-N` duplicate
+     * that orphans the old label (and its seeded row).
+     */
+    constructor(existing: Iterable<string>, reusable?: ReadonlyMap<string, string>);
+    allocate(scope: string, slug: string, value?: string): string;
+}
+/** Staged keys absent from the current code scan, with their staged values —
+ *  the KeyAllocator's reuse pool. */
+export declare function reusableStagedLabels(existingLabels: Record<string, string>, wrappedInCode: Iterable<string>): Map<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>;
+};
+/**
+ * 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. */
+export declare function readApplyExemptions(rootDir: string): Array<{
+    file: string;
+    kind: string;
+    preview: string;
+}>;
+export declare function applyWrap(rootDir: string, opts?: {
+    excludePrefixes?: string[];
+    importModule?: string;
+}): ApplyWrapResult;

package/dist/scripts/apply-wrap.js

@@ -0,0 +1,340 @@
+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;': '©',
+    '&reg;': '®',
+    '&trade;': '™',
+    '&deg;': '°',
+    '&middot;': '·',
+    '&bull;': '•',
+    '&hellip;': '…',
+    '&mdash;': '—',
+    '&ndash;': '–',
+    '&lsquo;': '‘',
+    '&rsquo;': '’',
+    '&ldquo;': '“',
+    '&rdquo;': '”',
+    '&laquo;': '«',
+    '&raquo;': '»',
+    '&times;': '×',
+    '&rarr;': '→',
+    '&larr;': '←',
+};
+export function decodeJsxEntities(text) {
+    return text
+        .replace(/&(amp|lt|gt|quot|apos|nbsp|copy|reg|trade|deg|middot|bull|hellip|mdash|ndash|lsquo|rsquo|ldquo|rdquo|laquo|raquo|times|rarr|larr);/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)));
+}
+const MARKDOWN_SYNTAX = [/\*\*[^*]+\*\*/, /(?<!`)`[^`]+`/, /\[[^\]]+\]\([^)]+\)/, /^#{1,6}\s/];
+/** Conservative markdown detection: bold pairs, inline code, links, and a
+ *  leading heading marker — not lone `*`/`[` characters in ordinary copy. */
+export function looksLikeMarkdown(text) {
+    return MARKDOWN_SYNTAX.some((pattern) => pattern.test(text));
+}
+/** 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) {
+    // camelCase boundaries become segments BEFORE lowercasing, so component
+    // file names keep their word structure (AgentStrip.tsx → agent-strip.*)
+    // and every humanized display of the key reads like the component name.
+    return collapse(text)
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/[̀-ͯ]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .split('-')
+        .slice(0, 4)
+        .join('-');
+}
+export class KeyAllocator {
+    used = new Set();
+    reusable = new Map();
+    /**
+     * `reusable` maps staged keys that no longer appear in code (a wrap the
+     * user reverted) to their staged value: re-applying the codemod over the
+     * same text reclaims the ORIGINAL key instead of minting a `-N` duplicate
+     * that orphans the old label (and its seeded row).
+     */
+    constructor(existing, reusable) {
+        for (const key of existing) {
+            this.used.add(key);
+        }
+        if (reusable) {
+            for (const [key, value] of reusable) {
+                this.reusable.set(key, value);
+            }
+        }
+    }
+    allocate(scope, slug, value) {
+        const base = `${scope}.${slug || 'item'}`;
+        let candidate = base;
+        let counter = 2;
+        while (this.used.has(candidate)) {
+            if (value !== undefined && this.reusable.get(candidate) === value) {
+                this.reusable.delete(candidate);
+                return candidate;
+            }
+            candidate = `${base}-${counter++}`;
+        }
+        this.used.add(candidate);
+        return candidate;
+    }
+}
+/** Staged keys absent from the current code scan, with their staged values —
+ *  the KeyAllocator's reuse pool. */
+export function reusableStagedLabels(existingLabels, wrappedInCode) {
+    const inCode = new Set(wrappedInCode);
+    return new Map(Object.entries(existingLabels).filter(([key]) => !inCode.has(key)));
+}
+/**
+ * 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;
+            }
+            if (looksLikeMarkdown(core)) {
+                // A parent that pipes its string child through a markdown renderer
+                // receives a React element after wrapping — the pipeline stops
+                // parsing and the **markers** render literally (a real parity break
+                // a dogfood gate caught). Text carrying markdown syntax stays agent
+                // work; syntax-free text renders identically either way.
+                skipped.push({ item, reason: 'markdown syntax in text — wrapping could break a markdown pipeline' });
+                continue;
+            }
+            const lead = raw.slice(0, raw.indexOf(core));
+            const trail = raw.slice(raw.indexOf(core) + core.length);
+            // Slug from the DECODED text — "&apos;" must never leak "apos" into a
+            // key ("today-apos-s-total" read "Today Apos S Total" in the Studio).
+            const value = decodeJsxEntities(collapse(core));
+            const id = allocator.allocate(scope, slugify(decodeJsxEntities(core)), value);
+            edits.push({
+                start: span.start,
+                end: span.end,
+                replacement: `${lead}<FimoText id="${id}">${core}</FimoText>${trail}`,
+            });
+            specifiers.add('FimoText');
+            labels[id] = value;
+            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. */
+export 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], reusableStagedLabels(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,165 @@
+import { humanizeSegment } from '../lib/humanize.js';
+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 — fill to the schema's real nesting so deep
+ *  page-builders render, matching the blocks-depth limit (7) in api-contracts.
+ *  The schema is already depth-bounded, so generation stays finite. */
+const MAX_FILL_DEPTH = 6;
+function kebabCase(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .toLowerCase()
+        .replace(/^-+|-+$/g, '');
+}
+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 `${humanizeSegment(field)} example ${ctx.index}${ctx.localeSuffix}`;
+        case 'richtext':
+            return richTextDoc(`Example ${humanizeSegment(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(humanizeSegment(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) {
+        // Rotate the variant window by row index so example entries render
+        // DIFFERENT block sets (entry 1 → variants 0-4, entry 2 → 5-9, …) —
+        // distinct-looking pages, and collectively more of the page builder
+        // exercised than the first five variants over and over.
+        const total = schema.oneOf.length;
+        const take = Math.min(EXAMPLE_BLOCK_VARIANTS, total);
+        const offset = total > 0 ? ((ctx.index - 1) * take) % total : 0;
+        return Array.from({ length: take }, (_, k) => schema.oneOf[(offset + k) % total]).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;