@avocadostudio-ai/shared 0.4.0 → 0.5.1

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) {
+    // 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)
+        return false;
     if (!DRAWN_KINDS.has(meta.kind))
         return false;
     if (meta.kind === "image")
@@ -122,6 +126,28 @@ function hasContent(value) {
 function generalizeIndex(path) {
     return path.replace(/\[\d+\]/g, "[]");
 }
+/**
+ * Is this field marked — at its own path, or at a finer one inside it?
+ *
+ * A prop the manifest calls `buttons` is not always drawn as one element. A
+ * renderer that maps over it and marks `buttons[].label` on each button has
+ * instrumented that field *better* than a single marker on the container would,
+ * and reporting it as missing is the kind of unclosable finding that gets a
+ * checker ignored. Villa hit exactly this, and it was one of the six gaps that
+ * kept its report off 100%.
+ *
+ * The prefix test is on `key[` and `key.` rather than on `key`, so `title` is
+ * not counted as covering `titleColor`.
+ */
+function isCovered(key, paths) {
+    if (paths.has(key))
+        return true;
+    for (const path of paths) {
+        if (path.startsWith(`${key}[`) || path.startsWith(`${key}.`))
+            return true;
+    }
+    return false;
+}
 /**
  * The item fields a list is expected to have markers for, given what is in it.
  *
@@ -260,7 +286,7 @@ export function editableCoverage(manifest, blocks) {
             if (knowsContent && !filled.has(key))
                 continue;
             expected += 1;
-            if (!paths.has(key)) {
+            if (!isCovered(key, paths)) {
                 missing.push(key);
             }
             else if (meta.kind === "image" && voids.has(key)) {
@@ -288,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/editor-block-meta.d.ts

@@ -0,0 +1,70 @@
+/**
+ * What the property panel should render for one block type.
+ *
+ * There are two sources and they disagree. The **manifest** is what the site
+ * serves over HTTP: its own schema, its own labels, its own list metadata. The
+ * **registry** is whatever is registered in the process doing the rendering —
+ * and in the editor that is its *own* bundled copy of `@avocadostudio-ai/blocks`,
+ * which registers the built-in types on import. A site that calls
+ * `registerBlocks` fills the registry inside the *orchestrator*; the editor's
+ * in-browser registry is a third source of truth that nobody registered into.
+ *
+ * This used to be inline in `PropertyPanel`, with the rule "the manifest decides
+ * *which* fields exist; the registry supplies richer metadata for any field in
+ * both". That is right when the site's `Hero` really is Avocado's `Hero`, and
+ * exactly wrong when the site re-registered that name with its own shape — which
+ * is the common case, because these are the names blocks *have*. A real
+ * integration collided on seven of its eight types and got a property panel
+ * describing Avocado's blocks: its `Left column` list was labelled
+ * `Left column items`, its `Variant` became `Style variant`.
+ *
+ * So the rule is now about *who said it*, not *who has it*:
+ *
+ * - The manifest **declared** the field (it is in `definition.fields`, not merely
+ *   derived from the JSON schema) → the site said this out loud, and wins.
+ * - The manifest only **derived** it → the site said nothing beyond the schema,
+ *   and the registry's entry is a better answer than an inference, because it
+ *   carries `imageSpec`, `options`, `inlineEditable` and a human label.
+ *
+ * It also carries `discriminator` and `itemFieldsByType` through, which the old
+ * merge dropped by constructing a two-key object. That was pure data loss: the
+ * manifest carries both, and without them the panel narrows nothing, so every
+ * row of a polymorphic list is measured against the merged union of all
+ * branches. Rows whose branch has no text field then fall back to `Item 4`,
+ * `Item 5` — in the case that found this, a bullet list and a pair of CTAs, both
+ * fully described in the manifest the panel had in hand.
+ */
+import type { BlockMeta, FieldMeta, ListFieldMeta } from "./blocks/_registry.ts";
+/** The shape this needs from a manifest entry — a structural subset of `BlockDefinition`. */
+export type EditorBlockDefinition = {
+    type: string;
+    displayName?: string;
+    propsSchema: Record<string, unknown>;
+    fields?: Record<string, unknown>;
+    listFields?: Record<string, unknown>;
+};
+/**
+ * Merge one manifest block definition with whatever the local registry knows
+ * about the same type.
+ *
+ * `registryMeta` is `undefined` for a type the registry has never heard of — a
+ * net-new block — and then the manifest is simply the answer.
+ */
+export declare function resolveEditorBlockMeta(definition: EditorBlockDefinition, registryMeta: BlockMeta | undefined): BlockMeta;
+/**
+ * The fields one list row is actually edited with.
+ *
+ * Polymorphic lists narrow to the branch named by the row's own discriminant
+ * value; anything else — no discriminator, or a value with no branch — falls
+ * back to the union in `itemFields`, which is the pre-narrowing behaviour and
+ * the right answer when there is nothing to narrow by.
+ *
+ * Exported because the panel and the editing-surface check must agree exactly.
+ * A checker that approximates this reports gaps the panel does not have, and
+ * misses the ones it does.
+ */
+export declare function resolveListItemFields(listField: ListFieldMeta, item: Record<string, unknown>): {
+    fields: Record<string, FieldMeta>;
+    discriminantValue: string;
+    matchedBranch: boolean;
+};

package/dist/editor-block-meta.js

@@ -0,0 +1,131 @@
+/**
+ * What the property panel should render for one block type.
+ *
+ * There are two sources and they disagree. The **manifest** is what the site
+ * serves over HTTP: its own schema, its own labels, its own list metadata. The
+ * **registry** is whatever is registered in the process doing the rendering —
+ * and in the editor that is its *own* bundled copy of `@avocadostudio-ai/blocks`,
+ * which registers the built-in types on import. A site that calls
+ * `registerBlocks` fills the registry inside the *orchestrator*; the editor's
+ * in-browser registry is a third source of truth that nobody registered into.
+ *
+ * This used to be inline in `PropertyPanel`, with the rule "the manifest decides
+ * *which* fields exist; the registry supplies richer metadata for any field in
+ * both". That is right when the site's `Hero` really is Avocado's `Hero`, and
+ * exactly wrong when the site re-registered that name with its own shape — which
+ * is the common case, because these are the names blocks *have*. A real
+ * integration collided on seven of its eight types and got a property panel
+ * describing Avocado's blocks: its `Left column` list was labelled
+ * `Left column items`, its `Variant` became `Style variant`.
+ *
+ * So the rule is now about *who said it*, not *who has it*:
+ *
+ * - The manifest **declared** the field (it is in `definition.fields`, not merely
+ *   derived from the JSON schema) → the site said this out loud, and wins.
+ * - The manifest only **derived** it → the site said nothing beyond the schema,
+ *   and the registry's entry is a better answer than an inference, because it
+ *   carries `imageSpec`, `options`, `inlineEditable` and a human label.
+ *
+ * It also carries `discriminator` and `itemFieldsByType` through, which the old
+ * merge dropped by constructing a two-key object. That was pure data loss: the
+ * manifest carries both, and without them the panel narrows nothing, so every
+ * row of a polymorphic list is measured against the merged union of all
+ * branches. Rows whose branch has no text field then fall back to `Item 4`,
+ * `Item 5` — in the case that found this, a bullet list and a pair of CTAs, both
+ * fully described in the manifest the panel had in hand.
+ */
+import { resolveManifestFieldMeta } from "./block-manifest.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Keys the definition stated for itself, as opposed to keys inferred from its schema. */
+function declaredKeys(source) {
+    return isRecord(source) ? new Set(Object.keys(source)) : new Set();
+}
+/**
+ * Merge one manifest block definition with whatever the local registry knows
+ * about the same type.
+ *
+ * `registryMeta` is `undefined` for a type the registry has never heard of — a
+ * net-new block — and then the manifest is simply the answer.
+ */
+export function resolveEditorBlockMeta(definition, registryMeta) {
+    const derived = resolveManifestFieldMeta(definition);
+    if (!registryMeta) {
+        return {
+            displayName: definition.displayName ?? definition.type,
+            fields: derived.fields,
+            ...(Object.keys(derived.listFields).length > 0 ? { listFields: derived.listFields } : {})
+        };
+    }
+    const declaredFields = declaredKeys(definition.fields);
+    const fields = {};
+    for (const [key, fromManifest] of Object.entries(derived.fields)) {
+        const fromRegistry = registryMeta.fields[key];
+        // The site said it out loud, or the registry has nothing to add.
+        fields[key] = declaredFields.has(key) || !fromRegistry ? fromManifest : fromRegistry;
+    }
+    const declaredLists = declaredKeys(definition.listFields);
+    const listFields = {};
+    for (const [key, fromManifest] of Object.entries(derived.listFields)) {
+        const fromRegistry = registryMeta.listFields?.[key];
+        if (!fromRegistry || declaredLists.has(key)) {
+            listFields[key] = fromManifest;
+            continue;
+        }
+        const declaredItems = declaredKeys(isRecord(definition.listFields?.[key])
+            ? definition.listFields[key].itemFields
+            : undefined);
+        const itemFields = {};
+        for (const [itemKey, itemFromManifest] of Object.entries(fromManifest.itemFields)) {
+            const itemFromRegistry = fromRegistry.itemFields[itemKey];
+            itemFields[itemKey] =
+                declaredItems.has(itemKey) || !itemFromRegistry ? itemFromManifest : itemFromRegistry;
+        }
+        listFields[key] = {
+            ...fromManifest,
+            ...(fromManifest.label ?? fromRegistry.label
+                ? { label: fromManifest.label ?? fromRegistry.label }
+                : {}),
+            itemFields,
+            // Never synthesised, never dropped: whichever source has a branch map, keep it.
+            ...(fromManifest.discriminator ?? fromRegistry.discriminator
+                ? { discriminator: fromManifest.discriminator ?? fromRegistry.discriminator }
+                : {}),
+            ...(fromManifest.itemFieldsByType ?? fromRegistry.itemFieldsByType
+                ? { itemFieldsByType: fromManifest.itemFieldsByType ?? fromRegistry.itemFieldsByType }
+                : {})
+        };
+    }
+    return {
+        ...registryMeta,
+        displayName: definition.displayName ?? registryMeta.displayName,
+        fields,
+        ...(Object.keys(listFields).length > 0 ? { listFields } : {})
+    };
+}
+/**
+ * The fields one list row is actually edited with.
+ *
+ * Polymorphic lists narrow to the branch named by the row's own discriminant
+ * value; anything else — no discriminator, or a value with no branch — falls
+ * back to the union in `itemFields`, which is the pre-narrowing behaviour and
+ * the right answer when there is nothing to narrow by.
+ *
+ * Exported because the panel and the editing-surface check must agree exactly.
+ * A checker that approximates this reports gaps the panel does not have, and
+ * misses the ones it does.
+ */
+export function resolveListItemFields(listField, item) {
+    if (!listField.discriminator) {
+        return { fields: listField.itemFields, discriminantValue: "", matchedBranch: false };
+    }
+    const raw = item[listField.discriminator];
+    const discriminantValue = raw === undefined || raw === null ? "" : String(raw);
+    const branch = listField.itemFieldsByType?.[discriminantValue];
+    return {
+        fields: branch ?? listField.itemFields,
+        discriminantValue,
+        matchedBranch: Boolean(branch)
+    };
+}

package/dist/index.d.ts

@@ -4,14 +4,18 @@ export type { FieldDiffKind, FieldDiff, BlockDiffStatus, BlockDiff, PageDiffStat
 export { isImagePath, toAltPath, isAltPath, toImagePath, setPropAtPath } from "./editable-path.ts";
 export { extractMarkedBlocks, editableCoverage, formatEditableCoverage } from "./editable-coverage.ts";
 export type { MarkedBlock, BlockCoverageGap, EditableCoverage } from "./editable-coverage.ts";
+export { panelCoverage, formatPanelCoverage, deriveRowLabel } from "./panel-coverage.ts";
+export type { PanelCoverage, PanelFinding, PanelFindingCode } from "./panel-coverage.ts";
+export { resolveEditorBlockMeta, resolveListItemFields } from "./editor-block-meta.ts";
+export type { EditorBlockDefinition } from "./editor-block-meta.ts";
 export { parseLink, resolveLink, normalizeLinkPath, isKnownRoute, internalPathForUrl, rankLinkTargets, rankFileTargets, suggestLinkTargets, scoreLinkCandidate, suggestLinkTarget, newTabKeyFor, linkAttrs, isFilePath, knownFileExtensions, linksInRichText, type LinkKind, type ParsedLink, type ResolvedLink, type LinkPageOption, type LinkFileOption, type LinkSuggestions, } from "./links.ts";
 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

@@ -2,6 +2,8 @@ export { EDITOR_PROTOCOL_VERSION } from "./protocol.js";
 export { getConfiguredDraftSecret, getSafeInternalRedirectPath, validateDraftSecret } from "./draft-mode.js";
 export { isImagePath, toAltPath, isAltPath, toImagePath, setPropAtPath } from "./editable-path.js";
 export { extractMarkedBlocks, editableCoverage, formatEditableCoverage } from "./editable-coverage.js";
+export { panelCoverage, formatPanelCoverage, deriveRowLabel } from "./panel-coverage.js";
+export { resolveEditorBlockMeta, resolveListItemFields } from "./editor-block-meta.js";
 export { parseLink, resolveLink, normalizeLinkPath, isKnownRoute, internalPathForUrl, rankLinkTargets, rankFileTargets, suggestLinkTargets, scoreLinkCandidate, suggestLinkTarget, newTabKeyFor, linkAttrs, isFilePath, knownFileExtensions, linksInRichText, } from "./links.js";
 /*
  * The rich-text grammar lives in `@avocadostudio-ai/richtext`, which owns the
@@ -35,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`
@@ -46,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

@@ -0,0 +1,105 @@
+/**
+ * Can a human actually edit this site in the property panel?
+ *
+ * `editableCoverage` answers the same question for the *preview*: which fields
+ * carry a marker the overlay can find. This is the panel's half, and it was the
+ * half with no check at all — which is why a real integration shipped a panel
+ * whose list rows read `Item 4`, `Item 5`, whose labels came from somebody
+ * else's block, and whose polymorphic branches were never narrowed. Every one of
+ * those was visible in the data the whole time. Nobody was asking.
+ *
+ * The check needs no browser, no screenshot and no model. It has the manifest
+ * (what the panel will render) and the site's own pages (what the rows really
+ * contain), and every finding below is a disagreement between the two.
+ *
+ * It resolves metadata through `resolveEditorBlockMeta` and rows through
+ * `resolveListItemFields` — the same functions the panel itself uses — so its
+ * findings are the panel's behaviour rather than a model of it. A checker that
+ * approximates the panel reports gaps the panel does not have and misses the
+ * ones it does, and gets switched off within a week.
+ *
+ * Pass `builtinTypes` (the registry the *editor* will run with) to get the
+ * collision findings. Without it, collisions are simply not reported — an
+ * absent input is never evidence.
+ */
+import { type EditorBlockDefinition } from "./editor-block-meta.ts";
+import type { BlockMeta, FieldMeta } from "./blocks/_registry.ts";
+export type PanelFindingCode = 
+/** A list row the panel labels `Item N` — present in the content, unidentifiable in the panel. */
+"unlabelled_row"
+/** A row whose discriminant value has no branch, so it is edited against the union of all branches. */
+ | "unmatched_branch"
+/** A list declares a discriminator and no branch map, or vice versa. */
+ | "incomplete_polymorphism"
+/** A prop the content holds that no field or list describes — uneditable, and invisible. */
+ | "orphan_prop"
+/** A field declared for rows that no row ever has. Panel noise. */
+ | "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 because the alt field beside it is empty. */
+ | "filename_row_label";
+export type PanelFinding = {
+    code: PanelFindingCode;
+    blockType: string;
+    /** Where the problem is, in the same path grammar operations use. */
+    path?: string;
+    /** One page slug that exhibits it, so the report points somewhere. */
+    exampleSlug?: string;
+    /** How many occurrences across everything examined. */
+    count: number;
+    detail: string;
+};
+export type PanelCoverage = {
+    /** List rows examined across every page. */
+    rowsExamined: number;
+    /** Rows the panel can label from their own content. */
+    rowsLabelled: number;
+    findings: PanelFinding[];
+    /** Block types on a page that the manifest does not describe. Not our business, but worth saying. */
+    unknownBlockTypes: string[];
+};
+type PageLike = {
+    slug?: string;
+    blocks?: Array<{
+        type?: string;
+        props?: Record<string, unknown>;
+    } | null | undefined>;
+};
+type ManifestLike = {
+    blocks: EditorBlockDefinition[];
+};
+/**
+ * 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 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" | "alt" | "filename" | "fallback";
+};
+export declare function panelCoverage(manifest: ManifestLike, pages: PageLike[], options?: {
+    builtinTypes?: Record<string, BlockMeta>;
+}): PanelCoverage;
+/** A human-readable report, in the shape `formatEditableCoverage` uses. */
+export declare function formatPanelCoverage(report: PanelCoverage): string;
+export {};