@docx-editor.dev/core 2.30.0 → 2.32.0

package/dist/{tree-session-contract-CwnTEVLF.d.ts → tree-session-contract-D1awo_dA.d.ts}

@@ -1,11 +1,10 @@
-import { S as StoryScope, g as SelectionMark, h as TransactOptions, b as StoryTargetRejection, e as TreeModelChange, H as HeaderFooterParts, a as HeaderFooterSectionResolution, I as InsertImageInput, i as ImageIntentResult, R as ReplaceImageOptions, A as ApplyImagePropertiesInput, j as FragmentPasteInput, k as FragmentPasteResult } from './tree-package-store-DKhdEVym.js';
-import { ag as TreeDocOp, O as OoxmlPart, N as OoxmlNode, Q as OoxmlPackage, ah as OoxmlElement, a as ReviewItem, ax as RevisionAttributionInput } from './types-barrel-CA0xB8kH.js';
-import { S as SupportedImageMime, c as ImageDecodePort } from './image-resources-Bipz8toD.js';
-import { D as DocumentTrackingSettings, I as InsertCustomNodeWrite, C as CustomNodeWriteResult, a as CustomNodeSweepOutcome, E as EmbeddedFont, B as BookmarkIndex, L as ListKind } from './custom-node-writes-0v0Kgw1T.js';
-import { H as HeadlessDocumentView, D as DocumentProperties } from './headless-document-view-DZQN8Bnx.js';
+import { S as StoryScope, g as SelectionMark, h as TransactOptions, d as HistoryGroup, a as StoryTargetRejection, e as TreeModelChange, H as HeaderFooterParts, b as HeaderFooterSectionResolution, I as InsertImageInput, i as ImageIntentResult, R as ReplaceImageOptions, A as ApplyImagePropertiesInput, j as FragmentPasteInput, k as FragmentPasteResult } from './tree-package-store-CRHvMyNj.js';
+import { au as TreeDocOp, O as OoxmlPart, a4 as OoxmlNode, a5 as OoxmlPackage, av as OoxmlElement, a as ReviewItem, an as SupportedImageMime, ad as ImageDecodePort, aF as RevisionAttributionInput } from './tree-op-types-C_S2niXW.js';
+import { D as DocumentTrackingSettings, I as InsertCustomNodeWrite, C as CustomNodeWriteResult, a as CustomNodeSweepOutcome, E as EmbeddedFont, B as BookmarkIndex, L as ListKind } from './custom-node-writes-CLJKGD9t.js';
+import { H as HeadlessDocumentView, D as DocumentProperties } from './headless-document-view-Bcz9_Qva.js';
 import { Node } from 'prosemirror-model';
 import { CollaborationDocumentPort } from './collaboration/replication.js';
-import { V as ViewScope } from './editor-scope-7o9xweiJ.js';
+import { V as ViewScope } from './editor-scope-B3L-1ALc.js';
 
 /**
  * Why an edited projection could not be mapped back into tree ops.
@@ -259,7 +258,11 @@ interface TreeApplyResult {
     readonly reason?: TreeBindingRejection | StoryTargetRejection | string;
 }
 /** Optional collaboration attribution and history grouping for a direct tree-op transaction. */
-type TreeApplyOptions = Pick<TransactOptions, 'origin' | 'actorId' | 'operationId' | 'recordsHistory' | 'historyGroup'> & {
+type TreeApplyOptions = Pick<TransactOptions, 'origin' | 'actorId' | 'operationId' | 'recordsHistory'> & {
+    /** The store token of the commit's history group, as `commitReviewOps` hands it over. */
+    readonly historyToken?: HistoryGroup;
+    /** @deprecated Use `historyToken`, the same store token under its one name. */
+    readonly historyGroup?: HistoryGroup;
     /** Package resources committed in the same transaction as the tree operations. */
     readonly packageEdits?: readonly ((pkg: OoxmlPackage) => OoxmlPackage)[];
     /** Canonical operations on related package parts, committed in the same undo unit. */
@@ -268,6 +271,11 @@ type TreeApplyOptions = Pick<TransactOptions, 'origin' | 'actorId' | 'operationI
         readonly ops: readonly TreeDocOp[];
     }[];
 };
