@avocadostudio-ai/site-sdk 0.5.1 → 0.7.0

package/dist/lens/create-lens.js

@@ -0,0 +1,349 @@
+/*
+ * The derivation: one field table, read as props and written back.
+ *
+ * `project` is the getter and `merge` is the setter, and the discipline of the
+ * whole thing is that they are inverses — a projection fed back through the
+ * merge must produce no change at all. That is not a property you reason out
+ * from the shapes; it is one you run against real content, which is why
+ * `roundTrip` below is part of the API rather than a script each integration
+ * writes for itself.
+ *
+ * Two rules govern every write, and both came out of running a projection
+ * through its own inverse over a real dataset rather than out of thinking about
+ * it:
+ *
+ *  1. **Unchanged means untouched.** A CMS with per-language fallback resolves
+ *     a missing translation to the default language, which is correct on screen
+ *     and a lie in storage. Merging a projection back wholesale materialises
+ *     every one of those fallbacks as a real translation — dozens per publish,
+ *     each identical to what the page already showed, so nothing looks wrong.
+ *     Compare against the *projection* of the source, never against a rebuilt
+ *     object: key order and synthetic row ids both make a string comparison
+ *     report changes nobody made.
+ *  2. **Empty means absent.** Writing `""` into a slot that had no value for
+ *     this language is a no-op on screen and a diff in the document.
+ *
+ * A field the table does not declare is invisible to Avocado and untouched by
+ * it: it does not reach the planner, does not appear in the panel, and survives
+ * every publish, because the merge patches the source document rather than
+ * replacing it. That is the lever for scope — declare what an editor should be
+ * able to change and leave the layout and behaviour switches out.
+ */
+import { SCALAR_CODECS } from "./scalar-codecs.js";
+function isRecord(v) {
+    return v != null && typeof v === "object" && !Array.isArray(v);
+}
+function humanise(key) {
+    return key
+        .replace(/[_-]+/g, " ")
+        .replace(/([a-z\d])([A-Z])/g, "$1 $2")
+        .replace(/^./, (c) => c.toUpperCase());
+}
+export function createLens(options) {
+    const { table, locale, primitives } = options;
+    const codecs = { ...SCALAR_CODECS, ...primitives.codecs };
+    function codecFor(spec) {
+        if (spec.kind === "list")
+            return listCodec;
+        const codec = codecs[spec.kind];
+        if (!codec) {
+            throw new Error(`No codec for field kind "${spec.kind}". The CMS primitive pack must supply one, ` +
+                `or the table should use a kind it does supply.`);
+        }
+        return codec;
+    }
+    function at(rec, path) {
+        if (path.length === 1)
+            return rec[path[0]];
+        const container = rec[path[0]];
+        return isRecord(container) ? container[path[1]] : undefined;
+    }
+    /**
+     * Where this language's value lives.
+     *
+     * Three cases, and the third is the one that cost a rewrite. A localised
+     * field is wherever `locale.path` says — for *every* language including the
+     * default, because a CMS that localises into an object under the key has no
+     * bare value at all, and short-circuiting the default to `doc[key]` reads
+     * that object back as `[object Object]`.
+     *
+     * A field with one value for every language is at the bare key, which is
+     * **not** the same as the default language's path: those coincide in a CMS
+     * that localises into a suffixed sibling and diverge in one that localises
+     * into an object. A field the CMS has stopped marking translatable is the
+     * same case — its old translations are still in the document and the delivery
+     * API ignores them, so this must too, or the publisher believes a field
+     * changed on every publish.
+     */
+    function slot(key, lang, spec, type) {
+        if (spec.localized === false)
+            return [key];
+        if (locale.translatable && !locale.translatable(type, key, lang))
+            return [key];
+        return locale.path(key, lang);
+    }
+    function isBlank(v) {
+        return v === undefined || v === null || v === "";
+    }
+    /**
+     * Read `key`'s value for `lang`, falling back to the default language.
+     *
+     * The default language is the fallback when the localised slot is absent *or*
+     * empty — an empty string in a translation slot is how a CMS spells "not
+     * translated yet", and reading it literally blanks the page.
+     */
+    function readField(rec, key, lang, spec, type) {
+        const target = slot(key, lang, spec, type);
+        const value = at(rec, target);
+        if (!isBlank(value))
+            return value;
+        const fallbackTarget = locale.path(key, locale.default);
+        if (target.length === fallbackTarget.length && target.every((seg, i) => seg === fallbackTarget[i]))
+            return value;
+        if (spec.localized === false)
+            return value;
+        const fallback = at(rec, fallbackTarget);
+        return isBlank(fallback) ? value : fallback;
+    }
+    function writeField(rec, key, lang, spec, type, value) {
+        const target = slot(key, lang, spec, type);
+        if (target.length === 1) {
+            rec[target[0]] = value;
+            return;
+        }
+        const container = isRecord(rec[target[0]]) ? { ...rec[target[0]] } : {};
+        container[target[1]] = value;
+        rec[target[0]] = container;
+    }
+    function specFor(type) {
+        return table[type];
+    }
+    /**
+     * A list of child rows, matched by identity rather than by position.
+     *
+     * Position is the wrong key and it fails quietly: reorder a list, or delete
+     * the second of five rows, and every row after the change is merged onto the
+     * wrong source — the edit lands, the page looks plausible, and four rows have
+     * quietly swapped their untouched fields. Matching on the CMS's own row id is
+     * what keeps a list edit a merge.
+     *
+     * **A row Avocado never saw stays where it was.** The editor's order is taken
+     * for the rows it knows; anything else is re-inserted at its original index.
+     * A list can hold types the table does not declare, and dropping them is how
+     * an integration deletes content it was never asked about.
+     *
+     * Built here rather than in a primitive pack because the walk is the same
+     * everywhere — what differs is the key a row carries its identity and type
+     * under, and both are already declared.
+     */
+    const listCodec = {
+        project(key, raw, ctx) {
+            const rows = Array.isArray(raw) ? raw : [];
+            const spec = ctx.spec;
+            if (spec.kind !== "list")
+                return { [key]: [] };
+            if ("itemFields" in spec) {
+                // Rows described inline: no type of their own, so project field by field.
+                const inline = spec.itemFields;
+                return {
+                    [key]: rows.filter(isRecord).map((row) => {
+                        const out = {};
+                        if (primitives.rowIdKey in row)
+                            out[primitives.rowIdKey] = row[primitives.rowIdKey];
+                        for (const [itemKey, itemSpec] of Object.entries(inline)) {
+                            const itemCtx = { spec: itemSpec, lang: ctx.lang, type: ctx.type, where: `${ctx.where}[] > ${itemKey}` };
+                            // A row's fields are localised exactly as a block's are — the
+                            // per-locale container sits on the row, not on the page.
+                            const raw = readField(row, itemKey, ctx.lang, itemSpec, ctx.type);
+                            Object.assign(out, codecFor(itemSpec).project(itemKey, raw, itemCtx));
+                        }
+                        return out;
+                    })
+                };
+            }
+            const typeKey = primitives.rowTypeKey;
+            return {
+                [key]: rows
+                    .filter((row) => isRecord(row) && Boolean(typeKey) && specFor(String(row[typeKey])) !== undefined)
+                    .map((row) => ({
+                    [typeKey]: row[typeKey],
+                    [primitives.rowIdKey]: row[primitives.rowIdKey],
+                    ...project(row, String(row[typeKey]), ctx.lang)
+                }))
+            };
+        },
+        merge(key, props, before, ctx) {
+            if (!(key in props))
+                return null;
+            const spec = ctx.spec;
+            if (spec.kind !== "list")
+                return null;
+            const items = Array.isArray(props[key]) ? props[key].filter(isRecord) : [];
+            const sourceRows = (Array.isArray(before) ? before : []).filter(isRecord);
+            const byId = new Map(sourceRows.map((row) => [row[primitives.rowIdKey], row]));
+            const seen = new Set();
+            const merged = [];
+            for (const item of items) {
+                const rowId = item[primitives.rowIdKey];
+                const source = rowId === undefined ? undefined : byId.get(rowId);
+                if (source)
+                    seen.add(rowId);
+                if ("itemFields" in spec) {
+                    const base = source ? { ...source } : { [primitives.rowIdKey]: primitives.newRowId() };
+                    let rowChanged = !source;
+                    for (const [itemKey, itemSpec] of Object.entries(spec.itemFields)) {
+                        const itemCtx = { spec: itemSpec, lang: ctx.lang, type: ctx.type, where: `${ctx.where}[] > ${itemKey}` };
+                        const before = source ? readField(source, itemKey, ctx.lang, itemSpec, ctx.type) : undefined;
+                        const outcome = codecFor(itemSpec).merge(itemKey, item, before, itemCtx);
+                        if (!outcome || "warning" in outcome)
+                            continue;
+                        writeField(base, itemKey, ctx.lang, itemSpec, ctx.type, outcome.value);
+                        rowChanged = true;
+                    }
+                    void rowChanged;
+                    merged.push(base);
+                    continue;
+                }
+                const typeKey = primitives.rowTypeKey;
+                const rowType = String(item[typeKey] ?? (source ? source[typeKey] : ""));
+                if (!rowType || !specFor(rowType)) {
+                    /*
+                     * A row that names no type is a row no CMS storing rows as documents
+                     * can construct, and guessing one writes content nobody asked for.
+                     * The op validator rejects this at the moment of the mistake; a row
+                     * that still reaches here is dropped from the merge rather than
+                     * fabricated, and the source list keeps whatever it had.
+                     */
+                    if (source)
+                        merged.push(source);
+                    continue;
+                }
+                const result = merge(source ?? { [typeKey]: rowType, [primitives.rowIdKey]: primitives.newRowId() }, item, rowType, ctx.lang, `${ctx.where}[]`);
+                merged.push(result.doc);
+            }
+            // Rows the table does not describe keep their place rather than vanishing.
+            for (const [index, row] of sourceRows.entries()) {
+                const rowId = row[primitives.rowIdKey];
+                if (seen.has(rowId))
+                    continue;
+                const typeKey = primitives.rowTypeKey;
+                const described = typeKey ? specFor(String(row[typeKey])) !== undefined : true;
+                if (described)
+                    continue;
+                merged.splice(Math.min(index, merged.length), 0, row);
+            }
+            /*
+             * Compared structurally, and deliberately not by counting rows.
+             *
+             * The projection omits every row whose type the table does not describe,
+             * so a list of five that Avocado can edit two of arrives back with two —
+             * and a length check reads that as three deletions on a list nobody
+             * touched. Comparing the rebuilt list to the source catches a real
+             * reorder, add and delete, and says nothing about a list that only looks
+             * shorter from Avocado's side.
+             */
+            return JSON.stringify(merged) === JSON.stringify(sourceRows) ? null : { value: merged };
+        }
+    };
+    /**
+     * One CMS document as Avocado props, in one language.
+     *
+     * A type the table does not declare projects to nothing, rather than to a
+     * partial guess — an undeclared type is one nobody said Avocado may edit.
+     */
+    function project(doc, type, lang, opts) {
+        const blockSpec = specFor(type);
+        if (!blockSpec)
+            return {};
+        const props = {};
+        for (const [key, spec] of Object.entries(blockSpec.fields)) {
+            const raw = opts?.resolved ? doc[key] : readField(doc, key, lang, spec, type);
+            const ctx = { spec, lang, type, where: `${type} > ${key}` };
+            Object.assign(props, codecFor(spec).project(key, raw, ctx));
+        }
+        return props;
+    }
+    /**
+     * Edited props back onto their source document, for one language.
+     *
+     * The source is the live CMS document, not a snapshot Avocado holds, so every
+     * field the table does not declare survives untouched by construction — and
+     * that is the difference between a publish that patches and a publish that
+     * silently deletes forty fields this integration never learned about.
+     */
+    function merge(source, props, type, lang, where = type, opts) {
+        const blockSpec = specFor(type);
+        if (!blockSpec)
+            return { doc: source, changed: false, warnings: [] };
+        /*
+         * The language the *page* is in, which is not always the language being
+         * written: a live preview merges into the bare keys of an already-resolved
+         * document — writing as if it were the default language — while the page it
+         * draws may be another. Translatability is a question about the page;
+         * where to store the value is a question about the write. Conflating them
+         * lets the preview show an edit the publish then refuses, which is worse
+         * than refusing it in both places.
+         */
+        const checkLang = opts?.checkLang ?? lang;
+        const out = { ...source };
+        const warnings = [];
+        let changed = false;
+        for (const [key, spec] of Object.entries(blockSpec.fields)) {
+            const before = readField(source, key, lang, spec, type);
+            const ctx = { spec, lang, type, where: `${where} > ${key}` };
+            const outcome = codecFor(spec).merge(key, props, before, ctx);
+            if (!outcome)
+                continue;
+            if ("warning" in outcome) {
+                warnings.push({ where: ctx.where, reason: outcome.warning });
+                continue;
+            }
+            /*
+             * Asked here, about a real change, and deliberately not earlier. The
+             * first version of this re-projected the source and compared JSON before
+             * deciding — and reported fields nobody had touched as refused
+             * translations, because a rebuilt object's key order does not match the
+             * source's and because list rows carry a synthetic id. Both are
+             * invisible differences that a string comparison calls a change.
+             */
+            if (checkLang !== locale.default &&
+                spec.localized !== false &&
+                locale.translatable &&
+                !locale.translatable(type, key, checkLang)) {
+                warnings.push({
+                    where: ctx.where,
+                    reason: `"${key}" is not translatable on ${type} — it has one value for every language, ` +
+                        `so this ${String(checkLang).toUpperCase()} edit cannot be stored. ` +
+                        `Edit it on the ${String(locale.default).toUpperCase()} page.`
+                });
+                continue;
+            }
+            writeField(out, key, lang, spec, type, outcome.value);
+            changed = true;
+        }
+        return { doc: out, changed, warnings };
+    }
+    /**
+     * Project, merge the projection straight back, and report what moved.
+     *
+     * Nothing should. A non-empty result is the signal that a codec is not the
+     * inverse of itself for some value in this dataset — the class of defect that
+     * is invisible in the editor, harmless in the preview, and shows up as a
+     * publish wanting to rewrite documents nobody opened.
+     *
+     * Run it over real content, not fixtures. Every rule in this file exists
+     * because a fixture round-tripped and a dataset did not.
+     */
+    function roundTrip(doc, type, lang, opts) {
+        const props = project(doc, type, lang, opts);
+        const result = merge(doc, props, type, lang);
+        const fields = Object.keys(specFor(type)?.fields ?? {}).filter((key) => {
+            const spec = specFor(type).fields[key];
+            const before = readField(doc, key, lang, spec, type);
+            const after = readField(result.doc, key, lang, spec, type);
+            return JSON.stringify(before ?? null) !== JSON.stringify(after ?? null);
+        });
+        return { clean: !result.changed && fields.length === 0, fields, warnings: result.warnings };
+    }
+    return { project, merge, roundTrip, table, locale, primitives, label: humanise };
+}

