@avocadostudio-ai/shared 0.5.0 → 0.6.0

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,9 @@ export declare const fieldMetaSchema: z.ZodObject<{
         }>>;
     }, z.core.$strip>>;
     multiline: z.ZodOptional<z.ZodBoolean>;
+    referenceLabelKey: z.ZodOptional<z.ZodString>;
+    panelOnly: z.ZodOptional<z.ZodBoolean>;
+    internal: z.ZodOptional<z.ZodBoolean>;
     inline: z.ZodOptional<z.ZodBoolean>;
     decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -57,6 +61,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 +81,9 @@ export declare const listFieldMetaSchema: z.ZodObject<{
             }>>;
         }, z.core.$strip>>;
         multiline: z.ZodOptional<z.ZodBoolean>;
+        referenceLabelKey: z.ZodOptional<z.ZodString>;
+        panelOnly: z.ZodOptional<z.ZodBoolean>;
+        internal: z.ZodOptional<z.ZodBoolean>;
         inline: z.ZodOptional<z.ZodBoolean>;
         decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -98,6 +106,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 +126,9 @@ export declare const listFieldMetaSchema: z.ZodObject<{
             }>>;
         }, z.core.$strip>>;
         multiline: z.ZodOptional<z.ZodBoolean>;
+        referenceLabelKey: z.ZodOptional<z.ZodString>;
+        panelOnly: z.ZodOptional<z.ZodBoolean>;
+        internal: z.ZodOptional<z.ZodBoolean>;
         inline: z.ZodOptional<z.ZodBoolean>;
         decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -145,6 +157,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 +177,9 @@ export declare const blockDefinitionSchema: z.ZodObject<{
             }>>;
         }, z.core.$strip>>;
         multiline: z.ZodOptional<z.ZodBoolean>;
+        referenceLabelKey: z.ZodOptional<z.ZodString>;
+        panelOnly: z.ZodOptional<z.ZodBoolean>;
+        internal: z.ZodOptional<z.ZodBoolean>;
         inline: z.ZodOptional<z.ZodBoolean>;
         decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -187,6 +203,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 +223,9 @@ export declare const blockDefinitionSchema: z.ZodObject<{
                 }>>;
             }, z.core.$strip>>;
             multiline: z.ZodOptional<z.ZodBoolean>;
+            referenceLabelKey: z.ZodOptional<z.ZodString>;
+            panelOnly: z.ZodOptional<z.ZodBoolean>;
+            internal: z.ZodOptional<z.ZodBoolean>;
             inline: z.ZodOptional<z.ZodBoolean>;
             decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
@@ -228,6 +248,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 +268,9 @@ export declare const blockDefinitionSchema: z.ZodObject<{
                 }>>;
             }, z.core.$strip>>;
             multiline: z.ZodOptional<z.ZodBoolean>;
+            referenceLabelKey: z.ZodOptional<z.ZodString>;
+            panelOnly: z.ZodOptional<z.ZodBoolean>;
+            internal: z.ZodOptional<z.ZodBoolean>;
             inline: z.ZodOptional<z.ZodBoolean>;
             decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
@@ -281,6 +305,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 +325,9 @@ export declare const blockManifestSchema: z.ZodObject<{
                 }>>;
             }, z.core.$strip>>;
             multiline: z.ZodOptional<z.ZodBoolean>;
+            referenceLabelKey: z.ZodOptional<z.ZodString>;
+            panelOnly: z.ZodOptional<z.ZodBoolean>;
+            internal: z.ZodOptional<z.ZodBoolean>;
             inline: z.ZodOptional<z.ZodBoolean>;
             decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
@@ -323,6 +351,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 +371,9 @@ export declare const blockManifestSchema: z.ZodObject<{
                     }>>;
                 }, z.core.$strip>>;
                 multiline: z.ZodOptional<z.ZodBoolean>;
+                referenceLabelKey: z.ZodOptional<z.ZodString>;
+                panelOnly: z.ZodOptional<z.ZodBoolean>;
+                internal: z.ZodOptional<z.ZodBoolean>;
                 inline: z.ZodOptional<z.ZodBoolean>;
                 decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     name: z.ZodString;
