@avocadostudio-ai/shared 0.5.0 → 0.5.1

package/dist/block-manifest.d.ts

@@ -15,6 +15,7 @@ export declare const fieldMetaSchema: z.ZodObject<{
         imageAlt: "imageAlt";
         color: "color";
         headingLevel: "headingLevel";
+        reference: "reference";
     }>;
     label: z.ZodOptional<z.ZodString>;
     inlineEditable: z.ZodOptional<z.ZodBoolean>;
@@ -34,6 +35,7 @@ export declare const fieldMetaSchema: z.ZodObject<{
         }>>;
     }, z.core.$strip>>;
     multiline: z.ZodOptional<z.ZodBoolean>;
+    referenceLabelKey: z.ZodOptional<z.ZodString>;
     inline: z.ZodOptional<z.ZodBoolean>;
     decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -57,6 +59,7 @@ export declare const listFieldMetaSchema: z.ZodObject<{
             imageAlt: "imageAlt";
             color: "color";
             headingLevel: "headingLevel";
+            reference: "reference";
         }>;
         label: z.ZodOptional<z.ZodString>;
         inlineEditable: z.ZodOptional<z.ZodBoolean>;
@@ -76,6 +79,7 @@ export declare const listFieldMetaSchema: z.ZodObject<{
             }>>;
         }, z.core.$strip>>;
         multiline: z.ZodOptional<z.ZodBoolean>;
+        referenceLabelKey: z.ZodOptional<z.ZodString>;
         inline: z.ZodOptional<z.ZodBoolean>;
         decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -98,6 +102,7 @@ export declare const listFieldMetaSchema: z.ZodObject<{
             imageAlt: "imageAlt";
             color: "color";
             headingLevel: "headingLevel";
+            reference: "reference";
         }>;
         label: z.ZodOptional<z.ZodString>;
         inlineEditable: z.ZodOptional<z.ZodBoolean>;
@@ -117,6 +122,7 @@ export declare const listFieldMetaSchema: z.ZodObject<{
             }>>;
         }, z.core.$strip>>;
         multiline: z.ZodOptional<z.ZodBoolean>;
+        referenceLabelKey: z.ZodOptional<z.ZodString>;
         inline: z.ZodOptional<z.ZodBoolean>;
         decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -145,6 +151,7 @@ export declare const blockDefinitionSchema: z.ZodObject<{
             imageAlt: "imageAlt";
             color: "color";
             headingLevel: "headingLevel";
+            reference: "reference";
         }>;
         label: z.ZodOptional<z.ZodString>;
         inlineEditable: z.ZodOptional<z.ZodBoolean>;
@@ -164,6 +171,7 @@ export declare const blockDefinitionSchema: z.ZodObject<{
             }>>;
         }, z.core.$strip>>;
         multiline: z.ZodOptional<z.ZodBoolean>;
+        referenceLabelKey: z.ZodOptional<z.ZodString>;
         inline: z.ZodOptional<z.ZodBoolean>;
         decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -187,6 +195,7 @@ export declare const blockDefinitionSchema: z.ZodObject<{
                 imageAlt: "imageAlt";
                 color: "color";
                 headingLevel: "headingLevel";
+                reference: "reference";
             }>;
             label: z.ZodOptional<z.ZodString>;
             inlineEditable: z.ZodOptional<z.ZodBoolean>;
@@ -206,6 +215,7 @@ export declare const blockDefinitionSchema: z.ZodObject<{
                 }>>;
             }, z.core.$strip>>;
             multiline: z.ZodOptional<z.ZodBoolean>;
+            referenceLabelKey: z.ZodOptional<z.ZodString>;
             inline: z.ZodOptional<z.ZodBoolean>;
             decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
@@ -228,6 +238,7 @@ export declare const blockDefinitionSchema: z.ZodObject<{
                 imageAlt: "imageAlt";
                 color: "color";
                 headingLevel: "headingLevel";
+                reference: "reference";
             }>;
             label: z.ZodOptional<z.ZodString>;
             inlineEditable: z.ZodOptional<z.ZodBoolean>;
@@ -247,6 +258,7 @@ export declare const blockDefinitionSchema: z.ZodObject<{
                 }>>;
             }, z.core.$strip>>;
             multiline: z.ZodOptional<z.ZodBoolean>;
+            referenceLabelKey: z.ZodOptional<z.ZodString>;
             inline: z.ZodOptional<z.ZodBoolean>;
             decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
@@ -281,6 +293,7 @@ export declare const blockManifestSchema: z.ZodObject<{
                 imageAlt: "imageAlt";
                 color: "color";
                 headingLevel: "headingLevel";
+                reference: "reference";
             }>;
             label: z.ZodOptional<z.ZodString>;
             inlineEditable: z.ZodOptional<z.ZodBoolean>;
@@ -300,6 +313,7 @@ export declare const blockManifestSchema: z.ZodObject<{
                 }>>;
             }, z.core.$strip>>;
             multiline: z.ZodOptional<z.ZodBoolean>;
+            referenceLabelKey: z.ZodOptional<z.ZodString>;
             inline: z.ZodOptional<z.ZodBoolean>;
             decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
