@wocart/theme 1.3.0 → 1.5.0

package/dist/index.js

@@ -3,16 +3,24 @@
  *
  * Code-owned: `defineComponent` / `defineTheme` / `validateThemeDefinition`.
  * Data-owned: `parsePageData` / `validatePageData` / `resolveInstance` /
- * `createInstance` (+ schemas).
- * Serializable: `themeManifest` / `validateThemeManifest`.
+ * `createInstance` / `checkFieldValue`, and the document operations a writer
+ * applies (`insertInstance`, …, `checkPageData`).
+ * Serializable: `themeManifest` / `validateThemeManifest` /
+ * `manifestCatalog` / `diffThemeManifests`.
  *
  * This entry is framework-neutral. The reference Astro renderer lives in the
  * `./astro` subpath.
  */
 export { defineComponent, defineTheme, validateThemeDefinition } from "./definitions.js";
 export { parsePageData, validatePageData } from "./page-data.js";
-export { resolveInstance, createInstance } from "./instances.js";
+export { resolveInstance, createInstance, checkStoredValue as checkFieldValue } from "./instances.js";
+export { RICH_TEXT_FORMATS, richTextToHtml, richTextToPlainText } from "./rich-text.js";
+export { instantiatePreset, isInsertableOn } from "./composition.js";
+export { checkPageData, duplicateInstance, findInstance, insertInstance, moveInstance, newInstanceId, removeInstance, setInstanceHidden, setInstanceProps, } from "./operations.js";
+export { THEME_SDK_VERSION } from "./version.js";
 export { resolveThemeSettings, checkThemeSettings } from "./settings.js";
 export { localize } from "./locales.js";
 export { PLURAL_CATEGORIES, formatMessage, messageForms, pluralFormIssues } from "./messages.js";
-export { THEME_MANIFEST_CONTRACT_VERSION, themeManifest, validateThemeManifest, } from "./manifest.js";
+export { THEME_MANIFEST_CONTRACT_VERSION, THEME_MANIFEST_PATH, manifestCatalog, themeManifest, validateThemeManifest, } from "./manifest.js";
+export { diffThemeManifests } from "./manifest-diff.js";
+export { PREVIEW_PROTOCOL_VERSION, THEME_PREVIEW_PATH, parsePreviewMarker, previewEndMarker, previewStartMarker, } from "./preview-protocol.js";

package/dist/instances.d.ts

@@ -12,6 +12,8 @@ export type CheckedValue = {
     ok: false;
     message: string;
 };
+/** Whether a field shows something with no stored value: a default, or content-pack text. */
+export declare function hasFallback(field: FieldDefinition): boolean;
 /** An own property only: `constructor` or `toString` must never read the prototype. */
 export declare function ownValue<T>(record: Record<string, T>, key: string): T | undefined;
 /**
@@ -23,9 +25,13 @@ export declare function resolveField(field: FieldDefinition, raw: unknown, conte
 /**
  * What a writer may store: a value that passes the field's rules, or — for a
  * translatable field — a per-language map whose every entry passes them, so no
- * language can hold an unsafe link or a wrong type.
+ * language can hold an unsafe link or a wrong type. Stricter than reading: an
+ * image reference or list item with keys the contract does not define is
+ * refused, never stripped.
  */
 export declare function checkStoredValue(field: FieldDefinition, value: unknown): CheckedValue;
+/** On a grid of `step` from `base`, allowing for binary floating point. */
+export declare function onStepGrid(value: number, base: number, step: number): boolean;
 /**
  * Create a new instance with insertion-time defaults:
  * materialises `field.default` values only — content-keyed fields stay unset

package/dist/instances.js

@@ -9,9 +9,14 @@
  * default applies last).
  */
 import { localize } from "./locales.js";