+/** History grouping for a comment or custom-node write: frames of one group share one undo step. */
+interface PackageWriteOptions {
+    /** The store token of the commit's history group, as `commitReviewOps` hands it over. */
+    readonly historyToken?: HistoryGroup;
+}
 /**
  * One open document: the canonical tree, and the only write path into it.
  *
@@ -359,6 +367,11 @@ interface TreeDocxSessionView extends HeadlessDocumentView {
     collaborationPort(documentId: string): CollaborationDocumentPort;
     /** Serialize the whole package back to DOCX bytes. */
     save(): Uint8Array;
+    /**
+     * {@link save} in steps a caller can pause between. The package is captured at the call, so
+     * the bytes describe the document as it was then, whatever happens between steps.
+     */
+    saveSteps(): Generator<void, Uint8Array>;
     /**
      * The resolved header/footer parts of the section, by variant (phase 2).
      *
@@ -506,7 +519,7 @@ interface TreeDocxSessionView extends HeadlessDocumentView {
     /** ISO-8601. Omitted writes no `@w:date`, because inventing one is a content change. */
     date?: string, scope?: StoryScope, 
     /** Binds id allocation to one actor, so two peers cannot mint the same comment id. */
-    actorId?: string): string | null;
+    actorId?: string, options?: PackageWriteOptions): string | null;
     /**
      * Resolve a comment thread, or reopen it. False when the document holds no such comment.
      *
@@ -514,7 +527,7 @@ interface TreeDocxSessionView extends HeadlessDocumentView {
      * `commentsExtended.xml`, a part a document with no thread does not have, so the state and the
      * part that records it commit together.
      */
-    setCommentResolved(commentId: string, resolved: boolean): boolean;
+    setCommentResolved(commentId: string, resolved: boolean, options?: PackageWriteOptions): boolean;
     /**
      * Delete a comment thread outright — body, thread state and story markers.
      *
@@ -523,7 +536,7 @@ interface TreeDocxSessionView extends HeadlessDocumentView {
      * shared notes part. False when the document holds no such comment, or when the removal was
      * refused.
      */
-    deleteComment(commentId: string, scope?: StoryScope, noteId?: number): boolean;
+    deleteComment(commentId: string, scope?: StoryScope, noteId?: number, options?: PackageWriteOptions): boolean;
     /**
      * Delete several comment objects as one package transaction and one undo unit.
      *
@@ -533,7 +546,7 @@ interface TreeDocxSessionView extends HeadlessDocumentView {
     deleteComments(comments: readonly {
         readonly commentId: string;
         readonly parentCommentId?: string;
-    }[], scope?: StoryScope, noteId?: number): boolean;
+    }[], scope?: StoryScope, noteId?: number, options?: PackageWriteOptions): boolean;
     /**
      * Insert a custom node, with the payload it carries, as ONE transaction.
      *
@@ -545,7 +558,7 @@ interface TreeDocxSessionView extends HeadlessDocumentView {
      * to live in its `w:tag` needs.
      */
     /** `scope` names the story the paragraph is in, and defaults to the body. */
