@avocadostudio-ai/richtext 0.2.0

package/dist/doc.js

@@ -0,0 +1,306 @@
+/**
+ * The pivot format: a ProseMirror document.
+ *
+ * Every CMS in this package models rich text differently — Contentful nests a
+ * recursive `document` tree, Sanity keeps a flat array of Portable Text blocks,
+ * Strapi a flat Slate-shaped array — and Avocado's own `richtext` fields hold a
+ * markdown string. Converting each pair directly would need six converters and
+ * would still lose whatever the two ends did not have in common. Instead every
+ * format converts to and from one shape, and that shape is the ProseMirror
+ * document the property panel already edits natively (`RichTextJsonField`).
+ *
+ * The types are deliberately open — `type` is a `string`, not a union of the
+ * names we know. A Portable Text block with a custom `_type`, a Contentful
+ * `embedded-entry-block`, a mark some space enabled last week: none of them are
+ * in our vocabulary, and a closed union would force each converter to throw the
+ * value away. They ride through the pivot as data instead, which is what makes
+ * a round trip through Avocado non-destructive for content Avocado cannot edit.
+ *
+ * Node and mark names are Tiptap's, because the editor is Tiptap: `paragraph`,
+ * `heading`, `bulletList`, `orderedList`, `listItem`, `blockquote`, `codeBlock`,
+ * `horizontalRule`, `hardBreak`, `text`; marks `bold`, `italic`, `strike`,
+ * `code`, `underline`, `link`.
+ */
+import { parseRichText, resolveRichTextHeadingLevel } from "./parse.js";
+/** Node names this package produces and understands. */
+export const NODE = {
+    doc: "doc",
+    paragraph: "paragraph",
+    heading: "heading",
+    bulletList: "bulletList",
+    orderedList: "orderedList",
+    listItem: "listItem",
+    blockquote: "blockquote",
+    codeBlock: "codeBlock",
+    horizontalRule: "horizontalRule",
+    hardBreak: "hardBreak",
+    text: "text",
+    /**
+     * A block the pivot could not model — a Portable Text `_type` we do not know,
+     * a Contentful embedded entry, a Strapi image. It carries the source object
+     * untouched under `attrs.data` so the converter back out can re-emit it
+     * unchanged. The editor registers a matching read-only node, so it also
+     * survives a trip through the property panel in its original position.
+     */
+    unknown: "avocadoUnknownBlock"
+};
+/** Mark names this package produces and understands. */
+export const MARK = {
+    bold: "bold",
+    italic: "italic",
+    strike: "strike",
+    code: "code",
+    underline: "underline",
+    link: "link"
+};
+/**
+ * A richtext value stored as a document rather than a markdown string.
+ *
+ * The same signature `block-manifest.ts` keys its `isProseMirrorDocSchema` off:
+ * an object whose `type` is the literal `"doc"`. Anything else — a markdown
+ * string included — is not a document and must not be handed to the converters.
+ */
+export function isRichTextDoc(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return candidate.type === "doc" && (candidate.content === undefined || Array.isArray(candidate.content));
+}
+export function emptyDoc() {
+    return { type: "doc", content: [] };
+}
+// ---------------------------------------------------------------------------
+// markdown -> document
+// ---------------------------------------------------------------------------
+function inlineToNodes(tokens) {
+    const nodes = [];
+    for (const token of tokens) {
+        if (token.type === "break") {
+            nodes.push({ type: NODE.hardBreak });
+            continue;
+        }
+        if (token.text.length === 0)
+            continue;
+        switch (token.type) {
+            case "text":
+                nodes.push({ type: NODE.text, text: token.text });
+                break;
+            case "strong":
+                nodes.push({ type: NODE.text, text: token.text, marks: [{ type: MARK.bold }] });
+                break;
+            case "em":
+                nodes.push({ type: NODE.text, text: token.text, marks: [{ type: MARK.italic }] });
+                break;
+            case "strike":
+                nodes.push({ type: NODE.text, text: token.text, marks: [{ type: MARK.strike }] });
+                break;
+            case "code":
+                nodes.push({ type: NODE.text, text: token.text, marks: [{ type: MARK.code }] });
+                break;
+            case "link":
+                nodes.push({
+                    type: NODE.text,
+                    text: token.text,
+                    marks: [{ type: MARK.link, attrs: { href: token.href } }]
+                });
+                break;
+        }
+    }
+    return nodes;
+}
+function withContent(node, content) {
+    // ProseMirror treats an absent `content` and an empty array the same, but the
+    // absent form is what Tiptap emits for an empty paragraph — match it so a
+    // doc that went out and came back compares equal.
+    return content.length > 0 ? { ...node, content } : node;
+}
+function listItemToNode(item) {
+    const content = [
+        withContent({ type: NODE.paragraph }, inlineToNodes(item.inline))
+    ];
+    if (item.children)
+        content.push(listToNode(item.children));
+    return { type: NODE.listItem, content };
+}
+function listToNode(list) {
+    return {
+        type: list.type === "ordered-list" ? NODE.orderedList : NODE.bulletList,
+        content: list.items.map(listItemToNode)
+    };
+}
+function blockToNodes(block) {
+    switch (block.type) {
+        case "heading": {
+            /*
+             * The authored hash count is clamped, not copied. A markdown body renders
+             * `#` as `<h2>` (see `resolveRichTextHeadingLevel`), so carrying `level:1`
+             * into the document would make the same content render a different
+             * outline depending on which representation it happened to be in.
+             */
+            const heading = withContent({ type: NODE.heading, attrs: { level: resolveRichTextHeadingLevel(block.level) } }, inlineToNodes(block.inline));
+            if (!block.trailing)
+                return [heading];
+            return [heading, withContent({ type: NODE.paragraph }, inlineToNodes(block.trailing))];
+        }
+        case "unordered-list":
+        case "ordered-list":
+            return [listToNode({ type: block.type, items: block.items })];
+        case "blockquote":
+            return [withContent({ type: NODE.blockquote }, block.children.flatMap(blockToNodes))];
+        case "code":
+            return [
+                {
+                    type: NODE.codeBlock,
+                    attrs: { language: block.language ?? null },
+                    ...(block.code.length > 0 ? { content: [{ type: NODE.text, text: block.code }] } : {})
+                }
+            ];
+        case "rule":
+            return [{ type: NODE.horizontalRule }];
+        case "paragraph":
+            return [withContent({ type: NODE.paragraph }, inlineToNodes(block.inline))];
+    }
+}
+/** Parse an Avocado markdown richtext value into the pivot document. */
+export function fromMarkdown(markdown) {
+    if (typeof markdown !== "string" || markdown.trim().length === 0)
+        return emptyDoc();
+    return { type: "doc", content: parseRichText(markdown).flatMap(blockToNodes) };
+}
+// ---------------------------------------------------------------------------
+// document -> markdown
+// ---------------------------------------------------------------------------
+/**
+ * Escape exactly what `prosemirror-markdown`'s `esc()` escapes on a text node.
+ *
+ * It has to be exactly that set: the parser unescapes the same characters, so
+ * escaping more would leave stray backslashes on the page and escaping fewer
+ * would let a literal `[` open a link on the next read.
+ */
+const TEXT_ESCAPE = /[`*\\~[\]_]/g;
+/** Link hrefs use a different set — see the link mark's serialiser. */
+const HREF_ESCAPE = /[()"]/g;
+export function escapeMarkdownText(text) {
+    return text.replace(TEXT_ESCAPE, "\\$&");
+}
+function escapeHref(href) {
+    return href.replace(HREF_ESCAPE, "\\$&");
+}
+function hasMark(node, name) {
+    return Array.isArray(node.marks) && node.marks.some((m) => m.type === name);
+}
+function linkHref(node) {
+    const link = node.marks?.find((m) => m.type === MARK.link);
+    const href = link?.attrs?.href;
+    return typeof href === "string" ? href : undefined;
+}
+/**
+ * Serialise one inline node.
+ *
+ * Marks the grammar cannot express — `underline`, a CMS's own decorator, an
+ * inline colour — drop off here and the text stays. That is the whole reason
+ * the document path exists: a value that needs those marks should be stored as
+ * a document, not flattened to markdown.
+ */
+function inlineToMarkdown(node) {
+    if (node.type === NODE.hardBreak)
+        return "\\\n";
+    if (typeof node.text !== "string") {
+        // An unknown inline node that still wraps text (some CMSes model links that
+        // way) — keep the words rather than dropping the span.
+        return (node.content ?? []).map(inlineToMarkdown).join("");
+    }
+    let out = hasMark(node, MARK.code) ? "`" + node.text + "`" : escapeMarkdownText(node.text);
+    if (hasMark(node, MARK.strike))
+        out = `~~${out}~~`;
+    if (hasMark(node, MARK.italic))
+        out = `*${out}*`;
+    if (hasMark(node, MARK.bold))
+        out = `**${out}**`;
+    const href = linkHref(node);
+    if (href !== undefined)
+        out = `[${out}](${escapeHref(href)})`;
+    return out;
+}
+function inlineListToMarkdown(nodes) {
+    return (nodes ?? []).map(inlineToMarkdown).join("");
+}
+function isListNode(node) {
+    return node.type === NODE.bulletList || node.type === NODE.orderedList;
+}
+function listToMarkdown(node, depth) {
+    const ordered = node.type === NODE.orderedList;
+    const indent = "  ".repeat(depth);
+    const lines = [];
+    const items = node.content ?? [];
+    for (let index = 0; index < items.length; index++) {
+        const children = items[index].content ?? [];
+        const paragraphs = children.filter((c) => !isListNode(c));
+        const nested = children.filter(isListNode);
+        /*
+         * A list item may hold several paragraphs. Markdown's lazy-continuation
+         * form for that is a blank line plus an indent, which this grammar reads as
+         * the end of the list — so the extra paragraphs are joined onto the item
+         * line with hard breaks instead. Lossy, and deliberately so: the
+         * alternative silently ends the list halfway down.
+         */
+        const text = paragraphs
+            .map((p) => (p.type === NODE.paragraph ? inlineListToMarkdown(p.content) : blockToMarkdown(p, depth)))
+            .filter((t) => t.length > 0)
+            .join("\\\n");
+        lines.push(`${indent}${ordered ? `${index + 1}.` : "-"} ${text}`);
+        for (const child of nested)
+            lines.push(listToMarkdown(child, depth + 1));
+    }
+    return lines.join("\n");
+}
+function blockToMarkdown(node, depth) {
+    switch (node.type) {
+        case NODE.paragraph:
+            return inlineListToMarkdown(node.content);
+        case NODE.heading: {
+            const rawLevel = typeof node.attrs?.level === "number" ? node.attrs.level : 2;
+            /*
+             * Clamped on the way out too. `# ` would be read back as level 2 by the
+             * markdown renderer, so writing it would make `doc -> markdown -> doc`
+             * change the value on every trip.
+             */
+            return `${"#".repeat(resolveRichTextHeadingLevel(rawLevel))} ${inlineListToMarkdown(node.content)}`;
+        }
+        case NODE.bulletList:
+        case NODE.orderedList:
+            return listToMarkdown(node, depth);
+        case NODE.blockquote:
+            return (node.content ?? [])
+                .map((child) => blockToMarkdown(child, depth))
+                .filter((chunk) => chunk.length > 0)
+                .join("\n\n")
+                .split("\n")
+                .map((line) => (line.length > 0 ? `> ${line}` : ">"))
+                .join("\n");
+        case NODE.codeBlock: {
+            const language = typeof node.attrs?.language === "string" ? node.attrs.language : "";
+            const code = (node.content ?? []).map((c) => c.text ?? "").join("");
+            return "```" + language + "\n" + code + "\n```";
+        }
+        case NODE.horizontalRule:
+            return "---";
+        case NODE.unknown:
+            // No markdown can stand in for it, and inventing one would put the
+            // placeholder into the published content. Dropped here on purpose; the
+            // document path is where these values keep their meaning.
+            return "";
+        default:
+            // An unrecognised block that still has children: keep the prose.
+            return (node.content ?? []).map((child) => blockToMarkdown(child, depth)).join("\n\n");
+    }
+}
+/** Serialise the pivot document to an Avocado markdown richtext value. */
+export function toMarkdown(input) {
+    const nodes = Array.isArray(input) ? input : (input.content ?? []);
+    return nodes
+        .map((node) => blockToMarkdown(node, 0))
+        .filter((chunk) => chunk.length > 0)
+        .join("\n\n")
+        .trim();
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@avocadostudio-ai/richtext` — the rich-text grammar and its converters.
+ *
+ * Two layers, and they are worth keeping straight:
+ *
+ * - **The grammar** (`parse.ts`) is the markdown subset an Avocado `richtext`
+ *   string is written in. It is a parser only: what a heading or a link looks
+ *   like on screen is the calling surface's business, and there are three of
+ *   those (the React renderers, the editor overlay, the Puck adapter).
+ * - **The pivot** (`doc.ts`) is a ProseMirror document, the shape the property
+ *   panel edits natively. Every CMS converts to and from it rather than to and
+ *   from each other, so adding a fourth CMS costs one converter pair, not three.
+ *
+ * The package has no runtime dependencies and knows nothing about React, the
+ * orchestrator or any CMS client — the CMS types here are structural, so a
+ * migration script can convert a dataset without installing anything else.
+ */
+export { parseInline, parseRichText, parseRichTextBlocks, normalizeRichTextBody, resolveRichTextHeadingLevel, clampMarkdownHeadings, unescapeMarkdownText, type InlineToken, type RichTextBlock, type RichTextList, type RichTextListItem } from "./parse.ts";
+export { NODE, MARK, isRichTextDoc, emptyDoc, fromMarkdown, toMarkdown, escapeMarkdownText, type RichTextDoc, type RichTextNode, type RichTextMark } from "./doc.ts";
+export { deepEqual, omitDeep, mergeByIdentity, mergeRichTextDoc } from "./merge.ts";
+export { fromPortableText, toPortableText, type PortableTextBlock, type PortableTextSpan, type PortableTextMarkDef, type ToPortableTextOptions } from "./portable-text.ts";
+export { fromContentful, toContentful, type ContentfulDocument, type ContentfulNode, type ContentfulMark } from "./contentful.ts";
+export { fromStrapiBlocks, toStrapiBlocks, type StrapiNode, type StrapiText } from "./strapi.ts";

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * `@avocadostudio-ai/richtext` — the rich-text grammar and its converters.
+ *
+ * Two layers, and they are worth keeping straight:
+ *
+ * - **The grammar** (`parse.ts`) is the markdown subset an Avocado `richtext`
+ *   string is written in. It is a parser only: what a heading or a link looks
+ *   like on screen is the calling surface's business, and there are three of
+ *   those (the React renderers, the editor overlay, the Puck adapter).
+ * - **The pivot** (`doc.ts`) is a ProseMirror document, the shape the property
+ *   panel edits natively. Every CMS converts to and from it rather than to and
+ *   from each other, so adding a fourth CMS costs one converter pair, not three.
+ *
+ * The package has no runtime dependencies and knows nothing about React, the
+ * orchestrator or any CMS client — the CMS types here are structural, so a
+ * migration script can convert a dataset without installing anything else.
+ */
+export { parseInline, parseRichText, parseRichTextBlocks, normalizeRichTextBody, resolveRichTextHeadingLevel, clampMarkdownHeadings, unescapeMarkdownText } from "./parse.js";
+export { NODE, MARK, isRichTextDoc, emptyDoc, fromMarkdown, toMarkdown, escapeMarkdownText } from "./doc.js";
+export { deepEqual, omitDeep, mergeByIdentity, mergeRichTextDoc } from "./merge.js";
+export { fromPortableText, toPortableText } from "./portable-text.js";
+export { fromContentful, toContentful } from "./contentful.js";
+export { fromStrapiBlocks, toStrapiBlocks } from "./strapi.js";

package/dist/merge.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Identity-preserving merges.
+ *
+ * Rich text in a CMS is not just its words. A Portable Text block carries a
+ * `_key` that annotations and real-time collaboration address it by; a
+ * Contentful node carries a `data` object with entry links in it; every format
+ * has fields no converter here understands. Re-serialising a document from
+ * scratch throws all of that away, and the diff a content editor sees on the
+ * next publish is "every block replaced" — which is both wrong and, on a
+ * dataset of any size, unreviewable.
+ *
+ * So a write is always a merge against what was already stored: blocks whose
+ * content did not change come back as the *original objects*, untouched, and
+ * only genuinely edited blocks are rebuilt.
+ */
+import { type RichTextDoc } from "./doc.ts";
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/** A shallow copy of `value` with the listed keys removed, recursively. */
+export declare function omitDeep<T>(value: T, keys: readonly string[]): T;
+/**
+ * Pair each newly built item with the stored item it replaces, and keep the
+ * stored one whenever the two say the same thing.
+ *
+ * Matching runs in two passes because a block that only *moved* must keep its
+ * key: content-equality first (so a reordered document reuses every key), then
+ * position for whatever is left over (so an edited block keeps the key of the
+ * block that was in its slot rather than being issued a new one).
+ *
+ * `identityKeys` are the fields excluded from the content comparison — the
+ * stored key itself, and anything else derived rather than authored.
+ */
+export declare function mergeByIdentity<T>(next: T[], previous: T[], options: {
+    /**
+     * Reduce an item to just the part a human authored, so two items that say
+     * the same thing compare equal however their storage keys differ.
+     */
+    canonical: (item: T) => unknown;
+    /** Copy the stored item's identity onto a rebuilt one. */
+    adopt: (rebuilt: T, stored: T) => T;
+    /** Should this stored item be considered at all? */
+    matches?: (rebuilt: T, stored: T) => boolean;
+}): T[];
+/**
+ * Fold a freshly built document into the one that was stored.
+ *
+ * Two jobs, and the second is the one that stops data loss:
+ *
+ * 1. Carry stored `_key`s onto the rebuilt nodes, so a CMS write updates blocks
+ *    rather than replacing them.
+ * 2. Put back anything the rebuilt document *could not have contained*. When a
+ *    plan rewrites a rich-text prop it sends a markdown string, and markdown has
+ *    no way to say "an embedded product card sat here" — so a naive coercion
+ *    deletes every such block on the first text edit. They are re-inserted at
+ *    the position they held before. That position is a guess once the
+ *    surrounding prose has changed length; keeping the block in roughly the
+ *    right place is the recoverable failure, deleting it is not.
+ */
+export declare function mergeRichTextDoc(next: RichTextDoc, previous: RichTextDoc, options?: {
+    /**
+     * The mark types the format `next` was built from can express. Marks
+     * outside this set are treated as invisible: they take no part in deciding
+     * whether a node changed, and they are carried over from the stored
+     * document. Defaults to markdown's vocabulary, which is what every caller
+     * of this function is coercing from. Pass every mark type in play to opt
+     * out — appropriate only when `next` came from a lossless source.
+     */
+    representableMarks?: readonly string[];
+}): RichTextDoc;

package/dist/merge.js

@@ -0,0 +1,252 @@
+/**
+ * Identity-preserving merges.
+ *
+ * Rich text in a CMS is not just its words. A Portable Text block carries a
+ * `_key` that annotations and real-time collaboration address it by; a
+ * Contentful node carries a `data` object with entry links in it; every format
+ * has fields no converter here understands. Re-serialising a document from
+ * scratch throws all of that away, and the diff a content editor sees on the
+ * next publish is "every block replaced" — which is both wrong and, on a
+ * dataset of any size, unreviewable.
+ *
+ * So a write is always a merge against what was already stored: blocks whose
+ * content did not change come back as the *original objects*, untouched, and
+ * only genuinely edited blocks are rebuilt.
+ */
+import { MARK, NODE } from "./doc.js";
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null || typeof a !== "object")
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, i) => deepEqual(item, b[i]));
+    }
+    const left = a;
+    const right = b;
+    // `undefined` and absent are the same thing here: a converter that omits a
+    // field and one that sets it to undefined produced the same value.
+    const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
+    for (const key of keys) {
+        if (left[key] === undefined && right[key] === undefined)
+            continue;
+        if (!deepEqual(left[key], right[key]))
+            return false;
+    }
+    return true;
+}
+/** A shallow copy of `value` with the listed keys removed, recursively. */
+export function omitDeep(value, keys) {
+    if (Array.isArray(value))
+        return value.map((item) => omitDeep(item, keys));
+    if (value === null || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (keys.includes(k))
+            continue;
+        out[k] = omitDeep(v, keys);
+    }
+    return out;
+}
+/**
+ * Pair each newly built item with the stored item it replaces, and keep the
+ * stored one whenever the two say the same thing.
+ *
+ * Matching runs in two passes because a block that only *moved* must keep its
+ * key: content-equality first (so a reordered document reuses every key), then
+ * position for whatever is left over (so an edited block keeps the key of the
+ * block that was in its slot rather than being issued a new one).
+ *
+ * `identityKeys` are the fields excluded from the content comparison — the
+ * stored key itself, and anything else derived rather than authored.
+ */
+export function mergeByIdentity(next, previous, options) {
+    const { canonical, adopt, matches } = options;
+    const claimed = new Set();
+    const result = new Array(next.length).fill(undefined);
+    const eligible = (rebuilt, index) => !claimed.has(index) && (matches ? matches(rebuilt, previous[index]) : true);
+    const storedCanonical = previous.map(canonical);
+    // Pass 1 — identical content, wherever it sits now.
+    for (let i = 0; i < next.length; i++) {
+        const bare = canonical(next[i]);
+        for (let j = 0; j < previous.length; j++) {
+            if (!eligible(next[i], j))
+                continue;
+            if (!deepEqual(bare, storedCanonical[j]))
+                continue;
+            claimed.add(j);
+            result[i] = previous[j];
+            break;
+        }
+    }
+    // Pass 2 — same slot, same shape: an edit in place.
+    for (let i = 0; i < next.length; i++) {
+        if (result[i] !== undefined)
+            continue;
+        if (i < previous.length && eligible(next[i], i)) {
+            claimed.add(i);
+            result[i] = adopt(next[i], previous[i]);
+            continue;
+        }
+        result[i] = next[i];
+    }
+    return result;
+}
+/**
+ * The character styles the markdown grammar can spell. Everything else — an
+ * underline, a Portable Text decorator like `accent`, any CMS-defined style —
+ * is invisible to a markdown round-trip: it leaves on the way out and cannot
+ * come back on the way in.
+ */
+const MARKDOWN_MARKS = [MARK.bold, MARK.italic, MARK.strike, MARK.code, MARK.link];
+function canonicalNode(node, representable) {
+    const { _key: _dropped, ...attrs } = node.attrs ?? {};
+    const out = { type: node.type };
+    if (Object.keys(attrs).length > 0)
+        out.attrs = attrs;
+    if (node.marks !== undefined) {
+        const visible = node.marks.filter((mark) => representable.has(mark.type));
+        if (visible.length > 0)
+            out.marks = visible;
+    }
+    if (node.text !== undefined)
+        out.text = node.text;
+    if (node.content !== undefined)
+        out.content = canonicalChildren(node.content, representable);
+    return out;
+}
+/**
+ * Project children, then glue back together the text spans the projection just
+ * made indistinguishable.
+ *
+ * Dropping an invisible mark leaves a seam. A stored paragraph reading
+ * `["Untouched ", accent("accented"), " paragraph."]` projects to three spans
+ * with identical (empty) marks, where the same sentence parsed from markdown is
+ * one span — so a comparison would report a difference that exists only because
+ * the styling was removed. Coalescing adjacent same-marked spans closes the
+ * seam and makes the two forms compare equal, which is the whole point.
+ */
+function canonicalChildren(nodes, representable) {
+    const out = [];
+    for (const node of nodes) {
+        const canonical = canonicalNode(node, representable);
+        const previous = out[out.length - 1];
+        const bothArePlainText = previous !== undefined &&
+            typeof previous.text === "string" &&
+            typeof canonical.text === "string" &&
+            previous.content === undefined &&
+            canonical.content === undefined &&
+            previous.type === canonical.type;
+        if (bothArePlainText && deepEqual(previous.marks, canonical.marks)) {
+            previous.text = `${previous.text}${canonical.text}`;
+            continue;
+        }
+        out.push(canonical);
+    }
+    return out;
+}
+/** The marks on a node the source format had no way to express. */
+function invisibleMarks(node, representable) {
+    return (node.marks ?? []).filter((mark) => !representable.has(mark.type));
+}
+/** Index every text span carrying invisible marks, by its exact text. */
+function collectInvisibleMarks(node, representable, into) {
+    if (typeof node.text === "string") {
+        const hidden = invisibleMarks(node, representable);
+        if (hidden.length > 0 && !into.has(node.text))
+            into.set(node.text, hidden);
+    }
+    for (const child of node.content ?? [])
+        collectInvisibleMarks(child, representable, into);
+}
+/**
+ * Put invisible marks back onto the text spans they were on, where those spans
+ * survived the edit verbatim.
+ *
+ * This is the consolation prize for a node that genuinely changed. Pass 1 has
+ * already handled untouched nodes by keeping the stored object whole; here the
+ * prose really was rewritten, so the only honest thing to preserve is a style
+ * whose exact run of text is still present. A span whose words changed loses
+ * its styling, because nothing in the edit says where the style should now end.
+ */
+function reapplyInvisibleMarks(rebuilt, byText, representable) {
+    const content = rebuilt.content?.map((child) => reapplyInvisibleMarks(child, byText, representable));
+    let marks = rebuilt.marks;
+    if (typeof rebuilt.text === "string") {
+        const hidden = byText.get(rebuilt.text);
+        if (hidden && hidden.length > 0) {
+            const already = new Set((marks ?? []).map((mark) => mark.type));
+            const additions = hidden.filter((mark) => !already.has(mark.type));
+            if (additions.length > 0)
+                marks = [...(marks ?? []), ...additions];
+        }
+    }
+    if (marks === rebuilt.marks && content === undefined)
+        return rebuilt;
+    return {
+        ...rebuilt,
+        ...(marks !== undefined ? { marks } : {}),
+        ...(content !== undefined ? { content } : {})
+    };
+}
+function nodeKey(node) {
+    const key = node.attrs?._key;
+    return typeof key === "string" ? key : undefined;
+}
+function adoptNodeKey(rebuilt, stored) {
+    const key = nodeKey(stored);
+    if (key === undefined)
+        return rebuilt;
+    return { ...rebuilt, attrs: { ...(rebuilt.attrs ?? {}), _key: key } };
+}
+/**
+ * Fold a freshly built document into the one that was stored.
+ *
+ * Two jobs, and the second is the one that stops data loss:
+ *
+ * 1. Carry stored `_key`s onto the rebuilt nodes, so a CMS write updates blocks
+ *    rather than replacing them.
+ * 2. Put back anything the rebuilt document *could not have contained*. When a
+ *    plan rewrites a rich-text prop it sends a markdown string, and markdown has
+ *    no way to say "an embedded product card sat here" — so a naive coercion
+ *    deletes every such block on the first text edit. They are re-inserted at
+ *    the position they held before. That position is a guess once the
+ *    surrounding prose has changed length; keeping the block in roughly the
+ *    right place is the recoverable failure, deleting it is not.
+ */
+export function mergeRichTextDoc(next, previous, options) {
+    const previousNodes = previous.content ?? [];
+    const nextNodes = next.content ?? [];
+    const representable = new Set(options?.representableMarks ?? MARKDOWN_MARKS);
+    const merged = mergeByIdentity(nextNodes, previousNodes, {
+        canonical: (node) => canonicalNode(node, representable),
+        adopt: (rebuilt, stored) => {
+            // Scoped to the one stored node being replaced, not the whole document:
+            // a style must not leak onto an unrelated node that happens to repeat a
+            // styled span's wording.
+            const hidden = new Map();
+            collectInvisibleMarks(stored, representable, hidden);
+            return adoptNodeKey(reapplyInvisibleMarks(rebuilt, hidden, representable), stored);
+        },
+        matches: (rebuilt, stored) => rebuilt.type === stored.type
+    });
+    const unrepresentable = previousNodes
+        .map((node, index) => ({ node, index }))
+        .filter(({ node }) => node.type === NODE.unknown);
+    if (unrepresentable.length === 0)
+        return { type: "doc", content: merged };
+    const survivors = new Set(merged.filter((n) => n.type === NODE.unknown).map(nodeKey).filter(Boolean));
+    const content = [...merged];
+    for (const { node, index } of unrepresentable) {
+        const key = nodeKey(node);
+        if (key !== undefined && survivors.has(key))
+            continue;
+        content.splice(Math.min(index, content.length), 0, node);
+    }
+    return { type: "doc", content };
+}