-import { COLLECTION_HANDLE_PATTERN, COLOR_PATTERN, MENU_HANDLE_PATTERN, isLocaleMap, isSafeLinkTarget } from "./schemas.js";
-/** Field kinds whose values may differ per language. Numbers, toggles and choices are shared. */
-const TRANSLATABLE_KINDS = new Set(["text", "textarea", "url"]);
+import { isRichTextDocumentShape, richTextProblem } from "./rich-text.js";
+import { COLLECTION_HANDLE_PATTERN, COLOR_PATTERN, MEDIA_KEY_PATTERN, MENU_HANDLE_PATTERN, RESOURCE_HANDLE_PATTERN, isLocaleMap, isLocaleMapOf, isSafeLinkTarget, } from "./schemas.js";
+/**
+ * Field kinds whose values may differ per language. Numbers, toggles, choices,
+ * references and images are shared (an image's alt text is per language).
+ */
+const TRANSLATABLE_KINDS = new Set(["text", "textarea", "url", "richtext"]);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const isTranslatable = (field) => TRANSLATABLE_KINDS.has(field.kind);
 /**
  * Gate one instance for rendering: field values through the chain, children
@@ -81,16 +86,39 @@ export function resolveInstance(definition, instance, scope = {}) {
     }
     return { props, children, slots, issues };
 }
+/** Whether a field shows something with no stored value: a default, or content-pack text. */
+export function hasFallback(field) {
+    if ((field.kind === "text" || field.kind === "textarea") && field.contentKey !== undefined)
+        return true;
+    return "default" in field && field.default !== undefined;
+}
 /** An own property only: `constructor` or `toString` must never read the prototype. */
 export function ownValue(record, key) {
     return Object.hasOwn(record, key) ? record[key] : undefined;
 }
