@avocadostudio-ai/shared 0.3.3 → 0.4.0

package/dist/block-manifest.d.ts

@@ -1,20 +1,11 @@
 import { z } from "zod";
 import type { FieldMeta, ListFieldMeta } from "./blocks/_registry.ts";
 export declare const jsonSchemaLikeSchema: z.ZodType<Record<string, unknown>>;
-/**
- * Field metadata a site may declare alongside the JSON schema.
- *
- * JSON Schema describes what a value *is*; this describes how a person edits
- * it, and the two are not the same question. A one-word headline and a six
- * sentence body are both `{"type":"string"}`, so a manifest carrying only the
- * schema gives them the same one-line input — which is exactly what happened to
- * every integration with a real prose field. `kind` and `multiline` have no
- * JSON Schema spelling, so they have to travel beside it.
- */
 export declare const fieldMetaSchema: z.ZodObject<{
     kind: z.ZodEnum<{
         number: "number";
         boolean: "boolean";
+        file: "file";
         enum: "enum";
         text: "text";
         richtext: "richtext";
@@ -56,6 +47,7 @@ export declare const listFieldMetaSchema: z.ZodObject<{
         kind: z.ZodEnum<{
             number: "number";
             boolean: "boolean";
+            file: "file";
             enum: "enum";
             text: "text";
             richtext: "richtext";
@@ -96,6 +88,7 @@ export declare const listFieldMetaSchema: z.ZodObject<{
         kind: z.ZodEnum<{
             number: "number";
             boolean: "boolean";
+            file: "file";
             enum: "enum";
             text: "text";
             richtext: "richtext";
@@ -142,6 +135,7 @@ export declare const blockDefinitionSchema: z.ZodObject<{
         kind: z.ZodEnum<{
             number: "number";
             boolean: "boolean";
+            file: "file";
             enum: "enum";
             text: "text";
             richtext: "richtext";
@@ -183,6 +177,7 @@ export declare const blockDefinitionSchema: z.ZodObject<{
             kind: z.ZodEnum<{
                 number: "number";
                 boolean: "boolean";
+                file: "file";
                 enum: "enum";
                 text: "text";
                 richtext: "richtext";
@@ -223,6 +218,7 @@ export declare const blockDefinitionSchema: z.ZodObject<{
             kind: z.ZodEnum<{
                 number: "number";
                 boolean: "boolean";
+                file: "file";
                 enum: "enum";
                 text: "text";
                 richtext: "richtext";
@@ -275,6 +271,7 @@ export declare const blockManifestSchema: z.ZodObject<{
             kind: z.ZodEnum<{
                 number: "number";
                 boolean: "boolean";
+                file: "file";
                 enum: "enum";
                 text: "text";
                 richtext: "richtext";
@@ -316,6 +313,7 @@ export declare const blockManifestSchema: z.ZodObject<{
                 kind: z.ZodEnum<{
                     number: "number";
                     boolean: "boolean";
+                    file: "file";
                     enum: "enum";
                     text: "text";
                     richtext: "richtext";
@@ -356,6 +354,7 @@ export declare const blockManifestSchema: z.ZodObject<{
                 kind: z.ZodEnum<{
                     number: "number";
                     boolean: "boolean";
+                    file: "file";
                     enum: "enum";
                     text: "text";
                     richtext: "richtext";

package/dist/block-manifest.js

@@ -23,8 +23,25 @@ export const jsonSchemaLikeSchema = z.lazy(() => z.object({
  * every integration with a real prose field. `kind` and `multiline` have no
  * JSON Schema spelling, so they have to travel beside it.
  */
+/*
+ * The same list as `FieldKind`, and pinned to it.
+ *
+ * A Zod enum cannot be derived from a union type, so this is the second place
+ * the kinds are written — and it drifted the moment a kind was added: `file`
+ * went into `FieldKind`, every derivation started emitting it, and this schema
+ * went on rejecting it, which surfaced as a type error three packages away in
+ * the MCP server rather than as anything about field kinds. The
+ * `satisfies`-flavoured assignment below makes the compiler check the two lists
+ * against each other here, where the mismatch is.
+ */
+const FIELD_KINDS = [
+    "text", "richtext", "url", "link", "file", "image", "imageAlt",
+    "enum", "color", "number", "boolean", "headingLevel"
+];
+const _everyKindListed = true;
+void _everyKindListed;
 export const fieldMetaSchema = z.object({
-    kind: z.enum(["text", "richtext", "url", "link", "image", "imageAlt", "enum", "color", "number", "boolean", "headingLevel"]),
+    kind: z.enum(FIELD_KINDS),
     label: z.string().optional(),
     inlineEditable: z.boolean().optional(),
     options: z.array(z.string()).optional(),
@@ -185,6 +202,54 @@ export function validateByJsonSchemaLike(schema, value) {
 const IMAGE_KEY_RE = /(?:image|img)(?:Url|Src)?$|^(?:src|imageUrl|logoUrl|heroImage)$/i;
 const IMAGE_ALT_KEY_RE = /(?:Alt)$/;
 const LINK_KEY_RE = /(?:href|link)$/i;
+/*
+ * Prop names that hold a document rather than a route.
+ *
+ * Deliberately narrow. `download`, `pdf`, `file`, `doc`, `attachment`,
+ * `brochure`, `datasheet` and `menu` are the words sites use, each optionally
+ * followed by Url/Href/Link/Path — so `menuPdf`, `downloadUrl` and
+ * `brochureHref` all land here, and `menuLabel` does not. A name this misses
+ * simply stays a `link`, which is where it already was; the cost of guessing
+ * wrong in the other direction is a page picker offered for a PDF.
+ */
+const FILE_KEY_RE = /(?:^|[a-z])(?:download|pdf|file|doc|document|attachment|brochure|datasheet|menu)(?:Url|Href|Link|Path)?$/i;
+/*
+ * A `contentMediaType` that means "this is a file to download".
+ *
+ * Not simply "anything that is not an image": `text/html`, `text/plain` and
+ * `text/markdown` are prose a block renders inline, and treating them as
+ * documents would put a file picker on a body field. `application/json` is
+ * excluded for the same reason — a config blob is data the block reads, not
+ * something a visitor downloads. What is left is `application/*` (pdf, msword,
+ * vnd.*, zip) plus the two text types that really are files.
+ */
+const FILE_MEDIA_TYPE_RE = /^application\/(?!json\b)|^text\/(?:csv|calendar)\b/i;
+/**
+ * A prop the CMS owns, which no editor may offer as a control.
+ *
+ * A leading underscore is the near-universal marker for a document's own
+ * bookkeeping — Sanity's `_key`, `_type`, `_id`, `_ref`, `_rev`; GraphQL's
+ * `__typename`. These reach a block's schema legitimately: a site that projects
+ * CMS array members has to carry `_key` through, because `_key` is the *address*
+ * a field-level publish patches by (`pageBuilder[_key=="home-hero"].heading.de`).
+ * Declaring it keeps the ops engine from stripping it off an edited item.
+ *
+ * But "the block can store it" was being read as "a person may type it". The
+ * property panel derives its controls from the schema, so `_key` rendered as an
+ * empty text box — empty because the projection hands the editor its own `id`,
+ * not the CMS key — labelled " key", sitting directly under a CTA's Label. That
+ * is not merely a stray control: the value a user typed into it would become the
+ * item's `_key`, which is the thing the publish diff addresses the array member
+ * by. Editing it re-points or orphans the patch, and the same derivation feeds
+ * the planner's block contracts, so the model was being shown `_key` as a prop
+ * it could set.
+ *
+ * Underscore-prefixed props are therefore stored, projected and published as
+ * before, and never editable by anyone.
+ */
+function isInternalPropKey(key) {
+    return key.startsWith("_");
+}
 function labelFromKey(key) {
     // ctaText → "CTA text", imageUrl → "Image", logoAlt → "Logo alt",
     // background_image → "Background image", video_url → "Video", src → "Src"
@@ -225,6 +290,24 @@ function inferFieldKind(key, schema) {
         return "imageAlt";
     if (IMAGE_KEY_RE.test(key))
         return "image";
+    /*
+     * A document prop, named as one. `menuPdf`, `brochureFile`, `datasheetDoc`,
+     * `downloadUrl` — all of them hold a path to a file rather than a route, and
+     * inferring them as `link` puts them in front of the page picker and the
+     * dead-route warning, which are both the wrong question. Checked before the
+     * link pattern precisely because `downloadUrl` and `fileHref` match both.
+     */
+    if (FILE_KEY_RE.test(key))
+        return "file";
+    /*
+     * A schema can also say so outright, and a `contentMediaType` of anything but
+     * an image means a document — the same standard vocabulary the markdown case
+     * above uses, so an integrator needs no proprietary annotation to get the
+     * right control.
+     */
+    if (typeof schema.contentMediaType === "string" && FILE_MEDIA_TYPE_RE.test(schema.contentMediaType)) {
+        return "file";
+    }
     /*
      * A custom block's `ctaHref` is a link, and inferring it as plain text gave
      * an integrator's editors a bare box where the built-in blocks get a page
@@ -235,12 +318,31 @@ function inferFieldKind(key, schema) {
         return "link";
     return "text";
 }
+/**
+ * A list item's `id` is identity, not content.
+ *
+ * The same argument as `_key` above, one convention over: every one of this
+ * package's own list blocks carries an optional `id` on each item, used as the
+ * React key and as the handle an operation addresses the item by. Derived from
+ * the schema it looks like any other optional string, so the panel drew a text
+ * box for it and the planner was shown it as a prop it could set — and a value
+ * typed there re-points or orphans the very patch that would save it.
+ *
+ * Scoped to list items deliberately. A top-level `id` prop on a block is a
+ * perfectly ordinary content field (an anchor, a slug, an embed's video id) and
+ * is left alone.
+ */
+function isItemIdentityKey(key) {
+    return key === "id";
+}
 function deriveItemFields(itemSchema) {
     const fields = {};
     const props = isObject(itemSchema.properties) ? itemSchema.properties : {};
     for (const [key, propSchema] of Object.entries(props)) {
         if (!isObject(propSchema))
             continue;
+        if (isInternalPropKey(key) || 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.
         const t = typeof propSchema.type === "string" ? propSchema.type : undefined;
@@ -334,6 +436,8 @@ export function deriveFieldMetaFromSchema(propsSchema) {
     for (const [key, propSchema] of Object.entries(props)) {
         if (!isObject(propSchema))
             continue;
+        if (isInternalPropKey(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.

package/dist/blocks/_helpers.d.ts

@@ -14,6 +14,18 @@ export declare const f: {
      */
     readonly newTab: (label?: string) => FieldMeta;
     readonly image: (label?: string, imageSpec?: ImageSpec) => FieldMeta;
+    /**
+     * A single emoji or symbol glyph, or the URL of a small image.
+     *
+     * Text in the panel, and deliberately *not* editable on the page. Whatever a
+     * person types into an icon goes through `renderBlockIcon`, which draws only a
+     * glyph or an image and renders **nothing** for anything else — so an inline
+     * edit that typed a word ("rocket", the name the planner reaches for) would
+     * make the icon silently disappear with the value stored and invisible. The
+     * panel's labelled box is the affordance that fits a value from a constrained
+     * vocabulary; a cursor blinking inside the emoji is not.
+     */
+    readonly icon: (label?: string) => FieldMeta;
     readonly imageAlt: (label?: string) => FieldMeta;
     readonly headingLevel: () => FieldMeta;
 };

package/dist/blocks/_helpers.js

@@ -13,6 +13,18 @@ export const f = {
      */
     newTab: (label = "Open in new tab") => ({ kind: "boolean", label, inlineEditable: false }),
     image: (label, imageSpec) => ({ kind: "image", label, inlineEditable: false, ...(imageSpec ? { imageSpec } : {}) }),
+    /**
+     * A single emoji or symbol glyph, or the URL of a small image.
+     *
+     * Text in the panel, and deliberately *not* editable on the page. Whatever a
+     * person types into an icon goes through `renderBlockIcon`, which draws only a
+     * glyph or an image and renders **nothing** for anything else — so an inline
+     * edit that typed a word ("rocket", the name the planner reaches for) would
+     * make the icon silently disappear with the value stored and invisible. The
+     * panel's labelled box is the affordance that fits a value from a constrained
+     * vocabulary; a cursor blinking inside the emoji is not.
+     */
+    icon: (label = "Icon (single emoji)") => ({ kind: "text", label, inlineEditable: false }),
     imageAlt: (label) => ({ kind: "imageAlt", label }),
     headingLevel: () => ({ kind: "headingLevel", label: "Heading type", inlineEditable: false }),
 };

package/dist/blocks/_registry.d.ts

@@ -10,8 +10,16 @@ export declare function isImagePlaceholder(url: string | undefined | null): bool
  * `url` is a *resource address* — an embed's iframe src, a video file, an OG
  * image — which is never an internal page, and where offering a list of pages
  * would be noise.
+ *
+ * `file` is a *document*: a menu PDF, a price list, a consent form. It is a
+ * third thing and not a flavour of either, because the question you ask of it
+ * is different. A `link` is checked against the site's pages; a `file` must not
+ * be, or every document on the site reports as a dead link. A `url` is checked
+ * 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.
  */
-export type FieldKind = "text" | "richtext" | "url" | "link" | "image" | "imageAlt" | "enum" | "color" | "number" | "boolean" | "headingLevel";
+export type FieldKind = "text" | "richtext" | "url" | "link" | "file" | "image" | "imageAlt" | "enum" | "color" | "number" | "boolean" | "headingLevel";
 /** Recommended image dimensions for an image field. */
 export type ImageSpec = {
     aspectRatio: "landscape" | "square" | "portrait";
@@ -113,6 +121,32 @@ export declare function registerBlock(type: string, config: BlockRegistration):
 export declare function getBlockMeta(type: string): BlockMeta | undefined;
 /** Get all registered block metadata. */
 export declare function getAllBlockMeta(): Readonly<Record<string, BlockMeta>>;
+/**
+ * Does this block type declare this prop?
+ *
+ * The only honest answer to "is `heading` a real prop" is the one the block's
+ * own schema gives, and it is the question two very different callers need: the
+ * plan normalizer, deciding whether a prop name the model emitted needs
+ * repairing, and the planner prompt, deciding whether a prop-name correction is
+ * even true of this site's catalogue. Both used to answer it by comparing the
+ * block type against a literal from Avocado's own catalogue, which is a fact
+ * about our names rather than about the site's schema — so a site that brings
+ * its own blocks got a confident wrong answer. Asking here means they cannot
+ * drift apart again.
+ *
+ * Manifest-registered blocks may carry a schema richer than their derived meta,
+ * so the schema gets the second look rather than the first refusal. An
+ * unregistered type answers `false`, which callers must read as "no evidence",
+ * not as "no".
+ */
+export declare function blockAcceptsProp(blockType: string, prop: string): boolean;
+/**
+ * Does this block type's list `listKey` declare an item field named `itemKey`?
+ * The list-shaped counterpart of `blockAcceptsProp`, with the same contract: a
+ * block with no declared list metadata answers `false` for every key, meaning
+ * "no evidence".
+ */
+export declare function blockListItemAcceptsKey(blockType: string, listKey: string, itemKey: string): boolean;
 /** Get the set of prop keys that are image fields for a block type. */
 export declare function getImageFields(blockType: string): Set<string>;
 /** Get list props that contain image fields: Map<listKey, Set<imageFieldKey>>. */

package/dist/blocks/_registry.js

@@ -141,6 +141,45 @@ export function getBlockMeta(type) {
 export function getAllBlockMeta() {
     return _blockMeta;
 }
+/**
+ * Does this block type declare this prop?
+ *
+ * The only honest answer to "is `heading` a real prop" is the one the block's
+ * own schema gives, and it is the question two very different callers need: the
+ * plan normalizer, deciding whether a prop name the model emitted needs
+ * repairing, and the planner prompt, deciding whether a prop-name correction is
+ * even true of this site's catalogue. Both used to answer it by comparing the
+ * block type against a literal from Avocado's own catalogue, which is a fact
+ * about our names rather than about the site's schema — so a site that brings
+ * its own blocks got a confident wrong answer. Asking here means they cannot
+ * drift apart again.
+ *
+ * Manifest-registered blocks may carry a schema richer than their derived meta,
+ * so the schema gets the second look rather than the first refusal. An
+ * unregistered type answers `false`, which callers must read as "no evidence",
+ * not as "no".
+ */
+export function blockAcceptsProp(blockType, prop) {
+    if (!blockType || !prop)
+        return false;
+    const meta = _blockMeta[blockType];
+    if (meta?.fields && prop in meta.fields)
+        return true;
+    const shape = _blockSchemas[blockType]?.shape;
+    return Boolean(shape && prop in shape);
+}
+/**
+ * Does this block type's list `listKey` declare an item field named `itemKey`?
+ * The list-shaped counterpart of `blockAcceptsProp`, with the same contract: a
+ * block with no declared list metadata answers `false` for every key, meaning
+ * "no evidence".
+ */
+export function blockListItemAcceptsKey(blockType, listKey, itemKey) {
+    if (!blockType || !listKey || !itemKey)
+        return false;
+    const itemFields = _blockMeta[blockType]?.listFields?.[listKey]?.itemFields;
+    return Boolean(itemFields && itemKey in itemFields);
+}
 /** Cache for getImageFields results. */
 const _imageFieldsCache = new Map();
 /** Get the set of prop keys that are image fields for a block type. */

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/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/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

@@ -28,6 +28,40 @@ const twoColumnItemFields = {
     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"),
@@ -43,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;