docxodus 9.9.0 → 11.0.0

package/dist/session.js

@@ -1,6 +1,46 @@
 // Copyright (c) Microsoft. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
-import { ContextBoundary, DiffFormat, PlaceholderKinds, ProjectionDepth } from "./types.js";
+import { ContextBoundary, DiffFormat, PlaceholderKinds, ProjectionDepth, ProjectionScopes } from "./types.js";
+function mutationBatchChangeSet(before, after, key) {
+    const beforeGroups = new Map();
+    const afterGroups = 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 === undefined)
+                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]),
+    };
+}
 /**
  * Stateful in-memory DOCX editing session keyed by markdown-projection anchor ids.
  * Mirror of the .NET `DocxSession` surface. See
@@ -26,6 +66,312 @@ export class DocxSession {
     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 !== undefined && 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 !== undefined && comment.date !== null)) {
+                    warnings.push("Comment date attributes may be generated from the execution clock; supply dates explicitly when byte-identical replay is required.");
+                }
+                // Same predicate as the .NET receipt (`annotation.Created.HasValue`): the warning is
+                // about an execution CLOCK, so an annotation added with no created timestamp is
+                // deterministic and must not raise it on one surface and not the other.
+                if (annotationChanges.added
+                    .some(annotation => annotation.created !== undefined && 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.");
+                }
+                // null, never "": an absent hash must not compare equal to another absent hash, or a
+                // naive `preview.packageHash === applied.packageHash` replay assertion passes vacuously.
+                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")];
+                }
+                // An empty list is a successful no-op step, matching the core contract.
+                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 !== undefined);
+            if (failedPreflight >= 0) {
+                const source = steps[failedPreflight];
+                const failed = {
+                    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: [failed], failure: failureOf(failed, true) });
+            }
+            const transaction = this.wasm.BeginTransaction(this.handle);
+            const completed = [];
+            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,
+                    };
+                    completed.push(step);
+                    if (!step.success) {
+                        this.wasm.RollbackTransaction(transaction);
+                        const rolledBack = completed.map(value => ({ ...value, rolledBack: true }));
+                        const failed = rolledBack[rolledBack.length - 1];
+                        return complete({ mode, status: "failed", success: false, rolledBack: true,
+                            steps: rolledBack, failure: failureOf(failed, true) });
+                    }
+                }
+                this.wasm.CommitTransaction(transaction);
+                return complete({ mode, status: "ok", success: true, rolledBack: false, steps: completed });
+            }
+            catch (error) {
+                try {
+                    this.wasm.RollbackTransaction(transaction);
+                }
+                catch { /* preserve the original */ }
+                throw error;
+            }
+        }
+        // Preserve sequential best-effort semantics: a later preflight can observe state created by
+        // an earlier successful step, so run it immediately before that step rather than up front.
+        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 === undefined,
+            rolledBack: false,
+            steps: completed,
+            failure: failed ? failureOf(failed, false) : undefined,
+        });
+    }
+    /**
+     * 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) : undefined,
+            })), mode);
+            const warnings = [...result.warnings];
+            let html = null;
+            // A rendered document always starts with '<'; a leading '{' is the bridge's error object.
+            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;
+            };
+            // Preview HTML MUST come from the façade's preview profile (DocxSessionOps.RenderPreview*),
+            // not the editor's authoring profile: the editor render hides comments, annotations and
+            // headers/footers, so routing a preview through it would show this surface a materially
+            // different document than the stdio/Python/MCP surfaces show for the identical batch.
+            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
@@ -41,8 +387,10 @@ export class DocxSession {
      *
      * @see docs/architecture/docx_mutation_api.md
      */
-    projectAnchor(anchorId, depth = ProjectionDepth.SubtreeAndFollowingSiblings) {
-        return JSON.parse(this.wasm.ProjectAnchor(this.handle, anchorId, depth));
+    projectAnchor(anchorId, depth = ProjectionDepth.SubtreeAndFollowingSiblings, citation) {
+        return JSON.parse(citation
+            ? this.wasm.ProjectAnchorWithCitations(this.handle, anchorId, depth, JSON.stringify(citation))
+            : this.wasm.ProjectAnchor(this.handle, anchorId, depth));
     }
     /**
      * Render a single block to faithful HTML from the live session — the editor's
@@ -61,11 +409,17 @@ export class DocxSession {
         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) {
@@ -116,17 +470,29 @@ export class DocxSession {
     }
     /**
      * 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) {
         const optionsJson = options ? JSON.stringify(options) : "";
         return JSON.parse(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.
@@ -164,7 +530,7 @@ export class DocxSession {
         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.
@@ -196,6 +562,10 @@ export class DocxSession {
     setRepeatHeaderRow(cellAnchorId, repeat) {
         return JSON.parse(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
@@ -242,6 +612,37 @@ export class DocxSession {
     setPageNumbering(anchorId, op) {
         return JSON.parse(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
@@ -284,6 +685,17 @@ export class DocxSession {
     insertFootnote(anchorId, characterOffset, markdown) {
         return JSON.parse(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) {
@@ -343,6 +755,87 @@ export class DocxSession {
     listComments() {
         return JSON.parse(this.wasm.ListComments(this.handle));
     }
+    listHyperlinks(scopes = ProjectionScopes.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 = ProjectionScopes.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 = ProjectionScopes.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 = ProjectionScopes.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
@@ -363,6 +856,22 @@ export class DocxSession {
     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) : "";
@@ -462,6 +971,10 @@ export class DocxSession {
      * 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.
@@ -635,8 +1148,11 @@ export class DocxSession {
      *
      * @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,
@@ -659,6 +1175,21 @@ export class DocxSession {
         }
         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
@@ -674,8 +1205,11 @@ export class DocxSession {
      *
      * @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
@@ -684,8 +1218,11 @@ export class DocxSession {
      * 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
@@ -693,8 +1230,11 @@ export class DocxSession {
      * 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) ─────────────────────────
     /**
@@ -733,13 +1273,22 @@ export class DocxSession {
         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
+     * 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 }`.
@@ -793,6 +1342,18 @@ export class DocxSession {
         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
@@ -851,6 +1412,13 @@ export class DocxSession {
         this.close();
     }
 }
+function imageBytesToBase64(bytes) {
+    let binary = "";
+    for (let offset = 0; offset < bytes.length; offset += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
+    }
+    return globalThis.btoa(binary);
+}
 /**
  * Opens a new {@link DocxSession} over the supplied DOCX bytes.
  * The returned session holds its document in WASM memory until you call