@@ -364,6 +396,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 +416,9 @@ export declare const blockManifestSchema: z.ZodObject<{
                     }>>;
                 }, z.core.$strip>>;
                 multiline: z.ZodOptional<z.ZodBoolean>;
+                referenceLabelKey: z.ZodOptional<z.ZodString>;
+                panelOnly: z.ZodOptional<z.ZodBoolean>;
+                internal: z.ZodOptional<z.ZodBoolean>;
                 inline: z.ZodOptional<z.ZodBoolean>;
                 decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     name: z.ZodString;
@@ -448,7 +484,11 @@ export declare function validateManifestDefaultProps(blocks: BlockDefinition[]):
  *
  * - `propsSchema` decides *which* props exist. A declared entry for a key the
  *   schema does not expose is ignored, not added — otherwise a stale manifest
- *   would put a control on a prop the block cannot store.
+ *   would put a control on a prop the block cannot store. The one exception is
+ *   `internal: true`, which adds no control by definition: it is how a site
+ *   names a prop the derivation skipped for being structural (a Contentful
+ *   `sys`, a `__source` snapshot) so the coverage checkers stop reporting it as
+ *   undescribed. Nothing else can be conjured this way.
  * - A declared entry is merged *over* the derived one, key by key, so a site
  *   can supply just `multiline` and keep the label and options that were
  *   inferred for it.

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,22 @@ 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(),
+    /*
+     * Both of these decide whether a surface *mentions* a field, and every one
+     * of those surfaces is on the far side of this boundary — the panel, the
+     * planner's schema summary, the coverage checkers. A key this schema omits
+     * is stripped rather than rejected, so an undeclared flag here means the
+     * declaration silently does nothing where it was supposed to act.
+     */
+    panelOnly: z.boolean().optional(),
+    internal: z.boolean().optional(),
     inline: z.boolean().optional(),
     decorators: z
         .array(z.object({ name: z.string().min(1), title: z.string().optional() }))
@@ -250,6 +266,29 @@ const FILE_MEDIA_TYPE_RE = /^application\/(?!json\b)|^text\/(?:csv|calendar)\b/i
 function isInternalPropKey(key) {
     return key.startsWith("_");
 }
