docxodus 9.9.0 → 11.0.0

package/dist/session.bundle.js

@@ -47,7 +47,46 @@ var DocxodusSession = (() => {
   };
 
   // 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 ────────────────────────────────────────────────
@@ -63,6 +102,336 @@ var DocxodusSession = (() => {
     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
@@ -78,9 +447,9 @@ var DocxodusSession = (() => {
      *
      * @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)
       );
     }
     /**
@@ -104,11 +473,21 @@ var DocxodusSession = (() => {
       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) {
@@ -163,7 +542,7 @@ var DocxodusSession = (() => {
     }
     /**
      * 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) {
@@ -172,10 +551,26 @@ var DocxodusSession = (() => {
         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.
@@ -215,7 +610,7 @@ var DocxodusSession = (() => {
       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.
@@ -255,6 +650,19 @@ var DocxodusSession = (() => {
         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
@@ -305,6 +713,58 @@ var DocxodusSession = (() => {
         this.wasm.SetPageNumbering(this.handle, anchorId, JSON.stringify(op))
       );
     }
+    /**
+     * Insert a **table of contents** before or after `anchorId` (issue #607). The field is written
+     * dirty and the document asks for a field update on open, so Word paginates and fills the table
+     * itself — nothing here ships a cached result that is stale the moment anything above it moves.
+     *
+     * The table is wrapped in the `w:sdt` content control Word puts around one, which is what gives
+     * it the *Update Table* control in Word's UI. Word's `TOCHeading` and `TOC1` styles are
+     * find-or-created; a document that already defines them keeps its own.
+     *
+     * Body anchors only, and refused under tracked-change recording: a generated table is regenerated
+     * wholesale on every field update, so there is no reversible way to redline it.
+     */
+    insertTableOfContents(anchorId, pos = "before", options) {
+      return JSON.parse(
+        this.wasm.InsertTableOfContents(
+          this.handle,
+          anchorId,
+          pos,
+          options ? JSON.stringify(options) : ""
+        )
+      );
+    }
+    /**
+     * Insert a **table of figures** — the captions carrying `options.captionLabel` and their page
+     * numbers. Same field mechanics as {@link insertTableOfContents}; Word writes this one as a bare
+     * paragraph rather than inside a content control, so this does too.
+     */
+    insertTableOfFigures(anchorId, pos = "before", options) {
+      return JSON.parse(
+        this.wasm.InsertTableOfFigures(
+          this.handle,
+          anchorId,
+          pos,
+          options ? JSON.stringify(options) : ""
+        )
+      );
+    }
+    /**
+     * Insert a **table of authorities** — the cases, statutes or other authorities marked in the
+     * document, grouped by `options.category`. The table lists entries the document has MARKED with
+     * `TA` fields; a document with no marked citations produces a table that is correct and empty.
+     */
+    insertTableOfAuthorities(anchorId, pos = "before", options) {
+      return JSON.parse(
+        this.wasm.InsertTableOfAuthorities(
+          this.handle,
+          anchorId,
+          pos,
+          options ? JSON.stringify(options) : ""
+        )
+      );
+    }
     /**
      * Remove the section's page-numbering start/format: it reverts to continuing the previous
      * section's numbering in Word's default `1, 2, 3`. Chapter-numbering attributes
@@ -349,6 +809,25 @@ var DocxodusSession = (() => {
         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) {
@@ -440,6 +919,170 @@ var DocxodusSession = (() => {
     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
@@ -460,6 +1103,22 @@ var DocxodusSession = (() => {
     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) : "";
@@ -565,6 +1224,10 @@ var DocxodusSession = (() => {
      * 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.
@@ -741,10 +1404,16 @@ var DocxodusSession = (() => {
      *
      * @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,
@@ -767,6 +1436,23 @@ var DocxodusSession = (() => {
       }
       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
@@ -782,8 +1468,9 @@ var DocxodusSession = (() => {
      *
      * @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
@@ -792,8 +1479,9 @@ var DocxodusSession = (() => {
      * 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
@@ -801,8 +1489,9 @@ var DocxodusSession = (() => {
      * 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) ─────────────────────────
     /**
@@ -847,15 +1536,25 @@ var DocxodusSession = (() => {
       );
     }
     /**
-     * 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 }`.
@@ -909,6 +1608,18 @@ var DocxodusSession = (() => {
       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
@@ -973,6 +1684,13 @@ var DocxodusSession = (() => {
       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, wasmExports, settings) {
     const bridge = wasmExports.DocxSessionBridge;
     const handle = bridge.OpenSession(bytes, settings ? JSON.stringify(settings) : "");