docxodus 6.2.0 → 6.4.0

package/dist/session.bundle.js

@@ -0,0 +1,607 @@
+"use strict";
+var DocxodusSession = (() => {
+  var __defProp = Object.defineProperty;
+  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+  var __getOwnPropNames = Object.getOwnPropertyNames;
+  var __hasOwnProp = Object.prototype.hasOwnProperty;
+  var __export = (target, all) => {
+    for (var name in all)
+      __defProp(target, name, { get: all[name], enumerable: true });
+  };
+  var __copyProps = (to, from, except, desc) => {
+    if (from && typeof from === "object" || typeof from === "function") {
+      for (let key of __getOwnPropNames(from))
+        if (!__hasOwnProp.call(to, key) && key !== except)
+          __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+    }
+    return to;
+  };
+  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+  // src/session.ts
+  var session_exports = {};
+  __export(session_exports, {
+    ContextBoundary: () => ContextBoundary,
+    DocxSession: () => DocxSession,
+    PlaceholderKinds: () => PlaceholderKinds,
+    openDocxSession: () => openDocxSession
+  });
+
+  // src/types.ts
+  var PlaceholderKinds = {
+    BlankFill: 1,
+    AlternativeClause: 2,
+    Instruction: 4,
+    All: 7
+  };
+  var DiffFormat = {
+    Json: 0,
+    Unified: 1,
+    SideBySide: 2
+  };
+  var ContextBoundary = {
+    Char: 0,
+    Bracket: 1,
+    Sentence: 2,
+    Comma: 3
+  };
+
+  // src/session.ts
+  var DocxSession = class {
+    /** @internal */
+    constructor(handle, wasm) {
+      // ─── Raw escape hatch ────────────────────────────────────────────────
+      this.raw = {
+        getXml: (anchorId) => this.wasm.RawGetXml(this.handle, anchorId),
+        insertXml: (anchorId, position, xml) => JSON.parse(this.wasm.RawInsertXml(this.handle, anchorId, position, xml)),
+        replaceXml: (anchorId, xml) => JSON.parse(this.wasm.RawReplaceXml(this.handle, anchorId, xml))
+      };
+      this.handle = handle;
+      this.wasm = wasm;
+    }
+    // ─── View ────────────────────────────────────────────────────────────
+    project() {
+      return JSON.parse(this.wasm.Project(this.handle));
+    }
+    /**
+     * 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
+     * whole document.
+     *
+     * - `ProjectionDepth.SelfOnly` — just the addressed block (one paragraph,
+     *   row, etc.).
+     * - `ProjectionDepth.Subtree` — the block + descendants (e.g. a table with
+     *   all its rows/cells, but no following content).
+     * - `ProjectionDepth.SubtreeAndFollowingSiblings` (default) — for headings
+     *   this returns the whole section (heading + content up to the next same-
+     *   or-higher heading); for non-headings it behaves like `Subtree`.
+     *
+     * @see docs/architecture/docx_mutation_api.md
+     */
+    projectAnchor(anchorId, depth = 2 /* SubtreeAndFollowingSiblings */) {
+      return JSON.parse(
+        this.wasm.ProjectAnchor(this.handle, anchorId, depth)
+      );
+    }
+    // ─── 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));
+    }
+    /**
+     * Delete every top-level block-level sibling between `fromAnchorId` (inclusive)
+     * and `toAnchorIdExclusive` (exclusive). Both anchors must share a direct
+     * parent and live in the same package part. Returns a single `EditResult`
+     * whose `removed` lists every anchor that was deleted.
+     *
+     * Records ONE undo snapshot — `undo()` restores the entire range.
+     *
+     * @see docs/architecture/docx_mutation_api.md#deleterange
+     */
+    deleteRange(fromAnchorId, toAnchorIdExclusive) {
+      return JSON.parse(this.wasm.DeleteRange(this.handle, fromAnchorId, toAnchorIdExclusive));
+    }
+    /**
+     * Delete a heading and everything below it up to (but not including) the next
+     * heading at the same or higher level. The heading anchor must have `kind === "h"`.
+     *
+     * If the target is the last heading in its parent, the section extends to the
+     * end of the parent (heading + everything after).
+     *
+     * @see docs/architecture/docx_mutation_api.md#deletesection
+     */
+    deleteSection(headingAnchorId) {
+      return JSON.parse(this.wasm.DeleteSection(this.handle, headingAnchorId));
+    }
+    // ─── Tier B: structural ──────────────────────────────────────────────
+    insertParagraph(anchorId, position, markdown) {
+      return JSON.parse(this.wasm.InsertParagraph(this.handle, anchorId, position, markdown));
+    }
+    splitParagraph(anchorId, characterOffset) {
+      return JSON.parse(this.wasm.SplitParagraph(this.handle, anchorId, characterOffset));
+    }
+    mergeParagraphs(firstAnchorId, secondAnchorId) {
+      return JSON.parse(this.wasm.MergeParagraphs(this.handle, firstAnchorId, secondAnchorId));
+    }
+    // ─── Tier C: formatting ──────────────────────────────────────────────
+    applyFormat(anchorId, span, op) {
+      const spanJson = span ? JSON.stringify(span) : "";
+      return JSON.parse(this.wasm.ApplyFormat(this.handle, anchorId, spanJson, JSON.stringify(op)));
+    }
+    /**
+     * Convenience: find `substring` in the anchor's flat text and apply `op` to the
+     * first occurrence. Eliminates the offset-arithmetic trap from #138 — caller passes
+     * the visible text they want formatted, the WASM-side resolves it to a CharSpan.
+     */
+    applyFormatBySubstring(anchorId, substring, op) {
+      return JSON.parse(
+        this.wasm.ApplyFormatBySubstring(this.handle, anchorId, substring, JSON.stringify(op))
+      );
+    }
+    /**
+     * Convenience: apply `op` to the exact span of a {@link TextMatch} (typically from
+     * {@link grep}). The match's `enclosingAnchor.id` + `span` address one specific
+     * occurrence even when several identical needles share the same block.
+     */
+    applyFormatToMatch(match, op) {
+      const span = { start: match.span.start, length: match.span.length };
+      return this.applyFormat(match.enclosingAnchor.id, span, op);
+    }
+    setParagraphStyle(anchorId, styleId) {
+      return JSON.parse(this.wasm.SetParagraphStyle(this.handle, anchorId, styleId));
+    }
+    setListLevel(anchorId, levelDelta) {
+      return JSON.parse(this.wasm.SetListLevel(this.handle, anchorId, levelDelta));
+    }
+    removeListMembership(anchorId) {
+      return JSON.parse(this.wasm.RemoveListMembership(this.handle, anchorId));
+    }
+    // ─── Tier D: cell content ────────────────────────────────────────────
+    replaceCellContent(cellAnchorId, markdown) {
+      return JSON.parse(this.wasm.ReplaceCellContent(this.handle, cellAnchorId, markdown));
+    }
+    // ─── Search ──────────────────────────────────────────────────────────
+    /**
+     * Searches the flat text of every paragraph/heading/list-item in scope for
+     * matches of `pattern`, returning them in document order with the run
+     * fragments each match spans. Lets callers rewrite a match in place while
+     * preserving each fragment's formatting (bold/italic/hyperlink/etc.).
+     *
+     * `pattern` is a regular expression — use plain string equivalents wrapped
+     * in `^` / `$` or pass literal text escaped via a helper.
+     *
+     * @see docs/architecture/docx_mutation_api.md#grep
+     */
+    grep(pattern, options) {
+      return JSON.parse(this.wasm.Grep(this.handle, pattern, options ? JSON.stringify(options) : ""));
+    }
+    /**
+     * Like {@link grep}, but lets a single match span adjacent block-level
+     * siblings (paragraphs/headings/list items) under the same parent. Block
+     * boundaries appear in the matched text as `\n`, so `^`/`$` with the
+     * Multiline flag anchor at boundaries and `.` won't cross unless Singleline
+     * is set.
+     *
+     * Matches never cross OOXML package parts, container boundaries (body →
+     * table cell), or non-paragraph siblings (a table between two paragraphs
+     * breaks the run). Returned superset of {@link grep}: single-block matches
+     * still appear with one slice. Filter `slices.length > 1` for cross-block only.
+     *
+     * @see docs/architecture/docx_mutation_api.md#grepcrossblock
+     */
+    grepCrossBlock(pattern, options) {
+      return JSON.parse(
+        this.wasm.GrepCrossBlock(this.handle, pattern, options ? JSON.stringify(options) : "")
+      );
+    }
+    /**
+     * Finds every literal occurrence of `find` in the anchor's flat text and
+     * replaces it with `replace`, preserving the surrounding run formatting that
+     * the match didn't touch. Returns one `EditResult` per attempted match.
+     *
+     * 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.
+     *
+     * @see docs/architecture/docx_mutation_api.md#replacetextrange
+     */
+    replaceTextRange(anchorId, find, replace, options) {
+      return JSON.parse(
+        this.wasm.ReplaceTextRange(this.handle, anchorId, find, replace, options ? JSON.stringify(options) : "")
+      );
+    }
+    /**
+     * Replaces a specific Grep match in place — addresses the exact span by
+     * `enclosingAnchor.id` + `span.{start,length}`, so identical needles in the
+     * same paragraph (the template-fill case where five `[___]` placeholders
+     * each get a different value) don't collide.
+     */
+    replaceMatch(match, replace) {
+      return JSON.parse(
+        this.wasm.ReplaceTextAtSpan(this.handle, match.enclosingAnchor.id, match.span.start, match.span.length, replace)
+      );
+    }
+    /**
+     * Helper for {@link fillPlaceholders} `coalesceWhitespaceAroundEmptyFill` path —
+     * mirrors the .NET `ReplaceMatchCoalescingNeighbors` rules. Inspects the chars
+     * immediately surrounding the match via `match.contextBefore` / `contextAfter`
+     * (so the option requires `contextChars >= 1`, the default) and expands the
+     * deletion span to absorb whitespace / leading-space-before-punctuation /
+     * matched-brackets where the patterns match. Falls back to literal-delete
+     * when no neighbor pattern applies.
+     *
+     * Note: with `boundary: ContextBoundary.Bracket`, neighbor brackets are not
+     * captured in context, so the bracket-coalesce rule won't fire on the JS side.
+     * The .NET implementation reads flat text directly and handles that case;
+     * callers who care should leave `boundary` at the default `Char`.
+     */
+    replaceMatchCoalescingNeighbors(match) {
+      const fold = (c) => {
+        if (c === "\xA0" || c === "\u202F" || c === "\u2009") return " ";
+        return c;
+      };
+      const l = fold(match.contextBefore.length > 0 ? match.contextBefore[match.contextBefore.length - 1] : void 0);
+      const r = fold(match.contextAfter.length > 0 ? match.contextAfter[0] : void 0);
+      const isSpace = (c) => c === " " || c === "	";
+      const isClauseTerm = (c) => c === "." || c === "," || c === ";" || c === ":" || c === "!" || c === "?";
+      const isOpen = (c) => c === "(" || c === "[" || c === "{";
+      const isClose = (c) => c === ")" || c === "]" || c === "}";
+      let extendLeft = 0;
+      let extendRight = 0;
+      if (isSpace(l) && isSpace(r)) {
+        extendRight = 1;
+      } else if (isSpace(l) && isClauseTerm(r)) {
+        extendLeft = 1;
+      } else if (isOpen(l) && isClose(r)) {
+        extendLeft = 1;
+        extendRight = 1;
+      }
+      if (extendLeft === 0 && extendRight === 0) {
+        return this.replaceMatch(match, "");
+      }
+      return JSON.parse(
+        this.wasm.ReplaceTextAtSpan(
+          this.handle,
+          match.enclosingAnchor.id,
+          match.span.start - extendLeft,
+          match.span.length + extendLeft + extendRight,
+          ""
+        )
+      );
+    }
+    /**
+     * Replace the bracketed portion of a `TextMatch` with `newInner`, preserving any
+     * prefix or suffix outside the brackets. Designed for `findPlaceholders` matches
+     * like `$[___]` where the regex `\$?\[…\]` captures a leading `$`:
+     * `replaceInner(match, "0.20")` yields `$0.20`, not `0.20`.
+     *
+     * Returns `MalformedMarkdown` if the match text does not contain balanced brackets.
+     */
+    replaceInner(match, newInner) {
+      return JSON.parse(this.wasm.ReplaceInner(
+        this.handle,
+        match.text,
+        match.enclosingAnchor.id,
+        match.span.start,
+        match.span.length,
+        newInner
+      ));
+    }
+    /**
+     * Picker-driven template fill. For every placeholder matching `options.kinds`,
+     * calls `picker`; if the picker returns a non-null string, the placeholder is
+     * replaced (with optional `$`-prefix preservation). Iterates until no more
+     * placeholders match (or `maxPasses` is reached, or a pass makes zero changes)
+     * — handles nested brackets that surface only after the inner ones are stripped.
+     *
+     * The TypeScript implementation mirrors the .NET `DocxSession.FillPlaceholders`
+     * exactly.
+     *
+     * The picker is invoked synchronously by this loop on the JS side (it does
+     * NOT run inside the WASM module). Async pickers are not supported: returning
+     * a `Promise` will cause a `TypeError` at runtime inside the `$`-prefix
+     * preservation branch (`Promise.startsWith is not a function`). For async
+     * data, pre-build a lookup map before calling and have the picker read from
+     * it synchronously.
+     */
+    fillPlaceholders(picker, options) {
+      const opts = options ?? {};
+      const kinds = opts.kinds ?? PlaceholderKinds.All;
+      const scope = opts.scope ?? 1;
+      const maxPasses = opts.maxPasses ?? 8;
+      const preserveDollarPrefix = opts.preserveDollarPrefix ?? true;
+      const contextChars = opts.contextChars ?? 80;
+      const boundary = opts.boundary ?? ContextBoundary.Char;
+      const coalesceEmpty = opts.coalesceWhitespaceAroundEmptyFill ?? false;
+      if (maxPasses <= 0) {
+        throw new RangeError("FillOptions.maxPasses must be > 0");
+      }
+      let filled = 0;
+      let workPasses = 0;
+      const errors = [];
+      const unfilled = [];
+      const seenSkipKeys = /* @__PURE__ */ new Set();
+      for (let pass = 1; pass <= maxPasses; pass++) {
+        const placeholders = this.findPlaceholders(kinds, scope, contextChars, boundary).sort((a, b) => {
+          const cmp = b.match.enclosingAnchor.id.localeCompare(a.match.enclosingAnchor.id);
+          if (cmp !== 0) return cmp;
+          return b.match.span.start - a.match.span.start;
+        });
+        if (placeholders.length === 0) break;
+        let passChanges = 0;
+        for (const p of placeholders) {
+          const pick = picker(p);
+          if (pick == null) {
+            const key = `${p.match.enclosingAnchor.id}:${p.match.span.start}:${p.match.span.length}`;
+            if (!seenSkipKeys.has(key)) {
+              seenSkipKeys.add(key);
+              unfilled.push(p);
+            }
+            continue;
+          }
+          let replacement = pick;
+          if (preserveDollarPrefix && p.match.text.startsWith("$") && !replacement.startsWith("$")) {
+            replacement = "$" + replacement;
+          }
+          const r = coalesceEmpty && replacement.length === 0 ? this.replaceMatchCoalescingNeighbors(p.match) : this.replaceMatch(p.match, replacement);
+          if (r.success) {
+            filled++;
+            passChanges++;
+          } else if (r.error) {
+            errors.push(r.error);
+          }
+        }
+        if (passChanges > 0) workPasses = pass;
+        if (passChanges === 0) break;
+      }
+      const stillPresent = this.findPlaceholders(kinds, scope).length;
+      return {
+        filled,
+        skipped: unfilled.length,
+        stillPresent,
+        passes: workPasses,
+        unfilled,
+        errors
+      };
+    }
+    /**
+     * Enumerate template placeholders in the document. Thin classifier over
+     * {@link grep}: distinguishes `[___]` value blanks (`blank_fill`),
+     * `[bracketed alternative clauses]` (`alternative_clause`), and
+     * `[insert X]` / `[*italic hint*]` instructions (`instruction`).
+     *
+     * Combine kinds with bitwise OR: `PlaceholderKinds.BlankFill | PlaceholderKinds.Instruction`.
+     * Default is `PlaceholderKinds.All`; default scope is body only (1).
+     *
+     * @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)
+      );
+    }
+    /**
+     * Returns a snapshot of edit-state introspection signals — placeholder counts,
+     * underscore-run leftovers, footnote/comment counts. Useful for "am I done?"
+     * verification at the end of an edit pipeline.
+     */
+    getEditSummary() {
+      return JSON.parse(this.wasm.GetEditSummary(this.handle));
+    }
+    /**
+     * Discoverability alias for {@link findPlaceholders}. Same return shape.
+     */
+    remainingPlaceholders(kinds = PlaceholderKinds.All) {
+      return JSON.parse(this.wasm.RemainingPlaceholders(this.handle, kinds));
+    }
+    getDiff(format = DiffFormat.Json) {
+      const raw = this.wasm.GetDiff(this.handle, format);
+      if (format === DiffFormat.Json) {
+        return JSON.parse(raw);
+      }
+      return raw;
+    }
+    // ─── Annotation-based anchor discovery (#132) ────────────────────────
+    /**
+     * Resolves an annotation's range to the block-level markdown anchors covering
+     * it, in document order. The bridge between Docxodus' read-side annotation API
+     * and the write-side session: an agent that wants to edit "the indemnification
+     * clause" looks the annotation up by id and gets the anchors it can hand to
+     * {@link replaceText} / {@link deleteBlock} / {@link raw}. Returns an empty
+     * list when the id is unknown or its bookmark is missing.
+     *
+     * v1 returns the enclosing block anchors — every paragraph/heading/list-item/
+     * cell/row/table whose subtree overlaps the bookmark range. Filter by
+     * `kind === "p" | "h" | "li"` when you want only text-bearing blocks.
+     *
+     * @see docs/architecture/docx_mutation_api.md#findbyannotation
+     */
+    findByAnnotation(annotationId) {
+      return JSON.parse(this.wasm.FindByAnnotation(this.handle, annotationId));
+    }
+    /**
+     * Finds every annotation whose `labelId` matches and resolves each of their
+     * ranges. The result is keyed by annotation id so callers can disambiguate
+     * when the same label is applied to multiple regions (three "WARRANTY"
+     * 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));
+    }
+    /**
+     * Resolves any bookmark in the main document part (Docxodus-managed or
+     * user-authored) to the block-level anchors covering its range, in document
+     * 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));
+    }
+    // ─── Text/kind-based anchor discovery (#171) ─────────────────────────
+    /**
+     * True when `anchorId` resolves to a live element in the current session.
+     * Cheap existence probe — use it to guard an anchor obtained from an earlier
+     * projection before handing it to a mutation (anchors can be invalidated by
+     * intervening edits; see the anchor lifecycle table in the mutation docs).
+     */
+    exists(anchorId) {
+      return this.wasm.Exists(this.handle, anchorId);
+    }
+    /**
+     * Find the first block-level anchor (in document order) whose flat text
+     * contains `needle`, or `null` when nothing matches. `options` tune case /
+     * whitespace handling and narrow the search by kind or scope. For all
+     * matches use {@link findAllByText}.
+     */
+    findByText(needle, options) {
+      return JSON.parse(
+        this.wasm.FindByText(this.handle, needle, options ? JSON.stringify(options) : "")
+      );
+    }
+    /**
+     * Like {@link findByText} but returns every matching anchor in document
+     * order (empty when nothing matches).
+     */
+    findAllByText(needle, options) {
+      return JSON.parse(
+        this.wasm.FindAllByText(this.handle, needle, options ? JSON.stringify(options) : "")
+      );
+    }
+    /**
+     * Find every block-level anchor whose flat text matches the regular
+     * expression `pattern`, in document order. `regexOptions` uses the numeric
+     * layout of .NET `RegexOptions` (e.g. `1` = IgnoreCase); `options` is the
+     * same shape as {@link findByText} (its `ignoreCase` composes with the regex
+     * flag). Defaults to `regexOptions = 0` (none).
+     */
+    findByRegex(pattern, regexOptions = 0, options) {
+      return JSON.parse(
+        this.wasm.FindByRegex(this.handle, pattern, regexOptions, options ? JSON.stringify(options) : "")
+      );
+    }
+    /**
+     * Return every anchor of the given `kind` (`"p"`, `"h"`, `"li"`, `"tbl"`,
+     * `"row"`, `"cell"`, …), in document order. 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 ?? "")
+      );
+    }
+    /**
+     * Look up a single anchor's preview info — `{ id, kind, scope, textPreview }`.
+     * Returns null when the anchor id is unknown.
+     *
+     * For iterating many anchors at once, prefer reading `textPreview` directly
+     * off the {@link MarkdownProjection.anchorIndex} entries (cheaper — no extra
+     * WASM round trip), or use {@link getAnchorInfos} for batched lookups.
+     */
+    getAnchorInfo(anchorId) {
+      const raw = this.wasm.GetAnchorInfo(this.handle, anchorId);
+      return JSON.parse(raw);
+    }
+    /**
+     * Bulk variant of {@link getAnchorInfo}: takes an array of anchor ids,
+     * returns a record where each unknown id maps to `null`.
+     */
+    getAnchorInfos(anchorIds) {
+      const raw = this.wasm.GetAnchorInfos(this.handle, JSON.stringify(anchorIds));
+      return JSON.parse(raw);
+    }
+    /**
+     * Resolve block-level metadata (style id+name, outline level, list membership,
+     * formatting probe) for an anchor. Returns null when the anchor doesn't exist.
+     */
+    getBlockMetadata(anchorId) {
+      const raw = this.wasm.GetBlockMetadata(this.handle, anchorId);
+      return JSON.parse(raw);
+    }
+    /**
+     * Bulk variant of {@link getBlockMetadata}. Unknown ids map to null;
+     * duplicates are deduped.
+     */
+    getBlockMetadatas(anchorIds) {
+      const raw = this.wasm.GetBlockMetadatas(this.handle, JSON.stringify(anchorIds));
+      return JSON.parse(raw);
+    }
+    /**
+     * Resolve the numbering facts for a list-item paragraph; returns null when
+     * the anchor has no w:numPr.
+     */
+    getListMembership(anchorId) {
+      const raw = this.wasm.GetListMembership(this.handle, anchorId);
+      return JSON.parse(raw);
+    }
+    /**
+     * Resolve page-layout info for the w:sectPr that governs an anchor.
+     * Returns null for anchors outside the body part.
+     */
+    getSectionInfo(anchorId) {
+      const raw = this.wasm.GetSectionInfo(this.handle, anchorId);
+      return JSON.parse(raw);
+    }
+    /**
+     * Enumerates every annotation persisted in the document. Lets an agent prime
+     * itself with "here are the labeled regions you can target" before committing
+     * to a specific id.
+     */
+    listAnnotations() {
+      return JSON.parse(this.wasm.ListAnnotations(this.handle));
+    }
+    // ─── Annotation write surface ────────────────────────────────────────
+    /**
+     * Annotate a range inside `anchorId`. When `span` is `null`/`undefined`
+     * the annotation wraps every inline run of the block. When
+     * `annotation.id` is `undefined`, a 16-char hex id is auto-generated and
+     * returned in `EditResult.annotationId`.
+     */
+    addAnnotation(anchorId, span, annotation) {
+      const spanJson = span ? JSON.stringify(span) : "";
+      return JSON.parse(
+        this.wasm.AddAnnotation(this.handle, anchorId, spanJson, JSON.stringify(annotation))
+      );
+    }
+    removeAnnotation(annotationId) {
+      return JSON.parse(this.wasm.SessionRemoveAnnotation(this.handle, annotationId));
+    }
+    updateAnnotation(annotationId, update) {
+      return JSON.parse(
+        this.wasm.UpdateAnnotation(this.handle, annotationId, JSON.stringify(update))
+      );
+    }
+    moveAnnotation(annotationId, newAnchorId, newSpan) {
+      const spanJson = newSpan ? JSON.stringify(newSpan) : "";
+      return JSON.parse(
+        this.wasm.MoveAnnotation(this.handle, annotationId, newAnchorId, spanJson)
+      );
+    }
+    // ─── Lifecycle ───────────────────────────────────────────────────────
+    undo() {
+      return this.wasm.Undo(this.handle);
+    }
+    redo() {
+      return this.wasm.Redo(this.handle);
+    }
+    save() {
+      return this.wasm.Save(this.handle);
+    }
+    close() {
+      this.wasm.CloseSession(this.handle);
+    }
+    // TypeScript 5.2+ disposable protocol
+    [Symbol.dispose]() {
+      this.close();
+    }
+  };
+  function openDocxSession(bytes, wasmExports, settings) {
+    const bridge = wasmExports.DocxSessionBridge;
+    const handle = bridge.OpenSession(bytes, settings ? JSON.stringify(settings) : "");
+    return new DocxSession(handle, bridge);
+  }
+  return __toCommonJS(session_exports);
+})();

