@simmalugnt-se/payload-editor-assistant 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.8.0
+
+- Rich text keeps its formatting. The model reads Lexical as Markdown blocks, one per paragraph,
+  heading or list, and changes single blocks (`set` on `content.2`, `array.insert`,
+  `array.remove`); every other block stays exactly as stored, alignment and styles included.
+  Headings, lists, bold, italic and links come back through Payload's own converters with the
+  field's editor config. Internal links read and write as `[text](doc:pages/12)` and are checked
+  against the field's `LinkFeature` collections and the editor's access. Parts Markdown cannot
+  express (embedded uploads, relationships, custom blocks) are kept, and may be moved or removed but
+  not changed. Before, any change to rich text turned it into plain paragraphs.
+- New optional peer dependency `@payloadcms/richtext-lexical`; without it, rich text works as before.
+- The change list shows which parts of a rich text field changed.
+- A list that is not rich text blocks is refused for a rich text field instead of reaching the form.
+- `validateProposal` receives the data as it will be stored, rich text as Lexical, instead of the
+  compiled operations' raw values.
+
+## 0.7.0
+
+- Picks images for upload fields, such as a share image. `content.find` on an upload collection
+  searches the filename and the collection's text fields (alt, caption, credit) and returns them
+  with the file's type and size; `media.view` takes `ids` to look at up to 6 candidates at a time
+  and 12 per turn, at a smaller size. The assistant proposes only an image it has looked at, and
+  says so when none fits. Fields with several images (`hasMany`) are not picked yet.
+- The suggested change names a chosen image or related document (its title field, filename or
+  title) instead of showing its id.
+- The model sees the fields inside groups, and which collection an upload or relationship points
+  at, so it finds fields such as `meta.image`.
+
 ## 0.6.0
 
 - `media.view`: the assistant can look at the image of the open upload document, so it writes alt

package/README.md

@@ -80,7 +80,7 @@ Nothing is reachable unless you list it. Each collection or global gets the capa
 | `form.read` | read the open edit form, including unsaved changes | no |
 | `form.propose` | put a change in the open form, where the editor keeps or undoes it | yes |
 | `draft.create` | create a new draft document (collections only) | yes |
-| `media.view` | look at the image of the open upload document (upload collections only) | no |
+| `media.view` | look at the open image, or at images by id when picking one (upload collections only) | no |
 
 The assistant never publishes. Form changes land in the open form and the editor saves as usual; an
 approved `draft.create` saves a new, unpublished draft. The `users` collection, Payload's own collections and fields that look like
@@ -103,6 +103,30 @@ address. It uses the smallest of the collection's `imageSizes` at least 768px wi
 original; JPEG, PNG, WebP and GIF up to 5 MB. Choose a model that reads images. Without
 `media.view` the assistant says it cannot see the image instead of guessing from the filename.
 
+With `content.find` as well, the assistant picks images for upload fields, such as a page's share
+image: it searches the collection by filename and text fields (alt, caption), looks at up to 6
+candidates at a time (12 per turn) and proposes one it has seen, or says none fits:
+
+```ts
+collections: {
+  media: { capabilities: ["content.find", "form.read", "form.propose", "media.view"] },
+},
+```
+
+The suggested change names the image ("Image: empty → office-2024.jpg"), and the form and Live
+Preview show it. Images with alt texts are easier to find. Fields with several images (`hasMany`)
+are not picked yet.
+
+## Rich text
+
+With `@payloadcms/richtext-lexical` installed, the assistant reads Lexical rich text as Markdown,
+one block per paragraph, heading or list, and changes only the blocks it is asked to: headings,
+lists, bold, italic and links survive, and every other block stays exactly as stored. It writes only
+what the field's editor allows. Internal links keep pointing at their documents, and new ones must
+point at a collection the field's `LinkFeature` allows and that the editor can read. Parts Markdown
+cannot express, such as an embedded image, are kept as they are. Without the package, rich text is
+written as plain paragraphs as before.
+
 ## Keep or undo
 
 A proposed form change goes straight into the open form, so the fields and Live Preview show it

