@avocadostudio-ai/site-sdk 0.6.0 → 0.8.0

package/dist/lens/register.d.ts

@@ -0,0 +1,32 @@
+import type { FieldTable, Primitives } from "./types.ts";
+export type RegisterOptions = {
+    /**
+     * The CMS pack, read for its image prop naming and its row keys.
+     *
+     * 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.
+     *
+     * `rowIdKey` and `rowTypeKey` are the same argument one level down: the
+     * projection writes a row's identity and type under those keys, so the schema
+     * has to expect them there and the list has to discriminate on them.
+     */
+    primitives?: Pick<Primitives, "imageNaming"> & Partial<Pick<Primitives, "rowIdKey" | "rowTypeKey">>;
+    /**
+     * `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;
+};
+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[];

package/dist/lens/register.js

@@ -0,0 +1,322 @@
+/*
+ * The table's other two consumers: the schema an edit is validated against, and
+ * the metadata the property panel draws with.
+ *
+ * Both matter and they answer different questions. Skip the Zod schema and
+ * every AI edit comes back `Unknown block type`. Skip the metadata and every
+ * string gets the same one-line input, because `kind` has no JSON Schema
+ * spelling — a rich-text body is then edited as a headline, and an image field
+ * gets a text box holding a URL.
+ *
+ * Deliberately separate from `createLens`. This writes to a global registry and
+ * `createLens` returns a value; folding a side effect into a constructor makes
+ * an object you cannot build twice, and makes the order of two imports matter.
+ */
+import { registerBlock, declareBlockCatalogue, z, FIELD_KINDS } from "@avocadostudio-ai/shared";
+import { suffixNaming } from "./types.js";
+/**
+ * A ProseMirror document, declared so the panel recognises it as one.
+ *
+ * The recogniser keys off `type` being pinned to the literal `"doc"`, which
+ * `z.literal` does survive into JSON Schema as a `const`. `content` is left
+ * unconstrained on purpose: it is somebody else's grammar, and validating it
+ * here would only reject documents the editor round-trips perfectly well.
+ */
+const richTextSchema = () => z.object({
+    type: z.literal("doc"),
+    content: z.array(z.any()).optional()
+});
+function humanise(key) {
+    return key
+        .replace(/[_-]+/g, " ")
+        .replace(/([a-z\d])([A-Z])/g, "$1 $2")
+        .replace(/^./, (c) => c.toUpperCase());
+}
+/**
+ * The row types a `list: { of }` can actually be given a shape for.
+ *
+ * A named type the table does not describe is skipped rather than emitted as an
+ * empty branch: Avocado cannot project or merge a row of it — `createLens`
+ * filters those rows out — so offering it in the panel would be an Add control
+ * for something no publish could store.
+ */
+function rowTypesFor(of, ctx) {
+    if (!ctx.rowTypeKey)
+        return [];
+    return [...new Set(of)].filter((type) => ctx.table[type] !== undefined && !ctx.visiting.has(type));
+}
+/**
+ * One list row as an object schema, and `loose` is the load-bearing word.
+ *
+ * A row is a CMS document: it carries `component`, `_uid`, and every field the
+ * table chose not to declare. `z.object` strips what it does not know, and the
+ * ops engine's passthrough only covers a block's *top-level* props — so a
+ * strict row schema would silently delete the undeclared half of every row an
+ * edit touched.
+ */
+function rowSchema(fields, ctx, pinned) {
+    const shape = { ...pinned };
+    // Declared, not merely tolerated: an undeclared prop present in the content is
+    // an `orphan_prop` to the coverage checkers, and a row id is one per row.
+    if (ctx.rowIdKey)
+        shape[ctx.rowIdKey] = z.string().optional();
+    Object.assign(shape, shapeForFields(fields, ctx));
+    return z.object(shape).loose();
+}
+/**
+ * A list's schema, in the one shape the manifest can resolve.
+ *
+ * It used to be `z.array(z.record(z.string(), z.any()))` for both forms, which
+ * reaches the manifest as an array of objects with no properties — so the
+ * derivation produced no item fields at all, `resolveManifestFieldMeta` dropped
+ * the list, and the panel drew neither rows nor an Add control. The metadata
+ * registered beside it was correct the whole time; the schema is what the panel
+ * sees, and it said nothing.
+ */
+function listSchemaFor(spec, ctx) {
+    if ("itemFields" in spec)
+        return z.array(rowSchema(spec.itemFields, ctx, {})).optional();
+    const typeKey = ctx.rowTypeKey;
+    const types = rowTypesFor(spec.of, ctx);
+    // Nothing describable: back to the opaque array, which at least stores the
+    // rows untouched rather than rejecting them.
+    if (types.length === 0)
+        return z.array(z.record(z.string(), z.any())).optional();
+    const branches = types.map((type) => rowSchema(ctx.table[type].fields, { ...ctx, visiting: new Set([...ctx.visiting, type]) }, {
+        [typeKey]: z.literal(type)
+    }));
+    return z.array(z.discriminatedUnion(typeKey, branches)).optional();
+}
+function schemaForField(spec, ctx) {
+    switch (spec.kind) {
+        case "richtext":
+            return richTextSchema().optional();
+        // Stored as the string the template renders. The document only exists
+        // while the panel has it open; `richTextSchema` would also admit a doc,
+        // and a doc written back is markup the site cannot render.
+        case "html":
+            return z.string().optional();
+        case "boolean":
+            return z.boolean().optional();
+        case "number":
+            return z.number().optional();
+        case "enum":
+            // Not `z.enum`: content that predates an option being removed still holds
+            // the old value, and a schema that rejects it makes the block uneditable
+            // in the one surface that can still fix it. The panel offers the declared
+            // options; the merge refuses an undeclared write.
+            return z.string().optional();
+        case "stringList":
+            return z.array(z.string()).optional();
+        case "imageList":
+            return z.array(z.record(z.string(), z.any())).optional();
+        case "list":
+            return listSchemaFor(spec, ctx);
+        default:
+            return z.string().optional();
+    }
+}
+/**
+ * A declared field set as an object shape — a block's props, or a row's.
+ *
+ * An image is two props and `key` may be neither of them: a pack that names
+ * them `heroUrl`/`heroAlt` must not also leave a bare `hero` in the schema, or
+ * the panel draws a third control that writes nowhere.
+ */
+function shapeForFields(fields, ctx) {
+    const shape = {};
+    for (const [key, spec] of Object.entries(fields)) {
+        if (spec.kind === "image") {
+            shape[ctx.naming.url(key)] = z.string().optional();
+            shape[ctx.naming.alt(key)] = z.string().optional();
+            continue;
+        }
+        shape[key] = schemaForField(spec, ctx);
+    }
+    return shape;
+}
+function metaForField(key, spec) {
+    const meta = {
+        /*
+         * `list` alone is still `text` here, and it is not a loss: a list travels
+         * the separate `listFields` channel, which carries its row shape, and the
+         * kind on this side is never read. `stringList` and `imageList` have no
+         * such channel — flattening them to `text` was the whole of AW-01, because
+         * the panel then discarded the metadata as contradicting an array schema
+         * and drew nothing.
+         */
+        kind: spec.kind === "list" ? "text" : spec.kind,
+        label: spec.label ?? humanise(key)
+    };
+    if (spec.internal)
+        meta.internal = true;
+    if (spec.panelOnly)
+        meta.panelOnly = true;
+    if (spec.kind === "text" && spec.multiline)
+        meta.multiline = true;
+    if (spec.kind === "text" && spec.inlineEditable !== undefined)
+        meta.inlineEditable = spec.inlineEditable;
+    if (spec.kind === "richtext" && spec.inline)
+        meta.inline = true;
+    if (spec.kind === "html" && spec.inline)
+        meta.inline = true;
+    /*
+     * Not editable on the page unless the site says so.
+     *
+     * Every other kind defaults to inline-editable, and for this one that
+     * default corrupts: the overlay edits an element's text, and the value here
+     * is markup wrapped around that text. A person fixing a typo in the hero
+     * headline would write the typo back without the spans. The panel converts
+     * properly, so it is the whole of the UI until a site opts in.
+     */
+    if (spec.kind === "html")
+        meta.inlineEditable = spec.inlineEditable ?? false;
+    if (spec.kind === "enum")
+        meta.options = [...spec.options];
+    if (spec.kind === "image" && spec.imageSpec)
+        meta.imageSpec = spec.imageSpec;
+    return meta;
+}
+/** The same expansion as `shapeForFields`, as panel metadata rather than schema. */
+function metaForFields(fields, ctx) {
+    const out = {};
+    if (ctx.rowIdKey)
+        out[ctx.rowIdKey] = { kind: "text", label: humanise(ctx.rowIdKey), internal: true };
+    for (const [key, spec] of Object.entries(fields)) {
+        if (spec.kind === "image") {
+            out[ctx.naming.url(key)] = metaForField(key, spec);
+            out[ctx.naming.alt(key)] = { kind: "imageAlt", label: `${spec.label ?? humanise(key)} alt` };
+            continue;
+        }
+        out[key] = metaForField(key, spec);
+    }
+    return out;
+}
+/**
+ * A list's panel metadata.
+ *
+ * Declared rather than left to the derivation because the derivation cannot
+ * know all of it: an enum's options never reach the JSON schema (the schema is
+ * a plain string on purpose, see above), and neither does a label the table
+ * chose. For the `of` form this carries the per-type field sets and the
+ * discriminator the panel narrows a row by — and that the ops engine reads to
+ * refuse a new row that names no type.
+ */
+function listMetaFor(key, spec, ctx) {
+    const label = spec.label ?? humanise(key);
+    if ("itemFields" in spec)
+        return { label, itemFields: metaForFields(spec.itemFields, ctx) };
+    const types = rowTypesFor(spec.of, ctx);
+    if (types.length === 0)
+        return { label, itemFields: {} };
+    const itemFieldsByType = {};
+    const merged = {};
+    for (const type of types) {
+        const fields = metaForFields(ctx.table[type].fields, {
+            ...ctx,
+            visiting: new Set([...ctx.visiting, type])
+        });
+        itemFieldsByType[type] = fields;
+        for (const [fieldKey, meta] of Object.entries(fields))
+            if (!(fieldKey in merged))
+                merged[fieldKey] = meta;
+    }
+    return { label, itemFields: merged, discriminator: ctx.rowTypeKey, itemFieldsByType };
+}
+/**
+ * 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.
+ */
+/**
+ * Refuse a field this table cannot draw, rather than emitting the nearest kind.
+ *
+ * Every gap this file has produced was found by a person looking at a property
+ * panel: a control drawn for something it cannot edit, or — worse — no control
+ * at all, with the field valid in the schema and present in the codec. Nothing
+ * failed, so nothing was reported, and the integration looked finished.
+ *
+ * TypeScript already rejects an unknown `kind` for a table written in
+ * TypeScript. This is for the tables that are not: `registerFieldTable` is a
+ * published entry point, adopters call it from plain JavaScript and from JSON
+ * they generated, and a misspelled kind there is currently a field that quietly
+ * becomes a text input over a value a text input destroys.
+ *
+ * It checks the kind only. It cannot tell whether the panel's control for a
+ * kind is the *right* control — that is what `FIELD_KINDS` and the editor's own
+ * exhaustiveness check are for.
+ */
+function assertDrawable(type, key, spec) {
+    const kind = spec.kind;
+    if (typeof kind === "string" && KNOWN_KINDS.includes(kind))
+        return;
+    throw new Error(`registerFieldTable: ${type}.${key} declares kind ${JSON.stringify(kind)}, which is not a field kind. `
+        + `Known kinds: ${KNOWN_KINDS.join(", ")}.`);
+}
+/**
+ * The kinds a table may declare.
+ *
+ * `FIELD_KINDS` is the panel's vocabulary; `list` is this layer's own, because
+ * a list is not a field — it travels the `listFields` channel instead and has
+ * no `FieldKind` spelling.
+ */
+const KNOWN_KINDS = [...FIELD_KINDS, "list"];
+export function registerFieldTable(table, options) {
+    const naming = options?.primitives?.imageNaming ?? suffixNaming("", "_alt");
+    const ctx = {
+        naming,
+        table,
+        rowIdKey: options?.primitives?.rowIdKey,
+        rowTypeKey: options?.primitives?.rowTypeKey,
+        visiting: new Set()
+    };
+    for (const [type, blockSpec] of Object.entries(table)) {
+        const shape = shapeForFields(blockSpec.fields, { ...ctx, visiting: new Set([type]) });
+        const fields = {};
+        const listFields = {};
+        for (const [key, spec] of Object.entries(blockSpec.fields)) {
+            assertDrawable(type, key, spec);
+            if (spec.kind === "imageList") {
+                listFields[key] = {
+                    label: spec.label ?? humanise(key),
+                    itemFields: { image: { kind: "image", label: "Image" }, alt: { kind: "imageAlt", label: "Alt text" } }
+                };
+                continue;
+            }
+            if (spec.kind === "list") {
+                listFields[key] = listMetaFor(key, spec, { ...ctx, visiting: new Set([type]) });
+                continue;
+            }
+            if (spec.kind === "image") {
+                fields[naming.url(key)] = metaForField(key, spec);
+                fields[naming.alt(key)] = { kind: "imageAlt", label: `${spec.label ?? humanise(key)} alt` };
+                continue;
+            }
+            fields[key] = metaForField(key, spec);
+        }
+        const meta = {
+            displayName: blockSpec.displayName,
+            fields,
+            ...(blockSpec.category ? { category: blockSpec.category } : {}),
+            ...(Object.keys(listFields).length > 0 ? { listFields } : {})
+        };
+        registerBlock(type, { schema: z.object(shape), meta });
+    }
+    if (options?.narrowCatalogue !== false) {
+        declareBlockCatalogue(Object.entries(table)
+            .filter(([, spec]) => spec.topLevel !== false)
+            .map(([type]) => type));
+    }
+}
+/**
+ * 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 function topLevelTypes(table) {
+    return Object.entries(table)
+        .filter(([, spec]) => spec.topLevel !== false)
+        .map(([type]) => type);
+}

package/dist/lens/sanity.d.ts

@@ -0,0 +1,28 @@
+import type { ImageNaming, LocaleLens, Primitives } from "./types.ts";
+/**
+ * A resolved image URL, which is a render of a reference and not the reference.
+ *
+ * This is why only the alt text below is writable. The URL a projection carries
+ * was built by the query that resolved `asset._ref` through the CDN; writing it
+ * back replaces a reference to an asset document with a string, which is
+ * precisely the overwrite a field-level publish diff exists to prevent.
+ */
+export declare function imageUrl(image: unknown): string;
+export declare function imageAlt(image: unknown): string;
+/**
+ * The locale lens for a site whose translatable fields are `{de, fr, en}`.
+ *
+ * One Sanity document becomes one Avocado page *per language*, because an
+ * Avocado prop is one value and this content model has three. `/preise` and
+ * `/fr/prix` are two pages backed by the same document.
+ */
+export declare function sanityLocale<L extends string>(defaultLang: L, languages: readonly L[]): LocaleLens<L>;
+/**
+ * The default naming is the one a tri-lingual Sanity site on Next 15 arrived
+ * at, and it is not a style choice: the asset picker recognises a field as an
+ * image by the `*imageUrl` / `*Image` name pattern, so an image field `hero`
+ * has to project to `heroUrl` for the picker to appear at all.
+ */
+export declare function sanityPrimitives(options?: {
+    imageNaming?: ImageNaming;
+}): Primitives;

package/dist/lens/sanity.js

@@ -0,0 +1,187 @@
+/*
+ * Sanity's answers to the same six questions.
+ *
+ * This pack exists as much to prove the abstraction as to serve Sanity. A codec
+ * interface derived from one CMS is a description of that CMS wearing a general
+ * name; the two that matter here disagree in every particular — a Storyblok
+ * asset is a flat object with a `filename`, a Sanity image is a reference to an
+ * asset document; Storyblok's rich text is the pivot itself, Sanity's is
+ * Portable Text; Storyblok localises into a suffixed sibling key, Sanity into a
+ * per-locale object under the key. Nothing above this file changes between the
+ * two, which is the claim.
+ */
+import { fromPortableText, toPortableText } from "@avocadostudio-ai/richtext";
+import { changed } from "./scalar-codecs.js";
+import { suffixNaming } from "./types.js";
+const isObj = (v) => v != null && typeof v === "object" && !Array.isArray(v);
+const str = (v) => (v == null ? "" : String(v));
+/**
+ * A resolved image URL, which is a render of a reference and not the reference.
+ *
+ * This is why only the alt text below is writable. The URL a projection carries
+ * was built by the query that resolved `asset._ref` through the CDN; writing it
+ * back replaces a reference to an asset document with a string, which is
+ * precisely the overwrite a field-level publish diff exists to prevent.
+ */
+export function imageUrl(image) {
+    if (!image)
+        return "";
+    if (typeof image === "string")
+        return image;
+    const img = image;
+    if (typeof img.url === "string")
+        return img.url;
+    const asset = isObj(img.asset) ? img.asset : undefined;
+    return str(asset?.url);
+}
+export function imageAlt(image) {
+    return isObj(image) ? str(image.alt) : "";
+}
+/**
+ * An image whose alt text is editable and whose asset is not.
+ *
+ * The asymmetry is deliberate and it is the honest shape: an editor changing
+ * alt text is editing content, and an editor "changing" the URL is proposing to
+ * repoint a reference at something the CMS has no record of.
+ */
+const imageCodec = (naming) => ({
+    project(key, raw) {
+        return { [naming.url(key)]: imageUrl(raw), [naming.alt(key)]: imageAlt(raw) };
+    },
+    merge(key, props, before) {
+        const altKey = naming.alt(key);
+        if (!(altKey in props))
+            return null;
+        const nextAlt = str(props[altKey]);
+        if (!changed(nextAlt, imageAlt(before)))
+            return null;
+        if (!isObj(before))
+            return null;
+        return { value: { ...before, alt: nextAlt } };
+    }
+});
+const fileCodec = {
+    project(key, raw) {
+        return { [key]: imageUrl(raw) };
+    },
+    merge() {
+        return null;
+    }
+};
+/**
+ * A reference, which is what Sanity stores every internal link as.
+ *
+ * Read as the href the query resolved; never written, for the same reason the
+ * image URL is never written — the stored value is a `_ref` and the href is one
+ * rendering of it, per locale.
+ */
+const referenceCodec = {
+    project(key, raw) {
+        if (typeof raw === "string")
+            return { [key]: raw };
+        const ref = isObj(raw) ? raw : undefined;
+        return { [key]: str(ref?.href ?? ref?.slug ?? "") };
+    },
+    merge(key, props, before) {
+        if (!(key in props))
+            return null;
+        const current = typeof before === "string" ? before : str(isObj(before) ? (before.href ?? before.slug) : "");
+        if (str(props[key]) === current)
+            return null;
+        return {
+            warning: `"${key}" points at a document in the CMS, not at a URL. Its address is derived from ` +
+                `that document — move or rename it in Sanity instead.`
+        };
+    },
+    fieldKind: "reference"
+};
+const richTextCodec = {
+    project(key, raw) {
+        return { [key]: fromPortableText(Array.isArray(raw) ? raw : []) };
+    },
+    merge(key, props, before) {
+        if (!(key in props))
+            return null;
+        /*
+         * Key-preserving on purpose. Portable Text blocks carry a `_key` that
+         * Sanity uses to address them, and a converter that mints fresh keys turns
+         * every edit into a full replacement of the array — which is a patch that
+         * conflicts with every other editor's concurrent patch, rather than one
+         * that merges with it.
+         */
+        const nextBlocks = toPortableText(props[key], { previous: Array.isArray(before) ? before : [] });
+        if (JSON.stringify(nextBlocks) === JSON.stringify(before ?? []))
+            return null;
+        const bothEmpty = nextBlocks.length === 0 && (!Array.isArray(before) || before.length === 0);
+        if (bothEmpty)
+            return null;
+        return { value: nextBlocks };
+    }
+};
+const imageListCodec = () => ({
+    project(key, raw) {
+        return {
+            [key]: (Array.isArray(raw) ? raw : []).map((img) => ({
+                image: imageUrl(img),
+                alt: imageAlt(img),
+                _key: isObj(img) ? img._key : undefined
+            }))
+        };
+    },
+    merge(key, props, before) {
+        if (!(key in props))
+            return null;
+        const items = Array.isArray(props[key]) ? props[key] : [];
+        const sourceItems = (Array.isArray(before) ? before : []);
+        const byKey = new Map(sourceItems.filter(isObj).map((row) => [row._key, row]));
+        const merged = items.map((item, i) => {
+            const src = (item._key !== undefined ? byKey.get(item._key) : undefined) ?? sourceItems[i] ?? {};
+            const alt = str(item.alt);
+            if (!isObj(src) || alt === imageAlt(src))
+                return src;
+            return { ...src, alt };
+        });
+        if (JSON.stringify(merged) === JSON.stringify(sourceItems))
+            return null;
+        return { value: merged };
+    }
+});
+/**
+ * The locale lens for a site whose translatable fields are `{de, fr, en}`.
+ *
+ * One Sanity document becomes one Avocado page *per language*, because an
+ * Avocado prop is one value and this content model has three. `/preise` and
+ * `/fr/prix` are two pages backed by the same document.
+ */
+export function sanityLocale(defaultLang, languages) {
+    return {
+        default: defaultLang,
+        languages,
+        path: (key, lang) => [key, lang]
+    };
+}
+/**
+ * The default naming is the one a tri-lingual Sanity site on Next 15 arrived
+ * at, and it is not a style choice: the asset picker recognises a field as an
+ * image by the `*imageUrl` / `*Image` name pattern, so an image field `hero`
+ * has to project to `heroUrl` for the picker to appear at all.
+ */
+export function sanityPrimitives(options) {
+    const imageNaming = options?.imageNaming ?? suffixNaming("Url", "Alt");
+    return {
+        imageNaming,
+        rowIdKey: "_key",
+        rowTypeKey: "_type",
+        newRowId: () => typeof crypto !== "undefined" && "randomUUID" in crypto
+            ? crypto.randomUUID().replace(/-/g, "").slice(0, 12)
+            : Math.random().toString(36).slice(2, 14),
+        codecs: {
+            image: imageCodec(imageNaming),
+            file: fileCodec,
+            link: referenceCodec,
+            reference: referenceCodec,
+            richtext: richTextCodec,
+            imageList: imageListCodec()
+        }
+    };
+}

package/dist/lens/scalar-codecs.d.ts

@@ -0,0 +1,26 @@
+import type { CodecContext, FieldCodec } from "./types.ts";
+/**
+ * Unchanged is not written, and empty is not written over absent.
+ *
+ * The second rule is the one that is easy to miss and expensive to discover.
+ * Writing `""` into a slot that had no value for this language looks like a
+ * no-op — the page rendered the fallback before and renders it after — and it
+ * is a real diff in the document, so a publish that touched one field reports
+ * every page as modified.
+ */
+export declare function changed(next: unknown, before: unknown): boolean;
+export declare const textCodec: FieldCodec;
+export declare const numberCodec: FieldCodec;
+export declare const booleanCodec: FieldCodec;
+/**
+ * A closed list, and a value outside it is refused rather than stored.
+ *
+ * The panel offers only the declared options, so an out-of-range value can only
+ * arrive from a planner — and storing one produces a page that renders its
+ * fallback branch with no error anywhere, which is the failure this whole file
+ * exists to stop being silent.
+ */
+export declare const enumCodec: FieldCodec;
+export declare const stringListCodec: FieldCodec;
+export declare const SCALAR_CODECS: Record<string, FieldCodec>;
+export type { CodecContext };

package/dist/lens/scalar-codecs.js

@@ -0,0 +1,92 @@
+/*
+ * The kinds no CMS shapes differently.
+ *
+ * A string is a string in Storyblok, Sanity, Contentful and Strapi; so is a
+ * number, a boolean, an enum value and a heading level. These carry no
+ * per-CMS answer, so a primitive pack that supplied them would be four copies
+ * of the same eight lines — and the eighth line, the one that decides whether a
+ * value counts as changed, is the one it is worst to get subtly different
+ * between two integrations.
+ */
+/**
+ * Unchanged is not written, and empty is not written over absent.
+ *
+ * The second rule is the one that is easy to miss and expensive to discover.
+ * Writing `""` into a slot that had no value for this language looks like a
+ * no-op — the page rendered the fallback before and renders it after — and it
+ * is a real diff in the document, so a publish that touched one field reports
+ * every page as modified.
+ */
+export function changed(next, before) {
+    if (next === before)
+        return false;
+    const nextEmpty = next === "" || next === undefined || next === null;
+    const beforeEmpty = before === "" || before === undefined || before === null;
+    return !(nextEmpty && beforeEmpty);
+}
+function scalar(read, write) {
+    return {
+        project(key, raw) {
+            return { [key]: read(raw) };
+        },
+        merge(key, props, before) {
+            if (!(key in props))
+                return null;
+            const next = write(props[key]);
+            return changed(next, read(before)) ? { value: next } : null;
+        }
+    };
+}
+const asText = (raw) => (raw == null ? "" : String(raw));
+export const textCodec = scalar(asText, asText);
+export const numberCodec = scalar((raw) => (typeof raw === "number" ? raw : Number(raw ?? 0) || 0), (next) => (typeof next === "number" ? next : Number(next ?? 0) || 0));
+export const booleanCodec = scalar((raw) => raw === true, (next) => next === true);
+/**
+ * A closed list, and a value outside it is refused rather than stored.
+ *
+ * The panel offers only the declared options, so an out-of-range value can only
+ * arrive from a planner — and storing one produces a page that renders its
+ * fallback branch with no error anywhere, which is the failure this whole file
+ * exists to stop being silent.
+ */
+export const enumCodec = {
+    project(key, raw) {
+        return { [key]: asText(raw) };
+    },
+    merge(key, props, before, ctx) {
+        if (!(key in props))
+            return null;
+        const next = asText(props[key]);
+        if (!changed(next, asText(before)))
+            return null;
+        const options = ctx.spec.kind === "enum" ? ctx.spec.options : [];
+        if (next !== "" && !options.includes(next)) {
+            return { warning: `"${next}" is not one of ${options.join(", ")}` };
+        }
+        return { value: next };
+    }
+};
+export const stringListCodec = {
+    project(key, raw) {
+        return { [key]: (Array.isArray(raw) ? raw : []).map(asText) };
+    },
+    merge(key, props, before) {
+        if (!(key in props))
+            return null;
+        const next = (Array.isArray(props[key]) ? props[key] : []).map(asText);
+        const prev = (Array.isArray(before) ? before : []).map(asText);
+        if (next.length === prev.length && next.every((v, i) => v === prev[i]))
+            return null;
+        if (next.length === 0 && prev.length === 0)
+            return null;
+        return { value: next };
+    }
+};
+export const SCALAR_CODECS = {
+    text: textCodec,
+    number: numberCodec,
+    boolean: booleanCodec,
+    enum: enumCodec,
+    headingLevel: textCodec,
+    stringList: stringListCodec
+};