docxodus 9.9.0 → 10.0.0

package/dist/embed.iife.js

@@ -154,6 +154,7 @@ var Docxodus = (() => {
     addAnnotation: () => addAnnotation,
     addAnnotationToHtml: () => addAnnotationToHtml,
     addAnnotationWithTarget: () => addAnnotationWithTarget,
+    clearPageCitationHighlight: () => clearPageCitationHighlight,
     compareDocuments: () => compareDocuments,
     compareDocumentsToHtml: () => compareDocumentsToHtml,
     compareDocumentsToHtmlWithLog: () => compareDocumentsToHtmlWithLog,
@@ -168,15 +169,18 @@ var Docxodus = (() => {
     createEditor: () => createEditor,
     createExternalAnnotationSet: () => createExternalAnnotationSet,
     createRibbonEditor: () => createRibbonEditor,
+    createUnavailablePageMap: () => createUnavailablePageMap,
     createViewer: () => createViewer,
     docxDiffAcceptRevisions: () => docxDiffAcceptRevisions,
     docxDiffCompare: () => docxDiffCompare,
+    docxDiffCompareProducts: () => docxDiffCompareProducts,
     docxDiffConsolidate: () => docxDiffConsolidate,
     docxDiffGetConflicts: () => docxDiffGetConflicts,
     docxDiffGetConsolidatedEditScript: () => docxDiffGetConsolidatedEditScript,
     docxDiffGetConsolidatedRevisions: () => docxDiffGetConsolidatedRevisions,
     docxDiffGetEditScript: () => docxDiffGetEditScript,
     docxDiffGetRevisions: () => docxDiffGetRevisions,
+    docxDiffGetSemanticChanges: () => docxDiffGetSemanticChanges,
     docxDiffRejectRevisions: () => docxDiffRejectRevisions,
     exportToOpenContract: () => exportToOpenContract,
     findElementById: () => findElementById,
@@ -186,6 +190,7 @@ var Docxodus = (() => {
     fitScale: () => fitScale,
     generateAnnotationCss: () => generateAnnotationCss,
     generateAnnotationVisibilityCss: () => generateAnnotationVisibilityCss,
+    generatePackageManifest: () => generatePackageManifest,
     getAnnotations: () => getAnnotations,
     getDocumentMetadata: () => getDocumentMetadata,
     getDocumentStructure: () => getDocumentStructure,
@@ -205,10 +210,12 @@ var Docxodus = (() => {
     isMoveDestination: () => isMoveDestination,
     isMoveSource: () => isMoveSource,
     mountRibbon: () => mountRibbon,
+    navigateToPageCitation: () => navigateToPageCitation,
     openDocxSession: () => openDocxSession2,
     paginateHtml: () => paginateHtml,
     parseSectionDimensions: () => parseSectionDimensions,
     projectAnnotationsOntoHtml: () => projectAnnotationsOntoHtml,
+    proveRedlineReversibility: () => proveRedlineReversibility,
     ptToPx: () => ptToPx,
     pxToPt: () => pxToPt,
     removeAnnotation: () => removeAnnotation,
@@ -228,6 +235,8 @@ var Docxodus = (() => {
     targetTableRow: () => targetTableRow,
     toDocumentBytes: () => toDocumentBytes,
     validateExternalAnnotations: () => validateExternalAnnotations,
+    verifyDeliverable: () => verifyDeliverable,
+    verifyDeliveryReceipt: () => verifyDeliveryReceipt,
     wasmBasePath: () => wasmBasePath
   });
 
@@ -480,7 +489,46 @@ var Docxodus = (() => {
   }
 
   // src/session.ts
-  var DocxSession = class {
+  function mutationBatchChangeSet(before, after, key) {
+    const beforeGroups = /* @__PURE__ */ new Map();
+    const afterGroups = /* @__PURE__ */ new Map();
+    const group = (items, target) => {
+      items.forEach((item, index) => {
+        const identity = key(item);
+        const indices = target.get(identity) ?? [];
+        indices.push(index);
+        target.set(identity, indices);
+      });
+    };
+    group(before, beforeGroups);
+    group(after, afterGroups);
+    const beforeMatched = before.map(() => false);
+    const afterMatched = after.map(() => false);
+    const modified = after.map(() => false);
+    for (const [identity, afterIndices] of afterGroups) {
+      const beforeIndices = beforeGroups.get(identity) ?? [];
+      for (const afterIndex of afterIndices) {
+        const beforeIndex = beforeIndices.find((index) => !beforeMatched[index] && JSON.stringify(before[index]) === JSON.stringify(after[afterIndex]));
+        if (beforeIndex === void 0) continue;
+        beforeMatched[beforeIndex] = true;
+        afterMatched[afterIndex] = true;
+      }
+      const remainingBefore = beforeIndices.filter((index) => !beforeMatched[index]);
+      const remainingAfter = afterIndices.filter((index) => !afterMatched[index]);
+      const modifiedCount = Math.min(remainingBefore.length, remainingAfter.length);
+      for (let index = 0; index < modifiedCount; index++) {
+        beforeMatched[remainingBefore[index]] = true;
+        afterMatched[remainingAfter[index]] = true;
+        modified[remainingAfter[index]] = true;
+      }
+    }
+    return {
+      added: after.filter((_, index) => !afterMatched[index]),
+      removed: before.filter((_, index) => !beforeMatched[index]),
+      modified: after.filter((_, index) => modified[index])
+    };
+  }
+  var DocxSession = class _DocxSession {
     /** @internal */
     constructor(handle, wasm) {
       // ─── Raw escape hatch ────────────────────────────────────────────────
@@ -496,6 +544,336 @@ var Docxodus = (() => {
     project() {
       return JSON.parse(this.wasm.Project(this.handle));
     }
+    /** Monotonic document version (0 at open; +1 per committed mutation/undo/redo). */
+    getVersion() {
+      return JSON.parse(this.wasm.GetVersion(this.handle)).version;
+    }
+    /**
+     * Verification manifest for the current logical checkpoint. Unsaved edits are included and
+     * the read does not mutate package bytes, caches, history, or the document version.
+     */
+    getPackageManifest() {
+      return JSON.parse(this.wasm.GetPackageManifest(this.handle));
+    }
+    /** Register a browser-materialized PageMap without changing the document version. */
+    registerPageMap(pageMap, expectedRendererFingerprint) {
+      return JSON.parse(this.wasm.RegisterPageMap(
+        this.handle,
+        JSON.stringify(pageMap),
+        expectedRendererFingerprint ?? ""
+      ));
+    }
+    getPageMapStatus(request) {
+      return JSON.parse(this.wasm.GetPageMapStatus(
+        this.handle,
+        request ? JSON.stringify(request) : ""
+      ));
+    }
+    getPageCitation(anchorId, request) {
+      return JSON.parse(this.wasm.GetPageCitation(
+        this.handle,
+        anchorId,
+        JSON.stringify(request)
+      ));
+    }
+    /** Evaluate optimistic guards without mutating or advancing the version. */
+    checkPreconditions(preconditions) {
+      return JSON.parse(
+        this.wasm.CheckPreconditions(this.handle, JSON.stringify(preconditions))
+      );
+    }
+    /**
+     * Guard any synchronous mutation. WASM calls are synchronous and single-threaded, so the
+     * check and callback form one uninterrupted client-side operation. Prefer a method's native
+     * `preconditions` option where it has one (notably replaceTextRange's match-count guard).
+     */
+    runWithPreconditions(preconditions, mutation) {
+      const checked = this.checkPreconditions(preconditions);
+      return checked.success ? mutation() : checked;
+    }
+    /**
+     * Execute synchronous mutations atomically by default. Atomic success is one undo/version
+     * unit; any failed or thrown step restores the exact package and history checkpoint.
+     */
+    executeBatch(steps, mode = "atomic") {
+      if (mode !== "atomic" && mode !== "best_effort") {
+        throw new RangeError(`unknown mutation batch mode: ${String(mode)}`);
+      }
+      const baseVersion = this.getVersion();
+      const observationWarnings = [];
+      const inspect = (label, read, fallback) => {
+        try {
+          return read();
+        } catch (error) {
+          observationWarnings.push(`${label} unavailable: ${error instanceof Error ? error.message : String(error)}`);
+          return fallback;
+        }
+      };
+      const beforeRevisions = inspect("Revision delta inspection", () => this.listRevisions(), []);
+      const beforeComments = inspect("Comment delta inspection", () => this.listComments(), []);
+      const beforeAnnotations = inspect("Annotation delta inspection", () => this.listAnnotations(), []);
+      const complete = (result) => {
+        try {
+          const revisionChanges = mutationBatchChangeSet(
+            beforeRevisions,
+            inspect("Revision delta inspection", () => this.listRevisions(), beforeRevisions),
+            (revision) => revision.id
+          );
+          const commentChanges = mutationBatchChangeSet(
+            beforeComments,
+            inspect("Comment delta inspection", () => this.listComments(), beforeComments),
+            (comment) => comment.anchorId
+          );
+          const annotationChanges = mutationBatchChangeSet(
+            beforeAnnotations,
+            inspect("Annotation delta inspection", () => this.listAnnotations(), beforeAnnotations),
+            (annotation) => annotation.id ?? ""
+          );
+          const resultVersion = inspect(
+            "Result version inspection",
+            () => this.getVersion(),
+            baseVersion
+          );
+          const warnings = [...observationWarnings];
+          if ([...revisionChanges.added, ...revisionChanges.modified].some((revision) => revision.date !== void 0 && revision.date !== null)) {
+            warnings.push("Tracked-revision date attributes may use the execution clock; compare revision ids, authors, types, text, and anchors across separate executions.");
+          }
+          if ([...commentChanges.added, ...commentChanges.modified].some((comment) => comment.date !== void 0 && comment.date !== null)) {
+            warnings.push("Comment date attributes may be generated from the execution clock; supply dates explicitly when byte-identical replay is required.");
+          }
+          if (annotationChanges.added.some((annotation) => annotation.created !== void 0 && annotation.created !== null)) {
+            warnings.push("Auto-generated annotation ids or creation timestamps are execution metadata; supply id and created explicitly when byte-identical replay is required.");
+          }
+          if (result.steps.some((step) => step.results.some((edit) => edit.created.length > 0))) {
+            warnings.push("Created anchors and related OOXML ids may be generated independently on replay; preview/apply equivalence is semantic and packageHash or anchor ids may differ.");
+          }
+          if (mode === "best_effort" && !result.success) {
+            warnings.push("Best-effort execution retains every successful step despite later failures.");
+          }
+          let packageHash = null;
+          if (!this.wasm.GetPackageContentHash) {
+            warnings.push("This WASM bundle predates package equivalence hashes; packageHash is unavailable.");
+          } else {
+            try {
+              packageHash = this.wasm.GetPackageContentHash(this.handle);
+            } catch (error) {
+              warnings.push(`Package equivalence hash unavailable: ${error instanceof Error ? error.message : String(error)}`);
+            }
+          }
+          return {
+            ...result,
+            preview: false,
+            baseVersion,
+            resultVersion,
+            packageHash,
+            revisionChanges,
+            commentChanges,
+            annotationChanges,
+            warnings,
+            html: null
+          };
+        } catch (error) {
+          return {
+            ...result,
+            preview: false,
+            baseVersion,
+            resultVersion: inspect("Result version inspection", () => this.getVersion(), baseVersion),
+            packageHash: null,
+            revisionChanges: { added: [], removed: [], modified: [] },
+            commentChanges: { added: [], removed: [], modified: [] },
+            annotationChanges: { added: [], removed: [], modified: [] },
+            warnings: [
+              ...observationWarnings,
+              `Batch receipt enrichment unavailable: ${error instanceof Error ? error.message : String(error)}`
+            ],
+            html: null
+          };
+        }
+      };
+      const internalFailure = (value) => ({
+        success: false,
+        error: { code: "internal_error", message: value instanceof Error ? value.message : String(value) },
+        created: [],
+        removed: [],
+        modified: []
+      });
+      const run = (step) => {
+        try {
+          const value = step.mutation();
+          const results = Array.isArray(value) ? value : [value];
+          if (results.some((result) => result === null || typeof result !== "object" || typeof result.success !== "boolean")) {
+            return [internalFailure("batch mutation returned invalid edit results")];
+          }
+          return results;
+        } catch (error) {
+          return [internalFailure(error)];
+        }
+      };
+      const failureOf = (step, rolledBack) => ({
+        index: step.index,
+        tool: step.tool,
+        action: step.action,
+        error: step.results.find((result) => !result.success)?.error ?? { code: "internal_error", message: "batch step failed without an error" },
+        rolledBack
+      });
+      const preflightOne = (step) => {
+        try {
+          return step.preflight?.();
+        } catch (error) {
+          return internalFailure(error).error;
+        }
+      };
+      if (mode === "atomic") {
+        const preflight = steps.map(preflightOne);
+        const failedPreflight = preflight.findIndex((error) => error !== void 0);
+        if (failedPreflight >= 0) {
+          const source = steps[failedPreflight];
+          const failed2 = {
+            index: failedPreflight,
+            tool: source.tool,
+            action: source.action,
+            success: false,
+            rolledBack: true,
+            results: [{ success: false, error: preflight[failedPreflight], created: [], removed: [], modified: [] }]
+          };
+          return complete({
+            mode,
+            status: "failed",
+            success: false,
+            rolledBack: true,
+            steps: [failed2],
+            failure: failureOf(failed2, true)
+          });
+        }
+        const transaction = this.wasm.BeginTransaction(this.handle);
+        const completed2 = [];
+        try {
+          for (let index = 0; index < steps.length; index++) {
+            const source = steps[index];
+            const results = run(source);
+            const step = {
+              index,
+              tool: source.tool,
+              action: source.action,
+              success: results.every((result) => result.success),
+              rolledBack: false,
+              results
+            };
+            completed2.push(step);
+            if (!step.success) {
+              this.wasm.RollbackTransaction(transaction);
+              const rolledBack = completed2.map((value) => ({ ...value, rolledBack: true }));
+              const failed2 = rolledBack[rolledBack.length - 1];
+              return complete({
+                mode,
+                status: "failed",
+                success: false,
+                rolledBack: true,
+                steps: rolledBack,
+                failure: failureOf(failed2, true)
+              });
+            }
+          }
+          this.wasm.CommitTransaction(transaction);
+          return complete({ mode, status: "ok", success: true, rolledBack: false, steps: completed2 });
+        } catch (error) {
+          try {
+            this.wasm.RollbackTransaction(transaction);
+          } catch {
+          }
+          throw error;
+        }
+      }
+      const completed = steps.map((source, index) => {
+        const preflight = preflightOne(source);
+        const results = preflight ? [{ success: false, error: preflight, created: [], removed: [], modified: [] }] : run(source);
+        return {
+          index,
+          tool: source.tool,
+          action: source.action,
+          success: results.every((result) => result.success),
+          rolledBack: false,
+          results
+        };
+      });
+      const failed = completed.find((step) => !step.success);
+      return complete({
+        mode,
+        status: failed ? completed.some((step) => step.success) ? "partial" : "failed" : "ok",
+        success: failed === void 0,
+        rolledBack: false,
+        steps: completed,
+        failure: failed ? failureOf(failed, false) : void 0
+      });
+    }
+    /**
+     * Execute the same callback batch algorithm against a complete isolated package clone.
+     * Callbacks receive the shadow session explicitly; mutate that argument. The live session's
+     * package, caches, version, configuration, and undo/redo history are never execution targets.
+     */
+    previewBatch(steps, mode = "atomic", options) {
+      if (mode !== "atomic" && mode !== "best_effort") {
+        throw new RangeError(`unknown mutation batch mode: ${String(mode)}`);
+      }
+      const htmlMode = options?.html ?? "none";
+      if (htmlMode !== "none" && htmlMode !== "scoped" && htmlMode !== "full") {
+        throw new RangeError(`unknown preview HTML mode: ${String(htmlMode)}`);
+      }
+      if (!this.wasm.OpenPreviewSession) {
+        throw new Error("This WASM bundle does not support isolated mutation previews.");
+      }
+      const shadow = new _DocxSession(this.wasm.OpenPreviewSession(this.handle), this.wasm);
+      try {
+        const result = shadow.executeBatch(
+          steps.map((step) => ({
+            tool: step.tool,
+            action: step.action,
+            mutation: () => step.mutation(shadow),
+            preflight: step.preflight ? () => step.preflight(shadow) : void 0
+          })),
+          mode
+        );
+        const warnings = [...result.warnings];
+        let html = null;
+        const unwrapRendered = (rendered) => {
+          if (rendered.trimStart().startsWith("{")) {
+            const envelope = JSON.parse(rendered);
+            if (envelope.error) {
+              warnings.push(`Preview HTML could not be generated: ${envelope.error}`);
+              return null;
+            }
+          }
+          return rendered;
+        };
+        const legacyProfileWarning = "This WASM bundle predates the shared preview HTML profile; preview HTML omits comments, annotations and headers/footers and may differ from other surfaces.";
+        try {
+          if (htmlMode === "scoped") {
+            if (!options?.htmlAnchorId) {
+              warnings.push("Scoped HTML was requested without htmlAnchorId; no HTML was generated.");
+            } else if (this.wasm.RenderPreviewBlockHtml) {
+              html = unwrapRendered(
+                this.wasm.RenderPreviewBlockHtml(shadow.handle, options.htmlAnchorId)
+              );
+            } else {
+              warnings.push(legacyProfileWarning);
+              html = shadow.renderBlock(options.htmlAnchorId);
+            }
+          } else if (htmlMode === "full") {
+            if (this.wasm.RenderPreviewHtml) {
+              html = unwrapRendered(this.wasm.RenderPreviewHtml(shadow.handle));
+            } else {
+              warnings.push(legacyProfileWarning);
+              html = unwrapRendered(this.wasm.RenderHtmlForReview ? this.wasm.RenderHtmlForReview(shadow.handle, "docx-", false, false, 1, true) : this.wasm.RenderHtml(shadow.handle, "docx-", false, false, 1));
+            }
+          }
+        } catch (error) {
+          warnings.push(`Preview HTML could not be generated: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return { ...result, preview: true, warnings, html };
+      } finally {
+        shadow.close();
+      }
+    }
     /**
      * Project a slice of the document keyed off an anchor — useful for showing
      * one section to an LLM at a time without paying the cost of projecting the
@@ -511,9 +889,9 @@ var Docxodus = (() => {
      *
      * @see docs/architecture/docx_mutation_api.md
      */
-    projectAnchor(anchorId, depth = 2 /* SubtreeAndFollowingSiblings */) {
+    projectAnchor(anchorId, depth = 2 /* SubtreeAndFollowingSiblings */, citation) {
       return JSON.parse(
-        this.wasm.ProjectAnchor(this.handle, anchorId, depth)
+        citation ? this.wasm.ProjectAnchorWithCitations(this.handle, anchorId, depth, JSON.stringify(citation)) : this.wasm.ProjectAnchor(this.handle, anchorId, depth)
       );
     }
     /**
@@ -537,11 +915,21 @@ var Docxodus = (() => {
       return html;
     }
     // ─── Tier A: text CRUD ───────────────────────────────────────────────
-    replaceText(anchorId, markdown) {
-      return JSON.parse(this.wasm.ReplaceText(this.handle, anchorId, markdown));
-    }
-    deleteBlock(anchorId) {
-      return JSON.parse(this.wasm.DeleteBlock(this.handle, anchorId));
+    replaceText(anchorId, markdown, preconditions) {
+      const apply = () => JSON.parse(
+        this.wasm.ReplaceText(this.handle, anchorId, markdown)
+      );
+      return preconditions ? this.runWithPreconditions(
+        { ...preconditions, anchorId: preconditions.anchorId ?? anchorId },
+        apply
+      ) : apply();
+    }
+    deleteBlock(anchorId, preconditions) {
+      const apply = () => JSON.parse(this.wasm.DeleteBlock(this.handle, anchorId));
+      return preconditions ? this.runWithPreconditions(
+        { ...preconditions, anchorId: preconditions.anchorId ?? anchorId },
+        apply
+      ) : apply();
     }
     /** Reorder one top-level paragraph/heading/list/table block relative to another. */
     moveBlock(sourceAnchorId, targetAnchorId, position) {
@@ -596,7 +984,7 @@ var Docxodus = (() => {
     }
     /**
      * Insert a `rows`×`cols` table before/after the block. `options` controls borders, row-major
-     * cell markdown, and cell alignment. The returned `EditResult.created` lists the cell-paragraph
+     * cell markdown, and cell alignment. The returned `EditResult.created` lists canonical `tc`
      * anchors (row-major), so each cell can then be addressed to fill/format.
      */
     insertTable(anchorId, position, rows, cols, options) {
@@ -605,10 +993,26 @@ var Docxodus = (() => {
         this.wasm.InsertTable(this.handle, anchorId, position, rows, cols, optionsJson)
       );
     }
+    /** Resolve a canonical `tbl` anchor to explicit table/row/column/cell identities. */
+    getTableMetadata(tableAnchorId) {
+      return JSON.parse(this.wasm.GetTableMetadata(this.handle, tableAnchorId));
+    }
+    /** Resolve a canonical `tc` anchor to its zero-based table-grid coordinate and spans. */
+    resolveTableCellAnchor(cellAnchorId) {
+      return JSON.parse(
+        this.wasm.ResolveTableCellAnchor(this.handle, cellAnchorId)
+      );
+    }
+    /** Resolve a zero-based table-grid coordinate to the physical `tc` covering it. */
+    resolveTableCellCoordinate(tableAnchorId, rowIndex, columnIndex) {
+      return JSON.parse(
+        this.wasm.ResolveTableCellCoordinate(this.handle, tableAnchorId, rowIndex, columnIndex)
+      );
+    }
     /**
-     * Table row/column editing, addressed by a cell-paragraph anchor (e.g. one returned from
-     * {@link insertTable}'s `created`). Insert clones the reference row/column's widths and starts
-     * empty (`created` lists the new cell-paragraph anchors); delete of the last row/column removes
+     * Table row/column editing, addressed by the canonical `tc` anchor returned from
+     * {@link insertTable}'s `created` or table metadata. Insert clones the reference row/column's
+     * widths and starts empty (`created` lists new `tc` anchors); delete of the last row/column removes
      * the whole table. All four are grid-aware: inserting across a merge extends it, deleting
      * through one narrows it, and deleting a vertical merge's lead row promotes the next row to
      * carry it — the grid is never left ragged.
@@ -648,7 +1052,7 @@ var Docxodus = (() => {
       return JSON.parse(this.wasm.UnmergeCells(this.handle, cellAnchorId));
     }
     /**
-     * Table styling, addressed by a cell-paragraph anchor — the post-insert counterpart of
+     * Table styling, addressed by a canonical `tc` anchor — the post-insert counterpart of
      * {@link insertTable}'s options (issue #315 Stage A). `setColumnWidths` retunes `w:tblGrid` +
      * every row's cell width (one positive twip value per column) and pins the table to fixed
      * layout, exactly as inserting with explicit `columnWidths` would.
@@ -688,6 +1092,19 @@ var Docxodus = (() => {
         this.wasm.SetRepeatHeaderRow(this.handle, cellAnchorId, repeat)
       );
     }
+    /** Apply row layout options to the row containing the canonical cell anchor. */
+    setTableRowOptions(cellAnchorId, options) {
+      return JSON.parse(
+        this.wasm.SetTableRowOptions(
+          this.handle,
+          cellAnchorId,
+          options.repeatHeader ?? null,
+          options.allowBreakAcrossPages ?? null,
+          options.heightTwips ?? null,
+          options.heightRule ?? "atLeast"
+        )
+      );
+    }
     // ─── Headers / footers / page numbers ────────────────────────────────
     /**
      * Set the running header story for the section that owns `anchorId` (any body block in that
@@ -782,6 +1199,25 @@ var Docxodus = (() => {
         this.wasm.InsertFootnote(this.handle, anchorId, characterOffset, markdown)
       );
     }
+    /**
+     * Insert a Word-faithful internal cross-reference — a `REF` field targeting an existing
+     * bookmark — at a character offset (issue #545). The field carries a cached result run
+     * (the bookmarked text, or the target's auto-number under `referenceNumber`), so
+     * renderers that do not recompute fields show a faithful snapshot and Word updates it
+     * like a hand-authored cross-reference. A missing or incoherent bookmark fails with
+     * `missing_bookmark_target`.
+     */
+    insertCrossReference(anchorId, characterOffset, bookmarkName, options) {
+      return JSON.parse(
+        this.wasm.InsertCrossReference(
+          this.handle,
+          anchorId,
+          characterOffset,
+          bookmarkName,
+          options ? JSON.stringify(options) : ""
+        )
+      );
+    }
     /** Create an endnote — see {@link insertFootnote}; writes the endnotes part and a
      * `w:endnoteReference`, and the created definition anchor has kind `en`. */
     insertEndnote(anchorId, characterOffset, markdown) {
@@ -873,6 +1309,170 @@ var Docxodus = (() => {
     listComments() {
       return JSON.parse(this.wasm.ListComments(this.handle));
     }
+    listHyperlinks(scopes = 63 /* All */) {
+      return JSON.parse(this.wasm.ListHyperlinks(this.handle, scopes));
+    }
+    addHyperlink(anchorId, span, kind, target) {
+      return JSON.parse(this.wasm.AddHyperlink(
+        this.handle,
+        anchorId,
+        span.start,
+        span.length,
+        kind,
+        target
+      ));
+    }
+    updateHyperlink(hyperlinkId, kind, target) {
+      return JSON.parse(this.wasm.UpdateHyperlink(this.handle, hyperlinkId, kind, target));
+    }
+    removeHyperlink(hyperlinkId) {
+      return JSON.parse(this.wasm.RemoveHyperlink(this.handle, hyperlinkId));
+    }
+    /** Versioned operational facts for native image inspection/mutation in this runtime. */
+    getImageCapabilities() {
+      return JSON.parse(this.wasm.GetImageCapabilities());
+    }
+    listImages(scopes = 63 /* All */) {
+      return JSON.parse(this.wasm.ListImages(this.handle, scopes));
+    }
+    insertImage(anchorId, characterOffset, bytes, options = {}) {
+      return JSON.parse(this.wasm.InsertImage(
+        this.handle,
+        anchorId,
+        characterOffset,
+        imageBytesToBase64(bytes),
+        JSON.stringify(options)
+      ));
+    }
+    replaceImage(imageId, bytes) {
+      return JSON.parse(this.wasm.ReplaceImage(
+        this.handle,
+        imageId,
+        imageBytesToBase64(bytes)
+      ));
+    }
+    setImageDimensions(imageId, dimensions) {
+      return JSON.parse(this.wasm.SetImageDimensions(
+        this.handle,
+        imageId,
+        JSON.stringify(dimensions)
+      ));
+    }
+    setImageMetadata(imageId, altText, title) {
+      return JSON.parse(this.wasm.SetImageMetadata(
+        this.handle,
+        imageId,
+        altText,
+        title
+      ));
+    }
+    setImageFloatingLayout(imageId, layout) {
+      return JSON.parse(this.wasm.SetImageFloatingLayout(
+        this.handle,
+        imageId,
+        JSON.stringify(layout)
+      ));
+    }
+    removeImage(imageId) {
+      return JSON.parse(this.wasm.RemoveImage(this.handle, imageId));
+    }
+    /** Native Word structured-document tags, in outer-before-inner story order. */
+    listContentControls(scopes = 63 /* All */) {
+      return JSON.parse(this.wasm.ListContentControls(this.handle, scopes));
+    }
+    fillContentControlText(anchorId, text, options = {}) {
+      return JSON.parse(this.wasm.FillContentControlText(
+        this.handle,
+        anchorId,
+        text,
+        JSON.stringify(options)
+      ));
+    }
+    fillContentControlRichText(anchorId, markdown, options = {}) {
+      return JSON.parse(this.wasm.FillContentControlRichText(
+        this.handle,
+        anchorId,
+        markdown,
+        JSON.stringify(options)
+      ));
+    }
+    setContentControlChecked(anchorId, isChecked, options = {}) {
+      return JSON.parse(this.wasm.SetContentControlChecked(
+        this.handle,
+        anchorId,
+        isChecked,
+        JSON.stringify(options)
+      ));
+    }
+    setContentControlDate(anchorId, value, displayText, options = {}) {
+      const timestamp = value instanceof Date ? value.toISOString() : value;
+      return JSON.parse(this.wasm.SetContentControlDate(
+        this.handle,
+        anchorId,
+        timestamp,
+        displayText ?? null,
+        JSON.stringify(options)
+      ));
+    }
+    selectContentControlItem(anchorId, value, options = {}) {
+      return JSON.parse(this.wasm.SelectContentControlItem(
+        this.handle,
+        anchorId,
+        value,
+        JSON.stringify(options)
+      ));
+    }
+    fillContentControlPicture(anchorId, bytes, options = {}) {
+      return JSON.parse(this.wasm.FillContentControlPicture(
+        this.handle,
+        anchorId,
+        imageBytesToBase64(bytes),
+        JSON.stringify(options)
+      ));
+    }
+    addRepeatingSectionItem(sectionAnchorId, afterItemAnchorId, options = {}) {
+      return JSON.parse(this.wasm.AddRepeatingSectionItem(
+        this.handle,
+        sectionAnchorId,
+        afterItemAnchorId ?? "",
+        JSON.stringify(options)
+      ));
+    }
+    removeRepeatingSectionItem(itemAnchorId) {
+      return JSON.parse(this.wasm.RemoveRepeatingSectionItem(
+        this.handle,
+        itemAnchorId
+      ));
+    }
+    listBookmarks(scopes = 63 /* All */) {
+      return JSON.parse(this.wasm.ListBookmarks(this.handle, scopes));
+    }
+    addBookmark(name, range) {
+      return JSON.parse(this.wasm.AddBookmark(
+        this.handle,
+        name,
+        range.startAnchorId,
+        range.startOffset,
+        range.endAnchorId,
+        range.endOffset
+      ));
+    }
+    renameBookmark(name, newName) {
+      return JSON.parse(this.wasm.RenameBookmark(this.handle, name, newName));
+    }
+    moveBookmark(name, range) {
+      return JSON.parse(this.wasm.MoveBookmark(
+        this.handle,
+        name,
+        range.startAnchorId,
+        range.startOffset,
+        range.endAnchorId,
+        range.endOffset
+      ));
+    }
+    removeBookmark(name) {
+      return JSON.parse(this.wasm.RemoveBookmark(this.handle, name));
+    }
     // ─── Tracked revisions (issue #318) ──────────────────────────────────
     /** Markup-native tracked-revision listing, in document order across body, headers,
      * footers, footnotes, and endnotes. Ids are stable while the underlying markup
@@ -893,6 +1493,22 @@ var Docxodus = (() => {
     rejectRevision(revisionId) {
       return JSON.parse(this.wasm.RejectRevision(this.handle, revisionId));
     }
+    /**
+     * Accept every live revision as one undoable session mutation.
+     *
+     * Fails closed: an unsupported, malformed, or ambiguous registry entry aborts the whole
+     * operation (`revisionUnsupported`/`revisionMalformed`/`revisionAmbiguous`) and nothing is
+     * mutated. There is no force mode — call {@link listRevisions} and read each entry's
+     * `diagnostic` to see what blocks it.
+     */
+    acceptAllRevisions() {
+      return JSON.parse(this.wasm.AcceptAllRevisions(this.handle));
+    }
+    /** Reject every live revision as one undoable session mutation. Fails closed exactly like
+     * {@link acceptAllRevisions}. */
+    rejectAllRevisions() {
+      return JSON.parse(this.wasm.RejectAllRevisions(this.handle));
+    }
     // ─── Tier C: formatting ──────────────────────────────────────────────
     applyFormat(anchorId, span, op) {
       const spanJson = span ? JSON.stringify(span) : "";
@@ -998,6 +1614,10 @@ var Docxodus = (() => {
      * replaces it with `replace`, preserving the surrounding run formatting that
      * the match didn't touch. Returns one `EditResult` per attempted match.
      *
+     * A `find` that matches nothing fails with a single `text_not_found` result
+     * naming the anchor and the needle — never an empty array. Pass
+     * `expectedMatchCount: 0` to assert absence as a successful no-op instead.
+     *
      * Run-formatting contract: the replacement text inherits the formatting of
      * the FIRST run the match spanned. Middle/trailing runs keep their `w:rPr`
      * but lose the slice of text the match consumed.
@@ -1174,10 +1794,16 @@ var Docxodus = (() => {
      *
      * @see docs/architecture/docx_mutation_api.md#findplaceholders
      */
-    findPlaceholders(kinds = PlaceholderKinds.All, scope = 1, contextChars = 80, boundary = ContextBoundary.Char) {
-      return JSON.parse(
-        this.wasm.FindPlaceholders(this.handle, kinds, scope, contextChars, boundary)
-      );
+    findPlaceholders(kinds = PlaceholderKinds.All, scope = 1, contextChars = 80, boundary = ContextBoundary.Char, citation) {
+      const json = citation ? this.wasm.FindPlaceholdersWithCitations(
+        this.handle,
+        kinds,
+        scope,
+        contextChars,
+        boundary,
+        JSON.stringify(citation)
+      ) : this.wasm.FindPlaceholders(this.handle, kinds, scope, contextChars, boundary);
+      return JSON.parse(json);
     }
     /**
      * Returns a snapshot of edit-state introspection signals — placeholder counts,
@@ -1200,6 +1826,23 @@ var Docxodus = (() => {
       }
       return raw;
     }
+    /**
+     * Return stable semantic changes from the package opened for this session to
+     * its current state. Requires `captureInitialProjection` (enabled by default).
+     */
+    getSemanticChanges() {
+      return JSON.parse(this.wasm.GetSemanticChanges(this.handle));
+    }
+    /**
+     * Run the default deliverable gate on this session's normal clean-save checkpoint.
+     * With initial projection capture enabled (the default), exact opening bytes are the
+     * baseline used for dispositions and semantic/package deltas.
+     */
+    verifyDeliverable() {
+      return JSON.parse(
+        this.wasm.VerifyDeliverable(this.handle)
+      );
+    }
     // ─── Annotation-based anchor discovery (#132) ────────────────────────
     /**
      * Resolves an annotation's range to the block-level markdown anchors covering
@@ -1215,8 +1858,9 @@ var Docxodus = (() => {
      *
      * @see docs/architecture/docx_mutation_api.md#findbyannotation
      */
-    findByAnnotation(annotationId) {
-      return JSON.parse(this.wasm.FindByAnnotation(this.handle, annotationId));
+    findByAnnotation(annotationId, citation) {
+      const json = citation ? this.wasm.FindByAnnotationWithCitations(this.handle, annotationId, JSON.stringify(citation)) : this.wasm.FindByAnnotation(this.handle, annotationId);
+      return JSON.parse(json);
     }
     /**
      * Finds every annotation whose `labelId` matches and resolves each of their
@@ -1225,8 +1869,9 @@ var Docxodus = (() => {
      * annotations on different paragraphs become three entries). Annotations
      * whose bookmark resolves to no anchors are omitted from the result.
      */
-    findByLabel(labelId) {
-      return JSON.parse(this.wasm.FindByLabel(this.handle, labelId));
+    findByLabel(labelId, citation) {
+      const json = citation ? this.wasm.FindByLabelWithCitations(this.handle, labelId, JSON.stringify(citation)) : this.wasm.FindByLabel(this.handle, labelId);
+      return JSON.parse(json);
     }
     /**
      * Resolves any bookmark in the main document part (Docxodus-managed or
@@ -1234,8 +1879,9 @@ var Docxodus = (() => {
      * order. Empty when the bookmark name is unknown. Use this for raw bookmark
      * names that didn't come from the annotation system.
      */
-    findByBookmark(bookmarkName) {
-      return JSON.parse(this.wasm.FindByBookmark(this.handle, bookmarkName));
+    findByBookmark(bookmarkName, citation) {
+      const json = citation ? this.wasm.FindByBookmarkWithCitations(this.handle, bookmarkName, JSON.stringify(citation)) : this.wasm.FindByBookmark(this.handle, bookmarkName);
+      return JSON.parse(json);
     }
     // ─── Text/kind-based anchor discovery (#171) ─────────────────────────
     /**
@@ -1280,15 +1926,25 @@ var Docxodus = (() => {
       );
     }
     /**
-     * Return every anchor of the given `kind` (`"p"`, `"h"`, `"li"`, `"tbl"`,
-     * `"row"`, `"cell"`, …), in document order. Reads the projection's anchor
+     * Return every anchor of the given `kind` — one of `"p"`, `"h"`, `"li"`,
+     * `"tbl"`, `"tr"`, `"tc"`, `"col"`, `"sdt"`, `"sec"`, `"fn"`, `"en"`,
+     * `"cmt"`, `"unk"` — in document order. Matching is an exact string comparison;
+     * in particular the row and cell tokens are `"tr"` and `"tc"`, never
+     * `"row"`/`"cell"`. Unknown strings are not parsed or rejected: they simply
+     * return an empty array. `"img"` and `"drw"` likewise return empty because the
+     * projection never assigns those reserved kinds; address images through the
+     * image surface instead. Reads the projection's anchor
      * index directly — no text scan. Pass `scope` (e.g. `"body"`) to restrict to
      * a single part; omit it to span all scopes.
      */
-    findByKind(kind, scope) {
-      return JSON.parse(
-        this.wasm.FindByKind(this.handle, kind, scope ?? "")
-      );
+    findByKind(kind, scope, citation) {
+      const json = citation ? this.wasm.FindByKindWithCitations(
+        this.handle,
+        kind,
+        scope ?? "",
+        JSON.stringify(citation)
+      ) : this.wasm.FindByKind(this.handle, kind, scope ?? "");
+      return JSON.parse(json);
     }
     /**
      * Look up a single anchor's preview info — `{ id, kind, scope, textPreview }`.
@@ -1342,6 +1998,18 @@ var Docxodus = (() => {
       const raw = this.wasm.GetSectionInfo(this.handle, anchorId);
       return JSON.parse(raw);
     }
+    /** Enumerate the document's explicit style catalog with resolved high-signal properties. */
+    listStyles() {
+      return JSON.parse(this.wasm.ListStyles(this.handle));
+    }
+    /** Inspect direct and effective paragraph/run formatting for one paragraph anchor. */
+    getFormatting(anchorId) {
+      return JSON.parse(this.wasm.GetFormatting(this.handle, anchorId));
+    }
+    /** Enumerate text-bearing runs as mutation-compatible anchor/span pairs. */
+    listInlineSpans(anchorId) {
+      return JSON.parse(this.wasm.ListInlineSpans(this.handle, anchorId));
+    }
     /**
      * Enumerates every annotation persisted in the document. Lets an agent prime
      * itself with "here are the labeled regions you can target" before committing
@@ -1406,6 +2074,13 @@ var Docxodus = (() => {
       this.close();
     }
   };
+  function imageBytesToBase64(bytes) {
+    let binary = "";
+    for (let offset = 0; offset < bytes.length; offset += 32768) {
+      binary += String.fromCharCode(...bytes.subarray(offset, offset + 32768));
+    }
+    return globalThis.btoa(binary);
+  }
   function openDocxSession(bytes, wasmExports2, settings) {
     const bridge = wasmExports2.DocxSessionBridge;
     const handle = bridge.OpenSession(bytes, settings ? JSON.stringify(settings) : "");
@@ -1457,17 +2132,41 @@ var Docxodus = (() => {
   function ptToPx(pt) {
     return pt / 0.75;
   }
+  function finiteDataNumber(value, fallback) {
+    if (value === void 0 || value.trim() === "") return fallback;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+  }
+  function positiveDataNumber(value, fallback) {
+    const parsed = finiteDataNumber(value, fallback);
+    return parsed > 0 ? parsed : fallback;
+  }
+  function nonNegativeDataNumber(value, fallback) {
+    const parsed = finiteDataNumber(value, fallback);
+    return parsed >= 0 ? parsed : fallback;
+  }
+  function positiveFinite(value, fallback) {
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+  }
   function parseSectionDimensions(section) {
-    const pageWidth = parseFloat(section.dataset.pageWidth || "") || DEFAULT_PAGE_WIDTH;
-    const pageHeight = parseFloat(section.dataset.pageHeight || "") || DEFAULT_PAGE_HEIGHT;
-    const contentWidth = parseFloat(section.dataset.contentWidth || "") || pageWidth - 2 * DEFAULT_MARGIN;
-    const contentHeight = parseFloat(section.dataset.contentHeight || "") || pageHeight - 2 * DEFAULT_MARGIN;
-    const marginTop = parseFloat(section.dataset.marginTop || "") || DEFAULT_MARGIN;
-    const marginRight = parseFloat(section.dataset.marginRight || "") || DEFAULT_MARGIN;
-    const marginBottom = parseFloat(section.dataset.marginBottom || "") || DEFAULT_MARGIN;
-    const marginLeft = parseFloat(section.dataset.marginLeft || "") || DEFAULT_MARGIN;
-    const headerDistance = parseFloat(section.dataset.headerHeight || "") || DEFAULT_HEADER_FOOTER_DISTANCE;
-    const footerDistance = parseFloat(section.dataset.footerHeight || "") || DEFAULT_HEADER_FOOTER_DISTANCE;
+    const pageWidth = positiveDataNumber(section.dataset.pageWidth, DEFAULT_PAGE_WIDTH);
+    const pageHeight = positiveDataNumber(section.dataset.pageHeight, DEFAULT_PAGE_HEIGHT);
+    const marginTop = finiteDataNumber(section.dataset.marginTop, DEFAULT_MARGIN);
+    const marginRight = finiteDataNumber(section.dataset.marginRight, DEFAULT_MARGIN);
+    const marginBottom = finiteDataNumber(section.dataset.marginBottom, DEFAULT_MARGIN);
+    const marginLeft = finiteDataNumber(section.dataset.marginLeft, DEFAULT_MARGIN);
+    const derivedContentWidth = positiveFinite(pageWidth - marginLeft - marginRight, pageWidth);
+    const derivedContentHeight = positiveFinite(pageHeight - marginTop - marginBottom, pageHeight);
+    const contentWidth = positiveDataNumber(section.dataset.contentWidth, derivedContentWidth);
+    const contentHeight = positiveDataNumber(section.dataset.contentHeight, derivedContentHeight);
+    const headerDistance = nonNegativeDataNumber(
+      section.dataset.headerHeight,
+      DEFAULT_HEADER_FOOTER_DISTANCE
+    );
+    const footerDistance = nonNegativeDataNumber(
+      section.dataset.footerHeight,
+      DEFAULT_HEADER_FOOTER_DISTANCE
+    );
     return {
       pageWidth,
       pageHeight,
@@ -1547,8 +2246,93 @@ var Docxodus = (() => {
   function samePageBox(a, b) {
     return a.pageWidth === b.pageWidth && a.pageHeight === b.pageHeight && a.marginTop === b.marginTop && a.marginRight === b.marginRight && a.marginBottom === b.marginBottom && a.marginLeft === b.marginLeft;
   }
+  function createUnavailablePageMap(documentVersion, rendererFingerprint, mode = "continuous") {
+    if (!rendererFingerprint) throw new Error("rendererFingerprint must be non-empty");
+    return {
+      schemaVersion: 1,
+      mode,
+      availability: "unavailable",
+      documentVersion,
+      rendererFingerprint,
+      pages: [],
+      fragments: []
+    };
+  }
+  var activePageCitationHighlights = /* @__PURE__ */ new WeakMap();
+  function clearPageCitationHighlight(root) {
+    const active = activePageCitationHighlights.get(root);
+    if (!active) return;
+    if (active.highlightClass && active.addedClass) {
+      active.target.classList.remove(active.highlightClass);
+    }
+    for (const style of active.inlineStyles ?? []) {
+      if (style.value) {
+        active.target.style.setProperty(style.name, style.value, style.priority);
+      } else {
+        active.target.style.removeProperty(style.name);
+      }
+    }
+    activePageCitationHighlights.delete(root);
+  }
+  function navigateToPageCitation(root, citation, options = {}) {
+    clearPageCitationHighlight(root);
+    if (citation.availability !== "available" || citation.fragments.length === 0) {
+      return { navigated: false, unavailableReason: "citation_unavailable" };
+    }
+    const byAttribute = (name, value, within = root) => {
+      for (const node of Array.from(within.querySelectorAll(`[${name}]`))) {
+        if (node.getAttribute(name) === value) return node;
+      }
+      return null;
+    };
+    const fragment = citation.fragments[0];
+    let target = byAttribute("data-page-fragment-id", fragment.fragmentId);
+    if (!target) {
+      const page = byAttribute("data-page-number", String(fragment.pageNumber));
+      if (page) target = byAttribute("data-source-anchor-id", citation.anchorId, page) ?? page;
+    }
+    if (!target) {
+      return {
+        navigated: false,
+        pageNumber: fragment.pageNumber,
+        fragmentId: fragment.fragmentId,
+        unavailableReason: "fragment_not_found"
+      };
+    }
+    if (options.highlightClass) {
+      const addedClass = !target.classList.contains(options.highlightClass);
+      target.classList.add(options.highlightClass);
+      activePageCitationHighlights.set(root, {
+        target,
+        highlightClass: options.highlightClass,
+        addedClass
+      });
+    } else if (options.highlight !== false) {
+      const names = ["outline", "outline-offset", "background-color"];
+      const inlineStyles = names.map((name) => ({
+        name,
+        value: target.style.getPropertyValue(name),
+        priority: target.style.getPropertyPriority(name)
+      }));
+      target.style.setProperty("outline", "3px solid #f4b400", "important");
+      target.style.setProperty("outline-offset", "2px", "important");
+      target.style.setProperty("background-color", "rgba(255, 235, 59, .18)", "important");
+      activePageCitationHighlights.set(root, { target, inlineStyles });
+    }
+    target.scrollIntoView({
+      behavior: options.behavior ?? "smooth",
+      block: options.block ?? "center"
+    });
+    return {
+      navigated: true,
+      target,
+      pageNumber: fragment.pageNumber,
+      fragmentId: fragment.fragmentId
+    };
+  }
   var MAX_FOOTNOTE_AREA_RATIO = 0.6;
-  var MIN_BODY_CONTENT_HEIGHT = 72;
+  var FOOTNOTE_MEASUREMENT_GUARD_PT = 2;
+  var FOOTNOTE_SOURCE_POSITION_ATTR = "data-pagination-footnote-source-position";
   var PaginationEngine = class {
     /**
      * Creates a new pagination engine.
@@ -1558,24 +2342,46 @@ var Docxodus = (() => {
      * @param options - Pagination options
      */
     constructor(staging, container, options = {}) {
+      this.createdPageCount = 0;
+      this.footnoteSeparator = null;
+      this.footnoteContinuationSeparator = null;
+      this.footnoteLayoutLikeWord8 = false;
       this.pendingFootnoteContinuation = null;
       /** Per-section `w:pgNumType` (start / format), read off the section wrappers. */
       this.pageNumbering = /* @__PURE__ */ new Map();
-      this.stagingElement = typeof staging === "string" ? document.getElementById(staging) : staging;
-      this.containerElement = typeof container === "string" ? document.getElementById(container) : container;
+      this.lastPages = [];
+      this.expectedPageMapAnchorIds = /* @__PURE__ */ new Set();
+      this.state = "ready";
+      const ownerDocument = typeof staging !== "string" ? staging.ownerDocument : typeof container !== "string" ? container.ownerDocument : globalThis.document;
+      this.stagingElement = typeof staging === "string" ? ownerDocument.getElementById(staging) : staging;
+      this.containerElement = typeof container === "string" ? ownerDocument.getElementById(container) : container;
       if (!this.stagingElement) {
         throw new Error("Staging element not found");
       }
       if (!this.containerElement) {
         throw new Error("Container element not found");
       }
+      if (this.stagingElement.ownerDocument !== this.containerElement.ownerDocument) {
+        throw new Error("Staging and container elements must belong to the same document");
+      }
+      const view = ownerDocument.defaultView;
+      if (!view) {
+        throw new Error("Pagination requires an attached document with a defaultView");
+      }
+      this.document = ownerDocument;
+      this.view = view;
       this.scale = options.scale ?? 1;
       this.cssPrefix = options.cssPrefix ?? "page-";
       this.showPageNumbers = options.showPageNumbers ?? true;
       this.pageGap = options.pageGap ?? 20;
       this.fragmentParagraphs = options.fragmentParagraphs ?? false;
+      this.deferFragmentIdentities = options.deferFragmentIdentities ?? false;
+      this.cancellationCheckpoint = options.checkCancellation;
+      this.pageCountCheckpoint = options.checkPageCount;
+      this.layoutToken = options.layoutToken;
       this.hfRegistry = /* @__PURE__ */ new Map();
       this.footnoteRegistry = /* @__PURE__ */ new Map();
+      this.commentMarginRegistry = /* @__PURE__ */ new Map();
     }
     /**
      * Runs the pagination process.
@@ -1583,58 +2389,469 @@ var Docxodus = (() => {
      * @returns PaginationResult with page information
      */
     paginate() {
-      const pages = [];
-      let pageNumber = 1;
-      this.hfRegistry = this.parseHeaderFooterRegistry();
-      this.footnoteRegistry = this.parseFootnoteRegistry();
-      const sections = this.stagingElement.querySelectorAll(
-        "[data-section-index]"
-      );
-      this.pageNumbering = this.parsePageNumbering(sections);
-      const sectionsToProcess = sections.length > 0 ? Array.from(sections) : [this.stagingElement];
-      const runs = [];
-      for (const section of sectionsToProcess) {
-        const dims = parseSectionDimensions(section);
-        const previous = runs[runs.length - 1];
-        if (previous && section.dataset.sectionType === "continuous" && samePageBox(previous.dims, dims)) {
-          previous.sections.push(section);
-        } else {
-          runs.push({
-            sections: [section],
-            sectionIndex: parseInt(section.dataset.sectionIndex || "0", 10),
-            dims
+      this.checkpoint();
+      if (this.state !== "ready") {
+        throw new Error(`PaginationEngine is one-shot and is already ${this.state}`);
+      }
+      if (!this.stagingElement.isConnected || !this.containerElement.isConnected) {
+        throw new Error("Pagination requires staging and container elements attached to their document");
+      }
+      if (this.document.documentElement.getBoundingClientRect().width <= 0) {
+        throw new Error("Pagination requires a browsing context with non-zero layout");
+      }
+      this.state = "running";
+      try {
+        const pages = [];
+        let pageNumber = 1;
+        this.hfRegistry = this.parseHeaderFooterRegistry();
+        this.footnoteRegistry = this.parseFootnoteRegistry();
+        ({
+          normal: this.footnoteSeparator,
+          continuation: this.footnoteContinuationSeparator
+        } = this.parseFootnoteSeparators());
+        this.commentMarginRegistry = this.parseCommentMarginRegistry();
+        this.footnoteLayoutLikeWord8 = this.stagingElement.dataset.footnoteLayoutLikeWord8 === "true";
+        const sections = this.stagingElement.querySelectorAll(
+          "[data-section-index]"
+        );
+        this.pageNumbering = this.parsePageNumbering(sections);
+        const sectionsToProcess = sections.length > 0 ? Array.from(sections) : [this.stagingElement];
+        this.expectedPageMapAnchorIds = /* @__PURE__ */ new Set();
+        const referencedFootnoteIds = /* @__PURE__ */ new Set();
+        const referencedCommentIds = /* @__PURE__ */ new Set();
+        for (const section of sectionsToProcess) {
+          this.checkpoint();
+          this.collectExpectedSourceAnchors(section, this.expectedPageMapAnchorIds, true);
+          for (const reference of Array.from(section.querySelectorAll("[data-footnote-id]"))) {
+            this.checkpoint();
+            if (reference.closest("#pagination-footnote-registry, #pagination-hf-registry")) continue;
+            const id = reference.dataset.footnoteId;
+            if (id) referencedFootnoteIds.add(id);
+          }
+          for (const reference of Array.from(section.querySelectorAll("[data-comment-id]"))) {
+            this.checkpoint();
+            if (reference.closest(
+              "#pagination-comment-margin-registry, #pagination-footnote-registry, #pagination-hf-registry"
+            )) continue;
+            const id = reference.dataset.commentId;
+            if (id) referencedCommentIds.add(id);
+          }
+        }
+        for (const id of referencedFootnoteIds) {
+          this.checkpoint();
+          const source = this.footnoteRegistry.get(id);
+          if (!source) continue;
+          this.collectExpectedSourceAnchors(source, this.expectedPageMapAnchorIds);
+          for (const reference of Array.from(
+            source.querySelectorAll("[data-comment-id]")
+          )) {
+            this.checkpoint();
+            const commentId = reference.dataset.commentId;
+            if (commentId) referencedCommentIds.add(commentId);
+          }
+        }
+        for (const id of referencedCommentIds) {
+          this.checkpoint();
+          const source = this.commentMarginRegistry.get(id);
+          if (source) this.collectExpectedSourceAnchors(source, this.expectedPageMapAnchorIds);
+        }
+        const runs = [];
+        for (const section of sectionsToProcess) {
+          this.checkpoint();
+          const dims = parseSectionDimensions(section);
+          const previous = runs[runs.length - 1];
+          if (previous && section.dataset.sectionType === "continuous" && samePageBox(previous.dims, dims)) {
+            previous.sections.push(section);
+            previous.sectionDimensions.set(
+              parseInt(section.dataset.sectionIndex || "0", 10),
+              dims
+            );
+          } else {
+            const sectionIndex = parseInt(section.dataset.sectionIndex || "0", 10);
+            runs.push({
+              sections: [section],
+              sectionIndex,
+              sectionType: section.dataset.sectionType ?? "nextPage",
+              dims,
+              sectionDimensions: /* @__PURE__ */ new Map([[sectionIndex, dims]])
+            });
+          }
+        }
+        for (const run of runs) {
+          this.checkpoint();
+          const needsParityFiller = pages.length > 0 && (run.sectionType === "oddPage" && pageNumber % 2 === 0 || run.sectionType === "evenPage" && pageNumber % 2 === 1);
+          if (needsParityFiller) {
+            const precedingPage = pages[pages.length - 1];
+            const precedingPageInSection = parseInt(
+              precedingPage.element.dataset.pageInSection ?? "1",
+              10
+            );
+            const precedingDisplayedPageNumber = parseInt(
+              precedingPage.element.dataset.displayedPageNumber ?? String(precedingPage.pageNumber),
+              10
+            );
+            const filler = this.createPage(
+              precedingPage.dimensions,
+              pageNumber,
+              precedingPage.sectionIndex,
+              precedingDisplayedPageNumber + 1,
+              [],
+              precedingPageInSection + 1,
+              [],
+              0,
+              null,
+              void 0,
+              true
+            );
+            pages.push(filler);
+            pageNumber++;
+          }
+          this.stagingElement.style.visibility = "hidden";
+          this.stagingElement.style.position = "absolute";
+          this.stagingElement.style.left = "-9999px";
+          this.stagingElement.style.display = "block";
+          const blocks = [];
+          for (const section of run.sections) {
+            this.checkpoint();
+            const sectionIndex = parseInt(section.dataset.sectionIndex || "0", 10);
+            const sectionDims = run.sectionDimensions.get(sectionIndex) ?? run.dims;
+            section.style.width = `${sectionDims.contentWidth}pt`;
+            const columnCount = parseInt(section.dataset.cols || "1", 10);
+            if (columnCount > 1) {
+              const gap = parseFloat(section.dataset.colGap || "");
+              blocks.push(...this.buildColumnBlocks(
+                section,
+                sectionDims,
+                sectionIndex,
+                columnCount,
+                Number.isFinite(gap) ? gap : 36
+              ));
+            } else {
+              blocks.push(...this.measureBlocks(section, sectionDims, sectionIndex));
+            }
+          }
+          const sectionPages = this.flowToPages(
+            blocks,
+            run.dims,
+            pageNumber,
+            run.sectionIndex,
+            run.sectionDimensions
+          );
+          this.checkpoint();
+          pages.push(...sectionPages);
+          pageNumber += sectionPages.length;
+        }
+        this.stagingElement.style.display = "none";
+        this.substitutePageNumberFields(pages.length);
+        for (const page of pages) {
+          this.checkpoint();
+          if (page.element.dataset.sectionFiller === "true") continue;
+          const pageInSection = parseInt(page.element.dataset.pageInSection || "1", 10);
+          const displayedPageNumber = parseInt(
+            page.element.dataset.displayedPageNumber || String(page.pageNumber),
+            10
+          );
+          const header = this.selectHeader(page.sectionIndex, pageInSection, displayedPageNumber);
+          const footer = this.selectFooter(page.sectionIndex, pageInSection, displayedPageNumber);
+          if (header) this.collectExpectedSourceAnchors(header, this.expectedPageMapAnchorIds);
+          if (footer) this.collectExpectedSourceAnchors(footer, this.expectedPageMapAnchorIds);
+        }
+        this.qualifyPageFragments(pages);
+        this.transferVisibleFragmentTargets();
+        if (!this.deferFragmentIdentities) this.normalizeVisiblePageFragments(pages);
+        this.lastPages = pages;
+        const result = {
+          totalPages: pages.length,
+          pages,
+          pageMap: this.layoutToken ? this.materializePageMap(
+            this.layoutToken.documentVersion,
+            this.layoutToken.rendererFingerprint
+          ) : void 0
+        };
+        this.state = "complete";
+        return result;
+      } catch (error) {
+        this.state = "failed";
+        throw error;
+      }
+    }
+    checkpoint() {
+      this.cancellationCheckpoint?.();
+    }
+    /**
+     * Normalize visible fragment identities after a caller applies final standalone styles.  This
+     * deliberately runs before the stability barrier; materializePageMap is read-only so PageMap
+     * measurement cannot mutate a tree after it was declared stable.
+     */
+    normalizePageMapFragmentIdentities() {
+      if (this.lastPages.length === 0) {
+        throw new Error("paginate() must complete before fragment identities can be normalized");
+      }
+      this.normalizeVisiblePageFragments(this.lastPages);
+    }
+    /**
+     * Materialize the last completed browser layout as portable page-relative point geometry.
+     * The caller supplies both invalidation tokens; this engine never guesses a document version
+     * or renderer fingerprint.
+     */
+    materializePageMap(documentVersion, rendererFingerprint) {
+      if (!Number.isSafeInteger(documentVersion) || documentVersion < 0) {
+        throw new Error("documentVersion must be a non-negative safe integer");
+      }
+      if (!rendererFingerprint) throw new Error("rendererFingerprint must be non-empty");
+      if (this.lastPages.length === 0) throw new Error("paginate() must complete before materializePageMap()");
+      const pages = this.lastPages.map((page) => ({
+        pageNumber: page.pageNumber,
+        pageInSection: parseInt(page.element.dataset.pageInSection || "1", 10),
+        width: page.dimensions.pageWidth,
+        height: page.dimensions.pageHeight,
+        sectionIndex: page.sectionIndex,
+        pageName: `docxodus-section-${page.sectionIndex}`
+      }));
+      const fragments = [];
+      const requiredAnchorIds = new Set(this.expectedPageMapAnchorIds);
+      if (requiredAnchorIds.size === 0) {
+        throw new Error("cannot publish an available PageMap without canonical source inventory");
+      }
+      const measuredAnchorIds = /* @__PURE__ */ new Set();
+      const emittedFragmentCounts = /* @__PURE__ */ new Map();
+      for (const page of this.lastPages) {
+        this.checkpoint();
+        const pageRect = page.element.getBoundingClientRect();
+        if (pageRect.width <= 0 || pageRect.height <= 0) {
+          throw new Error(`page ${page.pageNumber} has no measurable geometry`);
+        }
+        const pointPerRenderedX = page.dimensions.pageWidth / pageRect.width;
+        const pointPerRenderedY = page.dimensions.pageHeight / pageRect.height;
+        const nodes = page.element.querySelectorAll("[data-source-anchor-id]");
+        for (const element of Array.from(nodes)) {
+          this.checkpoint();
+          if (this.isDeliberatelyUnrenderedSource(element, page.element)) continue;
+          const anchorId = element.dataset.sourceAnchorId;
+          if (!anchorId || !element.dataset.pageFragmentId || !Number.isInteger(parseInt(element.dataset.fragmentIndex || "", 10))) {
+            throw new Error(`page ${page.pageNumber} contains an unqualified source anchor`);
+          }
+          const rect = element.getBoundingClientRect();
+          const style = this.view.getComputedStyle(element);
+          const deliberatelyHidden = style.display === "none" || style.visibility === "hidden";
+          if (deliberatelyHidden) continue;
+          requiredAnchorIds.add(anchorId);
+          const visibleRect = this.intersectWithClippingAncestors(element, page.element, pageRect, rect);
+          const left2 = visibleRect.left;
+          const top2 = visibleRect.top;
+          const right2 = visibleRect.right;
+          const bottom2 = visibleRect.bottom;
+          if (rect.width <= 0 || rect.height <= 0 || right2 <= left2 || bottom2 <= top2) {
+            continue;
+          }
+          measuredAnchorIds.add(anchorId);
+          const fragmentIndex = emittedFragmentCounts.get(anchorId) ?? 0;
+          emittedFragmentCounts.set(anchorId, fragmentIndex + 1);
+          const fragmentId = `p${page.pageNumber}-f${fragmentIndex}-${anchorId}`;
+          if (element.dataset.fragmentIndex !== String(fragmentIndex) || element.dataset.pageFragmentId !== fragmentId || element.dataset.pageNumber !== String(page.pageNumber)) {
+            throw new Error(
+              `page ${page.pageNumber} fragment identity changed after final-tree normalization`
+            );
+          }
+          fragments.push({
+            fragmentId,
+            anchorId,
+            fragmentIndex,
+            pageNumber: page.pageNumber,
+            geometry: {
+              x: (left2 - pageRect.left) * pointPerRenderedX,
+              y: (top2 - pageRect.top) * pointPerRenderedY,
+              width: (right2 - left2) * pointPerRenderedX,
+              height: (bottom2 - top2) * pointPerRenderedY
+            },
+            story: this.storyForCanonicalAnchor(anchorId),
+            inTableCell: element.matches("td,th") || element.closest("td,th") !== null
           });
         }
       }
-      for (const run of runs) {
-        this.stagingElement.style.visibility = "hidden";
-        this.stagingElement.style.position = "absolute";
-        this.stagingElement.style.left = "-9999px";
-        this.stagingElement.style.display = "block";
-        const blocks = [];
-        for (const section of run.sections) {
-          section.style.width = `${run.dims.contentWidth}pt`;
-          const columnCount = parseInt(section.dataset.cols || "1", 10);
-          if (columnCount > 1) {
-            const gap = parseFloat(section.dataset.colGap || "");
-            blocks.push(...this.buildColumnBlocks(
-              section,
-              run.dims,
-              run.sectionIndex,
-              columnCount,
-              Number.isFinite(gap) ? gap : 36
-            ));
-          } else {
-            blocks.push(...this.measureBlocks(section, run.dims));
+      const missingAnchor = Array.from(requiredAnchorIds).find((id) => !measuredAnchorIds.has(id));
+      if (missingAnchor) {
+        throw new Error(`source anchor ${missingAnchor} has no measurable fragment in the paginated layout`);
+      }
+      return {
+        schemaVersion: 1,
+        mode: "paginated",
+        availability: "available",
+        documentVersion,
+        rendererFingerprint,
+        pages,
+        fragments
+      };
+    }
+    normalizeVisiblePageFragments(pages) {
+      const emittedFragmentCounts = /* @__PURE__ */ new Map();
+      for (const page of pages) {
+        this.checkpoint();
+        const pageRect = page.element.getBoundingClientRect();
+        for (const element of Array.from(
+          page.element.querySelectorAll("[data-source-anchor-id]")
+        )) {
+          this.checkpoint();
+          if (this.isDeliberatelyUnrenderedSource(element, page.element)) continue;
+          const anchorId = element.dataset.sourceAnchorId;
+          if (!anchorId) continue;
+          const style = this.view.getComputedStyle(element);
+          if (style.display === "none" || style.visibility === "hidden") continue;
+          const rect = element.getBoundingClientRect();
+          const visible = this.intersectWithClippingAncestors(element, page.element, pageRect, rect);
+          if (rect.width <= 0 || rect.height <= 0 || visible.right <= visible.left || visible.bottom <= visible.top) continue;
+          const fragmentIndex = emittedFragmentCounts.get(anchorId) ?? 0;
+          emittedFragmentCounts.set(anchorId, fragmentIndex + 1);
+          element.dataset.pageNumber = String(page.pageNumber);
+          element.dataset.fragmentIndex = String(fragmentIndex);
+          element.dataset.pageFragmentId = `p${page.pageNumber}-f${fragmentIndex}-${anchorId}`;
+        }
+      }
+    }
+    /**
+     * Intersect an element with every ancestor that establishes an overflow clip before the page
+     * root. getBoundingClientRect() reports layout outside those clips, which is not rendered and
+     * therefore must not satisfy PageMap completeness or inflate portable geometry.
+     */
+    intersectWithClippingAncestors(element, page, pageRect, rect) {
+      let left2 = Math.max(rect.left, pageRect.left);
+      let top2 = Math.max(rect.top, pageRect.top);
+      let right2 = Math.min(rect.right, pageRect.right);
+      let bottom2 = Math.min(rect.bottom, pageRect.bottom);
+      const clips = (value) => value === "hidden" || value === "clip" || value === "scroll" || value === "auto";
+      for (let ancestor = element.parentElement; ancestor && ancestor !== page; ancestor = ancestor.parentElement) {
+        const style = this.view.getComputedStyle(ancestor);
+        const clipsX = clips(style.overflowX);
+        const clipsY = clips(style.overflowY);
+        if (!clipsX && !clipsY) continue;
+        const ancestorRect = ancestor.getBoundingClientRect();
+        if (clipsX) {
+          left2 = Math.max(left2, ancestorRect.left);
+          right2 = Math.min(right2, ancestorRect.right);
+        }
+        if (clipsY) {
+          top2 = Math.max(top2, ancestorRect.top);
+          bottom2 = Math.min(bottom2, ancestorRect.bottom);
+        }
+      }
+      return { left: left2, top: top2, right: right2, bottom: bottom2 };
+    }
+    storyForCanonicalAnchor(anchorId) {
+      const first = anchorId.indexOf(":");
+      const second = first < 0 ? -1 : anchorId.indexOf(":", first + 1);
+      const scope = first >= 0 && second > first ? anchorId.slice(first + 1, second) : "body";
+      if (scope.startsWith("hdr")) return "header";
+      if (scope.startsWith("ftr")) return "footer";
+      if (scope === "fn") return "footnote";
+      if (scope === "en") return "endnote";
+      if (scope === "cmt") return "comment";
+      return "body";
+    }
+    /**
+     * Add canonical IDs from an addressable source subtree to the pre-pagination inventory.
+     * Registry wrappers are excluded when scanning staging because selectable registry contents are
+     * inventoried separately. Producers may explicitly mark content that has no visual substrate
+     * with `data-page-map-exclude="true"`; native hidden semantics carry the same signal.
+     */
+    collectExpectedSourceAnchors(source, destination, excludeRegistries = false) {
+      const candidates = source.matches("[data-source-anchor-id]") ? [source] : [];
+      candidates.push(...Array.from(source.querySelectorAll("[data-source-anchor-id]")));
+      for (const element of candidates) {
+        if (excludeRegistries && element.closest(
+          "#pagination-hf-registry, #pagination-footnote-registry, #pagination-comment-margin-registry"
+        )) {
+          continue;
+        }
+        if (this.isZeroHeightExplicitBreakCarrier(element)) {
+          element.dataset.pageMapExclude = "true";
+        }
+        if (this.isDeliberatelyUnrenderedSource(element, source)) continue;
+        const anchorId = element.dataset.sourceAnchorId;
+        if (anchorId) destination.add(anchorId);
+      }
+    }
+    isZeroHeightExplicitBreakCarrier(element) {
+      const next = element.nextElementSibling;
+      const bounds = element.getBoundingClientRect();
+      return element.hasAttribute("data-source-anchor-id") && (element.textContent ?? "").replace(/\u00a0/g, "").trim() === "" && bounds.height <= 0.01 && !element.querySelector("[data-source-anchor-id]") && !element.querySelector("img,svg,canvas,table,hr,input,textarea,select") && (next?.dataset.pageBreak === "true" || next?.classList.contains(`${this.cssPrefix}break`) === true);
+    }
+    isDeliberatelyUnrenderedSource(element, sourceRoot) {
+      for (let current = element; current; current = current.parentElement) {
+        const zeroHeightExplicitBreakCarrier = current === element && this.isZeroHeightExplicitBreakCarrier(current);
+        if (current.dataset.pageMapExclude === "true" || current.dataset.pageBreak === "true" || current.classList.contains(`${this.cssPrefix}break`) || zeroHeightExplicitBreakCarrier || current.hidden || current.getAttribute("aria-hidden") === "true" || current.style.display === "none" || current.style.visibility === "hidden") {
+          return true;
+        }
+        if (current === sourceRoot) break;
+      }
+      return false;
+    }
+    /**
+     * Keep exactly one active bare-Unid editor anchor per source block. Presentation clones use
+     * canonical source identity plus page/fragment qualification instead.
+     */
+    qualifyPageFragments(pages) {
+      const fragmentCounts = /* @__PURE__ */ new Map();
+      const activeCanonicalIds = /* @__PURE__ */ new Set();
+      const activeBareAnchorIds = /* @__PURE__ */ new Set();
+      const makeInactive = (element) => {
+        element.removeAttribute("data-anchor");
+        element.removeAttribute("data-committed-text");
+        if (element.hasAttribute("contenteditable")) element.setAttribute("contenteditable", "false");
+      };
+      for (const page of pages) {
+        const nodes = page.element.querySelectorAll("[data-source-anchor-id]");
+        for (const element of Array.from(nodes)) {
+          const anchorId = element.dataset.sourceAnchorId;
+          if (!anchorId) continue;
+          const fragmentIndex = fragmentCounts.get(anchorId) ?? 0;
+          fragmentCounts.set(anchorId, fragmentIndex + 1);
+          element.dataset.pageNumber = String(page.pageNumber);
+          element.dataset.fragmentIndex = String(fragmentIndex);
+          element.dataset.pageFragmentId = `p${page.pageNumber}-f${fragmentIndex}-${anchorId}`;
+          const story = this.storyForCanonicalAnchor(anchorId);
+          const mayOwnActiveEditorAnchor = story === "body" || story === "comment" || story === "footnote" || story === "endnote";
+          if (element.hasAttribute("data-anchor")) {
+            const bareAnchorId = element.dataset.anchor;
+            if (mayOwnActiveEditorAnchor && !activeCanonicalIds.has(anchorId) && !activeBareAnchorIds.has(bareAnchorId)) {
+              activeCanonicalIds.add(anchorId);
+              activeBareAnchorIds.add(bareAnchorId);
+            } else {
+              makeInactive(element);
+            }
           }
         }
-        const sectionPages = this.flowToPages(blocks, run.dims, pageNumber, run.sectionIndex);
-        pages.push(...sectionPages);
-        pageNumber += sectionPages.length;
       }
-      this.stagingElement.style.display = "none";
-      this.substitutePageNumberFields(pages.length);
-      return { totalPages: pages.length, pages };
+      const activeStagingCanonicalIds = /* @__PURE__ */ new Set();
+      for (const element of Array.from(
+        this.stagingElement.querySelectorAll("[data-source-anchor-id][data-anchor]")
+      )) {
+        const anchorId = element.dataset.sourceAnchorId;
+        if (!anchorId) continue;
+        const bareAnchorId = element.dataset.anchor;
+        if (activeCanonicalIds.has(anchorId) || activeStagingCanonicalIds.has(anchorId) || activeBareAnchorIds.has(bareAnchorId)) {
+          makeInactive(element);
+        } else {
+          activeStagingCanonicalIds.add(anchorId);
+          activeBareAnchorIds.add(bareAnchorId);
+        }
+      }
+    }
+    /**
+     * Page flow clones source blocks while the hidden staging tree stays in the document. Any HTML
+     * fragment target copied into a visible page would therefore resolve to its earlier hidden
+     * source. Transfer target ownership to the page presentation after flow is complete; registry
+     * and wrapper IDs that have no visible counterpart remain available to pagination internals.
+     */
+    transferVisibleFragmentTargets() {
+      const visibleIds = new Set(Array.from(
+        this.containerElement.querySelectorAll("[id]")
+      ).map((element) => element.id).filter(Boolean));
+      if (visibleIds.size === 0) return;
+      for (const source of Array.from(
+        this.stagingElement.querySelectorAll("[id]")
+      )) {
+        if (visibleIds.has(source.id)) source.removeAttribute("id");
+      }
     }
     /** Read each section's `w:pgNumType` off its wrapper (see {@link SectionPageNumbering}). */
     parsePageNumbering(sections) {
@@ -1678,9 +2895,8 @@ var Docxodus = (() => {
         if (markers.length === 0) continue;
         const sectionIndex = parseInt(box.dataset.sectionIndex || "0", 10);
         const pageNumber = parseInt(box.dataset.pageNumber || "1", 10);
-        const pageInSection = parseInt(box.dataset.pageInSection || "1", 10);
         const numbering = this.pageNumbering.get(sectionIndex) ?? {};
-        const displayed = numbering.start !== void 0 ? numbering.start + pageInSection - 1 : pageNumber;
+        const displayed = parseInt(box.dataset.displayedPageNumber || String(pageNumber), 10);
         for (const marker of Array.from(markers)) {
           const kind = marker.dataset.field;
           if (kind !== "PAGE" && kind !== "NUMPAGES") continue;
@@ -1692,17 +2908,26 @@ var Docxodus = (() => {
     /**
      * Measures all content blocks in a section.
      */
-    measureBlocks(section, dims) {
+    measureBlocks(section, dims, sectionIndex) {
       const blocks = [];
       const children = Array.from(section.children);
       for (const child of children) {
+        this.checkpoint();
         if (child.dataset.sectionIndex !== void 0) {
-          const nestedBlocks = this.measureBlocks(child, dims);
+          const nestedSectionIndex = parseInt(child.dataset.sectionIndex || String(sectionIndex), 10);
+          const nestedBlocks = this.measureBlocks(child, dims, nestedSectionIndex);
           blocks.push(...nestedBlocks);
           continue;
         }
+        if (child.matches("section.endnotes")) {
+          const endnoteBlocks = this.measureSafeEndnoteBlocks(child, dims, sectionIndex);
+          if (endnoteBlocks) {
+            blocks.push(...endnoteBlocks);
+            continue;
+          }
+        }
         const rect = child.getBoundingClientRect();
-        const style = window.getComputedStyle(child);
+        const style = this.view.getComputedStyle(child);
         const marginTopPx = parseFloat(style.marginTop) || 0;
         const marginBottomPx = parseFloat(style.marginBottom) || 0;
         const heightPt = pxToPt(rect.height);
@@ -1711,6 +2936,7 @@ var Docxodus = (() => {
         const isPageBreak = child.dataset.pageBreak === "true" || child.classList.contains(`${this.cssPrefix}break`);
         blocks.push({
           element: child,
+          sectionIndex,
           heightPt,
           marginTopPt,
           marginBottomPt,
@@ -1723,6 +2949,95 @@ var Docxodus = (() => {
       }
       return blocks;
     }
+    /**
+     * Flatten the converter's `section.endnotes > ol > li > p` presentation into
+     * ordinary paragraph blocks. This preserves paragraph formatting and canonical
+     * p:en/en:en identities while allowing the existing paragraph fragmenter to
+     * split a long endnote across page boundaries.
+     */
+    measureSafeEndnoteBlocks(section, dims, sectionIndex) {
+      const sectionChildren = Array.from(section.children);
+      const list = sectionChildren.find((child) => child.tagName === "OL");
+      if (!list || sectionChildren.some((child) => child.tagName !== "HR" && child !== list) || Array.from(list.children).some((child) => child.tagName !== "LI")) {
+        return null;
+      }
+      const items = Array.from(list.children);
+      if (items.length === 0 || items.some(
+        (item) => item.children.length === 0 || Array.from(item.children).some((child) => child.tagName !== "P")
+      )) {
+        return null;
+      }
+      const blocks = [];
+      const sectionStyle = this.view.getComputedStyle(section);
+      for (const rule of sectionChildren.filter((child) => child.tagName === "HR")) {
+        this.checkpoint();
+        const clonedRule = rule.cloneNode(true);
+        if (blocks.length === 0) clonedRule.style.marginTop = sectionStyle.marginTop;
+        blocks.push(this.measureElement(clonedRule, dims, sectionIndex));
+      }
+      const listStyle = this.view.getComputedStyle(list);
+      for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
+        this.checkpoint();
+        const item = items[itemIndex];
+        const ownerAnchorId = item.dataset.sourceAnchorId;
+        const paragraphs = Array.from(item.children);
+        for (let paragraphIndex = 0; paragraphIndex < paragraphs.length; paragraphIndex++) {
+          this.checkpoint();
+          const paragraph = paragraphs[paragraphIndex];
+          if (!this.hasRangeFragmentSafeLayout(paragraph)) {
+            return null;
+          }
+          const clone = paragraph.cloneNode(true);
+          clone.dataset.paginationSafeEndnote = "true";
+          clone.style.fontSize ||= sectionStyle.fontSize;
+          clone.style.lineHeight ||= sectionStyle.lineHeight;
+          clone.style.paddingLeft ||= listStyle.paddingLeft;
+          if (ownerAnchorId && !Array.from(
+            clone.querySelectorAll("[data-source-anchor-id]")
+          ).some((node) => node.dataset.sourceAnchorId === ownerAnchorId)) {
+            const owner = this.document.createElement("span");
+            owner.dataset.sourceAnchorId = ownerAnchorId;
+            while (clone.firstChild) owner.appendChild(clone.firstChild);
+            clone.appendChild(owner);
+          }
+          if (paragraphIndex === 0) {
+            const itemId = item.id;
+            if (itemId) {
+              if (clone.id && clone.id !== itemId) return null;
+              clone.id = itemId;
+            }
+            const value = parseInt(item.getAttribute("value") || String(itemIndex + 1), 10);
+            const marker = this.formatOrderedListMarker(
+              Number.isFinite(value) ? value : itemIndex + 1,
+              listStyle.listStyleType
+            );
+            clone.insertBefore(this.document.createTextNode(`${marker}. `), clone.firstChild);
+          }
+          blocks.push(this.measureElement(clone, dims, sectionIndex));
+        }
+      }
+      return blocks;
+    }
+    /** Render the CSS ordered-list formats emitted by the converter after an endnote is flattened. */
+    formatOrderedListMarker(value, listStyleType) {
+      const format = (() => {
+        switch (listStyleType) {
+          case "lower-roman":
+            return "lowerRoman";
+          case "upper-roman":
+            return "upperRoman";
+          case "lower-alpha":
+          case "lower-latin":
+            return "lowerLetter";
+          case "upper-alpha":
+          case "upper-latin":
+            return "upperLetter";
+          default:
+            return "decimal";
+        }
+      })();
+      return formatPageNumber(value, format);
+    }
     /**
      * Flows a multi-column (`w:cols`) section's children into CSS-multicol container
      * blocks. Word lays such a section out as N columns inside the same body extent;
@@ -1740,7 +3055,7 @@ var Docxodus = (() => {
       const maxFragmentHeight = this.smallestEffectiveContentHeight(dims, sectionIndex);
       const isBreak = (child) => child.dataset.pageBreak === "true" || child.classList.contains(`${this.cssPrefix}break`);
       const makeContainer = (slice) => {
-        const container = document.createElement("div");
+        const container = this.document.createElement("div");
         container.style.columnCount = String(columnCount);
         container.style.columnGap = `${columnGapPt}pt`;
         for (const child of slice) {
@@ -1750,17 +3065,19 @@ var Docxodus = (() => {
       };
       let start2 = 0;
       while (start2 < children.length) {
+        this.checkpoint();
         if (isBreak(children[start2])) {
-          blocks.push(this.measureElement(children[start2], dims));
+          blocks.push(this.measureElement(children[start2], dims, sectionIndex));
           start2++;
           continue;
         }
         let end = start2 + 1;
         let container = makeContainer(children.slice(start2, end));
-        let measured = this.measureElement(container, dims);
+        let measured = this.measureElement(container, dims, sectionIndex);
         while (end < children.length && !isBreak(children[end])) {
+          this.checkpoint();
           const candidate = makeContainer(children.slice(start2, end + 1));
-          const candidateMeasured = this.measureElement(candidate, dims);
+          const candidateMeasured = this.measureElement(candidate, dims, sectionIndex);
           if (candidateMeasured.heightPt > maxFragmentHeight) break;
           container = candidate;
           measured = candidateMeasured;
@@ -1768,6 +3085,7 @@ var Docxodus = (() => {
         }
         blocks.push({
           element: container,
+          sectionIndex,
           heightPt: measured.heightPt,
           marginTopPt: measured.marginTopPt,
           marginBottomPt: measured.marginBottomPt,
@@ -1786,8 +3104,8 @@ var Docxodus = (() => {
      * This is intentionally DOM-based: table row heights cannot be inferred from individual
      * rows because wrapping and collapsed borders change the height of a fragment.
      */
-    measureElement(element, dims) {
-      const measurementHost = document.createElement("div");
+    measureElement(element, dims, sectionIndex) {
+      const measurementHost = this.document.createElement("div");
       measurementHost.style.position = "absolute";
       measurementHost.style.visibility = "hidden";
       measurementHost.style.left = "-9999px";
@@ -1796,9 +3114,10 @@ var Docxodus = (() => {
       measurementHost.appendChild(measuredElement);
       this.stagingElement.appendChild(measurementHost);
       const rect = measuredElement.getBoundingClientRect();
-      const style = window.getComputedStyle(measuredElement);
+      const style = this.view.getComputedStyle(measuredElement);
       const measured = {
         element,
+        sectionIndex,
         heightPt: pxToPt(rect.height),
         marginTopPt: pxToPt(parseFloat(style.marginTop) || 0),
         marginBottomPt: pxToPt(parseFloat(style.marginBottom) || 0),
@@ -1892,6 +3211,7 @@ var Docxodus = (() => {
       const knownIds = new Set(existingFootnoteIds);
       const newIds = [];
       for (const block of blocks) {
+        this.checkpoint();
         for (const id of this.extractFootnoteRefs(block.element)) {
           if (!knownIds.has(id)) {
             knownIds.add(id);
@@ -1909,8 +3229,8 @@ var Docxodus = (() => {
     smallestEffectiveContentHeight(dims, sectionIndex) {
       return Math.min(
         this.getPageBands(dims, sectionIndex, 1, 1).bodyHeight,
-        this.getPageBands(dims, sectionIndex, 2, 1).bodyHeight,
-        this.getPageBands(dims, sectionIndex, 2, 2).bodyHeight
+        this.getPageBands(dims, sectionIndex, 2, 2).bodyHeight,
+        this.getPageBands(dims, sectionIndex, 3, 3).bodyHeight
       );
     }
     /**
@@ -1948,10 +3268,11 @@ var Docxodus = (() => {
       if (wrapper.tagName !== "DIV" || wrapper.children.length !== 1 || block.keepWithNext || block.keepLines || block.pageBreakBefore || block.isPageBreak) {
         return null;
       }
-      const table = wrapper.firstElementChild;
-      if (!(table instanceof HTMLTableElement)) {
+      const tableElement = wrapper.firstElementChild;
+      if (!tableElement || tableElement.localName !== "table") {
         return null;
       }
+      const table = tableElement;
       const body = table.tBodies.length === 1 ? table.tBodies[0] : null;
       if (!body || table.tHead || table.tFoot || body.rows.length < 2 || Array.from(table.children).some((child) => child !== body && child.tagName !== "COLGROUP") || table.querySelector("table, [rowspan], [colspan], [data-footnote-id]") || wrapper.querySelector("[data-footnote-id]")) {
         return null;
@@ -1965,8 +3286,10 @@ var Docxodus = (() => {
       const groups = [];
       let start2 = 0;
       while (start2 < rows.length) {
+        this.checkpoint();
         let end = start2;
         while (end < rows.length) {
+          this.checkpoint();
           const candidate = this.createSimpleTableFragment(
             wrapper,
             table,
@@ -1974,7 +3297,7 @@ var Docxodus = (() => {
             rows.slice(start2, end + 1),
             start2 === 0
           );
-          const measured = this.measureElement(candidate, dims);
+          const measured = this.measureElement(candidate, dims, block.sectionIndex);
           if (measured.heightPt > maximumFragmentHeight) {
             break;
           }
@@ -2006,7 +3329,7 @@ var Docxodus = (() => {
         if (!isLast) {
           fragment.style.setProperty("margin-bottom", "0", "important");
         }
-        const measured = this.measureElement(fragment, dims);
+        const measured = this.measureElement(fragment, dims, block.sectionIndex);
         if (measured.heightPt + measured.marginTopPt + measured.marginBottomPt > minimumContentHeight) {
           return null;
         }
@@ -2021,35 +3344,198 @@ var Docxodus = (() => {
       return fragments;
     }
     /**
-     * A DOM endpoint that can finish a paragraph fragment. Endpoints are chosen
-     * after whitespace or at a run boundary so the paginator never deliberately
-     * cuts through an ordinary word merely to fill a little more of a page.
-     */
-    paragraphFragmentEndpoints(paragraph) {
-      const endpoints = [];
-      const walker = document.createTreeWalker(paragraph, NodeFilter.SHOW_TEXT);
+     * DOM endpoints that can finish a paragraph fragment. The flattened UTF-16
+     * offsets are checked against the browser's Unicode grapheme segmenter, so a
+     * formatting-run boundary can never bisect a surrogate pair, combining
+     * sequence, or joined emoji. NBSP/word-joiner boundaries remain indivisible.
+     * PAGE/NUMPAGES field results are atomic because splitting their marker would
+     * make later substitution duplicate or replace only half of the field.
+     */
+    paragraphFragmentEndpoints(paragraph, emergencyGraphemeBreaks = false) {
+      const textNodes = [];
+      const textStarts = /* @__PURE__ */ new Map();
+      const lastTextByField = /* @__PURE__ */ new Map();
+      const walker = this.document.createTreeWalker(paragraph, this.view.NodeFilter.SHOW_TEXT);
+      const flattenedChunks = [];
+      let flattenedLength = 0;
       let textNode;
       while (textNode = walker.nextNode()) {
-        const text = textNode.data;
-        if (text.length === 0) continue;
-        const whitespace = /\s+/g;
+        this.checkpoint();
+        textStarts.set(textNode, flattenedLength);
+        textNodes.push(textNode);
+        flattenedChunks.push(textNode.data);
+        flattenedLength += textNode.data.length;
+        let field = textNode.parentElement?.closest("[data-field]") ?? null;
+        while (field?.parentElement?.closest("[data-field]")) {
+          field = field.parentElement.closest("[data-field]");
+        }
+        if (field && paragraph.contains(field)) lastTextByField.set(field, textNode);
+      }
+      const flattenedText = flattenedChunks.join("");
+      if (!this.hasVisibleText(flattenedText)) return [];
+      const invisible = /[\s\u200B-\u200F\uFEFF]/;
+      let firstVisibleOffset = -1;
+      let lastVisibleOffset = -1;
+      for (let index = 0; index < flattenedText.length; index++) {
+        if (index % 4096 === 0) this.checkpoint();
+        if (invisible.test(flattenedText[index])) continue;
+        if (firstVisibleOffset < 0) firstVisibleOffset = index;
+        lastVisibleOffset = index;
+      }
+      const graphemeBoundaries = this.graphemeBoundaryOffsets(flattenedText);
+      const candidates = [];
+      const addCandidate = (candidate) => {
+        const { textOffset } = candidate;
+        if (textOffset <= 0 || textOffset >= flattenedText.length) return;
+        if (textOffset <= firstVisibleOffset || textOffset > lastVisibleOffset) return;
+        if (this.isNonBreakingTextBoundary(flattenedText, textOffset)) return;
+        if (!this.isLegalParagraphLineBoundary(paragraph, flattenedText, textOffset)) return;
+        if (graphemeBoundaries) {
+          if (!graphemeBoundaries.has(textOffset)) return;
+        } else if (!this.isConservativeFallbackTextBoundary(flattenedText, textOffset)) {
+          return;
+        }
+        candidates.push(candidate);
+      };
+      for (const node of textNodes) {
+        this.checkpoint();
+        const start2 = textStarts.get(node);
+        const atomic = node.parentElement?.closest(
+          "[data-field], [data-list-marker], a[data-comment-id]"
+        );
+        if (atomic && paragraph.contains(atomic)) continue;
+        const whitespace = /[\u0009-\u000D\u0020]+/g;
         let match;
-        while ((match = whitespace.exec(text)) !== null) {
-          endpoints.push({ node: textNode, offset: match.index + match[0].length });
+        let matchesSinceCheckpoint = 0;
+        while ((match = whitespace.exec(node.data)) !== null) {
+          if (++matchesSinceCheckpoint % 256 === 0) this.checkpoint();
+          const offset = match.index + match[0].length;
+          addCandidate({ node, offset, textOffset: start2 + offset, priority: 0 });
+        }
+        addCandidate({
+          node,
+          offset: node.data.length,
+          textOffset: start2 + node.data.length,
+          priority: 0
+        });
+        if (emergencyGraphemeBreaks) {
+          for (let offset = 1; offset < node.data.length; offset++) {
+            if (offset % 256 === 0) this.checkpoint();
+            addCandidate({
+              node,
+              offset,
+              textOffset: start2 + offset,
+              priority: -1
+            });
+          }
         }
-        if (endpoints.length === 0 || endpoints[endpoints.length - 1].node !== textNode || endpoints[endpoints.length - 1].offset !== text.length) {
-          endpoints.push({ node: textNode, offset: text.length });
+      }
+      for (const field of Array.from(paragraph.querySelectorAll("[data-field]"))) {
+        this.checkpoint();
+        if (field.parentElement?.closest("[data-field]")) continue;
+        const last = lastTextByField.get(field);
+        const parent = field.parentNode;
+        if (!last || !parent) continue;
+        const childIndex = Array.prototype.indexOf.call(parent.childNodes, field);
+        if (childIndex < 0) continue;
+        addCandidate({
+          node: parent,
+          offset: childIndex + 1,
+          textOffset: textStarts.get(last) + last.data.length,
+          priority: 1
+        });
+      }
+      candidates.sort((left2, right2) => left2.textOffset - right2.textOffset || right2.priority - left2.priority);
+      const endpoints = [];
+      for (const candidate of candidates) {
+        if (endpoints[endpoints.length - 1]?.textOffset !== candidate.textOffset) {
+          endpoints.push(candidate);
         }
       }
       return endpoints;
     }
+    /** Browser-native UAX #29 boundaries; null keeps older runtimes conservative. */
+    graphemeBoundaryOffsets(text) {
+      const SegmenterConstructor = this.view.Intl.Segmenter;
+      if (!SegmenterConstructor) return null;
+      const boundaries = /* @__PURE__ */ new Set([0, text.length]);
+      let segmentCount = 0;
+      for (const part of new SegmenterConstructor("en", { granularity: "grapheme" }).segment(text)) {
+        if (++segmentCount % 256 === 0) this.checkpoint();
+        boundaries.add(part.index);
+        boundaries.add(part.index + part.segment.length);
+      }
+      return boundaries;
+    }
+    /**
+     * Conservative UAX #14/CSS wrapping opportunities used for synthetic page
+     * boundaries. In particular, a formatting-run boundary is not itself a word
+     * boundary, and Japanese opening/closing punctuation stays with its pair.
+     * Arbitrary grapheme breaks are admitted only when the paragraph's CSS asks
+     * the browser to wrap anywhere.
+     */
+    isLegalParagraphLineBoundary(paragraph, text, offset) {
+      const lastCodeUnit = text.charCodeAt(offset - 1);
+      const beforeOffset = lastCodeUnit >= 56320 && lastCodeUnit <= 57343 ? Math.max(0, offset - 2) : offset - 1;
+      const beforeCodePoint = text.codePointAt(beforeOffset);
+      const afterCodePoint = text.codePointAt(offset);
+      const before = beforeCodePoint === void 0 ? "" : String.fromCodePoint(beforeCodePoint);
+      const after = afterCodePoint === void 0 ? "" : String.fromCodePoint(afterCodePoint);
+      if (/^[\u0009-\u000D\u0020]$/.test(before) || /^[\u0009-\u000D\u0020]$/.test(after)) return true;
+      if (/[-\u00AD\u2010]$/u.test(before)) return true;
+      const style = this.view.getComputedStyle(paragraph);
+      if (style.wordBreak === "break-all" || style.overflowWrap === "anywhere" || style.overflowWrap === "break-word") return true;
+      const eastAsian = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u;
+      if (!eastAsian.test(before) && !eastAsian.test(after)) return false;
+      const opening = "([{<\u2018\u201C\u3008\u300A\u300C\u300E\u3010\u3014\u3016\u3018\u301A\uFF08\uFF3B\uFF5B";
+      const closing = ")]}>\u2019\u201D\u3001\u3002\u3009\u300B\u300D\u300F\u3011\u3015\u3017\u3019\u301B\uFF01\uFF05\uFF09\uFF0C\uFF0E\uFF1A\uFF1B\uFF1F\uFF3D\uFF5D";
+      return !opening.includes(before) && !closing.includes(after);
+    }
+    /** Never fragment across characters whose line-break meaning is explicitly non-breaking. */
+    isNonBreakingTextBoundary(text, offset) {
+      const codePointBefore = (index) => {
+        if (index <= 0) return void 0;
+        const last = text.charCodeAt(index - 1);
+        const start2 = last >= 56320 && last <= 57343 ? index - 2 : index - 1;
+        return text.codePointAt(Math.max(0, start2));
+      };
+      const nonBreaking = /* @__PURE__ */ new Set([
+        160,
+        8206,
+        8207,
+        8209,
+        8234,
+        8235,
+        8236,
+        8237,
+        8238,
+        8239,
+        8288,
+        8294,
+        8295,
+        8296,
+        8297,
+        65279
+      ]);
+      return nonBreaking.has(codePointBefore(offset) ?? -1) || nonBreaking.has(text.codePointAt(offset) ?? -1);
+    }
+    /**
+     * Without Intl.Segmenter, admit only an all-ASCII boundary. This still
+     * fragments ordinary prose while refusing to guess about Unicode clusters.
+     */
+    isConservativeFallbackTextBoundary(text, offset) {
+      return text.charCodeAt(offset - 1) <= 127 && text.charCodeAt(offset) <= 127;
+    }
     /**
      * Whether a range contains visible text after ignoring bidi/zero-width marks.
      * Paragraph fragmentation deliberately excludes non-textual descendants, so
      * this is enough to reject empty head or tail fragments.
      */
     hasVisibleFragmentText(fragment) {
-      return (fragment.textContent || "").replace(/[\u200B-\u200F\uFEFF]/g, "").trim().length > 0;
+      return this.hasVisibleText(fragment.textContent || "");
+    }
+    hasVisibleText(text) {
+      return text.replace(/[\u200B-\u200F\uFEFF]/g, "").trim().length > 0;
     }
     /**
      * Phase one only handles text-like paragraph descendants. Objects, explicit
@@ -2058,13 +3544,25 @@ var Docxodus = (() => {
      * fallback instead of risking broken content or duplicate anchors.
      */
     canFragmentParagraph(block) {
-      if (!this.fragmentParagraphs || block.element.tagName !== "P") {
+      if (!this.fragmentParagraphs) {
         return false;
       }
       const paragraph = block.element;
       if (block.keepWithNext || block.keepLines || block.pageBreakBefore || block.isPageBreak || paragraph.dataset.widowControl === "true" || paragraph.hasAttribute("contenteditable")) {
         return false;
       }
+      return this.canRangeFragmentParagraph(paragraph);
+    }
+    /**
+     * Shared structural gate for body and note paragraph fragmentation. Footnote
+     * first paragraphs are inline beside their marker, so that one known layout
+     * context may opt into an inline root while retaining every descendant and
+     * break-safety restriction used for body text.
+     */
+    canRangeFragmentParagraph(paragraph, allowInlineRoot = false) {
+      if (paragraph.tagName !== "P" || paragraph.dataset.keepWithNext === "true" || paragraph.dataset.keepLines === "true" || paragraph.dataset.pageBreakBefore === "true" || paragraph.dataset.widowControl === "true" || paragraph.hasAttribute("contenteditable")) {
+        return false;
+      }
       const unsupportedDescendants = [
         "br",
         "img",
@@ -2095,21 +3593,27 @@ var Docxodus = (() => {
         "fieldset",
         "details",
         "[data-footnote-id]",
-        "[data-list-marker]",
-        "[data-anchor]",
-        "[id]",
         "[contenteditable]"
       ].join(", ");
       if (paragraph.querySelector(unsupportedDescendants)) {
         return false;
       }
-      const paragraphStyle = window.getComputedStyle(paragraph);
-      if (paragraphStyle.display !== "block" || paragraphStyle.position !== "static" || paragraphStyle.float !== "none" || paragraphStyle.whiteSpace !== "normal" || paragraphStyle.breakBefore !== "auto" || paragraphStyle.breakAfter !== "auto" || paragraphStyle.breakInside === "avoid" || paragraphStyle.pageBreakBefore !== "auto" || paragraphStyle.pageBreakAfter !== "auto" || paragraphStyle.pageBreakInside === "avoid") {
+      const isValidatedEndnote = paragraph.dataset.paginationSafeEndnote === "true";
+      return isValidatedEndnote || this.hasRangeFragmentSafeLayout(paragraph, allowInlineRoot);
+    }
+    /**
+     * A range clone preserves nested inline formatting exactly. Anything that establishes its own
+     * box/layout context is deferred until a future fragmenter can model it accurately. Callers
+     * must invoke this while the paragraph is attached to the styled document.
+     */
+    hasRangeFragmentSafeLayout(paragraph, allowInlineRoot = false) {
+      const paragraphStyle = this.view.getComputedStyle(paragraph);
+      if (paragraphStyle.display !== "block" && !(allowInlineRoot && paragraphStyle.display === "inline") || paragraphStyle.position !== "static" || paragraphStyle.float !== "none" || paragraphStyle.whiteSpace !== "normal" && paragraphStyle.whiteSpace !== "pre-wrap" || paragraphStyle.breakBefore !== "auto" || paragraphStyle.breakAfter !== "auto" || paragraphStyle.breakInside === "avoid" || paragraphStyle.pageBreakBefore !== "auto" || paragraphStyle.pageBreakAfter !== "auto" || paragraphStyle.pageBreakInside === "avoid") {
         return false;
       }
       for (const descendant of Array.from(paragraph.querySelectorAll("*"))) {
-        const style = window.getComputedStyle(descendant);
-        if (style.display !== "inline" || style.position !== "static" || style.float !== "none" || style.whiteSpace !== "normal") {
+        const style = this.view.getComputedStyle(descendant);
+        if (style.display !== "inline" || style.position !== "static" || style.float !== "none" || style.whiteSpace !== "normal" && style.whiteSpace !== "pre-wrap") {
           return false;
         }
       }
@@ -2136,58 +3640,122 @@ var Docxodus = (() => {
       return fragment;
     }
     /**
-     * Splits a simple paragraph at the largest DOM Range endpoint that fits the
-     * currently available body space. The caller then processes the tail normally,
-     * allowing it to fragment again on later pages when necessary.
+     * Range clones repeat an inline ancestor when the split lands inside it. Keep
+     * semantic wrappers (links, comments, formatting) on both sides, but retain a
+     * duplicated HTML/editor identity only on the leading fragment. Targets that
+     * occur wholly after the split are absent from `head` and remain on `tail`.
      */
-    tryFragmentParagraph(block, dims, availableHeightPt, effectiveMarginTopPt) {
-      if (!this.canFragmentParagraph(block) || availableHeightPt <= effectiveMarginTopPt) {
-        return null;
-      }
-      const paragraph = block.element;
-      const endpoints = this.paragraphFragmentEndpoints(paragraph);
-      if (endpoints.length < 2) {
-        return null;
-      }
-      let low = 0;
-      let high = endpoints.length - 2;
-      let best = null;
-      while (low <= high) {
-        const middle = Math.floor((low + high) / 2);
-        const endpoint = endpoints[middle];
-        const headRange = document.createRange();
-        headRange.setStart(paragraph, 0);
-        headRange.setEnd(endpoint.node, endpoint.offset);
-        const headContents = headRange.cloneContents();
-        if (!this.hasVisibleFragmentText(headContents)) {
-          low = middle + 1;
-          continue;
+    reconcileParagraphFragmentIdentities(head, tail) {
+      const elements = (root, selector2) => [
+        ...root.matches(selector2) ? [root] : [],
+        ...Array.from(root.querySelectorAll(selector2))
+      ];
+      const headIds = new Set(elements(head, "[id]").map((element) => element.id));
+      for (const element of elements(tail, "[id]")) {
+        if (headIds.has(element.id)) element.removeAttribute("id");
+      }
+      const headAnchors = new Set(elements(head, "[data-anchor]").map((element) => element.dataset.anchor).filter((anchor) => Boolean(anchor)));
+      for (const element of elements(tail, "[data-anchor]")) {
+        if (!element.dataset.anchor || !headAnchors.has(element.dataset.anchor)) continue;
+        element.removeAttribute("data-anchor");
+        element.removeAttribute("data-committed-text");
+      }
+    }
+    /**
+     * Range-clone the largest safe prefix accepted by `fits`. The measurement
+     * policy stays with the caller, allowing body blocks and note bands to share
+     * one DOM fragmenter while measuring in their respective layout contexts.
+     */
+    splitParagraphAtLargestFit(paragraph, fits, options = {}) {
+      const largestFit = (endpoints2) => {
+        const lastEndpoint = endpoints2[endpoints2.length - 1];
+        if (lastEndpoint) {
+          const lastRange = this.document.createRange();
+          lastRange.setStart(paragraph, 0);
+          lastRange.setEnd(lastEndpoint.node, lastEndpoint.offset);
+          const lastContents = lastRange.cloneContents();
+          if (this.hasVisibleFragmentText(lastContents)) {
+            const lastHead = this.createParagraphFragment(paragraph, lastRange, true, false);
+            if (fits(lastHead)) return { endpoint: lastEndpoint, head: lastHead };
+          }
         }
-        const head = this.createParagraphFragment(paragraph, headRange, true, false);
-        const measured = this.measureElement(head, dims);
-        if (effectiveMarginTopPt + measured.heightPt <= availableHeightPt) {
-          best = { endpoint, element: head, measured };
-          low = middle + 1;
-        } else {
-          high = middle - 1;
+        let low = 0;
+        let high = endpoints2.length - 2;
+        let best2 = null;
+        while (low <= high) {
+          this.checkpoint();
+          const middle = Math.floor((low + high) / 2);
+          const endpoint = endpoints2[middle];
+          const headRange = this.document.createRange();
+          headRange.setStart(paragraph, 0);
+          headRange.setEnd(endpoint.node, endpoint.offset);
+          const headContents = headRange.cloneContents();
+          if (!this.hasVisibleFragmentText(headContents)) {
+            low = middle + 1;
+            continue;
+          }
+          const head = this.createParagraphFragment(paragraph, headRange, true, false);
+          if (fits(head)) {
+            best2 = { endpoint, head };
+            low = middle + 1;
+          } else {
+            high = middle - 1;
+          }
         }
+        return best2;
+      };
+      let endpoints = this.paragraphFragmentEndpoints(paragraph);
+      let best = largestFit(endpoints);
+      if (!best && options.emergencyGraphemeBreaks) {
+        endpoints = this.paragraphFragmentEndpoints(paragraph, true);
+        best = largestFit(endpoints);
+      }
+      if (!best && options.forceFirstOnNoFit && endpoints.length > 0) {
+        const endpoint = endpoints[0];
+        const headRange = this.document.createRange();
+        headRange.setStart(paragraph, 0);
+        headRange.setEnd(endpoint.node, endpoint.offset);
+        best = {
+          endpoint,
+          head: this.createParagraphFragment(paragraph, headRange, true, false)
+        };
       }
       if (!best) {
-        return null;
+        return endpoints.length > 0 ? { kind: "no-fit" } : { kind: "indivisible" };
       }
-      const tailRange = document.createRange();
+      const tailRange = this.document.createRange();
       tailRange.setStart(best.endpoint.node, best.endpoint.offset);
       tailRange.setEnd(paragraph, paragraph.childNodes.length);
       const tailContents = tailRange.cloneContents();
-      if (!this.hasVisibleFragmentText(tailContents)) {
+      if (!this.hasVisibleFragmentText(tailContents)) return { kind: "indivisible" };
+      const tail = this.createParagraphFragment(paragraph, tailRange, false, true);
+      this.reconcileParagraphFragmentIdentities(best.head, tail);
+      return {
+        kind: "split",
+        head: best.head,
+        tail
+      };
+    }
+    /**
+     * Splits a simple paragraph at the largest DOM Range endpoint that fits the
+     * currently available body space. The caller then processes the tail normally,
+     * allowing it to fragment again on later pages when necessary.
+     */
+    tryFragmentParagraph(block, dims, availableHeightPt, effectiveMarginTopPt) {
+      if (!this.canFragmentParagraph(block) || availableHeightPt <= effectiveMarginTopPt) {
         return null;
       }
-      const tail = this.createParagraphFragment(paragraph, tailRange, false, true);
-      const tailMeasured = this.measureElement(tail, dims);
+      const split = this.splitParagraphAtLargestFit(block.element, (head) => {
+        const measured = this.measureElement(head, dims, block.sectionIndex);
+        return effectiveMarginTopPt + measured.heightPt <= availableHeightPt;
+      });
+      if (split.kind !== "split") return null;
+      const headMeasured = this.measureElement(split.head, dims, block.sectionIndex);
+      const tailMeasured = this.measureElement(split.tail, dims, block.sectionIndex);
       return [
         {
-          ...best.measured,
-          element: best.element,
+          ...headMeasured,
+          element: split.head,
           keepWithNext: false,
           keepLines: false,
           pageBreakBefore: false,
@@ -2195,7 +3763,7 @@ var Docxodus = (() => {
         },
         {
           ...tailMeasured,
-          element: tail,
+          element: split.tail,
           keepWithNext: false,
           keepLines: false,
           pageBreakBefore: false,
@@ -2266,7 +3834,7 @@ var Docxodus = (() => {
       const registry = /* @__PURE__ */ new Map();
       const registryEl = this.stagingElement.querySelector("#pagination-footnote-registry");
       if (!registryEl) return registry;
-      const entries = Array.from(registryEl.querySelectorAll("[data-footnote-id]"));
+      const entries = Array.from(registryEl.children).filter((entry) => entry instanceof this.view.HTMLElement && entry.hasAttribute("data-footnote-id"));
       for (const entry of entries) {
         const footnoteId = entry.dataset.footnoteId;
         if (footnoteId) {
@@ -2275,6 +3843,68 @@ var Docxodus = (() => {
       }
       return registry;
     }
+    /** Read Word's optional normal and continuation separator stories. */
+    parseFootnoteSeparators() {
+      const registry = this.stagingElement.querySelector("#pagination-footnote-registry");
+      const clone = (kind) => {
+        const source = Array.from(registry?.children ?? []).find(
+          (entry) => entry instanceof this.view.HTMLElement && entry.getAttribute("data-footnote-separator") === kind
+        );
+        return source?.cloneNode(true);
+      };
+      return {
+        normal: clone("normal") ?? null,
+        continuation: clone("continuation") ?? null
+      };
+    }
+    /** Append the exact separator story selected for this initial/continued note band. */
+    appendFootnoteSeparator(container, continuation) {
+      const kind = continuation ? "continuation" : "normal";
+      const source = continuation ? this.footnoteContinuationSeparator : this.footnoteSeparator;
+      if (!source) {
+        const fallback = this.document.createElement("hr");
+        fallback.dataset.footnoteSeparator = kind;
+        container.appendChild(fallback);
+        return;
+      }
+      const clone = source.cloneNode(true);
+      for (const element of [clone, ...Array.from(clone.querySelectorAll("*"))]) {
+        element.removeAttribute("id");
+        element.removeAttribute("data-anchor");
+        element.removeAttribute("data-committed-text");
+        element.removeAttribute("data-source-anchor-id");
+        element.removeAttribute("data-page-fragment-id");
+        element.removeAttribute("data-fragment-index");
+        element.removeAttribute("data-footnote-id");
+        element.removeAttribute("data-comment-id");
+        element.removeAttribute("name");
+        if (element instanceof this.view.HTMLAnchorElement && element.getAttribute("href")?.startsWith("#")) {
+          element.removeAttribute("href");
+        }
+        element.setAttribute("contenteditable", "false");
+      }
+      container.appendChild(clone);
+    }
+    /** Parses the hidden source notes used to render paginated margin comments. */
+    parseCommentMarginRegistry() {
+      const registry = /* @__PURE__ */ new Map();
+      const registryEl = this.stagingElement.querySelector(
+        "#pagination-comment-margin-registry"
+      );
+      if (!registryEl) return registry;
+      for (const entry of Array.from(
+        registryEl.querySelectorAll("[data-comment-id]")
+      )) {
+        const commentId = entry.dataset.commentId;
+        if (!commentId) continue;
+        let root = entry;
+        for (let parent = root.parentElement?.closest("[data-comment-id]"); parent && registryEl.contains(parent); parent = root.parentElement?.closest("[data-comment-id]")) {
+          root = parent;
+        }
+        registry.set(commentId, root.cloneNode(true));
+      }
+      return registry;
+    }
     /**
      * Extracts footnote reference IDs from an element.
      */
@@ -2289,6 +3919,92 @@ var Docxodus = (() => {
       }
       return ids;
     }
+    /** Clone a note child for the continuation queue with its original selector position. */
+    cloneFootnoteElementForContinuation(element, sourceIndex) {
+      const clone = element.cloneNode(true);
+      clone.setAttribute(
+        FOOTNOTE_SOURCE_POSITION_ATTR,
+        sourceIndex === 0 ? "first" : "later"
+      );
+      return clone;
+    }
+    /** Remove identities that belong only to the initial registry presentation shell. */
+    makeContinuationShellInert(element) {
+      element.removeAttribute("id");
+      element.removeAttribute("data-anchor");
+      element.removeAttribute("data-committed-text");
+    }
+    /**
+     * Build the exact continuation shape shared by measurement and paint.
+     *
+     * Keep the source `.footnote-item > .footnote-content` ancestry: document
+     * CSS, inherited direction/language, and custom classes frequently target
+     * those shells. Only the number and initial HTML/editor identities are
+     * omitted. A hidden sentinel preserves `p:not(:first-of-type)` for a page
+     * whose first carried element was a later source paragraph.
+     */
+    createFootnoteContinuationWrapper(continuation, elements = continuation.remainingElements) {
+      const source = this.footnoteRegistry.get(continuation.footnoteId);
+      const wrapper = source ? source.cloneNode(false) : this.document.createElement("div");
+      this.makeContinuationShellInert(wrapper);
+      wrapper.classList.add("footnote-continuation");
+      wrapper.dataset.footnoteId = continuation.footnoteId;
+      if (continuation.sourceAnchorId) {
+        wrapper.dataset.sourceAnchorId = continuation.sourceAnchorId;
+      }
+      const sourceContent = source?.querySelector(".footnote-content");
+      const content = sourceContent ? sourceContent.cloneNode(false) : this.document.createElement("span");
+      this.makeContinuationShellInert(content);
+      if (!sourceContent) content.className = "footnote-content";
+      const first = elements[0];
+      if (first?.tagName === "P" && first.getAttribute(FOOTNOTE_SOURCE_POSITION_ATTR) === "later") {
+        const sentinel = this.document.createElement("p");
+        sentinel.className = "footnote-continuation-position-sentinel";
+        sentinel.setAttribute("aria-hidden", "true");
+        sentinel.style.setProperty("display", "none", "important");
+        content.appendChild(sentinel);
+      }
+      for (let index = 0; index < elements.length; index++) {
+        this.checkpoint();
+        const element = elements[index];
+        const clone = element.cloneNode(true);
+        clone.removeAttribute(FOOTNOTE_SOURCE_POSITION_ATTR);
+        if (index === 0 && clone.tagName === "P") {
+          clone.style.setProperty("display", "block", "important");
+        }
+        content.appendChild(clone);
+      }
+      wrapper.appendChild(content);
+      return wrapper;
+    }
+    /** Build the exact partial-note item shape shared by measurement and paint. */
+    createPartialFootnoteItem(footnote, fittingElements) {
+      const item = footnote.cloneNode(false);
+      const number = footnote.querySelector(".footnote-number");
+      if (number) item.appendChild(number.cloneNode(true));
+      const sourceContent = footnote.querySelector(".footnote-content");
+      const content = sourceContent ? sourceContent.cloneNode(false) : this.document.createElement("span");
+      if (!sourceContent) content.className = "footnote-content";
+      for (const element of fittingElements) {
+        this.checkpoint();
+        content.appendChild(element.cloneNode(true));
+      }
+      item.appendChild(content);
+      return item;
+    }
+    /**
+     * Where a note measurement tree is attached.
+     *
+     * A note band is reserved from a measurement and then painted; if the two
+     * happen under different inherited typography the painted notes overflow the
+     * reserve, which is the invisible clipping this engine exists to avoid. The
+     * registry lives in the staging tree but a band paints inside the output
+     * container, so measure there. The host is never a page box, so a page's
+     * `zoom` cannot scale a reserve that is accounted for in unscaled points.
+     */
+    noteMeasurementHost() {
+      return this.containerElement.isConnected ? this.containerElement : this.stagingElement;
+    }
     /**
      * Measures the height of footnotes for given IDs (in points).
      * Creates a temporary container to measure the footnotes.
@@ -2296,140 +4012,246 @@ var Docxodus = (() => {
      * @param contentWidth - Width for measurement
      * @param continuation - Optional continuation content to include first
      */
-    measureFootnotesHeight(footnoteIds, contentWidth, continuation) {
+    measureFootnotesHeight(footnoteIds, contentWidth, continuation, partialFootnotes) {
       const hasContinuation = continuation && continuation.remainingElements.length > 0;
-      if (footnoteIds.length === 0 && !hasContinuation || this.footnoteRegistry.size === 0) {
+      if (footnoteIds.length === 0 && !hasContinuation) {
         return 0;
       }
-      const measureContainer = document.createElement("div");
+      if (this.footnoteRegistry.size === 0 && !hasContinuation) {
+        return 0;
+      }
+      const measureContainer = this.document.createElement("div");
       measureContainer.style.position = "absolute";
       measureContainer.style.visibility = "hidden";
       measureContainer.style.width = `${contentWidth}pt`;
       measureContainer.style.left = "-9999px";
       measureContainer.className = this.cssPrefix + "footnotes";
-      const hr = document.createElement("hr");
-      measureContainer.appendChild(hr);
+      this.appendFootnoteSeparator(measureContainer, Boolean(hasContinuation));
       if (hasContinuation) {
-        const contWrapper = document.createElement("div");
-        contWrapper.className = "footnote-continuation";
-        for (const el of continuation.remainingElements) {
-          contWrapper.appendChild(el.cloneNode(true));
-        }
-        measureContainer.appendChild(contWrapper);
+        measureContainer.appendChild(this.createFootnoteContinuationWrapper(continuation));
       }
+      const partialById = new Map(
+        partialFootnotes?.map((partial) => [partial.footnoteId, partial]) ?? []
+      );
       for (const id of footnoteIds) {
+        this.checkpoint();
         const footnote = this.footnoteRegistry.get(id);
         if (footnote) {
-          measureContainer.appendChild(footnote.cloneNode(true));
+          const partial = partialById.get(id);
+          measureContainer.appendChild(partial ? this.createPartialFootnoteItem(footnote, partial.fittingElements) : footnote.cloneNode(true));
         }
       }
-      this.stagingElement.appendChild(measureContainer);
-      const rect = measureContainer.getBoundingClientRect();
-      const heightPt = pxToPt(rect.height);
-      this.stagingElement.removeChild(measureContainer);
-      return heightPt;
+      this.noteMeasurementHost().appendChild(measureContainer);
+      try {
+        return pxToPt(measureContainer.getBoundingClientRect().height);
+      } finally {
+        measureContainer.remove();
+      }
     }
     /**
-     * Measures the height of just the continuation content (in points).
+     * Partition a continuation for one page's note band, preferring complete children
+     * and range-fragmenting an eligible paragraph when necessary. Always advances by
+     * at least one element so an indivisible oversized paragraph follows the established
+     * clipped fallback without trapping pagination in a loop.
      */
-    measureContinuationHeight(continuation, contentWidth) {
-      if (!continuation || continuation.remainingElements.length === 0) {
-        return 0;
-      }
-      const measureContainer = document.createElement("div");
+    splitContinuationForPage(continuation, availableHeightPt, contentWidth) {
+      const fitting = [];
+      let remaining = [];
+      const measureContainer = this.document.createElement("div");
       measureContainer.style.position = "absolute";
       measureContainer.style.visibility = "hidden";
       measureContainer.style.width = `${contentWidth}pt`;
       measureContainer.style.left = "-9999px";
       measureContainer.className = this.cssPrefix + "footnotes";
-      const hr = document.createElement("hr");
-      measureContainer.appendChild(hr);
-      for (const el of continuation.remainingElements) {
-        measureContainer.appendChild(el.cloneNode(true));
-      }
-      this.stagingElement.appendChild(measureContainer);
-      const rect = measureContainer.getBoundingClientRect();
-      const heightPt = pxToPt(rect.height);
-      this.stagingElement.removeChild(measureContainer);
-      return heightPt;
-    }
-    /**
-     * Splits a footnote element into parts that fit within the available height.
-     * Returns the elements that fit and the elements that need to continue.
-     */
-    splitFootnoteToFit(footnoteElement, availableHeightPt, contentWidth) {
-      const footnoteContent = footnoteElement.querySelector(".footnote-content");
-      if (!footnoteContent) {
-        return {
-          fits: Array.from(footnoteElement.children).map((el) => el.cloneNode(true)),
-          overflow: []
-        };
-      }
-      const children = Array.from(footnoteContent.children);
-      if (children.length <= 1) {
-        return {
-          fits: children.map((el) => el.cloneNode(true)),
-          overflow: []
-        };
-      }
-      const fits = [];
-      const overflow = [];
-      let currentHeight = 0;
-      const hrMeasure = document.createElement("div");
-      hrMeasure.style.position = "absolute";
-      hrMeasure.style.visibility = "hidden";
-      hrMeasure.style.width = `${contentWidth}pt`;
-      hrMeasure.style.left = "-9999px";
-      hrMeasure.className = this.cssPrefix + "footnotes";
-      const hr = document.createElement("hr");
-      hrMeasure.appendChild(hr);
-      this.stagingElement.appendChild(hrMeasure);
-      const hrHeight = pxToPt(hrMeasure.getBoundingClientRect().height);
-      this.stagingElement.removeChild(hrMeasure);
-      currentHeight = hrHeight;
-      const footnoteNumber = footnoteElement.querySelector(".footnote-number");
-      for (let i = 0; i < children.length; i++) {
-        const child = children[i];
-        const measureContainer = document.createElement("div");
-        measureContainer.style.position = "absolute";
-        measureContainer.style.visibility = "hidden";
-        measureContainer.style.width = `${contentWidth}pt`;
-        measureContainer.style.left = "-9999px";
-        measureContainer.className = this.cssPrefix + "footnotes";
-        measureContainer.appendChild(child.cloneNode(true));
-        this.stagingElement.appendChild(measureContainer);
-        const childHeight = pxToPt(measureContainer.getBoundingClientRect().height);
-        this.stagingElement.removeChild(measureContainer);
-        if (currentHeight + childHeight <= availableHeightPt) {
-          fits.push(child.cloneNode(true));
-          currentHeight += childHeight;
-        } else {
-          for (let j = i; j < children.length; j++) {
-            overflow.push(children[j].cloneNode(true));
+      this.appendFootnoteSeparator(measureContainer, true);
+      const wrapper = this.createFootnoteContinuationWrapper(continuation, []);
+      const content = wrapper.querySelector(":scope > .footnote-content");
+      if (!content) {
+        throw new Error("Footnote continuation is missing its content shell");
+      }
+      measureContainer.appendChild(wrapper);
+      this.noteMeasurementHost().appendChild(measureContainer);
+      try {
+        for (let index = 0; index < continuation.remainingElements.length; index++) {
+          this.checkpoint();
+          const element = continuation.remainingElements[index];
+          const sourcePosition = element.getAttribute(FOOTNOTE_SOURCE_POSITION_ATTR);
+          if (fitting.length === 0 && element.tagName === "P" && element.getAttribute(FOOTNOTE_SOURCE_POSITION_ATTR) === "later") {
+            const sentinel = this.document.createElement("p");
+            sentinel.className = "footnote-continuation-position-sentinel";
+            sentinel.setAttribute("aria-hidden", "true");
+            sentinel.style.setProperty("display", "none", "important");
+            content.appendChild(sentinel);
+          }
+          const candidate = element.cloneNode(true);
+          candidate.removeAttribute(FOOTNOTE_SOURCE_POSITION_ATTR);
+          if (fitting.length === 0 && candidate.tagName === "P") {
+            candidate.style.setProperty("display", "block", "important");
+          }
+          content.appendChild(candidate);
+          const candidateHeight = pxToPt(measureContainer.getBoundingClientRect().height);
+          if (candidateHeight <= availableHeightPt) {
+            fitting.push(element);
+            continue;
+          }
+          const canSplitCandidate = candidate.tagName === "P" && this.canRangeFragmentParagraph(candidate);
+          candidate.remove();
+          let split = null;
+          if (canSplitCandidate) {
+            split = this.splitParagraphAtLargestFit(candidate, (head) => {
+              content.appendChild(head);
+              try {
+                return pxToPt(measureContainer.getBoundingClientRect().height) <= availableHeightPt;
+              } finally {
+                head.remove();
+              }
+            }, {
+              // Both fallbacks below cut where ordinary line breaking would not,
+              // so they are only ever right for an element that owns the whole
+              // band: if this page already carries earlier content, a paragraph
+              // that will not start here belongs intact in the next note band.
+              emergencyGraphemeBreaks: fitting.length === 0,
+              // A continuation page owns the full note band. If even one legal
+              // grapheme is taller than it, clip only that unit and keep draining.
+              forceFirstOnNoFit: fitting.length === 0
+            });
+          }
+          if (split?.kind === "split") {
+            if (sourcePosition) {
+              split.head.setAttribute(FOOTNOTE_SOURCE_POSITION_ATTR, sourcePosition);
+              split.tail.setAttribute(FOOTNOTE_SOURCE_POSITION_ATTR, sourcePosition);
+            }
+            fitting.push(split.head);
+            remaining = [split.tail, ...continuation.remainingElements.slice(index + 1)];
+          } else if (fitting.length === 0) {
+            fitting.push(element);
+            remaining = continuation.remainingElements.slice(index + 1);
+          } else {
+            remaining = continuation.remainingElements.slice(index);
           }
           break;
         }
+      } finally {
+        measureContainer.remove();
       }
-      return { fits, overflow };
+      return {
+        current: {
+          footnoteId: continuation.footnoteId,
+          sourceAnchorId: continuation.sourceAnchorId,
+          remainingElements: fitting
+        },
+        overflow: remaining.length > 0 ? {
+          footnoteId: continuation.footnoteId,
+          sourceAnchorId: continuation.sourceAnchorId,
+          remainingElements: remaining
+        } : null
+      };
     }
     /**
-     * Measures a single footnote's height.
+     * Splits a footnote element into parts that fit within the available height.
+     * Returns the elements that fit and the elements that need to continue.
      */
-    measureSingleFootnoteHeight(footnoteId, contentWidth) {
-      const footnote = this.footnoteRegistry.get(footnoteId);
-      if (!footnote) return 0;
-      const measureContainer = document.createElement("div");
+    splitFootnoteToFit(footnoteElement, availableHeightPt, contentWidth, forceProgress = false, existingPayload) {
+      const layoutContext = this.document.createElement("div");
+      layoutContext.style.position = "absolute";
+      layoutContext.style.visibility = "hidden";
+      layoutContext.style.width = `${contentWidth}pt`;
+      layoutContext.style.left = "-9999px";
+      layoutContext.className = this.cssPrefix + "footnotes";
+      this.appendFootnoteSeparator(layoutContext, false);
+      const attachedFootnote = footnoteElement.cloneNode(true);
+      layoutContext.appendChild(attachedFootnote);
+      this.noteMeasurementHost().appendChild(layoutContext);
+      const measureContainer = this.document.createElement("div");
       measureContainer.style.position = "absolute";
       measureContainer.style.visibility = "hidden";
       measureContainer.style.width = `${contentWidth}pt`;
       measureContainer.style.left = "-9999px";
       measureContainer.className = this.cssPrefix + "footnotes";
-      measureContainer.appendChild(footnote.cloneNode(true));
-      this.stagingElement.appendChild(measureContainer);
-      const rect = measureContainer.getBoundingClientRect();
-      const heightPt = pxToPt(rect.height);
-      this.stagingElement.removeChild(measureContainer);
-      return heightPt;
+      const hasContinuation = Boolean(existingPayload?.continuation?.remainingElements.length);
+      this.appendFootnoteSeparator(measureContainer, hasContinuation);
+      if (hasContinuation) {
+        measureContainer.appendChild(this.createFootnoteContinuationWrapper(
+          existingPayload.continuation
+        ));
+      }
+      const partialById = new Map(
+        existingPayload?.partialFootnotes?.map((partial) => [partial.footnoteId, partial]) ?? []
+      );
+      for (const id of existingPayload?.footnoteIds ?? []) {
+        this.checkpoint();
+        const source = this.footnoteRegistry.get(id);
+        if (!source) continue;
+        const partial = partialById.get(id);
+        measureContainer.appendChild(partial ? this.createPartialFootnoteItem(source, partial.fittingElements) : source.cloneNode(true));
+      }
+      const measuredPartial = this.createPartialFootnoteItem(attachedFootnote, []);
+      const measuredContent = measuredPartial.querySelector(":scope > .footnote-content");
+      if (!measuredContent) {
+        layoutContext.remove();
+        throw new Error("Footnote is missing its content shell");
+      }
+      measureContainer.appendChild(measuredPartial);
+      this.noteMeasurementHost().appendChild(measureContainer);
+      try {
+        const footnoteContent = attachedFootnote.querySelector(".footnote-content");
+        if (!footnoteContent) {
+          return {
+            fits: Array.from(attachedFootnote.children).map((el) => el.cloneNode(true)),
+            overflow: []
+          };
+        }
+        const children = Array.from(footnoteContent.children);
+        const fits = [];
+        let overflow = [];
+        for (let i = 0; i < children.length; i++) {
+          this.checkpoint();
+          const child = children[i];
+          const measuredCandidate = child.cloneNode(true);
+          measuredContent.appendChild(measuredCandidate);
+          const candidateFits = pxToPt(measureContainer.getBoundingClientRect().height) <= availableHeightPt;
+          if (candidateFits) {
+            fits.push(child.cloneNode(true));
+            continue;
+          }
+          measuredCandidate.remove();
+          const split = this.canRangeFragmentParagraph(child, true) ? this.splitParagraphAtLargestFit(child, (head) => {
+            measuredContent.appendChild(head);
+            try {
+              return pxToPt(measureContainer.getBoundingClientRect().height) <= availableHeightPt;
+            } finally {
+              head.remove();
+            }
+          }, {
+            // Both fallbacks cut where ordinary line breaking would not, so they
+            // are only ever right for an element that owns the whole band: with
+            // earlier siblings already packed here, a paragraph that will not
+            // start belongs intact in the next note band.
+            emergencyGraphemeBreaks: fits.length === 0 && forceProgress,
+            forceFirstOnNoFit: fits.length === 0 && forceProgress
+          }) : null;
+          if (split?.kind === "split") {
+            fits.push(split.head);
+            split.tail.setAttribute(
+              FOOTNOTE_SOURCE_POSITION_ATTR,
+              i === 0 ? "first" : "later"
+            );
+            overflow = [split.tail, ...children.slice(i + 1).map((element, offset) => this.cloneFootnoteElementForContinuation(element, i + 1 + offset))];
+          } else if (split?.kind === "no-fit") {
+            overflow = children.slice(i).map((element, offset) => this.cloneFootnoteElementForContinuation(element, i + offset));
+          } else if (fits.length === 0 && forceProgress) {
+            fits.push(child.cloneNode(true));
+            overflow = children.slice(i + 1).map((element, offset) => this.cloneFootnoteElementForContinuation(element, i + 1 + offset));
+          } else {
+            overflow = children.slice(i).map((element, offset) => this.cloneFootnoteElementForContinuation(element, i + offset));
+          }
+          break;
+        }
+        return { fits, overflow };
+      } finally {
+        measureContainer.remove();
+        layoutContext.remove();
+      }
     }
     /**
      * Adds footnotes to a page container, including continuation content.
@@ -2442,12 +4264,11 @@ var Docxodus = (() => {
       if (this.footnoteRegistry.size === 0 && !hasContinuation) {
         return;
       }
-      const partialFootnoteIds = new Set(partialFootnotes?.map((p) => p.footnoteId) || []);
       const maxFootnoteHeight = Math.min(
         footnoteHeight,
         bands.bodyHeight * MAX_FOOTNOTE_AREA_RATIO
       );
-      const footnotesDiv = document.createElement("div");
+      const footnotesDiv = this.document.createElement("div");
       footnotesDiv.className = `${this.cssPrefix}footnotes`;
       footnotesDiv.style.position = "absolute";
       footnotesDiv.style.bottom = `${dims.pageHeight - (bands.bodyTop + bands.bodyHeight)}pt`;
@@ -2456,35 +4277,18 @@ var Docxodus = (() => {
       footnotesDiv.style.boxSizing = "border-box";
       footnotesDiv.style.maxHeight = `${maxFootnoteHeight}pt`;
       footnotesDiv.style.overflow = "hidden";
-      const hr = document.createElement("hr");
-      footnotesDiv.appendChild(hr);
+      this.appendFootnoteSeparator(footnotesDiv, Boolean(hasContinuation));
       if (hasContinuation) {
-        const contWrapper = document.createElement("div");
-        contWrapper.className = "footnote-continuation";
-        for (const el of continuation.remainingElements) {
-          contWrapper.appendChild(el.cloneNode(true));
-        }
-        footnotesDiv.appendChild(contWrapper);
+        footnotesDiv.appendChild(this.createFootnoteContinuationWrapper(continuation));
       }
       for (const id of footnoteIds) {
         const partial = partialFootnotes?.find((p) => p.footnoteId === id);
         if (partial) {
           const footnote = this.footnoteRegistry.get(id);
           if (footnote) {
-            const partialDiv = document.createElement("div");
-            partialDiv.className = "footnote-item";
-            partialDiv.dataset.footnoteId = id;
-            const numberSpan = footnote.querySelector(".footnote-number");
-            if (numberSpan) {
-              partialDiv.appendChild(numberSpan.cloneNode(true));
-            }
-            const contentSpan = document.createElement("span");
-            contentSpan.className = "footnote-content";
-            for (const el of partial.fittingElements) {
-              contentSpan.appendChild(el.cloneNode(true));
-            }
-            partialDiv.appendChild(contentSpan);
-            footnotesDiv.appendChild(partialDiv);
+            footnotesDiv.appendChild(
+              this.createPartialFootnoteItem(footnote, partial.fittingElements)
+            );
           }
         } else {
           const footnote = this.footnoteRegistry.get(id);
@@ -2495,30 +4299,26 @@ var Docxodus = (() => {
       }
       pageBox.appendChild(footnotesDiv);
     }
-    /**
-     * Selects the appropriate header for a page based on section, page position, and page number.
-     */
-    selectHeader(sectionIndex, pageInSection, globalPageNumber) {
+    /** Select the section's first/odd/even header from its one-based page position. */
+    selectHeader(sectionIndex, pageInSection, displayedPageNumber) {
       const sectionHf = this.hfRegistry.get(sectionIndex);
       if (!sectionHf) return void 0;
       if (pageInSection === 1 && sectionHf.headerFirst) {
         return sectionHf.headerFirst;
       }
-      if (globalPageNumber % 2 === 0 && sectionHf.headerEven) {
+      if (displayedPageNumber % 2 === 0 && sectionHf.headerEven) {
         return sectionHf.headerEven;
       }
       return sectionHf.headerDefault;
     }
-    /**
-     * Selects the appropriate footer for a page based on section, page position, and page number.
-     */
-    selectFooter(sectionIndex, pageInSection, globalPageNumber) {
+    /** Select the section's first/odd/even footer from its one-based page position. */
+    selectFooter(sectionIndex, pageInSection, displayedPageNumber) {
       const sectionHf = this.hfRegistry.get(sectionIndex);
       if (!sectionHf) return void 0;
       if (pageInSection === 1 && sectionHf.footerFirst) {
         return sectionHf.footerFirst;
       }
-      if (globalPageNumber % 2 === 0 && sectionHf.footerEven) {
+      if (displayedPageNumber % 2 === 0 && sectionHf.footerEven) {
         return sectionHf.footerEven;
       }
       return sectionHf.footerDefault;
@@ -2533,7 +4333,7 @@ var Docxodus = (() => {
      * Deterministic: it depends only on the section's page setup and the registry's pre-measured
      * story heights, never on the page's content, which is what keeps it lazy-loading compatible.
      */
-    getPageBands(dims, sectionIndex, pageInSection, globalPageNumber) {
+    getPageBands(dims, sectionIndex, pageInSection, displayedPageNumber) {
       const sectionHf = this.hfRegistry.get(sectionIndex);
       return resolvePageBands(
         dims,
@@ -2542,14 +4342,14 @@ var Docxodus = (() => {
           sectionHf?.headerEvenHeight,
           sectionHf?.headerDefaultHeight,
           pageInSection,
-          globalPageNumber
+          displayedPageNumber
         ),
         this.selectStoryHeight(
           sectionHf?.footerFirstHeight,
           sectionHf?.footerEvenHeight,
           sectionHf?.footerDefaultHeight,
           pageInSection,
-          globalPageNumber
+          displayedPageNumber
         )
       );
     }
@@ -2557,9 +4357,9 @@ var Docxodus = (() => {
      * The measured height of the running story this page position selects, mirroring
      * {@link selectHeader}/{@link selectFooter}. Zero when the page has no such story.
      */
-    selectStoryHeight(first, even, fallback, pageInSection, globalPageNumber) {
+    selectStoryHeight(first, even, fallback, pageInSection, displayedPageNumber) {
       if (pageInSection === 1 && first != null) return first;
-      if (globalPageNumber % 2 === 0 && even != null) return even;
+      if (displayedPageNumber % 2 === 0 && even != null) return even;
       return fallback ?? 0;
     }
     /**
@@ -2571,7 +4371,7 @@ var Docxodus = (() => {
      * silently starts overlapping body text.
      */
     measureHeaderFooterHeight(source, contentWidth) {
-      const measureContainer = document.createElement("div");
+      const measureContainer = this.document.createElement("div");
       measureContainer.style.position = "absolute";
       measureContainer.style.visibility = "hidden";
       measureContainer.style.width = `${contentWidth}pt`;
@@ -2590,79 +4390,275 @@ var Docxodus = (() => {
      * Implements a single-pass, forward-only algorithm that is compatible with future lazy loading.
      * Supports footnote continuation - long footnotes can split across pages.
      */
-    flowToPages(blocks, dims, startPageNumber, sectionIndex) {
+    flowToPages(blocks, dims, startPageNumber, sectionIndex, sectionDimensions) {
       const pages = [];
       let currentContent = [];
       let pageNumber = startPageNumber;
-      let pageInSection = 1;
+      let pageSectionIndex = sectionIndex;
+      const sectionStartPages = /* @__PURE__ */ new Map([[sectionIndex, startPageNumber]]);
+      const pageInSection = (owner = pageSectionIndex, physicalPage = pageNumber) => physicalPage - (sectionStartPages.get(owner) ?? physicalPage) + 1;
+      const dimensionsFor = (owner = pageSectionIndex) => sectionDimensions.get(owner) ?? dims;
+      const markSectionPlaced = (owner) => {
+        if (!sectionStartPages.has(owner)) sectionStartPages.set(owner, pageNumber);
+      };
+      const previousBox = this.containerElement.querySelector(
+        `.${this.cssPrefix}box:last-of-type`
+      );
+      let precedingDisplayedPageNumber = parseInt(
+        previousBox?.dataset.displayedPageNumber ?? "0",
+        10
+      );
+      const displayedPageNumber = (owner = pageSectionIndex, ownerPageInSection = pageInSection(owner), physicalPage = pageNumber) => {
+        const numbering = this.pageNumbering.get(owner) ?? {};
+        if (numbering.start !== void 0) {
+          return numbering.start + ownerPageInSection - 1;
+        }
+        const ownerNumbering = this.pageNumbering.get(pageSectionIndex) ?? {};
+        const currentPhysicalNumber = ownerNumbering.start !== void 0 ? ownerNumbering.start + pageInSection(pageSectionIndex) - 1 : precedingDisplayedPageNumber + 1;
+        return currentPhysicalNumber + physicalPage - pageNumber;
+      };
       let { bodyHeight: effectiveContentHeight } = this.getPageBands(
-        dims,
-        sectionIndex,
-        pageInSection,
-        pageNumber
+        dimensionsFor(),
+        pageSectionIndex,
+        pageInSection(),
+        displayedPageNumber()
       );
       let remainingHeight = effectiveContentHeight;
       let prevMarginBottomPt = 0;
       let currentFootnoteIds = [];
+      let currentPageHasFootnoteReference = false;
       let currentFootnoteHeight = 0;
       let currentContinuation = this.pendingFootnoteContinuation;
       let nextPageContinuation = null;
+      let currentContinuationPartitioned = false;
+      let currentPageAdmitted = false;
       let deferredFootnoteIds = [];
       let currentPartialFootnotes = [];
-      if (currentContinuation && currentContinuation.remainingElements.length > 0) {
-        currentFootnoteHeight = this.measureContinuationHeight(currentContinuation, dims.contentWidth);
-      }
-      const finishPage = () => {
+      const adoptEmptyPageOwner = (owner) => {
+        pageSectionIndex = owner;
+        const bands = this.getPageBands(
+          dimensionsFor(owner),
+          owner,
+          pageInSection(owner),
+          displayedPageNumber(owner)
+        );
+        effectiveContentHeight = bands.bodyHeight;
+        remainingHeight = effectiveContentHeight;
+      };
+      const admitCurrentPage = () => {
+        if (currentPageAdmitted) return;
+        this.admitPageAllocation();
+        currentPageAdmitted = true;
+      };
+      const prepareCurrentContinuation = () => {
+        if (currentContinuationPartitioned || (currentContinuation?.remainingElements.length ?? 0) === 0) return;
+        admitCurrentPage();
+        const ownedDimensions = dimensionsFor();
+        const pageBands = this.getPageBands(
+          ownedDimensions,
+          pageSectionIndex,
+          pageInSection(),
+          displayedPageNumber()
+        );
+        const partition = this.splitContinuationForPage(
+          currentContinuation,
+          pageBands.bodyHeight * MAX_FOOTNOTE_AREA_RATIO,
+          ownedDimensions.contentWidth
+        );
+        currentContinuation = partition.current;
+        if (partition.overflow) nextPageContinuation = partition.overflow;
+        currentContinuationPartitioned = true;
+        currentFootnoteHeight = this.measureFootnotesHeight(
+          currentFootnoteIds,
+          ownedDimensions.contentWidth,
+          currentContinuation,
+          currentPartialFootnotes
+        );
+      };
+      const finishPage = (nextPageSectionIndex = pageSectionIndex, forceEmptyPage = false) => {
         const hasCurrentContinuation = (currentContinuation?.remainingElements.length ?? 0) > 0;
-        if (currentContent.length === 0 && !hasCurrentContinuation) return;
+        if (!forceEmptyPage && currentContent.length === 0 && currentFootnoteIds.length === 0 && !hasCurrentContinuation) {
+          adoptEmptyPageOwner(nextPageSectionIndex);
+          return;
+        }
+        prepareCurrentContinuation();
+        admitCurrentPage();
+        let pageContinuation = currentContinuation;
+        const ownedPageInSection = pageInSection();
+        const ownedDimensions = dimensionsFor();
+        const ownedDisplayedPageNumber = displayedPageNumber(
+          pageSectionIndex,
+          ownedPageInSection
+        );
+        const pageBands = this.getPageBands(
+          ownedDimensions,
+          pageSectionIndex,
+          ownedPageInSection,
+          ownedDisplayedPageNumber
+        );
+        const maxFootnoteHeight = pageBands.bodyHeight * MAX_FOOTNOTE_AREA_RATIO;
+        pageContinuation = currentContinuation;
+        currentFootnoteHeight = this.measureFootnotesHeight(
+          currentFootnoteIds,
+          ownedDimensions.contentWidth,
+          pageContinuation,
+          currentPartialFootnotes
+        );
+        if (currentContent.length === 0 && currentFootnoteIds.length > 0 && currentPartialFootnotes.length === 0) {
+          const fittingIds = [];
+          for (let index = 0; index < currentFootnoteIds.length; index++) {
+            const footnoteId = currentFootnoteIds[index];
+            const candidateIds = [...fittingIds, footnoteId];
+            const candidateHeight = this.measureFootnotesHeight(
+              candidateIds,
+              ownedDimensions.contentWidth,
+              pageContinuation
+            );
+            const guardedCandidateHeight = candidateHeight + FOOTNOTE_MEASUREMENT_GUARD_PT;
+            if (guardedCandidateHeight <= maxFootnoteHeight) {
+              fittingIds.push(footnoteId);
+              currentFootnoteHeight = guardedCandidateHeight;
+              continue;
+            }
+            const hasPageContinuation = (pageContinuation?.remainingElements.length ?? 0) > 0;
+            if (fittingIds.length === 0 && !hasPageContinuation) {
+              const source = this.footnoteRegistry.get(footnoteId);
+              const split = source ? this.splitFootnoteToFit(
+                source,
+                maxFootnoteHeight - FOOTNOTE_MEASUREMENT_GUARD_PT,
+                ownedDimensions.contentWidth,
+                true
+              ) : null;
+              fittingIds.push(footnoteId);
+              if (source && split && split.fits.length > 0 && split.overflow.length > 0) {
+                currentPartialFootnotes.push({ footnoteId, fittingElements: split.fits });
+                nextPageContinuation = {
+                  footnoteId,
+                  sourceAnchorId: source.dataset.sourceAnchorId,
+                  remainingElements: split.overflow
+                };
+                currentFootnoteHeight = maxFootnoteHeight;
+              } else {
+                currentFootnoteHeight = guardedCandidateHeight;
+              }
+              deferredFootnoteIds.push(...currentFootnoteIds.slice(index + 1));
+            } else {
+              deferredFootnoteIds.push(...currentFootnoteIds.slice(index));
+            }
+            break;
+          }
+          currentFootnoteIds = fittingIds;
+        }
         const page = this.createPage(
-          dims,
+          ownedDimensions,
           pageNumber,
-          sectionIndex,
+          pageSectionIndex,
+          ownedDisplayedPageNumber,
           currentContent,
-          pageInSection,
+          ownedPageInSection,
           currentFootnoteIds,
           currentFootnoteHeight,
-          currentContinuation,
-          currentPartialFootnotes.length > 0 ? currentPartialFootnotes : void 0
+          pageContinuation,
+          currentPartialFootnotes.length > 0 ? currentPartialFootnotes : void 0,
+          false,
+          currentPageAdmitted
         );
         pages.push(page);
+        precedingDisplayedPageNumber = ownedDisplayedPageNumber;
         pageNumber++;
-        pageInSection++;
         currentContent = [];
-        const newBands = this.getPageBands(dims, sectionIndex, pageInSection, pageNumber);
+        pageSectionIndex = nextPageSectionIndex;
+        if (!sectionStartPages.has(pageSectionIndex)) {
+          sectionStartPages.set(pageSectionIndex, pageNumber);
+        }
+        const newBands = this.getPageBands(
+          dimensionsFor(),
+          pageSectionIndex,
+          pageInSection(),
+          displayedPageNumber()
+        );
         effectiveContentHeight = newBands.bodyHeight;
         remainingHeight = effectiveContentHeight;
         prevMarginBottomPt = 0;
         currentFootnoteIds = [];
+        currentPageHasFootnoteReference = false;
         currentPartialFootnotes = [];
         currentContinuation = nextPageContinuation;
         nextPageContinuation = null;
+        currentContinuationPartitioned = false;
+        currentPageAdmitted = false;
         if (deferredFootnoteIds.length > 0) {
           currentFootnoteIds = [...deferredFootnoteIds];
           deferredFootnoteIds = [];
         }
-        if (currentContinuation && currentContinuation.remainingElements.length > 0) {
-          currentFootnoteHeight = this.measureContinuationHeight(currentContinuation, dims.contentWidth);
-        } else {
-          currentFootnoteHeight = 0;
-        }
-        if (currentFootnoteIds.length > 0) {
-          currentFootnoteHeight += this.measureFootnotesHeight(
-            currentFootnoteIds,
-            dims.contentWidth,
-            null
-          );
-        }
+        const nextDimensions = dimensionsFor();
+        currentFootnoteHeight = currentContinuation ? 0 : this.measureFootnotesHeight(currentFootnoteIds, nextDimensions.contentWidth);
       };
+      const pageHasPayload = () => currentContent.length > 0 || currentFootnoteIds.length > 0 || (currentContinuation?.remainingElements.length ?? 0) > 0;
       for (let i = 0; i < blocks.length; i++) {
+        this.checkpoint();
         const block = blocks[i];
+        const allBlockFootnoteIds = this.extractFootnoteRefs(block.element);
+        if (block.sectionIndex !== pageSectionIndex && currentPageHasFootnoteReference && (!this.footnoteLayoutLikeWord8 || allBlockFootnoteIds.length > 0)) {
+          finishPage(block.sectionIndex);
+        }
+        const pageIsEmpty = currentContent.length === 0 && currentFootnoteIds.length === 0 && (currentContinuation?.remainingElements.length ?? 0) === 0;
+        if (pageIsEmpty && block.sectionIndex !== pageSectionIndex) {
+          adoptEmptyPageOwner(block.sectionIndex);
+        }
+        prepareCurrentContinuation();
+        if (currentFootnoteHeight > 0) {
+          const ownerDimensions = dimensionsFor();
+          const ownerBands = this.getPageBands(
+            ownerDimensions,
+            pageSectionIndex,
+            pageInSection(),
+            displayedPageNumber()
+          );
+          const ownerMaxFootnoteArea = ownerBands.bodyHeight * MAX_FOOTNOTE_AREA_RATIO;
+          if (currentFootnoteHeight > ownerMaxFootnoteArea) {
+            const fittingIds = [];
+            let fittingHeight = 0;
+            if ((currentContinuation?.remainingElements.length ?? 0) === 0 && currentPartialFootnotes.length === 0) {
+              for (const footnoteId of currentFootnoteIds) {
+                this.checkpoint();
+                const candidateHeight = this.measureFootnotesHeight(
+                  [...fittingIds, footnoteId],
+                  ownerDimensions.contentWidth
+                );
+                if (candidateHeight + FOOTNOTE_MEASUREMENT_GUARD_PT > ownerMaxFootnoteArea) break;
+                fittingIds.push(footnoteId);
+                fittingHeight = candidateHeight;
+              }
+            }
+            if (fittingIds.length > 0) {
+              deferredFootnoteIds = [
+                ...currentFootnoteIds.slice(fittingIds.length),
+                ...deferredFootnoteIds
+              ];
+              currentFootnoteIds = fittingIds;
+              currentFootnoteHeight = fittingHeight;
+            } else {
+              finishPage(block.sectionIndex);
+              i--;
+              continue;
+            }
+          }
+        }
+        const blockDimensions = dimensionsFor(block.sectionIndex);
+        const nextBlockPageInSection = pageInSection(block.sectionIndex, pageNumber + 1);
+        const freshBlockPageBodyHeight = this.getPageBands(
+          blockDimensions,
+          block.sectionIndex,
+          nextBlockPageInSection,
+          displayedPageNumber(block.sectionIndex, nextBlockPageInSection, pageNumber + 1)
+        ).bodyHeight;
         if (block.isPageBreak) {
-          finishPage();
+          finishPage(block.sectionIndex);
           continue;
         }
         if (block.pageBreakBefore && currentContent.length > 0) {
-          finishPage();
+          finishPage(block.sectionIndex);
         }
         const previousBlock = blocks[i - 1];
         const startsKeepChain = !previousBlock || !previousBlock.keepWithNext || previousBlock.isPageBreak || block.pageBreakBefore;
@@ -2678,7 +4674,7 @@ var Docxodus = (() => {
             if (newChainFootnoteIds.length > 0 && this.footnoteRegistry.size > 0) {
               const totalChainFootnoteHeight = this.measureFootnotesHeight(
                 [...currentFootnoteIds, ...newChainFootnoteIds],
-                dims.contentWidth,
+                blockDimensions.contentWidth,
                 currentContinuation
               );
               additionalChainFootnoteHeight = Math.max(
@@ -2690,61 +4686,68 @@ var Docxodus = (() => {
               keepChain,
               prevMarginBottomPt,
               currentContent.length === 0,
-              pageInSection
+              pageInSection(block.sectionIndex)
             ) + additionalChainFootnoteHeight;
             const currentAvailableHeight = remainingHeight - currentFootnoteHeight;
             if (currentChainHeight > currentAvailableHeight) {
               const nextPageBands = this.getPageBands(
-                dims,
-                sectionIndex,
-                pageInSection + 1,
-                pageNumber + 1
+                dimensionsFor(block.sectionIndex),
+                block.sectionIndex,
+                pageInSection(block.sectionIndex, pageNumber + 1),
+                displayedPageNumber(
+                  block.sectionIndex,
+                  pageInSection(block.sectionIndex, pageNumber + 1),
+                  pageNumber + 1
+                )
               );
               const freshChainBodyHeight = this.measureKeepWithNextChainBodyHeight(
                 keepChain,
                 0,
                 true,
-                pageInSection + 1
+                pageInSection(block.sectionIndex, pageNumber + 1)
               );
               const freshChainFootnoteHeight = this.measureFootnotesHeight(
                 newChainFootnoteIds,
-                dims.contentWidth,
+                blockDimensions.contentWidth,
                 nextPageContinuation
               );
               if (freshChainBodyHeight + freshChainFootnoteHeight <= nextPageBands.bodyHeight) {
-                finishPage();
+                finishPage(block.sectionIndex);
               }
             }
           }
         }
-        const allBlockFootnoteIds = this.extractFootnoteRefs(block.element);
         const newFootnoteIds = this.collectNewFootnoteIds([block], currentFootnoteIds);
+        let combinedFootnoteHeight = currentFootnoteHeight;
         let additionalFootnoteHeight = 0;
         if (newFootnoteIds.length > 0 && this.footnoteRegistry.size > 0) {
           const combinedFootnoteIds = [...currentFootnoteIds, ...newFootnoteIds];
-          const totalFootnoteHeight = this.measureFootnotesHeight(
+          combinedFootnoteHeight = this.measureFootnotesHeight(
             combinedFootnoteIds,
-            dims.contentWidth,
-            currentContinuation
+            blockDimensions.contentWidth,
+            currentContinuation,
+            currentPartialFootnotes
+          );
+          additionalFootnoteHeight = Math.max(
+            0,
+            combinedFootnoteHeight - currentFootnoteHeight
           );
-          additionalFootnoteHeight = totalFootnoteHeight - currentFootnoteHeight;
         }
         const isFirstOnPage = currentContent.length === 0;
         const effectiveMarginTop = this.effectiveBlockMarginTop(
           block,
           prevMarginBottomPt,
           isFirstOnPage,
-          pageInSection
+          pageInSection(block.sectionIndex)
         );
         const blockSpace = effectiveMarginTop + block.heightPt + additionalFootnoteHeight;
         const effectiveRemainingHeight = remainingHeight - currentFootnoteHeight;
         const bodyContentUsed = effectiveContentHeight - remainingHeight;
         const maxFootnoteArea = effectiveContentHeight * MAX_FOOTNOTE_AREA_RATIO;
-        const maxFootnoteExpansion = Math.max(0, maxFootnoteArea - currentFootnoteHeight);
         if (blockSpace > effectiveRemainingHeight) {
           const paragraphFragments = this.tryFragmentParagraph(
             block,
-            dims,
+            blockDimensions,
             effectiveRemainingHeight,
             effectiveMarginTop
           );
@@ -2754,40 +4757,74 @@ var Docxodus = (() => {
             continue;
           }
         }
-        if (blockSpace <= effectiveRemainingHeight) {
-          currentContent.push(this.cloneBlockForPage(block, isFirstOnPage, pageInSection));
+        if (blockSpace <= effectiveRemainingHeight && (combinedFootnoteHeight === 0 || combinedFootnoteHeight + FOOTNOTE_MEASUREMENT_GUARD_PT <= maxFootnoteArea)) {
+          markSectionPlaced(block.sectionIndex);
+          currentContent.push(this.cloneBlockForPage(
+            block,
+            isFirstOnPage,
+            pageInSection(block.sectionIndex)
+          ));
           remainingHeight -= effectiveMarginTop + block.heightPt + block.marginBottomPt;
           prevMarginBottomPt = block.marginBottomPt;
           if (newFootnoteIds.length > 0) {
             currentFootnoteIds.push(...newFootnoteIds);
-            currentFootnoteHeight += additionalFootnoteHeight;
+            currentFootnoteHeight = combinedFootnoteHeight;
           }
-        } else if (block.heightPt + this.effectiveBlockMarginTop(block, 0, true, pageInSection + 1) <= effectiveContentHeight) {
+          currentPageHasFootnoteReference ||= allBlockFootnoteIds.length > 0;
+        } else if (block.heightPt + this.effectiveBlockMarginTop(
+          block,
+          0,
+          true,
+          pageInSection(block.sectionIndex, pageNumber + 1)
+        ) <= freshBlockPageBodyHeight) {
           const blockSpaceWithoutFootnotes = effectiveMarginTop + block.heightPt;
-          const minBodySpaceNeeded = bodyContentUsed + blockSpaceWithoutFootnotes + MIN_BODY_CONTENT_HEIGHT;
-          const canExpandFootnotes = minBodySpaceNeeded <= effectiveContentHeight;
           if (newFootnoteIds.length > 0 && blockSpaceWithoutFootnotes <= effectiveRemainingHeight) {
-            currentContent.push(this.cloneBlockForPage(block, isFirstOnPage, pageInSection));
+            markSectionPlaced(block.sectionIndex);
+            currentContent.push(this.cloneBlockForPage(
+              block,
+              isFirstOnPage,
+              pageInSection(block.sectionIndex)
+            ));
             remainingHeight -= effectiveMarginTop + block.heightPt + block.marginBottomPt;
             prevMarginBottomPt = block.marginBottomPt;
             const availableForFootnotes = Math.min(
               maxFootnoteArea,
               effectiveContentHeight - bodyContentUsed - blockSpaceWithoutFootnotes
             );
-            for (const footnoteId of newFootnoteIds) {
+            const nextPageMaxFootnoteArea = freshBlockPageBodyHeight * MAX_FOOTNOTE_AREA_RATIO;
+            const deferralCannotHelp = availableForFootnotes >= nextPageMaxFootnoteArea;
+            for (let noteIndex = 0; noteIndex < newFootnoteIds.length; noteIndex++) {
+              this.checkpoint();
+              const footnoteId = newFootnoteIds[noteIndex];
               const footnote = this.footnoteRegistry.get(footnoteId);
               if (!footnote) continue;
-              const footnoteHeight = this.measureSingleFootnoteHeight(footnoteId, dims.contentWidth);
+              if (nextPageContinuation) {
+                deferredFootnoteIds.push(...newFootnoteIds.slice(noteIndex));
+                break;
+              }
+              const candidateIds = [...currentFootnoteIds, footnoteId];
+              const candidateHeight = this.measureFootnotesHeight(
+                candidateIds,
+                blockDimensions.contentWidth,
+                currentContinuation,
+                currentPartialFootnotes
+              );
               const spaceLeftForFootnotes = availableForFootnotes - currentFootnoteHeight;
-              if (footnoteHeight <= spaceLeftForFootnotes) {
+              if (candidateHeight + FOOTNOTE_MEASUREMENT_GUARD_PT <= availableForFootnotes) {
                 currentFootnoteIds.push(footnoteId);
-                currentFootnoteHeight += footnoteHeight;
+                currentFootnoteHeight = candidateHeight;
               } else {
                 if (spaceLeftForFootnotes > 20) {
                   const { fits, overflow } = this.splitFootnoteToFit(
                     footnote,
-                    spaceLeftForFootnotes,
-                    dims.contentWidth
+                    availableForFootnotes,
+                    blockDimensions.contentWidth,
+                    deferralCannotHelp,
+                    {
+                      footnoteIds: currentFootnoteIds,
+                      continuation: currentContinuation,
+                      partialFootnotes: currentPartialFootnotes
+                    }
                   );
                   if (fits.length > 0) {
                     currentFootnoteIds.push(footnoteId);
@@ -2798,78 +4835,70 @@ var Docxodus = (() => {
                     if (overflow.length > 0) {
                       nextPageContinuation = {
                         footnoteId,
+                        sourceAnchorId: footnote.dataset.sourceAnchorId,
                         remainingElements: overflow
                       };
                     }
-                    currentFootnoteHeight = availableForFootnotes;
+                    currentFootnoteHeight = this.measureFootnotesHeight(
+                      currentFootnoteIds,
+                      blockDimensions.contentWidth,
+                      currentContinuation,
+                      currentPartialFootnotes
+                    );
+                    if (overflow.length > 0) {
+                      deferredFootnoteIds.push(...newFootnoteIds.slice(noteIndex + 1));
+                      break;
+                    }
                   } else {
-                    deferredFootnoteIds.push(footnoteId);
+                    deferredFootnoteIds.push(...newFootnoteIds.slice(noteIndex));
+                    break;
                   }
                 } else {
-                  deferredFootnoteIds.push(footnoteId);
+                  deferredFootnoteIds.push(...newFootnoteIds.slice(noteIndex));
+                  break;
                 }
               }
             }
-          } else if (canExpandFootnotes && newFootnoteIds.length > 0) {
-            const expandedFootnoteSpace = Math.min(maxFootnoteArea, additionalFootnoteHeight + currentFootnoteHeight);
-            const bodySpaceAfterExpansion = effectiveContentHeight - expandedFootnoteSpace;
-            if (blockSpaceWithoutFootnotes <= bodySpaceAfterExpansion - bodyContentUsed) {
-              currentContent.push(this.cloneBlockForPage(block, isFirstOnPage, pageInSection));
-              remainingHeight = bodySpaceAfterExpansion - bodyContentUsed - blockSpaceWithoutFootnotes;
-              prevMarginBottomPt = block.marginBottomPt;
-              currentFootnoteIds.push(...newFootnoteIds);
-              currentFootnoteHeight = expandedFootnoteSpace;
-            } else {
-              finishPage();
-              const newPageFootnoteHeight = allBlockFootnoteIds.length > 0 ? this.measureFootnotesHeight(allBlockFootnoteIds, dims.contentWidth, currentContinuation) : currentContinuation ? this.measureContinuationHeight(currentContinuation, dims.contentWidth) : 0;
-              const newPageMarginTop = this.effectiveBlockMarginTop(
-                block,
-                0,
-                true,
-                pageInSection
-              );
-              const newPageSpace = newPageMarginTop + block.heightPt + block.marginBottomPt;
-              currentContent.push(this.cloneBlockForPage(block, true, pageInSection));
-              remainingHeight = effectiveContentHeight - newPageSpace;
-              prevMarginBottomPt = block.marginBottomPt;
-              currentFootnoteIds = [...currentFootnoteIds, ...allBlockFootnoteIds];
-              currentFootnoteHeight = newPageFootnoteHeight;
-            }
+            currentPageHasFootnoteReference ||= allBlockFootnoteIds.length > 0;
           } else {
-            finishPage();
-            const newPageFootnoteHeight = allBlockFootnoteIds.length > 0 ? this.measureFootnotesHeight(allBlockFootnoteIds, dims.contentWidth, currentContinuation) : currentContinuation ? this.measureContinuationHeight(currentContinuation, dims.contentWidth) : 0;
-            const newPageMarginTop = this.effectiveBlockMarginTop(
-              block,
-              0,
-              true,
-              pageInSection
-            );
-            const newPageSpace = newPageMarginTop + block.heightPt + block.marginBottomPt;
-            currentContent.push(this.cloneBlockForPage(block, true, pageInSection));
-            remainingHeight = effectiveContentHeight - newPageSpace;
-            prevMarginBottomPt = block.marginBottomPt;
-            currentFootnoteIds = [...currentFootnoteIds, ...allBlockFootnoteIds];
-            currentFootnoteHeight = newPageFootnoteHeight;
+            finishPage(block.sectionIndex, !pageHasPayload());
+            i--;
+            continue;
           }
         } else {
-          const tableFragments = this.trySplitSimpleOversizedTable(block, dims, sectionIndex);
+          const tableFragments = this.trySplitSimpleOversizedTable(
+            block,
+            dimensionsFor(block.sectionIndex),
+            block.sectionIndex
+          );
           if (tableFragments) {
             if (currentContent.length > 0 || currentContinuation) {
-              finishPage();
+              finishPage(block.sectionIndex);
             }
             blocks.splice(i, 1, ...tableFragments);
             i--;
             continue;
           }
-          if (currentContent.length > 0) {
-            finishPage();
+          if (pageHasPayload()) {
+            finishPage(block.sectionIndex);
+            i--;
+            continue;
           }
-          currentContent.push(this.cloneBlockForPage(block, true, pageInSection));
-          currentFootnoteIds = [...currentFootnoteIds, ...allBlockFootnoteIds];
-          finishPage();
+          markSectionPlaced(block.sectionIndex);
+          currentContent.push(this.cloneBlockForPage(
+            block,
+            true,
+            pageInSection(block.sectionIndex)
+          ));
+          deferredFootnoteIds.push(...newFootnoteIds);
+          currentPageHasFootnoteReference ||= allBlockFootnoteIds.length > 0;
+          finishPage(block.sectionIndex);
         }
       }
       finishPage();
+      while (currentFootnoteIds.length > 0 || deferredFootnoteIds.length > 0 || (currentContinuation?.remainingElements.length ?? 0) > 0) {
+        finishPage();
+      }
       this.pendingFootnoteContinuation = nextPageContinuation;
       return pages;
     }
@@ -2894,6 +4923,19 @@ var Docxodus = (() => {
         if (el.getAttribute("contenteditable") !== null) el.setAttribute("contenteditable", "false");
       }
     }
+    /** A repeated margin note is presentation, not a second bookmark/link target. */
+    makeClonedMarginCommentInert(root) {
+      this.makeClonedStoryInert(root);
+      const nodes = [root, ...Array.from(root.querySelectorAll("*"))];
+      for (const element of nodes) {
+        element.removeAttribute("id");
+        if (element.localName === "a" && element.getAttribute("href")?.startsWith("#")) {
+          element.removeAttribute("href");
+          element.setAttribute("aria-disabled", "true");
+          element.tabIndex = -1;
+        }
+      }
+    }
     /**
      * Resolves floating DrawingML objects after their anchor paragraphs have landed on a page.
      *
@@ -2919,7 +4961,7 @@ var Docxodus = (() => {
         const context = {
           staticLeft: toPageX(staticRect.left),
           staticTop: toPageY(staticRect.top),
-          lineHeight: paragraph ? (parseFloat(getComputedStyle(paragraph).lineHeight) || staticRect.height) / pixelsPerPoint : staticRect.height / pixelsPerPoint,
+          lineHeight: paragraph ? (parseFloat(this.view.getComputedStyle(paragraph).lineHeight) || staticRect.height) / pixelsPerPoint : staticRect.height / pixelsPerPoint,
           paragraphLeft: toPageX(paragraphRect.left),
           paragraphTop: toPageY(paragraphRect.top),
           paragraphWidth: paragraphRect.width / pixelsPerPoint,
@@ -3049,36 +5091,48 @@ var Docxodus = (() => {
       else if (alignment === "outside") fraction = pageNumber % 2 === 1 ? 1 : 0;
       return reference.start + (reference.size - objectSize) * fraction;
     }
+    /** Charge a physical page before any page-owned partitioning or DOM allocation. */
+    admitPageAllocation() {
+      const prospectivePageCount = this.createdPageCount + 1;
+      this.pageCountCheckpoint?.(prospectivePageCount);
+      this.createdPageCount = prospectivePageCount;
+    }
     /**
      * Creates a page container element.
      */
-    createPage(dims, pageNumber, sectionIndex, content, pageInSection, footnoteIds = [], footnoteHeight = 0, continuation, partialFootnotes) {
-      const pageBox = document.createElement("div");
+    createPage(dims, pageNumber, sectionIndex, displayedPageNumber, content, pageInSection, footnoteIds = [], footnoteHeight = 0, continuation, partialFootnotes, isSectionFiller = false, pageAlreadyAdmitted = false) {
+      if (!pageAlreadyAdmitted) this.admitPageAllocation();
+      const pageBox = this.document.createElement("div");
       pageBox.className = `${this.cssPrefix}box`;
       pageBox.style.width = `${dims.pageWidth}pt`;
       pageBox.style.height = `${dims.pageHeight}pt`;
       pageBox.style.overflow = "hidden";
       pageBox.style.position = "relative";
       if (this.scale !== 1) {
-        pageBox.style.zoom = String(this.scale);
-        pageBox.style.transform = `scale(${this.scale})`;
-        pageBox.style.transformOrigin = "top left";
-        const heightReductionPt = dims.pageHeight * (1 - this.scale);
-        const widthReductionPt = dims.pageWidth * (1 - this.scale);
-        const heightReductionPx = ptToPx(heightReductionPt);
-        const widthReductionPx = ptToPx(widthReductionPt);
-        pageBox.style.marginRight = `-${widthReductionPx}px`;
-        pageBox.style.marginBottom = `${this.pageGap - heightReductionPx}px`;
+        if (this.view.CSS?.supports("zoom", "1")) {
+          pageBox.style.zoom = String(this.scale);
+        } else {
+          pageBox.style.transform = `scale(${this.scale})`;
+          pageBox.style.transformOrigin = "top left";
+          const heightReductionPt = dims.pageHeight * (1 - this.scale);
+          const widthReductionPt = dims.pageWidth * (1 - this.scale);
+          const heightReductionPx = ptToPx(heightReductionPt);
+          const widthReductionPx = ptToPx(widthReductionPt);
+          pageBox.style.marginRight = `-${widthReductionPx}px`;
+          pageBox.style.marginBottom = `${this.pageGap - heightReductionPx}px`;
+        }
       }
       pageBox.style.willChange = "transform";
       pageBox.style.contain = "layout paint";
       pageBox.dataset.pageNumber = String(pageNumber);
       pageBox.dataset.sectionIndex = String(sectionIndex);
+      pageBox.dataset.displayedPageNumber = String(displayedPageNumber);
+      if (isSectionFiller) pageBox.dataset.sectionFiller = "true";
       pageBox.dataset.pageInSection = String(pageInSection);
-      const bands = this.getPageBands(dims, sectionIndex, pageInSection, pageNumber);
-      const headerSource = this.selectHeader(sectionIndex, pageInSection, pageNumber);
+      const bands = this.getPageBands(dims, sectionIndex, pageInSection, displayedPageNumber);
+      const headerSource = isSectionFiller ? void 0 : this.selectHeader(sectionIndex, pageInSection, displayedPageNumber);
       if (headerSource) {
-        const headerDiv = document.createElement("div");
+        const headerDiv = this.document.createElement("div");
         headerDiv.className = `${this.cssPrefix}header`;
         headerDiv.style.position = "absolute";
         headerDiv.style.top = `${bands.headerTop}pt`;
@@ -3100,7 +5154,7 @@ var Docxodus = (() => {
       }
       const contentAreaTop = bands.bodyTop;
       const contentAreaHeight = bands.bodyHeight;
-      const contentArea = document.createElement("div");
+      const contentArea = this.document.createElement("div");
       contentArea.className = `${this.cssPrefix}content`;
       contentArea.style.position = "absolute";
       contentArea.style.top = `${contentAreaTop}pt`;
@@ -3113,12 +5167,46 @@ var Docxodus = (() => {
       }
       pageBox.appendChild(contentArea);
       const hasContinuation = continuation && continuation.remainingElements.length > 0;
-      if (footnoteIds.length > 0 || hasContinuation) {
+      if (!isSectionFiller && (footnoteIds.length > 0 || hasContinuation)) {
         this.addPageFootnotes(pageBox, footnoteIds, dims, bands, footnoteHeight, continuation, partialFootnotes);
       }
-      const footerSource = this.selectFooter(sectionIndex, pageInSection, pageNumber);
+      const pageCommentIds = [];
+      for (const marker of Array.from(
+        pageBox.querySelectorAll("[data-comment-id]")
+      )) {
+        if (marker.closest(`.${this.cssPrefix}comment-margin`)) continue;
+        const id = marker.dataset.commentId;
+        if (id && this.commentMarginRegistry.has(id) && !pageCommentIds.includes(id)) {
+          pageCommentIds.push(id);
+        }
+      }
+      if (pageCommentIds.length > 0) {
+        const marginColumn = this.document.createElement("aside");
+        marginColumn.className = `${this.cssPrefix}comment-margin`;
+        marginColumn.style.position = "absolute";
+        marginColumn.style.top = `${contentAreaTop}pt`;
+        marginColumn.style.left = `${dims.marginLeft + dims.contentWidth + 3}pt`;
+        marginColumn.style.width = `${Math.max(12, dims.marginRight - 6)}pt`;
+        marginColumn.style.maxHeight = `${contentAreaHeight}pt`;
+        marginColumn.style.overflow = "hidden";
+        marginColumn.style.boxSizing = "border-box";
+        const placedThreadRoots = /* @__PURE__ */ new Set();
+        for (const id of pageCommentIds) {
+          const source = this.commentMarginRegistry.get(id);
+          if (source) {
+            const rootId = source.dataset.commentId ?? id;
+            if (placedThreadRoots.has(rootId)) continue;
+            placedThreadRoots.add(rootId);
+            const clone = source.cloneNode(true);
+            this.makeClonedMarginCommentInert(clone);
+            marginColumn.appendChild(clone);
+          }
+        }
+        pageBox.appendChild(marginColumn);
+      }
+      const footerSource = isSectionFiller ? void 0 : this.selectFooter(sectionIndex, pageInSection, displayedPageNumber);
       if (footerSource) {
-        const footerDiv = document.createElement("div");
+        const footerDiv = this.document.createElement("div");
         footerDiv.className = `${this.cssPrefix}footer`;
         footerDiv.style.position = "absolute";
         footerDiv.style.top = "auto";
@@ -3138,8 +5226,8 @@ var Docxodus = (() => {
         }
         pageBox.appendChild(footerDiv);
       }
-      if (this.showPageNumbers) {
-        const pageNum = document.createElement("div");
+      if (this.showPageNumbers && !isSectionFiller) {
+        const pageNum = this.document.createElement("div");
         pageNum.className = `${this.cssPrefix}number`;
         pageNum.textContent = String(pageNumber);
         pageBox.appendChild(pageNum);
@@ -3162,7 +5250,8 @@ var Docxodus = (() => {
     }
   };
   function paginateHtml(html, container, options = {}) {
-    const containerEl = typeof container === "string" ? document.getElementById(container) : container;
+    const ownerDocument = typeof container === "string" ? globalThis.document : container.ownerDocument;
+    const containerEl = typeof container === "string" ? ownerDocument.getElementById(container) : container;
     if (!containerEl) {
       throw new Error("Container element not found");
     }
@@ -6464,6 +8553,13 @@ var Docxodus = (() => {
   function escapeInlineMarkdown(text) {
     return text.replace(/([\\`*_[\]])/g, "\\$1");
   }
+  function escapeLeadingBlockMarkers(md) {
+    return md.split("\n").map((line) => {
+      if (/^[#>|]/.test(line) || /^[-+] /.test(line)) return "\\" + line;
+      if (/^\d+\. /.test(line)) return line.replace(".", "\\.");
+      return line;
+    }).join("\n");
+  }
   function collectInlineSegments(node, out) {
     node.childNodes.forEach((child) => {
       if (isGeneratedChrome(child)) return;
@@ -6515,7 +8611,7 @@ var Docxodus = (() => {
         merged.push({ ...s });
       }
     }
-    return merged.map(segToMarkdown).join("").trim();
+    return escapeLeadingBlockMarkers(merged.map(segToMarkdown).join("").trim());
   }
   function isListBlock(block) {
     return !!block.querySelector(":scope > [data-list-marker]");
@@ -8550,17 +10646,19 @@ var Docxodus = (() => {
       this.refreshAfter(block, idx, false);
     }
     // ─── Table row / column editing (active block must be inside a table cell) ──────────
-    /** Run a table-structure op on the active cell (a cell-paragraph block) and re-render. */
+    /** Run a table-structure op on the active cell's canonical tc anchor and re-render. */
     tableEdit(run) {
       const block = this.activeBlock;
-      if (this.closed || !block || !block.closest("table")) return;
+      const cell = block?.closest("td, th");
+      if (this.closed || !block || !cell || !block.closest("table")) return;
       const unid = block.getAttribute("data-anchor");
       if (!unid) return;
-      let fullId = this.anchorIdOf(block);
-      if (!fullId) return;
+      const paragraphId = this.anchorIdOf(block);
+      const cellId = this.anchorIdOf(cell);
+      if (!paragraphId || !cellId) return;
       const idx = this.blockIndex(block);
-      fullId = this.syncBlock(block, fullId);
-      const res = this.parseEdit(run(fullId));
+      this.syncBlock(block, paragraphId);
+      const res = this.parseEdit(run(cellId));
       if (!res.success) return;
       this.refreshAfter(block, idx, false);
     }
@@ -8713,6 +10811,59 @@ var Docxodus = (() => {
       if (!res.success) return;
       this.reconcile(idx, false);
     }
+    /**
+     * Add a native Word comment on the current selection in the active block — or on the whole
+     * block when the selection is collapsed (a null span comments the paragraph). The definition,
+     * threading parts, and body-side range markers are written by the session's `AddComment`
+     * (issue #300); the re-render shows the marker chrome the converter already draws. The
+     * annotation type legal review runs on, finally authorable from the shipped surface
+     * (issue #580).
+     */
+    addComment(markdown = "New comment.", author = "Reviewer") {
+      const block = this.activeBlock;
+      if (this.closed || !block) return;
+      const bridge = this.exports.DocxSessionBridge;
+      if (!bridge.AddComment) return;
+      let fullId = this.anchorIdOf(block);
+      if (!fullId) return;
+      const idx = this.blockIndex(block);
+      const span = selectionSpanIn(block);
+      fullId = this.syncBlock(block, fullId);
+      const res = this.parseEdit(
+        bridge.AddComment(
+          this.handle,
+          fullId,
+          span ? JSON.stringify(span) : "",
+          author,
+          "",
+          "",
+          markdown
+        )
+      );
+      if (!res.success) return;
+      this.reconcile(idx, false);
+    }
+    /** The document's native comment threads (session truth), for review UIs — flat entries
+     *  with `parentAnchorId` linking replies and `resolved` carrying thread state. */
+    listComments() {
+      if (this.closed) return [];
+      const bridge = this.exports.DocxSessionBridge;
+      if (!bridge.ListComments) return [];
+      try {
+        return JSON.parse(bridge.ListComments(this.handle));
+      } catch {
+        return [];
+      }
+    }
+    /** Resolve or reopen a comment thread by its `cmt` anchor id (from {@link listComments}).
+     *  Resolution is thread metadata (`commentsExtended`), not body markup, so no re-render is
+     *  needed — a review UI re-reads {@link listComments} for the new state. */
+    setCommentResolved(commentAnchorId, resolved) {
+      if (this.closed) return;
+      const bridge = this.exports.DocxSessionBridge;
+      if (!bridge.SetCommentResolved) return;
+      this.parseEdit(bridge.SetCommentResolved(this.handle, commentAnchorId, resolved));
+    }
     applyParagraphFormat(op) {
       const block = this.activeBlock;
       if (this.closed || !block) return;
@@ -9240,8 +11391,8 @@ var Docxodus = (() => {
         const backref = document.createElement("a");
         backref.setAttribute("class", `${prefix}-backref`);
         backref.setAttribute("contenteditable", "false");
-        backref.textContent = "\u21A9";
-        last.append(" ", backref);
+        backref.textContent = " \u21A9";
+        last.append(backref);
       }
       li.querySelectorAll("[data-anchor]").forEach((b) => this.wireBlock(b));
       return li;
@@ -9798,6 +11949,25 @@ var Docxodus = (() => {
   box-shadow: 0 1px 3px rgba(15, 23, 42, .08), 0 12px 24px rgba(15, 23, 42, .06);
 }
 
+/* \u2500\u2500 Review: comment threads \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+.dxr-threads {
+  display: flex; flex-direction: column; gap: 4px;
+  max-height: 92px; overflow-y: auto; min-width: 260px; padding-right: 2px;
+}
+.dxr-thread {
+  display: flex; align-items: center; gap: 6px;
+  font-size: 11px; line-height: 1.3; padding: 3px 6px;
+  border: 1px solid var(--dxr-rule); border-radius: 4px; background: var(--dxr-chrome-sunk);
+}
+.dxr-thread[data-resolved] { opacity: 0.55; }
+.dxr-thread[data-reply] { margin-left: 14px; }
+.dxr-thread .dxr-tauthor { font-weight: 600; white-space: nowrap; }
+.dxr-thread .dxr-ttext {
+  flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; max-width: 220px;
+}
+.dxr-thread button { flex: none; }
+.dxr-group.dxr-grow { flex: 1; min-width: 0; }
+
 /* \u2500\u2500 Table size picker \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
 .dxr-pop {
   display: none;
@@ -10116,6 +12286,7 @@ var Docxodus = (() => {
     <button type="button" class="dxr-tab" role="tab" data-tab="home" aria-selected="true">Home</button>
     <button type="button" class="dxr-tab" role="tab" data-tab="insert" aria-selected="false">Insert</button>
     <button type="button" class="dxr-tab" role="tab" data-tab="layout" aria-selected="false">Layout</button>
+    <button type="button" class="dxr-tab" role="tab" data-tab="review" aria-selected="false">Review</button>
     <button type="button" class="dxr-tab" role="tab" data-tab="table" data-contextual aria-selected="false" hidden>Table</button>
   </div>
 
@@ -10281,6 +12452,31 @@ var Docxodus = (() => {
       </div>
     </div>
 
+    <!-- REVIEW \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+         Comment authoring over the session's native comment family (issue #580):
+         the button comments the selection (the whole block when collapsed), and
+         the thread list is live session truth with resolve/reopen per thread. -->
+    <div class="dxr-panel" data-panel="review">
+      <div class="dxr-group">
+        <span class="dxr-glabel">Comments</span>
+        <div class="dxr-row">
+          <input data-dxr="commenttext" type="text" placeholder="Comment text&#8230;"
+                 title="The comment body; markdown is honored" />
+          <button type="button" data-dxr="comment"
+                  title="Comment on the selection, or on the whole block when nothing is selected">&#128172; Comment</button>
+        </div>
+        <div class="dxr-row">
+          <span class="dxr-note">Comments the selected text; the whole block when the caret is collapsed.</span>
+        </div>
+      </div>
+      <div class="dxr-group dxr-grow">
+        <span class="dxr-glabel">Threads</span>
+        <div class="dxr-threads" data-dxr="threads" aria-live="polite">
+          <span class="dxr-note">No comments yet.</span>
+        </div>
+      </div>
+    </div>
+
     <!-- TABLE (contextual) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
          Row/column editing lives here rather than in a floating toolbar: a docked
          contextual tab cannot overlap the cell you are editing. -->
@@ -10788,6 +12984,18 @@ var Docxodus = (() => {
         if (this.live && style.value) this.run("style", () => this.live.setParagraphStyle(style.value));
         style.value = "";
       });
+      const commentButton = this.control("comment");
+      if (commentButton) {
+        this.keepSelection(commentButton);
+        commentButton.addEventListener("click", () => {
+          if (!this.live) return;
+          const input = this.control("commenttext");
+          const text = input?.value.trim() || "New comment.";
+          this.run("comment", () => this.live.addComment(text, this.options.revisionAuthor ?? "Reviewer"));
+          if (input) input.value = "";
+          this.renderThreads();
+        });
+      }
       this.wireFileActions();
       this.wireLayout();
       this.wirePicker();
@@ -10910,6 +13118,52 @@ var Docxodus = (() => {
         else panel.removeAttribute("data-active");
       }
       if (name === "layout") this.syncPageNumbering();
+      if (name === "review") this.renderThreads();
+    }
+    /** Re-render the Review tab's thread list from session truth ({@link DocxEditor.listComments}):
+     *  one row per comment, replies indented under their thread root, resolve/reopen per root. */
+    renderThreads() {
+      const host = this.control("threads");
+      if (!host || !this.live) return;
+      const doc = this.element.ownerDocument ?? document;
+      host.textContent = "";
+      const comments = this.live.listComments();
+      if (comments.length === 0) {
+        const empty = doc.createElement("span");
+        empty.className = "dxr-note";
+        empty.textContent = "No comments yet.";
+        host.appendChild(empty);
+        return;
+      }
+      for (const entry of comments) {
+        const row = doc.createElement("div");
+        row.className = "dxr-thread";
+        row.setAttribute("data-thread", entry.anchorId);
+        if (entry.resolved) row.setAttribute("data-resolved", "");
+        if (entry.parentAnchorId) row.setAttribute("data-reply", "");
+        const author = doc.createElement("span");
+        author.className = "dxr-tauthor";
+        author.textContent = entry.author || "\u2014";
+        row.appendChild(author);
+        const text = doc.createElement("span");
+        text.className = "dxr-ttext";
+        text.textContent = entry.text;
+        text.title = entry.text;
+        row.appendChild(text);
+        if (!entry.parentAnchorId) {
+          const toggle = doc.createElement("button");
+          toggle.type = "button";
+          toggle.textContent = entry.resolved ? "Reopen" : "Resolve";
+          toggle.title = entry.resolved ? "Reopen this comment thread" : "Mark this comment thread resolved";
+          toggle.addEventListener("click", () => {
+            if (!this.live) return;
+            this.run(entry.resolved ? "reopen comment" : "resolve comment", () => this.live.setCommentResolved(entry.anchorId, !entry.resolved));
+            this.renderThreads();
+          });
+          row.appendChild(toggle);
+        }
+        host.appendChild(row);
+      }
     }
     // ── selection-driven state ──────────────────────────────────────────────────
     selectionElement() {
@@ -11212,6 +13466,55 @@ var Docxodus = (() => {
     const buffer = await input.arrayBuffer();
     return new Uint8Array(buffer);
   }
+  async function generatePackageManifest(document2) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document2);
+    await yieldToMain();
+    return JSON.parse(
+      exports.DocumentConverter.GeneratePackageManifest(bytes)
+    );
+  }
+  async function verifyDeliverable(document2, baseline) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document2);
+    const baselineBytes = baseline === void 0 ? void 0 : await toBytes(baseline);
+    await yieldToMain();
+    return JSON.parse(
+      baselineBytes === void 0 ? exports.DocumentConverter.VerifyDeliverable(bytes) : exports.DocumentConverter.VerifyDeliverableWithBaseline(
+        baselineBytes,
+        bytes
+      )
+    );
+  }
+  async function verifyDeliveryReceipt(receiptJson, artifacts) {
+    const exports = ensureInitialized();
+    const artifactsJson = artifacts === void 0 ? "" : JSON.stringify(
+      Object.fromEntries(
+        Object.entries(artifacts).map(([artifactId, bytes]) => [
+          artifactId,
+          bytesToBase64(bytes)
+        ])
+      )
+    );
+    await yieldToMain();
+    return JSON.parse(
+      exports.DocumentConverter.VerifyDeliveryReceipt(receiptJson, artifactsJson)
+    );
+  }
+  async function proveRedlineReversibility(baseline, intendedFinal, redline) {
+    const exports = ensureInitialized();
+    const baselineBytes = await toBytes(baseline);
+    const intendedFinalBytes = await toBytes(intendedFinal);
+    const redlineBytes = await toBytes(redline);
+    await yieldToMain();
+    return JSON.parse(
+      exports.DocumentConverter.ProveRedlineReversibility(
+        baselineBytes,
+        intendedFinalBytes,
+        redlineBytes
+      )
+    );
+  }
   async function renderBlockHtml(document2, anchorId, options) {
     const exports = ensureInitialized();
     const bytes = await toBytes(document2);
@@ -11472,21 +13775,30 @@ var Docxodus = (() => {
       throw new Error(`Failed to get DocxDiff revisions: ${error.error}`);
     }
     const parsed = JSON.parse(result);
-    return (parsed.revisions || parsed.Revisions || []).map((r) => ({
-      revisionType: r.revisionType ?? r.RevisionType,
-      text: r.text ?? r.Text,
-      author: r.author ?? r.Author,
-      date: r.date ?? r.Date,
-      moveGroupId: r.moveGroupId ?? r.MoveGroupId ?? void 0,
-      isMoveSource: r.isMoveSource ?? r.IsMoveSource ?? void 0,
-      formatChange: r.formatChange || r.FormatChange ? {
-        oldProperties: r.formatChange?.oldProperties ?? r.FormatChange?.OldProperties,
-        newProperties: r.formatChange?.newProperties ?? r.FormatChange?.NewProperties,
-        changedPropertyNames: r.formatChange?.changedPropertyNames ?? r.FormatChange?.ChangedPropertyNames
-      } : void 0,
-      leftAnchor: r.leftAnchor ?? r.LeftAnchor ?? void 0,
-      rightAnchor: r.rightAnchor ?? r.RightAnchor ?? void 0
-    }));
+    return (parsed.revisions || parsed.Revisions || []).map(mapDocxDiffRevision);
+  }
+  async function docxDiffCompareProducts(left2, right2, settings, products) {
+    const exports = ensureInitialized();
+    const leftBytes = await toBytes(left2);
+    const rightBytes = await toBytes(right2);
+    await yieldToMain();
+    const result = exports.DocxDiffBridge.CompareProductsJson(
+      leftBytes,
+      rightBytes,
+      docxDiffSettingsJson(settings),
+      products ? JSON.stringify(products) : ""
+    );
+    if (isErrorResponse(result)) {
+      const error = parseError(result);
+      throw new Error(`Failed to compare products: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return {
+      redline: typeof parsed.redlineB64 === "string" ? Uint8Array.from(atob(parsed.redlineB64), (c) => c.charCodeAt(0)) : void 0,
+      revisions: Array.isArray(parsed.revisions) ? parsed.revisions.map(mapDocxDiffRevision) : void 0,
+      editScript: parsed.editScript !== void 0 ? parsed.editScript : void 0,
+      semanticChanges: parsed.semanticChanges !== void 0 ? parsed.semanticChanges : void 0
+    };
   }
   async function docxDiffGetEditScript(left2, right2, settings) {
     const exports = ensureInitialized();
@@ -11504,6 +13816,22 @@ var Docxodus = (() => {
     }
     return result;
   }
+  async function docxDiffGetSemanticChanges(left2, right2, settings) {
+    const exports = ensureInitialized();
+    const leftBytes = await toBytes(left2);
+    const rightBytes = await toBytes(right2);
+    await yieldToMain();
+    const result = exports.DocxDiffBridge.GetSemanticChangesJson(
+      leftBytes,
+      rightBytes,
+      docxDiffSettingsJson(settings)
+    );
+    if (isErrorResponse(result)) {
+      const error = parseError(result);
+      throw new Error(`Failed to get semantic changes: ${error.error}`);
+    }
+    return JSON.parse(result);
+  }
   async function docxDiffAcceptRevisions(redline) {
     const exports = ensureInitialized();
     const bytes = await toBytes(redline);
@@ -11757,6 +14085,7 @@ var Docxodus = (() => {
     const parsed = JSON.parse(result);
     const convertElement = (el) => ({
       id: el.Id || el.id,
+      anchorId: el.AnchorId || el.anchorId,
       type: el.Type || el.type,
       textPreview: el.TextPreview || el.textPreview,
       index: el.Index ?? el.index,
@@ -11768,8 +14097,12 @@ var Docxodus = (() => {
     });
     const convertTableColumn = (col) => ({
       tableId: col.TableId || col.tableId,
+      anchorId: col.AnchorId || col.anchorId,
+      tableAnchorId: col.TableAnchorId || col.tableAnchorId,
+      isVirtual: col.IsVirtual ?? col.isVirtual ?? false,
       columnIndex: col.ColumnIndex ?? col.columnIndex,
       cellIds: col.CellIds || col.cellIds || [],
+      cellAnchorIds: col.CellAnchorIds || col.cellAnchorIds || [],
       rowCount: col.RowCount ?? col.rowCount
     });
     const root = convertElement(parsed.Root || parsed.root);
@@ -11832,7 +14165,8 @@ var Docxodus = (() => {
       hasEndnotes: parsed.HasEndnotes ?? parsed.hasEndnotes,
       hasTrackedChanges: parsed.HasTrackedChanges ?? parsed.hasTrackedChanges,
       hasComments: parsed.HasComments ?? parsed.hasComments,
-      estimatedPageCount: parsed.EstimatedPageCount ?? parsed.estimatedPageCount
+      estimatedPageCount: parsed.EstimatedPageCount ?? parsed.estimatedPageCount,
+      estimatedPageCountSource: parsed.EstimatedPageCountSource ?? parsed.estimatedPageCountSource ?? "heuristic"
     };
   }
   async function exportToOpenContract(document2) {