docxodus 9.9.0 → 10.0.0

package/dist/embed.bundle.js

@@ -362,7 +362,46 @@ function targetSearchInElement(elementId, searchText, occurrence = 1) {
 }
 
 // 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 ────────────────────────────────────────────────
@@ -378,6 +417,336 @@ var DocxSession = class {
   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
@@ -393,9 +762,9 @@ var DocxSession = class {
    *
    * @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)
     );
   }
   /**
@@ -419,11 +788,21 @@ var DocxSession = class {
     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) {
@@ -478,7 +857,7 @@ var DocxSession = class {
   }
   /**
    * 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) {
@@ -487,10 +866,26 @@ var DocxSession = class {
       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.
@@ -530,7 +925,7 @@ var DocxSession = class {
     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.
@@ -570,6 +965,19 @@ var DocxSession = class {
       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
@@ -664,6 +1072,25 @@ var DocxSession = class {
       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) {
@@ -755,6 +1182,170 @@ var DocxSession = class {
   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
@@ -775,6 +1366,22 @@ var DocxSession = class {
   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) : "";
@@ -880,6 +1487,10 @@ var DocxSession = class {
    * 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.
@@ -1056,10 +1667,16 @@ var DocxSession = class {
    *
    * @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,
@@ -1082,6 +1699,23 @@ var DocxSession = class {
     }
     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
@@ -1097,8 +1731,9 @@ var DocxSession = class {
    *
    * @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
@@ -1107,8 +1742,9 @@ var DocxSession = class {
    * 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
@@ -1116,8 +1752,9 @@ var DocxSession = class {
    * 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) ─────────────────────────
   /**
@@ -1162,15 +1799,25 @@ var DocxSession = class {
     );
   }
   /**
-   * 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 }`.
@@ -1224,6 +1871,18 @@ var DocxSession = class {
     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
@@ -1288,6 +1947,13 @@ var DocxSession = class {
     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) : "");
@@ -1339,17 +2005,41 @@ function pxToPt(px) {
 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,
@@ -1429,8 +2119,93 @@ function applyZoom(el, scale, naturalPt) {
 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.
@@ -1440,24 +2215,46 @@ var PaginationEngine = class {
    * @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.
@@ -1465,58 +2262,469 @@ var PaginationEngine = class {
    * @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) {
@@ -1560,9 +2768,8 @@ var PaginationEngine = class {
       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;
@@ -1574,17 +2781,26 @@ var PaginationEngine = class {
   /**
    * 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);
@@ -1593,6 +2809,7 @@ var PaginationEngine = class {
       const isPageBreak = child.dataset.pageBreak === "true" || child.classList.contains(`${this.cssPrefix}break`);
       blocks.push({
         element: child,
+        sectionIndex,
         heightPt,
         marginTopPt,
         marginBottomPt,
@@ -1605,6 +2822,95 @@ var PaginationEngine = class {
     }
     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;
@@ -1622,7 +2928,7 @@ var PaginationEngine = class {
     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) {
@@ -1632,17 +2938,19 @@ var PaginationEngine = class {
     };
     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;
@@ -1650,6 +2958,7 @@ var PaginationEngine = class {
       }
       blocks.push({
         element: container,
+        sectionIndex,
         heightPt: measured.heightPt,
         marginTopPt: measured.marginTopPt,
         marginBottomPt: measured.marginBottomPt,
@@ -1668,8 +2977,8 @@ var PaginationEngine = class {
    * 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";
@@ -1678,9 +2987,10 @@ var PaginationEngine = class {
     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),
@@ -1774,6 +3084,7 @@ var PaginationEngine = class {
     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);
@@ -1791,8 +3102,8 @@ var PaginationEngine = class {
   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
     );
   }
   /**
@@ -1830,10 +3141,11 @@ var PaginationEngine = class {
     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;
@@ -1847,8 +3159,10 @@ var PaginationEngine = class {
     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,
@@ -1856,7 +3170,7 @@ var PaginationEngine = class {
           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;
         }
@@ -1888,7 +3202,7 @@ var PaginationEngine = class {
       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;
       }
@@ -1903,35 +3217,198 @@ var PaginationEngine = class {
     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
@@ -1940,13 +3417,25 @@ var PaginationEngine = class {
    * 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",
@@ -1977,21 +3466,27 @@ var PaginationEngine = class {
       "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;
       }
     }
@@ -2018,58 +3513,122 @@ var PaginationEngine = class {
     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,
@@ -2077,7 +3636,7 @@ var PaginationEngine = class {
       },
       {
         ...tailMeasured,
-        element: tail,
+        element: split.tail,
         keepWithNext: false,
         keepLines: false,
         pageBreakBefore: false,
@@ -2148,7 +3707,7 @@ var PaginationEngine = class {
     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) {
@@ -2157,6 +3716,68 @@ var PaginationEngine = class {
     }
     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.
    */
@@ -2171,6 +3792,92 @@ var PaginationEngine = class {
     }
     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.
@@ -2178,140 +3885,246 @@ var PaginationEngine = class {
    * @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;
+    }
+    if (this.footnoteRegistry.size === 0 && !hasContinuation) {
       return 0;
     }