+/**
+ * The same statement the paragraph above makes, as a field rather than as an
+ * absence.
+ *
+ * These props used to be skipped outright, which kept them out of the panel
+ * and away from the planner — correct, and invisible to everything that reads
+ * the resolved metadata afterwards. `panelCoverage` is the one that noticed:
+ * a prop in the content and in no field set is an `orphan_prop`, and one
+ * Storyblok integration's `_uid` produced **~800 of them**, burying every real
+ * finding under a wall of noise that could not be closed. There was no way to
+ * close it, because "skipped" and "never declared" were the same thing.
+ *
+ * Emitting `internal: true` says it out loud instead. Every surface that must
+ * not mention the prop checks that flag, so nothing about the promise above
+ * changes; what changes is that the checkers can tell a known non-content prop
+ * from an undescribed one.
+ *
+ * `kind` is a formality here — nothing renders the field — so it does not
+ * matter that a `_key` and a `sys` object both come out as `text`.
+ */
+function internalFieldMeta(key) {
+    return { kind: "text", label: labelFromKey(key), internal: true };
+}
 function labelFromKey(key) {
     // ctaText → "CTA text", imageUrl → "Image", logoAlt → "Logo alt",
     // background_image → "Background image", video_url → "Video", src → "Src"
@@ -341,7 +380,11 @@ function deriveItemFields(itemSchema) {
     for (const [key, propSchema] of Object.entries(props)) {
         if (!isObject(propSchema))
             continue;
-        if (isInternalPropKey(key) || isItemIdentityKey(key))
+        if (isInternalPropKey(key)) {
+            fields[key] = internalFieldMeta(key);
+            continue;
+        }
+        if (isItemIdentityKey(key))
             continue;
         // Skip opaque object/array props (they'd render as "[object Object]"), but
         // keep richtext docs — those self-identify and get the richtext editor.
@@ -436,8 +479,10 @@ export function deriveFieldMetaFromSchema(propsSchema) {
     for (const [key, propSchema] of Object.entries(props)) {
         if (!isObject(propSchema))
             continue;
-        if (isInternalPropKey(key))
+        if (isInternalPropKey(key)) {
+            fields[key] = internalFieldMeta(key);
             continue;
+        }
         const type = typeof propSchema.type === "string" ? propSchema.type : undefined;
         // Array of a discriminated union (oneOf/anyOf of object branches) →
         // polymorphic list field: per-branch fields keyed by the discriminant value.
@@ -497,7 +542,11 @@ export function validateManifestDefaultProps(blocks) {
  *
  * - `propsSchema` decides *which* props exist. A declared entry for a key the
  *   schema does not expose is ignored, not added — otherwise a stale manifest
- *   would put a control on a prop the block cannot store.
+ *   would put a control on a prop the block cannot store. The one exception is
+ *   `internal: true`, which adds no control by definition: it is how a site
+ *   names a prop the derivation skipped for being structural (a Contentful
+ *   `sys`, a `__source` snapshot) so the coverage checkers stop reporting it as
+ *   undescribed. Nothing else can be conjured this way.
  * - A declared entry is merged *over* the derived one, key by key, so a site
  *   can supply just `multiline` and keep the label and options that were
  *   inferred for it.
@@ -508,7 +557,20 @@ export function resolveManifestFieldMeta(definition) {
     const resolvedFields = {};
     for (const [key, derived] of Object.entries(fields)) {
         const declared = declaredFields[key];
-        resolvedFields[key] = isObject(declared) ? { ...derived, ...declared } : derived;
+        const merged = isObject(declared) ? { ...derived, ...declared } : derived;
+        // The underscore convention is not negotiable by declaration: a site may
+        // label `_key` or change its kind, and it still may not hand it to a
+        // person, because the value typed there is the address a field-level
+        // publish patches by.
+        resolvedFields[key] = isInternalPropKey(key) ? { ...merged, internal: true } : merged;
+    }
+    for (const [key, declared] of Object.entries(declaredFields)) {
+        if (key in resolvedFields)
+            continue;
+        if (!isObject(declared) || declared.internal !== true)
+            continue;
+        const fm = declared;
+        resolvedFields[key] = { label: labelFromKey(key), ...fm, kind: fm.kind ?? "text" };
     }
     const declaredLists = isObject(definition.listFields) ? definition.listFields : {};
     const resolvedListFields = {};

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,46 @@ export type FieldMeta = {
      * Use this one when there is no element at all.
      */
     panelOnly?: boolean;
+    /**
+     * This prop belongs to the system that stores the content, not to anyone
+     * editing it.
+     *
+     * Storyblok's `_uid`, Contentful's `sys.id`, a `__source` snapshot, a
+     * revision stamp: the publisher needs them, a person must never edit them,
+     * and the planner must never be told they exist. Until this flag there was
+     * no way to say so, so they rode along undeclared — which is not the same as
+     * absent. An undeclared prop is an `orphan_prop` to `panelCoverage`, and one
+     * integration's `_uid` produced **~800 of them**, burying every real finding
+     * under a wall of noise that could not be closed.
+     *
+     * Declaring the prop internal says the opposite of what leaving it out says:
+     * "this is known, it is not content, and nothing that talks to a human or a
+     * model should mention it." Concretely it is hidden from the property panel,
+     * absent from the schema summary the planner reads, not expected to carry a
+     * preview marker, never offered for translation, and not a coverage finding
+     * in either direction — neither an orphan nor a phantom.
+     *
+     * It is not access control. The value still rides in `props`, still
+     * round-trips through the draft, and is still what the adapter writes back;
+     * an operation that names one is refused the way any undeclared prop is,
+     * because the planner was never told about it.
+     *
+     * `panelOnly` is the weaker neighbour and means almost the reverse: *a
+     * person does edit this, just not on the page.* Reach for that one when the
+     * field has no element; reach for this one when the field has no audience.
+     */
+    internal?: 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 +196,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 +293,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

@@ -49,6 +49,10 @@ const DRAWN_KINDS = new Set(["text", "richtext", "image"]);
  * button, and the panel offering one is the site saying the image is editable.
  */
 function needsMarker(meta) {
+    // Not content at all — a CMS's `_uid`, a revision stamp. Nobody edits it
+    // anywhere, so there is nothing on the page for it to be missing from.
+    if (meta.internal)
+        return false;
     // The site has said outright that nothing on the page draws this — a
     // `sectionId`, a `<video poster>`, an input's `placeholder`. See `panelOnly`.
     if (meta.panelOnly)
@@ -73,10 +77,19 @@ const VOID_ELEMENTS = new Set([
     "link", "meta", "param", "source", "track", "wbr",
 ]);
 /** One element: its tag name, and the raw attribute text, quotes respected. */
-const TAG_RE = /<([a-zA-Z][\w-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/g;
+const TAG_RE = /<(\/?)([a-zA-Z][\w-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/g;
 const BLOCK_ID_RE = /\bdata-block-id="([^"]*)"/;
 const BLOCK_TYPE_RE = /\bdata-block-type="([^"]*)"/;
 const TARGET_RE = /\bdata-editable-target="([^"]*)"/;
+const SCOPE_RE = /\bdata-editable-scope="([^"]*)"/;
+/** `items[3]` + `question` → `items[3].question`; `cards` + `[0].title` → `cards[0].title`. */
+function joinPath(scope, path) {
+    if (scope === "")
+        return path;
+    if (path === "")
+        return scope;
+    return path.startsWith("[") ? `${scope}${path}` : `${scope}.${path}`;
+}
 /**
  * Read the marked blocks out of a rendered page's HTML.
  *
@@ -90,9 +103,35 @@ const TARGET_RE = /\bdata-editable-target="([^"]*)"/;
 export function extractMarkedBlocks(html) {
     const blocks = [];
     let current = null;
+    /*
+     * The open elements that carry a `data-editable-scope`, innermost last, each
+     * remembered with the tag that will close it. A component rendering a list
+     * row marks a bare `question` and its parent supplies `items[3]`, so the
+     * path this file compares against the manifest exists only as the join —
+     * see `editableScopeProps`. Without the stack a scoped site's every field
+     * reads as missing, and the check that exists to catch a lost marker becomes
+     * the reason nobody runs it.
+     */
+    const scopes = [];
+    const depths = new Map();
     for (const match of html.matchAll(TAG_RE)) {
-        const tag = match[1].toLowerCase();
-        const attrs = match[2] ?? "";
+        const closing = match[1] === "/";
+        const tag = match[2].toLowerCase();
+        const attrs = match[3] ?? "";
+        const selfClosing = attrs.trimEnd().endsWith("/");
+        const isVoid = VOID_ELEMENTS.has(tag);
+        if (closing) {
+            const depth = (depths.get(tag) ?? 0) - 1;
+            depths.set(tag, depth);
+            while (scopes.length > 0) {
+                const top = scopes[scopes.length - 1];
+                if (top.tag === tag && top.depth === depth)
+                    scopes.pop();
+                else
+                    break;
+            }
+            continue;
+        }
         const blockId = BLOCK_ID_RE.exec(attrs)?.[1];
         const blockType = BLOCK_TYPE_RE.exec(attrs)?.[1];
         if (blockId !== undefined || blockType !== undefined) {
@@ -102,13 +141,29 @@ export function extractMarkedBlocks(html) {
                 paths: [],
             };
             blocks.push(current);
+            // A path is scoped from the block down, so a scope opened outside this
+            // block must not reach into it.
+            scopes.length = 0;
         }
         const target = TARGET_RE.exec(attrs)?.[1];
         if (target !== undefined && current) {
-            current.paths.push(target);
-            if (VOID_ELEMENTS.has(tag))
-                (current.voidPaths ??= []).push(target);
+            const path = scopes.reduce((acc, s) => joinPath(acc, s.scope), "");
+            const full = joinPath(path, target);
+            current.paths.push(full);
+            if (isVoid)
+                (current.voidPaths ??= []).push(full);
         }
+        if (isVoid || selfClosing)
+            continue;
+        const depth = depths.get(tag) ?? 0;
+        depths.set(tag, depth + 1);
+        const scope = SCOPE_RE.exec(attrs)?.[1];
+        // The scoping element's own marker is not inside its scope — a component
+        // that both scopes its children and marks a field of its own would
+        // otherwise prefix its own path with the scope it sets for them. That is
+        // why this comes after the target is recorded.
+        if (scope !== undefined && scope !== "")
+            scopes.push({ tag, scope, depth });
     }
     return blocks;
 }
@@ -314,7 +369,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.6.0",
   "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.6.0"
   },
   "devDependencies": {
     "tsx": "^4.21.0",