@portone/docx-editor 0.5.1 → 0.6.1

package/dist/editor/createEditor.js

@@ -6,6 +6,7 @@ import { keymap } from "prosemirror-keymap";
 import { EditorState } from "prosemirror-state";
 import { tableEditing } from "prosemirror-tables";
 import { EditorView } from "prosemirror-view";
+import { withNoteLabels } from "../docx/notes/numbering.js";
 import { pageDecorations } from "../page/pageDecorations.js";
 import { pageGeometryStyle, pagePixels } from "../page/pageLayout.js";
 import { editsShut } from "../schema/protectionState.js";
@@ -26,6 +27,8 @@ import { imageFiles } from "./imageFiles.js";
 import { columnResize } from "./plugins/columnResize.js";
 import { commentComposer } from "./plugins/commentComposer.js";
 import { commentDecorations } from "./plugins/commentDecorations.js";
+import { commentRestoration } from "./plugins/commentRestoration.js";
+import { compositionSelection } from "./plugins/compositionSelection.js";
 import {
   displayDerivation,
   withDerivedDisplay
@@ -36,6 +39,9 @@ import { docxKeymap, historyKeys } from "./plugins/keymap.js";
 import { linkPanel } from "./plugins/linkPanel.js";
 import { listInputRules } from "./plugins/listInputRules.js";
 import { lockedContent } from "./plugins/lockedContent.js";
+import { noteLifecycle } from "./plugins/noteLifecycle.js";
+import { noteNavigation } from "./plugins/noteNavigation.js";
+import { noteNumbering } from "./plugins/noteNumbering.js";
 import { numberingMarkers } from "./plugins/numberingDecorations.js";
 import { rowResize } from "./plugins/rowResize.js";
 import { tabCaret } from "./plugins/tabCaret.js";
@@ -57,8 +63,13 @@ function createEditorState(doc, options = {}) {
   } = options;
   return EditorState.create({
     // The values the document arrived with were worked out against whatever opened it; the
-    // state's are worked out against its own snapshot, tables' shared lines included
-    doc: withDerivedDisplay(doc, document),
+    // state's are worked out against its own snapshot, tables' shared lines and note labels
+    // included
+    doc: withNoteLabels(
+      withDerivedDisplay(doc, document),
+      document.noteNumbering,
+      document.specialNotes
+    ),
     plugins: [
       // Consumer plugins lead the array. ProseMirror walks the plugins in order and takes the
       // first answer for a keypress, a paste, a drop or any other DOM event, so this is the
@@ -69,9 +80,12 @@ function createEditorState(doc, options = {}) {
       editorDocument(document),
       // Refuses every edit no guard in `schema/guards` lets through, whoever asked for it. It is
       // not optional: a document that locked a part of itself stays locked in every consumer, and
-      // the preserved bookmark markers and note references stay where the file put them.
+      // the preserved bookmark markers stay where the file put them.
       lockedContent(),
       documentProtection({ protection, author, editableComments }),
+      // Ahead of the keys and the clipboard: the plugin registered first sees a DOM event first,
+      // and this one hands every composition on
+      compositionSelection(),
       history(),
       keymap(docxKeymap),
       historyKeys(),
@@ -96,8 +110,16 @@ function createEditorState(doc, options = {}) {
       // The list beside the page, the lookup the comment commands ask, and these ranges are the
       // one walk this plugin holds (`plugins/commentDecorations`)
       commentDecorations(),
+      // A comment outlives the text it was written for: an edit that sweeps its reference away has
+      // it put back where the deletion left, detached from the page (`plugins/commentRestoration`)
+      commentRestoration(),
+      // A note goes with the last reference to it, and a copied reference gets a note of its own.
+      // It stands ahead of the numbering, which then labels what it settled
+      noteLifecycle(),
+      noteNumbering(),
       // What the notes under the page are, worked out from the document the same way
       noteProjection.plugin,
+      noteNavigation(),
       // Adjacent text tabs still need separate DOM ranges for layout and pointer selection.
       tabDecorations(),
       tabPointer(),

package/dist/editor/documentStyles.d.ts

@@ -36,6 +36,9 @@ export declare function documentGeometry(state: EditorState): PageGeometry;
  * section is where the document says it is, and the snapshot holds the first section's paper
  * alone. Reading it walks every block, so a caller drawing a whole document asks once and looks
  * its positions up (`page/pageLayout`) rather than calling this per block.
+ *
+ * A side story writes down no section, so its own blocks say nothing about the paper: what it is
+ * drawn on is the paper of the place it is called from, which its snapshot carries.
  */
 export declare function sectionGeometryAt(state: EditorState, pos: number): PageGeometry;
 /** The document-wide interval between automatic tab stops, in points. */

package/dist/editor/documentStyles.js

@@ -19,7 +19,8 @@ function documentGeometry(state) {
   return documentOf(state).geometry;
 }
 function sectionGeometryAt(state, pos) {
-  return sectionAt(state.doc, pos).props.geometry;
+  const document = documentOf(state);
+  return document.sideStory ? document.geometry : sectionAt(state.doc, pos).props.geometry;
 }
 function documentDefaultTabStopPt(state) {
   return documentOf(state).defaultTabStopPt;

package/dist/editor/editorDocument.d.ts

@@ -10,9 +10,11 @@
 import type { Node as PMNode } from "prosemirror-model";
 import { type EditorState, Plugin } from "prosemirror-state";
 import { type FormattingContext, type ParagraphStyleOption } from "../docx/formatting";
+import { type NoteNumbering } from "../docx/notes/reading";
 import { type PageGeometry } from "../docx/pageGeometry";
 import type { SessionStore } from "../docx/session";
 import type { DocumentDefaults } from "../model/format";
+import { type StoryKey } from "../schema/stories";
 /** The document-level values one editing state is built on */
 export interface EditorDocument {
     /** The document these values were read from. Null for a state built without one */
@@ -30,12 +32,26 @@ export interface EditorDocument {
     readonly canStartNewList: boolean;
     /** The paper the document is written on, which decides the width a new table is fitted to */
     readonly geometry: PageGeometry;
+    /**
+     * Whether these values stand for a side story rather than for the body, whose paper is then the
+     * geometry above rather than anything the story's own blocks say (`editor/documentStyles`).
+     */
+    readonly sideStory: boolean;
     /** The distance between automatic tab stops when no custom stop applies */
     readonly defaultTabStopPt: number;
     /** Every id already present in the opened Comments part, including unreferenced entries */
     readonly reservedCommentIds: ReadonlySet<string>;
     /** Every paragraph id present in the opened comment parts, including orphan extension entries */
     readonly reservedCommentParaIds: ReadonlySet<string>;
+    /** How the document counts its footnotes and endnotes, which the note labels are spelled in */
+    readonly noteNumbering: NoteNumbering;
+    /** The note entries that lay out the page rather than number a note: separators and the continuation notice */
+    readonly specialNotes: ReadonlySet<StoryKey>;
+    /**
+     * Every entry of an editable kind the opened notes parts hold, separators and entries no
+     * reference names included, which a new note may not take the id of
+     */
+    readonly reservedNoteKeys: ReadonlySet<StoryKey>;
 }
 /** What a state built without an opened document answers: the same as nothing being written down */
 export declare const NO_DOCUMENT: EditorDocument;
@@ -51,6 +67,14 @@ export declare function documentOf(state: EditorState): EditorDocument;
  * both leave the same object behind, allowing the sheet's style to be cached against that identity.
  */
 export declare function editorDocument(document: EditorDocument): Plugin<EditorDocument>;
+/**
+ * The snapshot one side story is edited against: the document's own values, with the two a story
+ * answers differently.
+ *
+ * A story has nowhere of its own to write a list definition, and the paper its text wraps at is
+ * the paper of the place it is called from rather than anything the story says.
+ */
+export declare function storyDocument(document: EditorDocument, geometry: PageGeometry): EditorDocument;
 /** The comment ids the opened document already spent, which a new comment may not take */
 export declare function reservedCommentIds(state: EditorState): ReadonlySet<string>;
 /** The paragraph ids the opened comment parts already spent */

package/dist/editor/editorDocument.js

@@ -6,9 +6,17 @@ import {
   NO_FORMATTING
 } from "../docx/formatting.js";
 import { canDefineNewList } from "../docx/newLists.js";
+import {
+  DEFAULT_NOTE_NUMBERING
+} from "../docx/notes/reading.js";
 import { A4_PORTRAIT } from "../docx/pageGeometry.js";
 import { NEW_LISTS_ATTR, newListsOf } from "../numbering/listRegistry.js";
+import {
+  EDITABLE_NOTE_KINDS,
+  STORIES_ATTR
+} from "../schema/stories.js";
 var NO_IDS = /* @__PURE__ */ new Set();
+var NO_NOTE_KEYS = /* @__PURE__ */ new Set();
 var NO_PARAGRAPH_STYLES = [];
 var NO_DOCUMENT = {
   session: null,
@@ -17,9 +25,13 @@ var NO_DOCUMENT = {
   paragraphStyles: NO_PARAGRAPH_STYLES,
   canStartNewList: true,
   geometry: A4_PORTRAIT,
+  sideStory: false,
   defaultTabStopPt: DEFAULT_TAB_STOP_PT,
   reservedCommentIds: NO_IDS,
-  reservedCommentParaIds: NO_IDS
+  reservedCommentParaIds: NO_IDS,
+  noteNumbering: DEFAULT_NOTE_NUMBERING,
+  specialNotes: NO_NOTE_KEYS,
+  reservedNoteKeys: NO_NOTE_KEYS
 };
 function reservedParaIds(session) {
   const paraIds = /* @__PURE__ */ new Set();
@@ -46,9 +58,17 @@ function editorDocumentOf(session, doc) {
     paragraphStyles: session.paragraphStyles,
     canStartNewList: canDefineNewList(session),
     geometry: session.geometry,
+    sideStory: false,
     defaultTabStopPt: session.defaultTabStopPt,
     reservedCommentIds: new Set(session.comments.byId.keys()),
-    reservedCommentParaIds: reservedParaIds(session)
+    reservedCommentParaIds: reservedParaIds(session),
+    noteNumbering: session.noteNumbering,
+    specialNotes: session.specialNotes,
+    reservedNoteKeys: new Set(
+      Array.from(session.stories.values()).flatMap(
+        (story) => EDITABLE_NOTE_KINDS.some((kind) => kind === story.kind) ? [story.key] : []
+      )
+    )
   };
 }
 var editorDocumentKey = new PluginKey("docxEditorDocument");
@@ -61,15 +81,24 @@ function derived(current, doc) {
     formatting: formattingWithNewLists(current.formatting, doc)
   } : editorDocumentOf(current.session, doc);
 }
+function onlyStoriesMoved(next, before) {
+  const names = Object.keys(next.attrs);
+  return next.attrs[STORIES_ATTR] !== before.attrs[STORIES_ATTR] && names.length === Object.keys(before.attrs).length && names.every(
+    (name) => name === STORIES_ATTR || next.attrs[name] === before.attrs[name]
+  );
+}
 function editorDocument(document) {
   return new Plugin({
     key: editorDocumentKey,
     state: {
       init: () => document,
-      apply: (tr, current, old) => tr.doc.attrs === old.doc.attrs ? current : derived(current, tr.doc)
+      apply: (tr, current, old) => tr.doc.attrs === old.doc.attrs || onlyStoriesMoved(tr.doc, old.doc) ? current : derived(current, tr.doc)
     }
   });
 }
+function storyDocument(document, geometry) {
+  return { ...document, sideStory: true, canStartNewList: false, geometry };
+}
 function reservedCommentIds(state) {
   return documentOf(state).reservedCommentIds;
 }
@@ -82,5 +111,6 @@ export {
   editorDocument,
   editorDocumentOf,
   reservedCommentIds,
-  reservedCommentParaIds
+  reservedCommentParaIds,
+  storyDocument
 };

package/dist/editor/notes/noteSurface.d.ts

@@ -0,0 +1,53 @@
+/**
+ * What a footnote or an endnote draws and does differently from any other story.
+ *
+ * A note's story opens with a mark of its own (`w:footnoteRef`, `w:endnoteRef`), which the file
+ * keeps as a preserved chip. Word draws that mark as the number the reference carries, so it is
+ * drawn here as that label in superscript, the way the reference in the body is.
+ *
+ * The rest is what the story view asks a kind of story for (`editor/stories`): the host every
+ * edit leaves through, and the extensions that give a note its chip, its key rule, the number it
+ * keeps through an edit, and what a paste into one may carry.
+ */
+import type { EditorView } from "prosemirror-view";
+import { type StoryKey } from "../../schema/stories";
+import { type SliceNormalizer } from "../clipboard/normalizers";
+import type { StoryNodeSpecs } from "../stories/storyMarkup";
+import { type StoryExtensions, type StoryHost } from "../stories/storyView";
+/** The node specs a note's story is drawn with, its own reference mark drawn as `labelOf` answers */
+export declare function noteNodeSpecs(labelOf: () => string): StoryNodeSpecs;
+/**
+ * Takes out of a paste what the notes part cannot be written with: an image, and a link.
+ *
+ * Either needs a relationship of the part it stands in, and the notes part writer writes none, so
+ * both would go out naming a relationship the file does not hold. A link or an image the file
+ * itself wrote inside a note stays; this is about what a paste would add.
+ */
+export declare const dropUnwritableContent: SliceNormalizer;
+/**
+ * Takes a note reference out of a paste: a note may not hold a note.
+ *
+ * The lifecycle, the numbering and the writer all walk the body alone, so a reference inside a
+ * story would call a note nothing numbers, counts or settles, and one copied from beside the note
+ * it was pasted into would have that note calling itself. The text it stood in stays, the way the
+ * other anchors leave theirs (`editor/clipboard/normalizers`).
+ */
+export declare const dropNoteReferences: SliceNormalizer;
+/**
+ * Puts the caret back just after the reference that calls this note and takes the body's focus,
+ * which is what leaves the note: Escape and a press on the note's own number both run it.
+ */
+export declare function returnToReference(main: EditorView, key: StoryKey): void;
+/**
+ * The host a note's editing view writes through, whichever kind of note stands under the key.
+ *
+ * Every edit leaves as that kind's own body command, so a lock around the reference and the
+ * editing protection judge a note edit where they judge a body edit, and the main document keeps
+ * the one history both share.
+ */
+export declare function noteHost(main: EditorView, activate: StoryHost["activate"]): StoryHost;
+/**
+ * What a note adds to the story view: its chip, the number it keeps first, its key rule, and what
+ * a paste may bring in
+ */
+export declare function noteExtensions(main: EditorView, key: StoryKey, labelOf: () => string): StoryExtensions;

package/dist/editor/notes/noteSurface.js

@@ -0,0 +1,246 @@
+// src/editor/notes/noteSurface.ts
+import { keymap } from "prosemirror-keymap";
+import {
+  DOMSerializer,
+  Mark
+} from "prosemirror-model";
+import { Plugin, TextSelection } from "prosemirror-state";
+import { NOTE_NUMBER_ELEMENTS } from "../../docx/notes/newNote.js";
+import { docxSchema } from "../../schema/index.js";
+import { editShut, transactionAllowed } from "../../schema/guards.js";
+import { editsShut } from "../../schema/protectionState.js";
+import { noteKeyOf } from "../../schema/stories.js";
+import { editorClassNames } from "../../styles/classNames.js";
+import {
+  detachAnchors,
+  dropSourceIdentity,
+  mapSliceNodes,
+  rederiveDisplay,
+  rekeyNumbering
+} from "../clipboard/normalizers.js";
+import { redo, undo } from "../commands/historyCommands.js";
+import { noteBodyCommand } from "../commands/noteCommands.js";
+import { onMac } from "../plugins/keymap.js";
+import { noteReferenceAt } from "../plugins/noteNavigation.js";
+import {
+  NO_CAPABILITY
+} from "../stories/storyView.js";
+function isOwnMark(node) {
+  const element = node.attrs.element;
+  return node.type === docxSchema.nodes.rawRunContent && typeof element === "string" && NOTE_NUMBER_ELEMENTS.includes(element);
+}
+function drawnBySchema(node) {
+  return docxSchema.nodes.rawRunContent.spec.toDOM?.(node) ?? ["span"];
+}
+function markSpec(node, labelOf) {
+  return isOwnMark(node) ? ["sup", { class: editorClassNames.noteMark }, labelOf()] : drawnBySchema(node);
+}
+function noteNodeSpecs(labelOf) {
+  return { rawRunContent: (node) => markSpec(node, labelOf) };
+}
+function noteMarkView(labelOf, back) {
+  return (node) => {
+    const { dom } = DOMSerializer.renderSpec(document, markSpec(node, labelOf));
+    if (isOwnMark(node) && dom instanceof HTMLElement) {
+      dom.addEventListener("mousedown", (event) => {
+        event.preventDefault();
+        back();
+      });
+    }
+    return { dom };
+  };
+}
+var dropUnwritableContent = (slice) => mapSliceNodes(slice, (node) => {
+  if (node.type === docxSchema.nodes.image) return null;
+  const marks = node.marks.filter(
+    (mark) => mark.type !== docxSchema.marks.link
+  );
+  return Mark.sameSet(marks, node.marks) ? node : node.mark(marks);
+});
+var dropNoteReferences = (slice, { move }) => move ? slice : mapSliceNodes(
+  slice,
+  (node) => node.type === docxSchema.nodes.noteReference ? null : node
+);
+var NOTE_TAKES = NO_CAPABILITY;
+var NOTE_NORMALIZERS = [
+  dropSourceIdentity,
+  detachAnchors,
+  dropNoteReferences,
+  dropUnwritableContent,
+  rekeyNumbering,
+  rederiveDisplay
+];
+function runOn(main, command) {
+  return command(main.state, (tr) => main.dispatch(tr), main);
+}
+function referenceOf(main, key) {
+  const note = noteKeyOf(key);
+  return note === null ? null : noteReferenceAt(main.state.doc, note.kind, note.id);
+}
+function returnToReference(main, key) {
+  const found = referenceOf(main, key);
+  if (found !== null) {
+    const after = found.pos + found.node.nodeSize;
+    main.dispatch(
+      main.state.tr.setSelection(TextSelection.near(main.state.doc.resolve(after))).scrollIntoView()
+    );
+  }
+  main.focus();
+}
+function leadingChipSize(story) {
+  const first = story.firstChild?.firstChild ?? null;
+  return first !== null && isOwnMark(first) ? first.nodeSize : 0;
+}
+function ownMarkIn(story) {
+  let found = null;
+  story.descendants((node, pos) => {
+    if (found === null && isOwnMark(node)) found = { pos, node };
+    return found === null;
+  });
+  return found;
+}
+function caretFloor(story) {
+  const held = ownMarkIn(story);
+  return held === null || held.pos !== markHome(story) ? null : held.pos + held.node.nodeSize;
+}
+function markHome(story) {
+  const type = docxSchema.nodes.rawRunContent;
+  let at = null;
+  story.descendants((node, pos) => {
+    if (at !== null) return false;
+    if (!node.isTextblock) return true;
+    if (node.type.contentMatch.matchType(type) !== null) at = pos + 1;
+    return false;
+  });
+  return at;
+}
+function pressesTowardsTheNumber() {
+  return [
+    "ArrowLeft",
+    "ArrowUp",
+    "Home",
+    "PageUp",
+    "Mod-ArrowLeft",
+    "Mod-ArrowUp",
+    "Mod-Home",
+    ...onMac() ? ["Ctrl-a"] : []
+  ];
+}
+function holdAtTheNumber(extend) {
+  return (state, dispatch) => {
+    const floor = caretFloor(state.doc);
+    const home = markHome(state.doc);
+    if (floor === null || home === null) return false;
+    const { selection } = state;
+    if (extend ? selection.head > home : selection.from > floor) return false;
+    if (dispatch && !extend) {
+      dispatch(state.tr.setSelection(TextSelection.create(state.doc, floor)));
+    }
+    return true;
+  };
+}
+function keysOffTheNumber() {
+  return Object.fromEntries(
+    pressesTowardsTheNumber().flatMap((press) => [
+      [press, holdAtTheNumber(false)],
+      [`Shift-${press}`, holdAtTheNumber(true)]
+    ])
+  );
+}
+function ownMarkFirst() {
+  return new Plugin({
+    appendTransaction(transactions, oldState, newState) {
+      const tr = newState.tr;
+      const home = markHome(newState.doc);
+      if (transactions.some((changed) => changed.docChanged) && home !== null) {
+        const held = ownMarkIn(newState.doc);
+        const lost = ownMarkIn(oldState.doc);
+        if (held === null) {
+          if (lost !== null) tr.insert(home, lost.node);
+        } else if (held.pos !== home) {
+          tr.delete(held.pos, held.pos + held.node.nodeSize).insert(
+            home,
+            held.node
+          );
+        }
+      }
+      const floor = caretFloor(tr.doc);
+      if (floor !== null && tr.selection.empty && tr.selection.from < floor) {
+        tr.setSelection(
+          TextSelection.create(tr.doc, Math.min(floor, tr.doc.content.size))
+        );
+      }
+      return tr.docChanged || tr.selectionSet ? tr : null;
+    }
+  });
+}
+function holdsNothing(story) {
+  const only = story.childCount === 1 ? story.firstChild : null;
+  return only !== null && only.type === docxSchema.nodes.paragraph && only.content.size === leadingChipSize(story);
+}
+function deleteEmptyNote(main, key) {
+  return (state, dispatch) => {
+    if (!state.selection.empty) return false;
+    if (!holdsNothing(state.doc)) return false;
+    const $at = state.selection.$from;
+    if ($at.index(0) !== 0 || $at.parentOffset > leadingChipSize(state.doc)) {
+      return false;
+    }
+    const found = referenceOf(main, key);
+    if (found === null) return false;
+    const tr = main.state.tr.delete(found.pos, found.pos + found.node.nodeSize);
+    if (!transactionAllowed(tr, main.state)) return false;
+    if (dispatch) {
+      main.dispatch(
+        tr.setSelection(TextSelection.near(tr.doc.resolve(found.pos))).scrollIntoView()
+      );
+      main.focus();
+    }
+    return true;
+  };
+}
+function noteHost(main, activate) {
+  return {
+    state: () => main.state,
+    write(key, story) {
+      const note = noteKeyOf(key);
+      return note !== null && runOn(main, noteBodyCommand(note.kind, note.id, story));
+    },
+    undo: () => runOn(main, undo),
+    redo: () => runOn(main, redo),
+    leave: (key) => returnToReference(main, key),
+    shut(key) {
+      if (editsShut(main.state)) return true;
+      const found = referenceOf(main, key);
+      if (found === null) return true;
+      return editShut(main.state, {
+        kind: "replace",
+        from: found.pos,
+        to: found.pos + found.node.nodeSize
+      });
+    },
+    activate
+  };
+}
+function noteExtensions(main, key, labelOf) {
+  return {
+    plugins: [
+      ownMarkFirst(),
+      keymap(keysOffTheNumber()),
+      keymap({ Backspace: deleteEmptyNote(main, key) })
+    ],
+    nodeViews: {
+      rawRunContent: noteMarkView(labelOf, () => returnToReference(main, key))
+    },
+    normalizers: NOTE_NORMALIZERS,
+    takes: NOTE_TAKES
+  };
+}
+export {
+  dropNoteReferences,
+  dropUnwritableContent,
+  noteExtensions,
+  noteHost,
+  noteNodeSpecs,
+  returnToReference
+};

package/dist/editor/plugins/commentDecorations.js

@@ -34,7 +34,7 @@ function commentsIn(doc) {
     const id = stringAttr(node.attrs.id) ?? "";
     const start = markers.starts.get(id);
     const end = markers.ends.get(id);
-    const hasRange = start !== void 0 && end !== void 0 && start < end;
+    const anchored = start !== void 0 && end !== void 0 && start < end;
     const point = start ?? end ?? pos;
     return {
       id,
@@ -43,9 +43,10 @@ function commentsIn(doc) {
       initials: stringAttr(node.attrs.initials),
       date: stringAttr(node.attrs.date),
       text: bodyText(doc, id),
-      from: hasRange ? start + 1 : point,
-      to: hasRange ? end : point,
+      from: anchored ? start + 1 : point,
+      to: anchored ? end : point,
       referencePos: pos,
+      anchored,
       resolved: node.attrs.resolved === true,
       replies: repliesAttr(node.attrs.replies).map((reply) => ({
         id: reply.id,
@@ -69,7 +70,7 @@ function deriveComments(doc) {
     byId,
     decorations: DecorationSet.create(
       doc,
-      comments.filter((comment) => comment.from < comment.to).map(
+      comments.filter((comment) => !comment.resolved && comment.from < comment.to).map(
         (comment) => Decoration.inline(comment.from, comment.to, {
           class: editorClassNames.commentRange,
           "data-comment-id": comment.id

package/dist/editor/plugins/commentRestoration.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Keeps a comment when the text it was written for goes away.
+ *
+ * Deleting commented text is an edit of the body, not a decision about the thread, so a body edit
+ * that takes a comment's nodes away has them put back at the spots the edit left: the thread stays
+ * anchored where one range marker survived, detached where both went (`DocumentComment.anchored`).
+ *
+ * The comment's story (`docx/story`) tells such an edit from `removeComment`: a body deletion does
+ * not reach the story, so a comment is put back while its story stands, which only `removeComment`
+ * takes away. The cost is that a reference the comments part held no body for is never put back.
+ *
+ * A restoration is an ordinary transaction the guards judge (`editor/plugins/lockedContent`): the
+ * nodes take the nearest spot left open, and a document leaving none loses the comment. A range
+ * marker with no home takes its surviving counterpart down, so no export carries half a range.
+ *
+ * A restoration needs no deferral around an open IME composition: the nodes go in beside the
+ * composed text rather than rewriting it (`e2e/hangulComposition.spec.ts`).
+ */
+import { Plugin } from "prosemirror-state";
+export declare function commentRestoration(): Plugin;