@portone/docx-editor 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # @portone/docx-editor
 
+## 0.2.1
+
+### Patch Changes
+
+- [#53](https://github.com/portone-io/docx-editor/pull/53) [`d264803`](https://github.com/portone-io/docx-editor/commit/d264803381c3272ae31e1af1faa7fd158b95a81f) Thanks [@Deea222](https://github.com/Deea222)! - Stop text copied out of the editor from carrying the document's private data.
+  
+  A copy was drawn the way the editor draws itself, so the HTML it left on the clipboard held the paragraph and run XML, the name and recorded identity of a comment's author, what the comment and its replies say, and the body of a footnote.
+  All of it landed in whatever application it was pasted into, and in `comment` mode a reader who may not change the body could take the body out this way.
+  A copy now carries only what a reader of it needs, and the paragraph style it names is the style's id rather than the whole `w:pPr`.
+  A link goes out as a link, so it can be followed where it lands and comes back as one when it is pasted here again.
+  
+  The plain text beside it says what was copied: a tab is a tab, a line break is a line, a page break is a form feed, and a table's cells stand apart by a tab and its rows by a line, so a table pasted into a spreadsheet arrives as a table.
+  A cell holding a line break is the exception, since the line inside it reads as the start of the next row.
+
+- [#50](https://github.com/portone-io/docx-editor/pull/50) [`41d82c5`](https://github.com/portone-io/docx-editor/commit/41d82c5bee74597baedd813c43c8dcfcdfe74fbf) Thanks [@Deea222](https://github.com/Deea222)! - Stop `onlyCommentsChangedBy` from excusing a part a submission relates as a comment part.
+  
+  The three comment parts are left out of the byte comparison, and which parts those were came from the submitted file's own relationships.
+  A file could relate a second comments, extended comments or people part at any part it liked and have that part go uncompared, so a rewritten styles part, a settings part pointing at a template off the package, replaced image bytes or forged document properties were all reported as a change to nothing but comments.
+  The parts left out are now the ones the reader opened, a comment part may be related once, one related for the first time has to be a part the submission brought with it, and a relationship part naming one id twice is turned down.
+  
+  A file that relates an extended comments part but carries no comments part now has that part read, so writing the first comment into it writes that part rather than a second one beside it.
+  Two extended parts related at once was a file whose settled threads a reader would lose, since only the first of them is read.
+  
+  This affects 0.2.0. A server that accepted files on this verdict should upgrade and run the check again over what it accepted, where such a file now answers `part-changed` naming the part, or `relationship-changed` naming the relationship part.
+
+- [#56](https://github.com/portone-io/docx-editor/pull/56) [`467f6f5`](https://github.com/portone-io/docx-editor/commit/467f6f5781dbf6eb6739dbf3369155c7287ee608) Thanks [@Deea222](https://github.com/Deea222)! - Commands and `canRunCommand` now report false where a bookmark marker or a note reference would be removed, instead of reporting true and changing nothing.
+  
+  A refusal over one of those markers also ends an open IME composition, the way a refusal over a locked control already did.
+
+- [#59](https://github.com/portone-io/docx-editor/pull/59) [`6d7b97f`](https://github.com/portone-io/docx-editor/commit/6d7b97fdb89e0aba7ac13057b503ec510a5550c1) Thanks [@Deea222](https://github.com/Deea222)! - Formatting XML is now written through shared primitives that consistently escape attribute values while preserving existing formatting behavior.
+
+- [#58](https://github.com/portone-io/docx-editor/pull/58) [`d9edb75`](https://github.com/portone-io/docx-editor/commit/d9edb75fa45e1a6cc81e5741a5242cf500107091) Thanks [@Deea222](https://github.com/Deea222)! - Pagination measures every block as a list of break candidates; no visible change
+
+- [#55](https://github.com/portone-io/docx-editor/pull/55) [`7110baa`](https://github.com/portone-io/docx-editor/commit/7110baae68b75323720a39374c6df58db4367896) Thanks [@Deea222](https://github.com/Deea222)! - Turn down a raw OOXML fragment that does not hold its shape as it enters the document, rather than writing it into the exported file.
+  
+  Keep imported formatting when a document uses an inherited default namespace or an alternative WordprocessingML prefix. Reject nested namespace rebinding that could disconnect hyperlinks from their targets on export.
+  
+  The editor draws the original XML of a paragraph, a run, a table, an image or an annotation into the page as a `data-` attribute, so that it can read the live DOM back after an IME composition or a browser edit. A fragment written into one of those attributes from outside, by a consumer plugin or through `view.pasteHTML`, is now held to what that attribute goes back out as: a whole element under an expected name, an opening tag's attributes, or an opening tag the writer closes itself. One that does not hold it is turned down along with the rule reading it, so the content settles one level plainer - a paragraph keeps its text and loses its properties, a run loses its mark, a content control or a hyperlink loses its wrapper - instead of a `data-ppr` reading `</w:p><w:p>...` writing a second paragraph into the exported body, or one that never closed reaching export and failing the whole document with `malformed-xml`.
+
+- [#54](https://github.com/portone-io/docx-editor/pull/54) [`8aea477`](https://github.com/portone-io/docx-editor/commit/8aea477dceab5462c15903b25b29c738980aff47) Thanks [@Deea222](https://github.com/Deea222)! - An untouched table opened in the editor is written back byte for byte, its `w:tblGridChange` included.
+  
+  Export decided whether a block was untouched by comparing it with the one import produced, attrs and all.
+  Opening a document works some of those attrs out again from the formatting around them - a table's shared cell borders among them - so a table nobody had touched compared unequal and was rebuilt, and the rebuild dropped the markup the writer does not model.
+  
+  Each attr now declares whether the writer writes from it, whether the editor works it out for the screen, or whether it identifies something in the open document, and the comparison ignores the ones worked out for the screen.
+  Exporting through `createEditorState` is held to the same byte identity as exporting straight from `importDocx`.
+
+- [#48](https://github.com/portone-io/docx-editor/pull/48) [`de84006`](https://github.com/portone-io/docx-editor/commit/de840061dd60f3b652273410bc2d0a85b9451ad3) Thanks [@Deea222](https://github.com/Deea222)! - Stop `onlyCommentsChangedBy` from refusing a comment written into a table cell.
+  
+  A commented table is rebuilt on the way out, so it came back worded the way this editor words it while the original carried the wording its producer chose, and the two were compared word for word.
+  The story is now compared as this editor writes it back, so two blocks this editor would write alike are read alike: the attribute order inside a `w:tcW` or a `w:tblW`, a percentage width written as `100%` or as `5000`, runs a producer split that say the same text, and a table's `w:tblGridChange`.
+  Formatting properties keep the line breaks, comments and text a producer wrote between them, so rewriting a run's bold, a paragraph's alignment or a cell of a rebuilt table no longer drops them.
+  A rebuilt table keeps what stood inside its width and span properties too.
+
+- [#52](https://github.com/portone-io/docx-editor/pull/52) [`991ba48`](https://github.com/portone-io/docx-editor/commit/991ba48501e20e60bfc69b3c76862f4a26123b3e) Thanks [@Deea222](https://github.com/Deea222)! - Read the comment parts entry by entry in `onlyCommentsChangedBy`.
+  
+  The three parts a comment is written across are the ones a comment edit may rewrite, so the package comparison passes over their bytes.
+  Nothing read them afterwards, which let a submission carry a field pointing at a remote image inside a comment body, a comment attributed to a third author that nothing refers to, or markup wrapped around a body, and still be answered as a file where only comments changed.
+  Each entry now has to arrive as it was, or be one this editor writes for an author who could have written it, and an entry nothing refers to has to stay as it was.
+  A file that fails is refused as `part-changed` naming the comment part.
+  
+  Settling or replying to a comment that arrived with the file no longer rewrites its entry as plain text.
+  The entry keeps what it said, and its last paragraph gains the `w14:paraId` the thread state is written against.
+  The extended comments part carries an entry only for a comment that has thread state.
+
+## 0.2.0
+
+### Minor Changes
+
+- [#45](https://github.com/portone-io/docx-editor/pull/45) [`3190a35`](https://github.com/portone-io/docx-editor/commit/3190a359e0686bdc14166e22b1d96c761dabe251) Thanks [@Deea222](https://github.com/Deea222)! - Add a `comment` mode and record who wrote each comment.
+  
+  **Breaking:** `mode` is now required and the `commentAuthor` prop is removed.
+  `author: { id, name, initials? }` moves into `mode` for its `comment` and `edit` kinds.
+  `contextMenus` moves off `mode` onto `DocxEditor` itself, so `mode: { kind: "edit", contextMenus: false }` becomes `contextMenus={false}`.
+  
+  In `comment` mode the text can be selected and copied but not changed, while comments can be written, answered, resolved, and reopened.
+  A comment records its author's identity in the document, so two authors sharing a display name stay distinct.
+  Only a comment's author may edit or delete it, and anyone may reply, resolve, and reopen.
+  `mode.editableComments: "all"` opens every comment to a moderator.
+  The `canEditComment` and `editingProtection` queries report what the current mode allows.
+  A server can check a file coming back with `onlyCommentsChangedBy` from `@portone/docx-editor/core`, which answers `{ ok: true }` or `{ ok: false, reason }` for whether the file differs in nothing but one author's comments.
+
 ## 0.1.1
 
 ### Patch Changes

package/CONTRIBUTING.md

@@ -48,12 +48,16 @@ pnpm test:e2e
 
 [Testing](https://github.com/portone-io/docx-editor/blob/main/docs/testing.md) explains the scope and prerequisites of every check.
 
+A command added to `./commands` or `./table` needs a writer probe in `src/docx/__testing__/writerProbes.ts` with a `check` of its immediate effect, so its export is validated before another command can overwrite it, or an entry in `NOT_A_WRITER` giving the reason it reaches no writer.
+
 ## Changesets
 
 If you changed anything under `src/`, run `pnpm changeset` and commit the file it writes.
 It becomes the CHANGELOG entry, so write it for someone reading release notes rather than the diff.
 Choose `patch` unless the change adds to or breaks the public API.
 Those are `minor` while the package is below 1.0.
+A declaration added, removed, or rewritten in `etc/*.api.md` after running `pnpm api:update` is what that looks like; a line that only gains or loses an `(undocumented)` marker is not.
+Commit the regenerated report in the same commit as the changeset.
 
 By contributing, you agree that your contribution is licensed under the Apache License 2.0 used by this project.
 

package/README.md

@@ -18,21 +18,33 @@ import "@portone/docx-editor/styles.css";
 import { DocxEditor, type DocxEditorHandle } from "@portone/docx-editor";
 import { useRef } from "react";
 
-export function Editor({ file }: { file: File }) {
+export function Editor({
+  file,
+  user,
+}: {
+  file: File;
+  user: { id: string; name: string };
+}) {
   const editorRef = useRef<DocxEditorHandle | null>(null);
 
-  return <DocxEditor ref={editorRef} document={file} />;
+  return (
+    <DocxEditor
+      ref={editorRef}
+      document={file}
+      mode={{ kind: "edit", author: { id: user.id, name: user.name } }}
+    />
+  );
 }
 ```
 
-`document` accepts a `File`, `Blob`, `ArrayBuffer`, or `Uint8Array`; use the ref to export the edited document as bytes.
+`document` accepts a `File`, `Blob`, `ArrayBuffer`, or `Uint8Array`; `mode` selects read-only, comment-only, or full editing and names the author new comments are attributed to; use the ref to export the edited document as bytes.
 
 ## What it does
 
-- Provides browser editing with built-in controls, read-only mode, and document locking.
+- Provides browser editing with built-in controls, read-only and comment-only modes, and document locking.
 - Fits the page to the available width by default and lets readers choose a fixed zoom level.
 - Exports edited documents as DOCX bytes or browser downloads.
-- Preserves document structures and package parts across edits.
+- Preserves document structures and package parts across edits, and records who wrote each comment.
 - Reads document styles, theme fonts, page layout, and CJK font information for display.
 
 See [Feature support](https://docx-editor.portone.io/docs/features) for the support matrix. Build [custom controls](https://docx-editor.portone.io/docs/custom-controls) or use [programmatic DOCX import and export](https://docx-editor.portone.io/docs/core).

package/dist/DocxEditor.d.ts

@@ -13,6 +13,7 @@ import { type CSSProperties, type ReactNode } from "react";
 import { type DocxSource } from "./docx/importDocx";
 import { type CommentAuthor } from "./editor/commands/commentCommands";
 import { DocxImportError } from "./ooxml/errors";
+import type { EditableComments } from "./schema/protection";
 import type { FontFallbacks } from "./styles/fontStack";
 import type { DocxEditorPresets } from "./ui/presets";
 import { type DocxEditorZoom } from "./ui/zoom";
@@ -24,22 +25,37 @@ export interface DocxEditorHandle {
 /**
  * What the editor is for, which decides what it offers.
  *
- * A read-only editor takes no edits, so it has no toolbar and no right click menus either: what
- * used to be three booleans of which one silently emptied the other two is one choice here.
+ * The three kinds are the standings OOXML document protection names (`ST_DocProtect`) and the
+ * ones a shared document gives its readers: a reader, a commenter, an editor. A read-only editor
+ * takes no edits, so it has no toolbar and no right click menus either: what used to be three
+ * booleans of which one silently emptied the other two is one choice here. A `comment` editor is
+ * the `comments` protection - the body may not be changed, comments may be written, answered and
+ * settled - which is what a reviewer who must not touch the text is handed. Both kinds that write
+ * comments name whose they are, so a reader is never asked for an identity it has no use for.
+ *
+ * `editableComments` is whose comments the panel offers to edit or delete: one's own, which is a
+ * comment carrying no recognised identity or the very identity given here, or every one, which
+ * is a moderator's standing. Replying and resolving are open to every commenter either way.
+ *
  * `locking` is what a screen where a template is written gets: settling a part of a document is
  * an authoring act, not something every reader of a form should be handed. A lock the document
  * already carries holds whichever mode is chosen.
  *
- * `contextMenus: false` leaves the right click to the browser, for a consumer drawing menus of
- * its own. The plugins that take the browser's menu away go into the editor state, which is built
- * when the editor mounts, so this is read once there like `plugins`.
+ * The kind, the author and `editableComments` are read on every render and take effect on the
+ * open document. Whether the right click opens the editor's own menus is `contextMenus`, a prop
+ * of its own, since the plugins behind it are read when the editor mounts rather than per render.
  */
 export type DocxEditorMode = {
     kind: "readOnly";
+} | {
+    kind: "comment";
+    author: CommentAuthor;
+    editableComments?: EditableComments;
 } | {
     kind: "edit";
+    author: CommentAuthor;
+    editableComments?: EditableComments;
     toolbar?: boolean;
-    contextMenus?: boolean;
     locking?: boolean;
 };
 export interface DocxEditorProps {
@@ -58,8 +74,8 @@ export interface DocxEditorProps {
      * never silent either way. Hand one in to write the refusal in your own words.
      */
     renderImportError?: (error: DocxImportError) => ReactNode;
-    /** What the editor is for. Editing with the toolbar shown and no locking when none is given */
-    mode?: DocxEditorMode;
+    /** What the editor is for: a reader's, a commenter's or an editor's surface */
+    mode: DocxEditorMode;
     /** Whether to draw approximate page boundaries over the document's own paper. Drawn when read only too */
     showPageGuides?: boolean;
     /**
@@ -96,8 +112,6 @@ export interface DocxEditorProps {
      * takes effect without a remount.
      */
     presets?: DocxEditorPresets;
-    /** The identity written by the built-in comment and reply composers */
-    commentAuthor?: CommentAuthor;
     /**
      * ProseMirror plugins handed in by the consumer, which is how mentions, highlights,
      * autocomplete and the like are added from outside the package.
@@ -110,6 +124,16 @@ export interface DocxEditorProps {
      * `key` and remount.
      */
     plugins?: readonly Plugin[];
+    /**
+     * Whether the right click opens the editor's own menus. `false` leaves it to the browser,
+     * which is what a consumer drawing menus of its own wants. Defaults to `true`.
+     *
+     * Read once, when the editor mounts, like `plugins`: the plugins that take the browser's menu
+     * away go into the editor state, which is built there. A menu the protection has nothing to
+     * offer from stands down by itself, so a mode change needs nothing here. Later changes are
+     * ignored; to turn the menus around, change the `key` and remount.
+     */
+    contextMenus?: boolean;
     className?: string;
     style?: CSSProperties;
     onReady?: (view: EditorView) => void;

package/dist/DocxEditor.js

@@ -15,6 +15,7 @@ import {
 } from "./editor/commands/commentCommands.js";
 import { activeLinkSpan } from "./editor/commands/linkCommands.js";
 import { createEditorState, createEditorView } from "./editor/createEditor.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";
@@ -23,6 +24,7 @@ import { DocxImportError } from "./ooxml/errors.js";
 import { PageGuides } from "./page/PageGuides.js";
 import { A4_PAGE_PIXELS, pagePixels } from "./page/pageLayout.js";
 import { usePageLayout } from "./page/usePageLayout.js";
+import { editingProtection, protectionOf } from "./schema/protectionState.js";
 import { editorClassNames } from "./styles/classNames.js";
 import { CommentsPanel } from "./ui/CommentsPanel.js";
 import { LinkCard } from "./ui/LinkCard.js";
@@ -34,6 +36,38 @@ 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 affordancesOf(mode) {
+  switch (mode.kind) {
+    case "readOnly":
+      return {
+        protection: "readOnly",
+        author: null,
+        editableComments: "own",
+        toolbar: false,
+        locking: false
+      };
+    case "comment":
+      return {
+        protection: "comments",
+        author: mode.author ?? null,
+        editableComments: mode.editableComments ?? "own",
+        toolbar: false,
+        locking: false
+      };
+    case "edit":
+      return {
+        protection: "none",
+        author: mode.author ?? null,
+        editableComments: mode.editableComments ?? "own",
+        toolbar: mode.toolbar ?? true,
+        locking: mode.locking ?? false
+      };
+    default: {
+      const unmodelled = mode;
+      return unmodelled;
+    }
+  }
+}
 function openDocument(bytes) {
   try {
     const { doc, session } = importDocx(bytes);
@@ -97,32 +131,28 @@ function zoomVariable(factor) {
 function DocxEditorSurface({
   document: source,
   renderImportError,
-  mode = { kind: "edit" },
+  mode,
   showPageGuides = true,
   zoom,
   defaultZoom = "fit-width",
   onZoomChange,
   fontFallbacks,
   presets,
-  commentAuthor = { name: "Anonymous" },
   plugins,
+  contextMenus,
   className,
   style,
   onReady,
   onChange
 }, ref) {
-  const readOnly = mode.kind === "readOnly";
-  const showToolbar = mode.kind === "edit" && (mode.toolbar ?? true);
-  const allowLocking = mode.kind === "edit" && (mode.locking ?? false);
+  const { protection, author, editableComments, toolbar, locking } = affordancesOf(mode);
   const bytes = useDocumentBytes(source);
   const opened = useMemo(
     () => bytes === null ? null : openDocument(bytes),
     [bytes]
   );
   const mountedPlugins = useRef(plugins).current;
-  const mountedContextMenus = useRef(
-    mode.kind !== "edit" || (mode.contextMenus ?? true)
-  ).current;
+  const mountedContextMenus = useRef(contextMenus ?? true).current;
   const mountedFontFallbacks = useRef(fontFallbacks).current;
   const layerRef = useRef(null);
   const rootRef = useRef(null);
@@ -173,11 +203,13 @@ function DocxEditorSurface({
           ...opened.session.comments.extendedOrdered.map(
             (extension) => extension.paraId
           )
-        ]
+        ],
+        protection,
+        author,
+        editableComments
       }),
       defaults: opened.session.defaults,
       geometry: opened.session.geometry,
-      readOnly,
       fontFallbacks: mountedFontFallbacks,
       onStateChange: (state) => {
         keptState.current = { of: opened, state };
@@ -196,19 +228,32 @@ function DocxEditorSurface({
     };
   }, [
     opened,
-    readOnly,
     mountedContextMenus,
     mountedFontFallbacks,
     mountedPlugins,
     latestOnReady,
     latestOnChange
   ]);
+  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);
+    if (held.protection === protection && held.authorId === authorId && held.editableComments === editableComments) {
+      return;
+    }
+    view.dispatch(
+      setProtection(view.state.tr, { protection, author, editableComments })
+    );
+  }, [mounted, protection, authorId, editableComments]);
   useImperativeHandle(ref, () => {
     const view = viewRef.current;
     if (!view || opened?.status !== "opened") return null;
     const session = opened.session;
     return { view, exportBytes: () => exportDocx(view.state.doc, session) };
-  }, [opened, readOnly]);
+  }, [opened]);
   const overlay = usePageLayout({
     view: live?.view ?? null,
     layer: layerRef,
@@ -219,21 +264,22 @@ function DocxEditorSurface({
   if (opened?.status === "rejected") {
     return renderImportError ? renderImportError(opened.error) : /* @__PURE__ */ jsx(ImportRejection, { error: opened.error });
   }
-  const textAnchor = live && !readOnly ? textMenuAnchor(live.state) : null;
-  const tableAnchor = live && !readOnly && !textAnchor ? tableMenuAnchor(live.state) : null;
+  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 hasUnresolvedComments = comments.some((comment) => !comment.resolved);
-  const effectiveComposerOpen = commentComposerOpen && !readOnly;
+  const effectiveComposerOpen = commentComposerOpen && commentsOpenToWrite;
   const showComments = live !== null && (commentsOpen || effectiveComposerOpen || hasUnresolvedComments);
   const commentsPanel = live && showComments && /* @__PURE__ */ jsx(
     CommentsPanel,
     {
       view: live.view,
       state: live.state,
-      readOnly,
       composerOpen: effectiveComposerOpen,
-      author: commentAuthor,
+      author,
       closeComposer: () => setCommentComposerOpen(false),
       scrollContainer: rootRef.current,
       allCommentsOpen: commentsOpen
@@ -245,7 +291,7 @@ function DocxEditorSurface({
       className: [editorClassNames.frame, className].filter(Boolean).join(" "),
       style,
       children: [
-        live && showToolbar && /* @__PURE__ */ jsx(
+        live && toolbar && /* @__PURE__ */ jsx(
           Toolbar,
           {
             view: live.view,
@@ -270,7 +316,7 @@ function DocxEditorSurface({
             "data-comments": showComments ? "visible" : void 0,
             style: zoomVariable(effectiveZoom),
             children: [
-              live && readOnly && comments.length > 0 && /* @__PURE__ */ jsx(
+              live && !bodyOpen && comments.length > 0 && /* @__PURE__ */ jsx(
                 "button",
                 {
                   type: "button",
@@ -306,14 +352,13 @@ function DocxEditorSurface({
             ]
           }
         ),
-        live && !readOnly && isLinkPanelOpen(live.state) && /* @__PURE__ */ jsx(LinkPanel, { view: live.view, state: live.state }),
+        live && bodyOpen && isLinkPanelOpen(live.state) && /* @__PURE__ */ jsx(LinkPanel, { view: live.view, state: live.state }),
         live && linkAtCursor && /* @__PURE__ */ jsx(
           LinkCard,
           {
             view: live.view,
             state: live.state,
-            link: linkAtCursor,
-            readOnly
+            link: linkAtCursor
           },
           linkAtCursor.from
         ),
@@ -323,7 +368,7 @@ function DocxEditorSurface({
             view: live.view,
             state: live.state,
             anchor: textAnchor,
-            allowLocking,
+            allowLocking: locking,
             onAddComment: () => {
               setCommentComposerOpen(true);
             }
@@ -335,7 +380,7 @@ function DocxEditorSurface({
             view: live.view,
             state: live.state,
             anchor: tableAnchor,
-            allowLocking
+            allowLocking: locking
           }
         )
       ]

package/dist/core.d.ts

@@ -5,6 +5,8 @@
 import type { Node as PMNode } from "prosemirror-model";
 import { type DocxBytes } from "./docx/importDocx";
 import type { DocxSession } from "./docx/session";
+export type { CommentOnlyVerdict } from "./docx/commentOnlyChange";
+export { onlyCommentsChangedBy } from "./docx/commentOnlyChange";
 export { exportDocx } from "./docx/exportDocx";
 export type { ParagraphStyleOption } from "./docx/formatting";
 export type { DocxBytes } from "./docx/importDocx";

package/dist/core.js

@@ -1,5 +1,6 @@
 // src/core.ts
 import { importDocx as openDocx } from "./docx/importDocx.js";
+import { onlyCommentsChangedBy } from "./docx/commentOnlyChange.js";
 import { exportDocx } from "./docx/exportDocx.js";
 import { documentNumbering, documentPartPath } from "./docx/session.js";
 import {
@@ -26,6 +27,7 @@ export {
   emuToPx,
   exportDocx,
   importDocx,
+  onlyCommentsChangedBy,
   parseNumbering,
   pxToEmu,
   toCellFormat,

package/dist/docx/commentOnlyChange.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Whether a file handed back changed in nothing but comments one author is allowed to have made.
+ *
+ * The editor's own refusal under a comment protection (`schema/protection`) is a courtesy to the
+ * user: the browser holds the file, so the rule is held again here, where a server takes it in.
+ * The judgement is over the package rather than over the document alone, since a submission is
+ * free to rewrite anything the story does not carry - the paper the document is written on, its
+ * styles, its headers - and a document comparison would see none of it.
+ */
+import { type EditableComments } from "../schema/protection";
+import { type DocxBytes } from "./importDocx";
+/**
+ * Why a file is not the one it claims to be. `part-changed` and `relationship-changed` name the
+ * part they were reached over; the other three are about the document story itself.
+ */
+export type CommentOnlyVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "body-changed" | "comment-not-owned" | "comment-author-forged";
+} | {
+    ok: false;
+    reason: "part-changed" | "relationship-changed";
+    part: string;
+};
+/**
+ * Whether the submitted file differs from the original in nothing but comments, every one of them
+ * added, edited, moved, deleted, replied to or settled by the author with this identity.
+ *
+ * Every part of the package has to arrive as it left, save for the three a comment is written
+ * across and the relationship and content type they are declared with; the document story itself
+ * has to read as it did, comments aside. Those three parts are read entry by entry instead
+ * (`./comments/verifying`), 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.
+ *
+ * `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.
+ *
+ * Bytes that are not a readable docx are turned down the way opening one is, with a
+ * `DocxImportError`, rather than being answered as a file that changed.
+ */
+export declare function onlyCommentsChangedBy(original: DocxBytes, submitted: DocxBytes, authorId: string, { editableComments }?: {
+    editableComments?: EditableComments;
+}): CommentOnlyVerdict;