canopycms 0.6.0 → 0.7.0

package/dist/submission-attribution.js

@@ -1,11 +1,18 @@
 import { personName } from './auth/person-name.js';
 import { getErrorMessage } from './utils/error.js';
 import { canopyLogWarn } from './utils/logger.js';
+import { editorDeepLink } from './editor-url.js';
 const MAX_NAME_LENGTH = 80;
 const MAX_ID_LENGTH = 128;
 const MAX_EMAIL_LENGTH = 254;
 const MAX_DESCRIPTION_LENGTH = 10_000;
-const MAX_LISTED_ENTRIES = 100;
+/** How many changed paths the PR body lists. */
+export const MAX_LISTED_ENTRIES = 100;
+/**
+ * The section's own text, its comment block aside. With the block's MAX_COMMENTS_LENGTH the
+ * section stays under 45,200, leaving over 20,000 of GitHub's 65,536 to the text a human adds.
+ */
+const MAX_SECTION_LENGTH = 30_000;
 /**
  * The PR body region canopycms owns. On update only the text between these
  * markers is replaced, so anything a human wrote around it survives.
@@ -14,6 +21,14 @@ const MAX_LISTED_ENTRIES = 100;
 export const PR_SECTION_START = '<!-- canopycms:submission:start -->';
 /** @internal Exported for tests. */
 export const PR_SECTION_END = '<!-- canopycms:submission:end -->';
+/**
+ * The editor-comment summary, nested in the section so a comment change can replace it alone:
+ * the rest of the section is built from the submit (mergeCommentsBlock).
+ * @internal Exported for tests.
+ */
+export const PR_COMMENTS_START = '<!-- canopycms:comments:start -->';
+/** @internal Exported for tests. */
+export const PR_COMMENTS_END = '<!-- canopycms:comments:end -->';
 // Cc (C0/C1 controls incl. newlines), Cf (zero-width and bidi overrides), Zl/Zp
 // (Unicode line/paragraph separators) can forge a trailer line or hide text; Cs
 // (a lone surrogate) reaches git as U+FFFD, since Node encodes it so.
