@portone/docx-editor 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,164 @@
 # @portone/docx-editor
 
+## 0.5.0
+
+### Minor Changes
+
+- [#105](https://github.com/portone-io/docx-editor/pull/105) [`efe7dbf`](https://github.com/portone-io/docx-editor/commit/efe7dbf6f2cb260ee912dbaed4c518c11b3527b7) Thanks [@Deea222](https://github.com/Deea222)! - Keep markup the editor cannot model where it stood, instead of standing the paragraph around it down.
+  
+  Opening a document used to walk a handful of element names and give up on the rest, and giving up
+  travelled outward until a whole paragraph became an "Unsupported content" placeholder. A word
+  processor writes a `w:lastRenderedPageBreak` on every page it lays out, so a real document opened
+  with one locked paragraph per page.
+  
+  Every level of the document now has a preservation rule of its own. A run child stays inside its
+  run, a paragraph child beside the runs, a block stays a block, and only a marker or a wrapper
+  standing between the rows or the cells of a table - where there is no node to keep it in - still
+  stands the table down. What is left shows as a small box naming the element it stands for, or as
+  nothing where the file drew nothing, and the paragraph around it stays editable.
+  
+  - A field code and its drawn result, a tracked insertion or deletion, a symbol, a positional tab
+    and a content control the editor could not take apart are visible where they stand.
+  - Bookmarks, permission ranges, the markers of a moved passage and the pieces of a field cannot be
+    removed by an edit; a tracked-change container, a simple field and a symbol can be selected and
+    deleted whole.
+  - `documentFidelity` and the `notes` of `importDocx` now report `preserved-run-content`, and no
+    longer report `paragraph-demoted` for a document being opened.
+  - New node `rawRunContent`, and `rawInline` gains the attrs `element`, `display`, `text` and
+    `guarded`. A plugin reading the document model sees both.
+  - A footnote body, a comment body and a header now read a `w:cr` and a `w:noBreakHyphen` the way
+    the document body does.
+
+- [#106](https://github.com/portone-io/docx-editor/pull/106) [`f2871cd`](https://github.com/portone-io/docx-editor/commit/f2871cd5535780c10574906c9dceb2b3ecc4715c) Thanks [@Deea222](https://github.com/Deea222)! - The comment composer keeps the text it was opened over while the document is edited elsewhere, and closes when that text is deleted or the mode turns read-only. The comment is written on that text rather than on whatever is selected when the writer submits.
+  
+  Opening the composer no longer scrolls the document back to its first page.
+  
+  `addComment` and `canAddComment` take an optional `{ from, to }` range as their last argument, which a composer of your own can hold across edits the same way; the current selection is still used when none is given.
+
+- [#116](https://github.com/portone-io/docx-editor/pull/116) [`4d9964d`](https://github.com/portone-io/docx-editor/commit/4d9964d59ce66ce52dac06b86968b8ee20dc4f2d) Thanks [@Deea222](https://github.com/Deea222)! - Comment bodies keep their formatting when edited, and `setCommentBody` accepts a formatted body.
+  
+  **Breaking:** the `commentReference` node loses its `text`, `commentXml` and `imported` attrs and
+  the `noteReference` node loses its `text` attr, together with the `data-comment-text`,
+  `data-comment-xml`, `data-comment-imported` and `data-note-text` attributes that carried them into
+  the DOM. A plugin that matched any of those reads what a comment or a note says through
+  `documentComments` and `documentNotes` instead, which answer as they always did.
+  
+  **Breaking:** `DocumentComment`, `DocumentCommentReply` and `DocumentNote` declare every field
+  `readonly`. They are the editor's own records, worked out once per edit and handed out rather than
+  copied, so a caller that was writing into one copies it first.
+  
+  A side story - a comment's body, a footnote's - is now read the way the document body is: the same
+  block readers, the same verbatim slices, one document of the editor's own schema per story. It
+  stands on the document node under `doc.attrs.stories`, so an edit to it rides a transaction and
+  lands in the history, and everything the edit did not touch is written back as the bytes it arrived
+  as. Editing a comment used to flatten its body to plain text and rewrite it as one run, which lost
+  its bold, its paragraph style and its second paragraph.
+  
+  `setCommentBody(id, body)` is a new command on `./commands`. It takes a `doc` node of `docxSchema`,
+  which is what a composer of your own builds a formatted body as; `updateComment(id, text)` stays
+  what it was for a body that is only text.
+  
+  Dropping those attrs is what the story replaces them with: what a comment or a note says is no
+  longer written on the node marking where it stands, so nothing has to keep the two in step, a copy
+  of the node no longer carries the body along with it, and neither reaches the clipboard.
+
+- [#108](https://github.com/portone-io/docx-editor/pull/108) [`d783e24`](https://github.com/portone-io/docx-editor/commit/d783e2485eaf6bbbacc3498202019ab053f4e7da) Thanks [@Deea222](https://github.com/Deea222)! - Keep a table whose markers stand between its rows or its cells, and stand every block the editor
+  cannot model as one kind of placeholder.
+  
+  **Breaking:** the `docxRaw` and `bookmarkBlock` node types no longer exist. Both were placeholders
+  for a block nobody could read, differing only in where the block stood and whether anything of it
+  was drawn, and `rawBlock` is now the one node for all of them. A plugin that matched either name
+  matches `rawBlock` instead and reads `display` (`"chip"` for a placeholder box, `"hidden"` for a
+  marker that draws nothing) and `guarded` to tell them apart. The class names
+  `docx-editor-bookmark-block`, `docx-editor-raw-xml` and `docx-editor-table` are gone with them;
+  every placeholder now draws as `docx-editor-raw-block`.
+  
+  - A bookmark spanning a table column stands under the row rather than inside a cell, and used to
+    cost the whole table its structure. Such a table now opens as a table, and the marker goes back
+    exactly where it stood. A marker following a cell that only continues a vertical merge is the
+    remaining exception, since that cell is created fresh on export.
+  - `documentFidelity` and the `notes` of `importDocx` no longer report `table-demoted` for a table
+    whose only unread markup is a marker.
+  - A placeholder can now be moved between the body and a table cell and still export.
+  - `table` and `tableRow` gain a `leadingXml` attr, `tableRow` and `tableCell` a `trailingXml` attr:
+    the markers each carries between its children.
+  
+  Table markers remain protected against deletion, duplication and reordering, including markers
+  whose ranges cross into a cell paragraph. Export checks read those fragments in document order.
+
+### Patch Changes
+
+- [#109](https://github.com/portone-io/docx-editor/pull/109) [`05e9431`](https://github.com/portone-io/docx-editor/commit/05e9431c5ba773fa9f751860cbf34760b191d91a) Thanks [@Deea222](https://github.com/Deea222)! - Cache comment and note lists between document edits. Public readers continue to return independent comment, reply, and note records, so changes to their results cannot alter the editor's cached data.
+
+- [#118](https://github.com/portone-io/docx-editor/pull/118) [`7de8870`](https://github.com/portone-io/docx-editor/commit/7de8870596bf4b311ab4b9fe4f19fb1291d37dbb) Thanks [@Deea222](https://github.com/Deea222)! - Every section now previews the headers and footers it names. A document whose second section
+  selects a header of its own used to draw the first section's on every page, because only the first
+  section's references were ever resolved.
+  
+  A header and a footer body is read the way the document body is: the same block readers, the same
+  verbatim slices, one story per part on the document node beside the comment and footnote stories.
+  The plain-text walker each of them used to have is gone, so a `w:cr`, a no-break hyphen and a field
+  read the same in a header as they do anywhere else, and a `PAGE` or `NUMPAGES` field is now found by
+  pairing the field characters it is written between rather than by scanning the text they surround.
+  
+  A header story the editor rewrote is written back into its own part, around the two ends that part
+  arrived with, and every part nobody rewrote is repacked as the bytes it came as. Editing a header is
+  not offered in the editor yet; this is the model and the export path underneath it.
+
+- [#115](https://github.com/portone-io/docx-editor/pull/115) [`9c5331d`](https://github.com/portone-io/docx-editor/commit/9c5331d543b3238f9859c60f5821e7b94fe52bba) Thanks [@Deea222](https://github.com/Deea222)! - Copying and pasting inside the same document now keeps what it was copied as: paragraph and character formatting, tabs, breaks, images, links, and whole tables, instead of the part an HTML reader could make out. Copying a grid of cells and pasting it over selected cells fills them in place. Comment markers, bookmarks, and note references are not copied, so cutting and pasting them back drops them. A pasted list whose numbering the document no longer defines is given a number that it does, keeping the bullets or numbers it was copied with; a list arriving from another document or application is renumbered by the reader that reads it. Content copied from another document, including a second editor on the same page, still comes in through that reader.
+
+- [#119](https://github.com/portone-io/docx-editor/pull/119) [`9b4b3fc`](https://github.com/portone-io/docx-editor/commit/9b4b3fc72ca51b89adf81063ca7fb2fb2c126e3f) Thanks [@Deea222](https://github.com/Deea222)! - Page boundaries and table widths now follow the paper of the section a block sits in. A document
+  whose second section is landscape used to be paginated as though the whole of it were the first
+  section's portrait paper, and a table put in that section was divided into the upright body width
+  and could not be widened past it.
+  
+  Each page is now as tall as the body its own section leaves, a section break starts a new page
+  unless it is marked continuous, and a table is fitted to the body width of the section it is
+  inserted or dragged in. An image pasted into a section is fitted to the height that section's paper
+  leaves. A page number still carries on across a section boundary rather than restarting where the
+  section asks.
+  
+  One sheet is still drawn at one width, the first section's, because nothing draws two paper widths
+  on one sheet. A landscape section is therefore paginated on landscape pages but drawn on the
+  sheet's width, and a table wider than the sheet's body is drawn shrunk to fit it while the document
+  keeps the width it was given. An even-page or odd-page start is preserved and exported untouched
+  but drawn as an ordinary new page.
+
+- [#110](https://github.com/portone-io/docx-editor/pull/110) [`272cd5c`](https://github.com/portone-io/docx-editor/commit/272cd5c55098ef4c62e352fc9837b3db807c1439) Thanks [@Deea222](https://github.com/Deea222)! - Keep a picture's extension lists intact when the image is resized.
+  
+  A picture written by Word often carries extension lists - the small records a word processor
+  attaches to a picture to remember things the format has no field for, such as which application
+  created it or what resolution to keep it at. Resizing such an image used to overwrite the name of
+  any empty record with the image's new size, which left the document with content Word reads as
+  invalid. Only the two sizes an image is drawn from are rewritten now, and every extension record
+  goes back out exactly as it came in.
+  
+  Size updates follow the picture’s own XML paths, so an extension’s nested transforms and size
+  records stay unchanged too. Size attributes retain their quoting and surrounding markup.
+
+- [#112](https://github.com/portone-io/docx-editor/pull/112) [`0327d4d`](https://github.com/portone-io/docx-editor/commit/0327d4dabe1de5814d440bf21f89cf5e5d1308b9) Thanks [@Deea222](https://github.com/Deea222)! - Give a document's sections a model of their own. Every `w:sectPr` is now read once - its paper and
+  margins, the header and footer stories it selects, whether the first page differs, and the page
+  number it starts at - instead of being read twice by two readers that looked for it differently.
+  
+  The section that closes the body rides on the document node as `sectPr` rather than in the
+  preserved tail. It is written straight back out, so an untouched document still exports byte for
+  byte, and a submission that rewrites the paper it is written on is refused by
+  `onlyCommentsChangedBy` as it was before.
+  
+  Pressing Enter in the last paragraph of a section continues to leave the break on the later half,
+  now on the same reading of `w:pPr` the rest of the package uses.
+
+- [#111](https://github.com/portone-io/docx-editor/pull/111) [`4357635`](https://github.com/portone-io/docx-editor/commit/435763591d456ec26f6466b5e69ecc226a20f743) Thanks [@Deea222](https://github.com/Deea222)! - Take a comment added to a document whose author shares your display name, instead of refusing the whole save.
+  A document an older Word wrote has no people part, so its comments name an author and nobody in particular.
+  Adding a comment under one of those names no longer records a person for it, which had handed the comments already there to whoever commented next, and `onlyCommentsChangedBy` now takes such a comment back rather than reading it as a forged author.
+  Every comment carrying a shared name, the new one included, stays everyone's to edit.
+  This also protects comments preserved outside the editable story: their authors are not assigned to a new commenter, and the verifier rejects a people record that would claim them.
+
+- [#113](https://github.com/portone-io/docx-editor/pull/113) [`e61185e`](https://github.com/portone-io/docx-editor/commit/e61185e645b06ce5091e59b08c5926fcaf71da16) Thanks [@Deea222](https://github.com/Deea222)! - Pasting text over selected table cells now fills every selected cell instead of only the first. Pasting the clipboard's plain text (Ctrl/Cmd+Shift+V) ignores accompanying HTML and images. Right-click Paste passes the clipboard's HTML and text through the same handlers as Ctrl/Cmd+V, including image loading and text fallback. Unreadable clipboard content leaves the selection intact when there is no usable text fallback.
+
+- [#117](https://github.com/portone-io/docx-editor/pull/117) [`faf4081`](https://github.com/portone-io/docx-editor/commit/faf4081b43cbfd111985b1aa124e0e90b4136fc9) Thanks [@Deea222](https://github.com/Deea222)! - A hyperlink whose text is already underlined, which is how a word processor writes one, is drawn with one line under it rather than two. The editor's own link line is still drawn under a link the document leaves unstyled.
+
+- [#106](https://github.com/portone-io/docx-editor/pull/106) [`f2871cd`](https://github.com/portone-io/docx-editor/commit/f2871cd5535780c10574906c9dceb2b3ecc4715c) Thanks [@Deea222](https://github.com/Deea222)! - Reject invalid comment range positions without throwing or adding a comment at a rounded position.
+
 ## 0.4.0
 
 ### Minor Changes

package/dist/DocxEditor.d.ts

@@ -12,7 +12,7 @@ import type { EditorView } from "prosemirror-view";
 import { type CSSProperties, type ReactNode } from "react";
 import { type DocxSource } from "./docx/importDocx";
 import { type ExportProblem } from "./docx/invariants";
-import { type CommentAuthor } from "./editor/commands/commentCommands";
+import type { CommentAuthor } from "./editor/commands/commentCommands";
 import { DocxImportError } from "./ooxml/errors";
 import type { EditableComments } from "./schema/protection";
 import type { FontFallbacks } from "./styles/fontStack";

package/dist/DocxEditor.js

@@ -9,22 +9,27 @@ import {
   useState
 } from "react";
 import { exportDocx } from "./docx/exportDocx.js";
+import { variantsFor } from "./docx/headersFooters.js";
 import { importDocx } from "./docx/importDocx.js";
 import { exportProblems } from "./docx/invariants.js";
-import {
-  documentComments
-} from "./editor/commands/commentCommands.js";
+import { sectionIn, sectionsOf } from "./docx/sections.js";
 import { activeLinkSpan } from "./editor/commands/linkCommands.js";
 import { createEditorView, editorStateForSession } from "./editor/createEditor.js";
+import {
+  closeCommentComposer,
+  isCommentComposerOpen
+} from "./editor/plugins/commentComposer.js";
+import { commentProjection } from "./editor/plugins/commentDecorations.js";
 import { setProtection } from "./editor/plugins/documentProtection.js";
 import { isLinkPanelOpen } from "./editor/plugins/linkPanel.js";
 import { tableMenuAnchor } from "./editor/plugins/tableContextMenu.js";
 import { textMenuAnchor } from "./editor/plugins/textContextMenu.js";
 import { DocxImportError } from "./ooxml/errors.js";
 import { PageGuides } from "./page/PageGuides.js";
-import { A4_PAGE_PIXELS, pagePixels } from "./page/pageLayout.js";
+import { A4_PAGE_PIXELS, pagePixels, sectionPixels } from "./page/pageLayout.js";
 import { usePageLayout } from "./page/usePageLayout.js";
 import { editingProtection, protectionOf } from "./schema/protectionState.js";
+import { storyNodeOf } from "./schema/stories.js";
 import { editorClassNames } from "./styles/classNames.js";
 import { CommentsPanel } from "./ui/CommentsPanel.js";
 import { LinkCard } from "./ui/LinkCard.js";
@@ -36,6 +41,9 @@ import { Toolbar } from "./ui/Toolbar.js";
 import { useFitWidthZoom } from "./ui/useFitWidthZoom.js";
 import { normalizeZoom } from "./ui/zoom.js";
 import { jsx, jsxs } from "react/jsx-runtime";
+function runOn(view, command) {
+  command(view.state, (transaction) => view.dispatch(transaction));
+}
 function affordancesOf(mode) {
   switch (mode.kind) {
     case "readOnly":
@@ -161,7 +169,6 @@ function DocxEditorSurface({
   );
   const viewRef = useRef(null);
   const [live, setLive] = useState(null);
-  const [commentComposerOpen, setCommentComposerOpen] = useState(false);
   const [commentsOpen, setCommentsOpen] = useState(false);
   const [uncontrolledZoom, setUncontrolledZoom] = useState(
     () => normalizeZoom(defaultZoom)
@@ -217,7 +224,6 @@ function DocxEditorSurface({
   const authorId = author?.id ?? null;
   const mounted = live !== null;
   useLayoutEffect(() => {
-    if (protection === "readOnly") setCommentComposerOpen(false);
     const view = viewRef.current;
     if (!view || !mounted) return;
     const held = protectionOf(view.state);
@@ -231,40 +237,58 @@ function DocxEditorSurface({
   useImperativeHandle(ref, () => {
     const view = viewRef.current;
     if (!view || opened?.status !== "opened") return null;
-    const session = opened.session;
+    const session2 = opened.session;
     return {
       view,
-      exportBytes: () => exportDocx(view.state.doc, session),
-      exportProblems: () => exportProblems(view.state.doc, session)
+      exportBytes: () => exportDocx(view.state.doc, session2),
+      exportProblems: () => exportProblems(view.state.doc, session2)
     };
   }, [opened]);
+  const doc = live?.state.doc ?? null;
+  const session = opened?.status === "opened" ? opened.session : null;
+  const sections = useMemo(
+    () => doc === null ? null : sectionsOf(doc),
+    [doc]
+  );
+  const sectionPapers = useMemo(
+    () => sections === null ? void 0 : sectionPixels(sections),
+    [sections]
+  );
   const overlay = usePageLayout({
     view: live?.view ?? null,
     layer: layerRef,
     enabled: showPageGuides,
     revision: live?.state.doc,
-    geometry: opened?.status === "opened" ? opened.session.geometry : void 0
+    sections: sectionPapers
   });
+  const headersFootersFor = useMemo(() => {
+    if (doc === null || session === null || sections === null) return void 0;
+    const shown = sections.map(
+      (section) => variantsFor(
+        section,
+        session.headerFooterStories,
+        (key) => storyNodeOf(doc, key)
+      )
+    );
+    return (face) => shown[sectionIn(sections, doc, face.pos).index] ?? null;
+  }, [doc, session, sections]);
   if (opened?.status === "rejected") {
     return renderImportError ? renderImportError(opened.error) : /* @__PURE__ */ jsx(ImportRejection, { error: opened.error });
   }
   const bodyOpen = live !== null && editingProtection(live.state) === "none";
-  const commentsOpenToWrite = live !== null && editingProtection(live.state) !== "readOnly";
   const textAnchor = live ? textMenuAnchor(live.state) : null;
   const tableAnchor = live && !textAnchor ? tableMenuAnchor(live.state) : null;
   const linkAtCursor = live && !live.view.composing && !isLinkPanelOpen(live.state) ? activeLinkSpan(live.state) : null;
-  const comments = live?.state === void 0 ? [] : documentComments(live.state);
+  const comments = live?.state === void 0 ? [] : commentProjection.read(live.state).comments;
   const hasUnresolvedComments = comments.some((comment) => !comment.resolved);
-  const effectiveComposerOpen = commentComposerOpen && commentsOpenToWrite;
-  const showComments = live !== null && (commentsOpen || effectiveComposerOpen || hasUnresolvedComments);
+  const composerOpen = live !== null && isCommentComposerOpen(live.state);
+  const showComments = live !== null && (commentsOpen || composerOpen || hasUnresolvedComments);
   const commentsPanel = live && showComments && /* @__PURE__ */ jsx(
     CommentsPanel,
     {
       view: live.view,
       state: live.state,
-      composerOpen: effectiveComposerOpen,
       author,
-      closeComposer: () => setCommentComposerOpen(false),
       scrollContainer: rootRef.current,
       allCommentsOpen: commentsOpen
     }
@@ -284,10 +308,8 @@ function DocxEditorSurface({
             presets,
             commentsOpen,
             onToggleComments: () => {
-              setCommentsOpen((open) => {
-                if (open) setCommentComposerOpen(false);
-                return !open;
-              });
+              if (commentsOpen) runOn(live.view, closeCommentComposer);
+              setCommentsOpen(!commentsOpen);
             },
             zoom: selectedZoom,
             onZoomChange: changeZoom
@@ -323,7 +345,7 @@ function DocxEditorSurface({
                         PageGuides,
                         {
                           overlay,
-                          headersFooters: opened?.status === "opened" ? opened.session.headersFooters : void 0
+                          headersFootersFor
                         }
                       ),
                       live && opened?.status === "opened" && /* @__PURE__ */ jsx(NotesPanel, { state: live.state, pageWidth: page.pageWidth })
@@ -352,10 +374,7 @@ function DocxEditorSurface({
             view: live.view,
             state: live.state,
             anchor: textAnchor,
-            allowLocking: locking,
-            onAddComment: () => {
-              setCommentComposerOpen(true);
-            }
+            allowLocking: locking
           }
         ),
         live && tableAnchor && /* @__PURE__ */ jsx(

package/dist/docx/cloning.js

@@ -1,7 +1,7 @@
 // src/docx/cloning.ts
 import { attrsText, withoutAttrs } from "../ooxml/element.js";
-import { parseProps, renderProps, setChild } from "../ooxml/props.js";
 import { parseAttrs } from "../ooxml/tagScan.js";
+import { withoutSectionBreak } from "./sections.js";
 var carried = (value) => value;
 var defaulted = () => void 0;
 var PARAGRAPH_ID_ATTRS = ["paraId", "textId"];
@@ -13,13 +13,8 @@ function withoutParagraphIds(value) {
   if (kept.length === attrs.length) return value;
   return kept.length === 0 ? null : attrsText(kept);
 }
-function withoutSectionBreak(value) {
-  if (typeof value !== "string") return value;
-  const props = parseProps(value);
-  if (props === null) return value;
-  const without = setChild(props, "sectPr", null);
-  if (without.children.length === props.children.length) return value;
-  return renderProps(without) || null;
+function droppingSectionBreak(value) {
+  return typeof value === "string" ? withoutSectionBreak(value) : value;
 }
 var INHERITED_CELL_ATTRS = ["tcAttrs", "tcPr", "tcW", "format"];
 var INHERITED_ROW_ATTRS = ["trAttrs", "trPr", "format"];
@@ -48,7 +43,7 @@ var CLONE_POLICIES = {
       // A paragraph-level `w:sectPr` ends the section it stands in, so it belongs to whichever
       // paragraph ends up last in that section: the second half of a split, and no half of a copy,
       // which is lifted out of the section it was taken from.
-      pPr: (value, side) => side === "after" ? value : withoutSectionBreak(value),
+      pPr: (value, side) => side === "after" ? value : droppingSectionBreak(value),
       // What names the block this paragraph was opened from. Only the half still standing where
       // that block stood may go on claiming it; `docx/exportDocx` writes the original bytes back
       // for whatever claims one.

package/dist/docx/commentOnlyChange.d.ts

@@ -34,9 +34,11 @@ export type CommentOnlyVerdict = {
  * has to read as it did, comments aside. Those three parts are read entry by entry instead
  * (`./comments/policy`), since a comment edit is free to rewrite them and something has to say
  * what it may have written there. A comment carrying no recorded identity is everyone's to
- * edit here as it is in the editor (`schema/protection`), while a comment that appeared has to
- * carry this identity: a file can claim any author, and the editor's own hand in writing it is
- * not there to vouch for it. An identity already recorded is nobody's to rewrite.
+ * edit here as it is in the editor (`schema/protection`). A comment that appeared carries this
+ * identity, or none under a name an original comment already carried unattributed, including a
+ * preserved comment outside the editable story. A file can claim any author, so an addition under
+ * any other name must carry the requester's identity. An identity already recorded is nobody's
+ * to rewrite, and a new identity cannot claim an original unattributed comment.
  *
  * `editableComments: "all"` judges the file of an editor opened for a moderator, where every
  * comment was theirs to edit; an identity is nobody's to rewrite under either setting.

package/dist/docx/comments/grammar.d.ts

@@ -22,13 +22,38 @@ export declare const COMMENT_EX_ATTRIBUTES: ReadonlySet<string>;
  * everything it writes.
  */
 export declare function declarationWritten(attr: Attr): boolean;
+/**
+ * Whether this element and everything inside it declares only namespaces this package writes.
+ *
+ * A declaration decides what every name under it means, so a block rebinding a prefix says one
+ * thing to this reader and another to Word, and is a place to put bytes nothing looks at.
+ */
+export declare function declarationsWritten(el: Element): boolean;
 /**
  * Whether the element carries no attribute outside this set, and declares no namespace outside
  * what the writer declares.
  */
 export declare function attributesWithin(el: Element, allowed: ReadonlySet<string>): boolean;
-/** The body of a comment, as a paragraph of one run holding the text and the breaks in it */
-export declare function renderCommentBody(text: string, paraId: string | null): string;
+/**
+ * Whether the element holds elements and nothing else.
+ *
+ * The writer puts no whitespace, comment or stray text between the pieces of a body, so an entry
+ * carrying any is one it did not write, and a reading that passed over them would leave a place to
+ * put bytes nothing looks at.
+ */
+export declare function holdsElementsOnly(el: Element): boolean;
+/** XML layout whitespace, which is the one text carrying no payload wherever it stands */
+export declare function isLayoutText(node: Node): boolean;
+/**
+ * Whether the element holds elements and the whitespace a producer laid them out over.
+ *
+ * A block is sliced with the whitespace standing ahead of it (`docx/scan`), so the writer hands a
+ * block it left untouched back with the layout it arrived in, and an entry from a part written
+ * over several lines carries that layout between its blocks. Whitespace is the only text this
+ * passes over: a comment, a processing instruction or a stretch of real text is a place to put
+ * bytes nothing looks at, and none of them is anything the writer puts out.
+ */
+export declare function holdsElementsAndLayout(el: Element): boolean;
 /**
  * The paragraph a thread key belongs on, which is the last one of the body.
  *
@@ -61,20 +86,12 @@ export declare function arrivedEntries(partXml: string | null): ReadonlyMap<stri
  * declares it on its root along with the compatibility markup that goes with it (`./writing`).
  */
 export declare function withThreadKey(commentXml: string, paraId: string, arrived: Element | null): string;
-/**
- * The text of a comment written in that shape, and null for an entry holding anything else: a
- * field, a second run, markup a producer wrapped it in, an attribute this editor does not write.
- *
- * An entry that arrived and was not edited is compared as it stands rather than read here, so
- * saying no to a shape this editor would not have written turns down only a rewrite.
- */
 /** Whether this editor's writer could have put out this thread state */
 export declare function wellFormedCommentExtension(entry: Element): boolean;
 /** Whether this editor's writer could have put out this recorded identity */
 export declare function wellFormedPerson(entry: Element): boolean;
 /** The identity a recorded person stands for, and null for an entry recording none */
 export declare function recordedIdentity(person: Element): string | null;
-export declare function readStrictCommentBody(comment: Element): string | null;
 /** The thread state of one comment, as this editor writes it into the extended part */
 export declare function renderCommentExtension(comment: CommentReferenceData | CommentReplyData): string;
 /**

package/dist/docx/comments/grammar.js

@@ -1,14 +1,9 @@
 // src/docx/comments/grammar.ts
-import {
-  attrsText,
-  elementXml,
-  xmlnsAttr
-} from "../../ooxml/element.js";
-import { NAMESPACES, qualify, wName } from "../../ooxml/names.js";
+import { attrsText, elementXml } from "../../ooxml/element.js";
+import { NAMESPACES, qualify } from "../../ooxml/names.js";
 import {
   attributeByLocalName,
   elementChildren,
-  escapeXml,
   parseXml,
   W_NS
 } from "../../ooxml/xml.js";
@@ -16,7 +11,6 @@ import { COMMENT_AUTHOR_PROVIDER, W14_NS, W15_NS } from "./constants.js";
 var ELEMENT_NODE = 1;
 var TEXT_NODE = 3;
 var XMLNS_NS = "http://www.w3.org/2000/xmlns/";
-var XML_NS = "http://www.w3.org/XML/1998/namespace";
 var nameKey = (namespace, localName) => `${namespace ?? ""} ${localName}`;
 var COMMENT_ATTRIBUTES = /* @__PURE__ */ new Set([
   nameKey(W_NS, "id"),
@@ -29,12 +23,6 @@ var COMMENT_EX_ATTRIBUTES = /* @__PURE__ */ new Set([
   nameKey(W15_NS, "paraIdParent"),
   nameKey(W15_NS, "done")
 ]);
-var PARAGRAPH_ATTRIBUTES = /* @__PURE__ */ new Set([
-  nameKey(W14_NS, "paraId")
-]);
-var TEXT_ATTRIBUTES = /* @__PURE__ */ new Set([
-  nameKey(XML_NS, "space")
-]);
 var PERSON_ATTRIBUTES = /* @__PURE__ */ new Set([
   nameKey(W15_NS, "author")
 ]);
@@ -42,7 +30,6 @@ var PRESENCE_ATTRIBUTES = /* @__PURE__ */ new Set([
   nameKey(W15_NS, "providerId"),
   nameKey(W15_NS, "userId")
 ]);
-var NO_ATTRIBUTES = /* @__PURE__ */ new Set();
 var THREAD_KEY = /^[0-9A-Fa-f]{8}$/;
 function threadKeyOrNone(el, localName) {
   const value = attributeByLocalName(el, localName);
@@ -57,6 +44,11 @@ function declarationWritten(attr) {
   if (!attr.name.startsWith("xmlns:")) return false;
   return WRITTEN_NAMESPACES.get(attr.name.slice("xmlns:".length)) === attr.value;
 }
+function declarationsWritten(el) {
+  return Array.from(el.attributes).every(
+    (attr) => !attr.name.startsWith("xmlns") || declarationWritten(attr)
+  ) && Array.from(el.children).every(declarationsWritten);
+}
 function attributesWithin(el, allowed) {
   return Array.from(el.attributes).every(
     (attr) => attr.namespaceURI === XMLNS_NS ? declarationWritten(attr) : allowed.has(nameKey(attr.namespaceURI, attr.localName))
@@ -70,22 +62,13 @@ function holdsElementsOnly(el) {
     (node) => node.nodeType === ELEMENT_NODE
   );
 }
-function holdsTextOnly(el) {
-  return Array.from(el.childNodes).every((node) => node.nodeType === TEXT_NODE);
-}
-function renderCommentBody(text, paraId) {
-  const lines = text.split("\n");
-  const pieces = [];
-  lines.forEach((line, index) => {
-    if (index > 0) pieces.push(elementXml(wName("br"), []));
-    if (line.length > 0 || lines.length === 1) {
-      pieces.push(
-        elementXml(wName("t"), [["xml:space", "preserve"]], [escapeXml(line)])
-      );
-    }
-  });
-  const key = paraId === null ? [] : [xmlnsAttr("w14"), [qualify("w14", "paraId"), paraId]];
-  return elementXml(wName("p"), key, [elementXml(wName("r"), [], pieces)]);
+function isLayoutText(node) {
+  return node.nodeType === TEXT_NODE && /^[ \t\r\n]*$/.test(node.nodeValue ?? "");
+}
+function holdsElementsAndLayout(el) {
+  return Array.from(el.childNodes).every(
+    (node) => node.nodeType === ELEMENT_NODE || isLayoutText(node)
+  );
 }
 var PARAGRAPH_OR_SKIPPED = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<([^\s<>/:="']+:)?p(?=[\s/>])[^>]*>/g;
 function lastBodyParagraph(comment) {
@@ -132,25 +115,6 @@ function withThreadKey(commentXml, paraId, arrived) {
   const keyed = opening[0].slice(0, selfClosing ? -2 : -1) + ` ${attrsText([[qualify("w14", "paraId"), paraId]])}` + (selfClosing ? "/>" : ">");
   return commentXml.slice(0, opening.index) + keyed + commentXml.slice(opening.index + opening[0].length);
 }
-function readRunText(run) {
-  if (!holdsElementsOnly(run)) return null;
-  const pieces = [];
-  for (const child of Array.from(run.children)) {
-    if (isNamed(child, W_NS, "br")) {
-      if (!attributesWithin(child, NO_ATTRIBUTES) || child.childNodes.length > 0) {
-        return null;
-      }
-      pieces.push("\n");
-      continue;
-    }
-    if (!isNamed(child, W_NS, "t")) return null;
-    if (!attributesWithin(child, TEXT_ATTRIBUTES) || child.getAttributeNS(XML_NS, "space") !== "preserve" || !holdsTextOnly(child)) {
-      return null;
-    }
-    pieces.push(child.textContent ?? "");
-  }
-  return pieces.join("");
-}
 function wellFormedCommentExtension(entry) {
   return attributesWithin(entry, COMMENT_EX_ATTRIBUTES) && entry.childNodes.length === 0 && threadKeyOrNone(entry, "paraId") && threadKeyOrNone(entry, "paraIdParent") && // The writer says a thread is settled or open, and nothing else `ST_OnOff` would take
   ["0", "1", null].includes(attributeByLocalName(entry, "done"));
@@ -167,21 +131,6 @@ function recordedIdentity(person) {
   const [presence] = Array.from(person.children);
   return presence === void 0 ? null : attributeByLocalName(presence, "userId");
 }
-function readStrictCommentBody(comment) {
-  if (!holdsElementsOnly(comment)) return null;
-  const paragraphs = Array.from(comment.children);
-  if (paragraphs.length !== 1) return null;
-  const [paragraph] = paragraphs;
-  if (!isNamed(paragraph, W_NS, "p")) return null;
-  if (!attributesWithin(paragraph, PARAGRAPH_ATTRIBUTES)) return null;
-  if (!holdsElementsOnly(paragraph)) return null;
-  const runs = Array.from(paragraph.children);
-  if (runs.length !== 1) return null;
-  const [run] = runs;
-  if (!isNamed(run, W_NS, "r")) return null;
-  if (!attributesWithin(run, NO_ATTRIBUTES)) return null;
-  return readRunText(run);
-}
 function renderCommentExtension(comment) {
   if (comment.extensionXml !== null) return comment.extensionXml;
   const parent = "parentParaId" in comment ? [[qualify("w15", "paraIdParent"), comment.parentParaId]] : [];
@@ -211,10 +160,12 @@ export {
   arrivedEntries,
   attributesWithin,
   declarationWritten,
+  declarationsWritten,
+  holdsElementsAndLayout,
+  holdsElementsOnly,
+  isLayoutText,
   lastBodyParagraph,
-  readStrictCommentBody,
   recordedIdentity,
-  renderCommentBody,
   renderCommentExtension,
   renderPerson,
   wellFormedCommentExtension,

package/dist/docx/comments/model.d.ts

@@ -3,15 +3,17 @@
  */
 import type { Node as PMNode } from "prosemirror-model";
 import type { ImportedComments } from "./reading";
+/**
+ * A comment as the reference node in the story carries it: who wrote it, where its thread state
+ * hangs, and the replies under it. What it says is not here - a body is a story of its own, held
+ * on the document node under `comment:<id>` (`docx/story`).
+ */
 export interface CommentReferenceData {
     id: string;
     author: string | null;
     authorId: string | null;
     initials: string | null;
     date: string | null;
-    text: string;
-    commentXml: string | null;
-    imported: boolean;
     paraId: string;
     resolved: boolean;
     extensionXml: string | null;
@@ -24,9 +26,6 @@ export interface CommentReplyData {
     authorId: string | null;
     initials: string | null;
     date: string | null;
-    text: string;
-    commentXml: string | null;
-    imported: boolean;
     paraId: string;
     parentParaId: string;
     extensionXml: string | null;