package/dist/lens/index.d.ts

@@ -0,0 +1,7 @@
+export { createLens } from "./create-lens.ts";
+export type { Lens, LensOptions, MergeResult, MergeWarning, ProjectOptions } from "./create-lens.ts";
+export { registerFieldTable, topLevelTypes } from "./register.ts";
+export type { RegisterOptions } from "./register.ts";
+export { suffixNaming } from "./types.ts";
+export type { BlockSpec, CodecContext, FieldCodec, FieldSpec, FieldTable, ImageNaming, LocaleLens, MergeOutcome, Primitives } from "./types.ts";
+export { changed } from "./scalar-codecs.ts";

package/dist/lens/index.js

@@ -0,0 +1,25 @@
+/*
+ * The field table, and the four things derived from it.
+ *
+ * ```ts
+ * import { createLens, registerFieldTable } from "@avocadostudio-ai/site-sdk/lens"
+ * import { storyblokPrimitives } from "@avocadostudio-ai/site-sdk/lens/storyblok"
+ *
+ * const primitives = storyblokPrimitives()
+ *
+ * registerFieldTable(TABLE, { primitives })     // schemas + panel metadata
+ * export const lens = createLens({              // projection + merge
+ *   table: TABLE,
+ *   locale: { default: "de", languages: ["de", "en", "fr"], path: (k, l) => [`${k}__i18n__${l}`] },
+ *   primitives,
+ * })
+ * ```
+ *
+ * The two are separate on purpose: registration writes to a global registry and
+ * `createLens` returns a value, so folding one into the other would make an
+ * object you cannot build twice and make the order of two imports matter.
+ */
+export { createLens } from "./create-lens.js";
+export { registerFieldTable, topLevelTypes } from "./register.js";
+export { suffixNaming } from "./types.js";
+export { changed } from "./scalar-codecs.js";

