@portone/docx-editor 0.1.1 → 0.2.1

package/dist/docx/commentOnlyChange.js

@@ -0,0 +1,162 @@
+// src/docx/commentOnlyChange.ts
+import { decodeUtf8, elementChildren, parseXml } from "../ooxml/xml.js";
+import {
+  commentAdditionsBy,
+  commentEditsOwned,
+  commentIdentitiesKept,
+  withoutComments
+} from "../schema/protection.js";
+import {
+  COMMENTS_CONTENT_TYPE,
+  COMMENTS_EXTENDED_CONTENT_TYPE,
+  COMMENTS_EXTENDED_REL_TYPE,
+  COMMENTS_REL_TYPE,
+  CONTENT_TYPES_PATH,
+  PEOPLE_CONTENT_TYPE,
+  PEOPLE_REL_TYPE
+} from "./comments/constants.js";
+import { commentPartsKept } from "./comments/verifying.js";
+import { importDocx } from "./importDocx.js";
+import {
+  readRelationships,
+  relsPathOf
+} from "./relationships.js";
+import {
+  comparableStory,
+  isModelledBlock
+} from "./storyProjection.js";
+var COMMENT_REL_TYPES = [
+  COMMENTS_REL_TYPE,
+  COMMENTS_EXTENDED_REL_TYPE,
+  PEOPLE_REL_TYPE
+];
+var COMMENT_CONTENT_TYPES = [
+  COMMENTS_CONTENT_TYPE,
+  COMMENTS_EXTENDED_CONTENT_TYPE,
+  PEOPLE_CONTENT_TYPE
+];
+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) {
+  return new Set(
+    commentPartsOf(session).filter((path) => path !== null)
+  );
+}
+function aroundTheStory(session) {
+  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));
+  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) {
+  if (bytes === void 0) return /* @__PURE__ */ new Map();
+  const declared = /* @__PURE__ */ new Map();
+  for (const el of elementChildren(
+    parseXml(decodeUtf8(bytes).text).documentElement
+  )) {
+    const key = el.localName === "Default" ? el.getAttribute("Extension") : el.localName === "Override" ? el.getAttribute("PartName") : null;
+    if (key !== null) declared.set(key, el.getAttribute("ContentType") ?? "");
+  }
+  return declared;
+}
+function contentTypesKept(before, after) {
+  for (const [key, type] of before) {
+    if (after.get(key) !== type) return false;
+  }
+  for (const [key, type] of after) {
+    if (!before.has(key) && !COMMENT_CONTENT_TYPES.includes(type)) return false;
+  }
+  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 };
+  }
+  const relsPath = relsPathOf(before.mainPartPath);
+  const untouched = /* @__PURE__ */ new Set([
+    before.mainPartPath,
+    relsPath,
+    CONTENT_TYPES_PATH,
+    ...commentPartPaths(before),
+    ...commentPartPaths(after)
+  ]);
+  for (const path of /* @__PURE__ */ new Set([...before.parts.keys(), ...after.parts.keys()])) {
+    if (untouched.has(path)) continue;
+    const was = before.parts.get(path);
+    const now = after.parts.get(path);
+    if (was === void 0 || now === void 0 || !sameBytes(was, now)) {
+      return { ok: false, reason: "part-changed", part: path };
+    }
+  }
+  if (!relationshipsKept(
+    readRelationships(before.parts, relsPath),
+    readRelationships(after.parts, relsPath)
+  ) || !gainedCommentPartsAreNew(before, after)) {
+    return { ok: false, reason: "relationship-changed", part: relsPath };
+  }
+  if (!contentTypesKept(
+    contentTypes(before.parts.get(CONTENT_TYPES_PATH)),
+    contentTypes(after.parts.get(CONTENT_TYPES_PATH))
+  )) {
+    return { ok: false, reason: "part-changed", part: CONTENT_TYPES_PATH };
+  }
+  if (aroundTheStory(before) !== aroundTheStory(after)) {
+    return { ok: false, reason: "part-changed", part: before.mainPartPath };
+  }
+  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 (!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.doc, after.doc, {
+    protection: "comments",
+    authorId,
+    editableComments
+  })) {
+    return refused("comment-not-owned");
+  }
+  return { ok: true };
+}
+function onlyCommentsChangedBy(original, submitted, authorId, { editableComments = "own" } = {}) {
+  const before = importDocx(original);
+  const after = importDocx(submitted);
+  const packaged = packageKept(before.session, after.session);
+  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,6 +3,14 @@ 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";
+/**
+ * The `w15:providerId` under which this editor records a comment author's identity. An identity
+ * another provider recorded, Word's directory above all, is one this editor cannot vouch for and
+ * is read as none.
+ */
+export declare const COMMENT_AUTHOR_PROVIDER = "portone-docx-editor";

package/dist/docx/comments/constants.js

@@ -1,20 +1,27 @@
 // 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";
 export {
   COMMENTS_CONTENT_TYPE,
   COMMENTS_EXTENDED_CONTENT_TYPE,
   COMMENTS_EXTENDED_REL_TYPE,
   COMMENTS_REL_TYPE,
+  COMMENT_AUTHOR_PROVIDER,
   CONTENT_TYPES_PATH,
   MC_NS,
+  PEOPLE_CONTENT_TYPE,
+  PEOPLE_REL_TYPE,
   W14_NS,
   W15_NS
 };

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

@@ -0,0 +1,7 @@
+/** Declares a part an export adds in `[Content_Types].xml`, leaving the original text as it came. */
+/**
+ * The content types part with an override for this part, or null when it already declares one.
+ * `current` is the part as an earlier addition in the same export left it, so that two additions
+ * do not each write over the other's declaration.
+ */
+export declare function withContentType(parts: Map<string, Uint8Array>, partPath: string, contentType: string, current: Uint8Array | undefined): Uint8Array | null;

package/dist/docx/comments/contentTypes.js

@@ -0,0 +1,38 @@
+// src/docx/comments/contentTypes.ts
+import { DocxExportError } from "../../ooxml/errors.js";
+import { decodeUtf8, encodeUtf8 } from "../../ooxml/xml.js";
+import { CONTENT_TYPES_PATH } from "./constants.js";
+var TYPES_OPEN_TAG = /<(?:[\w.-]+:)?Types\b[^>]*>/;
+function withContentType(parts, partPath, contentType, current) {
+  const original = current ?? parts.get(CONTENT_TYPES_PATH);
+  if (!original) {
+    throw new DocxExportError(
+      "missing-content-types",
+      `cannot add a part to a package that has no ${CONTENT_TYPES_PATH}`
+    );
+  }
+  const { text, hadBom } = decodeUtf8(original);
+  const partName = `/${partPath}`;
+  if (new RegExp(
+    `<(?:[\\w.-]+:)?Override[^>]+PartName=["']${partName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}["']`,
+    "i"
+  ).test(text)) {
+    return null;
+  }
+  const open = TYPES_OPEN_TAG.exec(text);
+  if (!open) {
+    throw new DocxExportError(
+      "malformed-xml",
+      `${CONTENT_TYPES_PATH} has no Types element`
+    );
+  }
+  const rootName = /^<([^\s>]+)/.exec(open[0])?.[1] ?? "Types";
+  const separator = rootName.indexOf(":");
+  const prefix = separator < 0 ? "" : `${rootName.slice(0, separator)}:`;
+  const declaration = `<${prefix}Override PartName="${partName}" ContentType="${contentType}"/>`;
+  const at = open.index + open[0].length;
+  return encodeUtf8(text.slice(0, at) + declaration + text.slice(at), hadBom);
+}
+export {
+  withContentType
+};

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/model.d.ts

@@ -6,6 +6,7 @@ import type { ImportedComments } from "./reading";
 export interface CommentReferenceData {
     id: string;
     author: string | null;
+    authorId: string | null;
     initials: string | null;
     date: string | null;
     text: string;
@@ -20,6 +21,7 @@ export interface CommentReferenceData {
 export interface CommentReplyData {
     id: string;
     author: string | null;
+    authorId: string | null;
     initials: string | null;
     date: string | null;
     text: string;

package/dist/docx/comments/model.js

@@ -23,6 +23,7 @@ function importedCommentReplies(comments, rootId) {
     replies.push({
       id: reply.id,
       author: reply.author,
+      authorId: reply.authorId,
       initials: reply.initials,
       date: reply.date,
       text: reply.text,
@@ -55,6 +56,7 @@ function replyData(value) {
       {
         id,
         author: nullableString(entry.author),
+        authorId: nullableString(entry.authorId),
         initials: nullableString(entry.initials),
         date: nullableString(entry.date),
         text: nullableString(entry.text) ?? "",
@@ -74,6 +76,7 @@ function referenceData(node) {
   return {
     id,
     author: nullableString(node.attrs.author),
+    authorId: nullableString(node.attrs.authorId),
     initials: nullableString(node.attrs.initials),
     date: nullableString(node.attrs.date),
     text: nullableString(node.attrs.text) ?? "",

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

@@ -0,0 +1,39 @@
+/**
+ * The people part, where Word records who a comment author is beyond the display name
+ * (`w15:people`): a `w15:person` carrying a `w15:presenceInfo` whose `w15:providerId` names the
+ * directory that issued `w15:userId`.
+ *
+ * This editor records the identity a host application hands it under a provider of its own
+ * (`COMMENT_AUTHOR_PROVIDER`). The `w15:author` name is the key both Word and this editor read the
+ * part by, so a name stands for one identity per file: a name the part already records is read as
+ * it stands and never appended to. Appending a second person for it would leave a file naming two
+ * identities for one name, where a reader keying by name hands one author's comments to the other.
+ */
+import { type RelationshipWriter } from "../relationships";
+import type { SessionStore } from "../session";
+import type { CommentReferenceData, CommentReplyData } from "./model";
+export interface ImportedPeople {
+    partPath: string | null;
+    xml: string | null;
+    hadBom: boolean;
+    /**
+     * Every author name the part records, mapped to the identity it stands for. Null where this
+     * editor cannot vouch for the name: another provider recorded it, or it is recorded twice over
+     * under different identities and nothing in the file says which of them wrote what.
+     */
+    byAuthor: ReadonlyMap<string, string | null>;
+}
+export declare const NO_PEOPLE: ImportedPeople;
+/** Reads the people part related from the main document story. */
+export declare function readPeople(parts: Map<string, Uint8Array>, mainPartPath: string): ImportedPeople;
+/**
+ * The identity this editor recorded for the author of that name. Null for a name it did not
+ * record, and for one the part records under more than one identity.
+ */
+export declare function commentAuthorId(people: ImportedPeople, author: string): string | null;
+/**
+ * Plans the people part, its relationship and its content type for every identity the current
+ * comments carry that the document has not recorded. Null when it has recorded them all, which
+ * leaves the part as it arrived.
+ */
+export declare function planPeoplePart(bodies: Iterable<CommentReferenceData | CommentReplyData>, session: SessionStore, relationships: RelationshipWriter, currentContentTypes: Uint8Array | undefined): ReadonlyMap<string, Uint8Array> | null;