-    insertCustomNode(write: InsertCustomNodeWrite, scope?: StoryScope): CustomNodeWriteResult;
+    insertCustomNode(write: InsertCustomNodeWrite, scope?: StoryScope, options?: PackageWriteOptions): CustomNodeWriteResult;
     /**
      * Remove a custom node and, in the same transaction, the payload it bound.
      *
@@ -663,4 +676,4 @@ interface TreeDocxSessionView extends HeadlessDocumentView {
 }
 
 export { bodyParagraphs as d, docToTreeOps as e, partHasNode as p, reconcileDoc as r, treeToDoc as t };
-export type { DocumentStyleEntry as D, MapResult as M, TreeDocxSessionView as T, TreeApplyResult as a, TreeApplyOptions as b, TreeBindingRejection as c, DocumentThemeColorEntry as f };
+export type { DocumentStyleEntry as D, MapResult as M, PackageWriteOptions as P, TreeDocxSessionView as T, TreeApplyResult as a, TreeApplyOptions as b, TreeBindingRejection as c, DocumentThemeColorEntry as f };

package/dist/unsupported-elements-CVos5cqe.d.ts

@@ -0,0 +1,23 @@
+import { U as UnsupportedElement } from './semantic-records-BvN-WWst.js';
+
+/** A component mount point and its built-in fallback. @public */
+interface UnsupportedElementHost {
+    /** Stable identity for one painted occurrence. */
+    readonly key: string;
+    readonly element: HTMLElement;
+    readonly fallback: HTMLElement;
+    readonly slot: HTMLElement;
+    readonly unsupported: UnsupportedElement;
+    /** Hide the default and expose custom controls to assistive technology. Restore with false. */
+    setCustomized(custom: boolean): void;
+}
+/**
+ * Observe placeholder mounts across repaint, pagination, and document replacement.
+ * The returned function disconnects the observer. Component mutations do not publish
+ * another list unless the engine's mount points change.
+ * @public
+ */
+declare function observeUnsupportedElements(container: HTMLElement, listener: (hosts: readonly UnsupportedElementHost[]) => void): () => void;
+
+export { observeUnsupportedElements as o };
+export type { UnsupportedElementHost as U };

package/docs/accept-reject-without-scrolling.md

@@ -0,0 +1,95 @@
+<!-- Generated from docs/site/content/recipes by scripts/sync-agent-docs.mjs. Edit the source and run `bun run docs:agent`. -->
+
+# Accept or reject without scrolling
+
+When your own list drives the scroll, open an item with `useReview().setActive(key, { reveal: false })`. The caret moves to the item, and the page stays where it is. Then resolve the item with `accept(item)` or `reject(item)`. Review writes such as accept, reject, and comment never scroll the page.
+
+**React**
+
+```tsx
+import { useReview, type ReviewItemView } from '@docx-editor.dev/pro/react';
+
+export function ChangeRow({ item }: { item: ReviewItemView }) {
+  const { setActive, accept, reject } = useReview();
+  return (
+    <li onClick={() => setActive(item.key, { reveal: false })}>
+      {item.text}
+      <button
+        disabled={item.readOnly}
+        onClick={(event) => {
+          event.stopPropagation();
+          accept(item);
+        }}
+      >
+        Accept
+      </button>
+      <button
+        disabled={item.readOnly}
+        onClick={(event) => {
+          event.stopPropagation();
+          reject(item);
+        }}
+      >
+        Reject
+      </button>
+    </li>
+  );
+}
+```
+
+`accept` and `reject` return `false` when the editor refuses the decision, for example in viewing mode. Read `useReview().lastRefusal` for the diagnostic code.
+
+**Vue**
+
+```vue
+<script setup lang="ts">
+import { useReview, type ReviewItemView } from '@docx-editor.dev/pro/vue';
+
+defineProps<{ item: ReviewItemView }>();
+const { setActive, accept, reject } = useReview();
+</script>
+
+<template>
+  <li @click="setActive(item.key, { reveal: false })">
+    {{ item.text }}
+    <button :disabled="item.readOnly" @click.stop="accept(item)">Accept</button>
+    <button :disabled="item.readOnly" @click.stop="reject(item)">Reject</button>
+  </li>
+</template>
+```
+
+`accept` and `reject` return `false` when the editor refuses the decision, for example in viewing mode. `useReview()` returns `lastRefusal` as a ref, so read `lastRefusal.value?.code` in script, or `lastRefusal?.code` in the template.
+
+The buttons stop the click from reaching the row, so a decision does not also activate the item.
+
+`reveal` takes `false` or one of four placements:
+
+| Value | Where the item lands |
+| --- | --- |
+| `'centerIfNeeded'` (default) | Stays still when the item is on screen; centered when it has to travel. |
+| `'center'` | Always centered. |
+| `'nearest'` | The smallest scroll that brings it into view. |
+| `'start'` | Near the top of the viewport. |
+
+Add `announce: true` to open the packaged balloon or card for the item.
+
+## Decide in a headless pipeline
+
+The editing API has no viewport. Load the revisions and call `Revision.accept()` or `Revision.reject()`.
+
+```ts
+import { DocxEditor } from '@docx-editor.dev/editor-api';
+
+const runtime = await DocxEditor.createServer(bytes, { author: 'Review bot' });
+await runtime.run(async (context) => {
+  const revisions = context.document.body.revisions;
+  revisions.load('items/author');
+  await context.sync();
+  for (const revision of revisions.items) {
+    if (revision.author === 'Review bot') revision.accept();
+  }
+  await context.sync();
+});
+const saved = await runtime.save();
+runtime.dispose();
+```