package/dist/lens/lens.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lens/lens.test.js

@@ -0,0 +1,221 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { createLens } from "./create-lens.js";
+import { storyblokPrimitives, storyblokLocale } from "./storyblok.js";
+import { sanityPrimitives, sanityLocale } from "./sanity.js";
+// ---------------------------------------------------------------------------
+// Storyblok: a suffixed sibling key per language
+// ---------------------------------------------------------------------------
+const TABLE = {
+    hero_section: {
+        displayName: "Hero",
+        topLevel: true,
+        fields: {
+            title: { kind: "text" },
+            background_image: { kind: "image" },
+            cta_link: { kind: "link" },
+            anchor: { kind: "text", localized: false },
+            buttons: { kind: "list", of: ["button"] }
+        }
+    },
+    button: {
+        displayName: "Button",
+        topLevel: false,
+        fields: {
+            label: { kind: "text" },
+            variant: { kind: "enum", options: ["solid", "outline"] }
+        }
+    }
+};
+const sbLocale = storyblokLocale("de", ["de", "fr"]);
+const sb = createLens({ table: TABLE, locale: sbLocale, primitives: storyblokPrimitives() });
+function story() {
+    return {
+        component: "hero_section",
+        _uid: "u_hero",
+        title: "Willkommen",
+        title__i18n__fr: "Bienvenue",
+        background_image: { fieldtype: "asset", id: 9, filename: "https://a.storyblok.com/f/1/a.jpg", alt: "Halle" },
+        cta_link: { fieldtype: "multilink", linktype: "url", url: "https://book.example.com" },
+        anchor: "top",
+        // Declared by nobody. It has to survive every write below.
+        layout_variant: "wide",
+        buttons: [
+            { component: "button", _uid: "u_b1", label: "Buchen", label__i18n__fr: "Réserver", variant: "solid" },
+            { component: "spacer", _uid: "u_x1", height: 24 }
+        ]
+    };
+}
+test("a field the table does not declare is not projected", () => {
+    const props = sb.project(story(), "hero_section", "de");
+    assert.equal("layout_variant" in props, false);
+    assert.equal(props.title, "Willkommen");
+});
+test("an image projects to two props, a URL and its alt", () => {
+    const props = sb.project(story(), "hero_section", "de");
+    assert.equal(props.background_image, "https://a.storyblok.com/f/1/a.jpg");
+    assert.equal(props.background_image_alt, "Halle");
+});
+test("a language reads its own slot, and falls back to the default when absent", () => {
+    assert.equal(sb.project(story(), "hero_section", "fr").title, "Bienvenue");
+    const noFrench = { ...story(), title__i18n__fr: undefined };
+    assert.equal(sb.project(noFrench, "hero_section", "fr").title, "Willkommen");
+});
+/*
+ * The rule the whole file turns on. French has no value for `anchor` — it is
+ * declared `localized: false` — and no value for the image alt, so the
+ * projection carries German strings sitting in a French page. Merging that
+ * projection back must write none of them: each one would become a real,
+ * fabricated French translation, invisible on screen and permanent in the
+ * document.
+ */
+test("a projection merged straight back changes nothing, in either language", () => {
+    for (const lang of ["de", "fr"]) {
+        const result = sb.roundTrip(story(), "hero_section", lang);
+        assert.equal(result.clean, true, `${lang}: ${result.fields.join(", ")}`);
+    }
+});
+test("a real edit is written into the language being edited, and only there", () => {
+    const props = sb.project(story(), "hero_section", "fr");
+    const { doc, changed } = sb.merge(story(), { ...props, title: "Salut" }, "hero_section", "fr");
+    assert.equal(changed, true);
+    assert.equal(doc.title__i18n__fr, "Salut");
+    assert.equal(doc.title, "Willkommen", "the German value must not move");
+});
+test("a field nobody declared survives a write", () => {
+    const props = sb.project(story(), "hero_section", "de");
+    const { doc } = sb.merge(story(), { ...props, title: "Neu" }, "hero_section", "de");
+    assert.equal(doc.layout_variant, "wide");
+});
+test("a non-localised field writes to the bare key whatever page is edited", () => {
+    const props = sb.project(story(), "hero_section", "fr");
+    const { doc } = sb.merge(story(), { ...props, anchor: "hero" }, "hero_section", "fr");
+    assert.equal(doc.anchor, "hero");
+    assert.equal("anchor__i18n__fr" in doc, false);
+});
+/*
+ * A story link is a reference rendered per-locale, so its href cannot be
+ * written back — but an external URL is stored as itself and stays editable,
+ * which is the case that matters (booking and shop links).
+ */
+test("an external link is writable and a story link is refused with a reason", () => {
+    const props = sb.project(story(), "hero_section", "de");
+    const external = sb.merge(story(), { ...props, cta_link: "https://shop.example.com" }, "hero_section", "de");
+    assert.equal(external.doc.cta_link.url, "https://shop.example.com");
+    assert.equal(external.warnings.length, 0);
+    const withStoryLink = { ...story(), cta_link: { fieldtype: "multilink", linktype: "story", cached_url: "faq" } };
+    const refused = sb.merge(withStoryLink, { ...sb.project(withStoryLink, "hero_section", "de"), cta_link: "/anything" }, "hero_section", "de");
+    assert.equal(refused.changed, false);
+    assert.match(refused.warnings[0].reason, /points at a page in the CMS/);
+});
+test("a child row is matched by its own id, not by position", () => {
+    const props = sb.project(story(), "hero_section", "de");
+    const buttons = props.buttons;
+    assert.equal(buttons.length, 1, "an undeclared child type is not projected");
+    assert.equal(buttons[0]._uid, "u_b1");
+    const reordered = { ...props, buttons: [{ ...buttons[0], label: "Jetzt buchen" }] };
+    const { doc } = sb.merge(story(), reordered, "hero_section", "de");
+    const merged = doc.buttons;
+    assert.equal(merged.find((b) => b._uid === "u_b1").label, "Jetzt buchen");
+});
+/*
+ * A list can hold types the table does not describe, and dropping them is how
+ * an integration deletes content it was never asked about.
+ */
+test("a child row of an undeclared type keeps its place through a list edit", () => {
+    const props = sb.project(story(), "hero_section", "de");
+    const buttons = props.buttons;
+    const { doc } = sb.merge(story(), { ...props, buttons: [{ ...buttons[0], label: "X" }] }, "hero_section", "de");
+    const merged = doc.buttons;
+    assert.ok(merged.some((b) => b._uid === "u_x1"), "the spacer must survive");
+});
+test("a value outside a closed list is refused rather than stored", () => {
+    const source = { component: "button", _uid: "u_b1", label: "Buchen", variant: "solid" };
+    const result = sb.merge(source, { label: "Buchen", variant: "ghost" }, "button", "de");
+    assert.equal(result.changed, false);
+    assert.match(result.warnings[0].reason, /not one of solid, outline/);
+});
+// ---------------------------------------------------------------------------
+// Sanity: a per-locale object under the key itself
+// ---------------------------------------------------------------------------
+/*
+ * The same table, the same lens, a CMS that disagrees in every particular — a
+ * per-locale object rather than a suffixed key, a reference rather than a flat
+ * asset, `_key` rather than `_uid`. If anything above `Primitives` had turned
+ * out to be Storyblok-shaped, it would show up here.
+ */
+const SANITY_TABLE = {
+    heroSplit: {
+        displayName: "Hero — split",
+        fields: {
+            heading: { kind: "text" },
+            // Sanity localises only what the schema marks translatable, and an image
+            // is not: it is one asset reference for every language, at the bare key
+            // rather than inside a `{de, fr}` container. Declaring that is the
+            // difference between reading the image and reading nothing.
+            hero: { kind: "image", localized: false },
+            // The list *container* is one array for every language; what is
+            // translated are the fields on its rows. Storyblok and Sanity differ here
+            // and the table is where the difference is stated.
+            buttons: {
+                kind: "list",
+                localized: false,
+                itemFields: { label: { kind: "text" }, variant: { kind: "enum", options: ["solid", "outline"] } }
+            }
+        }
+    }
+};
+const sanity = createLens({
+    table: SANITY_TABLE,
+    locale: sanityLocale("de", ["de", "fr"]),
+    primitives: sanityPrimitives()
+});
+function sanityDoc() {
+    return {
+        _type: "heroSplit",
+        _key: "k_hero",
+        heading: { de: "Willkommen", fr: "Bienvenue" },
+        hero: { _type: "image", asset: { _ref: "image-abc", url: "https://cdn.sanity.io/a.jpg" }, alt: "Halle" },
+        buttons: [{ _key: "k_b1", label: { de: "Buchen", fr: "Réserver" }, variant: "solid" }]
+    };
+}
+test("the same lens reads a per-locale object", () => {
+    assert.equal(sanity.project(sanityDoc(), "heroSplit", "de").heading, "Willkommen");
+    assert.equal(sanity.project(sanityDoc(), "heroSplit", "fr").heading, "Bienvenue");
+});
+test("an image names its props the way the asset picker expects", () => {
+    const props = sanity.project(sanityDoc(), "heroSplit", "de");
+    assert.equal(props.heroUrl, "https://cdn.sanity.io/a.jpg");
+    assert.equal(props.heroAlt, "Halle");
+});
+test("a Sanity projection merged back changes nothing either", () => {
+    for (const lang of ["de", "fr"]) {
+        const result = sanity.roundTrip(sanityDoc(), "heroSplit", lang);
+        assert.equal(result.clean, true, `${lang}: ${result.fields.join(", ")}`);
+    }
+});
+test("an edit lands in its own locale slot and leaves the other alone", () => {
+    const props = sanity.project(sanityDoc(), "heroSplit", "fr");
+    const { doc } = sanity.merge(sanityDoc(), { ...props, heading: "Salut" }, "heroSplit", "fr");
+    assert.deepEqual(doc.heading, { de: "Willkommen", fr: "Salut" });
+});
+/*
+ * The URL is a render of `asset._ref`, so writing it back would replace a
+ * reference with a string. The alt text is content and stays editable — the
+ * asymmetry is the point.
+ */
+test("an image's alt is writable and its resolved URL is not", () => {
+    const props = sanity.project(sanityDoc(), "heroSplit", "de");
+    const { doc } = sanity.merge(sanityDoc(), { ...props, heroAlt: "Die Halle", heroUrl: "https://evil.example/x.jpg" }, "heroSplit", "de");
+    const image = doc.hero;
+    assert.equal(image.alt, "Die Halle");
+    assert.deepEqual(image.asset, { _ref: "image-abc", url: "https://cdn.sanity.io/a.jpg" });
+});
+test("an inline-described row merges by _key", () => {
+    const props = sanity.project(sanityDoc(), "heroSplit", "de");
+    const buttons = props.buttons;
+    assert.equal(buttons[0]._key, "k_b1");
+    const { doc } = sanity.merge(sanityDoc(), { ...props, buttons: [{ ...buttons[0], label: "Jetzt" }] }, "heroSplit", "de");
+    const merged = doc.buttons;
+    assert.deepEqual(merged[0].label, { de: "Jetzt", fr: "Réserver" });
+});

