@avocadostudio-ai/shared 0.3.2 → 0.4.0

package/dist/blocks/cta.js

@@ -7,8 +7,10 @@ registerBlock("CTA", {
         description: z.string().min(1),
         ctaText: z.string().min(1),
         ctaHref: z.string().min(1),
+        ctaNewTab: z.boolean().optional(),
         secondaryCtaText: z.string().optional(),
-        secondaryCtaHref: z.string().optional()
+        secondaryCtaHref: z.string().optional(),
+        secondaryCtaNewTab: z.boolean().optional()
     }),
     meta: {
         displayName: "Call to Action",
@@ -18,9 +20,11 @@ registerBlock("CTA", {
             title: f.text("Headline"),
             description: f.longtext("Description"),
             ctaText: f.text("Button text"),
-            ctaHref: f.url("Button link"),
+            ctaHref: f.link("Button link"),
+            ctaNewTab: f.newTab(),
             secondaryCtaText: f.text("Secondary button text"),
-            secondaryCtaHref: f.url("Secondary button link"),
+            secondaryCtaHref: f.link("Secondary button link"),
+            secondaryCtaNewTab: f.newTab(),
             headingLevel: f.headingLevel(),
         }
     }

package/dist/blocks/feature-grid.js

@@ -25,7 +25,7 @@ registerBlock("FeatureGrid", {
             features: {
                 label: "Features",
                 itemFields: {
-                    icon: f.text("Icon (single emoji)"),
+                    icon: f.icon(),
                     title: f.text("Feature title"),
                     description: f.longtext("Feature description"),
                 }

package/dist/blocks/hero.js

@@ -7,13 +7,15 @@ registerBlock("Hero", {
         subheading: z.string().min(1),
         ctaText: z.string().min(1),
         ctaHref: z.string().min(1),
+        ctaNewTab: z.boolean().optional(),
         imageUrl: z.string().min(1),
         imageAlt: z.string().min(1),
         imagePosition: z.enum(["left", "right", "full"]).default("right").catch("right"),
         textAlign: z.enum(["left", "center"]).default("left").catch("left"),
         eyebrow: z.string().optional(),
         secondaryCtaText: z.string().optional(),
-        secondaryCtaHref: z.string().optional()
+        secondaryCtaHref: z.string().optional(),
+        secondaryCtaNewTab: z.boolean().optional()
     }),
     meta: {
         displayName: "Hero",
@@ -23,14 +25,16 @@ registerBlock("Hero", {
             heading: f.text("Heading"),
             subheading: f.text("Subheading"),
             ctaText: f.text("CTA button text"),
-            ctaHref: f.url("CTA link"),
+            ctaHref: f.link("CTA link"),
+            ctaNewTab: f.newTab(),
             imageUrl: f.image("Hero image", { aspectRatio: "landscape", width: 1536, height: 1024 }),
             imageAlt: f.imageAlt("Hero image alt text"),
             imagePosition: { kind: "enum", label: "Image position", options: ["left", "right", "full"], inlineEditable: false },
             textAlign: { kind: "enum", label: "Text alignment", options: ["left", "center"], inlineEditable: false },
             eyebrow: f.text("Eyebrow text"),
             secondaryCtaText: f.text("Secondary CTA text"),
-            secondaryCtaHref: f.url("Secondary CTA link"),
+            secondaryCtaHref: f.link("Secondary CTA link"),
+            secondaryCtaNewTab: f.newTab(),
             headingLevel: f.headingLevel(),
         }
     }

package/dist/blocks/site-header.js

@@ -5,6 +5,7 @@ const navLinkLeaf = z.object({
     id: z.string().optional(),
     label: z.string().min(1),
     href: z.string().min(1),
+    newTab: z.boolean().optional(),
 });
 registerBlock("SiteHeader", {
     schema: z.object({
@@ -29,7 +30,8 @@ registerBlock("SiteHeader", {
                 label: "Nav links",
                 itemFields: {
                     label: f.text("Link label"),
-                    href: f.url("Link URL"),
+                    href: f.link("Link URL"),
+                    newTab: f.newTab(),
                 },
             },
         },

package/dist/blocks/stats.js

@@ -21,7 +21,7 @@ registerBlock("Stats", {
             stats: {
                 label: "Stats",
                 itemFields: {
-                    icon: f.text("Icon (single emoji)"),
+                    icon: f.icon(),
                     value: f.text("Value"),
                     label: f.text("Label"),
                     description: f.text("Description"),

package/dist/blocks/table.js

@@ -16,8 +16,11 @@ registerBlock("Table", {
         fields: {
             title: f.text("Section title"),
             headingLevel: f.headingLevel(),
-            headers: f.text("Column headers"),
-            rows: f.text("Table rows"),
+            // Both are lists of scalars, which `FieldKind` cannot name — the panel
+            // recognises the value's shape instead: `headers` edits one per line,
+            // `rows` (string[][]) is shown there and edited cell-by-cell in the page.
+            headers: f.text("Column headers (one per line)"),
+            rows: f.text("Table rows (edit cells in the page)"),
             striped: { kind: "enum", label: "Striped rows", options: ["true", "false"], inlineEditable: false },
         },
     }

package/dist/blocks/testimonials.js

@@ -23,7 +23,7 @@ registerBlock("Testimonials", {
             items: {
                 label: "Testimonials",
                 itemFields: {
-                    icon: f.text("Icon (single emoji)"),
+                    icon: f.icon(),
                     quote: f.longtext("Quote"),
                     author: f.text("Author"),
                     role: f.text("Role / Company"),

package/dist/blocks/two-column.js

@@ -10,6 +10,7 @@ const twoColumnChild = z.object({
     text: z.string().optional(),
     label: z.string().optional(),
     href: z.string().optional(),
+    newTab: z.boolean().optional(),
     src: z.string().optional(),
     alt: z.string().optional(),
     poster: z.string().optional(),
@@ -21,11 +22,46 @@ const twoColumnItemFields = {
     type: { kind: "enum", label: "Component type", options: ["heading", "subheading", "paragraph", "list", "cta", "ctas", "image", "video"] },
     text: f.longtext("Text content"),
     label: f.text("Button label"),
-    href: f.url("Link URL"),
+    href: f.link("Link URL"),
+    newTab: f.newTab(),
     src: f.image("Media source", { aspectRatio: "portrait", width: 768, height: 1024 }),
     alt: f.imageAlt("Alt text"),
     poster: f.image("Video poster image", { aspectRatio: "landscape", width: 768, height: 512 }),
 };
+/**
+ * Which of those fields a child actually has, by its `type`.
+ *
+ * The union above is the merged fallback and it is a poor description of any
+ * single child: a heading has `text` and nothing else, and the panel was
+ * offering it a button label, a link, a media source, alt text and a video
+ * poster — nine controls for a one-field component, on every child of every
+ * TwoColumn. The renderer reads exactly one shape per `type` and ignores the
+ * rest, so a value typed into any of the others is stored and never drawn.
+ *
+ * `discriminator` + `itemFieldsByType` is the vocabulary the manifest already
+ * has for this; the derivation builds it automatically for a schema written as
+ * a `oneOf` of branches, and this block's schema is one permissive object with
+ * a `type` enum, so it has to be said out loud. The property panel narrows to
+ * the branch, the coverage check expects markers only for fields the child can
+ * draw, and `variant` — a styling hint the renderer never reads — stops being
+ * offered as content at all.
+ */
+const twoColumnItemFieldsByType = {
+    heading: { text: f.longtext("Heading text") },
+    subheading: { text: f.longtext("Subheading text") },
+    paragraph: { text: f.richtext("Body text") },
+    list: { text: f.longtext("Text content") },
+    cta: { label: f.text("Button label"), href: f.link("Link URL"), newTab: f.newTab() },
+    ctas: { label: f.text("Button label"), href: f.link("Link URL"), newTab: f.newTab() },
+    image: {
+        src: f.image("Image", { aspectRatio: "portrait", width: 768, height: 1024 }),
+        alt: f.imageAlt("Alt text"),
+    },
+    video: {
+        src: f.url("Video file URL"),
+        poster: f.image("Video poster image", { aspectRatio: "landscape", width: 768, height: 512 }),
+    },
+};
 registerBlock("TwoColumn", {
     schema: z.object({
         variant: z.enum(["default", "accent"]).default("default").catch("default"),
@@ -41,8 +77,18 @@ registerBlock("TwoColumn", {
             headingLevel: f.headingLevel(),
         },
         listFields: {
-            left: { label: "Left column items", itemFields: twoColumnItemFields },
-            right: { label: "Right column items", itemFields: twoColumnItemFields }
+            left: {
+                label: "Left column items",
+                itemFields: twoColumnItemFields,
+                discriminator: "type",
+                itemFieldsByType: twoColumnItemFieldsByType
+            },
+            right: {
+                label: "Right column items",
+                itemFields: twoColumnItemFields,
+                discriminator: "type",
+                itemFieldsByType: twoColumnItemFieldsByType
+            }
         }
     }
 });

package/dist/editable-coverage.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Which editable fields does a rendered preview actually offer?
+ *
+ * The overlay finds every job it does by walking `[data-editable-target]`, so a
+ * field the site never marked is a field with no inline editing, no hover pill
+ * and — for an image — no Change button. Nothing about that is visible: the
+ * property panel is built from this same manifest and never looks at the page,
+ * so an unmarked field still appears there, still edits, and still saves. The
+ * preview simply offers less than the panel does, quietly and forever.
+ *
+ * `missingEditableTargetsWarning` in preview-adapter catches the all-or-nothing
+ * case at runtime. This is the graded one, and it is the case that actually
+ * recurs: instrumentation is per-component work spread over a dozen files, so
+ * it gets done on one branch, not merged, and re-lost on the next. The symptom
+ * is always a single missing button, reported as a bug in the button.
+ *
+ * The manifest already knows every editable field of every block type, and the
+ * rendered page already carries the block type on each wrapper. Nothing further
+ * is needed to answer the question exactly — only somebody asking it, which is
+ * what this is for: an integrator asserts on it in their own test suite, and a
+ * branch that drops the markers goes red instead of going quiet.
+ */
+import { type BlockManifest } from "./block-manifest.ts";
+/** One block as it appears in a rendered page: its type, and the paths marked inside it. */
+export type MarkedBlock = {
+    blockType: string;
+    blockId?: string;
+    paths: string[];
+    /** Paths whose marker sits on a void element — see `VOID_ELEMENTS`. */
+    voidPaths?: string[];
+    /**
+     * The block's props, when the caller has them.
+     *
+     * Optional, and worth supplying. A field with no value draws nothing, and an
+     * element that was never drawn cannot carry a marker — so without this, a
+     * prop that happens to be empty on every page of the site is indistinguishable
+     * from one nobody instrumented, and gets reported as a gap that cannot be
+     * closed. PBA had two: `ctaSection.body` and `heroImage.subheading`, neither
+     * of which has content anywhere on the site.
+     */
+    props?: Record<string, unknown>;
+};
+export type BlockCoverageGap = {
+    blockType: string;
+    /** One block id that has the gap, so the report points somewhere. */
+    exampleBlockId?: string;
+    /** Top-level fields that draw something and carry no marker. */
+    missing: string[];
+    /** Item fields of a list that is present in the page but under-marked, as `cards[].title`. */
+    missingItemFields: string[];
+    /**
+     * Image fields marked on an element that cannot hold the button — an `<img>`
+     * most of the time. Present in the HTML, and as useless as absent.
+     */
+    markedOnVoidElement: string[];
+    /**
+     * Lists with no marked path at all. Weaker evidence than the other two: an
+     * empty list and an uninstrumented list look identical from outside, so this
+     * is reported separately rather than counted as a gap.
+     */
+    unmarkedLists: string[];
+};
+export type EditableCoverage = {
+    /** Fields that should carry a marker, summed over the block types on the page. */
+    expected: number;
+    /** How many of those do. */
+    marked: number;
+    gaps: BlockCoverageGap[];
+    /** Block types on the page that the manifest does not describe — not our business, but worth saying. */
+    unknownBlockTypes: string[];
+};
+/**
+ * Read the marked blocks out of a rendered page's HTML.
+ *
+ * A linear scan: each `data-editable-target` belongs to the most recently seen
+ * block. That is exact when block wrappers are siblings, which is the contract
+ * `getPreviewWrapperProps` describes — one wrapper per block, not nested. A
+ * site that nests blocks inside blocks will see inner fields attributed to the
+ * outer one; it would also confuse the overlay's own `closest()` walk, so it is
+ * out of contract on both ends rather than a limitation of this function.
+ */
+export declare function extractMarkedBlocks(html: string): MarkedBlock[];
+export declare function editableCoverage(manifest: BlockManifest, blocks: MarkedBlock[]): EditableCoverage;
+/** A report a person can read in a terminal. */
+export declare function formatEditableCoverage(report: EditableCoverage): string;

package/dist/editable-coverage.js

@@ -0,0 +1,342 @@
+/**
+ * Which editable fields does a rendered preview actually offer?
+ *
+ * The overlay finds every job it does by walking `[data-editable-target]`, so a
+ * field the site never marked is a field with no inline editing, no hover pill
+ * and — for an image — no Change button. Nothing about that is visible: the
+ * property panel is built from this same manifest and never looks at the page,
+ * so an unmarked field still appears there, still edits, and still saves. The
+ * preview simply offers less than the panel does, quietly and forever.
+ *
+ * `missingEditableTargetsWarning` in preview-adapter catches the all-or-nothing
+ * case at runtime. This is the graded one, and it is the case that actually
+ * recurs: instrumentation is per-component work spread over a dozen files, so
+ * it gets done on one branch, not merged, and re-lost on the next. The symptom
+ * is always a single missing button, reported as a bug in the button.
+ *
+ * The manifest already knows every editable field of every block type, and the
+ * rendered page already carries the block type on each wrapper. Nothing further
+ * is needed to answer the question exactly — only somebody asking it, which is
+ * what this is for: an integrator asserts on it in their own test suite, and a
+ * branch that drops the markers goes red instead of going quiet.
+ */
+import { resolveManifestFieldMeta } from "./block-manifest.js";
+/**
+ * The field kinds a marker is expected for: the ones something on the page
+ * *draws*.
+ *
+ * A renderer emits `data-editable-target` for an element, and only these three
+ * are elements. `enum`, `boolean`, `number`, `color` and `headingLevel` are
+ * settings — they change how something looks rather than being a thing on the
+ * page. `url`, `link` and `file` are attributes on an anchor whose *label* is
+ * the text field next to them, and `imageAlt` is an attribute on the image. A
+ * checker that demanded markers for those would report gaps that cannot be
+ * closed, which is the fastest way to get a checker ignored.
+ */
+const DRAWN_KINDS = new Set(["text", "richtext", "image"]);
+/**
+ * Does this field need an element marked for it?
+ *
+ * `inlineEditable: false` on a text field is the site saying the string is not
+ * something anybody edits on the page — an anchor id, a slug fragment, a
+ * machine value that happens to be typed as text. Honouring it is what keeps
+ * this checker worth reading: PBA declares seven of those, and counting them as
+ * gaps would have made the first report 16% instead of 19% and every one of the
+ * extra findings unfixable.
+ *
+ * It is not consulted for images. There, "inline editable" means typing into
+ * it, which nobody does to a photo; the marker is what carries the Change
+ * button, and the panel offering one is the site saying the image is editable.
+ */
+function needsMarker(meta) {
+    if (!DRAWN_KINDS.has(meta.kind))
+        return false;
+    if (meta.kind === "image")
+        return true;
+    return meta.inlineEditable !== false;
+}
+/**
+ * Elements that cannot contain anything.
+ *
+ * The overlay mounts its image Change button by *appending it into* the marked
+ * element, so a marker on an `<img>` is inert — the attribute is in the HTML,
+ * the editor finds the field, and no button can ever appear. It looks
+ * instrumented from every angle except the one that matters, and this package's
+ * own Card and Hero renderers both did it on their full-bleed variants.
+ */
+const VOID_ELEMENTS = new Set([
+    "area", "base", "br", "col", "embed", "hr", "img", "input",
+    "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 BLOCK_ID_RE = /\bdata-block-id="([^"]*)"/;
+const BLOCK_TYPE_RE = /\bdata-block-type="([^"]*)"/;
+const TARGET_RE = /\bdata-editable-target="([^"]*)"/;
+/**
+ * Read the marked blocks out of a rendered page's HTML.
+ *
+ * A linear scan: each `data-editable-target` belongs to the most recently seen
+ * block. That is exact when block wrappers are siblings, which is the contract
+ * `getPreviewWrapperProps` describes — one wrapper per block, not nested. A
+ * site that nests blocks inside blocks will see inner fields attributed to the
+ * outer one; it would also confuse the overlay's own `closest()` walk, so it is
+ * out of contract on both ends rather than a limitation of this function.
+ */
+export function extractMarkedBlocks(html) {
+    const blocks = [];
+    let current = null;
+    for (const match of html.matchAll(TAG_RE)) {
+        const tag = match[1].toLowerCase();
+        const attrs = match[2] ?? "";
+        const blockId = BLOCK_ID_RE.exec(attrs)?.[1];
+        const blockType = BLOCK_TYPE_RE.exec(attrs)?.[1];
+        if (blockId !== undefined || blockType !== undefined) {
+            current = {
+                blockType: blockType ?? "",
+                ...(blockId !== undefined ? { blockId } : {}),
+                paths: [],
+            };
+            blocks.push(current);
+        }
+        const target = TARGET_RE.exec(attrs)?.[1];
+        if (target !== undefined && current) {
+            current.paths.push(target);
+            if (VOID_ELEMENTS.has(tag))
+                (current.voidPaths ??= []).push(target);
+        }
+    }
+    return blocks;
+}
+/** Does this prop hold anything a renderer would draw? */
+function hasContent(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === "string")
+        return value.trim() !== "";
+    if (Array.isArray(value))
+        return value.length > 0;
+    return true;
+}
+/** `cards[2].title` → `cards[].title`; anything else unchanged. */
+function generalizeIndex(path) {
+    return path.replace(/\[\d+\]/g, "[]");
+}
+/**
+ * The item fields a list is expected to have markers for, given what is in it.
+ *
+ * Two refinements of "every field the manifest declares for this list", both
+ * for the same reason the top-level fields already consult `props`: an element
+ * that was never drawn cannot carry a marker, and reporting it is a finding
+ * nobody can act on.
+ *
+ * 1. A field no item has a value for is not expected. `imageUrl` is optional on
+ *    every card block here, and a page whose cards are all text would otherwise
+ *    report a missing image marker on every one of them.
+ *
+ * 2. When the list is polymorphic — `discriminator` plus `itemFieldsByType`,
+ *    the shape a `oneOf` schema derives and a permissive one has to declare —
+ *    each item is measured against *its own* branch. TwoColumn is the case: a
+ *    `type: "image"` child has `src` and `alt` and no `label`, and asking it for
+ *    a button label is asking the renderer to draw a field the item does not
+ *    have.
+ *
+ * With no props in hand there is nothing to narrow by, so every declared field
+ * is expected — the behaviour before this existed.
+ */
+function expectedItemFields(listMeta, items) {
+    /*
+     * The discriminator is never content. It decides which shape the item is —
+     * `derivePolymorphicListField` deletes it from every branch it builds for
+     * exactly that reason — and a list whose metadata was declared rather than
+     * derived has nothing doing the same, so a `type` typed as a plain string
+     * arrives here looking like an ordinary text field nobody marked.
+     */
+    const isContent = ([key, meta]) => key !== listMeta.discriminator && needsMarker(meta);
+    const declared = Object.entries(listMeta.itemFields ?? {}).filter(isContent);
+    if (!items)
+        return declared;
+    const expected = new Map();
+    for (const raw of items) {
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        const item = raw;
+        const branchKey = listMeta.discriminator ? String(item[listMeta.discriminator] ?? "") : "";
+        const fields = listMeta.itemFieldsByType?.[branchKey] ?? listMeta.itemFields ?? {};
+        for (const entry of Object.entries(fields)) {
+            if (!isContent(entry))
+                continue;
+            if (!hasContent(item[entry[0]]))
+                continue;
+            expected.set(entry[0], entry[1]);
+        }
+    }
+    return [...expected];
+}
+export function editableCoverage(manifest, blocks) {
+    const definitions = new Map(manifest.blocks.map((block) => [block.type, block]));
+    // Aggregate by type: a missing marker is a property of the component, not of
+    // the one instance that happened to render first.
+    const pathsByType = new Map();
+    const exampleIdByType = new Map();
+    const unknownBlockTypes = new Set();
+    /*
+     * Props that at least one instance of a type actually had. Only consulted
+     * when some instance supplied props at all — a caller that passes none gets
+     * the old behaviour, where every declared field is expected.
+     */
+    const filledByType = new Map();
+    const sawPropsForType = new Set();
+    const voidByType = new Map();
+    /** Every list item seen for a type, by list key — what `expectedItemFields` narrows by. */
+    const listItemsByType = new Map();
+    for (const block of blocks) {
+        if (!block.blockType)
+            continue;
+        if (!definitions.has(block.blockType)) {
+            unknownBlockTypes.add(block.blockType);
+            continue;
+        }
+        let paths = pathsByType.get(block.blockType);
+        if (!paths) {
+            paths = new Set();
+            pathsByType.set(block.blockType, paths);
+            if (block.blockId)
+                exampleIdByType.set(block.blockType, block.blockId);
+        }
+        for (const path of block.paths)
+            paths.add(generalizeIndex(path));
+        if (block.voidPaths?.length) {
+            let voids = voidByType.get(block.blockType);
+            if (!voids) {
+                voids = new Set();
+                voidByType.set(block.blockType, voids);
+            }
+            for (const path of block.voidPaths)
+                voids.add(generalizeIndex(path));
+        }
+        if (!block.props)
+            continue;
+        sawPropsForType.add(block.blockType);
+        let filled = filledByType.get(block.blockType);
+        if (!filled) {
+            filled = new Set();
+            filledByType.set(block.blockType, filled);
+        }
+        let lists = listItemsByType.get(block.blockType);
+        if (!lists) {
+            lists = new Map();
+            listItemsByType.set(block.blockType, lists);
+        }
+        for (const [key, value] of Object.entries(block.props)) {
+            if (hasContent(value))
+                filled.add(key);
+            if (Array.isArray(value)) {
+                const seen = lists.get(key);
+                if (seen)
+                    seen.push(...value);
+                else
+                    lists.set(key, [...value]);
+            }
+        }
+    }
+    let expected = 0;
+    let marked = 0;
+    const gaps = [];
+    for (const [blockType, paths] of pathsByType) {
+        const definition = definitions.get(blockType);
+        const { fields, listFields } = resolveManifestFieldMeta(definition);
+        const missing = [];
+        const missingItemFields = [];
+        const unmarkedLists = [];
+        const voids = voidByType.get(blockType) ?? new Set();
+        const markedOnVoidElement = [];
+        const knowsContent = sawPropsForType.has(blockType);
+        const filled = filledByType.get(blockType) ?? new Set();
+        for (const [key, meta] of Object.entries(fields)) {
+            if (!needsMarker(meta))
+                continue;
+            // Nothing drew it, so nothing could have marked it.
+            if (knowsContent && !filled.has(key))
+                continue;
+            expected += 1;
+            if (!paths.has(key)) {
+                missing.push(key);
+            }
+            else if (meta.kind === "image" && voids.has(key)) {
+                // Marked, found by the editor, and unable to hold the button.
+                markedOnVoidElement.push(key);
+            }
+            else {
+                marked += 1;
+            }
+        }
+        for (const [listKey, listMeta] of Object.entries(listFields)) {
+            const listPresent = [...paths].some((path) => path.startsWith(`${listKey}[]`));
+            const drawnItemFields = expectedItemFields(listMeta, knowsContent ? (listItemsByType.get(blockType)?.get(listKey) ?? []) : undefined);
+            if (drawnItemFields.length === 0)
+                continue;
+            // An empty list on every page is not an instrumentation question either,
+            // and with props in hand we can say so instead of guessing.
+            if (knowsContent && !filled.has(listKey))
+                continue;
+            if (!listPresent) {
+                // Could be an empty list on this page. Not counted against coverage.
+                unmarkedLists.push(listKey);
+                continue;
+            }
+            for (const [itemKey, itemMeta] of drawnItemFields) {
+                const path = `${listKey}[].${itemKey}`;
+                expected += 1;
+                if (!paths.has(path)) {
+                    missingItemFields.push(path);
+                }
+                else if (itemMeta.kind === "image" && voids.has(path)) {
+                    markedOnVoidElement.push(path);
+                }
+                else {
+                    marked += 1;
+                }
+            }
+        }
+        if (missing.length > 0 ||
+            missingItemFields.length > 0 ||
+            unmarkedLists.length > 0 ||
+            markedOnVoidElement.length > 0) {
+            const exampleBlockId = exampleIdByType.get(blockType);
+            gaps.push({
+                blockType,
+                ...(exampleBlockId ? { exampleBlockId } : {}),
+                missing,
+                missingItemFields,
+                unmarkedLists,
+                markedOnVoidElement,
+            });
+        }
+    }
+    return { expected, marked, gaps, unknownBlockTypes: [...unknownBlockTypes] };
+}
+/** A report a person can read in a terminal. */
+export function formatEditableCoverage(report) {
+    const lines = [];
+    const pct = report.expected === 0 ? 100 : Math.round((report.marked / report.expected) * 100);
+    lines.push(`editable fields marked: ${report.marked}/${report.expected} (${pct}%)`);
+    for (const gap of report.gaps) {
+        const where = gap.exampleBlockId ? ` (e.g. ${gap.exampleBlockId})` : "";
+        lines.push(`  ${gap.blockType}${where}`);
+        for (const key of gap.missing)
+            lines.push(`    unmarked  ${key}`);
+        for (const key of gap.missingItemFields)
+            lines.push(`    unmarked  ${key}`);
+        for (const key of gap.markedOnVoidElement) {
+            lines.push(`    marked on a void element (no button can mount)  ${key}`);
+        }
+        for (const key of gap.unmarkedLists) {
+            lines.push(`    no marker for any item of ${key}[] — empty on this page, or not instrumented`);
+        }
+    }
+    if (report.unknownBlockTypes.length > 0) {
+        lines.push(`  not in the manifest, skipped: ${report.unknownBlockTypes.join(", ")}`);
+    }
+    return lines.join("\n");
+}

package/dist/editable-path.d.ts

@@ -7,6 +7,17 @@
 export declare function isImagePath(editablePath: string): boolean;
 /** Derives the companion alt-text path from an image path. Returns the path unchanged if it is not an image path. */
 export declare function toAltPath(editablePath: string): string;
+/** Returns true if the editable path points to an image's alt text. */
+export declare function isAltPath(editablePath: string): boolean;
+/**
+ * Derives the image path an alt-text path belongs to — the inverse of
+ * `toAltPath`. Returns the path unchanged if it is not an alt path.
+ *
+ * Alt text has no node of its own in a rendered page: it is an attribute on the
+ * image. Anything that wants to *show* somebody where an alt-text problem is
+ * has to point at the image instead, and this is the only step between the two.
+ */
+export declare function toImagePath(editablePath: string): string;
 /**
  * Return a copy of `props` with `value` written at `editablePath`, using
  * copy-on-write so the input (and every untouched subtree) is shared by reference.

package/dist/editable-path.js

@@ -13,6 +13,23 @@ export function isImagePath(editablePath) {
 export function toAltPath(editablePath) {
     return editablePath.replace(/imageUrl$/i, "imageAlt").replace(/\.src$/i, ".alt");
 }
+/** Matches editable paths that point to an image's alt text. */
+const ALT_PATH_RE = /(imageAlt|\.alt)$/i;
+/** Returns true if the editable path points to an image's alt text. */
+export function isAltPath(editablePath) {
+    return ALT_PATH_RE.test(editablePath);
+}
+/**
+ * Derives the image path an alt-text path belongs to — the inverse of
+ * `toAltPath`. Returns the path unchanged if it is not an alt path.
+ *
+ * Alt text has no node of its own in a rendered page: it is an attribute on the
+ * image. Anything that wants to *show* somebody where an alt-text problem is
+ * has to point at the image instead, and this is the only step between the two.
+ */
+export function toImagePath(editablePath) {
+    return editablePath.replace(/imageAlt$/i, "imageUrl").replace(/\.alt$/i, ".src");
+}
 /**
  * Parse an editable-target path into a flat list of access steps.
  *