@avocadostudio-ai/shared 0.3.3 → 0.4.0

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/index.d.ts

@@ -2,11 +2,13 @@ export { EDITOR_PROTOCOL_VERSION } from "./protocol.ts";
 export { getConfiguredDraftSecret, getSafeInternalRedirectPath, validateDraftSecret, type DraftSecretValidationResult } from "./draft-mode.ts";
 export type { FieldDiffKind, FieldDiff, BlockDiffStatus, BlockDiff, PageDiffStatus, PageDiff, PublishDiff, SiteConfigFieldDiff, SiteConfigDiff, } from "./publish-diff.ts";
 export { isImagePath, toAltPath, isAltPath, toImagePath, setPropAtPath } from "./editable-path.ts";
-export { parseLink, resolveLink, normalizeLinkPath, isKnownRoute, internalPathForUrl, rankLinkTargets, scoreLinkCandidate, suggestLinkTarget, newTabKeyFor, linkAttrs, type LinkKind, type ParsedLink, type ResolvedLink, type LinkPageOption, } from "./links.ts";
+export { extractMarkedBlocks, editableCoverage, formatEditableCoverage } from "./editable-coverage.ts";
+export type { MarkedBlock, BlockCoverageGap, EditableCoverage } from "./editable-coverage.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, 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, 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 { 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";

package/dist/index.js

@@ -1,7 +1,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 { parseLink, resolveLink, normalizeLinkPath, isKnownRoute, internalPathForUrl, rankLinkTargets, scoreLinkCandidate, suggestLinkTarget, newTabKeyFor, linkAttrs, } from "./links.js";
+export { extractMarkedBlocks, editableCoverage, formatEditableCoverage } from "./editable-coverage.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
  * parser and every CMS converter and has no dependencies of its own. It is