package/docs/comment-on-found-text.md

@@ -0,0 +1,72 @@
+<!-- Generated from docs/site/content/recipes by scripts/sync-agent-docs.mjs. Edit the source and run `bun run docs:agent`. -->
+
+# Comment on found text
+
+In a browser host, find the text with `editor.findMatches`, select the first match with `editor.selectMatch`, and then call `useReview().comment`. The comment is written as the editor's `author`, so set `author` on the editor and add `reviewModule()` to its modules. `selectMatch` opens the header, footer, or note that holds the match, so a match in any story works.
+
+**React**
+
+```tsx
+import { useDocxEditor } from '@docx-editor.dev/react';
+import { useReview } from '@docx-editor.dev/pro/react';
+
+export function CommentOnTerm({ term }: { term: string }) {
+  const editor = useDocxEditor();
+  const { comment } = useReview();
+  const run = () => {
+    const [match] = editor?.findMatches(term, { wholeWord: true }) ?? [];
+    if (match && editor?.selectMatch(match).ok) comment(`Define "${term}".`);
+  };
+  return <button onClick={run}>Comment on {term}</button>;
+}
+```
+
+`comment` returns `false` when the editor refuses the write. Read `useReview().lastRefusal` for the diagnostic code.
+
+**Vue**
+
+```vue
+<script setup lang="ts">
+import { useDocxEditor } from '@docx-editor.dev/vue';
+import { useReview } from '@docx-editor.dev/pro/vue';
+
+const props = defineProps<{ term: string }>();
+const editor = useDocxEditor();
+const { comment } = useReview();
+function run() {
+  const [match] = editor.value?.findMatches(props.term, { wholeWord: true }) ?? [];
+  if (match && editor.value?.selectMatch(match).ok) comment(`Define "${props.term}".`);
+}
+</script>
+
+<template>
+  <button @click="run">Comment on {{ term }}</button>
+</template>
+```
+
+`comment` returns `false` when the editor refuses the write. `useReview()` returns `lastRefusal` as a ref, so read `lastRefusal.value?.code` in script, or `lastRefusal?.code` in the template.
+
+## Comment in a headless pipeline
+
+On a server or in an agent pipeline, search the body and call `Range.insertComment`. The runtime writes the comment as its `author` option.
+
+```ts
+import { DocxEditor } from '@docx-editor.dev/editor-api';
+
+const runtime = await DocxEditor.createServer(bytes, { author: 'Review bot' });
+await runtime.run(async (context) => {
+  const found = context.document.body.search(term, { matchWholeWord: true });
+  found.load('items');
+  await context.sync();
+  found.items[0]?.insertComment(`Define "${term}".`);
+  await context.sync();
+});
+const saved = await runtime.save();
+runtime.dispose();
+```
+
+Both paths save the same comment markup: the same `w:comment` attributes, the same date format, and the same range markers.
+
+## Reply to a thread
+
+To answer an existing comment, call `useReview().reply(item, text)` in a browser host, or `Comment.reply(text)` in the editing API.

package/docs/custom-review-cards.md