+/** The entry for the first language in `locales` that `map` has. */
+function pickLocale(map, locales) {
+    for (const locale of locales) {
+        if (Object.hasOwn(map, locale))
+            return map[locale];
+    }
+    return undefined;
+}
 /**
  * The value an instance stores for this field, in the preferred language. A
  * per-language map without an entry for any preferred language is not an
  * error — the chain moves on to the pack and the default.
  */
 function storedValueFor(field, raw, locales) {
+    if (field.kind === "richtext") {
+        if (isRichTextDocumentShape(raw))
+            return { kind: "value", value: raw };
+        if (!isLocaleMapOf(raw, isRecord)) {
+            return { kind: "invalid", message: "must be a rich-text document or a map from language tags to documents" };
+        }
+        const picked = pickLocale(raw, locales);
+        return picked === undefined ? { kind: "untranslated" } : { kind: "value", value: picked };
+    }
     if (!isTranslatable(field) || typeof raw !== "object" || raw === null || Array.isArray(raw)) {
         return { kind: "value", value: raw };
     }
@@ -109,15 +137,18 @@ function storedValueFor(field, raw, locales) {
  * `settings`.
  */
 export function resolveField(field, raw, content, locales, issues, prefix) {
+    if (field.kind === "list") {
+        return resolveListField(field, raw, content, locales, issues, prefix);
+    }
     if (raw !== undefined) {
         const stored = storedValueFor(field, raw, locales);
         const checked = stored.kind === "value"
-            ? checkFieldValue(field, stored.value)
+            ? checkKindValue(field, stored.value, "read")
             : stored.kind === "invalid"
                 ? { ok: false, message: stored.message }
                 : undefined;
         if (checked?.ok) {
-            return checked.value;
+            return presentValue(field, checked.value, locales);
         }
         if (checked !== undefined) {
             issues.push({
@@ -136,10 +167,14 @@ export function resolveField(field, raw, content, locales, issues, prefix) {
             }
         }
     }
-    if (field.default !== undefined) {
+    if (field.kind !== "image" && field.default !== undefined) {
         const fallback = field.kind === "text" || field.kind === "textarea"
             ? localize(field.default, locales)
-            : field.default;
+            : field.kind === "richtext"
+                ? isRichTextDocumentShape(field.default)
+                    ? field.default
+                    : pickLocale(field.default, locales)
+                : field.default;
         if (fallback !== undefined) {
             return fallback;
         }
@@ -153,27 +188,209 @@ export function resolveField(field, raw, content, locales, issues, prefix) {
     }
     return undefined;
 }
+/** A checked value as the component receives it: an image's alt in the rendered language. */
+function presentValue(field, value, locales) {
+    if (field.kind !== "image")
+        return value;
+    const reference = value;
+    const image = { key: reference.key };
+    if (reference.alt !== undefined) {
+        const alt = typeof reference.alt === "string" ? reference.alt : localize(reference.alt, locales);
+        if (alt !== undefined)
+            image.alt = alt;
+    }
+    if (reference.width !== undefined)
+        image.width = reference.width;
+    if (reference.height !== undefined)
+        image.height = reference.height;
+    if (reference.focal !== undefined) {
+        const focal = reference.focal;
+        image.focal = { x: focal.x, y: focal.y };
+    }
+    return image;
+}
+/**
+ * A list through the chain: the stored items when the value is a list (each
+ * item checked on its own, so one bad item never costs the others), else the
+ * default items.
+ */
+function resolveListField(field, raw, content, locales, issues, prefix) {
+    const path = `${prefix}.${field.key}`;
+    if (raw !== undefined) {
+        if (Array.isArray(raw))
+            return resolveListItems(field, raw, content, locales, issues, path);
+        issues.push({ path, code: "invalid-prop", message: `"${field.key}" must be a list of items; treated as absent` });
+    }
+    if (field.default !== undefined) {
+        // Defaults are checked when the theme is assembled; their resolution reports nothing.
+        return resolveListItems(field, field.default, content, locales, [], path);
+    }
+    if (field.required === true) {
+        issues.push({ path, code: "missing-required-prop", message: `required field "${field.key}" has no value` });
+    }
+    return undefined;
+}
+function resolveListItems(field, raw, content, locales, issues, path) {
+    const declared = new Set(field.fields.map((itemField) => itemField.key));
+    const seenIds = new Set();
+    const items = [];
+    raw.forEach((item, index) => {
+        const itemPath = `${path}[${index}]`;
+        if (!isRecord(item) || typeof item.id !== "string" || item.id.length === 0) {
+            issues.push({ path: itemPath, code: "invalid-prop", message: "a list item must be an object with a non-empty string `id`; dropped" });
+            return;
+        }
+        if (seenIds.has(item.id)) {
+            issues.push({ path: `${itemPath}.id`, code: "duplicate-id", message: `duplicate list item id "${item.id}"; the later item is dropped` });
+            return;
+        }
+        seenIds.add(item.id);
+        let props = {};
+        if (isRecord(item.props)) {
+            props = item.props;
+        }
+        else if (item.props !== undefined) {
+            issues.push({ path: `${itemPath}.props`, code: "invalid-prop", message: "`props` must be an object; the item's fields fall back to their defaults" });
+        }
+        for (const key of Object.keys(props)) {
+            if (!declared.has(key)) {
+                issues.push({ path: `${itemPath}.props.${key}`, code: "unknown-prop", message: `"${key}" is not a declared field of the "${field.key}" items` });
+            }
+        }
+        const resolved = { id: item.id };
+        for (const itemField of field.fields) {
+            if (itemField.key === "id")
+                continue;
+            const value = resolveField(itemField, ownValue(props, itemField.key), content, locales, issues, `${itemPath}.props`);
+            if (value !== undefined)
+                resolved[itemField.key] = value;
+        }
+        items.push(resolved);
+    });
+    if (field.max !== undefined && items.length > field.max) {
+        issues.push({ path, code: "invalid-prop", message: `"${field.key}" has ${items.length} items; only the first ${field.max} are kept` });
+        items.length = field.max;
+    }
+    if (field.min !== undefined && items.length < field.min) {
+        issues.push({ path, code: "invalid-prop", message: `"${field.key}" has ${items.length} items; at least ${field.min} expected` });
+    }
+    return items;
+}
 /**
  * What a writer may store: a value that passes the field's rules, or — for a
  * translatable field — a per-language map whose every entry passes them, so no
- * language can hold an unsafe link or a wrong type.
+ * language can hold an unsafe link or a wrong type. Stricter than reading: an
+ * image reference or list item with keys the contract does not define is
+ * refused, never stripped.
  */
 export function checkStoredValue(field, value) {
+    if (field.kind === "list")
+        return checkStoredList(field, value);
+    if (field.kind === "richtext") {
+        if (isRichTextDocumentShape(value))
+            return checkKindValue(field, value, "write");
+        if (!isLocaleMapOf(value, isRecord)) {
+            return { ok: false, message: "must be a rich-text document or a map from language tags to documents" };
+        }
+        for (const [locale, document] of Object.entries(value)) {
+            const checked = checkKindValue(field, document, "write");
+            if (!checked.ok)
+                return { ok: false, message: `(${locale}) ${checked.message}` };
+        }
+        return { ok: true, value };
+    }
     if (!isTranslatable(field) || typeof value !== "object" || value === null || Array.isArray(value)) {
-        return checkFieldValue(field, value);
+        return checkKindValue(field, value, "write");
     }
     if (!isLocaleMap(value)) {
         return { ok: false, message: "must be a string or a map from language tags to strings" };
     }
     for (const [locale, text] of Object.entries(value)) {
-        const checked = checkFieldValue(field, text);
+        const checked = checkKindValue(field, text, "write");
         if (!checked.ok)
             return { ok: false, message: `(${locale}) ${checked.message}` };
     }
     return { ok: true, value };
 }
-/** Kind check shared by resolution and creation. */
-function checkFieldValue(field, value) {
+function checkStoredList(field, value) {
+    if (!Array.isArray(value))
+        return { ok: false, message: "must be a list of items" };
+    if (field.min !== undefined && value.length < field.min)
+        return { ok: false, message: `must have at least ${field.min} items` };
+    if (field.max !== undefined && value.length > field.max)
+        return { ok: false, message: `must have at most ${field.max} items` };
+    const itemFields = new Map(field.fields.map((itemField) => [itemField.key, itemField]));
+    const seenIds = new Set();
+    for (const [index, item] of value.entries()) {
+        if (!isRecord(item))
+            return { ok: false, message: `item ${index} must be an object` };
+        const extra = Object.keys(item).find((key) => key !== "id" && key !== "props");
+        if (extra !== undefined)
+            return { ok: false, message: `item ${index} has an unknown key "${extra}"` };
+        if (typeof item.id !== "string" || item.id.length === 0)
+            return { ok: false, message: `item ${index} needs a non-empty string \`id\`` };
+        if (seenIds.has(item.id))
+            return { ok: false, message: `item ${index} repeats the id "${item.id}"` };
+        seenIds.add(item.id);
+        if (item.props === undefined)
+            continue;
+        if (!isRecord(item.props))
+            return { ok: false, message: `item ${index}: \`props\` must be an object` };
+        for (const [key, propValue] of Object.entries(item.props)) {
+            const itemField = itemFields.get(key);
+            if (itemField === undefined)
+                return { ok: false, message: `item ${index}: "${key}" is not a declared field` };
+            const checked = checkStoredValue(itemField, propValue);
+            if (!checked.ok)
+                return { ok: false, message: `item ${index}: "${key}" ${checked.message}` };
+        }
+    }
+    return { ok: true, value };
+}
+const MEDIA_REFERENCE_KEYS = ["key", "alt", "width", "height", "focal"];
+const isUnitInterval = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+/** Why `value` is not an image reference, or `null`. `write` refuses keys the contract does not define. */
+function mediaReferenceProblem(value, mode) {
+    if (!isRecord(value))
+        return "must be an image reference { key, alt?, width?, height?, focal? }";
+    if (mode === "write") {
+        const extra = Object.keys(value).find((key) => !MEDIA_REFERENCE_KEYS.includes(key));
+        if (extra !== undefined)
+            return `has an unknown key "${extra}"`;
+    }
+    if (typeof value.key !== "string" || !MEDIA_KEY_PATTERN.test(value.key)) {
+        return "must have a `key` naming an object in the store's media (namespace/name, no `..`)";
+    }
+    if (value.alt !== undefined && typeof value.alt !== "string" && !isLocaleMap(value.alt)) {
+        return "`alt` must be a string or a map from language tags to strings";
+    }
+    for (const dimension of ["width", "height"]) {
+        const size = value[dimension];
+        if (size !== undefined && !(typeof size === "number" && Number.isInteger(size) && size > 0)) {
+            return `\`${dimension}\` must be a positive whole number of pixels`;
+        }
+    }
+    if (value.focal !== undefined) {
+        const focal = value.focal;
+        const shapeOk = isRecord(focal) &&
+            isUnitInterval(focal.x) &&
+            isUnitInterval(focal.y) &&
+            (mode === "read" || Object.keys(focal).every((key) => key === "x" || key === "y"));
+        if (!shapeOk)
+            return "`focal` must be { x, y }, each between 0 and 1";
+    }
+    return null;
+}
+/** On a grid of `step` from `base`, allowing for binary floating point. */
+export function onStepGrid(value, base, step) {
+    const steps = (value - base) / step;
+    return Math.abs(steps - Math.round(steps)) <= 1e-9 * Math.max(1, Math.abs(steps));
+}
+/**
+ * Kind check shared by resolution (`read`) and writing (`write`). Lists are
+ * checked item by item by their own paths, never here.
+ */
+function checkKindValue(field, value, mode) {
     switch (field.kind) {
         case "text":
         case "textarea":
@@ -190,6 +407,9 @@ function checkFieldValue(field, value) {
             if (field.max !== undefined && value > field.max) {
                 return { ok: false, message: `must be <= ${field.max}` };
             }
+            if (field.step !== undefined && !onStepGrid(value, field.min ?? 0, field.step)) {
+                return { ok: false, message: `must be a multiple of ${field.step} from ${field.min ?? 0}` };
+            }
             return { ok: true, value };
         }
         case "boolean":
@@ -215,6 +435,24 @@ function checkFieldValue(field, value) {
             return typeof value === "string" && COLLECTION_HANDLE_PATTERN.test(value)
                 ? { ok: true, value }
                 : { ok: false, message: "must be a collection handle" };
+        case "product":
+            return typeof value === "string" && RESOURCE_HANDLE_PATTERN.test(value)
+                ? { ok: true, value }
+                : { ok: false, message: "must be a product handle" };
+        case "category":
+            return typeof value === "string" && RESOURCE_HANDLE_PATTERN.test(value)
+                ? { ok: true, value }
+                : { ok: false, message: "must be a category slug" };
+        case "image": {
+            const problem = mediaReferenceProblem(value, mode);
+            return problem === null ? { ok: true, value } : { ok: false, message: problem };
+        }
+        case "richtext": {
+            const problem = richTextProblem(value, field.formats);
+            return problem === null ? { ok: true, value } : { ok: false, message: problem };
+        }
+        case "list":
+            return checkStoredList(field, value);
         case "select":
             return typeof value === "string" && field.options.includes(value)
                 ? { ok: true, value }
@@ -290,7 +528,7 @@ export function createInstance(definition, id, props = {}) {
             materialized[field.key] = provided;
             continue;
         }
-        if (field.default !== undefined) {
+        if (field.kind !== "image" && field.default !== undefined) {
             const checked = checkStoredValue(field, field.default);
             if (!checked.ok) {
                 throw new TypeError(`createInstance: default for "${field.key}" ${checked.message}`);

package/dist/manifest-diff.d.ts

@@ -0,0 +1,14 @@
+import type { ThemeManifest } from "./types.js";
+/** One difference, located by a path into the manifest. */
+export interface ManifestChange {
+    path: string;
+    message: string;
+}
+export interface ManifestDiff {
+    /** Changes saved documents, settings or text edits may not survive. */
+    breaking: ManifestChange[];
+    /** Changes that only add. */
+    additive: ManifestChange[];
+}
+/** Compare a theme's manifest with its next version's. */
+export declare function diffThemeManifests(previous: ThemeManifest, next: ThemeManifest): ManifestDiff;

package/dist/manifest-diff.js

@@ -0,0 +1,160 @@
+/**
+ * What changes between two versions of a theme, for the documents and
+ * settings merchants already saved. A change is breaking when a saved value
+ * could stop being read as it was: something removed or renamed, a kind
+ * changed, a rule narrowed, a field newly required with nothing to fill it.
+ * Everything else is additive. Saved data is never migrated: the reader
+ * degrades with reports, and this diff says beforehand what will degrade.
+ */
+import { hasFallback } from "./instances.js";
+/** Compare a theme's manifest with its next version's. */
+export function diffThemeManifests(previous, next) {
+    const diff = { breaking: [], additive: [] };
+    const breaking = (path, message) => diff.breaking.push({ path, message });
+    const additive = (path, message) => diff.additive.push({ path, message });
+    if (previous.key !== next.key) {
+        breaking("key", `the theme key changed from "${previous.key}" to "${next.key}": every saved edit is keyed by it`);
+    }
+    for (const locale of previous.locales) {
+        if (!next.locales.includes(locale))
+            breaking("locales", `the theme no longer covers "${locale}"`);
+    }
+    for (const locale of next.locales) {
+        if (!previous.locales.includes(locale))
+            additive("locales", `the theme now covers "${locale}"`);
+    }
+    const nextSurfaces = new Map(next.surfaces.map((surface) => [surface.key, surface]));
+    for (const surface of previous.surfaces) {
+        const after = nextSurfaces.get(surface.key);
+        if (after === undefined)
+            breaking(`surfaces.${surface.key}`, `surface "${surface.key}" was removed`);
+        else if (after.pageType !== surface.pageType) {
+            breaking(`surfaces.${surface.key}.pageType`, `surface "${surface.key}" renders "${after.pageType ?? "no page type"}" instead of "${surface.pageType ?? "no page type"}"`);
+        }
+    }
+    for (const surface of next.surfaces) {
+        if (!previous.surfaces.some((before) => before.key === surface.key))
+            additive(`surfaces.${surface.key}`, `surface "${surface.key}" was added`);
+    }
+    const settingFields = (manifest) => manifest.settings.flatMap((group) => group.fields);
+    compareFields(settingFields(previous), settingFields(next), "settings", breaking, additive);
+    for (const [locale, pack] of Object.entries(previous.content)) {
+        const after = next.content[locale] ?? {};
+        for (const key of Object.keys(pack)) {
+            if (!Object.hasOwn(after, key))
+                breaking(`content.${locale}.${key}`, `content key "${key}" (${locale}) was removed: a merchant's edit of it no longer shows`);
+        }
+    }
+    for (const [type, spec] of Object.entries(previous.components)) {
+        const after = next.components[type];
+        if (after === undefined) {
+            breaking(`components.${type}`, `component "${type}" was removed: saved instances of it render nothing`);
+            continue;
+        }
+        compareComponents(spec, after, `components.${type}`, breaking, additive);
+    }
+    for (const type of Object.keys(next.components)) {
+        if (!Object.hasOwn(previous.components, type))
+            additive(`components.${type}`, `component "${type}" was added`);
+    }
+    return diff;
+}
+function compareComponents(previous, next, path, breaking, additive) {
+    compareFields(previous.fields, next.fields, `${path}.fields`, breaking, additive);
+    const nextSlots = new Map(next.slots.map((slot) => [slot.name, slot]));
+    for (const slot of previous.slots) {
+        const after = nextSlots.get(slot.name);
+        if (after === undefined) {
+            breaking(`${path}.slots.${slot.name}`, `slot "${slot.name}" was removed: its saved children are dropped`);
+            continue;
+        }
+        compareSlots(slot, after, `${path}.slots.${slot.name}`, breaking, additive);
+    }
+    for (const slot of next.slots) {
+        if (!previous.slots.some((before) => before.name === slot.name))
+            additive(`${path}.slots.${slot.name}`, `slot "${slot.name}" was added`);
+    }
+}
+function compareSlots(previous, next, path, breaking, additive) {
+    if (previous.multiple !== false && next.multiple === false) {
+        breaking(`${path}.multiple`, "the slot now holds one instance: saved extra children are dropped");
+    }
+    else if (previous.multiple === false && next.multiple !== false) {
+        additive(`${path}.multiple`, "the slot now holds several instances");
+    }
+    if (next.allow !== undefined) {
+        const removed = previous.allow === undefined ? undefined : previous.allow.filter((type) => !next.allow.includes(type));
+        if (previous.allow === undefined)
+            breaking(`${path}.allow`, `the slot now accepts only ${next.allow.join(", ")}`);
+        else if (removed !== undefined && removed.length > 0)
+            breaking(`${path}.allow`, `the slot no longer accepts ${removed.join(", ")}`);
+        const added = previous.allow === undefined ? [] : next.allow.filter((type) => !previous.allow.includes(type));
+        if (added.length > 0)
+            additive(`${path}.allow`, `the slot now also accepts ${added.join(", ")}`);
+    }
+    else if (previous.allow !== undefined) {
+        additive(`${path}.allow`, "the slot now accepts any component");
+    }
+}
+function compareFields(previous, next, path, breaking, additive) {
+    const nextFields = new Map(next.map((field) => [field.key, field]));
+    for (const field of previous) {
+        const fieldPath = `${path}.${field.key}`;
+        const after = nextFields.get(field.key);
+        if (after === undefined) {
+            breaking(fieldPath, `field "${field.key}" was removed: saved values for it are ignored`);
+            continue;
+        }
+        if (after.kind !== field.kind) {
+            breaking(`${fieldPath}.kind`, `field "${field.key}" changed kind from ${field.kind} to ${after.kind}: saved values no longer read`);
+            continue;
+        }
+        if (after.required === true && field.required !== true && !hasFallback(after)) {
+            breaking(`${fieldPath}.required`, `field "${field.key}" is now required with no default`);
+        }
+        compareKindRules(field, after, fieldPath, breaking, additive);
+    }
+    for (const field of next) {
+        if (previous.some((before) => before.key === field.key))
+            continue;
+        if (field.required === true && !hasFallback(field)) {
+            breaking(`${path}.${field.key}`, `required field "${field.key}" was added with no default: saved instances lack it`);
+        }
+        else {
+            additive(`${path}.${field.key}`, `field "${field.key}" was added`);
+        }
+    }
+}
+function compareKindRules(previous, next, path, breaking, additive) {
+    if (previous.kind === "select" && next.kind === "select") {
+        const removed = previous.options.filter((option) => !next.options.includes(option));
+        if (removed.length > 0)
+            breaking(`${path}.options`, `options ${removed.map((option) => `"${option}"`).join(", ")} were removed`);
+        const added = next.options.filter((option) => !previous.options.includes(option));
+        if (added.length > 0)
+            additive(`${path}.options`, `options ${added.map((option) => `"${option}"`).join(", ")} were added`);
+    }
+    if (previous.kind === "number" && next.kind === "number") {
+        if (next.min !== undefined && (previous.min === undefined || next.min > previous.min))
+            breaking(`${path}.min`, `the minimum rose to ${next.min}`);
+        if (next.max !== undefined && (previous.max === undefined || next.max < previous.max))
+            breaking(`${path}.max`, `the maximum fell to ${next.max}`);
+        if (next.step !== undefined && next.step !== previous.step)
+            breaking(`${path}.step`, `values must now be multiples of ${next.step}`);
+    }
+    if (previous.kind === "richtext" && next.kind === "richtext" && next.formats !== undefined) {
+        const before = previous.formats;
+        const removed = before === undefined ? undefined : before.filter((format) => !next.formats.includes(format));
+        if (before === undefined)
+            breaking(`${path}.formats`, `the field now allows only ${next.formats.join(", ")}`);
+        else if (removed !== undefined && removed.length > 0)
+            breaking(`${path}.formats`, `the field no longer allows ${removed.join(", ")}`);
+    }
+    if (previous.kind === "list" && next.kind === "list") {
+        if (next.max !== undefined && (previous.max === undefined || next.max < previous.max))
+            breaking(`${path}.max`, `the list now holds at most ${next.max} items`);
+        if (next.min !== undefined && (previous.min === undefined || next.min > previous.min))
+            breaking(`${path}.min`, `the list now needs at least ${next.min} items`);
+        compareFields(previous.fields, next.fields, `${path}.fields`, breaking, additive);
+    }
+}