@@ -34,7 +35,7 @@ export {
 // Constants & helpers
 IMAGE_PLACEHOLDER, isImagePlaceholder, 
 // Registry functions
-registerBlock, resetListFieldWarnings, getBlockMeta, getAllBlockMeta, getImageFields, getListImageFields, getMediaFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, 
+registerBlock, resetListFieldWarnings, getBlockMeta, getAllBlockMeta, blockAcceptsProp, blockListItemAcceptsKey, getImageFields, getListImageFields, getMediaFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, 
 // Backwards-compatible exports
 blockSchemas, allowedBlockTypes, 
 // The catalogue a site actually renders — see `declareBlockCatalogue`

package/dist/links.d.ts

@@ -17,7 +17,14 @@
  * never decides what the editor may type.
  */
 /** How a link string addresses its target. */
-export type LinkKind = "empty" | "page" | "external" | "email" | "phone" | "anchor";
+export type LinkKind = "empty" | "page" | "file" | "external" | "email" | "phone" | "anchor";
+/** Does this route-shaped path name a document rather than a page? */
+export declare function isFilePath(path: string): boolean;
+/**
+ * The file extensions this module recognises, for a caller that has to describe
+ * them — an upload control's `accept`, a picker's filter, a docs page.
+ */
+export declare function knownFileExtensions(): string[];
 /** A link string, classified. */
 export type ParsedLink = {
     kind: LinkKind;
@@ -59,19 +66,49 @@ export declare function normalizeLinkPath(path: string): string;
  * disagree about what "dead" means.
  */
 export declare function isKnownRoute(path: string, knownSlugs: Iterable<string>): boolean;
+/**
+ * A document the site can link to, as the editor needs to know it.
+ *
+ * `path` is what goes in the link. Everything else is for showing it to a
+ * person, and every field but `path` is optional because a site that answers
+ * this question from a directory listing has only the path.
+ */
+export type LinkFileOption = {
+    /** The URL to link to — `/downloads/menu-de.pdf`. */
+    path: string;
+    /** What to call it in a picker. Defaults to the filename. */
+    name?: string;
+    /** MIME type, when the store knows it. */
+    contentType?: string;
+    /** Bytes, when the store knows it — a picker shows it, nothing decides on it. */
+    size?: number;
+};
 /** A parsed link plus what the site knows about its target. */
 export type ResolvedLink = ParsedLink & {
     /** The matching page, when `kind` is `page` and the route is known. */
     page?: LinkPageOption;
-    /** True for a `page` link whose route matches nothing the site knows about. */
+    /** The matching document, when `kind` is `file` and the asset list has it. */
+    file?: LinkFileOption;
+    /**
+     * True for a link whose target matches nothing the site knows about.
+     *
+     * For a `page` this is decided from the slug list, which is always present.
+     * For a `file` it is decided from the asset list, which is *not* — a site
+     * that cannot enumerate its documents passes none, and then `missing` stays
+     * undefined rather than becoming `true`. "We did not check" and "it is not
+     * there" have to stay distinguishable, or every site without an asset store
+     * would report all of its own documents as broken.
+     */
     missing?: boolean;
 };
 /**
- * Classify a link *and* look up its page. Pages may be keyed by `slug` or by
+ * Classify a link *and* look up its target. Pages may be keyed by `slug` or by
  * `path` (they differ on locale-prefixed sites — see
  * `docs/ideas/page-identity-punch-list.md`), so both are matched.
+ *
+ * `files` is optional and its absence is meaningful — see `missing` above.
  */
-export declare function resolveLink(value: unknown, pages?: readonly LinkPageOption[]): ResolvedLink;
+export declare function resolveLink(value: unknown, pages?: readonly LinkPageOption[], files?: readonly LinkFileOption[]): ResolvedLink;
 /**
  * How well a page answers what was typed, from 0 (nothing in common) to 1.
  *
@@ -84,8 +121,72 @@ export declare function resolveLink(value: unknown, pages?: readonly LinkPageOpt
  * (see `tokenWeights`); without it every word counts the same.
  */
 export declare function scoreLinkCandidate(query: string, page: LinkPageOption, corpus?: readonly LinkPageOption[]): number;
-/** Known pages ranked by how well they answer `query`, best first. */
+/**
+ * Known pages ranked by how well they answer `query`, best first.
+ *
+ * Held to the same floor as `suggestLinkTarget`, which it did not used to be:
+ * anything sharing a single token came back, so on a tri-lingual site every
+ * `/fr/*` page answered every French-flavoured query. Typing a document path
+ * into the link picker listed `/fr/`, `/fr/faq/` and `/fr/evenements/` — six
+ * rows of pages, each one click away from replacing a working PDF link with a
+ * link to the FAQ. A near-miss still ranks well above the floor; what the floor
+ * removes is the coincidence.
+ */
 export declare function rankLinkTargets(query: string, pages: readonly LinkPageOption[]): LinkPageOption[];
+/**
+ * Known documents ranked by how well they answer `query`, best first.
+ *
+ * The same scorer as pages, and the corpus weighting is what makes it work
+ * here: every document on a site shares its directory and its extension, so
+ * `downloads` and `pdf` identify nothing and are weighted to nearly nothing,
+ * while the part of the filename someone got wrong is what decides the order.
+ *
+ * This is the half a substring filter cannot do. `AadventureArenaBerm` is a
+ * real filename on a real site, typo included; a person typing it from memory
+ * gets one character wrong and a substring match returns nothing at all —
+ * which reads exactly like "this site has no such document".
+ */
+export declare function rankFileTargets(query: string, files: readonly LinkFileOption[]): LinkFileOption[];
+/** What a link picker should offer for what has been typed so far. */
+export type LinkSuggestions = {
+    pages: LinkPageOption[];
+    files: LinkFileOption[];
+};
+/**
+ * The pages and documents to offer for a partly-typed link.
+ *
+ * Two surfaces ask this question — the property panel's link field and the
+ * prose editor's link popover — and they answered it with their own inline
+ * copies of "substring, else rank". The copies disagreed, and both made the
+ * same mistake: they ranked *pages* for a query the parser had already
+ * classified as a document. A screenshot of the result is why this function
+ * exists — `/downloads/…-Gruppen-FR.pdf` typed in, six pages offered, not one
+ * of the site's fifteen PDFs among them.
+ *
+ * So the kind decides which list is offered at all:
+ *
+ * - a document path offers documents, never pages;
+ * - a route offers pages, and any document whose path literally contains what
+ *   was typed (`menu` should still find the menu PDFs);
+ * - `mailto:`, `tel:`, `#anchor` and `https://` offer neither — there is
+ *   nothing on this site they could mean, and the caller's empty state can say
+ *   so instead.
+ *
+ * Within a kind, a literal substring is what a person typing into a box
+ * expects, and ranking is the fallback for when nothing matches literally.
+ */
+export declare function suggestLinkTargets(query: string, options?: {
+    pages?: readonly LinkPageOption[];
+    files?: readonly LinkFileOption[];
+    limit?: number;
+    /**
+     * With an empty box, list the site's first documents alongside its pages.
+     * The prose picker wants that — it is how an editor discovers the site has
+     * documents at all. The link *field* does not: a document shelf under every
+     * link field would bury the pages, which is what a link usually wants.
+     */
+    browseFiles?: boolean;
+}): LinkSuggestions;
 /**
  * The page a dead internal link probably meant.
  *
@@ -120,3 +221,23 @@ export declare function linkAttrs(href: unknown, newTab?: unknown): {
     target?: string;
     rel?: string;
 };
+/**
+ * Every href inside a richtext value.
+ *
+ * A link is not only a `link`-kind prop. Most of the links on a real page are
+ * written *into* prose — `[Menükarte](/downloads/menu-de.pdf)` — and every
+ * link-aware surface we have was walking declared fields only. So the four
+ * menu-PDF links on a live site's Bistro section were not checked, not
+ * rewritten on rename, and not reported; the one linking to a filename with a
+ * typo in it had been wrong since August with nothing able to notice.
+ *
+ * Three shapes, because a richtext value is three things depending on where it
+ * came from: markdown (a site that projects its CMS prose to markdown), a
+ * ProseMirror document (the editor's own format), and raw HTML (a block with a
+ * loose schema). Walking all three costs one function and means a caller never
+ * has to know which it was handed.
+ *
+ * Returns hrefs in document order, duplicates included — a caller that reports
+ * findings wants one per occurrence, and a caller that wants a set can make one.
+ */
+export declare function linksInRichText(value: unknown): string[];