@@ -0,0 +1,178 @@
+<!-- Generated from docs/site/content/recipes by scripts/sync-agent-docs.mjs. Edit the source and run `bun run docs:agent`. -->
+
+# Custom cards in the review rail
+
+To draw your own cards, render `DocxEditorReview` with `preset` set to `false` and put your card component inside it. Your component reads the items from `useReview()`, measures each card, stacks the cards with `useStackedReviewPositions`, and converts positions to pixels with `useReviewRailMetrics()`.
+
+Measure every card with a `ResizeObserver` and pass the heights in CSS pixels. Without measured heights, each card reserves only `defaultHeight`, and a taller card overlaps the next one.
+
+**React**
+
+```tsx
+import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react';
+import {
+  DocxEditorReview,
+  useReview,
+  useReviewRailMetrics,
+  useStackedReviewPositions,
+} from '@docx-editor.dev/pro/react';
+
+type OnHeight = (key: string, height: number) => void;
+
+function MeasuredCard({
+  id,
+  top,
+  onHeight,
+  children,
+}: {
+  id: string;
+  top: number;
+  onHeight: OnHeight;
+  children: ReactNode;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const node = ref.current!;
+    const observer = new ResizeObserver(() => onHeight(id, node.offsetHeight));
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [id, onHeight]);
+  return (
+    <div ref={ref} style={{ position: 'absolute', top }}>
+      {children}
+    </div>
+  );
+}
+
+function MyCards() {
+  const { items, selectionAnchorY, accept } = useReview();
+  const metrics = useReviewRailMetrics();
+  const [heights, setHeights] = useState<ReadonlyMap<string, number>>(() => new Map());
+  const onHeight = useCallback<OnHeight>(
+    (key, height) =>
+      setHeights((prev) => (prev.get(key) === height ? prev : new Map(prev).set(key, height))),
+    []
+  );
+  const positions = useStackedReviewPositions(items, heights, {
+    scale: metrics.scale,
+    defaultHeight: 96,
+  });
+  const top = (y: number) => metrics.top + y * metrics.scale;
+  return (
+    <>
+      {items.map((item) => (
+        <MeasuredCard
+          key={item.key}
+          id={item.key}
+          top={top(positions.get(item.key) ?? 0)}
+          onHeight={onHeight}
+        >
+          {item.text}
+          {item.kind === 'revision' && <button onClick={() => accept(item)}>Accept</button>}
+        </MeasuredCard>
+      ))}
+      <DocxEditorReview.Draft top={top(selectionAnchorY ?? 0)} />
+    </>
+  );
+}
+
+export function MyRail() {
+  return (
+    <DocxEditorReview preset={false}>
+      <MyCards />
+      <DocxEditorReview.AddComment />
+    </DocxEditorReview>
+  );
+}
+```
+
+The heights map gets a new reference only when a height changes, so the stack recomputes only then. Keep that rule if you store heights another way.
+
+**Vue**
+
+```vue
+<!-- MyCards.vue -->
+<script setup lang="ts">
+import { onBeforeUnmount, shallowReactive } from 'vue';
+import {
+  DocxEditorReview,
+  useReview,
+  useReviewRailMetrics,
+  useStackedReviewPositions,
+} from '@docx-editor.dev/pro/vue';
+
+const { items, selectionAnchorY, accept } = useReview();
+const { metrics } = useReviewRailMetrics();
+// Reactive, so a new measurement restacks the cards.
+const heights = shallowReactive(new Map<string, number>());
+const positions = useStackedReviewPositions(items, heights, () => ({
+  scale: metrics.value.scale,
+  defaultHeight: 96,
+}));
+const top = (y: number) => `${metrics.value.top + y * metrics.value.scale}px`;
+
+const observed = new Map<string, { el: Element; observer: ResizeObserver }>();
+function measure(key: string, el: unknown) {
+  const current = observed.get(key);
+  if (current?.el === el) return;
+  current?.observer.disconnect();
+  observed.delete(key);
+  if (!(el instanceof HTMLElement)) {
+    heights.delete(key);
+    return;
+  }
+  const observer = new ResizeObserver(() => heights.set(key, el.offsetHeight));
+  observer.observe(el);
+  observed.set(key, { el, observer });
+}
+onBeforeUnmount(() => observed.forEach(({ observer }) => observer.disconnect()));
+</script>
+
+<template>
+  <div
+    v-for="item in items"
+    :key="item.key"
+    :ref="(el) => measure(item.key, el)"
+    :style="{ position: 'absolute', top: top(positions.get(item.key) ?? 0) }"
+  >
+    {{ item.text }}
+    <button v-if="item.kind === 'revision'" @click="accept(item)">Accept</button>
+  </div>
+  <DocxEditorReview.Draft :top="metrics.top + (selectionAnchorY ?? 0) * metrics.scale" />
+</template>
+```
+
+```vue
+<!-- MyRail.vue -->
+<script setup lang="ts">
+import { DocxEditorReview } from '@docx-editor.dev/pro/vue';
+import MyCards from './MyCards.vue';
+</script>
+
+<template>
+  <DocxEditorReview :preset="false">
+    <MyCards />
+    <DocxEditorReview.AddComment />
+  </DocxEditorReview>
+</template>
+```
+
+A plain `Map` is not reactive, so writes to it would not restack the cards. Use `shallowReactive(new Map())`, or a ref that you replace on each change.
+
+## Root parts and card parts
+
+`DocxEditorReview` finds its parts among its own children by element type.
+
+- **Root parts** are `List`, `Markers`, `AddComment`, `Draft`, and `Balloon`. Put them as direct children of `DocxEditorReview`. Fragments are transparent in React and in Vue. The rail gives these parts geometry that only it can compute, such as the comment button's `top`. A root part inside your own wrapper component is not a part. It renders as ordinary content, without that wiring.
+- **Card parts** are `Card`, `Empty`, and the parts inside a card, such as `Author`, `Summary`, `Accept`, and `Reply`. Put them inside `DocxEditorReview.List`.
+
+With `preset` set to `false`, the rail adds no defaults. Root parts that you pass keep their wiring. Every other child renders as is inside the rail element, where `useReviewRailMetrics()` reads the rail's own measurement.
+
+## Position the compose box
+
+`DocxEditorReview.Draft` renders only while a comment draft is open. A draft opens from `DocxEditorReview.AddComment` or from the `review.addComment` toolbar control. You can place `Draft` in either of these places:
+
+- As a direct child of `DocxEditorReview`.
+- Inside your own card component, as in the example. It still renders only while the draft is open.
+
+Without `top`, the box sits where the packaged card stack puts it. That position comes from the packaged cards, not yours, so when you render your own cards, pass `top` from your own stack. In the narrow compact rail, the box takes the compact card's `left` in both cases, so it does not overflow the marker strip. The example places the box at the selection's anchor. To keep it clear of your cards, add an entry with the key of your choice and the anchor `selectionAnchorY` to the list that you pass to `useStackedReviewPositions`, in document order.

