@portone/docx-editor 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # @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

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/dist/docx/commentOnlyChange.d.ts

@@ -29,7 +29,9 @@ export type CommentOnlyVerdict = {
  *
  * 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. A comment carrying no recorded identity is everyone's to
+ * 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.

package/dist/docx/commentOnlyChange.js

@@ -1,10 +1,10 @@
 // src/docx/commentOnlyChange.ts
 import { decodeUtf8, elementChildren, parseXml } from "../ooxml/xml.js";
 import {
-  changesOnlyComments,
   commentAdditionsBy,
   commentEditsOwned,
-  commentIdentitiesKept
+  commentIdentitiesKept,
+  withoutComments
 } from "../schema/protection.js";
 import {
   COMMENTS_CONTENT_TYPE,
@@ -15,12 +15,16 @@ import {
   PEOPLE_CONTENT_TYPE,
   PEOPLE_REL_TYPE
 } from "./comments/constants.js";
+import { commentPartsKept } from "./comments/verifying.js";
 import { importDocx } from "./importDocx.js";
 import {
   readRelationships,
-  relsPathOf,
-  resolveTarget
+  relsPathOf
 } from "./relationships.js";
+import {
+  comparableStory,
+  isModelledBlock
+} from "./storyProjection.js";
 var COMMENT_REL_TYPES = [
   COMMENTS_REL_TYPE,
   COMMENTS_EXTENDED_REL_TYPE,
@@ -35,32 +39,32 @@ var refused = (reason) => ({ ok: false, reason });
 function sameBytes(before, after) {
   return before.length === after.length && before.every((byte, index) => byte === after[index]);
 }
+function commentPartsOf(session) {
+  const { partPath, extendedPartPath, people } = session.comments;
+  return [partPath, extendedPartPath, people.partPath];
+}
 function commentPartPaths(session) {
-  const related = readRelationships(
-    session.parts,
-    relsPathOf(session.mainPartPath)
-  ).filter(
-    (entry) => !entry.external && COMMENT_REL_TYPES.includes(entry.type)
-  );
   return new Set(
-    related.map((entry) => resolveTarget(session.mainPartPath, entry.target))
+    commentPartsOf(session).filter((path) => path !== null)
   );
 }
 function aroundTheStory(session) {
-  const preserved = session.blocks.filter(
-    (block) => block.node.type.name !== "paragraph" && block.node.type.name !== "table"
-  ).map((block) => block.xml).join("");
+  const preserved = session.blocks.filter((block) => !isModelledBlock(block.node)).map((block) => block.xml).join("");
   return session.documentPrefix + preserved + session.documentSuffix;
 }
 function relationshipsKept(before, after) {
+  if (new Set(before.map((entry) => entry.id)).size !== before.length || new Set(after.map((entry) => entry.id)).size !== after.length) {
+    return false;
+  }
   const now = new Map(after.map((entry) => [entry.id, entry]));
   const kept = before.every((entry) => {
     const current = now.get(entry.id);
     return current !== void 0 && current.type === entry.type && current.target === entry.target && current.external === entry.external;
   });
   const ids = new Set(before.map((entry) => entry.id));
-  return kept && after.every(
-    (entry) => ids.has(entry.id) || COMMENT_REL_TYPES.includes(entry.type)
+  const parts = after.filter((entry) => !entry.external);
+  return kept && after.filter((entry) => !ids.has(entry.id)).every(
+    (entry) => COMMENT_REL_TYPES.includes(entry.type) && !entry.external && parts.filter((other) => other.type === entry.type).length === 1
   );
 }
 function contentTypes(bytes) {
@@ -83,6 +87,12 @@ function contentTypesKept(before, after) {
   }
   return true;
 }
+function gainedCommentPartsAreNew(before, after) {
+  const had = commentPartsOf(before);
+  return commentPartsOf(after).every(
+    (path, kind) => path === null || path === had[kind] || !before.parts.has(path)
+  );
+}
 function packageKept(before, after) {
   if (before.mainPartPath !== after.mainPartPath) {
     return { ok: false, reason: "part-changed", part: before.mainPartPath };
@@ -106,7 +116,7 @@ function packageKept(before, after) {
   if (!relationshipsKept(
     readRelationships(before.parts, relsPath),
     readRelationships(after.parts, relsPath)
-  )) {
+  ) || !gainedCommentPartsAreNew(before, after)) {
     return { ok: false, reason: "relationship-changed", part: relsPath };
   }
   if (!contentTypesKept(
@@ -120,12 +130,17 @@ function packageKept(before, after) {
   }
   return { ok: true };
 }
+function sameBody(before, after) {
+  const was = comparableStory(before, withoutComments);
+  const now = comparableStory(after, withoutComments);
+  return was !== null && now !== null && was.length === now.length && was.every((block, at) => block === now[at]);
+}
 function storyKept(before, after, authorId, editableComments) {
-  if (!changesOnlyComments(before, after)) return refused("body-changed");
-  if (!commentIdentitiesKept(before, after) || !commentAdditionsBy(before, after, authorId)) {
+  if (!sameBody(before, after)) return refused("body-changed");
+  if (!commentIdentitiesKept(before.doc, after.doc) || !commentAdditionsBy(before.doc, after.doc, authorId)) {
     return refused("comment-author-forged");
   }
-  if (!commentEditsOwned(before, after, {
+  if (!commentEditsOwned(before.doc, after.doc, {
     protection: "comments",
     authorId,
     editableComments
@@ -138,7 +153,9 @@ function onlyCommentsChangedBy(original, submitted, authorId, { editableComments
   const before = importDocx(original);
   const after = importDocx(submitted);
   const packaged = packageKept(before.session, after.session);
-  return packaged.ok ? storyKept(before.doc, after.doc, authorId, editableComments) : packaged;
+  if (!packaged.ok) return packaged;
+  const story = storyKept(before, after, authorId, editableComments);
+  return story.ok ? commentPartsKept(before, after, authorId, editableComments) : story;
 }
 export {
   onlyCommentsChangedBy

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

@@ -3,9 +3,9 @@ export declare const COMMENTS_EXTENDED_REL_TYPE = "http://schemas.microsoft.com/
 export declare const COMMENTS_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml";
 export declare const COMMENTS_EXTENDED_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml";
 export declare const CONTENT_TYPES_PATH = "[Content_Types].xml";
-export declare const W14_NS = "http://schemas.microsoft.com/office/word/2010/wordml";
-export declare const W15_NS = "http://schemas.microsoft.com/office/word/2012/wordml";
-export declare const MC_NS = "http://schemas.openxmlformats.org/markup-compatibility/2006";
+export declare const W14_NS: "http://schemas.microsoft.com/office/word/2010/wordml";
+export declare const W15_NS: "http://schemas.microsoft.com/office/word/2012/wordml";
+export declare const MC_NS: "http://schemas.openxmlformats.org/markup-compatibility/2006";
 export declare const PEOPLE_REL_TYPE = "http://schemas.microsoft.com/office/2011/relationships/people";
 export declare const PEOPLE_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.people+xml";
 /**

package/dist/docx/comments/constants.js

@@ -1,13 +1,14 @@
 // src/docx/comments/constants.ts
+import { NAMESPACES } from "../../ooxml/names.js";
 import { R_NS } from "../../ooxml/xml.js";
 var COMMENTS_REL_TYPE = `${R_NS}/comments`;
 var COMMENTS_EXTENDED_REL_TYPE = "http://schemas.microsoft.com/office/2011/relationships/commentsExtended";
 var COMMENTS_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml";
 var COMMENTS_EXTENDED_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml";
 var CONTENT_TYPES_PATH = "[Content_Types].xml";
-var W14_NS = "http://schemas.microsoft.com/office/word/2010/wordml";
-var W15_NS = "http://schemas.microsoft.com/office/word/2012/wordml";
-var MC_NS = "http://schemas.openxmlformats.org/markup-compatibility/2006";
+var W14_NS = NAMESPACES.w14;
+var W15_NS = NAMESPACES.w15;
+var MC_NS = NAMESPACES.mc;
 var PEOPLE_REL_TYPE = "http://schemas.microsoft.com/office/2011/relationships/people";
 var PEOPLE_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.people+xml";
 var COMMENT_AUTHOR_PROVIDER = "portone-docx-editor";

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

@@ -0,0 +1,80 @@
+/**
+ * The shapes this editor writes the three comment parts in, and the reading of those shapes.
+ *
+ * Each entry is written here and judged here, so the two halves cannot drift apart: a body written
+ * by hand can be told from one this editor put out only where the writer and the reader agree on
+ * what it puts out. `./reading` keeps a lenient flattener for display, which takes whatever a
+ * producer wrote and shows what it can; this one judges an entry that came back and says no to
+ * everything else.
+ */
+import { type XmlAttr } from "../../ooxml/element";
+import type { CommentReferenceData, CommentReplyData } from "./model";
+/** The attributes this editor writes on a `w:comment`. The thread key goes on the body's paragraph */
+export declare const COMMENT_ATTRIBUTES: ReadonlySet<string>;
+/** The attributes this editor writes on a `w15:commentEx` */
+export declare const COMMENT_EX_ATTRIBUTES: ReadonlySet<string>;
+/**
+ * Whether the element carries no attribute outside this set.
+ *
+ * A namespace declaration is not an attribute of the element in this sense: it says where the
+ * names come from rather than anything about the entry, and where a producer puts one is its own
+ * business.
+ */
+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;
+/**
+ * The paragraph a thread key belongs on, which is the last one of the body.
+ *
+ * A body may hold a paragraph of another vocabulary, a picture's DrawingML `a:p` among them, and a
+ * key put on that says nothing about the thread. The namespace decides, since a prefix means only
+ * what the element it sits on binds it to, and a document may bind the same prefix twice over.
+ */
+export declare function lastBodyParagraph(comment: Element): Element | null;
+/**
+ * The entries a part arrived holding, under the id each carries.
+ *
+ * The writer asks the document which paragraph a key goes on rather than asking the text, because
+ * only the document knows what a prefix means where it is written.
+ */
+export declare function arrivedEntries(partXml: string | null): ReadonlyMap<string, Element>;
+/**
+ * The entry with the thread key on its body's last paragraph, and unchanged where it has one.
+ *
+ * Settling a thread or replying to it hangs the state off that key, and an entry that arrived
+ * without one has to gain it. Writing the entry afresh instead would put back only what this
+ * editor models, so a body holding more than plain text would lose it to a change nobody asked
+ * for and nobody made.
+ *
+ * `arrived` is that entry as the document has it, which is what says which paragraph is a
+ * WordprocessingML one and whether it already carries a key under some prefix. The text is only
+ * asked where that paragraph is: its opening tag is the one at the same place among the tags named
+ * `p`, counted the same way in both.
+ *
+ * The `w14` prefix is declared on the part rather than here: a part holding any thread state
+ * 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;
+/**
+ * The identity this editor records for an author, as it writes it into the people part.
+ *
+ * The prefix and the declaration come from the caller, which is writing into a part whose root
+ * already binds them or is being written from nothing.
+ */
+export declare function renderPerson(author: string, userId: string, prefix: string, declaration: XmlAttr | null): string;

package/dist/docx/comments/grammar.js

@@ -0,0 +1,213 @@
+// src/docx/comments/grammar.ts
+import {
+  attrsText,
+  elementXml,
+  xmlnsAttr
+} from "../../ooxml/element.js";
+import { qualify, wName } from "../../ooxml/names.js";
+import {
+  attributeByLocalName,
+  elementChildren,
+  escapeXml,
+  parseXml,
+  W_NS
+} from "../../ooxml/xml.js";
+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"),
+  nameKey(W_NS, "author"),
+  nameKey(W_NS, "date"),
+  nameKey(W_NS, "initials")
+]);
+var COMMENT_EX_ATTRIBUTES = /* @__PURE__ */ new Set([
+  nameKey(W15_NS, "paraId"),
+  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")
+]);
+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);
+  return value === null || THREAD_KEY.test(value);
+}
+function attributesWithin(el, allowed) {
+  return Array.from(el.attributes).every(
+    (attr) => attr.namespaceURI === XMLNS_NS || attr.name === "xmlns" || allowed.has(nameKey(attr.namespaceURI, attr.localName))
+  );
+}
+function isNamed(el, namespace, localName) {
+  return el.namespaceURI === namespace && el.localName === localName;
+}
+function holdsElementsOnly(el) {
+  return Array.from(el.childNodes).every(
+    (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)]);
+}
+var PARAGRAPH_OR_SKIPPED = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<([^\s<>/:="']+:)?p(?=[\s/>])[^>]*>/g;
+function lastBodyParagraph(comment) {
+  const paragraphs = comment.getElementsByTagNameNS(W_NS, "p");
+  return paragraphs.length === 0 ? null : paragraphs[paragraphs.length - 1];
+}
+function namedParagraphs(comment) {
+  return Array.from(comment.getElementsByTagName("*")).filter(
+    (element) => element.localName === "p"
+  );
+}
+function arrivedEntries(partXml) {
+  const entries = /* @__PURE__ */ new Map();
+  if (partXml === null) return entries;
+  let root;
+  try {
+    root = parseXml(partXml).documentElement;
+  } catch {
+    return entries;
+  }
+  for (const entry of elementChildren(root)) {
+    if (entry.namespaceURI !== W_NS || entry.localName !== "comment") continue;
+    const id = attributeByLocalName(entry, "id");
+    if (id !== null && !entries.has(id)) entries.set(id, entry);
+  }
+  return entries;
+}
+function withThreadKey(commentXml, paraId, arrived) {
+  if (arrived === null) return commentXml;
+  const target = lastBodyParagraph(arrived);
+  if (target === null) return commentXml;
+  if (target.getAttributeNS(W14_NS, "paraId") !== null || target.hasAttribute("w14:paraId")) {
+    return commentXml;
+  }
+  const at = namedParagraphs(arrived).indexOf(target);
+  const openings = Array.from(commentXml.matchAll(PARAGRAPH_OR_SKIPPED)).filter(
+    (match) => !match[0].startsWith("<!")
+  );
+  const opening = openings[at];
+  if (at === -1 || opening === void 0 || opening.index === void 0) {
+    return commentXml;
+  }
+  const selfClosing = opening[0].endsWith("/>");
+  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"));
+}
+function wellFormedPerson(entry) {
+  if (!attributesWithin(entry, PERSON_ATTRIBUTES)) return false;
+  if (!holdsElementsOnly(entry)) return false;
+  const children = Array.from(entry.children);
+  if (children.length !== 1) return false;
+  const [presence] = children;
+  return isNamed(presence, W15_NS, "presenceInfo") && attributesWithin(presence, PRESENCE_ATTRIBUTES) && attributeByLocalName(presence, "providerId") === COMMENT_AUTHOR_PROVIDER && attributeByLocalName(presence, "userId") !== null && presence.childNodes.length === 0;
+}
+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]] : [];
+  const done = "resolved" in comment ? [[qualify("w15", "done"), comment.resolved ? "1" : "0"]] : [];
+  return elementXml(qualify("w15", "commentEx"), [
+    [qualify("w15", "paraId"), comment.paraId],
+    ...parent,
+    ...done
+  ]);
+}
+function renderPerson(author, userId, prefix, declaration) {
+  const declared = declaration === null ? [] : [declaration];
+  return elementXml(
+    `${prefix}person`,
+    [...declared, [`${prefix}author`, author]],
+    [
+      elementXml(`${prefix}presenceInfo`, [
+        [`${prefix}providerId`, COMMENT_AUTHOR_PROVIDER],
+        [`${prefix}userId`, userId]
+      ])
+    ]
+  );
+}
+export {
+  COMMENT_ATTRIBUTES,
+  COMMENT_EX_ATTRIBUTES,
+  arrivedEntries,
+  attributesWithin,
+  lastBodyParagraph,
+  readStrictCommentBody,
+  recordedIdentity,
+  renderCommentBody,
+  renderCommentExtension,
+  renderPerson,
+  wellFormedCommentExtension,
+  wellFormedPerson,
+  withThreadKey
+};

package/dist/docx/comments/people.js

@@ -1,11 +1,13 @@
 // src/docx/comments/people.ts
+import { xmlnsAttr } from "../../ooxml/element.js";
 import { DocxExportError } from "../../ooxml/errors.js";
+import { xmlnsDecl } from "../../ooxml/names.js";
 import {
+  attributeByLocalName,
   childByLocalName,
   decodeUtf8,
   elementChildren,
   encodeUtf8,
-  escapeXml,
   parseXml
 } from "../../ooxml/xml.js";
 import {
@@ -22,15 +24,13 @@ import {
   W15_NS
 } from "./constants.js";
 import { withContentType } from "./contentTypes.js";
+import { renderPerson } from "./grammar.js";
 var NO_PEOPLE = {
   partPath: null,
   xml: null,
   hadBom: false,
   byAuthor: /* @__PURE__ */ new Map()
 };
-function attribute(el, localName) {
-  return Array.from(el.attributes).find((entry) => entry.localName === localName)?.value ?? null;
-}
 function readPeople(parts, mainPartPath) {
   const relationship = readRelationships(parts, relsPathOf(mainPartPath)).find(
     (entry) => entry.type === PEOPLE_REL_TYPE && !entry.external
@@ -45,14 +45,15 @@ function readPeople(parts, mainPartPath) {
   const byAuthor = /* @__PURE__ */ new Map();
   for (const el of elementChildren(root)) {
     if (el.localName !== "person") continue;
-    const author = attribute(el, "author");
+    const author = attributeByLocalName(el, "author");
     if (author === null) continue;
     byAuthor.set(author, null);
     const presence = childByLocalName(el, "presenceInfo");
     if (presence === null) continue;
-    if (attribute(presence, "providerId") !== COMMENT_AUTHOR_PROVIDER) continue;
+    if (attributeByLocalName(presence, "providerId") !== COMMENT_AUTHOR_PROVIDER)
+      continue;
     const ids = ourIds.get(author) ?? /* @__PURE__ */ new Set();
-    ids.add(attribute(presence, "userId"));
+    ids.add(attributeByLocalName(presence, "userId"));
     ourIds.set(author, ids);
   }
   for (const [author, ids] of ourIds) {
@@ -64,9 +65,6 @@ function readPeople(parts, mainPartPath) {
 function commentAuthorId(people, author) {
   return people.byAuthor.get(author) ?? null;
 }
-function personXml(author, userId, prefix, declaration) {
-  return `<${prefix}person${declaration} ${prefix}author="${escapeXml(author)}"><${prefix}presenceInfo ${prefix}providerId="${COMMENT_AUTHOR_PROVIDER}" ${prefix}userId="${escapeXml(userId)}"/></${prefix}person>`;
-}
 function unrecordedAuthors(bodies, people) {
   const unrecorded = /* @__PURE__ */ new Map();
   for (const body of bodies) {
@@ -129,9 +127,9 @@ function peopleXml(people, added) {
   if (xml === null) {
     const persons2 = Array.from(
       added,
-      ([author, userId]) => personXml(author, userId, "w15:", "")
+      ([author, userId]) => renderPerson(author, userId, "w15:", null)
     );
-    return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w15:people xmlns:w15="${W15_NS}">${persons2.join("")}</w15:people>`;
+    return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w15:people ${xmlnsDecl("w15")}>${persons2.join("")}</w15:people>`;
   }
   const root = parseXml(xml).documentElement;
   if (root.localName !== "people") {
@@ -140,11 +138,11 @@ function peopleXml(people, added) {
   const prefix = w15Prefix(root);
   const persons = Array.from(
     added,
-    ([author, userId]) => personXml(
+    ([author, userId]) => renderPerson(
       author,
       userId,
       prefix ?? "w15:",
-      prefix === null ? ` xmlns:w15="${W15_NS}"` : ""
+      prefix === null ? xmlnsAttr("w15") : null
     )
   ).join("");
   const start = rootTagStart(xml);