@wocart/theme 1.4.0 → 1.6.0

package/dist/composition.js

@@ -0,0 +1,60 @@
+/**
+ * Composition rules a writer applies when it adds a component to a document:
+ * where a component may go, and how a preset becomes instances. Pure: no
+ * I/O, no randomness — ids come from the caller.
+ */
+import { createInstance } from "./instances.js";
+/** Whether a surface key is `entry` itself or one of its alternates (`product.compact` for `product`). */
+export function surfaceCovers(entry, surface) {
+    return surface === entry || surface.startsWith(`${entry}.`);
+}
+/**
+ * Whether an editor may insert this component on `surface`: it is not marked
+ * `insertable: false`, and its `capabilities.surfaces` (absent = any surface)
+ * cover the surface. Accepts a definition or its manifest spec.
+ */
+export function isInsertableOn(component, surface) {
+    const capabilities = component.capabilities;
+    if (capabilities?.insertable === false)
+        return false;
+    const surfaces = capabilities?.surfaces;
+    return surfaces === undefined || surfaces.some((entry) => surfaceCovers(entry, surface));
+}
+/**
+ * The instances a preset describes: the component with the preset's props
+ * over its field defaults (`createInstance`), and every child component the
+ * same way, each with an id from `newId`. Throws on what is a programming
+ * error — an unknown component or preset, or props its fields refuse — as
+ * `createInstance` does; `validateThemeDefinition` reports these at assembly.
+ */
+export function instantiatePreset(theme, type, presetKey, newId) {
+    const definition = Object.hasOwn(theme.components, type) ? theme.components[type] : undefined;
+    if (definition === undefined)
+        throw new TypeError(`instantiatePreset: "${type}" is not in the theme catalog`);
+    const preset = (definition.presets ?? []).find((candidate) => candidate.key === presetKey);
+    if (preset === undefined)
+        throw new TypeError(`instantiatePreset: "${type}" has no preset "${presetKey}"`);
+    return build(theme, { ...presetBody(preset), type }, newId);
+}
+function presetBody(preset) {
+    const body = {};
+    if (preset.props !== undefined)
+        body.props = preset.props;
+    if (preset.children !== undefined)
+        body.children = preset.children;
+    if (preset.slots !== undefined)
+        body.slots = preset.slots;
+    return body;
+}
+function build(theme, node, newId) {
+    const definition = Object.hasOwn(theme.components, node.type) ? theme.components[node.type] : undefined;
+    if (definition === undefined)
+        throw new TypeError(`instantiatePreset: "${node.type}" is not in the theme catalog`);
+    const instance = createInstance(definition, newId(), node.props ?? {});
+    if (node.children !== undefined)
+        instance.children = node.children.map((child) => build(theme, child, newId));
+    if (node.slots !== undefined) {
+        instance.slots = Object.fromEntries(Object.entries(node.slots).map(([name, list]) => [name, list.map((child) => build(theme, child, newId))]));
+    }
+    return instance;
+}

package/dist/definitions.js

@@ -4,7 +4,11 @@
  * data — the validator exists so a theme's test suite fails loudly on catalog
  * bugs when the catalog is assembled.
  */
-import { COLOR_PATTERN, MENU_HANDLE_PATTERN, COLLECTION_HANDLE_PATTERN, SURFACE_KEY_PATTERN, THEME_KEY_PATTERN, TYPE_KEY_PATTERN, isLocaleMap, isLocaleTag, isSafeLinkTarget, } from "./schemas.js";
+import { instantiatePreset } from "./composition.js";
+import { checkStoredValue, onStepGrid } from "./instances.js";
+import { validatePageData } from "./page-data.js";
+import { RICH_TEXT_FORMATS, isRichTextDocumentShape, richTextProblem } from "./rich-text.js";
+import { COLOR_PATTERN, MENU_HANDLE_PATTERN, COLLECTION_HANDLE_PATTERN, PAGE_TYPES, RESOURCE_HANDLE_PATTERN, SURFACE_KEY_PATTERN, THEME_KEY_PATTERN, TYPE_KEY_PATTERN, isLocaleMap, isLocaleMapOf, isLocaleTag, isSafeLinkTarget, } from "./schemas.js";
 export function defineComponent(definition) {
     return definition;
 }