@@ -323,6 +337,7 @@ export declare const blockManifestSchema: z.ZodObject<{
                     imageAlt: "imageAlt";
                     color: "color";
                     headingLevel: "headingLevel";
+                    reference: "reference";
                 }>;
                 label: z.ZodOptional<z.ZodString>;
                 inlineEditable: z.ZodOptional<z.ZodBoolean>;
@@ -342,6 +357,7 @@ export declare const blockManifestSchema: z.ZodObject<{
                     }>>;
                 }, z.core.$strip>>;
                 multiline: z.ZodOptional<z.ZodBoolean>;
+                referenceLabelKey: z.ZodOptional<z.ZodString>;
                 inline: z.ZodOptional<z.ZodBoolean>;
                 decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     name: z.ZodString;
@@ -364,6 +380,7 @@ export declare const blockManifestSchema: z.ZodObject<{
                     imageAlt: "imageAlt";
                     color: "color";
                     headingLevel: "headingLevel";
+                    reference: "reference";
                 }>;
                 label: z.ZodOptional<z.ZodString>;
                 inlineEditable: z.ZodOptional<z.ZodBoolean>;
@@ -383,6 +400,7 @@ export declare const blockManifestSchema: z.ZodObject<{
                     }>>;
                 }, z.core.$strip>>;
                 multiline: z.ZodOptional<z.ZodBoolean>;
+                referenceLabelKey: z.ZodOptional<z.ZodString>;
                 inline: z.ZodOptional<z.ZodBoolean>;
                 decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     name: z.ZodString;

package/dist/block-manifest.js