@@ -189,13 +204,99 @@ function codeSpan(value) {
 function neutralizeComments(text) {
     return text.replace(/<!--/g, '&lt;!--').replace(/--!?>/g, '--&gt;');
 }
+/**
+ * A URL safe as a Markdown link destination: the characters that could end the destination,
+ * open a title or escape are percent-encoded, which a server reads as the same address.
+ * Brackets are legal in a destination and are an IPv6 host's syntax, so they stay.
+ */
+function markdownHref(href) {
+    return href.replace(/[()<>\\\s'"`]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`);
+}
+const PR_COMMENTS_NOTICE = 'Comments on this pull request do not reach the CanopyCMS editor, so the author will not see them.';
 function editorLabel(editor) {
     return editor.name
         ? `${codeSpan(editor.name)} (${codeSpan(editor.userId)})`
         : codeSpan(editor.userId);
 }
-/** The canopycms-owned PR body section, including its start and end markers. */
-export function buildPrSection(input) {
+/** A Markdown-safe editor link for `branch` (and an entry), or undefined without a URL or branch. */
+function editorLinker(branch, editorUrl) {
+    return (entryPath) => branch && editorUrl ? markdownHref(editorDeepLink(editorUrl, branch, entryPath)) : undefined;
+}
+const MAX_LISTED_THREADS = 50;
+const MAX_EXCERPT_LENGTH = 80;
+const MAX_COMMENTS_LENGTH = 15_000;
+const LINE_BREAK = /\r\n?|\n|\u2028|\u2029/;
+/**
+ * An entry path from comments.json, which is read without validation, if it is a plain
+ * logical path: the editor's `entry` param matches it exactly, so anything else links nowhere.
+ */
+function threadEntryPath(raw) {
+    if (typeof raw !== 'string' || cleanPath(raw) !== raw)
+        return undefined;
+    return raw.split('/').every((s) => s !== '' && s !== '.' && s !== '..') ? raw : undefined;
+}
+/**
+ * One line per unresolved thread: where it is, the first line of its first comment and a link.
+ * The excerpt is a code span of cleaned text, so a comment cannot mention, reference an issue
+ * (or close one), autolink or carry HTML; it is visible to everyone who can read the PR.
+ */
+function threadLine(thread, link) {
+    const entryPath = threadEntryPath(thread.entryPath);
+    const field = thread.type === 'field' && typeof thread.canopyPath === 'string'
+        ? cleanText(thread.canopyPath, MAX_NAME_LENGTH)
+        : undefined;
+    const where = entryPath
+        ? `${codeSpan(entryPath)}${field ? ` › ${codeSpan(field)}` : ''}`
+        : thread.type === 'branch'
+            ? 'Branch'
+            : 'An entry';
+    const [first] = Array.isArray(thread.comments) ? thread.comments : [];
+    const text = typeof first?.text === 'string' ? first.text.split(LINE_BREAK)[0] : undefined;
+    const excerpt = cleanText(text, MAX_EXCERPT_LENGTH);
+    const href = entryPath ? link(entryPath) : thread.type === 'branch' ? link() : undefined;
+    return [
+        `- ${where}`,
+        excerpt ? ` — ${codeSpan(excerpt)}` : '',
+        href ? ` ([open in editor](${href}))` : '',
+    ].join('');
+}
+/**
+ * The editor-comment summary between its markers: the unresolved threads, oldest first, or
+ * that every thread is resolved, or that there are none, or that they could not be read.
+ * comments.json is read without validation, so an entry that is not an object is skipped.
+ */
+export function buildCommentsBlock(threads, branch, editorUrl) {
+    if (threads === null) {
+        return `${PR_COMMENTS_START}\nThe editor comments could not be read.\n${PR_COMMENTS_END}`;
+    }
+    const open = threads
+        .filter((t) => typeof t === 'object' && t !== null && !t.resolved)
+        .sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt)));
+    let body;
+    if (open.length > 0) {
+        const listed = open.slice(0, MAX_LISTED_THREADS);
+        const linker = editorLinker(branch, editorUrl);
+        let lines = listed.map((t) => threadLine(t, linker));
+        // The PR body's 65,536-character limit is shared with the rest of the section: past the
+        // budget the links go, then lines from the end.
+        if (lines.join('\n').length > MAX_COMMENTS_LENGTH) {
+            lines = listed.map((t) => threadLine(t, () => undefined));
+        }
+        let shown = lines.length;
+        while (shown > 0 && lines.slice(0, shown).join('\n').length > MAX_COMMENTS_LENGTH)
+            shown--;
+        lines = lines.slice(0, shown);
+        if (open.length > shown)
+            lines.push(`- …and ${open.length - shown} more`);
+        const noun = open.length === 1 ? 'comment thread' : 'comment threads';
+        body = `**${open.length} unresolved editor ${noun}**\n\n${lines.join('\n')}`;
+    }
+    else {
+        body = threads.length > 0 ? 'All editor comments resolved.' : 'No editor comments.';
+    }
+    return `${PR_COMMENTS_START}\n${body}\n${PR_COMMENTS_END}`;
+}
+function renderPrSection(input, layout, commentsBlock) {
     const parts = [];
     const [submitter] = input.submitter ? cleanEditors([input.submitter]) : [];
     parts.push(submitter
@@ -205,23 +306,77 @@ export function buildPrSection(input) {
     if (others.length > 0) {
         parts.push(`Also edited by: ${others.map(editorLabel).join(', ')}`);
     }
-    const paths = [...new Set(input.changedPaths)]
-        .map(cleanPath)
-        .filter((p) => p !== undefined);
+    const link = editorLinker(input.branch, input.editorUrl);
+    const branchLink = link();
+    if (branchLink)
+        parts.push(`[Open this branch in the editor](${branchLink})`);
+    parts.push(`> [!IMPORTANT]\n> ${PR_COMMENTS_NOTICE} ` +
+        (branchLink
+            ? `Comment in the [editor](${branchLink}) instead.`
+            : 'Comment in the editor instead.'));
+    const paths = changedPathsOf(input);
     if (paths.length > 0) {
-        const listed = paths.slice(0, MAX_LISTED_ENTRIES).map((p) => `- ${codeSpan(p)}`);
-        if (paths.length > MAX_LISTED_ENTRIES) {
-            listed.push(`- …and ${paths.length - MAX_LISTED_ENTRIES} more`);
-        }
+        const listed = paths.slice(0, layout.listed).map(({ raw, clean }) => {
+            const entryPath = layout.entryLinks ? input.entryPaths?.get(raw) : undefined;
+            const entryLink = entryPath === undefined ? undefined : link(entryPath);
+            return entryLink
+                ? `- ${codeSpan(clean)} ([open in editor](${entryLink}))`
+                : `- ${codeSpan(clean)}`;
+        });
+        if (paths.length > layout.listed)
+            listed.push(`- …and ${paths.length - layout.listed} more`);
         parts.push(`**Changed entries (${paths.length})**\n\n${listed.join('\n')}`);
     }
+    parts.push(commentsBlock);
     // Last, so an unclosed fence or `<details>` in free Markdown cannot swallow
     // the attribution above it.
-    const description = input.description?.trim();
-    if (description)
-        parts.push(neutralizeComments(truncate(description, MAX_DESCRIPTION_LENGTH)));
+    if (layout.description)
+        parts.push(layout.description);
     return `${PR_SECTION_START}\n${parts.join('\n\n')}\n${PR_SECTION_END}`;
 }
+function changedPathsOf(input) {
+    return [...new Set(input.changedPaths)]
+        .map((raw) => ({ raw, clean: cleanPath(raw) }))
+        .filter((p) => p.clean !== undefined);
+}
+/** `text` cut to at most `max` UTF-16 units, never inside a surrogate pair. */
+function truncateUnits(text, max) {
+    if (text.length <= max)
+        return text;
+    if (max < 1)
+        return '';
+    const cut = text.slice(0, max - 1);
+    return `${/[\uD800-\uDBFF]$/.test(cut) ? cut.slice(0, -1) : cut}…`;
+}
+/**
+ * The canopycms-owned PR body section, including its start and end markers. GitHub refuses a
+ * body over 65,536 characters and the rest of the body is a human's, so a section whose text
+ * apart from the comment block is over MAX_SECTION_LENGTH loses its entry links, then the
+ * description's end, then entries from the end of the list. The attribution lines themselves
+ * are never cut. The comment block, rendered now or re-rendered later, has MAX_COMMENTS_LENGTH.
+ */
+export function buildPrSection(input) {
+    const raw = input.description?.trim();
+    const description = raw ? neutralizeComments(truncate(raw, MAX_DESCRIPTION_LENGTH)) : '';
+    const block = buildCommentsBlock(input.threads === undefined ? [] : input.threads, input.branch, input.editorUrl);
+    const size = (l) => renderPrSection(input, l, block).length - block.length;
+    const layout = { entryLinks: true, listed: MAX_LISTED_ENTRIES, description };
+    const fits = (l) => size(l) <= MAX_SECTION_LENGTH;
+    if (fits(layout))
+        return renderPrSection(input, layout, block);
+    layout.entryLinks = false;
+    if (fits(layout))
+        return renderPrSection(input, layout, block);
+    // The description's separator is two newlines.
+    const room = MAX_SECTION_LENGTH - size({ ...layout, description: '' }) - 2;
+    if (room > 0) {
+        return renderPrSection(input, { ...layout, description: truncateUnits(description, room) }, block);
+    }
+    layout.description = '';
+    while (layout.listed > 0 && !fits(layout))
+        layout.listed = Math.max(0, layout.listed - 10);
+    return renderPrSection(input, layout, block);
+}
 /**
  * `existing` with its canopycms section replaced by `section`, keeping every
  * character outside the markers. The section is the first end marker together
@@ -231,13 +386,37 @@ export function buildPrSection(input) {
  */
 export function mergePrSection(existing, section) {
     const body = existing ?? '';
+    const found = findPrSection(body);
+    if (found) {
+        return body.slice(0, found.start) + section + body.slice(found.end + PR_SECTION_END.length);
+    }
+    const human = body.split(PR_SECTION_START).join('').split(PR_SECTION_END).join('').trimEnd();
+    return human ? `${human}\n\n${section}` : section;
+}
+/** The index pair of the canopycms section in `body` (see mergePrSection), or undefined. */
+function findPrSection(body) {
     for (let end = body.indexOf(PR_SECTION_END); end >= 0;) {
         const start = body.lastIndexOf(PR_SECTION_START, end - PR_SECTION_START.length);
-        if (start >= 0) {
-            return body.slice(0, start) + section + body.slice(end + PR_SECTION_END.length);
-        }
+        if (start >= 0)
+            return { start, end };
         end = body.indexOf(PR_SECTION_END, end + PR_SECTION_END.length);
     }
-    const human = body.split(PR_SECTION_START).join('').split(PR_SECTION_END).join('').trimEnd();
-    return human ? `${human}\n\n${section}` : section;
+    return undefined;
+}
+/**
+ * `existing` with the comment block inside its canopycms section replaced by `block`, or
+ * undefined when the section or its block is missing (a PR body written before the block
+ * existed, or edited by hand): the next submit writes both. Only markers inside the section
+ * count, and the description in it cannot spell one (neutralizeComments).
+ */
+export function mergeCommentsBlock(existing, block) {
+    const body = existing ?? '';
+    const section = findPrSection(body);
+    if (!section)
+        return undefined;
+    const start = body.indexOf(PR_COMMENTS_START, section.start);
+    const end = start < 0 ? -1 : body.indexOf(PR_COMMENTS_END, start);
+    if (start < 0 || end < 0 || end > section.end)
+        return undefined;
+    return body.slice(0, start) + block + body.slice(end + PR_COMMENTS_END.length);
 }

package/dist/task-queue/cms-task-queue.d.ts

@@ -5,7 +5,7 @@
  */
 import type { Task, TaskQueueLogger } from './types.js';
 /** Actions the EC2 worker can execute on behalf of Lambda. */
-export type TaskAction = 'push-and-create-pr' | 'push-and-update-pr' | 'push-and-create-or-update-pr' | 'convert-to-draft' | 'close-pr' | 'delete-remote-branch' | 'push-branch';
+export type TaskAction = 'push-and-create-pr' | 'push-and-update-pr' | 'push-and-create-or-update-pr' | 'convert-to-draft' | 'close-pr' | 'delete-remote-branch' | 'push-branch' | 'sync-pr-comments';
 /** A task with a CMS-specific action. */
 export type WorkerTask = Task & {
     action: TaskAction;

package/dist/types.d.ts

@@ -45,6 +45,12 @@ export interface BranchMetadata {
      * leaves no PR number. Absent on branches the CMS never pushed there.
      */
     pushedToGitHubAt?: string;
+    /**
+     * The latest editor URL a submit took from its request (editor-url.ts); a submit that took
+     * none, or used config.editorUrl, leaves it as it was. A comment change re-renders the PR's
+     * comment summary with config.editorUrl or this, so a commenter never supplies the links.
+     */
+    editorUrl?: string;
     /** Sync status for async GitHub operations (used when Lambda has no internet) */
     syncStatus?: SyncStatus;
     /** Whether any rebase of this branch kept its version of an entry base also changed */

package/dist/utils/content-serialize.js

@@ -519,11 +519,12 @@ function writesFrontmatter(data) {
     return Object.values(data).some((value) => value !== undefined);
 }
 /**
- * The body to write: `body`'s content in `existingRaw`'s text wherever they agree
- * (`preserveMarkdownSource`), opening with the blank line the frontmatter is followed by on disk.
- * gray-matter leaves that blank line in the body, and the editor's body does not carry it, so it
- * is restored here even when the splice falls back. A body under frontmatter the file did not
- * have, or under frontmatter with no body yet, gets one blank line, Prettier's style.
+ * The body to write: `body`'s content in `existingRaw`'s text wherever they agree, and in the
+ * export style elsewhere (`preserveMarkdownSource`), opening with the blank line the frontmatter
+ * is followed by on disk. gray-matter leaves that blank line in the body, and the editor's body
+ * does not carry it, so it is restored here even when the splice falls back. A body under
+ * frontmatter the file did not have, or under frontmatter with no body yet, gets one blank line,
+ * Prettier's style.
  *
  * With no frontmatter written, the body opens the file: it loses its leading blank lines, except
  * the one newline that stops a body starting with `---` (after any BOM, which gray-matter skips)
@@ -531,7 +532,7 @@ function writesFrontmatter(data) {
  */
 function bodyToWrite(body, data, format, existingRaw) {
     const priorBody = existingRaw === undefined ? undefined : extractBody(existingRaw);
-    const spliced = priorBody === undefined ? body : preserveMarkdownSource(priorBody, body, format);
+    const spliced = preserveMarkdownSource(priorBody, body, format);
     if (!writesFrontmatter(data)) {
         const flush = spliced.replace(/^(?:\r?\n)+/, '');
         return /^\uFEFF?---/.test(flush) ? `\n${flush}` : flush;

package/dist/utils/markdown-body-splice.d.ts

@@ -1,10 +1,13 @@
 /**
  * Source-preserving save for md/mdx bodies.
  *
- * The editor sends a body re-serialised from its own document model, so every block comes back
- * in the serialiser's style (bullet and emphasis markers, rule style, escapes, no blank line
- * after the frontmatter) whether or not the user touched it. This writes the on-disk text of
- * every block whose MEANING the edit left alone, and the editor's text only where it changed:
+ * The rich editor sends a body re-serialised from its own document model, so every block comes
+ * back in the serialiser's style (bullet and emphasis markers, rule style, escapes, no blank line
+ * after the frontmatter) whether or not the user touched it; the source editor sends whatever was
+ * typed. This writes the on-disk text of every block whose MEANING the edit left alone, and the
+ * edit's text only where it changed. The edit's changed blocks are first restyled in place to
+ * `MARKDOWN_EXPORT_OPTIONS`'s markers (`markdown-restyle.ts`), so a changed block is written in
+ * that one style whichever editor mode produced it:
  *
  * - Top-level blocks are aligned by a position-free canonical form of their mdast, so a block
  *   matches only when it parses to the same tree. A matched block is written from disk.
@@ -15,10 +18,10 @@
  *   stands for the original it is paired with) is the disk's; elsewhere it is the editor's,
  *   re-indented into the original's nesting and written in its line endings.
  *
- * The result is kept only if it parses to exactly the tree the editor's body parses to. A splice
- * that fails that check is retried without descending into lists, and failing that the editor's
- * body is written as sent: the worst case is the editor's own serialisation, never different
- * content.
+ * The result is kept only if it parses to exactly the tree the editor's body parses to, and so is
+ * the restyled edit. A splice that fails that check is retried without descending into lists,
+ * then both again from the edit as sent; failing all four, the restyled edit is written whole,
+ * or the edit as sent when it did not read back: the worst case is never different content.
  */
 export type MarkdownBodyFormat = 'md' | 'mdx';
 /**
@@ -34,6 +37,8 @@ export declare function markdownBlocks(text: string, format: MarkdownBodyFormat)
 }[] | undefined;
 /**
  * The body to write for an edit from `original` (on disk) to `updated` (the editor's body):
- * `updated`'s content, in `original`'s text wherever the two agree. See the module header.
+ * `updated`'s content, in `original`'s text wherever the two agree. With no `original` to keep
+ * text from (a new file, or a body on disk that does not parse), the whole edit is restyled.
+ * See the module header.
  */
-export declare function preserveMarkdownSource(original: string, updated: string, format: MarkdownBodyFormat): string;
+export declare function preserveMarkdownSource(original: string | undefined, updated: string, format: MarkdownBodyFormat): string;

package/dist/utils/markdown-body-splice.js

@@ -1,10 +1,13 @@
 /**
  * Source-preserving save for md/mdx bodies.
  *
- * The editor sends a body re-serialised from its own document model, so every block comes back
- * in the serialiser's style (bullet and emphasis markers, rule style, escapes, no blank line
- * after the frontmatter) whether or not the user touched it. This writes the on-disk text of
- * every block whose MEANING the edit left alone, and the editor's text only where it changed:
+ * The rich editor sends a body re-serialised from its own document model, so every block comes
+ * back in the serialiser's style (bullet and emphasis markers, rule style, escapes, no blank line
+ * after the frontmatter) whether or not the user touched it; the source editor sends whatever was
+ * typed. This writes the on-disk text of every block whose MEANING the edit left alone, and the
+ * edit's text only where it changed. The edit's changed blocks are first restyled in place to
+ * `MARKDOWN_EXPORT_OPTIONS`'s markers (`markdown-restyle.ts`), so a changed block is written in
+ * that one style whichever editor mode produced it:
  *
  * - Top-level blocks are aligned by a position-free canonical form of their mdast, so a block
  *   matches only when it parses to the same tree. A matched block is written from disk.
@@ -15,10 +18,10 @@
  *   stands for the original it is paired with) is the disk's; elsewhere it is the editor's,
  *   re-indented into the original's nesting and written in its line endings.
  *
- * The result is kept only if it parses to exactly the tree the editor's body parses to. A splice
- * that fails that check is retried without descending into lists, and failing that the editor's
- * body is written as sent: the worst case is the editor's own serialisation, never different
- * content.
+ * The result is kept only if it parses to exactly the tree the editor's body parses to, and so is
+ * the restyled edit. A splice that fails that check is retried without descending into lists,
+ * then both again from the edit as sent; failing all four, the restyled edit is written whole,
+ * or the edit as sent when it did not read back: the worst case is never different content.
  */
 import { fromMarkdown } from 'mdast-util-from-markdown';
 import { gfmFromMarkdown } from 'mdast-util-gfm';
@@ -27,6 +30,7 @@ import { gfm } from 'micromark-extension-gfm';
 import { mdxjs } from 'micromark-extension-mdxjs';
 import { createDebugLogger } from './debug.js';
 import { getErrorMessage } from './error.js';
+import { orderedNumber, restyleMarkdown } from './markdown-restyle.js';
 import { withSourceLineEndings } from './yaml-source-splice.js';
 const log = createDebugLogger({ prefix: 'MarkdownBodySplice' });
 /** Above this many LCS cells the middle of a sequence is treated as one changed run. */
@@ -352,10 +356,10 @@ function gapBetween(text, a, b) {
 }
 /**
  * Rewrites an output item's marker to the original list's: its bullet character, or for an
- * ordered list its delimiter and numbering scheme (all one number when the original's first two
- * items share one, else counting up from its start). Undefined when the original's markers
- * cannot be read, or when renumbering would change the width of a multi-line item, whose
- * continuation lines are aligned to the old width.
+ * ordered list its delimiter, numbered as Prettier numbers the original (`orderedNumber`) and
+ * zero-padded as it is. Undefined when the original's markers cannot be read, or when
+ * renumbering would change the width of a multi-line item, whose continuation lines are aligned
+ * to the old width.
  */
 function listMarkers(text, items, ordered) {
     const firstStart = startOf(items[0]);
@@ -371,17 +375,15 @@ function listMarkers(text, items, ordered) {
     const first = numberAt(firstStart);
     if (first === null)
         return undefined;
-    const start = Number(first[1]);
     const delimiter = first[2] ?? '.';
     // `01.`, `02.`: zero-padded to the first marker's width.
     const padTo = first[1]?.startsWith('0') ? first[1].length : 0;
-    const second = items.length > 1 ? numberAt(startOf(items[1])) : null;
-    const step = second !== null && Number(second[1]) === start ? 0 : 1;
+    const typed = items.map((item) => Number(numberAt(startOf(item))?.[1]));
     return (itemText, index) => {
         const current = /^\d{1,9}[.)]/.exec(itemText);
         if (current === null)
             return undefined;
-        const marker = `${String(start + step * index).padStart(padTo, '0')}${delimiter}`;
+        const marker = `${String(orderedNumber(typed, index)).padStart(padTo, '0')}${delimiter}`;
         if (marker.length !== current[0].length && itemText.includes('\n'))
             return undefined;
         return marker + itemText.slice(current[0].length);
@@ -389,7 +391,9 @@ function listMarkers(text, items, ordered) {
 }
 /**
  * The body to write for an edit from `original` (on disk) to `updated` (the editor's body):
- * `updated`'s content, in `original`'s text wherever the two agree. See the module header.
+ * `updated`'s content, in `original`'s text wherever the two agree. With no `original` to keep
+ * text from (a new file, or a body on disk that does not parse), the whole edit is restyled.
+ * See the module header.
  */
 export function preserveMarkdownSource(original, updated, format) {
     if (original === updated)
@@ -403,20 +407,59 @@ export function preserveMarkdownSource(original, updated, format) {
         return updated;
     }
 }
+/**
+ * The indexes of the edit's top-level blocks the splice writes from disk: those the alignment
+ * matches, and those that moved (an unmatched original of the same meaning, each used once).
+ */
+function diskBlocks(oNodes, nNodes) {
+    const oKeys = oNodes.map(canonical);
+    const nKeys = nNodes.map(canonical);
+    const pairs = matchSequences(oKeys, nKeys);
+    const fromDisk = new Set(pairs.map(([, ni]) => ni));
+    const matched = new Set(pairs.map(([oi]) => oi));
+    const unmatched = new Map();
+    oKeys.forEach((key, index) => {
+        if (!matched.has(index))
+            unmatched.set(key, (unmatched.get(key) ?? 0) + 1);
+    });
+    nKeys.forEach((key, index) => {
+        const left = unmatched.get(key) ?? 0;
+        if (fromDisk.has(index) || left === 0)
+            return;
+        unmatched.set(key, left - 1);
+        fromDisk.add(index);
+    });
+    return fromDisk;
+}
 function splice(original, updated, format) {
-    const before = parse(original, format);
+    const before = original === undefined ? undefined : parse(original, format);
     const after = parse(updated, format);
-    if (before === undefined || after === undefined)
+    if (after === undefined)
         return undefined;
     const target = canonical(after);
-    for (const deep of [true, false]) {
-        const candidate = new Splicer(original, updated, deep).body(before, after);
-        if (candidate === undefined)
-            continue;
-        const reparsed = parse(candidate, format);
-        if (reparsed !== undefined && canonical(reparsed) === target)
-            return candidate;
-        log.debug('markdown-body-splice', 'splice does not read back as the edit', { deep });
+    const fromDisk = diskBlocks(before?.children ?? [], after.children);
+    const restyled = restyleMarkdown(updated, after, (index) => fromDisk.has(index), (text) => {
+        const tree = parse(text, format);
+        return tree !== undefined && canonical(tree) === target ? tree : undefined;
+    });
+    if (original === undefined || before === undefined)
+        return restyled?.text;
+    const asSent = { text: updated, tree: after };
+    // The rich editor already writes this style, so its restyled edit is usually the edit as sent.
+    const edits = restyled === undefined || restyled.text === updated ? [asSent] : [restyled, asSent];
+    for (const edit of edits) {
+        for (const deep of [true, false]) {
+            const candidate = new Splicer(original, edit.text, deep).body(before, edit.tree);
+            if (candidate === undefined)
+                continue;
+            const reparsed = parse(candidate, format);
+            if (reparsed !== undefined && canonical(reparsed) === target)
+                return candidate;
+            log.debug('markdown-body-splice', 'splice does not read back as the edit', {
+                deep,
+                restyled: edit !== asSent,
+            });
+        }
     }
-    return undefined;
+    return restyled?.text;
 }

package/dist/utils/markdown-export-options.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The style every markdown body is written in: Prettier's markers. The rich editor exports with
+ * it, and a save restyles edited blocks to it whichever editor mode produced them
+ * (`markdown-restyle.ts`). MDXEditor's prop replaces its defaults, so `listItemIndent` is
+ * restated.
+ */
+export declare const MARKDOWN_EXPORT_OPTIONS: {
+    readonly listItemIndent: "one";
+    readonly bullet: "-";
+    readonly emphasis: "_";
+    readonly strong: "*";
+    readonly rule: "-";
+};

package/dist/utils/markdown-export-options.js

@@ -0,0 +1,13 @@
+/**
+ * The style every markdown body is written in: Prettier's markers. The rich editor exports with
+ * it, and a save restyles edited blocks to it whichever editor mode produced them
+ * (`markdown-restyle.ts`). MDXEditor's prop replaces its defaults, so `listItemIndent` is
+ * restated.
+ */
+export const MARKDOWN_EXPORT_OPTIONS = {
+    listItemIndent: 'one',
+    bullet: '-',
+    emphasis: '_',
+    strong: '*',
+    rule: '-',
+};

package/dist/utils/markdown-restyle.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Restyles markdown to `MARKDOWN_EXPORT_OPTIONS`'s markers IN PLACE: each normalisation Prettier
+ * makes is an edit to the marker bytes of the text as typed, so every other byte (URLs, titles,
+ * entities, escapes, inline code, JSX) is the edit's own by construction. A serialiser cannot
+ * promise that: it writes every value from the tree, and a tree-equal rewrite of a URL or an
+ * entity is invisible to a tree check.
+ *
+ * The normalisations, each as Prettier 3 writes them:
+ * - emphasis `_`, or `*` where `_` could not delimit it (beside a word character) and inside
+ *   other emphasis; strong `**`. Emphasis after a literal `_` in its block keeps `*`, because
+ *   Prettier misreads `a_b _x_` (`underscoreStarts`);
+ * - bullets `-`, and ordered delimiters `.`, alternating with `*` / `)` for a list that follows
+ *   another; ordered numbering by `orderedNumber`, where that keeps each marker's width;
+ * - `---` rules (`***` inside a list, see `ruleIn`), `# x` headings for one-line setext and ATX
+ *   headings, backtick fences for `~~~`;
+ * - one blank line between blocks, none between link definitions; between list items and an
+ *   item's blocks, several blank lines become one, which keeps a list's looseness;
+ * - no trailing space before a soft line ending; an escaped `_` between two letters or digits
+ *   unescaped, except in links and in blocks holding `$` or `[[`;
+ * - tables padded to their columns, when every cell is printable ASCII.
+ *
+ * Each top-level block's edits are kept only if the text they are part of reads back as the
+ * edit (`readsBack`): all at once, then halves, within a parse budget, so a block that cannot be
+ * restyled leaves the others restyled.
+ */
+/** The parts of an mdast node the restyle and the splice read. */
+export interface MdNode {
+    readonly type: string;
+    readonly children?: readonly MdNode[];
+    readonly position?: {
+        readonly start: {
+            readonly offset?: number;
+        };
+        readonly end: {
+            readonly offset?: number;
+        };
+    };
+    readonly ordered?: boolean | null;
+    readonly checked?: boolean | null;
+    readonly depth?: number;
+    readonly value?: string;
+    readonly align?: readonly (string | null)[] | null;
+}
+/**
+ * The number Prettier writes for item `index` of an ordered list typed with `numbers`: the first
+ * keeps its number; the rest count up from it, or are all 1 when the list is typed that way
+ * (its second number is 1, and so is its third when it starts at 0).
+ */
+export declare function orderedNumber(numbers: readonly number[], index: number): number;
+/**
+ * `source` (whose parse is `tree`) restyled in place, every top-level block for which `fixed`
+ * is false; undefined when no restyle reads back. `readsBack` returns the parse of a candidate
+ * when it means what `source` means.
+ */
+export declare function restyleMarkdown<T extends MdNode>(source: string, tree: MdNode, fixed: (index: number) => boolean, readsBack: (text: string) => T | undefined): {
+    text: string;
+    tree: T;
+} | undefined;