@@ -61,7 +65,6 @@ function inspectLocales(locales, issues) {
 /** Check the whole catalog: key/type identity, field rules, slot rules. */
 export function validateThemeDefinition(theme, options = {}) {
     const issues = [];
-    const contentKeys = options.contentKeys === undefined ? undefined : new Set(options.contentKeys);
     if (!isRecord(theme)) {
         addIssue(issues, "", "invalid-theme", "theme must be an object");
         return issues;
@@ -77,6 +80,12 @@ export function validateThemeDefinition(theme, options = {}) {
         return issues;
     }
     const locales = inspectLocales(theme.locales, issues);
+    if (theme.preview !== undefined && typeof theme.preview !== "boolean") {
+        addIssue(issues, "preview", "invalid-theme", "`preview` must be a boolean");
+    }
+    const packKeys = theme.content === undefined ? undefined : inspectContent(theme.content, issues, locales, theme.locales !== undefined);
+    // An explicit key set wins; declared packs supply one otherwise.
+    const contentKeys = options.contentKeys !== undefined ? new Set(options.contentKeys) : packKeys;
     // Surfaces are optional theme-level metadata for the serializable manifest
     // (`themeManifest`). Absent means "declares none"; present entries are
     // checked so a typo fails loudly at assembly time. Never consulted by page
@@ -93,6 +102,9 @@ export function validateThemeDefinition(theme, options = {}) {
         contentKeys,
         catalogKeys: new Set(Object.keys(theme.components)),
         locales,
+        surfaceKeys: new Set((Array.isArray(theme.surfaces) ? theme.surfaces : [])
+            .map((surface) => (isRecord(surface) ? surface.key : undefined))
+            .filter((key) => typeof key === "string")),
     };
     if (theme.settings !== undefined)
         inspectSettings(theme.settings, issues, rules);
@@ -108,8 +120,91 @@ export function validateThemeDefinition(theme, options = {}) {
             addIssue(issues, `${path}.type`, "type-mismatch", `definition type "${definition.type}" must equal its catalog key "${key}"`);
         }
     }
+    // Documents and presets are read through the catalog, so they are checked
+    // once the catalog itself is sound.
+    if (issues.length === 0)
+        inspectComposition(theme, issues);
     return issues;
 }
+/**
+ * The theme's own packs: one per language, each a map of keys to text.
+ * Returns the keys every pack has — what a `contentKey` may name.
+ */
+function inspectContent(content, issues, locales, localesDeclared) {
+    if (!isRecord(content)) {
+        addIssue(issues, "content", "invalid-content", "`content` must map language tags to content packs");
+        return undefined;
+    }
+    // An empty map declares no packs, as an absent one does (the manifest normalizes to it).
+    if (Object.keys(content).length === 0)
+        return undefined;
+    let common;
+    for (const [locale, pack] of Object.entries(content)) {
+        const path = `content.${locale}`;
+        if (!isLocaleTag(locale)) {
+            addIssue(issues, path, "invalid-content", `${JSON.stringify(locale)} is not a BCP 47 language tag in canonical case`);
+            continue;
+        }
+        if (localesDeclared && !locales.includes(locale)) {
+            addIssue(issues, path, "invalid-content", `"${locale}" is not one of the theme's languages`);
+        }
+        if (!isRecord(pack)) {
+            addIssue(issues, path, "invalid-content", "a content pack must map keys to text");
+            continue;
+        }
+        for (const [key, text] of Object.entries(pack)) {
+            if (key.length === 0 || key === "__proto__" || typeof text !== "string") {
+                addIssue(issues, `${path}.${key}`, "invalid-content", "a content pack maps non-empty keys to strings");
+            }
+        }
+        const keys = new Set(Object.keys(pack));
+        common = common === undefined ? keys : new Set([...common].filter((key) => keys.has(key)));
+    }
+    for (const locale of locales) {
+        if (!Object.hasOwn(content, locale)) {
+            addIssue(issues, `content.${locale}`, "invalid-content", `the theme declares "${locale}" but ships no content pack for it`);
+        }
+    }
+    return common;
+}
+/** Default documents and presets, read through the (sound) catalog as a writer would. */
+function inspectComposition(theme, issues) {
+    (theme.surfaces ?? []).forEach((surface, index) => {
+        if (surface.document === undefined)
+            return;
+        const path = `surfaces[${index}].document`;
+        const checked = validatePageData(theme, surface.document);
+        if (checked.page !== null && checked.page.surface !== surface.key) {
+            addIssue(issues, `${path}.surface`, "invalid-document", `the default document is for "${checked.page.surface}", not "${surface.key}"`);
+        }
+        for (const issue of checked.issues) {
+            // Content-keyed text is filled from the store's pack at render.
+            if (issue.code === "missing-required-prop")
+                continue;
+            addIssue(issues, issue.path === "" ? path : `${path}.${issue.path}`, "invalid-document", issue.message);
+        }
+    });
+    for (const [type, definition] of Object.entries(theme.components)) {
+        (definition.presets ?? []).forEach((preset, index) => {
+            const path = `components.${type}.presets[${index}]`;
+            let counter = 0;
+            let instance;
+            try {
+                instance = instantiatePreset(theme, type, preset.key, () => `preset-${(counter += 1)}`);
+            }
+            catch (error) {
+                addIssue(issues, path, "invalid-preset", error instanceof Error ? error.message : String(error));
+                return;
+            }
+            const checked = validatePageData(theme, { version: 1, surface: "preset", sections: [instance] });
+            for (const issue of checked.issues) {
+                if (issue.code === "missing-required-prop")
+                    continue;
+                addIssue(issues, `${path}.${issue.path.replace(/^sections\[0\]\.?/, "")}`.replace(/\.$/, ""), "invalid-preset", issue.message);
+            }
+        });
+    }
+}
 /**
  * The theme's settings groups: an array of `{ key, label, fields }`, group keys
  * unique and kebab-case, fields checked like a component's, and every setting
@@ -177,6 +272,22 @@ function inspectSurfaces(surfaces, issues, locales) {
         if (labelProblem !== null) {
             addIssue(issues, `${surfacePath}.label`, "invalid-theme", `\`label\` ${labelProblem}`);
         }
+        if (surface.pageType !== undefined && !PAGE_TYPES.includes(surface.pageType)) {
+            addIssue(issues, `${surfacePath}.pageType`, "invalid-theme", `\`pageType\` must be one of ${PAGE_TYPES.join(", ")}`);
+        }
+        if (surface.document !== undefined && !isRecord(surface.document)) {
+            addIssue(issues, `${surfacePath}.document`, "invalid-document", "`document` must be a page document");
+        }
+        if (typeof surface.key === "string" && surface.key.includes(".")) {
+            const baseKey = surface.key.slice(0, surface.key.indexOf("."));
+            const base = surfaces.find((candidate) => isRecord(candidate) && candidate.key === baseKey);
+            if (!isRecord(base)) {
+                addIssue(issues, `${surfacePath}.key`, "invalid-theme", `"${surface.key}" is an alternate of "${baseKey}", which the theme does not declare`);
+            }
+            else if (base.pageType !== surface.pageType) {
+                addIssue(issues, `${surfacePath}.pageType`, "invalid-theme", `an alternate renders its base's page type (${JSON.stringify(base.pageType ?? null)})`);
+            }
+        }
     });
 }
 function inspectDefinition(definition, path, issues, rules) {
@@ -217,11 +328,31 @@ function inspectDefinition(definition, path, issues, rules) {
         if (!isRecord(definition.capabilities)) {
             addIssue(issues, `${path}.capabilities`, "invalid-capability", "`capabilities` must be an object");
         }
-        else if (definition.capabilities.insertable !== undefined &&
-            typeof definition.capabilities.insertable !== "boolean") {
-            addIssue(issues, `${path}.capabilities.insertable`, "invalid-capability", "`insertable` must be a boolean");
+        else {
+            if (definition.capabilities.insertable !== undefined &&
+                typeof definition.capabilities.insertable !== "boolean") {
+                addIssue(issues, `${path}.capabilities.insertable`, "invalid-capability", "`insertable` must be a boolean");
+            }
+            const surfaces = definition.capabilities.surfaces;
+            if (surfaces !== undefined) {
+                if (!Array.isArray(surfaces) || surfaces.length === 0) {
+                    addIssue(issues, `${path}.capabilities.surfaces`, "invalid-capability", "`surfaces` must be a non-empty array of surface keys (omit it for any surface)");
+                }
+                else {
+                    surfaces.forEach((surface, index) => {
+                        if (typeof surface !== "string" || !rules.surfaceKeys.has(surface)) {
+                            addIssue(issues, `${path}.capabilities.surfaces[${index}]`, "invalid-capability", `${JSON.stringify(surface)} is not a surface this theme declares`);
+                        }
+                        else if (surfaces.indexOf(surface) !== index) {
+                            addIssue(issues, `${path}.capabilities.surfaces[${index}]`, "invalid-capability", `duplicate surface "${surface}"`);
+                        }
+                    });
+                }
+            }
         }
     }
+    if (definition.presets !== undefined)
+        inspectPresets(definition.presets, path, issues, rules);
     if (definition.fields !== undefined) {
         if (!Array.isArray(definition.fields)) {
             addIssue(issues, `${path}.fields`, "invalid-field", "`fields` must be an array");
@@ -239,7 +370,7 @@ function inspectDefinition(definition, path, issues, rules) {
         }
     }
 }
-function inspectFields(fields, path, issues, rules) {
+function inspectFields(fields, path, issues, rules, { inList = false } = {}) {
     const { contentKeys, locales } = rules;
     const seenKeys = new Set();
     fields.forEach((field, index) => {
@@ -248,6 +379,17 @@ function inspectFields(fields, path, issues, rules) {
             addIssue(issues, fieldPath, "invalid-field", "field must be an object");
             return;
         }
+        if (inList) {
+            if (field.kind === "list") {
+                addIssue(issues, `${fieldPath}.kind`, "invalid-field", "a list item cannot hold another list");
+            }
+            if (field.key === "id") {
+                addIssue(issues, `${fieldPath}.key`, "invalid-field", "`id` cannot be a list item field: it is the item's own identity");
+            }
+            if (field.contentKey !== undefined) {
+                addIssue(issues, `${fieldPath}.contentKey`, "invalid-field", "a list item field cannot default from the content pack: every item would read the same key");
+            }
+        }
         if (typeof field.key !== "string" || field.key.length === 0) {
             addIssue(issues, `${fieldPath}.key`, "invalid-field", "`key` must be a non-empty string");
         }
@@ -311,6 +453,9 @@ function inspectFields(fields, path, issues, rules) {
                     field.min > field.max) {
                     addIssue(issues, fieldPath, "invalid-field", "`min` must be <= `max`");
                 }
+                if (field.step !== undefined && !(typeof field.step === "number" && Number.isFinite(field.step) && field.step > 0)) {
+                    addIssue(issues, `${fieldPath}.step`, "invalid-field", "`step` must be a finite number greater than 0");
+                }
                 // A default outside the declared bounds would sail through assembly
                 // and then behave incoherently at runtime (`resolveInstance` trusts
                 // authored defaults while rejecting the same out-of-range instance
@@ -323,6 +468,10 @@ function inspectFields(fields, path, issues, rules) {
                     if (typeof field.max === "number" && field.default > field.max) {
                         addIssue(issues, `${fieldPath}.default`, "invalid-field", `\`default\` must be <= ${field.max}`);
                     }
+                    const base = typeof field.min === "number" ? field.min : 0;
+                    if (typeof field.step === "number" && field.step > 0 && !onStepGrid(field.default, base, field.step)) {
+                        addIssue(issues, `${fieldPath}.default`, "invalid-field", `\`default\` must be a multiple of ${field.step} from ${base}`);
+                    }
                 }
                 break;
             }
@@ -343,6 +492,22 @@ function inspectFields(fields, path, issues, rules) {
                     (typeof field.default !== "string" || !options.includes(field.default))) {
                     addIssue(issues, `${fieldPath}.default`, "invalid-field", "`default` must be one of `options`");
                 }
+                if (field.optionLabels !== undefined) {
+                    if (!isRecord(field.optionLabels)) {
+                        addIssue(issues, `${fieldPath}.optionLabels`, "invalid-field", "`optionLabels` must map options to labels");
+                    }
+                    else {
+                        for (const [option, label] of Object.entries(field.optionLabels)) {
+                            if (!Array.isArray(options) || !options.includes(option)) {
+                                addIssue(issues, `${fieldPath}.optionLabels.${option}`, "invalid-field", `"${option}" is not one of \`options\``);
+                                continue;
+                            }
+                            const problem = localizedTextProblem(label, locales, { allowEmpty: false });
+                            if (problem !== null)
+                                addIssue(issues, `${fieldPath}.optionLabels.${option}`, "invalid-field", `the label ${problem}`);
+                        }
+                    }
+                }
                 break;
             }
             case "color": {
@@ -363,6 +528,28 @@ function inspectFields(fields, path, issues, rules) {
                 }
                 break;
             }
+            case "product":
+            case "category": {
+                if (field.default !== undefined && (typeof field.default !== "string" || !RESOURCE_HANDLE_PATTERN.test(field.default))) {
+                    addIssue(issues, `${fieldPath}.default`, "invalid-field", `\`default\` must be a ${field.kind === "product" ? "product handle" : "category slug"}: no spaces, slashes, \`?\`, \`#\` or \`%\``);
+                }
+                break;
+            }
+            case "image": {
+                if (field.default !== undefined) {
+                    addIssue(issues, `${fieldPath}.default`, "invalid-field", "an image field has no default: a theme cannot know a store's media");
+                }
+                break;
+            }
+            case "richtext": {
+                inspectRichTextField(field, fieldPath, issues, locales);
+                break;
+            }
+            case "list": {
+                if (!inList)
+                    inspectListField(field, fieldPath, issues, rules);
+                break;
+            }
             case "url": {
                 if (field.default !== undefined &&
                     (typeof field.default !== "string" || !isSafeLinkTarget(field.default))) {
@@ -375,6 +562,118 @@ function inspectFields(fields, path, issues, rules) {
         }
     });
 }
+/** Preset shapes; what they build is checked once the catalog is sound (`inspectComposition`). */
+function inspectPresets(presets, path, issues, rules) {
+    if (!Array.isArray(presets)) {
+        addIssue(issues, `${path}.presets`, "invalid-preset", "`presets` must be an array");
+        return;
+    }
+    const keys = new Set();
+    presets.forEach((preset, index) => {
+        const presetPath = `${path}.presets[${index}]`;
+        if (!isRecord(preset)) {
+            addIssue(issues, presetPath, "invalid-preset", "a preset must be an object");
+            return;
+        }
+        if (typeof preset.key !== "string" || !TYPE_KEY_PATTERN.test(preset.key)) {
+            addIssue(issues, `${presetPath}.key`, "invalid-preset", "`key` must be lowercase kebab-case");
+        }
+        else if (keys.has(preset.key)) {
+            addIssue(issues, `${presetPath}.key`, "invalid-preset", `duplicate preset "${preset.key}"`);
+        }
+        else {
+            keys.add(preset.key);
+        }
+        const labelProblem = localizedTextProblem(preset.label, rules.locales, { allowEmpty: false });
+        if (labelProblem !== null)
+            addIssue(issues, `${presetPath}.label`, "invalid-preset", `\`label\` ${labelProblem}`);
+        if (preset.description !== undefined) {
+            const problem = localizedTextProblem(preset.description, rules.locales, { allowEmpty: false });
+            if (problem !== null)
+                addIssue(issues, `${presetPath}.description`, "invalid-preset", `\`description\` ${problem}`);
+        }
+        if (preset.props !== undefined && !isRecord(preset.props)) {
+            addIssue(issues, `${presetPath}.props`, "invalid-preset", "`props` must be an object");
+        }
+    });
+}
+function inspectRichTextField(field, fieldPath, issues, locales) {
+    if (field.contentKey !== undefined) {
+        addIssue(issues, `${fieldPath}.contentKey`, "invalid-field", "a rich-text field cannot default from the content pack, which holds plain text");
+    }
+    let formats;
+    if (field.formats !== undefined) {
+        const declared = field.formats;
+        if (!Array.isArray(declared) || declared.length === 0) {
+            addIssue(issues, `${fieldPath}.formats`, "invalid-field", "`formats` must be a non-empty array (omit it to allow every format)");
+        }
+        else {
+            const seen = new Set();
+            declared.forEach((format, index) => {
+                if (!RICH_TEXT_FORMATS.includes(format)) {
+                    addIssue(issues, `${fieldPath}.formats[${index}]`, "invalid-field", `unknown rich-text format ${JSON.stringify(format)}; known: ${RICH_TEXT_FORMATS.join(", ")}`);
+                }
+                else if (seen.has(format)) {
+                    addIssue(issues, `${fieldPath}.formats[${index}]`, "invalid-field", `duplicate format "${String(format)}"`);
+                }
+                seen.add(format);
+            });
+            formats = declared.filter((format) => RICH_TEXT_FORMATS.includes(format));
+        }
+    }
+    if (field.default === undefined)
+        return;
+    const value = field.default;
+    if (isRichTextDocumentShape(value)) {
+        const problem = richTextProblem(value, formats);
+        if (problem !== null)
+            addIssue(issues, `${fieldPath}.default`, "invalid-field", `\`default\` ${problem}`);
+        return;
+    }
+    if (!isLocaleMapOf(value, isRecord)) {
+        addIssue(issues, `${fieldPath}.default`, "invalid-field", "`default` must be a rich-text document or a map from language tags to documents");
+        return;
+    }
+    for (const [locale, document] of Object.entries(value)) {
+        const problem = richTextProblem(document, formats);
+        if (problem !== null)
+            addIssue(issues, `${fieldPath}.default.${locale}`, "invalid-field", `\`default\` (${locale}) ${problem}`);
+    }
+    const missing = locales.filter((locale) => !Object.hasOwn(value, locale));
+    if (missing.length > 0) {
+        addIssue(issues, `${fieldPath}.default`, "invalid-field", `\`default\` is missing the theme's languages: ${missing.join(", ")}`);
+    }
+}
+function inspectListField(field, fieldPath, issues, rules) {
+    const itemFields = field.fields;
+    if (!Array.isArray(itemFields) || itemFields.length === 0) {
+        addIssue(issues, `${fieldPath}.fields`, "invalid-field", "`fields` must be a non-empty array of item fields");
+        return;
+    }
+    const before = issues.length;
+    inspectFields(itemFields, fieldPath, issues, rules, { inList: true });
+    const itemFieldsValid = issues.length === before;
+    for (const bound of ["min", "max"]) {
+        const value = field[bound];
+        if (value !== undefined && !(typeof value === "number" && Number.isInteger(value) && value >= (bound === "max" ? 1 : 0))) {
+            addIssue(issues, `${fieldPath}.${bound}`, "invalid-field", `\`${bound}\` must be a whole number${bound === "max" ? " of at least 1" : " of at least 0"}`);
+        }
+    }
+    if (typeof field.min === "number" && typeof field.max === "number" && field.min > field.max) {
+        addIssue(issues, fieldPath, "invalid-field", "`min` must be <= `max`");
+    }
+    if (field.itemLabel !== undefined) {
+        const labelField = itemFields.find((itemField) => isRecord(itemField) && itemField.key === field.itemLabel);
+        if (!isRecord(labelField) || (labelField.kind !== "text" && labelField.kind !== "textarea")) {
+            addIssue(issues, `${fieldPath}.itemLabel`, "invalid-field", "`itemLabel` must name one of the item's `text` or `textarea` fields");
+        }
+    }
+    if (field.default !== undefined && itemFieldsValid) {
+        const checked = checkStoredValue(field, field.default);
+        if (!checked.ok)
+            addIssue(issues, `${fieldPath}.default`, "invalid-field", `\`default\` ${checked.message}`);
+    }
+}
 function inspectSlots(slots, path, issues, catalogKeys) {
     const seenNames = new Set();
     slots.forEach((slot, index) => {

package/dist/index.d.ts

@@ -3,18 +3,31 @@
  *
  * 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 type { CheckedValue as FieldValueCheck } 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 type { DocumentEdit, DocumentIssue, DocumentIssueCode, InstanceLocation, InstancePlacement, } from "./operations.js";
+export { THEME_SDK_VERSION } from "./version.js";
+export type { RichTextHtmlOptions } from "./rich-text.js";
 export { resolveThemeSettings, checkThemeSettings } from "./settings.js";
 export { localize } from "./locales.js";
 export { PLURAL_CATEGORIES, formatMessage, messageForms, pluralFormIssues } from "./messages.js";
 export type { MessageOptions, MessageValues, PluralCategory } from "./messages.js";
-export { THEME_MANIFEST_CONTRACT_VERSION, themeManifest, validateThemeManifest, } from "./manifest.js";
-export type { JsonValue, JsonObject, LocaleCode, LocalizedText, ResolutionScope, FieldKind, FieldDefinition, FieldValue, InferProps, FieldValues, SlotDefinition, ComponentCapabilities, ComponentDefinition, ComponentSpec, SurfaceSpec, ThemeDefinition, SettingsGroup, InferSettings, ThemeSettingsIssue, ThemeSettingsIssueCode, ThemeSettingsResult, ColorFieldDefinition, MenuFieldDefinition, CollectionFieldDefinition, ThemeManifest, ThemeManifestIssue, ThemeManifestIssueCode, ThemeManifestResult, ComponentInstance, PageData, ThemeRenderContext, LoadContext, LoadFn, ReadCache, PageDataIssue, PageDataIssueCode, PageDataResult, ResolvedInstance, ThemeDefinitionIssue, ThemeDefinitionIssueCode, ThemeValidationOptions, } from "./types.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";
+export type { PreviewEditorMessage, PreviewInstance, PreviewMode, PreviewPageMessage, PreviewPatch, PreviewRect, } from "./preview-protocol.js";
+export type { ManifestChange, ManifestDiff } from "./manifest-diff.js";
+export type { JsonValue, JsonObject, LocaleCode, LocalizedText, ResolutionScope, FieldKind, FieldDefinition, FieldValue, InferProps, FieldValues, SlotDefinition, ComponentCapabilities, ComponentPreset, PresetInstance, SurfacePageType, ComponentDefinition, ComponentSpec, SurfaceSpec, ThemeDefinition, SettingsGroup, InferSettings, ThemeSettingsIssue, ThemeSettingsIssueCode, ThemeSettingsResult, NumberFieldDefinition, ColorFieldDefinition, MenuFieldDefinition, CollectionFieldDefinition, ProductFieldDefinition, CategoryFieldDefinition, ImageFieldDefinition, RichTextFieldDefinition, RichTextFormat, ListFieldDefinition, ListItemFieldDefinition, ListItem, MediaReference, ResolvedImage, RichTextValue, RichTextDocument, RichTextBlock, RichTextParagraph, RichTextHeading, RichTextList, RichTextListItem, RichTextInline, RichTextText, RichTextBreak, RichTextMark, ThemeManifest, ThemeManifestIssue, ThemeManifestIssueCode, ThemeManifestResult, ComponentInstance, PageData, ThemeRenderContext, LoadContext, LoadFn, ReadCache, PageDataIssue, PageDataIssueCode, PageDataResult, ResolvedInstance, ThemeDefinitionIssue, ThemeDefinitionIssueCode, ThemeValidationOptions, } from "./types.js";

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