package/docs/highlight-ranges.md

@@ -0,0 +1,48 @@
+<!-- Generated from docs/site/content/recipes by scripts/sync-agent-docs.mjs. Edit the source and run `bun run docs:agent`. -->
+
+# Highlight ranges
+
+Use `useHighlights(name, source, options)` to mark text as a named set while a component is mounted. A function source runs again after document changes, so the marks follow the text. Highlights are view state. They do not change the document and are not saved.
+
+**React**
+
+```tsx
+import { useCallback } from 'react';
+import { useHighlights, type Editor } from '@docx-editor.dev/react';
+
+export function GlossaryMarks({ terms }: { terms: readonly string[] }) {
+  const findTerms = useCallback(
+    (editor: Editor) => editor.findMatches(terms, { wholeWord: true }).flat(),
+    [terms]
+  );
+  const { applied } = useHighlights('glossary', findTerms, { className: 'glossary-term' });
+  return <span>{applied} marked</span>;
+}
+```
+
+Keep a function source stable with `useCallback`.
+
+**Vue**
+
+```vue
+<script setup lang="ts">
+import { useHighlights, type Editor } from '@docx-editor.dev/vue';
+
+const props = defineProps<{ terms: readonly string[] }>();
+const result = useHighlights(
+  'glossary',
+  (editor: Editor) => editor.findMatches(props.terms, { wholeWord: true }).flat(),
+  { className: 'glossary-term' }
+);
+</script>
+
+<template>
+  <span>{{ result.applied }} marked</span>
+</template>
+```
+
+A function source that reads props or refs runs again when they change.
+
+Use a unique `name` for each set. Two calls with the same name replace each other's ranges. Set `activeIndex` in the options to show one range in the active color, for example the current result of your own search list.
+
+Outside a component, call `watchHighlights(editor, name, source, options)` from `@docx-editor.dev/core/editor`, or `editor.setHighlights` for a fixed set.

