@avocadostudio-ai/shared 0.4.0 → 0.5.0

package/dist/blocks/_registry.d.ts

@@ -76,6 +76,27 @@ export type FieldMeta = {
     }[];
     /** Whether the field is required. Auto-derived from Zod schema at registration. */
     required?: boolean;
+    /**
+     * This field is edited in the property panel and nowhere else, by design.
+     *
+     * Not every editable prop is *drawn* as an element. A `sectionId` becomes an
+     * HTML `id`; a video's `poster` and an input's `placeholder` are attributes;
+     * a form field's `key` and `type` are configuration. None of them has an
+     * element that could carry `data-editable-target`, so the preview cannot
+     * offer them and the panel is the whole of their UI.
+     *
+     * `editableCoverage` takes this as "no marker expected", which is what makes
+     * the number mean something: without it a correct integration reports 88%
+     * and the integrator gating on it has to hard-code a magic threshold, at
+     * which point a real regression that drops one marker while a new field adds
+     * another slips through. With it, 100% is reachable and anything less is
+     * actionable.
+     *
+     * `inlineEditable: false` is a *different* statement, and narrower: it says a
+     * text field is not typed into on the page, and it says nothing about images.
+     * Use this one when there is no element at all.
+     */
+    panelOnly?: boolean;
 };
 /** Metadata for list-type props (features, items, cards). */
 export type ListFieldMeta = {

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)) {

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,6 +4,10 @@ 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";

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

package/dist/panel-coverage.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 while a populated alt field sits beside it. */
+ | "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 the filename of the first image, else
+ * `Item N`. Kept here so the two cannot drift — the panel imports this.
+ */
+export declare function deriveRowLabel(fields: Record<string, FieldMeta>, item: Record<string, unknown>, index: number, options?: {
+    discriminator?: string;
+}): {
+    label: string;
+    source: "text" | "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 {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/shared",
-  "version": "0.4.0",
+  "version": "0.5.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.4.0"
+    "@avocadostudio-ai/richtext": "^0.5.0"
   },
   "devDependencies": {
     "tsx": "^4.21.0",