@docx-editor.dev/core 2.31.0 → 2.33.0

package/dist/{tree-package-store-B8l8DX3Z.d.ts → tree-package-store-DXhX1PE-.d.ts}

@@ -1,4 +1,4 @@
-import { Q as OoxmlPackage, af as SupportedImageMime, O as OoxmlPart, N as OoxmlNode, ap as OoxmlElement, aH as PackageWatermarkWrite, aI as OoxmlInvariantIssue, aE as ImageDecodePort, aG as RevisionAttributionInput, aJ as DrawingTreeDocOp, aK as ImpactClass, ao as TreeDocOp, aC as TreeOpRejection, aL as OoxmlParagraphNode, aM as OoxmlNoteNode, aN as OoxmlContinuationSeparatorNode, aO as OoxmlEndnotesNode, aP as OoxmlFootnotesNode, aQ as OoxmlNoteRefNode, aR as OoxmlNoteReferenceNode, aS as OoxmlSeparatorNode } from './types-barrel-CkF2JbU4.js';
+import { a5 as OoxmlPackage, an as SupportedImageMime, O as OoxmlPart, a4 as OoxmlNode, av as OoxmlElement, aH as PackageWatermarkWrite, aI as OoxmlInvariantIssue, ad as ImageDecodePort, aE as RevisionAttributionInput, aJ as DrawingTreeDocOp, aK as ImpactClass, au as TreeDocOp, aF as TreeOpRejection, aL as OoxmlParagraphNode, aM as OoxmlNoteNode, aN as OoxmlContinuationSeparatorNode, aO as OoxmlEndnotesNode, aP as OoxmlFootnotesNode, aQ as OoxmlNoteRefNode, aR as OoxmlNoteReferenceNode, aS as OoxmlSeparatorNode } from './tree-op-types-Df4oY2u4.js';
 
 /** A freshly allocated drawing property id, or the reason one could not be minted. */
 type DrawingPropertyIdResult = {
@@ -1098,6 +1098,11 @@ interface FragmentPasteInput {
      * merged document shows it. Omitted (solo) keeps Word's dense sequences.
      */
     readonly actorId?: string;
+    /**
+     * Suggesting mode: the author and date the whole paste is proposed under, as one tracked
+     * insertion (`trackedFragment`). The caller tracks `priorOps` itself.
+     */
+    readonly revision?: RevisionAttributionInput;
 }
 type FragmentPasteResult = (Extract<PackageTransactResult, {
     ok: true;
@@ -1381,5 +1386,5 @@ declare class TreePackageStore {
     private publishSynthetic;
 }
 
-export { NOTE_CONTINUATION_SEPARATOR_ID as B, DEFAULT_MAX_EDITABLE_STORY_PARTS as D, NOTE_ID_MAX as G, NOTE_ID_MIN as J, NOTE_SEPARATOR_ID as K, MAX_FRAGMENT_DECODED_BYTES as M, TreePackageStore as T, allocateDrawingPropertyId as a8, allocateNoteId as a9, isNoteNode as aA, isNoteRefNode as aB, isNoteReferenceNode as aC, isSeparatorNode as aD, normalNoteIds as aE, noteAtomText as aF, noteIdOf as aG, noteKindOf as aH, noteRefKindOf as aI, noteReferenceKindOf as aJ, noteTypeOf as aK, notesOf as aL, notesPartHasId as aM, observeHistoryGroup as aN, parentNodeOf as aO, parseNoteId as aP, parseNoteScopeId as aQ, removeNode as aR, replaceChildren as aS, replaceNode as aT, resolveHeaderFooterParts as aU, resolveHeaderFooterPartsBySection as aV, resolveHeaderFooterResolutionBySection as aW, resolveNotesPart as aX, withBinaryPart as aY, withEmbeddedImage as aZ, withoutUnreferencedImagePart as a_, applyEdits as aa, applyFragmentPaste as ab, applyHeaderFooterLifecycleOp as ac, applyNoteLifecycleOp as ad, atomicNoteSpansOf as ae, cascadeDeletedNoteReferences as af, collectNodeIds as ag, collectNoteReferences as ah, collectPackageNoteReferences as ai, collectSectionPropertyNodes as aj, createNodeIdAllocator as ak, createNoteReferenceScanBudget as al, customMarkFollows as am, diagnoseNoteReferences as an, findNode as ao, findNoteById as ap, formatNoteScopeId as aq, hasNode as ar, insertChildren as as, isContinuationSeparatorNode as at, isEndnotesNode as au, isFootnotesNode as av, isHeaderFooterLifecycleOp as aw, isNormalNote as ax, isNoteAtomNode as ay, isNoteLifecycleOp as az, TreeDocumentStore as f, reportHistoryGroup as r, MAX_NOTES_PER_PART as w, MAX_NOTE_REFERENCE_PARTS as x, MAX_NOTE_REFERENCE_SCAN as y, NOTE_ATOM_CHAR as z };
-export type { PackageTransactResult as $, ApplyImagePropertiesInput as A, ContentLockPolicy as C, EditOptions as E, FieldResultsMode as F, HeaderFooterParts as H, InsertImageInput as I, NoteDiagnostic as L, NoteKind as N, NoteDiagnosticCode as O, NoteLifecycleImpact as P, NoteLifecycleOp as Q, ReplaceImageOptions as R, StoryScope as S, NoteLifecycleOptions as U, NoteLifecycleRejection as V, NoteLifecycleResult as W, NoteReferenceHit as X, NoteReferenceScanBudget as Y, NoteType as Z, OoxmlEditResult as _, HeaderFooterSectionResolution as a, RemotePackageAttribution as a0, StoryResolveResult as a1, TransactionRevisionIds as a2, TreeDocumentStoreOptions as a3, TreePackageStoreOptions as a4, TreeStoryRef as a5, TransactResult as a6, TransactionContext as a7, StoryTargetRejection as b, HeaderFooterVariant as c, HistoryGroup as d, TreeModelChange as e, SelectionMark as g, TransactOptions as h, ImageIntentResult as i, FragmentPasteInput as j, FragmentPasteResult as k, AtomicNoteSpan as l, CascadeDeletedNoteReferencesOptions as m, DrawingPropertyIdResult as n, HeaderFooterKind as o, HeaderFooterLifecycleImpact as p, HeaderFooterLifecycleOp as q, HeaderFooterLifecycleRejection as s, HeaderFooterLifecycleResult as t, HeaderFooterSlotMeta as u, HistoryCaptureKind as v };
+export { NOTE_CONTINUATION_SEPARATOR_ID as B, DEFAULT_MAX_EDITABLE_STORY_PARTS as D, NOTE_ID_MAX as G, NOTE_ID_MIN as J, NOTE_SEPARATOR_ID as K, MAX_FRAGMENT_DECODED_BYTES as M, TreePackageStore as T, allocateDrawingPropertyId as a8, allocateNoteId as a9, isNoteNode as aA, isNoteRefNode as aB, isNoteReferenceNode as aC, isSeparatorNode as aD, normalNoteIds as aE, noteAtomText as aF, noteIdOf as aG, noteKindOf as aH, noteRefKindOf as aI, noteReferenceKindOf as aJ, noteTypeOf as aK, notesOf as aL, notesPartHasId as aM, observeHistoryGroup as aN, parentNodeOf as aO, parseNoteId as aP, parseNoteScopeId as aQ, removeNode as aR, replaceChildren as aS, replaceNode as aT, resolveHeaderFooterParts as aU, resolveHeaderFooterPartsBySection as aV, resolveHeaderFooterResolutionBySection as aW, resolveNotesPart as aX, withBinaryPart as aY, withEmbeddedImage as aZ, withoutUnreferencedImagePart as a_, applyEdits as aa, applyFragmentPaste as ab, applyHeaderFooterLifecycleOp as ac, applyNoteLifecycleOp as ad, atomicNoteSpansOf as ae, cascadeDeletedNoteReferences as af, collectNodeIds as ag, collectNoteReferences as ah, collectPackageNoteReferences as ai, collectSectionPropertyNodes as aj, createNodeIdAllocator as ak, createNoteReferenceScanBudget as al, customMarkFollows as am, diagnoseNoteReferences as an, findNode as ao, findNoteById as ap, formatNoteScopeId as aq, hasNode as ar, insertChildren as as, isContinuationSeparatorNode as at, isEndnotesNode as au, isFootnotesNode as av, isHeaderFooterLifecycleOp as aw, isNormalNote as ax, isNoteAtomNode as ay, isNoteLifecycleOp as az, TreeDocumentStore as d, reportHistoryGroup as r, MAX_NOTES_PER_PART as w, MAX_NOTE_REFERENCE_PARTS as x, MAX_NOTE_REFERENCE_SCAN as y, NOTE_ATOM_CHAR as z };
+export type { PackageTransactResult as $, ApplyImagePropertiesInput as A, ContentLockPolicy as C, EditOptions as E, FieldResultsMode as F, HeaderFooterVariant as H, InsertImageInput as I, NoteDiagnostic as L, NoteKind as N, NoteDiagnosticCode as O, NoteLifecycleImpact as P, NoteLifecycleOp as Q, ReplaceImageOptions as R, StoryScope as S, NoteLifecycleOptions as U, NoteLifecycleRejection as V, NoteLifecycleResult as W, NoteReferenceHit as X, NoteReferenceScanBudget as Y, NoteType as Z, OoxmlEditResult as _, StoryTargetRejection as a, RemotePackageAttribution as a0, StoryResolveResult as a1, TransactionRevisionIds as a2, TreeDocumentStoreOptions as a3, TreePackageStoreOptions as a4, TreeStoryRef as a5, TransactResult as a6, TransactionContext as a7, HistoryGroup as b, TreeModelChange as c, HeaderFooterParts as e, HeaderFooterSectionResolution as f, SelectionMark as g, TransactOptions as h, ImageIntentResult as i, FragmentPasteInput as j, FragmentPasteResult as k, AtomicNoteSpan as l, CascadeDeletedNoteReferencesOptions as m, DrawingPropertyIdResult as n, HeaderFooterKind as o, HeaderFooterLifecycleImpact as p, HeaderFooterLifecycleOp as q, HeaderFooterLifecycleRejection as s, HeaderFooterLifecycleResult as t, HeaderFooterSlotMeta as u, HistoryCaptureKind as v };

package/dist/{tree-session-contract-DeLRqohz.d.ts → tree-session-contract-CF2625mv.d.ts}

@@ -1,10 +1,10 @@
-import { S as StoryScope, g as SelectionMark, h as TransactOptions, d as HistoryGroup, 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-B8l8DX3Z.js';
-import { ao as TreeDocOp, O as OoxmlPart, N as OoxmlNode, Q as OoxmlPackage, ap as OoxmlElement, a as ReviewItem, af as SupportedImageMime, aE as ImageDecodePort, aG as RevisionAttributionInput } from './types-barrel-CkF2JbU4.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-TeUvMP13.js';
-import { H as HeadlessDocumentView, D as DocumentProperties } from './headless-document-view-qOpaCF82.js';
+import { S as StoryScope, g as SelectionMark, h as TransactOptions, b as HistoryGroup, a as StoryTargetRejection, c as TreeModelChange, e as HeaderFooterParts, f as HeaderFooterSectionResolution, I as InsertImageInput, i as ImageIntentResult, R as ReplaceImageOptions, A as ApplyImagePropertiesInput, j as FragmentPasteInput, k as FragmentPasteResult } from './tree-package-store-DXhX1PE-.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, aE as RevisionAttributionInput } from './tree-op-types-Df4oY2u4.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-AqY5KpVx.js';
+import { H as HeadlessDocumentView, c as DocumentProperties } from './drawing-graphic-kind-CXYGYbB3.js';
 import { Node } from 'prosemirror-model';
 import { CollaborationDocumentPort } from './collaboration/replication.js';
-import { V as ViewScope } from './editor-scope-C7ke1KJG.js';
+import { V as ViewScope } from './editor-scope-CA6egMaK.js';
 
 /**
  * Why an edited projection could not be mapped back into tree ops.

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

@@ -0,0 +1,23 @@
+import { U as UnsupportedElement } from './semantic-records-DoK0lNjS.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).