package/docs/index.md

@@ -0,0 +1,36 @@
+<!-- Generated from docs/site/content/recipes by scripts/sync-agent-docs.mjs. Edit the source and run `bun run docs:agent`. -->
+
+# Which API for which job
+
+The library has two ways to change a document. Each one fits a different host. Choose the path first, then use the symbol for your task.
+
+| Job | Use |
+| --- | --- |
+| Build a review UI in the browser | The React or Vue adapter hooks, plus the review hooks and `DocxEditorReview` from `@docx-editor.dev/pro/react` or `@docx-editor.dev/pro/vue`. |
+| Edit in a headless, server, or agent pipeline | The editing API in `@docx-editor.dev/editor-api`, which follows the Office.js object model. |
+
+| Task | Browser host (React or Vue) | Headless, server, or agent |
+| --- | --- | --- |
+| [Comment on found text](./comment-on-found-text.md) | `editor.findMatches`, `editor.selectMatch`, then `useReview().comment` | `body.search`, then `Range.insertComment` |
+| Reply to a thread | `useReview().reply(item, text)` | `Comment.reply(text)` |
+| [Record a tracked replacement](./tracked-replacement.md) | Suggesting mode, then `editor.exec({ type: 'replaceMatch', match, text })` | `document.changeTrackingMode = 'TrackMineOnly'`, then `Range.insertText(text, 'Replace')` |
+| [Propose an AI rewrite as tracked changes](./propose-rewrite.md) | The same code through `DocxEditor.createBrowser` from `@docx-editor.dev/editor-api/browser` | `prepareRewrite` from `@docx-editor.dev/editor-api/agent` |
+| [Accept or reject a change](./accept-reject-without-scrolling.md) | `useReview().accept(item)` or `useReview().reject(item)` | `Revision.accept()` or `Revision.reject()` |
+| [Open or reveal a change without scrolling](./accept-reject-without-scrolling.md) | `useReview().setActive(key, { reveal: false })` | Not applicable: no viewport |
+| [Highlight ranges](./highlight-ranges.md) | `useHighlights(name, source, options)` | Not applicable |
+| [Custom review rail cards](./custom-review-cards.md) | `DocxEditorReview` with `preset` set to `false`, `useReview().items`, `useStackedReviewPositions`, and `useReviewRailMetrics` | Not applicable |
+| Comment-on-selection button | `DocxEditorReview.AddComment` as a direct child of `DocxEditorReview`, or `useEditorCommand('review.addComment')` | Not applicable |
+| Page setup and paragraph dialogs from a custom toolbar | `DocxEditor.PageSetupDialog` or `DocxEditor.ParagraphDialog` with `open` and a close handler (`onClose` in React, `@close` in Vue); enable the button from `usePageSetup().isEnabled` or `useParagraphFormat().isEnabled` | `Section.pageSetup`, and `Paragraph` properties such as `alignment` |
+
+The review hooks need `reviewModule()` from `@docx-editor.dev/pro` in the editor's modules, and an editor `author` for comments and tracked changes. The editing API takes its author from the `author` option of `DocxEditor.createServer`, imported from `@docx-editor.dev/editor-api`, or of `DocxEditor.createBrowser`, imported from `@docx-editor.dev/editor-api/browser`.
+
+## Recipes
+
+- [Comment on found text](./comment-on-found-text.md)
+- [Replace as a tracked change](./tracked-replacement.md)
+- [Propose an AI rewrite as tracked changes](./propose-rewrite.md)
+- [Custom cards in the review rail](./custom-review-cards.md)
+- [Highlight ranges](./highlight-ranges.md)
+- [Accept or reject without scrolling](./accept-reject-without-scrolling.md)
+
+For the full hook reference, see [React hooks](https://www.docx-editor.dev/docs/2.x/react/hooks) and [Vue composables](https://www.docx-editor.dev/docs/2.x/vue/composables). For the editing API, see [Editing API](https://www.docx-editor.dev/docs/2.x/editor-api).