@@ -36,7 +36,7 @@ export const jsonSchemaLikeSchema = z.lazy(() => z.object({
  */
 const FIELD_KINDS = [
     "text", "richtext", "url", "link", "file", "image", "imageAlt",
-    "enum", "color", "number", "boolean", "headingLevel"
+    "enum", "color", "number", "boolean", "headingLevel", "reference"
 ];
 const _everyKindListed = true;
 void _everyKindListed;
@@ -54,6 +54,13 @@ export const fieldMetaSchema = z.object({
     })
         .optional(),
     multiline: z.boolean().optional(),
+    /*
+     * Travels with the manifest because the panel is what reads it, and the panel
+     * is in a different process. A key this schema omits is stripped here, not
+     * rejected — so a reference would have arrived in the editor with nothing to
+     * label it and no sign that anything had been declared.
+     */
+    referenceLabelKey: z.string().optional(),
     inline: z.boolean().optional(),
     decorators: z
         .array(z.object({ name: z.string().min(1), title: z.string().optional() }))

package/dist/blocks/_registry.d.ts

@@ -18,8 +18,27 @@ export declare function isImagePlaceholder(url: string | undefined | null): bool
  * against nothing at all; a `file` can be checked against what the site's asset
  * store actually holds, which is the only way anyone finds out that a menu link
  * has been pointing at a filename with a typo in it since August.
+ *
+ * `reference` is a *pointer the CMS owns*, and it is not a flavour of `link`.
+ * A Storyblok story link is `{ linktype: "story", id: <uuid>, cached_url: "faq" }`
+ * and the Delivery API renders it per language — `/faq` on the German page,
+ * `/fr/faq` on the French one. Neither string is what the document holds.
+ * Contentful entry links and Sanity references have the same shape and the same
+ * problem. Declare one as `link` and the projection stops being invertible in
+ * both directions at once: the diff reports every reference on every page as
+ * changed because the rendered href never equals the stored object, and writing
+ * the href back replaces the reference with a hard-coded URL, which silently
+ * stops following renames — the one thing the reference was for.
+ *
+ * So the panel shows it and does not edit it. The value is carried through
+ * untouched, the way `avocadoUnknownBlock` carries a rich-text node the pivot
+ * cannot model, and `referenceLabelKey` says where to find something a person
+ * can read. Re-pointing a reference needs a picker that knows the CMS's own
+ * document ids, which only the integration has; until it exists, showing the
+ * target and refusing the edit is the honest answer and the corrupting one is
+ * a text input.
  */
-export type FieldKind = "text" | "richtext" | "url" | "link" | "file" | "image" | "imageAlt" | "enum" | "color" | "number" | "boolean" | "headingLevel";
+export type FieldKind = "text" | "richtext" | "url" | "link" | "file" | "image" | "imageAlt" | "enum" | "color" | "number" | "boolean" | "headingLevel" | "reference";
 /** Recommended image dimensions for an image field. */
 export type ImageSpec = {
     aspectRatio: "landscape" | "square" | "portrait";
@@ -97,6 +116,17 @@ export type FieldMeta = {
      * Use this one when there is no element at all.
      */
     panelOnly?: boolean;
+    /**
+     * For `kind: "reference"`: the key inside the value holding something a
+     * person can read.
+     *
+     * Optional, because the common spellings are tried anyway — Storyblok's
+     * `cached_url`, a `slug`, a `title`, a `name`. Set it when the reference
+     * carries a readable key under a name nothing would guess, or when it carries
+     * several and the wrong one wins. Purely a display concern: it never selects
+     * what is written, because a reference is not written here at all.
+     */
+    referenceLabelKey?: string;
 };
 /** Metadata for list-type props (features, items, cards). */
 export type ListFieldMeta = {
@@ -137,6 +167,14 @@ export type BlockRegistration = {
 };
 /** Test seam: forget what has already been warned about. */
 export declare function resetListFieldWarnings(): void;
+/** Whether `type` is currently backed by Avocado's own definition. */
+export declare function isBuiltinBlock(type: string): boolean;
+/**
+ * Register one of Avocado's own blocks. Internal — a site uses `registerBlock`,
+ * and registering over a built-in name deliberately drops the built-in flag
+ * with the built-in schema.
+ */
+export declare function registerBuiltinBlock(type: string, config: BlockRegistration): void;
 export declare function registerBlock(type: string, config: BlockRegistration): void;
 /** Get metadata for a registered block type, or undefined. */
 export declare function getBlockMeta(type: string): BlockMeta | undefined;
@@ -226,6 +264,19 @@ export declare function isInBlockCatalogue(type: string): boolean;
 export declare function catalogueBlockTypes(): string[];
 /** Declared types with no registration behind them — a typo, or a missing import. */
 export declare function undeclaredBlockTypes(): string[];
+/**
+ * Something a person can read out of a reference value.
+ *
+ * A reference is opaque by design — the panel shows it and never rewrites it —
+ * but "opaque" must not mean `[object Object]` in the one place a person looks
+ * to check which document a CTA points at. Storyblok spells the readable half
+ * `cached_url`, Contentful puts a `slug` or `title` on the resolved entry,
+ * Sanity hands over a bare `_ref`. Falls back to the id, and then to nothing,
+ * which the panel renders as "not set" rather than as a broken label.
+ *
+ * `referenceLabelKey` wins when the meta declares it.
+ */
+export declare function referenceLabel(value: unknown, labelKey?: string): string;
 export declare function getPropDisplayName(blockType: string | undefined, propKey: string): string;
 export declare function defaultListItemForBlock(type: BlockType, listKey: string): Record<string, unknown> | null;
 /** Base schema — accepts any block type. Used for ingesting external site content with custom blocks. */

package/dist/blocks/_registry.js

@@ -68,6 +68,72 @@ function unwrapZod(schema) {
     }
     return current;
 }
+/**
+ * The object shapes a list's rows can take.
+ *
+ * A monomorphic list has one. A polymorphic list — `z.discriminatedUnion`, the
+ * shape our own docs tell an integrator to use when rows differ — has one per
+ * branch and no `.shape` of its own. Reading `.element.shape` and stopping there
+ * declared every correct polymorphic list unbacked, warned about it at startup,
+ * and prescribed `z.array(z.object({ … }))`: the one edit that really would
+ * break it, because collapsing the union is what stops each row narrowing to its
+ * own field set. The panel never used this path — it reads the JSON Schema,
+ * where the branches survive as `anyOf` — so the lists worked exactly as
+ * declared while their author was being told they could not.
+ */
+function listElementBranches(element) {
+    const unwrapped = unwrapZod(element);
+    if (!unwrapped)
+        return undefined;
+    const ownShape = unwrapped.shape;
+    if (ownShape)
+        return [{ discriminantValues: [], shape: ownShape }];
+    const def = unwrapped.def ?? unwrapped._def;
+    const options = def?.options;
+    if (!Array.isArray(options) || options.length === 0)
+        return undefined;
+    const discriminator = def?.discriminator;
+    const branches = [];
+    for (const option of options) {
+        const optionShape = unwrapZod(option)?.shape;
+        if (!optionShape)
+            continue;
+        branches.push({
+            discriminantValues: discriminator ? literalValuesOf(optionShape[discriminator]) : [],
+            shape: optionShape
+        });
+    }
+    return branches.length > 0 ? branches : undefined;
+}
+/** The values a discriminant field admits, spelled as the strings a row carries. */
+function literalValuesOf(schema) {
+    const def = unwrapZod(schema)?.def ?? unwrapZod(schema)?._def;
+    if (!def)
+        return [];
+    if (Array.isArray(def.values))
+        return def.values.map(String); // z.literal in Zod 4
+    if (def.value !== undefined)
+        return [String(def.value)]; // z.literal in Zod 3
+    if (def.entries)
+        return Object.values(def.entries).map(String); // z.enum
+    return [];
+}
+/**
+ * Fill in `required` from the Zod shapes a field set can be backed by.
+ *
+ * More than one shape means the set spans branches, and a key only one branch
+ * declares cannot be required of a row that might be another branch.
+ */
+function deriveRequired(fields, shapes) {
+    for (const [key, field] of Object.entries(fields)) {
+        if (field.required !== undefined)
+            continue;
+        const backing = shapes.filter((s) => s[key]);
+        if (backing.length === 0)
+            continue;
+        field.required = backing.length === shapes.length && backing.every((s) => !s[key].isOptional());
+    }
+}
 const warnedListFields = new Set();
 function warnUnbackedListField(type, listKey, present) {
     const key = `${type}.${listKey}`;
@@ -91,8 +157,35 @@ function warnUnbackedListField(type, listKey, present) {
 export function resetListFieldWarnings() {
     warnedListFields.clear();
 }
+/**
+ * The block types Avocado itself defines, as opposed to a site's own.
+ *
+ * A site that renders its own `Hero` registers it under that name, and from
+ * then on the name is all the two shapes have in common. Anything that reasons
+ * about a block by hard-coded key — the demo-content migrations in
+ * `session-state`, which stamp `imageUrl` and a `left`/`right` pair onto
+ * whatever is called `Hero` or `TwoColumn` — is reasoning about *our* schema,
+ * and must not run against a schema it has never seen. Registration order
+ * settles it: whoever registered last owns the name, so the flag is written on
+ * every call rather than only on the first.
+ */
+const _builtinBlockTypes = G.__ase_builtinBlockTypes ?? (G.__ase_builtinBlockTypes = new Set());
+/** Whether `type` is currently backed by Avocado's own definition. */
+export function isBuiltinBlock(type) {
+    return _builtinBlockTypes.has(type);
+}
+/**
+ * Register one of Avocado's own blocks. Internal — a site uses `registerBlock`,
+ * and registering over a built-in name deliberately drops the built-in flag
+ * with the built-in schema.
+ */
+export function registerBuiltinBlock(type, config) {
+    registerBlock(type, config);
+    _builtinBlockTypes.add(type);
+}
 export function registerBlock(type, config) {
     _blockSchemas[type] = config.schema;
+    _builtinBlockTypes.delete(type);
     // Auto-derive `required` on each FieldMeta from the Zod schema shape
     const shape = config.schema.shape;
     if (shape) {
@@ -112,18 +205,20 @@ export function registerBlock(type, config) {
                 // Without the outer unwrap, `z.array(...).optional()` — which is how a
                 // list should be declared — looked like no array at all, so every
                 // optional list silently skipped its own `required` derivation.
-                const elementShape = unwrapZod(listZod)?.element?.shape;
-                if (!elementShape) {
+                const branches = listElementBranches(unwrapZod(listZod)?.element);
+                if (!branches) {
                     warnUnbackedListField(type, listKey, listZod !== undefined);
                     continue;
                 }
-                for (const [itemKey, itemField] of Object.entries(listMeta.itemFields)) {
-                    if (itemField.required !== undefined)
+                // `itemFields` is the union of every branch — the set a row is edited
+                // against when its discriminant matches nothing — so a key is required
+                // there only if every branch has it and no branch makes it optional.
+                deriveRequired(listMeta.itemFields, branches.map((b) => b.shape));
+                for (const [value, branchFields] of Object.entries(listMeta.itemFieldsByType ?? {})) {
+                    const matching = branches.filter((b) => b.discriminantValues.includes(value));
+                    if (matching.length === 0)
                         continue;
-                    const zodItem = elementShape[itemKey];
-                    if (zodItem) {
-                        itemField.required = !zodItem.isOptional();
-                    }
+                    deriveRequired(branchFields, matching.map((b) => b.shape));
                 }
             }
         }
@@ -391,6 +486,47 @@ export function undeclaredBlockTypes() {
         return [];
     return [...declared].filter((t) => !(t in _blockSchemas));
 }
+/**
+ * Something a person can read out of a reference value.
+ *
+ * A reference is opaque by design — the panel shows it and never rewrites it —
+ * but "opaque" must not mean `[object Object]` in the one place a person looks
+ * to check which document a CTA points at. Storyblok spells the readable half
+ * `cached_url`, Contentful puts a `slug` or `title` on the resolved entry,
+ * Sanity hands over a bare `_ref`. Falls back to the id, and then to nothing,
+ * which the panel renders as "not set" rather than as a broken label.
+ *
+ * `referenceLabelKey` wins when the meta declares it.
+ */
+export function referenceLabel(value, labelKey) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "string" || typeof value === "number")
+        return String(value).trim();
+    if (typeof value !== "object" || Array.isArray(value))
+        return "";
+    const rec = value;
+    const readable = (key) => {
+        const candidate = rec[key];
+        return typeof candidate === "string" || typeof candidate === "number" ? String(candidate).trim() : "";
+    };
+    if (labelKey) {
+        const declared = readable(labelKey);
+        if (declared !== "")
+            return declared;
+    }
+    for (const key of ["cached_url", "slug", "url", "href", "title", "name", "label"]) {
+        const found = readable(key);
+        if (found !== "")
+            return found;
+    }
+    for (const key of ["_ref", "id", "_id", "uuid", "entryId"]) {
+        const found = readable(key);
+        if (found !== "")
+            return found;
+    }
+    return "";
+}
 export function getPropDisplayName(blockType, propKey) {
     if (!blockType)
         return propKey;
@@ -429,6 +565,14 @@ function defaultScalarForField(field, fieldKey) {
         return false;
     if (field.kind === "enum")
         return Array.isArray(field.options) && field.options.length > 0 ? field.options[0] : "";
+    /*
+     * A reference points at a document in the CMS. There is no default one, and
+     * `"New Story link"` in a field the site resolves to a URL is a broken link
+     * dressed as content. An added row simply has no reference until somebody
+     * sets one upstream.
+     */
+    if (field.kind === "reference")
+        return null;
     return `New ${label}`;
 }
 export function defaultListItemForBlock(type, listKey) {

package/dist/blocks/banner.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock } from "./_registry.js";
+import { registerBuiltinBlock } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("Banner", {
+registerBuiltinBlock("Banner", {
     schema: z.object({
         text: z.string().min(1),
         variant: z.enum(["info", "success", "warning"]).default("info").catch("info"),

package/dist/blocks/card-grid.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock } from "./_registry.js";
+import { registerBuiltinBlock } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("CardGrid", {
+registerBuiltinBlock("CardGrid", {
     schema: z.object({
         title: z.string().min(1),
         subtitle: z.string().optional(),

package/dist/blocks/card.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock } from "./_registry.js";
+import { registerBuiltinBlock } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("Card", {
+registerBuiltinBlock("Card", {
     schema: z.object({
         title: z.string().min(1),
         description: z.string().min(1),

package/dist/blocks/carousel.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock, IMAGE_PLACEHOLDER } from "./_registry.js";
+import { registerBuiltinBlock, IMAGE_PLACEHOLDER } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("Carousel", {
+registerBuiltinBlock("Carousel", {
     schema: z.object({
         items: z.array(z.object({
             id: z.string().optional(),

package/dist/blocks/cta.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock } from "./_registry.js";
+import { registerBuiltinBlock } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("CTA", {
+registerBuiltinBlock("CTA", {
     schema: z.object({
         title: z.string().min(1),
         description: z.string().min(1),

package/dist/blocks/embed.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock } from "./_registry.js";
+import { registerBuiltinBlock } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("Embed", {
+registerBuiltinBlock("Embed", {
     schema: z.object({
         embedType: z.enum(["map", "social", "custom"]).default("map").catch("map"),
         url: z.string().min(1),

package/dist/blocks/faq-accordion.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock } from "./_registry.js";
+import { registerBuiltinBlock } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("FAQAccordion", {
+registerBuiltinBlock("FAQAccordion", {
     schema: z.object({
         title: z.string().min(1),
         items: z.array(z.object({ id: z.string().optional(), q: z.string().min(1), a: z.string().min(1) })).min(1)

package/dist/blocks/feature-grid.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock } from "./_registry.js";
+import { registerBuiltinBlock } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("FeatureGrid", {
+registerBuiltinBlock("FeatureGrid", {
     schema: z.object({
         title: z.string().min(1),
         columns: z.enum(["2", "3", "4"]).default("3").catch("3"),

package/dist/blocks/footer.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock } from "./_registry.js";
+import { registerBuiltinBlock } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("Footer", {
+registerBuiltinBlock("Footer", {
     schema: z.object({
         copyright: z.string().min(1),
         columns: z.array(z.object({ id: z.string().optional(), title: z.string().min(1), links: z.string().min(1) })).min(1)

package/dist/blocks/gallery.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock, IMAGE_PLACEHOLDER } from "./_registry.js";
+import { registerBuiltinBlock, IMAGE_PLACEHOLDER } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("Gallery", {
+registerBuiltinBlock("Gallery", {
     schema: z.object({
         title: z.string().optional(),
         headingLevel: z.string().optional(),

package/dist/blocks/hero.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock, IMAGE_PLACEHOLDER } from "./_registry.js";
+import { registerBuiltinBlock, IMAGE_PLACEHOLDER } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("Hero", {
+registerBuiltinBlock("Hero", {
     schema: z.object({
         heading: z.string().min(1),
         subheading: z.string().min(1),

package/dist/blocks/quote.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock } from "./_registry.js";
+import { registerBuiltinBlock } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("Quote", {
+registerBuiltinBlock("Quote", {
     schema: z.object({
         quote: z.string().min(1),
         author: z.string().optional(),

package/dist/blocks/rich-text.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock } from "./_registry.js";
+import { registerBuiltinBlock } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("RichText", {
+registerBuiltinBlock("RichText", {
     schema: z.object({
         title: z.string(),
         body: z.string().min(1)

package/dist/blocks/site-header.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { registerBlock } from "./_registry.js";
+import { registerBuiltinBlock } from "./_registry.js";
 import { f } from "./_helpers.js";
 const navLinkLeaf = z.object({
     id: z.string().optional(),
@@ -7,7 +7,7 @@ const navLinkLeaf = z.object({
     href: z.string().min(1),
     newTab: z.boolean().optional(),
 });
-registerBlock("SiteHeader", {
+registerBuiltinBlock("SiteHeader", {
     schema: z.object({
         siteName: z.string().min(1),
         logoUrl: z.string().min(1),

package/dist/blocks/stats.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock } from "./_registry.js";
+import { registerBuiltinBlock } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("Stats", {
+registerBuiltinBlock("Stats", {
     schema: z.object({
         title: z.string().optional(),
         stats: z.array(z.object({

package/dist/blocks/table.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock } from "./_registry.js";
+import { registerBuiltinBlock } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("Table", {
+registerBuiltinBlock("Table", {
     schema: z.object({
         title: z.string().optional(),
         headingLevel: z.string().optional(),

package/dist/blocks/tabs.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock } from "./_registry.js";
+import { registerBuiltinBlock } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("Tabs", {
+registerBuiltinBlock("Tabs", {
     schema: z.object({
         title: z.string().optional(),
         tabs: z.array(z.object({

package/dist/blocks/testimonials.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock } from "./_registry.js";
+import { registerBuiltinBlock } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("Testimonials", {
+registerBuiltinBlock("Testimonials", {
     schema: z.object({
         title: z.string().min(1),
         items: z.array(z.object({

package/dist/blocks/two-column.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { registerBlock, IMAGE_PLACEHOLDER } from "./_registry.js";
+import { registerBuiltinBlock, IMAGE_PLACEHOLDER } from "./_registry.js";
 import { f } from "./_helpers.js";
 const twoColumnChild = z.object({
     id: z.string().optional(),
@@ -62,7 +62,7 @@ const twoColumnItemFieldsByType = {
         poster: f.image("Video poster image", { aspectRatio: "landscape", width: 768, height: 512 }),
     },
 };
-registerBlock("TwoColumn", {
+registerBuiltinBlock("TwoColumn", {
     schema: z.object({
         variant: z.enum(["default", "accent"]).default("default").catch("default"),
         left: z.array(twoColumnChild).min(1),

package/dist/blocks/video.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { registerBlock } from "./_registry.js";
+import { registerBuiltinBlock } from "./_registry.js";
 import { f } from "./_helpers.js";
-registerBlock("Video", {
+registerBuiltinBlock("Video", {
     schema: z.object({
         src: z.string().min(1),
         title: z.string().optional(),

package/dist/editable-coverage.js

@@ -314,7 +314,15 @@ export function editableCoverage(manifest, blocks) {
             for (const [itemKey, itemMeta] of drawnItemFields) {
                 const path = `${listKey}[].${itemKey}`;
                 expected += 1;
-                if (!paths.has(path)) {
+                /*
+                 * `isCovered`, not `paths.has`, for the same reason the top-level scan
+                 * uses it: a row field can itself be a list. `buttons` is marked as
+                 * `left[].buttons[].label` — the label is the only part of a button a
+                 * person edits in place — and an exact match called that unmarked,
+                 * reporting a gap whose only remedy would be a second marker on an
+                 * element that draws nothing.
+                 */
+                if (!isCovered(path, paths)) {
                     missingItemFields.push(path);
                 }
                 else if (itemMeta.kind === "image" && voids.has(path)) {

package/dist/index.d.ts

@@ -12,10 +12,10 @@ export { parseLink, resolveLink, normalizeLinkPath, isKnownRoute, internalPathFo
 export { parseInline, parseRichText, parseRichTextBlocks, normalizeRichTextBody, resolveRichTextHeadingLevel, clampMarkdownHeadings, unescapeMarkdownText, isRichTextDoc, fromMarkdown, toMarkdown, mergeRichTextDoc, NODE, MARK, type InlineToken, type RichTextBlock, type RichTextList, type RichTextListItem, type RichTextDoc, type RichTextNode, type RichTextMark } from "@avocadostudio-ai/richtext";
 export { blockDefinitionSchema, blockManifestSchema, buildBlockManifest, jsonSchemaLikeSchema, validateByJsonSchemaLike, findManifestSchemaIssue, type ManifestSchemaIssue, validateManifestDefaultProps, deriveFieldMetaFromSchema, resolveManifestFieldMeta, isProseMirrorDocSchema, type BlockDefinition, type BlockManifest } from "./block-manifest.ts";
 export { z } from "zod";
-export { type FieldKind, type ImageSpec, type FieldMeta, type ListFieldMeta, type BlockMeta, type BlockType, type BlockInstance, type BlockRegistration, IMAGE_PLACEHOLDER, isImagePlaceholder, registerBlock, resetListFieldWarnings, getBlockMeta, getAllBlockMeta, blockAcceptsProp, blockListItemAcceptsKey, getImageFields, getListImageFields, getMediaFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, blockSchemas, allowedBlockTypes, declareBlockCatalogue, getBlockCatalogue, isInBlockCatalogue, catalogueBlockTypes, undeclaredBlockTypes, getPropDisplayName, defaultListItemForBlock, blockInstanceSchema, blockInstanceSchemaLenient, validateBlockProps, getBlockJsonSchema, } from "./blocks/_registry.ts";
+export { type FieldKind, type ImageSpec, type FieldMeta, type ListFieldMeta, type BlockMeta, type BlockType, type BlockInstance, type BlockRegistration, IMAGE_PLACEHOLDER, isImagePlaceholder, registerBlock, isBuiltinBlock, resetListFieldWarnings, getBlockMeta, getAllBlockMeta, blockAcceptsProp, blockListItemAcceptsKey, getImageFields, getListImageFields, getMediaFields, isFieldInlineEditable, referenceLabel, getImageSpec, isChrome, getChromeTypes, blockSchemas, allowedBlockTypes, declareBlockCatalogue, getBlockCatalogue, isInBlockCatalogue, catalogueBlockTypes, undeclaredBlockTypes, getPropDisplayName, defaultListItemForBlock, blockInstanceSchema, blockInstanceSchemaLenient, validateBlockProps, getBlockJsonSchema, } from "./blocks/_registry.ts";
 export { defaultPropsForType, declaredDefaultPropsForType, resolveHeadingTag, resolveItemHeadingTag, DEFAULT_HEADING_LEVELS, } from "./blocks/index.ts";
 export { blockTypeToCamel, camelToBlockType, blockTypeToLower, lowerToBlockType, } from "./block-names.ts";
-export { makeAddBlock, generateBlockId, makeAddItem, generateItemId, ensureItemIds, type AddBlockOp, type MakeAddBlockOptions, type AddItemOp, type MakeAddItemOptions, } from "./ops/builders.ts";
+export { makeAddBlock, generateBlockId, makeAddItem, generateItemId, ensureItemIds, withoutGeneratedItemIds, isGeneratedItemId, type AddBlockOp, type MakeAddBlockOptions, type AddItemOp, type MakeAddItemOptions, } from "./ops/builders.ts";
 export { THEME_TOKEN_TO_CSS_VARS, themeTokenKeys, semanticThemeTokensSchema, mapSemanticThemeTokens, type ThemeTokenKey, type SemanticThemeTokens, } from "./ops/theme-tokens.ts";
 export { chatStreamEventSchema, parseChatStreamFrame, type ChatStreamEvent, type ChatStreamEventType, type ChatStreamFrame, } from "./chat-events.ts";
 export { type PageMeta, type PageDoc, type SiteConfig, type Operation, type EditPlan, type PatchRejectReason, type ApplyPatchMessage, type PatchAckMessage, type ResetToServerMessage, pageMetaSchema, pageDocSchema, pageDocSchemaLenient, siteConfigSchema, operationSchema, editPlanSchema, demoPublishedPages, demoSiteConfig, } from "./schemas.ts";

package/dist/index.js

@@ -37,7 +37,7 @@ export {
 // Constants & helpers
 IMAGE_PLACEHOLDER, isImagePlaceholder, 
 // Registry functions
-registerBlock, resetListFieldWarnings, getBlockMeta, getAllBlockMeta, blockAcceptsProp, blockListItemAcceptsKey, getImageFields, getListImageFields, getMediaFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, 
+registerBlock, isBuiltinBlock, resetListFieldWarnings, getBlockMeta, getAllBlockMeta, blockAcceptsProp, blockListItemAcceptsKey, getImageFields, getListImageFields, getMediaFields, isFieldInlineEditable, referenceLabel, getImageSpec, isChrome, getChromeTypes, 
 // Backwards-compatible exports
 blockSchemas, allowedBlockTypes, 
 // The catalogue a site actually renders — see `declareBlockCatalogue`
@@ -48,7 +48,7 @@ getPropDisplayName, defaultListItemForBlock,
 blockInstanceSchema, blockInstanceSchemaLenient, validateBlockProps, getBlockJsonSchema, } from "./blocks/_registry.js";
 export { defaultPropsForType, declaredDefaultPropsForType, resolveHeadingTag, resolveItemHeadingTag, DEFAULT_HEADING_LEVELS, } from "./blocks/index.js";
 export { blockTypeToCamel, camelToBlockType, blockTypeToLower, lowerToBlockType, } from "./block-names.js";
-export { makeAddBlock, generateBlockId, makeAddItem, generateItemId, ensureItemIds, } from "./ops/builders.js";
+export { makeAddBlock, generateBlockId, makeAddItem, generateItemId, ensureItemIds, withoutGeneratedItemIds, isGeneratedItemId, } from "./ops/builders.js";
 export { THEME_TOKEN_TO_CSS_VARS, themeTokenKeys, semanticThemeTokensSchema, mapSemanticThemeTokens, } from "./ops/theme-tokens.js";
 export { chatStreamEventSchema, parseChatStreamFrame, } from "./chat-events.js";
 export { 

package/dist/ops/builders.d.ts

@@ -65,3 +65,37 @@ export declare function ensureItemIds(blocks: Array<{
     type: string;
     props: unknown;
 }>): boolean;
+/**
+ * Whether `value` is an id this module generated, rather than one the content
+ * arrived with.
+ *
+ * The shape is the whole point: eight lowercase hex characters behind `i_`. A
+ * CMS's own row key — a Sanity `_key`, a Contentful `sys.id`, a Storyblok
+ * `_uid` flattened to `id` — does not match, and must not be stripped by
+ * anything below.
+ */
+export declare function isGeneratedItemId(value: unknown): boolean;
+/**
+ * The same blocks with Avocado's own list-row stamps removed.
+ *
+ * `ensureItemIds` writes an `id` onto every row of every declared list so the
+ * panel can keep rows stable under reordering and a planner can address one by
+ * name. It goes into `props`, because `props` is the only thing persisted — and
+ * it comes back out of `/draft/pages` indistinguishable from content.
+ *
+ * An adapter that compares its draft against freshly-read CMS content therefore
+ * sees **every block with a list** as changed, permanently and from the first
+ * load. On the integration that found this, a one-field edit to one page
+ * produced a publish that wanted to rewrite 117 stories; the same publish
+ * touches one after this. Diagnosing it took a field-level diff of two JSON
+ * blobs, which is why the keys are named here in code rather than described in
+ * a document.
+ *
+ * Returns a deep copy — the draft keeps its ids, which every op still needs.
+ * Only ids this module generated are removed, so a row that carries the CMS's
+ * own `id` keeps it.
+ */
+export declare function withoutGeneratedItemIds<T extends {
+    type: string;
+    props: unknown;
+}>(blocks: T[]): T[];

package/dist/ops/builders.js

@@ -108,6 +108,69 @@ export function ensureItemIds(blocks) {
     }
     return changed;
 }
+/**
+ * Whether `value` is an id this module generated, rather than one the content
+ * arrived with.
+ *
+ * The shape is the whole point: eight lowercase hex characters behind `i_`. A
+ * CMS's own row key — a Sanity `_key`, a Contentful `sys.id`, a Storyblok
+ * `_uid` flattened to `id` — does not match, and must not be stripped by
+ * anything below.
+ */
+export function isGeneratedItemId(value) {
+    return typeof value === "string" && /^i_[0-9a-f]{8}$/.test(value);
+}
+/**
+ * The same blocks with Avocado's own list-row stamps removed.
+ *
+ * `ensureItemIds` writes an `id` onto every row of every declared list so the
+ * panel can keep rows stable under reordering and a planner can address one by
+ * name. It goes into `props`, because `props` is the only thing persisted — and
+ * it comes back out of `/draft/pages` indistinguishable from content.
+ *
+ * An adapter that compares its draft against freshly-read CMS content therefore
+ * sees **every block with a list** as changed, permanently and from the first
+ * load. On the integration that found this, a one-field edit to one page
+ * produced a publish that wanted to rewrite 117 stories; the same publish
+ * touches one after this. Diagnosing it took a field-level diff of two JSON
+ * blobs, which is why the keys are named here in code rather than described in
+ * a document.
+ *
+ * Returns a deep copy — the draft keeps its ids, which every op still needs.
+ * Only ids this module generated are removed, so a row that carries the CMS's
+ * own `id` keeps it.
+ */
+export function withoutGeneratedItemIds(blocks) {
+    return blocks.map((block) => {
+        const listFields = getBlockMeta(block.type)?.listFields;
+        const props = block.props;
+        if (!listFields || !props || typeof props !== "object" || Array.isArray(props))
+            return block;
+        const nextProps = { ...props };
+        let changed = false;
+        for (const listKey of Object.keys(listFields)) {
+            const list = nextProps[listKey];
+            if (!Array.isArray(list))
+                continue;
+            let listChanged = false;
+            const rows = list.map((item) => {
+                if (!item || typeof item !== "object" || Array.isArray(item))
+                    return item;
+                const rec = item;
+                if (!isGeneratedItemId(rec.id))
+                    return item;
+                const { id: _dropped, ...rest } = rec;
+                listChanged = true;
+                return rest;
+            });
+            if (listChanged) {
+                nextProps[listKey] = rows;
+                changed = true;
+            }
+        }
+        return changed ? { ...block, props: nextProps } : block;
+    });
+}
 function randomSuffix() {
     const c = globalThis.crypto;
     if (c?.randomUUID)

package/dist/panel-coverage.d.ts

@@ -37,7 +37,7 @@ export type PanelFindingCode =
  | "phantom_field"
 /** The type name exists in the editor's own registry with a different shape. */
  | "colliding_type"
-/** An image row labelled by its filename while a populated alt field sits beside it. */
+/** An image row labelled by its filename because the alt field beside it is empty. */
  | "filename_row_label";
 export type PanelFinding = {
     code: PanelFindingCode;
@@ -73,14 +73,29 @@ type ManifestLike = {
  * The label the panel puts on a collapsed list row.
  *
  * Mirrors `PropertyPanel`'s own derivation exactly, including its fallbacks: the
- * first text-ish field with a value, else the filename of the first image, else
- * `Item N`. Kept here so the two cannot drift — the panel imports this.
+ * first text-ish field with a value, else that image's alt text, else the
+ * filename of the first image, else `Item N`. Kept here so the two cannot drift
+ * — the panel imports this.
+ *
+ * "With a value" is load-bearing and was, for a while, only true of the comment.
+ * The code took the first *declared* candidate and read whatever it held, so a
+ * field set listing an empty `title` ahead of a populated `text` labelled the row
+ * `Item 4` with the answer sitting one key further along. Each step below scans
+ * for content instead of stopping at the first key of the right kind.
+ *
+ * Alt text outranks the filename because it is the only one of the two a person
+ * wrote on purpose. A column of `20250904_075546.webp`, `20250904_081233.webp`
+ * tells a reader which row is which no better than `Item 4` did, while the alt
+ * beside it already says "Pool bei Sonnenuntergang". The first version of this
+ * ranked the filename higher and the check then reported the mismatch as a
+ * finding — which told a site its alt text was the better label while the panel
+ * had no way to use it. A finding with no remedy gets switched off.
  */
 export declare function deriveRowLabel(fields: Record<string, FieldMeta>, item: Record<string, unknown>, index: number, options?: {
     discriminator?: string;
 }): {
     label: string;
-    source: "text" | "filename" | "fallback";
+    source: "text" | "alt" | "filename" | "fallback";
 };
 export declare function panelCoverage(manifest: ManifestLike, pages: PageLike[], options?: {
     builtinTypes?: Record<string, BlockMeta>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/shared",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,7 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/richtext": "^0.5.0"
+    "@avocadostudio-ai/richtext": "^0.5.1"
   },
   "devDependencies": {
     "tsx": "^4.21.0",