@avocadostudio-ai/site-sdk 0.6.0 → 0.8.0

package/dist/editor-render.d.ts

@@ -0,0 +1,43 @@
+declare const EDITOR_RENDER_HEADER = "x-avocado-editor-render";
+export { EDITOR_RENDER_HEADER };
+/**
+ * The pure half, so the decision is testable without a Next request.
+ *
+ * `getHeader` is whatever `headers()` gives you; `isDraftMode` is
+ * `draftMode().isEnabled`.
+ */
+export declare function isEditorRenderFrom(getHeader: (name: string) => string | null | undefined, isDraftMode: boolean): boolean;
+/**
+ * `true` when this render is being drawn inside the Avocado editor.
+ *
+ * Call it in the root layout and gate everything a preview should not carry:
+ *
+ * ```tsx
+ * export default async function RootLayout({ children }) {
+ *   const inEditor = await isEditorRender()
+ *   return (
+ *     <html lang="de">
+ *       <body>
+ *         {children}
+ *         {!inEditor && <CookieConsent />}
+ *         {!inEditor && <Analytics />}
+ *       </body>
+ *     </html>
+ *   )
+ * }
+ * ```
+ *
+ * **It answers a rendering question, not an authorization one.** What may see
+ * unpublished content is decided by `resolveEditorContext`, which requires draft
+ * mode or a valid secret; this only decides whether to mount third-party
+ * scripts. The header can be sent by anyone, and the worst a forged one does is
+ * opt that visitor out of the site's own analytics and consent banner — which
+ * is self-consistent, because the tracking those scripts set up does not happen
+ * either. Never gate content or credentials on it.
+ *
+ * Reading `headers()` opts the calling segment into dynamic rendering. That is
+ * already true of any layout that reads cookies for a session, and it is the
+ * price of a layout knowing anything about the request at all — but it is worth
+ * knowing before adding the call to a fully static layout.
+ */
+export declare function isEditorRender(): Promise<boolean>;

package/dist/editor-render.js

@@ -0,0 +1,71 @@
+/*
+ * Whether this render is the editor's preview, answerable from a layout.
+ *
+ * `resolveEditorContext()` already tells a *page* it is being previewed, and
+ * that is the wrong half of the tree for the thing sites keep getting wrong.
+ * Consent banners, analytics, tag managers and other visual editors' bridges
+ * are mounted in the root layout, and a Next layout receives no `searchParams`
+ * — so the natural implementation renders the real layout and brings all of
+ * them into the iframe.
+ *
+ * Measured on one integration, per preview render: three uncaught cross-origin
+ * errors from the consent platform reaching for `parent.location`, a cookie
+ * banner covering the page being edited, and a `page_view` written into the
+ * site's own analytics for every block an editor clicked through — twenty
+ * blocks, twenty pageviews, attributed to whoever was editing. Nobody would
+ * choose that, and nobody was asked.
+ *
+ * The signal is a request header the proxy sets when it rewrites to the preview
+ * route, because that is the one thing available to a layout regardless of
+ * where the site put its own state. Draft mode is checked too, for a site whose
+ * preview reaches the route some other way.
+ */
+const EDITOR_RENDER_HEADER = "x-avocado-editor-render";
+export { EDITOR_RENDER_HEADER };
+/**
+ * The pure half, so the decision is testable without a Next request.
+ *
+ * `getHeader` is whatever `headers()` gives you; `isDraftMode` is
+ * `draftMode().isEnabled`.
+ */
+export function isEditorRenderFrom(getHeader, isDraftMode) {
+    return getHeader(EDITOR_RENDER_HEADER) === "1" || isDraftMode;
+}
+/**
+ * `true` when this render is being drawn inside the Avocado editor.
+ *
+ * Call it in the root layout and gate everything a preview should not carry:
+ *
+ * ```tsx
+ * export default async function RootLayout({ children }) {
+ *   const inEditor = await isEditorRender()
+ *   return (
+ *     <html lang="de">
+ *       <body>
+ *         {children}
+ *         {!inEditor && <CookieConsent />}
+ *         {!inEditor && <Analytics />}
+ *       </body>
+ *     </html>
+ *   )
+ * }
+ * ```
+ *
+ * **It answers a rendering question, not an authorization one.** What may see
+ * unpublished content is decided by `resolveEditorContext`, which requires draft
+ * mode or a valid secret; this only decides whether to mount third-party
+ * scripts. The header can be sent by anyone, and the worst a forged one does is
+ * opt that visitor out of the site's own analytics and consent banner — which
+ * is self-consistent, because the tracking those scripts set up does not happen
+ * either. Never gate content or credentials on it.
+ *
+ * Reading `headers()` opts the calling segment into dynamic rendering. That is
+ * already true of any layout that reads cookies for a session, and it is the
+ * price of a layout knowing anything about the request at all — but it is worth
+ * knowing before adding the call to a fully static layout.
+ */
+export async function isEditorRender() {
+    const { headers, draftMode } = await import("next/headers");
+    const [headerList, draft] = await Promise.all([headers(), draftMode()]);
+    return isEditorRenderFrom((name) => headerList.get(name), draft.isEnabled);
+}