package/dist/lens/register.d.ts

@@ -0,0 +1,34 @@
+import type { FieldTable, Primitives } from "./types.ts";
+export type RegisterOptions = {
+    /**
+     * The CMS pack, read only for its image prop naming.
+     *
+     * Passing the same object `createLens` gets is what makes the panel and the
+     * projection agree about what an image field's two props are called. Held
+     * apart they are two declarations that must match with nothing checking that
+     * they do — and the symptom is an asset picker that never appears.
+     */
+    primitives?: Pick<Primitives, "imageNaming">;
+    /**
+     * `false` to leave Avocado's own built-in block types in the picker.
+     *
+     * The default narrows the catalogue to the table, because a site that cannot
+     * render `FeatureGrid` should not be offered it — an editor who adds one gets
+     * a block that renders as nothing, and the only trace is a warning in a log.
+     */
+    narrowCatalogue?: boolean;
+};
+/**
+ * Register every type in the table as an Avocado block type.
+ *
+ * Adding a field to a block becomes one line in one file: the schema, the
+ * panel, the projection and the merge all read the same declaration.
+ */
+export declare function registerFieldTable(table: FieldTable, options?: RegisterOptions): void;
+/**
+ * The types a page body may hold, which is not every type in the table.
+ *
+ * A row type — a card, a button — is declared so the panel can draw it and the
+ * merge can construct it, and must never appear in the block picker.
+ */
+export declare function topLevelTypes(table: FieldTable): string[];