@json-to-office/core-docx 0.32.0 → 0.34.0

package/dist/index.js

@@ -1134,7 +1134,7 @@ function getPageDimensions(size) {
   if (typeof size === "string") {
     return PAGE_SIZES[size];
   }
-  return size;
+  return { width: size.width, height: size.height };
 }
 var resolveTableParagraphSpacing, PAGE_SIZES, getTableStyle, getDocumentMargins, getPageSetup;
 var init_layoutUtils = __esm({
@@ -1151,10 +1151,10 @@ var init_layoutUtils = __esm({
       };
     };
     PAGE_SIZES = {
-      A4: { width: 11906, height: 16838 },
-      A3: { width: 16838, height: 23811 },
-      LETTER: { width: 12240, height: 15840 },
-      LEGAL: { width: 12240, height: 20160 }
+      A4: { width: 11906, height: 16838, code: 9 },
+      A3: { width: 16838, height: 23811, code: 8 },
+      LETTER: { width: 12240, height: 15840, code: 1 },
+      LEGAL: { width: 12240, height: 20160, code: 5 }
     };
     getTableStyle = (theme, themeName) => {
       const themeConfig = resolveTheme(theme, themeName);
@@ -1291,7 +1291,8 @@ var init_layoutUtils = __esm({
         return {
           size: {
             width: dimensions.width,
-            height: dimensions.height
+            height: dimensions.height,
+            ...dimensions.code !== void 0 && { code: dimensions.code }
           },
           margin: {
             top: margins.top ?? defaultMargins.top ?? 1440,
@@ -1303,10 +1304,11 @@ var init_layoutUtils = __esm({
       }
       return {
         size: {
-          width: 11906,
-          // 8.5 inches in twips (Letter size)
-          height: 16838
-          // 11.7 inches in twips (Letter size)
+          width: PAGE_SIZES.A4.width,
+          // 210mm in twips (A4)
+          height: PAGE_SIZES.A4.height,
+          // 297mm in twips (A4)
+          code: PAGE_SIZES.A4.code
         },
         margin: {
           top: defaultMargins.top ?? 1440,
@@ -2528,18 +2530,7 @@ function getColumnSettings(layout) {
 function createSectionProperties(columnSettings, theme, themeName, sectionType, pageOverride) {
   const basePageSetup = getPageSetup(theme, themeName);
   const pageSetup = pageOverride ? {
-    size: {
-      ...basePageSetup.size,
-      ...pageOverride.size && typeof pageOverride.size === "object" ? pageOverride.size : pageOverride.size ? (() => {
-        const sizes = {
-          A4: { width: 11906, height: 16838 },
-          A3: { width: 16838, height: 23811 },
-          LETTER: { width: 12240, height: 15840 },
-          LEGAL: { width: 12240, height: 20160 }
-        };
-        return sizes[pageOverride.size];
-      })() : {}
-    },
+    size: pageOverride.size ? getPageDimensions(pageOverride.size) : basePageSetup.size,
     margin: {
       ...basePageSetup.margin,
       ...pageOverride.margins || {}
@@ -2641,8 +2632,8 @@ Suggestion: ${suggestion}`
 // src/core/render.ts
 import {
   Document,
-  Paragraph as Paragraph7,
-  TextRun as TextRun6,
+  Paragraph as Paragraph9,
+  TextRun as TextRun9,
   AlignmentType as AlignmentType5,
   BookmarkStart as BookmarkStart2,
   BookmarkEnd as BookmarkEnd2
@@ -3061,17 +3052,19 @@ function convertBorders(borders, theme) {
     color: resolveColor(side.color, theme),
     ...side.space !== void 0 ? { space: side.space } : {}
   } : void 0;
-  const top = mapSide(borders.top);
-  const bottom = mapSide(borders.bottom);
-  const left = mapSide(borders.left);
-  const right = mapSide(borders.right);
-  const anyDefined = top || bottom || left || right;
-  return anyDefined ? {
-    ...top && { top },
-    ...bottom && { bottom },
-    ...left && { left },
-    ...right && { right }
-  } : void 0;
+  const sides = [
+    "top",
+    "bottom",
+    "left",
+    "right",
+    "between"
+  ];
+  const converted = {};
+  for (const side of sides) {
+    const value = mapSide(borders[side]);
+    if (value) converted[side] = value;
+  }
+  return Object.keys(converted).length > 0 ? converted : void 0;
 }
 function createWordStyles(themeNameOrObject = "minimal", language) {
   const theme = typeof themeNameOrObject === "string" ? getTheme(themeNameOrObject) || getTheme("minimal") : themeNameOrObject;
@@ -3440,7 +3433,7 @@ function createWordStyles(themeNameOrObject = "minimal", language) {
       }
       const tocMatch = /^TOC([1-9])$/.exec(styleKey);
       const customStyle = tocMatch ? styleValue : resolveStyleWithBaseStyle(theme, styleKey) || styleValue;
-      const styleId = tocMatch ? `JTD_TOC${tocMatch[1]}` : styleKey;
+      const styleId = tocMatch ? `TOC${tocMatch[1]}` : styleKey;
       const styleName = tocMatch ? `TOC ${tocMatch[1]}` : styleKey.replace(/([A-Z])/g, " $1").trim();
       const mapBaseStyleId = (base) => {
         if (!base) return "Normal";
@@ -3512,8 +3505,8 @@ function createWordStyles(themeNameOrObject = "minimal", language) {
       continue;
     }
     paragraphStyles.push({
-      // Use a namespaced ID but canonical display name
-      id: `JTD_TOC${i}`,
+      // Canonical id and display name — see the styleId note above.
+      id: `TOC${i}`,
       name: `TOC ${i}`,
       basedOn: "Normal",
       next: "Normal",
@@ -3536,20 +3529,43 @@ function createWordStyles(themeNameOrObject = "minimal", language) {
       }
     });
   }
+  const noteStyle = resolveStyleWithBaseStyle(theme, "normal") || theme.styles?.normal;
+  const bodyRun = convertRunProperties(
+    mergeFontAndStyleProperties(resolveFontProperties(theme, noteStyle?.font), {
+      size: noteStyle?.size,
+      color: noteStyle?.color
+    }),
+    theme,
+    theme.colors.text
+  );
+  const noteRun = {
+    ...bodyRun,
+    ...typeof bodyRun.size === "number" && {
+      size: Math.max(12, bodyRun.size - 4)
+    }
+  };
   return {
     paragraphStyles,
     // Cast needed due to docx typing
-    // Document-default proofing language (w:docDefaults/w:rPrDefault). Runs that
-    // don't set their own w:lang inherit this, so Word spell-checks the whole
-    // document in the requested language unless a component overrides it.
-    ...language && {
-      default: {
+    default: {
+      // Document-default proofing language (w:docDefaults/w:rPrDefault). Runs
+      // that don't set their own w:lang inherit this, so Word spell-checks the
+      // whole document in the requested language unless a component overrides
+      // it.
+      ...language && {
         document: {
           run: {
             language: { value: language }
           }
         }
-      }
+      },
+      // Run properties only: docx's own note paragraph defaults (single line
+      // spacing, no space after) are already what a note wants, and an empty
+      // spacing override would drop its line rule.
+      footnoteText: { run: noteRun },
+      footnoteReference: { run: { ...noteRun, superScript: true } },
+      endnoteText: { run: noteRun },
+      endnoteReference: { run: { ...noteRun, superScript: true } }
     }
   };
 }
@@ -3671,7 +3687,15 @@ import {
 } from "docx";
 
 // src/utils/textParser.ts
-import { TextRun, ExternalHyperlink, InternalHyperlink, Tab } from "docx";
+import {
+  TextRun,
+  ExternalHyperlink,
+  InternalHyperlink,
+  FootnoteReferenceRun,
+  EndnoteReferenceRun,
+  Tab
+} from "docx";
+var FOOTNOTE_MARKER_REGEX = /\[\^([^\]\s]+)\]/;
 function escapeRegExp(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -3848,8 +3872,8 @@ function buildTextRuns(text, commonProps, opts = {}) {
   return runs;
 }
 function createTextRunsWithNewlines(text, baseStyle, options, overrideStyle) {
-  return buildTextRuns(
-    text,
+  const runs = (segment) => buildTextRuns(
+    segment,
     buildRunCommonProps(baseStyle, {
       bold: overrideStyle?.bold,
       italics: overrideStyle?.italics,
@@ -3857,6 +3881,34 @@ function createTextRunsWithNewlines(text, baseStyle, options, overrideStyle) {
     }),
     { noProof: baseStyle.noProof, noProofWords: options.noProofWords }
   );
+  if (!options.noteRef) return runs(text);
+  return splitNoteMarkers(text, options.noteRef, runs);
+}
+function splitNoteMarkers(text, noteRef, runs) {
+  const regex = new RegExp(FOOTNOTE_MARKER_REGEX.source, "g");
+  const out = [];
+  let lastIndex = 0;
+  let pending = "";
+  let match;
+  while ((match = regex.exec(text)) !== null) {
+    const note = noteRef(match[1]);
+    if (note === void 0) {
+      pending += text.slice(lastIndex, regex.lastIndex);
+      lastIndex = regex.lastIndex;
+      continue;
+    }
+    const before = pending + text.slice(lastIndex, match.index);
+    pending = "";
+    if (before) out.push(...runs(before));
+    out.push(
+      note.endnote ? new EndnoteReferenceRun(note.id) : new FootnoteReferenceRun(note.id)
+    );
+    lastIndex = regex.lastIndex;
+  }
+  if (out.length === 0) return runs(text);
+  const trailing = pending + text.slice(lastIndex);
+  if (trailing) out.push(...runs(trailing));
+  return out;
 }
 function parseTextWithHyperlinks(text, baseStyle = {}, options = {}) {
   const normalizedText = normalizeUnicodeText(text);
@@ -4112,6 +4164,52 @@ initializeBuiltinPlaceholders();
 
 // src/utils/revisionUtils.ts
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
+
+// src/utils/componentAnnotations.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function hasKey(value, key) {
+  return isRecord(value) && Boolean(value[key]);
+}
+function cellHasAnnotation(cell, key) {
+  if (!isRecord(cell)) return false;
+  if (hasKey(cell, key)) return true;
+  const content = cell.content;
+  return isRecord(content) && componentHasAnnotation(content, key);
+}
+function componentHasAnnotation(component, key) {
+  const props = component.props;
+  if (props) {
+    if (props[key]) return true;
+    const items = props.items;
+    if (Array.isArray(items) && items.some((item) => hasKey(item, key))) {
+      return true;
+    }
+    const rows = props.rows;
+    if (Array.isArray(rows) && rows.some((row) => hasKey(row, key))) {
+      return true;
+    }
+    const columns = props.columns;
+    if (Array.isArray(columns) && columns.some((column) => {
+      if (!isRecord(column)) return false;
+      if (cellHasAnnotation(column.header, key)) return true;
+      const cells = column.cells;
+      return Array.isArray(cells) && cells.some((cell) => cellHasAnnotation(cell, key));
+    })) {
+      return true;
+    }
+  }
+  const children = component.children;
+  if (Array.isArray(children)) {
+    return children.some(
+      (child) => isRecord(child) && componentHasAnnotation(child, key)
+    );
+  }
+  return false;
+}
+
+// src/utils/revisionUtils.ts
 var DEFAULT_REVISION_AUTHOR = "json-to-office";
 var DEFAULT_REVISION_DATE = "1970-01-01T00:00:00Z";
 var RevisionIdRegistry = class {
@@ -4196,25 +4294,25 @@ function createRevisionRuns(revision, baseStyle) {
   return runs;
 }
 function componentHasRevision(component) {
-  const props = component.props;
-  if (props) {
-    if (props.revision) return true;
-    const items = props.items;
-    if (Array.isArray(items)) {
-      if (items.some(
-        (item) => typeof item === "object" && item !== null && "revision" in item && item.revision
-      )) {
-        return true;
-      }
-    }
-  }
-  const children = component.children;
-  if (Array.isArray(children)) {
-    return children.some(
-      (child) => typeof child === "object" && child !== null && componentHasRevision(child)
-    );
-  }
-  return false;
+  return componentHasAnnotation(component, "revision");
+}
+function createRevisionMark(mark) {
+  const attributes = {
+    id: globalRevisionIdRegistry.next(),
+    author: mark.author || DEFAULT_REVISION_AUTHOR,
+    date: mark.date || DEFAULT_REVISION_DATE
+  };
+  return mark.type === "insert" ? { insertion: attributes } : { deletion: attributes };
+}
+function createMarkedTextRuns(text, mark, baseStyle) {
+  return createRevisionRuns(
+    {
+      author: mark.author,
+      date: mark.date,
+      segments: [{ type: mark.type, text }]
+    },
+    baseStyle
+  );
 }
 
 // src/core/cached-render.ts
@@ -4291,14 +4389,23 @@ async function clearComponentCache() {
   }
   bypassStats.clear();
 }
+var DYNAMIC_CONTEXT_COMPONENTS = /* @__PURE__ */ new Set([
+  "toc",
+  "section",
+  "visual",
+  "heading",
+  "list",
+  "paragraph"
+]);
+function componentBypassReason(component) {
+  if (componentHasRevision(component)) return "revision-ids";
+  if (componentHasAnnotation(component, "comment")) return "comment-ids";
+  if ("id" in component) return "bookmark-id";
+  if (DYNAMIC_CONTEXT_COMPONENTS.has(component.name)) return "dynamic-context";
+  return null;
+}
 async function renderComponentWithCache(component, theme, themeName, context, bypassCache = false) {
-  const bypassReason = componentHasRevision(
-    component
-  ) ? "revision-ids" : "id" in component ? "bookmark-id" : component.name === "toc" || component.name === "section" || component.name === "visual" || component.name === "heading" || // Both explicit lists and markdown-list paragraphs register
-  // numbering in the current document scope. Cached paragraphs can
-  // otherwise reference definitions that only existed in a previous
-  // render.
-  component.name === "list" || component.name === "paragraph" ? "dynamic-context" : null;
+  const bypassReason = componentBypassReason(component);
   if (!componentCache) {
     initializeComponentCache();
   }
@@ -4368,8 +4475,8 @@ function getComponentCacheStats() {
 
 // src/core/content.ts
 import {
-  Paragraph,
-  TextRun as TextRun4,
+  Paragraph as Paragraph3,
+  TextRun as TextRun7,
   Table,
   TableRow,
   TableCell,
@@ -4464,6 +4571,252 @@ var BookmarkRegistry = class {
 };
 var globalBookmarkRegistry = new BookmarkRegistry();
 
+// src/utils/commentAnchors.ts
+import {
+  CommentRangeEnd,
+  CommentRangeStart,
+  CommentReference,
+  TextRun as TextRun5
+} from "docx";
+
+// src/utils/commentRegistry.ts
+import { Paragraph, TextRun as TextRun4 } from "docx";
+import { AsyncLocalStorage as AsyncLocalStorage4 } from "async_hooks";
+var DEFAULT_COMMENT_AUTHOR = "json-to-office";
+var DEFAULT_COMMENT_DATE = "1970-01-01T00:00:00Z";
+function createState() {
+  return { counter: 0, comments: [], hasResolved: false };
+}
+function deriveInitials(author) {
+  const initials = author.split(/[\s._-]+/).filter(Boolean).map((word) => word[0]).join("").toUpperCase().slice(0, 3);
+  return initials || author.slice(0, 2).toUpperCase();
+}
+function bodyParagraphs(text) {
+  return normalizeUnicodeText(text).split("\n").map((line) => new Paragraph({ children: [new TextRun4({ text: line })] }));
+}
+var CommentRegistry = class {
+  fallback = createState();
+  scopes = new AsyncLocalStorage4();
+  get state() {
+    return this.scopes.getStore() ?? this.fallback;
+  }
+  /** Run work with an isolated registry that follows its async call chain. */
+  runScoped(callback) {
+    return this.scopes.run(createState(), callback);
+  }
+  /**
+   * Register a comment thread and return every id its anchors must carry — the
+   * root first, then each reply in order. Word anchors every comment in a
+   * thread over the same range, so all of them need a range and a reference.
+   *
+   * Ids are unique and monotonic within a render. `parentId` is derived here
+   * rather than authored; docx turns it into the `w15:paraIdParent` links in
+   * `word/commentsExtended.xml`.
+   */
+  register(comment) {
+    const state = this.state;
+    const resolved = comment.resolved;
+    const rootId = ++state.counter;
+    state.comments.push({
+      ...this.toOptions(comment, rootId),
+      ...resolved !== void 0 && { resolved }
+    });
+    const ids = [rootId];
+    for (const reply of comment.replies ?? []) {
+      const replyId = ++state.counter;
+      state.comments.push({
+        ...this.toOptions(reply, replyId),
+        parentId: rootId,
+        // Word resolves a thread as a whole, so the flag rides every member.
+        ...resolved !== void 0 && { resolved }
+      });
+      ids.push(replyId);
+    }
+    if (resolved !== void 0) state.hasResolved = true;
+    return ids;
+  }
+  toOptions(comment, id) {
+    const author = comment.author || DEFAULT_COMMENT_AUTHOR;
+    return {
+      id,
+      author,
+      initials: comment.initials || deriveInitials(author),
+      date: new Date(comment.date || DEFAULT_COMMENT_DATE),
+      children: bodyParagraphs(comment.text)
+    };
+  }
+  /**
+   * Every comment registered in this scope, in id order.
+   *
+   * docx writes `word/commentsExtended.xml` — and therefore any `w15:done` —
+   * only when at least one comment in the document carries a `parentId`. A
+   * document whose only resolved comment has no replies would silently lose
+   * that state, so say so rather than dropping it quietly.
+   */
+  getAll() {
+    const state = this.state;
+    if (state.hasResolved && !state.comments.some((comment) => comment.parentId !== void 0)) {
+      console.warn(
+        "A comment sets `resolved` but the document has no replies. Word stores the resolved flag in commentsExtended.xml, which is written only for threaded comments, so the flag will not survive."
+      );
+    }
+    return [...state.comments];
+  }
+  /** Test-only: reset the current scope's counter and bodies. */
+  clear() {
+    const state = this.scopes.getStore();
+    if (state) {
+      state.counter = 0;
+      state.comments.length = 0;
+      state.hasResolved = false;
+    } else {
+      this.fallback = createState();
+    }
+  }
+};
+var globalCommentRegistry = new CommentRegistry();
+
+// src/utils/commentAnchors.ts
+function openCommentRange(comment) {
+  if (!comment) return void 0;
+  const ids = globalCommentRegistry.register(comment);
+  return { ids, start: ids.map((id) => new CommentRangeStart(id)) };
+}
+function closeCommentRange(ids) {
+  return ids.flatMap((id) => [
+    new CommentRangeEnd(id),
+    new TextRun5({ children: [new CommentReference(id)] })
+  ]);
+}
+
+// src/utils/noteRegistry.ts
+import { Paragraph as Paragraph2, TextRun as TextRun6 } from "docx";
+import { AsyncLocalStorage as AsyncLocalStorage5 } from "async_hooks";
+function createState2() {
+  return {
+    footnoteCounter: 0,
+    endnoteCounter: 0,
+    footnotes: {},
+    endnotes: {}
+  };
+}
+function bodyParagraphs2(text, style) {
+  return normalizeUnicodeText(text).split("\n").map(
+    (line) => new Paragraph2({
+      style,
+      children: [new TextRun6({ text: line })]
+    })
+  );
+}
+var NoteRegistry = class {
+  fallback = createState2();
+  scopes = new AsyncLocalStorage5();
+  get state() {
+    return this.scopes.getStore() ?? this.fallback;
+  }
+  /** Run work with an isolated registry that follows its async call chain. */
+  runScoped(callback) {
+    return this.scopes.run(createState2(), callback);
+  }
+  /**
+   * Register a footnote body and return the id its reference must use. Ids are
+   * unique and monotonic within a render.
+   */
+  registerFootnote(text) {
+    const state = this.state;
+    const id = ++state.footnoteCounter;
+    state.footnotes[String(id)] = {
+      children: bodyParagraphs2(text, "FootnoteText")
+    };
+    return id;
+  }
+  /** Register an endnote body and return the id its reference must use. */
+  registerEndnote(text) {
+    const state = this.state;
+    const id = ++state.endnoteCounter;
+    state.endnotes[String(id)] = {
+      children: bodyParagraphs2(text, "EndnoteText")
+    };
+    return id;
+  }
+  /** Every footnote registered in this scope, keyed by id. */
+  getFootnotes() {
+    return { ...this.state.footnotes };
+  }
+  /** Every endnote registered in this scope, keyed by id. */
+  getEndnotes() {
+    return { ...this.state.endnotes };
+  }
+  /** Test-only: reset the current scope's counters and bodies. */
+  clear() {
+    const state = this.scopes.getStore();
+    if (state) {
+      state.footnoteCounter = 0;
+      state.endnoteCounter = 0;
+      for (const key of Object.keys(state.footnotes)) {
+        delete state.footnotes[key];
+      }
+      for (const key of Object.keys(state.endnotes)) {
+        delete state.endnotes[key];
+      }
+    } else {
+      this.fallback = createState2();
+    }
+  }
+};
+var globalNoteRegistry = new NoteRegistry();
+
+// src/utils/noteResolver.ts
+function collectDeclared(footnotes, endnotes) {
+  const declared = /* @__PURE__ */ new Map();
+  const declare = (note, endnote) => {
+    const existing = declared.get(note.id);
+    if (existing) {
+      console.warn(
+        existing.endnote === endnote ? `Note id "${note.id}" is declared twice in the same ${endnote ? "endnotes" : "footnotes"} array. Using the first declaration and ignoring the rest.` : `Note id "${note.id}" is declared as both a footnote and an endnote in the same paragraph. Using the footnote and ignoring the endnote.`
+      );
+      return;
+    }
+    declared.set(note.id, { text: note.text, endnote });
+  };
+  for (const note of footnotes ?? []) declare(note, false);
+  for (const note of endnotes ?? []) declare(note, true);
+  return declared;
+}
+function createNoteResolver(footnotes, endnotes) {
+  const declared = collectDeclared(footnotes, endnotes);
+  if (declared.size === 0) return void 0;
+  const registered = /* @__PURE__ */ new Map();
+  return {
+    resolve(id) {
+      const existing = registered.get(id);
+      if (existing !== void 0) return existing;
+      const note = declared.get(id);
+      if (note === void 0) {
+        console.warn(
+          `Note marker "[^${id}]" has no matching entry in this paragraph's footnotes or endnotes (declared: ${[...declared.keys()].join(", ")}). Rendering the marker as literal text.`
+        );
+        return void 0;
+      }
+      const resolved = {
+        id: note.endnote ? globalNoteRegistry.registerEndnote(note.text) : globalNoteRegistry.registerFootnote(note.text),
+        endnote: note.endnote
+      };
+      registered.set(id, resolved);
+      return resolved;
+    },
+    reportUnemitted(text) {
+      for (const [id, note] of declared) {
+        if (registered.has(id)) continue;
+        const kind = note.endnote ? "Endnote" : "Footnote";
+        console.warn(
+          text.includes(`[^${id}]`) ? `${kind} "${id}" is declared and its marker appears in the text, but the marker was not resolved \u2014 markers are not recognised in text that also contains {PLACEHOLDER} substitutions. The note will not appear in the document.` : `${kind} "${id}" is declared but never referenced as [^${id}] in this paragraph. It will not appear in the document.`
+        );
+      }
+    }
+  };
+}
+
 // src/core/content.ts
 init_styleHelpers();
 import { synthesizeFamilyName } from "@json-to-office/shared";
@@ -4487,6 +4840,20 @@ function resolveNoProofWords(theme, optionWords) {
   const merged = [...themeWords || [], ...optionWords || []];
   return merged.length > 0 ? Array.from(new Set(merged)) : void 0;
 }
+function reportNotesUnsupportedInRevision(footnotes, endnotes, revision) {
+  const declared = [...footnotes ?? [], ...endnotes ?? []];
+  if (declared.length === 0) return;
+  const text = revision.segments.map((segment) => segment.text).join("");
+  const referenced = declared.filter((note) => text.includes(`[^${note.id}]`));
+  console.warn(
+    `Paragraph declares ${declared.length} note(s) (${declared.map((note) => note.id).join(", ")}) alongside a \`revision\`. Tracked-change text renders literally, so note markers are not resolved there` + (referenced.length > 0 ? ` \u2014 the marker(s) ${referenced.map((note) => `[^${note.id}]`).join(", ")} will render as literal text` : "") + ". The notes will not appear in the document."
+  );
+}
+function wrapInComment(children, comment) {
+  const anchor = openCommentRange(comment);
+  if (!anchor) return children;
+  return [...anchor.start, ...children, ...closeCommentRange(anchor.ids)];
+}
 function createText(content, theme, themeName, options = {}) {
   const normalizedContent = normalizeUnicodeText(content);
   const style = options.style || "Normal";
@@ -4506,6 +4873,10 @@ function createText(content, theme, themeName, options = {}) {
   if (options.columnBreak) {
     children.push(new ColumnBreak());
   }
+  const commentAnchor = openCommentRange(options.comment);
+  if (commentAnchor) {
+    children.push(...commentAnchor.start);
+  }
   const hasWeightRequest = options.fontWeight != null || options.bold === true;
   const effectiveFamily = options.fontFamily ?? (hasWeightRequest ? resolveFontFamily(theme, "body") : void 0);
   const weighted = applyFontWeightAlias({
@@ -4542,6 +4913,11 @@ function createText(content, theme, themeName, options = {}) {
     ...options.noProof !== void 0 && { noProof: options.noProof }
   };
   if (options.revision) {
+    reportNotesUnsupportedInRevision(
+      options.footnotes,
+      options.endnotes,
+      options.revision
+    );
     const revisionRuns = createRevisionRuns(options.revision, baseTextStyle);
     if (options.bookmarkId) {
       globalBookmarkRegistry.register(
@@ -4559,11 +4935,17 @@ function createText(content, theme, themeName, options = {}) {
       children.push(...revisionRuns);
     }
   } else {
+    const noteResolver = createNoteResolver(
+      options.footnotes,
+      options.endnotes
+    );
     const textRuns = parseTextWithDecorators(normalizedContent, baseTextStyle, {
       boldColor: options.boldColor ? resolveColor(options.boldColor, theme) : void 0,
       enableHyperlinks: true,
-      noProofWords: resolveNoProofWords(theme, options.noProofWords)
+      noProofWords: resolveNoProofWords(theme, options.noProofWords),
+      noteRef: noteResolver?.resolve
     });
+    noteResolver?.reportUnemitted(normalizedContent);
     if (options.bookmarkId) {
       globalBookmarkRegistry.register(
         options.bookmarkId,
@@ -4580,9 +4962,12 @@ function createText(content, theme, themeName, options = {}) {
       children.push(...textRuns);
     }
   }
+  if (commentAnchor) {
+    children.push(...closeCommentRange(commentAnchor.ids));
+  }
   const isFloating = !!options.floating;
   const frameOptions = isFloating && options.floating ? mapFrameOptions(options.floating, theme, themeName) : void 0;
-  return new Paragraph({
+  return new Paragraph3({
     children,
     style,
     alignment: options.alignment ? getAlignment(options.alignment) : void 0,
@@ -4677,6 +5062,10 @@ function createHeading(text, level, theme, _themeName, options = {}) {
   if (options.columnBreak) {
     children.push(new ColumnBreak());
   }
+  const commentAnchor = openCommentRange(options.comment);
+  if (commentAnchor) {
+    children.push(...commentAnchor.start);
+  }
   const hasDecorators = /(\*\*\*|___|(\*\*|__)|(\*|_))/.test(normalizedText);
   const headingHasWeightRequest = options.fontWeight != null || options.bold === true;
   const headingEffectiveFamily = options.fontFamily ?? (headingHasWeightRequest ? resolveFontFamily(theme, "heading") : void 0);
@@ -4713,7 +5102,7 @@ function createHeading(text, level, theme, _themeName, options = {}) {
   const headingNoProofWords = resolveNoProofWords(theme, options.noProofWords);
   const makeHeadingRuns = (value) => splitByNoProofWords(
     value,
-    (segment, matched) => new TextRun4({
+    (segment, matched) => new TextRun7({
       text: segment,
       ...baseTextStyle,
       ...matched && { noProof: true }
@@ -4772,7 +5161,10 @@ function createHeading(text, level, theme, _themeName, options = {}) {
       children.push(...makeHeadingRuns(normalizedText));
     }
   }
-  return new Paragraph({
+  if (commentAnchor) {
+    children.push(...closeCommentRange(commentAnchor.ids));
+  }
+  return new Paragraph3({
     children,
     style: styleId,
     alignment: getAlignment(options.alignment || "left"),
@@ -4839,7 +5231,7 @@ async function createImage(path4, theme, themeName, options = {}) {
       spacing.after = pointsToTwips(options.spacing.after);
     }
     elements.push(
-      new Paragraph({
+      new Paragraph3({
         children: [imageRun],
         alignment,
         ...Object.keys(spacing).length > 0 && { spacing },
@@ -4856,7 +5248,7 @@ async function createImage(path4, theme, themeName, options = {}) {
     const hasDecorators = /(\*\*\*|___|(\*\*|__)|(\*|_))/.test(options.caption);
     if (!hasDecorators) {
       elements.push(
-        new Paragraph({
+        new Paragraph3({
           text: normalizeUnicodeText(options.caption),
           style: "Normal",
           alignment: AlignmentType2.LEFT
@@ -4872,7 +5264,7 @@ async function createImage(path4, theme, themeName, options = {}) {
         }
       );
       elements.push(
-        new Paragraph({
+        new Paragraph3({
           children: textRuns,
           style: "Normal",
           // Use Normal style for consistent font inheritance
@@ -4889,13 +5281,13 @@ function createStatistic(data, options = {}) {
   const normalizedNumber = normalizeUnicodeText(data.number);
   const normalizedDescription = normalizeUnicodeText(data.description);
   return [
-    new Paragraph({
+    new Paragraph3({
       text: normalizedNumber,
       style: "StatisticNumber",
       alignment,
       spacing: options.spacing
     }),
-    new Paragraph({
+    new Paragraph3({
       text: normalizedDescription,
       style: "StatisticDescription",
       alignment
@@ -4907,6 +5299,15 @@ function createList(items, _theme, _themeName, options = {}) {
     return [];
   }
   const paragraphs = [];
+  const noteResolver = createNoteResolver(options.footnotes, options.endnotes);
+  const rendersAt = items.map((item) => {
+    const text = typeof item === "string" ? item : item.text;
+    const revision = typeof item === "object" ? item.revision : void 0;
+    return Boolean(text.trim()) || Boolean(revision);
+  });
+  const firstRendered = rendersAt.indexOf(true);
+  const lastRendered = rendersAt.lastIndexOf(true);
+  const commentAnchor = firstRendered === -1 ? void 0 : openCommentRange(options.comment);
   items.forEach((item, index) => {
     const itemText = typeof item === "string" ? item : item.text;
     const itemLevel = typeof item === "object" ? item.level || 0 : 0;
@@ -4918,7 +5319,8 @@ function createList(items, _theme, _themeName, options = {}) {
       itemText,
       {},
       {
-        enableHyperlinks: true
+        enableHyperlinks: true,
+        noteRef: noteResolver?.resolve
       }
     );
     const spacing = {};
@@ -4930,10 +5332,15 @@ function createList(items, _theme, _themeName, options = {}) {
     } else if (options.spacing?.item) {
       spacing.after = pointsToTwips(options.spacing.item);
     }
-    const paragraph = new Paragraph({
+    const paragraphChildren = [
+      ...commentAnchor && index === firstRendered ? commentAnchor.start : [],
+      ...textRuns,
+      ...commentAnchor && index === lastRendered ? closeCommentRange(commentAnchor.ids) : []
+    ];
+    const paragraph = new Paragraph3({
       style: "Normal",
       // Apply Normal style for font inheritance
-      children: textRuns,
+      children: paragraphChildren,
       alignment: options.alignment ? getAlignment(options.alignment) : AlignmentType2.LEFT,
       spacing,
       // Use proper docx numbering instead of prepending text
@@ -4946,6 +5353,9 @@ function createList(items, _theme, _themeName, options = {}) {
     });
     paragraphs.push(paragraph);
   });
+  noteResolver?.reportUnemitted(
+    items.map((item) => typeof item === "string" ? item : item.text).join("\n")
+  );
   return paragraphs;
 }
 async function createTable(columns, tableConfig, theme, themeName, _options = {}) {
@@ -5279,10 +5689,10 @@ async function createTable(columns, tableConfig, theme, themeName, _options = {}
         return false;
     }
   };
-  const processCellContent = async (cell, cellDefaults, baseCellStyle) => {
+  const processCellContent = async (cell, cellDefaults, baseCellStyle, comment, revision, rowMark) => {
     let cellChildren = [];
     if (!cell) {
-      return cellChildren;
+      return wrapInComment(cellChildren, comment);
     }
     const cellWeighted = applyFontWeightAlias({
       fontFamily: cellDefaults.font?.family || baseCellStyle.font,
@@ -5326,11 +5736,10 @@ async function createTable(columns, tableConfig, theme, themeName, _options = {}
             color: resolveColor(paragraphFont.color, theme)
           }
         };
-        cellChildren = parseTextWithDecorators(
-          textComp.props.text,
-          paragraphStyle,
-          { enableHyperlinks: true }
-        );
+        const paragraphRevision = revision ?? textComp.props.revision;
+        cellChildren = paragraphRevision ? createRevisionRuns(paragraphRevision, paragraphStyle) : rowMark ? createMarkedTextRuns(textComp.props.text, rowMark, paragraphStyle) : parseTextWithDecorators(textComp.props.text, paragraphStyle, {
+          enableHyperlinks: true
+        });
       } else if (isImageComponent(cell)) {
         const imageComp = cell;
         try {
@@ -5365,7 +5774,7 @@ async function createTable(columns, tableConfig, theme, themeName, _options = {}
         } catch (error) {
           const imageSource = imageComp.props.svg?.trim() ? "inline-svg" : imageComp.props.base64 || imageComp.props.path || "unknown";
           cellChildren = [
-            new TextRun4({
+            new TextRun7({
               text: `[IMAGE: ${imageSource.substring(0, 50)}${imageSource.length > 50 ? "..." : ""}]`,
               font: mergedStyle.font,
               size: mergedStyle.size,
@@ -5375,7 +5784,7 @@ async function createTable(columns, tableConfig, theme, themeName, _options = {}
         }
       } else {
         cellChildren = [
-          new TextRun4({
+          new TextRun7({
             text: `[Unsupported component type: ${cell.name}]`,
             font: mergedStyle.font,
             size: mergedStyle.size,
@@ -5384,11 +5793,11 @@ async function createTable(columns, tableConfig, theme, themeName, _options = {}
         ];
       }
     } else {
-      cellChildren = parseTextWithDecorators(cell, mergedStyle, {
+      cellChildren = revision ? createRevisionRuns(revision, mergedStyle) : rowMark ? createMarkedTextRuns(cell, rowMark, mergedStyle) : parseTextWithDecorators(cell, mergedStyle, {
         enableHyperlinks: true
       });
     }
-    return cellChildren;
+    return wrapInComment(cellChildren, comment);
   };
   const numColumns = columns.length;
   const headerHeight = columns.reduce(
@@ -5445,7 +5854,9 @@ async function createTable(columns, tableConfig, theme, themeName, _options = {}
         const cellChildren = await processCellContent(
           headerCell?.content,
           mergedDefaults,
-          tableStyle.tableHeader
+          tableStyle.tableHeader,
+          headerCell?.comment,
+          headerCell?.revision
         );
         const horizontalAlignment = mergedDefaults.horizontalAlignment;
         const verticalAlignment = getVerticalAlignment(
@@ -5453,7 +5864,7 @@ async function createTable(columns, tableConfig, theme, themeName, _options = {}
         );
         return new TableCell({
           children: [
-            new Paragraph({
+            new Paragraph3({
               ...tableConfig.keepInOnePage && { keepNext: true },
               spacing: tableStyle.headerParagraph,
               alignment: getAlignment(horizontalAlignment),
@@ -5496,6 +5907,10 @@ async function createTable(columns, tableConfig, theme, themeName, _options = {}
   const dataRows = await Promise.all(
     Array.from({ length: numRows }, async (_, rowIndex) => {
       const isLastRow = rowIndex === numRows - 1;
+      const rowProps = tableConfig.rows?.[rowIndex];
+      const rowRevision = rowProps?.revision;
+      const rowRevisionAttributes = rowRevision ? createRevisionMark(rowRevision) : void 0;
+      const paragraphMarks = rowRevision ? columns.map(() => ({ run: createRevisionMark(rowRevision) })) : void 0;
       const rowHeight = columns.reduce(
         (maxHeight, column, colIndex) => {
           const cell = column.cells?.[rowIndex];
@@ -5525,6 +5940,14 @@ async function createTable(columns, tableConfig, theme, themeName, _options = {}
       );
       return new TableRow({
         height: rowHeight !== void 0 ? { value: rowHeight * 20, rule: "atLeast" } : void 0,
+        ...rowProps?.cantSplit !== void 0 && {
+          cantSplit: rowProps.cantSplit
+        },
+        ...rowProps?.tableHeader !== void 0 && {
+          tableHeader: rowProps.tableHeader
+        },
+        // w:trPr/w:ins | w:del — the row itself was inserted or deleted.
+        ...rowRevisionAttributes,
         children: await Promise.all(
           columns.map(async (column, colIndex) => {
             const cell = column.cells?.[rowIndex];
@@ -5548,10 +5971,11 @@ async function createTable(columns, tableConfig, theme, themeName, _options = {}
               );
               return new TableCell({
                 children: [
-                  new Paragraph({
+                  new Paragraph3({
                     ...tableConfig.keepInOnePage && !isLastRow || isLastRow && tableConfig.keepNext ? { keepNext: true } : {},
                     spacing: tableStyle.cellParagraph,
                     alignment: AlignmentType2.LEFT,
+                    ...paragraphMarks?.[colIndex],
                     children: []
                   })
                 ],
@@ -5616,7 +6040,10 @@ async function createTable(columns, tableConfig, theme, themeName, _options = {}
             const cellChildren = await processCellContent(
               cell.content,
               mergedDefaults,
-              tableStyle.tableCell
+              tableStyle.tableCell,
+              cell.comment,
+              cell.revision,
+              rowRevision
             );
             const horizontalAlignment = mergedDefaults.horizontalAlignment;
             const verticalAlignment = getVerticalAlignment(
@@ -5624,10 +6051,11 @@ async function createTable(columns, tableConfig, theme, themeName, _options = {}
             );
             return new TableCell({
               children: [
-                new Paragraph({
+                new Paragraph3({
                   ...tableConfig.keepInOnePage && !isLastRow || isLastRow && tableConfig.keepNext ? { keepNext: true } : {},
                   spacing: tableStyle.cellParagraph,
                   alignment: getAlignment(horizontalAlignment),
+                  ...paragraphMarks?.[colIndex],
                   children: cellChildren
                 })
               ],
@@ -5786,7 +6214,9 @@ function renderHeadingComponent(component, theme, themeName) {
       // Bookmark ID for internal linking
       bookmarkId,
       // Tracked-change segments (rendered as native Word revisions)
-      revision: config.revision
+      revision: config.revision,
+      // Review comment anchored to this heading's text
+      comment: config.comment
     }
   );
   return [header];
@@ -5794,7 +6224,7 @@ function renderHeadingComponent(component, theme, themeName) {
 
 // src/utils/numberingConfig.ts
 import { AlignmentType as AlignmentType3, convertInchesToTwip, LevelFormat } from "docx";
-import { AsyncLocalStorage as AsyncLocalStorage4 } from "async_hooks";
+import { AsyncLocalStorage as AsyncLocalStorage6 } from "async_hooks";
 var LEVEL_FORMAT_MAP = {
   decimal: LevelFormat.DECIMAL,
   upperRoman: LevelFormat.UPPER_ROMAN,
@@ -5872,6 +6302,21 @@ function getAlignment2(alignment) {
   if (!alignment) return AlignmentType3.LEFT;
   return ALIGNMENT_MAP[alignment] || AlignmentType3.LEFT;
 }
+function createMarkerRunStyle(font) {
+  if (!font) return void 0;
+  const run = {
+    ...font.family && { font: font.family },
+    // docx run sizes are half-points.
+    ...font.size !== void 0 && { size: font.size * 2 },
+    ...font.color && { color: font.color },
+    ...font.bold !== void 0 && { bold: font.bold },
+    ...font.italic !== void 0 && { italics: font.italic },
+    ...font.underline !== void 0 && {
+      underline: font.underline ? { type: "single" } : void 0
+    }
+  };
+  return Object.keys(run).length > 0 ? run : void 0;
+}
 function createNumberingConfig(config) {
   const levels = [];
   for (const levelConfig of config.levels) {
@@ -5880,6 +6325,7 @@ function createNumberingConfig(config) {
     const text = levelConfig.text || (format2 === LevelFormat.BULLET ? "\u2022" : `%${levelConfig.level + 1}.`);
     const baseIndent = levelConfig.indent?.left !== void 0 ? levelConfig.indent.left / 72 : 0.5 * (levelConfig.level + 1);
     const hangingIndent = levelConfig.indent?.hanging !== void 0 ? levelConfig.indent.hanging / 72 : 0.25;
+    const markerRun = createMarkerRunStyle(levelConfig.font);
     const level = {
       level: levelConfig.level,
       format: format2,
@@ -5891,7 +6337,10 @@ function createNumberingConfig(config) {
             left: convertInchesToTwip(baseIndent),
             hanging: convertInchesToTwip(hangingIndent)
           }
-        }
+        },
+        // The marker glyph carries its own run properties; without this it
+        // inherits whatever the list paragraph resolves to.
+        ...markerRun && { run: markerRun }
       },
       // Add start number if specified
       ...levelConfig.start !== void 0 && { start: levelConfig.start }
@@ -5908,7 +6357,7 @@ var NumberingRegistry = class {
     configs: /* @__PURE__ */ new Map(),
     counter: 0
   };
-  scopes = new AsyncLocalStorage4();
+  scopes = new AsyncLocalStorage6();
   get state() {
     return this.scopes.getStore() ?? this.fallback;
   }
@@ -6020,7 +6469,10 @@ function renderParagraphComponent(component, theme, themeName) {
     return createList(listData.items, theme, themeName, {
       numberingReference: reference,
       spacing: resolvedConfig.spacing,
-      alignment: resolvedConfig.alignment
+      alignment: resolvedConfig.alignment,
+      comment: resolvedConfig.comment,
+      footnotes: resolvedConfig.footnotes,
+      endnotes: resolvedConfig.endnotes
     });
   }
   const styleFromTheme = (() => {
@@ -6084,12 +6536,18 @@ function renderParagraphComponent(component, theme, themeName) {
     // Pass bookmark ID for internal linking
     bookmarkId: resolvedConfig.id,
     // Tracked-change segments (rendered as native Word revisions)
-    revision: resolvedConfig.revision
+    revision: resolvedConfig.revision,
+    // Review comment anchored to this paragraph's text
+    comment: resolvedConfig.comment,
+    // Note bodies for the `[^id]` markers in this paragraph
+    footnotes: resolvedConfig.footnotes,
+    endnotes: resolvedConfig.endnotes
   });
   return [text];
 }
 
 // src/components/list.ts
+init_colorUtils();
 function createLevelsFromSimplifiedProps(props) {
   const levels = [];
   let format2;
@@ -6136,6 +6594,22 @@ function createLevelsFromSimplifiedProps(props) {
   }
   return levels;
 }
+function resolveMarkerFonts(levels, theme) {
+  return levels.map((level) => {
+    const font = level.font;
+    if (!font?.color) return level;
+    return {
+      ...level,
+      font: { ...font, color: resolveColor(font.color, theme) }
+    };
+  });
+}
+function applyListStart(levels, start) {
+  if (start === void 0) return levels;
+  return levels.map(
+    (level) => level.level === 0 && level.start === void 0 ? { ...level, start } : level
+  );
+}
 function getMaxLevelFromItems(items) {
   if (!items || !Array.isArray(items)) {
     return 0;
@@ -6198,7 +6672,10 @@ function renderListComponent(component, theme, themeName) {
     let levels;
     if (resolvedConfig.levels && resolvedConfig.levels.length > 0) {
       levels = fillMissingLevels(
-        resolvedConfig.levels,
+        applyListStart(
+          resolvedConfig.levels,
+          resolvedConfig.start
+        ),
         maxLevel
       );
     } else {
@@ -6207,7 +6684,7 @@ function renderListComponent(component, theme, themeName) {
     }
     const config = {
       reference,
-      levels
+      levels: resolveMarkerFonts(levels, theme)
     };
     const numberingConfig = createNumberingConfig(config);
     globalNumberingRegistry.register(numberingConfig);
@@ -6215,7 +6692,9 @@ function renderListComponent(component, theme, themeName) {
   return createList(resolvedConfig.items, theme, themeName, {
     numberingReference: reference,
     spacing: resolvedConfig.spacing,
-    alignment: resolvedConfig.alignment
+    alignment: resolvedConfig.alignment,
+    // Review comment spanning the whole list
+    comment: resolvedConfig.comment
   });
 }
 
@@ -6306,10 +6785,10 @@ function convertBorders2(bordersConfig, theme) {
 // src/styles/utils/cellUtils.ts
 init_styleHelpers();
 init_colorUtils();
-import { Paragraph as Paragraph2 } from "docx";
+import { Paragraph as Paragraph4 } from "docx";
 function buildCellOptions(children, styleCfg, theme) {
   const cellOpts = {
-    children: children.length ? children : [new Paragraph2({})],
+    children: children.length ? children : [new Paragraph4({})],
     margins: {
       top: styleCfg?.padding?.top ? pointsToTwips(styleCfg.padding.top) : 0,
       right: styleCfg?.padding?.right ? pointsToTwips(styleCfg.padding.right) : 0,
@@ -6512,25 +6991,66 @@ async function renderTableComponent(component, theme, themeName) {
 }
 
 // src/components/section.ts
-import { Paragraph as Paragraph4, BookmarkStart, BookmarkEnd } from "docx";
-function generateSectionBookmarkId(context) {
-  const custom = context.custom ??= {};
-  const state = custom.sectionBookmarks ??= {
-    next: 1
-  };
-  const ordinal = state.next++;
-  const linkId = 1e6 + ordinal;
-  return {
-    id: `_NestedSection_${ordinal}`,
-    linkId
-  };
-}
+import { Paragraph as Paragraph6, BookmarkStart, BookmarkEnd } from "docx";
+
+// src/core/sectionBookmarks.ts
+import { AsyncLocalStorage as AsyncLocalStorage7 } from "async_hooks";
+var NESTED_LINK_ID_BASE = 1e6;
+function createState3() {
+  return { nextNested: 1, resolved: /* @__PURE__ */ new WeakMap() };
+}
+var SectionBookmarkRegistry = class {
+  fallback = createState3();
+  scopes = new AsyncLocalStorage7();
+  get state() {
+    return this.scopes.getStore() ?? this.fallback;
+  }
+  /** Run work with an isolated registry that follows its async call chain. */
+  runScoped(callback) {
+    return this.scopes.run(createState3(), callback);
+  }
+  /**
+   * The bookmark for a layout section, derived from its ordinal.
+   *
+   * Every layout chunk of one user-defined section shares an ordinal (see
+   * `computeSectionOrdinals`), so they all resolve to the same bookmark — which
+   * is the point: the start lands in the first chunk and the end in the last.
+   */
+  forLayoutSection(ordinal) {
+    return { id: `_Section_${ordinal}`, linkId: ordinal };
+  }
+  /**
+   * The bookmark for a `section` component, allocated on first sight and
+   * remembered so re-resolving the same component never allocates twice.
+   */
+  forSectionComponent(component) {
+    const state = this.state;
+    const existing = state.resolved.get(component);
+    if (existing) return existing;
+    const ordinal = state.nextNested++;
+    const bookmark = {
+      id: `_NestedSection_${ordinal}`,
+      linkId: NESTED_LINK_ID_BASE + ordinal
+    };
+    state.resolved.set(component, bookmark);
+    return bookmark;
+  }
+  /** Test-only: reset the unscoped fallback counters. */
+  clear() {
+    if (!this.scopes.getStore()) {
+      this.fallback = createState3();
+    }
+  }
+};
+var globalSectionBookmarkRegistry = new SectionBookmarkRegistry();
+
+// src/components/section.ts
 async function renderSectionComponent(component, theme, themeName, context) {
   if (!isSectionComponent(component)) return [];
   const elements = [];
-  const { id: sectionBookmarkId, linkId: bookmarkLinkId } = generateSectionBookmarkId(context);
+  const { id: sectionBookmarkId, linkId: bookmarkLinkId } = globalSectionBookmarkRegistry.forSectionComponent(component);
   elements.push(
-    new Paragraph4({
+    new Paragraph6({
       children: [new BookmarkStart(sectionBookmarkId, bookmarkLinkId)],
       spacing: {
         before: 0,
@@ -6558,7 +7078,7 @@ async function renderSectionComponent(component, theme, themeName, context) {
     }
   }
   elements.push(
-    new Paragraph4({
+    new Paragraph6({
       children: [new BookmarkEnd(bookmarkLinkId)],
       spacing: {
         before: 0,
@@ -6572,7 +7092,7 @@ async function renderSectionComponent(component, theme, themeName, context) {
 
 // src/components/columns.ts
 import {
-  Paragraph as Paragraph5,
+  Paragraph as Paragraph7,
   Table as Table5,
   TableRow as TableRow3,
   TableCell as TableCell3,
@@ -6664,7 +7184,7 @@ async function renderColumnsAsTable(component, theme, themeName, context) {
       columnElements.push(...rendered);
     }
     if (columnElements.length === 0) {
-      columnElements.push(new Paragraph5({}));
+      columnElements.push(new Paragraph7({}));
     }
     cells.push(
       new TableCell3({
@@ -6715,12 +7235,34 @@ function renderStatisticComponent(component, _theme) {
 
 // src/components/toc/index.ts
 import {
-  Paragraph as Paragraph6,
+  Paragraph as Paragraph8,
   TableOfContents,
   AlignmentType as AlignmentType4,
-  TextRun as TextRun5,
+  TextRun as TextRun8,
   StyleLevel
 } from "docx";
+function toStyleDisplayName(styleId) {
+  return styleId.replace(/([A-Z])/g, " $1").replace(/[-_]+/g, " ").replace(/\s+/g, " ").trim();
+}
+function selectCachedEntries(collected, options) {
+  if (!collected || collected.length === 0) return [];
+  const { depthStart, depthEnd, sectionBookmarkId, styleLevels } = options;
+  const entries = [];
+  for (const entry of collected) {
+    if (sectionBookmarkId && entry.sectionBookmarkId !== sectionBookmarkId) {
+      continue;
+    }
+    if (entry.styleId !== void 0) {
+      const level = styleLevels.get(entry.styleId) ?? styleLevels.get(toStyleDisplayName(entry.styleId));
+      if (level === void 0) continue;
+      entries.push({ title: entry.title, level });
+      continue;
+    }
+    if (entry.level < depthStart || entry.level > depthEnd) continue;
+    entries.push({ title: entry.title, level: entry.level });
+  }
+  return entries;
+}
 function parseDepthRange(rawDepth, fieldName, defaultFrom = 1, defaultTo = 3) {
   if (typeof rawDepth !== "object" || rawDepth === null) {
     throw new Error(
@@ -6776,9 +7318,9 @@ function renderTocComponent(component, theme, context) {
   const paragraphs = [];
   if (componentProps.title) {
     paragraphs.push(
-      new Paragraph6({
+      new Paragraph8({
         children: [
-          new TextRun5({
+          new TextRun8({
             text: componentProps.title,
             bold: true,
             size: 28
@@ -6796,11 +7338,14 @@ function renderTocComponent(component, theme, context) {
     );
   }
   const stylesWithLevels = [];
+  const styleLevels = /* @__PURE__ */ new Map();
   if (componentProps.styles && componentProps.styles.length > 0) {
     for (const styleMapping of componentProps.styles) {
       const styleId = styleMapping.styleId;
       const isCustomStyle = !!theme.styles && Object.prototype.hasOwnProperty.call(theme.styles, styleId);
-      const styleDisplayName = isCustomStyle ? styleId.replace(/([A-Z])/g, " $1").replace(/[-_]+/g, " ").replace(/\s+/g, " ").trim() : styleId;
+      const styleDisplayName = isCustomStyle ? toStyleDisplayName(styleId) : styleId;
+      styleLevels.set(styleId, styleMapping.level);
+      styleLevels.set(styleDisplayName, styleMapping.level);
       stylesWithLevels.push(
         new StyleLevel(styleDisplayName, styleMapping.level)
       );
@@ -6808,6 +7353,12 @@ function renderTocComponent(component, theme, context) {
   }
   const effectiveDepthStart = depthStart;
   const effectiveDepthEnd = depthEnd;
+  const cachedEntries = selectCachedEntries(context?.tocHeadings, {
+    depthStart,
+    depthEnd,
+    sectionBookmarkId,
+    styleLevels
+  });
   const tocOptions = {
     hyperlink: true,
     // Enable clickable hyperlinks (\h switch)
@@ -6846,7 +7397,10 @@ function renderTocComponent(component, theme, context) {
     // default to tab
   };
   paragraphs.push(
-    new TableOfContents(componentProps.title ?? "Table of Contents", tocOptions)
+    new TableOfContents(componentProps.title ?? "Table of Contents", {
+      ...tocOptions,
+      ...cachedEntries.length > 0 && { cachedEntries }
+    })
   );
   return paragraphs;
 }
@@ -7395,6 +7949,78 @@ async function prerasterizeVisuals(root, serviceConfig, options = {}) {
   return map;
 }
 
+// src/core/sectionOrdinals.ts
+function computeSectionOrdinals(sections) {
+  let counter = 0;
+  return sections.map((section, index) => {
+    if (!section.belongsToUserSection) {
+      if (section.isUserSection) counter++;
+      return { closeBookmark: false };
+    }
+    const ordinal = section.isUserSection ? counter + 1 : counter;
+    if (section.isUserSection) counter++;
+    const next = sections[index + 1];
+    const closeBookmark = !next || !next.belongsToUserSection || next.isUserSection;
+    return { ordinal, closeBookmark };
+  });
+}
+
+// src/core/collectTocHeadings.ts
+import { getStandardComponent } from "@json-to-office/shared-docx";
+function normalizeEntryTitle(text) {
+  return normalizeUnicodeText(text).replace(/(\*\*\*|___)([\s\S]*?)\1/g, "$2").replace(/(\*\*|__)([\s\S]*?)\1/g, "$2").replace(/(\*|_)([\s\S]*?)\1/g, "$2").trim();
+}
+function isContainer(name) {
+  return getStandardComponent(name)?.hasChildren === true;
+}
+function isEnabled(component) {
+  return !("enabled" in component && component.enabled === false);
+}
+function styleEntryKey(props) {
+  const themeStyle = props.themeStyle;
+  if (typeof themeStyle !== "string" || !themeStyle) return void 0;
+  if (/^heading[1-6]$/i.test(themeStyle)) return void 0;
+  if (["normal", "title", "subtitle"].includes(themeStyle.toLowerCase())) {
+    return void 0;
+  }
+  return themeStyle;
+}
+function collectTocHeadings(sections) {
+  const entries = [];
+  const ordinals = computeSectionOrdinals(sections);
+  sections.forEach((section, index) => {
+    const ordinal = ordinals[index]?.ordinal;
+    const sectionBookmarkId = ordinal ? globalSectionBookmarkRegistry.forLayoutSection(ordinal).id : void 0;
+    const visit = (component) => {
+      if (!isEnabled(component)) return;
+      const props = component.props ?? {};
+      if (component.name === "heading") {
+        const text = typeof props.text === "string" ? props.text : "";
+        const title = normalizeEntryTitle(text);
+        if (title) {
+          const level = typeof props.level === "number" ? props.level : 1;
+          entries.push({ title, level, sectionBookmarkId });
+        }
+        return;
+      }
+      if (component.name === "paragraph") {
+        const styleId = styleEntryKey(props);
+        const text = typeof props.text === "string" ? props.text : "";
+        const title = normalizeEntryTitle(text);
+        if (styleId && title) {
+          entries.push({ title, level: 1, styleId, sectionBookmarkId });
+        }
+        return;
+      }
+      if (!isContainer(component.name)) return;
+      const children = component.children;
+      if (Array.isArray(children)) children.forEach(visit);
+    };
+    section.components.forEach(visit);
+  });
+  return entries;
+}
+
 // src/core/render.ts
 function getAlignment3(alignment) {
   switch (alignment) {
@@ -7432,7 +8058,23 @@ async function renderDocument(structure, layout, options) {
       () => globalBookmarkRegistry.runScoped(
         () => globalRevisionIdRegistry.runScoped(
           () => globalNumberingRegistry.runScoped(
-            () => renderDocumentScoped(structure, layout, options)
+            () => globalSectionBookmarkRegistry.runScoped(
+              () => (
+                // Comment ids are a separate OOXML namespace from w:ins/w:del,
+                // but they need the same per-render isolation: outside this nest
+                // concurrent generations would interleave counters and an anchor
+                // would point at another document's comment body.
+                globalCommentRegistry.runScoped(
+                  () => (
+                    // Footnote ids are document-scoped too: a reference resolved
+                    // against another render's counter points at the wrong body.
+                    globalNoteRegistry.runScoped(
+                      () => renderDocumentScoped(structure, layout, options)
+                    )
+                  )
+                )
+              )
+            )
           )
         )
       )
@@ -7467,19 +8109,23 @@ async function renderDocumentScoped(structure, layout, options) {
       error instanceof Error ? error.message : error
     );
   }
-  let sectionBookmarkCounter = 0;
+  try {
+    const tocHeadings = collectTocHeadings(layout.sections);
+    if (tocHeadings.length > 0) {
+      context.tocHeadings = tocHeadings;
+    }
+  } catch (error) {
+    console.warn(
+      "[core-docx] TOC entry collection failed; the TOC field will rely on the reader refreshing it:",
+      error instanceof Error ? error.message : error
+    );
+  }
+  const sectionOrdinals = computeSectionOrdinals(layout.sections);
   let previousHeader = void 0;
   let previousFooter = void 0;
   for (let idx = 0; idx < layout.sections.length; idx++) {
     const layoutSection = layout.sections[idx];
-    let sectionOrdinal = void 0;
-    if (layoutSection.belongsToUserSection) {
-      if (layoutSection.isUserSection) {
-        sectionOrdinal = sectionBookmarkCounter + 1;
-      } else {
-        sectionOrdinal = sectionBookmarkCounter;
-      }
-    }
+    const { ordinal: sectionOrdinal, closeBookmark } = sectionOrdinals[idx];
     let headerToUse;
     if (layoutSection.header === "linkToPrevious") {
       headerToUse = previousHeader;
@@ -7503,13 +8149,6 @@ async function renderDocumentScoped(structure, layout, options) {
       header: headerToUse,
       footer: footerToUse
     };
-    let closeBookmark = false;
-    if (layoutSection.belongsToUserSection && sectionOrdinal !== void 0) {
-      const next = layout.sections[idx + 1];
-      if (!next || !next.belongsToUserSection || next.isUserSection) {
-        closeBookmark = true;
-      }
-    }
     const rendered = await renderSection(
       sectionToRender,
       structure.theme,
@@ -7519,14 +8158,14 @@ async function renderDocumentScoped(structure, layout, options) {
       closeBookmark,
       options?.bypassCache === true
     );
-    if (layoutSection.isUserSection) {
-      sectionBookmarkCounter++;
-    }
     if (rendered.children.length > 0) {
       sections.push(rendered);
     }
   }
   const numberingConfigs = globalNumberingRegistry.getAll();
+  const comments = globalCommentRegistry.getAll();
+  const footnotes = globalNoteRegistry.getFootnotes();
+  const endnotes = globalNoteRegistry.getEndnotes();
   return new Document({
     styles: createWordStyles(structure.theme, structure.language),
     sections,
@@ -7537,6 +8176,12 @@ async function renderDocumentScoped(structure, layout, options) {
       // Word opens the document in review mode (further edits are tracked)
       ...structure.trackRevisions && { trackRevisions: true }
     },
+    // word/comments.xml, emitted only when something was actually commented
+    ...comments.length > 0 && { comments: { children: comments } },
+    // word/footnotes.xml and word/endnotes.xml bodies, keyed by the id their
+    // references carry
+    ...Object.keys(footnotes).length > 0 && { footnotes },
+    ...Object.keys(endnotes).length > 0 && { endnotes },
     // Add numbering configurations if any lists were rendered
     ...numberingConfigs.length > 0 && {
       numbering: {
@@ -7583,9 +8228,9 @@ async function renderHeaderFooterComponents(components, theme, themeName, contex
       let imageSource = resolveImageSource(imageComp.props);
       if (!imageSource) {
         elements.push(
-          new Paragraph7({
+          new Paragraph9({
             children: [
-              new TextRun6({
+              new TextRun9({
                 text: "[IMAGE: Missing path, base64, or svg property]",
                 font: getThemeFonts(theme).body.family,
                 size: 20,
@@ -7653,7 +8298,7 @@ async function renderHeaderFooterComponents(components, theme, themeName, contex
           ...floatingOptions && { floating: floatingOptions }
         });
         elements.push(
-          new Paragraph7({
+          new Paragraph9({
             children: [imageRun],
             alignment: imageComp.props.alignment ? getAlignment3(imageComp.props.alignment) : void 0,
             style: "Normal"
@@ -7666,9 +8311,9 @@ async function renderHeaderFooterComponents(components, theme, themeName, contex
           error instanceof Error ? error.message : error
         );
         elements.push(
-          new Paragraph7({
+          new Paragraph9({
             children: [
-              new TextRun6({
+              new TextRun9({
                 text: `[IMAGE: ${sourcePreview}]`,
                 font: getThemeFonts(theme).body.family,
                 size: 20,
@@ -7698,8 +8343,9 @@ async function renderHeaderFooterComponents(components, theme, themeName, contex
 async function renderSection(section, theme, themeName, context, sectionOrdinal, closeBookmark, bypassCache = false) {
   const elements = [];
   const isFirstLayoutOfUserSection = section.isUserSection;
-  const sharedLinkId = section.belongsToUserSection && sectionOrdinal ? sectionOrdinal : void 0;
-  const sectionBookmarkId = sharedLinkId !== void 0 ? `_Section_${sharedLinkId}` : void 0;
+  const bookmark = section.belongsToUserSection && sectionOrdinal ? globalSectionBookmarkRegistry.forLayoutSection(sectionOrdinal) : void 0;
+  const sharedLinkId = bookmark?.linkId;
+  const sectionBookmarkId = bookmark?.id;
   const sectionContext = {
     ...context,
     section: {
@@ -7712,7 +8358,7 @@ async function renderSection(section, theme, themeName, context, sectionOrdinal,
   };
   if (sectionBookmarkId && isFirstLayoutOfUserSection && sharedLinkId !== void 0) {
     elements.push(
-      new Paragraph7({
+      new Paragraph9({
         children: [new BookmarkStart2(sectionBookmarkId, sharedLinkId)],
         spacing: {
           before: 0,
@@ -7737,7 +8383,7 @@ async function renderSection(section, theme, themeName, context, sectionOrdinal,
   }
   if (closeBookmark && sharedLinkId !== void 0) {
     elements.push(
-      new Paragraph7({
+      new Paragraph9({
         children: [new BookmarkEnd2(sharedLinkId)]
       })
     );
@@ -7891,9 +8537,9 @@ function fixFloatingImageIdsInBuffer(buffer) {
     throw new Error("document.xml not found in DOCX");
   }
   let idCounter = 1;
-  const documentXml = documentEntry.getData().toString("utf8").replace(/<wp:docPr\s+id="(\d+)"/g, () => {
+  const documentXml = documentEntry.getData().toString("utf8").replace(/(<wp:docPr\b[^>]*?\s)id="\d+"/g, (_match, prefix) => {
     const newId = idCounter++;
-    return `<wp:docPr id="${newId}"`;
+    return `${prefix}id="${newId}"`;
   });
   zip.updateFile(documentEntry, Buffer.from(documentXml, "utf8"));
   return zip.toBuffer();
@@ -9273,6 +9919,7 @@ export {
   UnknownPreservedComponentError,
   cleanComponentProps,
   clearComponentCache,
+  componentBypassReason,
   corporateTheme,
   createComponent,
   createDocumentGenerator,