package/dist/editor-rewrite-core.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Options shared by every host's editor rewrite.
+ *
+ * `EditorProxyOptions` in `./proxy.ts` extends this with `trailingSlash`, which
+ * exists only to re-issue a redirect Next was told to stop issuing.
+ */
+export type EditorRewriteOptions = {
+    /**
+     * The internal route prefix that the dynamic editor/draft page lives under.
+     * @default "/preview-draft"
+     */
+    previewRoute?: string;
+    /**
+     * Query parameter that signals an editor iframe request.
+     * @default "__editor"
+     */
+    editorParam?: string;
+    /**
+     * Name of the cookie that keeps in-preview navigation in draft mode, or
+     * `false` to key the rewrite on {@link EditorRewriteOptions.editorParam}
+     * alone.
+     *
+     * A link clicked inside the editor iframe carries no `__editor=1`, so without
+     * a cookie the second page a user visits renders published content.
+     *
+     * The default is Next's own `__prerender_bypass`, which is not Avocado's to
+     * claim: anything else calling `draftMode().enable()` — Sanity's Presentation
+     * tool, Contentful's live preview — sets the same cookie, and every one of
+     * *their* preview requests then lands on Avocado's preview route.
+     *
+     * A host with no draft-mode convention of its own has no `__prerender_bypass`
+     * to inherit and must name and set a cookie itself; whatever it names goes
+     * here, so the rewrite triggers on the same cookie the host sets.
+     *
+     * @default "__prerender_bypass"
+     */
+    draftCookie?: string | false;
+};
+/** What the host should do with this request. */
+export type EditorRewriteDecision = 
+/** Not an editor request. The caller's cue to run its own logic, not a decision to pass through. */
+{
+    kind: "pass";
+}
+/** Serve the preview route instead, with these request headers added. */
+ | {
+    kind: "preview";
+    pathname: string;
+    headers: Record<string, string>;
+};
+export type EditorRewriteRequest = {
+    /**
+     * The path the host routes on. Next supplies `nextUrl.pathname`, which has
+     * `basePath` already stripped; a host without the concept passes the URL's
+     * own pathname. It matters because the preview prefix is prepended to this
+     * value, and prepending it to a path that still carries a basePath produces a
+     * route that exists nowhere.
+     */
+    pathname: string;
+    searchParams: URLSearchParams;
+    hasCookie: (name: string) => boolean;
+};
+/**
+ * Whether a request is the editor previewing the site, and where it should be
+ * served from if so.
+ *
+ * Pure, and the whole of the rewrite: `editorPreviewRewrite` in `./proxy.ts` is
+ * this plus `NextResponse.rewrite`, and any other host's middleware is this
+ * plus its own equivalent.
+ */
+export declare function decideEditorRewrite(request: EditorRewriteRequest, options?: EditorRewriteOptions): EditorRewriteDecision;