package/dist/domain/content.js

@@ -3,6 +3,8 @@ import { projectIdentity, projectRecord } from "../schema/project.js";
 import { hasCapability, resolveAllowlist } from "./allowlist.js";
 import { localApi } from "./local-api.js";
 const FIND_LIMIT = 8;
+/** An upload's short text fields (alt, caption, credit) are returned up to this length. */
+const UPLOAD_TEXT_LIMIT = 200;
 export async function findContent(req, options, input) {
     const query = input.query.trim();
     const slugs = input.collection
@@ -27,10 +29,18 @@ export async function findContent(req, options, input) {
         if (!config) {
             continue;
         }
+        // Uploads are found by their file and short texts, and described by them: an image has no title.
+        const uploadTexts = config.upload ? uploadTextFields(req, options, slug) : undefined;
         try {
             const found = await localApi(req).find({
                 collection: slug,
-                ...(query ? { where: searchWhere(query, config.admin?.useAsTitle) } : {}),
+                ...(query
+                    ? {
+                        where: uploadTexts
+                            ? uploadWhere(query, uploadTexts)
+                            : searchWhere(query, config.admin?.useAsTitle),
+                    }
+                    : {}),
                 limit: FIND_LIMIT,
                 depth: 0,
                 locale: input.locale,
@@ -44,6 +54,7 @@ export async function findContent(req, options, input) {
                 results.push({
                     collection: slug,
                     ...projectIdentity(doc, input.locale),
+                    ...(uploadTexts ? uploadIdentity(doc, uploadTexts) : {}),
                 });
             }
         }
@@ -106,6 +117,37 @@ export async function findContentById(req, options, input) {
         return { ok: false, error: "tool_denied", message: "Document is not accessible." };
     }
 }
+/** Top-level text fields of an upload collection that the allowlist shows, e.g. alt and credit. */
+function uploadTextFields(req, options, collection) {
+    return entityFields(req, options, { collection })
+        .filter((field) => field.type === "text" || field.type === "textarea")
+        .map((field) => field.name);
+}
+function uploadWhere(query, texts) {
+    return {
+        or: [
+            { id: { equals: query } },
+            { filename: { contains: query } },
+            ...texts.map((name) => ({ [name]: { contains: query } })),
+        ],
+    };
+}
+function uploadIdentity(doc, texts) {
+    const identity = {
+        filename: doc.filename,
+        mimeType: doc.mimeType,
+        width: doc.width,
+        height: doc.height,
+    };
+    for (const name of texts) {
+        const value = doc[name];
+        identity[name] =
+            typeof value === "string" && value.length > UPLOAD_TEXT_LIMIT
+                ? `${value.slice(0, UPLOAD_TEXT_LIMIT - 1)}…`
+                : value;
+    }
+    return identity;
+}
 function searchWhere(query, useAsTitle) {
     const clauses = [{ id: { equals: query } }];
     const titleField = useAsTitle && useAsTitle !== "id" ? useAsTitle : "title";

package/dist/domain/decide.js

@@ -1,7 +1,8 @@
 import { compileOperations } from "../form/compile.js";
 import { hashFormRevision } from "../form/hash.js";
 import { isFormOperation } from "../form/operations.js";
-import { finalizeCompiled } from "../form/shape.js";
+import { loadRichText } from "../form/rich-text.js";
+import { finalizeCompiled, openRichText } from "../form/shape.js";
 import { DEFAULT_APPROVAL_SLUG } from "../package-name.js";
 import { entityFields } from "../schema/discover.js";
 import { hasCapability, resolveAllowlist } from "./allowlist.js";
@@ -9,6 +10,7 @@ import { writeAudit } from "./audit.js";
 import { localApi } from "./local-api.js";
 import { verifyDocumentRelations } from "./relations.js";
 export async function decideChange(req, options, input) {
+    await loadRichText();
     const actor = String(req.user?.id);
     const found = await localApi(req).findByID({
         collection: DEFAULT_APPROVAL_SLUG,
@@ -67,7 +69,11 @@ export async function decideChange(req, options, input) {
             return { ok: false, error: "stale_context", message: "The form changed before approval." };
         }
     }
-    const compiled = compileOperations(current, operations, {
+    const fields = entityFields(req, options, {
+        collection: record.targetCollection ?? undefined,
+        global: record.targetGlobal ?? undefined,
+    });
+    const compiled = compileOperations(openRichText(current, fields), operations, {
         allowlist: resolved.allowlist.fields,
         denyFields: options.denyFields,
     });
@@ -80,16 +86,12 @@ export async function decideChange(req, options, input) {
         await consume(req, record.id, "failed");
         return { ok: false, error: "tool_denied", message: "Proposal hash mismatch." };
     }
-    const fields = entityFields(req, options, {
-        collection: record.targetCollection ?? undefined,
-        global: record.targetGlobal ?? undefined,
-    });
-    const finalized = finalizeCompiled(compiled.data, fields);
+    const finalized = finalizeCompiled(compiled.data, fields, current);
     if (!finalized.ok) {
         await consume(req, record.id, "failed");
         return { ok: false, error: "tool_denied", message: finalized.error };
     }
-    const relations = await verifyDocumentRelations(req, fields, finalized.data);
+    const relations = await verifyDocumentRelations(req, fields, finalized.data, finalized.links);
     if (!relations.ok) {
         await consume(req, record.id, "failed");
         return { ok: false, error: "tool_denied", message: relations.message };

package/dist/domain/media.d.ts

@@ -1,6 +1,8 @@
 import type { PayloadRequest } from "payload";
 import type { ValidatedEditorAssistantOptions } from "../config/validate.ts";
 export declare const MAX_IMAGE_BYTES: number;
+export declare const MAX_IMAGES_PER_CALL = 6;
+export declare const MAX_IMAGES_PER_TURN = 12;
 export type ImageSource = {
     filename: string;
     mimeType: string;
@@ -25,10 +27,10 @@ export type MediaViewResult = {
     message: string;
 };
 /**
- * The image file to show the model: the smallest of Payload's `imageSizes` at least
- * `PREFERRED_WIDTH` wide, otherwise the original.
+ * The image file to show the model: the smallest of Payload's `imageSizes` at least `minWidth`
+ * wide, otherwise the original.
  */
-export declare function pickImageSource(doc: Record<string, unknown>): ImageSource | null;
+export declare function pickImageSource(doc: Record<string, unknown>, minWidth?: number): ImageSource | null;
 /**
  * Reads the image of a saved upload document with the editor's access, the way Payload serves it:
  * the storage adapter's handlers first, then the file in `staticDir`, then a public URL fetched
@@ -37,4 +39,42 @@ export declare function pickImageSource(doc: Record<string, unknown>): ImageSour
 export declare function viewMedia(req: PayloadRequest, options: ValidatedEditorAssistantOptions, input: {
     collection?: string;
     documentId?: string | number;
+    minWidth?: number;
 }): Promise<MediaViewResult>;
+export type ViewedImage = {
+    id: string | number;
+    mediaType: string;
+    data: string;
+};
+export type MediaListResult = {
+    ok: true;
+    data: {
+        images: Array<{
+            id: string | number;
+            filename: string;
+            width?: number;
+            height?: number;
+            alt?: unknown;
+        } | {
+            id: string | number;
+            error: string;
+        }>;
+    };
+    images: ViewedImage[];
+} | {
+    ok: false;
+    error: string;
+    message: string;
+};
+/**
+ * Several images by id, to compare candidates when picking one: at most `MAX_IMAGES_PER_CALL`, and
+ * never more than `budget.remaining` in the turn. Each is read as `viewMedia` reads the open one, at
+ * a smaller size; one that cannot be shown is listed with the reason instead.
+ */
+export declare function viewMediaList(req: PayloadRequest, options: ValidatedEditorAssistantOptions, input: {
+    collection?: string;
+    ids: Array<string | number>;
+    budget: {
+        remaining: number;
+    };
+}): Promise<MediaListResult>;

package/dist/domain/media.js

@@ -7,17 +7,21 @@ import { localApi } from "./local-api.js";
 const READABLE_TYPES = new Set(["image/jpeg", "image/png", "image/webp", "image/gif"]);
 /** Enough detail for an alt text without sending a full-size original. */
 const PREFERRED_WIDTH = 768;
+/** Enough to tell candidates apart when picking one, at a fraction of the tokens. */
+const BROWSE_WIDTH = 384;
 export const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+export const MAX_IMAGES_PER_CALL = 6;
+export const MAX_IMAGES_PER_TURN = 12;
 const FETCH_TIMEOUT_MS = 10_000;
 /**
- * The image file to show the model: the smallest of Payload's `imageSizes` at least
- * `PREFERRED_WIDTH` wide, otherwise the original.
+ * The image file to show the model: the smallest of Payload's `imageSizes` at least `minWidth`
+ * wide, otherwise the original.
  */
-export function pickImageSource(doc) {
+export function pickImageSource(doc, minWidth = PREFERRED_WIDTH) {
     const original = asSource(doc);
     const sizes = Object.values(asRecord(doc.sizes) ?? {})
         .map((size) => asSource(asRecord(size) ?? {}))
-        .filter((size) => size !== null && (size.width ?? 0) >= PREFERRED_WIDTH)
+        .filter((size) => size !== null && (size.width ?? 0) >= minWidth)
         .sort((a, b) => (a.width ?? 0) - (b.width ?? 0));
     return sizes[0] ?? original;
 }
@@ -61,7 +65,7 @@ export async function viewMedia(req, options, input) {
     catch {
         return { ok: false, error: "tool_denied", message: "Document is not accessible." };
     }
-    const source = pickImageSource(doc);
+    const source = pickImageSource(doc, input.minWidth);
     if (!source || !READABLE_TYPES.has(source.mimeType)) {
         return {
             ok: false,
@@ -84,6 +88,79 @@ export async function viewMedia(req, options, input) {
         image: { mediaType: source.mimeType, data: bytes.data.toString("base64") },
     };
 }
+/**
+ * Several images by id, to compare candidates when picking one: at most `MAX_IMAGES_PER_CALL`, and
+ * never more than `budget.remaining` in the turn. Each is read as `viewMedia` reads the open one, at
+ * a smaller size; one that cannot be shown is listed with the reason instead.
+ */
+export async function viewMediaList(req, options, input) {
+    const collection = input.collection ?? onlyViewableCollection(req, options);
+    if (!collection) {
+        return {
+            ok: false,
+            error: "tool_denied",
+            message: "Say which collection the images are in.",
+        };
+    }
+    const resolved = resolveAllowlist(options, { collection });
+    if (!resolved ||
+        !hasCapability(resolved.allowlist, "media.view") ||
+        !findCollectionConfig(req, collection)?.upload) {
+        return {
+            ok: false,
+            error: "tool_denied",
+            message: "Images in this collection are not allowlisted.",
+        };
+    }
+    if (input.ids.length > MAX_IMAGES_PER_CALL) {
+        return {
+            ok: false,
+            error: "tool_denied",
+            message: `Look at no more than ${MAX_IMAGES_PER_CALL} images at a time.`,
+        };
+    }
+    const listed = [];
+    const images = [];
+    for (const id of input.ids) {
+        if (input.budget.remaining <= 0) {
+            listed.push({
+                id,
+                error: `You have looked at ${MAX_IMAGES_PER_TURN} images this turn, the most allowed.`,
+            });
+            continue;
+        }
+        const viewed = await viewMedia(req, options, {
+            collection,
+            documentId: id,
+            minWidth: BROWSE_WIDTH,
+        });
+        if (!viewed.ok) {
+            listed.push({ id, error: viewed.message });
+            continue;
+        }
+        input.budget.remaining -= 1;
+        listed.push({ id, ...viewed.data });
+        images.push({ id, ...viewed.image });
+    }
+    if (images.length === 0) {
+        const reasons = listed.map((entry) => ("error" in entry ? entry.error : "")).filter(Boolean);
+        return {
+            ok: false,
+            error: "unsupported_media",
+            message: [...new Set(reasons)].join(" ") || "No image could be shown.",
+        };
+    }
+    return { ok: true, data: { images: listed }, images };
+}
+/** The one allowlisted upload collection with `media.view`, when there is exactly one. */
+function onlyViewableCollection(req, options) {
+    const viewable = Object.entries(options.collections)
+        .filter(([slug, allowlist]) => {
+        return hasCapability(allowlist, "media.view") && findCollectionConfig(req, slug)?.upload;
+    })
+        .map(([slug]) => slug);
+    return viewable.length === 1 ? viewable[0] : undefined;
+}
 async function readSource(req, collection, uploadConfig, source, prefix) {
     const upload = (asRecord(uploadConfig) ?? {});
     const tooLarge = {

package/dist/domain/propose.js

@@ -1,19 +1,23 @@
 import { changedPaths } from "../form/changed-paths.js";
 import { compileOperations } from "../form/compile.js";
-import { humanDiff } from "../form/diff.js";
+import { humanDiff, richTextLines } from "../form/diff.js";
 import { hashFormRevision } from "../form/hash.js";
 import { isFormOperation, normalizeOperations } from "../form/operations.js";
-import { finalizeCompiled } from "../form/shape.js";
+import { getAtPath, parseFieldPath } from "../form/path.js";
+import { loadRichText, toBlocks } from "../form/rich-text.js";
+import { finalizeCompiled, openRichText } from "../form/shape.js";
 import { DEFAULT_APPROVAL_SLUG } from "../package-name.js";
 import { entityFields, findCollectionConfig, hasDrafts } from "../schema/discover.js";
+import { fieldAtPath } from "../schema/fields.js";
 import { hasCapability, resolveAllowlist } from "./allowlist.js";
 import { writeAudit } from "./audit.js";
 import { findContentById } from "./content.js";
 import { localApi } from "./local-api.js";
-import { verifyDocumentRelations } from "./relations.js";
+import { labelRelations, verifyDocumentRelations } from "./relations.js";
 /** Long enough to look at a change in the preview before keeping it. */
 const TTL_MS = 30 * 60_000;
 export async function proposeChange(req, options, input) {
+    await loadRichText();
     const resolved = resolveAllowlist(options, input);
     if (!resolved || !hasCapability(resolved.allowlist, input.capability)) {
         return { ok: false, error: "tool_denied", message: "Capability is not allowlisted." };
@@ -24,37 +28,43 @@ export async function proposeChange(req, options, input) {
     }
     const typedOperations = operations;
     const current = await resolveCurrentForm(req, options, input);
-    const compiled = compileOperations(current, typedOperations, {
+    const fields = entityFields(req, options, {
+        collection: input.collection,
+        global: input.global,
+    });
+    // Rich text opens into blocks, so operations can reach one block and leave the rest as stored.
+    const compiled = compileOperations(openRichText(current, fields), typedOperations, {
         allowlist: resolved.allowlist.fields,
         denyFields: options.denyFields,
     });
     if (!compiled.ok) {
         return { ok: false, error: "tool_denied", message: compiled.error };
     }
-    if (options.validateProposal) {
-        const extra = await options.validateProposal({
-            operations: typedOperations,
-            data: compiled.data,
-        });
-        if (!extra.ok) {
-            return { ok: false, error: "tool_denied", message: extra.errors.join(" ") };
-        }
-    }
     if (input.capability === "draft.create") {
         const blocked = draftCreateDenied(req, input.collection);
         if (blocked) {
             return { ok: false, error: "tool_denied", message: blocked };
         }
     }
-    const fields = entityFields(req, options, {
-        collection: input.collection,
-        global: input.global,
-    });
-    const finalized = finalizeCompiled(compiled.data, fields);
+    const richTextBefore = richTextPaths(typedOperations, fields, current).map((path) => ({
+        path,
+        blocks: storedBlocks(fields, path, current),
+        after: getAtPath(compiled.data, parseFieldPath(path)),
+    }));
+    const finalized = finalizeCompiled(compiled.data, fields, current);
     if (!finalized.ok) {
         return { ok: false, error: "tool_denied", message: finalized.error };
     }
-    const relations = await verifyDocumentRelations(req, fields, finalized.data);
+    if (options.validateProposal) {
+        const extra = await options.validateProposal({
+            operations: typedOperations,
+            data: finalized.data,
+        });
+        if (!extra.ok) {
+            return { ok: false, error: "tool_denied", message: extra.errors.join(" ") };
+        }
+    }
+    const relations = await verifyDocumentRelations(req, fields, finalized.data, finalized.links);
     if (!relations.ok) {
         return { ok: false, error: "tool_denied", message: relations.message };
     }
@@ -62,7 +72,21 @@ export async function proposeChange(req, options, input) {
     const canonicalHash = await hashFormRevision(typedOperations);
     const nonce = crypto.randomUUID();
     const expiresAt = new Date(Date.now() + TTL_MS).toISOString();
-    const diff = humanDiff(current, typedOperations, input.language);
+    // Ids set by this change, before and after, get names in the change list.
+    const setIds = new Set(typedOperations.flatMap((operation) => operation.op === "set"
+        ? [operation.value, getAtPath(current, parseFieldPath(operation.path))]
+            .filter((value) => typeof value === "string" || typeof value === "number")
+            .map(String)
+        : []));
+    const labels = setIds.size
+        ? await labelRelations(req, fields, [finalized.data, current], setIds)
+        : undefined;
+    const inRichText = (operation) => "path" in operation &&
+        richTextBefore.some(({ path }) => operation.path === path || operation.path.startsWith(`${path}.`));
+    const diff = [
+        ...humanDiff(current, typedOperations.filter((operation) => !inRichText(operation)), input.language, labels),
+        ...richTextBefore.flatMap(({ path, blocks, after }) => richTextLines(path, blocks, Array.isArray(after) ? after : [after], input.language)),
+    ];
     let created;
     try {
         created = await localApi(req).create({
@@ -153,3 +177,26 @@ function draftCreateDenied(req, collection) {
     }
     return null;
 }
+/** Rich text fields the operations reach, whole or by block, as form paths. */
+function richTextPaths(operations, fields, current) {
+    const paths = new Set();
+    for (const operation of operations) {
+        if (!("path" in operation))
+            continue;
+        const segments = operation.path.split(".");
+        for (let end = 1; end <= segments.length; end++) {
+            const prefix = segments.slice(0, end).join(".");
+            if (fieldAtPath(fields, prefix, current)?.type === "richText") {
+                paths.add(prefix);
+                break;
+            }
+        }
+    }
+    return [...paths];
+}
+/** The stored rich text at `path` as the model read it: Markdown blocks and `{ keep, type }`. */
+function storedBlocks(fields, path, current) {
+    const field = fieldAtPath(fields, path, current);
+    const blocks = toBlocks(getAtPath(current, parseFieldPath(path)), field?.editor);
+    return Array.isArray(blocks) ? blocks : [];
+}

package/dist/domain/relations.d.ts

@@ -4,9 +4,19 @@ export type RelationRef = {
     collection: string;
     id: string;
 };
-export declare function verifyDocumentRelations(req: PayloadRequest, fields: FieldNode[], data: Record<string, unknown>): Promise<{
+/**
+ * Every relation and upload in `data`, and `extra` refs such as internal links in rewritten rich
+ * text, must exist and be readable by the editor.
+ */
+export declare function verifyDocumentRelations(req: PayloadRequest, fields: FieldNode[], data: Record<string, unknown>, extra?: RelationRef[]): Promise<{
     ok: true;
 } | {
     ok: false;
     message: string;
 }>;
+/**
+ * Names for the documents that relation and upload fields in `data` point at, by id, for the change
+ * list: the collection's title field, then a filename or title. Read with the editor's access;
+ * anything unreadable keeps its id. `only` limits the lookups to those ids.
+ */
+export declare function labelRelations(req: PayloadRequest, fields: FieldNode[], data: Array<Record<string, unknown>>, only?: Set<string>): Promise<Map<string, string>>;

package/dist/domain/relations.js

@@ -1,6 +1,11 @@
+import { findCollectionConfig } from "../schema/discover.js";
 import { localApi } from "./local-api.js";
-export async function verifyDocumentRelations(req, fields, data) {
-    const refs = collectRefs(fields, data);
+/**
+ * Every relation and upload in `data`, and `extra` refs such as internal links in rewritten rich
+ * text, must exist and be readable by the editor.
+ */
+export async function verifyDocumentRelations(req, fields, data, extra = []) {
+    const refs = [...collectRefs(fields, data), ...extra];
     for (const ref of refs) {
         try {
             await localApi(req).findByID({
@@ -21,6 +26,38 @@ export async function verifyDocumentRelations(req, fields, data) {
     }
     return { ok: true };
 }
+/**
+ * Names for the documents that relation and upload fields in `data` point at, by id, for the change
+ * list: the collection's title field, then a filename or title. Read with the editor's access;
+ * anything unreadable keeps its id. `only` limits the lookups to those ids.
+ */
+export async function labelRelations(req, fields, data, only) {
+    const labels = new Map();
+    for (const ref of data.flatMap((entry) => collectRefs(fields, entry))) {
+        if (labels.has(ref.id) || (only && !only.has(ref.id))) {
+            continue;
+        }
+        try {
+            const doc = await localApi(req).findByID({
+                collection: ref.collection,
+                id: ref.id,
+                depth: 0,
+                req,
+                user: req.user,
+                overrideAccess: false,
+            });
+            const useAsTitle = findCollectionConfig(req, ref.collection)?.admin?.useAsTitle;
+            const label = [useAsTitle ? doc[useAsTitle] : undefined, doc.filename, doc.title].find((value) => typeof value === "string" && value.trim() !== "");
+            if (label) {
+                labels.set(ref.id, label);
+            }
+        }
+        catch {
+            // Unreadable: the change list shows the id, and verification refuses the proposal.
+        }
+    }
+    return labels;
+}
 function collectRefs(fields, data) {
     if (!data || typeof data !== "object") {
         return [];

package/dist/form/diff.d.ts

@@ -4,6 +4,15 @@ export type HumanDiffLine = {
     text: string;
 };
 export type DiffLanguage = "sv" | "en";
-export declare function humanDiff(current: Record<string, unknown>, operations: FormOperation[], language?: DiffLanguage): HumanDiffLine[];
+/**
+ * `labels` names related documents by id (see `labelRelations`), so a chosen image reads as its
+ * filename or alt text instead of an id. Rich text is listed by `richTextLines` instead.
+ */
+export declare function humanDiff(current: Record<string, unknown>, operations: FormOperation[], language?: DiffLanguage, labels?: Map<string, string>): HumanDiffLine[];
+/**
+ * The parts of a rich text field that changed: `before` as the model read it (Markdown blocks),
+ * `after` as compiled, where `{ keep: i }` is block `i` unchanged.
+ */
+export declare function richTextLines(path: string, before: unknown[], after: unknown[], language?: DiffLanguage): HumanDiffLine[];
 /** Sub-lines are indented two spaces; the approval panel nests them under the header. */
 export declare const DIFF_SUBLINE_INDENT = "  ";