package/dist/session.d.ts

@@ -1,4 +1,4 @@
-import type { AnchorInfo, AnchorTargetRef, AnnotationUpdate, BlockMetadata, BulkEditResult, CharSpan, CrossBlockMatch, DiffEntry, DocumentAnnotation, DocxodusWasmExports, DocxSessionProjection, DocxSessionSettings, EditResult, EditSummary, FillOptions, FormatOp, GrepOptions, ListMembership, ReplaceOptions, SectionInfo, TemplatePlaceholder, TextMatch } from "./types.js";
+import type { AnchorInfo, AnchorTargetRef, AnnotationUpdate, BlockMetadata, BulkEditResult, CharSpan, CrossBlockMatch, DiffEntry, DocumentAnnotation, DocxodusWasmExports, DocxSessionProjection, DocxSessionSettings, EditResult, EditSummary, FillOptions, FindOptions, FormatOp, GrepOptions, ListMembership, ReplaceOptions, SectionInfo, TemplatePlaceholder, TextMatch } from "./types.js";
 import { DiffFormat, ProjectionDepth } from "./types.js";
 /**
  * Stateful in-memory DOCX editing session keyed by markdown-projection anchor ids.
@@ -235,6 +235,40 @@ export declare class DocxSession {
      * names that didn't come from the annotation system.
      */
     findByBookmark(bookmarkName: string): AnchorTargetRef[];