package/dist/editor-rewrite-core.js

@@ -0,0 +1,37 @@
+import { DEFAULT_PREVIEW_ROUTE } from "./editor-matcher.js";
+import { EDITOR_RENDER_HEADER } from "./editor-render.js";
+/**
+ * Whether a request is the editor previewing the site, and where it should be
+ * served from if so.
+ *
+ * Pure, and the whole of the rewrite: `editorPreviewRewrite` in `./proxy.ts` is
+ * this plus `NextResponse.rewrite`, and any other host's middleware is this
+ * plus its own equivalent.
+ */
+export function decideEditorRewrite(request, options) {
+    const previewRoute = options?.previewRoute ?? DEFAULT_PREVIEW_ROUTE;
+    const editorParam = options?.editorParam ?? "__editor";
+    const draftCookie = options?.draftCookie === undefined ? "__prerender_bypass" : options.draftCookie;
+    const isEditor = request.searchParams.get(editorParam) === "1";
+    const hasDraftCookie = draftCookie !== false && request.hasCookie(draftCookie);
+    if (!isEditor && !hasDraftCookie)
+        return { kind: "pass" };
+    /*
+     * The one fact a layout can get at.
+     *
+     * A page learns it is being previewed from `resolveEditorContext(searchParams)`.
+     * A layout receives no search params, and the root layout is exactly where a
+     * site mounts its consent banner, analytics and tag manager — so every
+     * integration loads all three into the editor iframe until somebody notices
+     * the pageviews. Stamping the rewritten request lets `isEditorRenderFrom()`
+     * answer in a layout without the site threading anything down to it.
+     *
+     * Set on the request, replacing any client-supplied header of the same name,
+     * so what a layout reads is this function's answer and not the caller's.
+     */
+    return {
+        kind: "preview",
+        pathname: `${previewRoute}${request.pathname}`,
+        headers: { [EDITOR_RENDER_HEADER]: "1" },
+    };
+}

package/dist/lens/create-lens.d.ts

@@ -0,0 +1,48 @@
+import type { FieldTable, LocaleLens, Primitives } from "./types.ts";
+export type LensOptions<L extends string = string> = {
+    table: FieldTable;
+    locale: LocaleLens<L>;
+    primitives: Primitives;
+};
+/** Where a write was refused or degraded, and why. */
+export type MergeWarning = {
+    /** `/preise > hero_section > title` — where it happened. */
+    where: string;
+    reason: string;
+};
+export type MergeResult<D> = {
+    doc: D;
+    changed: boolean;
+    warnings: MergeWarning[];
+};
+export type ProjectOptions = {
+    /**
+     * `true` when the document already came out of the CMS with a language
+     * applied, so the bare keys hold the right values and the localised slots
+     * must not be consulted.
+     *
+     * Delivery APIs resolve; management APIs do not. Getting this wrong is
+     * silent in one direction — a resolved document read as raw finds nothing in
+     * the suffixed keys and falls back to the same values it already had.
+     */
+    resolved?: boolean;
+};
+type Doc = Record<string, unknown>;
+declare function humanise(key: string): string;
+export declare function createLens<L extends string = string>(options: LensOptions<L>): {
+    project: (doc: Doc, type: string, lang: L, opts?: ProjectOptions) => Doc;
+    merge: (source: Doc, props: Doc, type: string, lang: L, where?: string, opts?: {
+        checkLang?: L;
+    }) => MergeResult<Doc>;
+    roundTrip: (doc: Doc, type: string, lang: L, opts?: ProjectOptions) => {
+        clean: boolean;
+        fields: string[];
+        warnings: MergeWarning[];
+    };
+    table: FieldTable;
+    locale: LocaleLens<L>;
+    primitives: Primitives;
+    label: typeof humanise;
+};
+export type Lens<L extends string = string> = ReturnType<typeof createLens<L>>;
+export {};

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";