-    const measureContainer = document.createElement("div");
+    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));
+    measureContainer.style.left = "-9999px";
+    measureContainer.className = this.cssPrefix + "footnotes";
+    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.
@@ -2324,12 +4137,11 @@ var PaginationEngine = class {
     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`;
@@ -2338,35 +4150,18 @@ var PaginationEngine = class {
     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);
@@ -2377,30 +4172,26 @@ var PaginationEngine = class {
     }
     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;
@@ -2415,7 +4206,7 @@ var PaginationEngine = class {
    * 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,
@@ -2424,14 +4215,14 @@ var PaginationEngine = class {
         sectionHf?.headerEvenHeight,
         sectionHf?.headerDefaultHeight,
         pageInSection,
-        globalPageNumber
+        displayedPageNumber
       ),
       this.selectStoryHeight(
         sectionHf?.footerFirstHeight,
         sectionHf?.footerEvenHeight,
         sectionHf?.footerDefaultHeight,
         pageInSection,
-        globalPageNumber
+        displayedPageNumber
       )
     );
   }
@@ -2439,9 +4230,9 @@ var PaginationEngine = class {
    * 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;
   }
   /**
@@ -2453,7 +4244,7 @@ var PaginationEngine = class {
    * 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`;
@@ -2472,79 +4263,275 @@ var PaginationEngine = class {
    * 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;
@@ -2560,7 +4547,7 @@ var PaginationEngine = class {
           if (newChainFootnoteIds.length > 0 && this.footnoteRegistry.size > 0) {
             const totalChainFootnoteHeight = this.measureFootnotesHeight(
               [...currentFootnoteIds, ...newChainFootnoteIds],
-              dims.contentWidth,
+              blockDimensions.contentWidth,
               currentContinuation
             );
             additionalChainFootnoteHeight = Math.max(
@@ -2572,61 +4559,68 @@ var PaginationEngine = class {
             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
         );
@@ -2636,40 +4630,74 @@ var PaginationEngine = class {
           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);
@@ -2680,78 +4708,70 @@ var PaginationEngine = class {
                   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;
   }
@@ -2776,6 +4796,19 @@ var PaginationEngine = class {
       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.
    *
@@ -2801,7 +4834,7 @@ var PaginationEngine = class {
       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,
@@ -2931,36 +4964,48 @@ var PaginationEngine = class {
     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`;
@@ -2982,7 +5027,7 @@ var PaginationEngine = class {
     }
     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`;
@@ -2995,12 +5040,46 @@ var PaginationEngine = class {
     }
     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";
@@ -3020,8 +5099,8 @@ var PaginationEngine = class {
       }
       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);
@@ -3044,7 +5123,8 @@ var PaginationEngine = class {
   }
 };
 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");
   }
@@ -6346,6 +8426,13 @@ function fontWeightIsBold(w) {
 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;
@@ -6397,7 +8484,7 @@ function serializeInlineMarkdown(block) {
       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]");
@@ -8432,17 +10519,19 @@ var DocxEditor = class _DocxEditor {
     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);
   }
@@ -8595,6 +10684,59 @@ var DocxEditor = class _DocxEditor {
     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;
@@ -9122,8 +11264,8 @@ var DocxEditor = class _DocxEditor {
       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;
@@ -9680,6 +11822,25 @@ var RIBBON_CSS = `
   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;
@@ -9998,6 +12159,7 @@ var RIBBON_HTML = `
     <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>
 
@@ -10163,6 +12325,31 @@ var RIBBON_HTML = `
       </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. -->
@@ -10670,6 +12857,18 @@ var RibbonSurface = class {
       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();
@@ -10792,6 +12991,52 @@ var RibbonSurface = class {
       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() {
@@ -11093,6 +13338,55 @@ async function toBytes(input) {
   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);
@@ -11353,21 +13647,30 @@ async function docxDiffGetRevisions(left2, right2, settings) {
     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();
@@ -11385,6 +13688,22 @@ async function docxDiffGetEditScript(left2, right2, settings) {
   }
   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);
@@ -11638,6 +13957,7 @@ async function getDocumentStructure(document2) {
   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,
@@ -11649,8 +13969,12 @@ async function getDocumentStructure(document2) {
   });
   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);
@@ -11713,7 +14037,8 @@ async function getDocumentMetadata(document2) {
     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) {
@@ -12509,6 +14834,7 @@ export {
   addAnnotation,
   addAnnotationToHtml,
   addAnnotationWithTarget,
+  clearPageCitationHighlight,
   compareDocuments,
   compareDocumentsToHtml,
   compareDocumentsToHtmlWithLog,
@@ -12523,15 +14849,18 @@ export {
   createEditor,
   createExternalAnnotationSet,
   createRibbonEditor,
+  createUnavailablePageMap,
   createViewer,
   docxDiffAcceptRevisions,
   docxDiffCompare,
+  docxDiffCompareProducts,
   docxDiffConsolidate,
   docxDiffGetConflicts,
   docxDiffGetConsolidatedEditScript,
   docxDiffGetConsolidatedRevisions,
   docxDiffGetEditScript,
   docxDiffGetRevisions,
+  docxDiffGetSemanticChanges,
   docxDiffRejectRevisions,
   exportToOpenContract,
   findElementById,
@@ -12541,6 +14870,7 @@ export {
   fitScale,
   generateAnnotationCss,
   generateAnnotationVisibilityCss,
+  generatePackageManifest,
   getAnnotations,
   getDocumentMetadata,
   getDocumentStructure,
@@ -12560,10 +14890,12 @@ export {
   isMoveDestination,
   isMoveSource,
   mountRibbon,
+  navigateToPageCitation,
   openDocxSession2 as openDocxSession,
   paginateHtml,
   parseSectionDimensions,
   projectAnnotationsOntoHtml,
+  proveRedlineReversibility,
   ptToPx,
   pxToPt,
   removeAnnotation,
@@ -12583,5 +14915,7 @@ export {
   targetTableRow,
   toDocumentBytes,
   validateExternalAnnotations,
+  verifyDeliverable,
+  verifyDeliveryReceipt,
   wasmBasePath
 };