+    /**
+     * True when `anchorId` resolves to a live element in the current session.
+     * Cheap existence probe — use it to guard an anchor obtained from an earlier
+     * projection before handing it to a mutation (anchors can be invalidated by
+     * intervening edits; see the anchor lifecycle table in the mutation docs).
+     */
+    exists(anchorId: string): boolean;
+    /**
+     * Find the first block-level anchor (in document order) whose flat text
+     * contains `needle`, or `null` when nothing matches. `options` tune case /
+     * whitespace handling and narrow the search by kind or scope. For all
+     * matches use {@link findAllByText}.
+     */
+    findByText(needle: string, options?: FindOptions): AnchorTargetRef | null;
+    /**
+     * Like {@link findByText} but returns every matching anchor in document
+     * order (empty when nothing matches).
+     */
+    findAllByText(needle: string, options?: FindOptions): AnchorTargetRef[];
+    /**
+     * Find every block-level anchor whose flat text matches the regular
+     * expression `pattern`, in document order. `regexOptions` uses the numeric
+     * layout of .NET `RegexOptions` (e.g. `1` = IgnoreCase); `options` is the
+     * same shape as {@link findByText} (its `ignoreCase` composes with the regex
+     * flag). Defaults to `regexOptions = 0` (none).
+     */
+    findByRegex(pattern: string, regexOptions?: number, options?: FindOptions): AnchorTargetRef[];
+    /**
+     * Return every anchor of the given `kind` (`"p"`, `"h"`, `"li"`, `"tbl"`,
+     * `"row"`, `"cell"`, …), in document order. 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: string, scope?: string): AnchorTargetRef[];
     /**
      * Look up a single anchor's preview info — `{ id, kind, scope, textPreview }`.
      * Returns null when the anchor id is unknown.
@@ -297,6 +331,6 @@ export declare class DocxSession {
  * {@link DocxSession.close} (or it is disposed).
  */
 export declare function openDocxSession(bytes: Uint8Array, wasmExports: DocxodusWasmExports, settings?: DocxSessionSettings): DocxSession;
-export type { AnchorInfo, AnchorRef, AnchorTargetRef, BlockSlice, CharSpan, CrossBlockMatch, DocumentAnnotation, DocxSessionProjection, DocxSessionSettings, EditError, EditErrorCode, EditResult, FormatOp, GrepOptions, MarkdownPatch, PlaceholderKind, ReplaceOptions, RunFormatting, RunFragment, TemplatePlaceholder, TextMatch } from "./types.js";
+export type { AnchorInfo, AnchorRef, AnchorTargetRef, BlockSlice, CharSpan, CrossBlockMatch, DocumentAnnotation, DocxSessionProjection, DocxSessionSettings, EditError, EditErrorCode, EditResult, FindOptions, FormatOp, GrepOptions, MarkdownPatch, PlaceholderKind, ReplaceOptions, RunFormatting, RunFragment, TemplatePlaceholder, TextMatch } from "./types.js";
 export { ContextBoundary, PlaceholderKinds } from "./types.js";
 //# sourceMappingURL=session.d.ts.map