> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Redlining

A redline is a document with tracked changes. Word shows each change with its author and date, and the reader accepts or rejects it. OfficeJS writes real Word revisions (`w:ins`, `w:del`, `w:rPrChange` …), so Word, Google Docs and LibreOffice show them as usual.

The examples use Node. In a page, import `WordDocument` from `@reductoai/docx/officejs` or `@reductoai/docx/browser` and use `fromBytes` / `toBytes`. The editing code is the same.

## Turn on tracking

```ts theme={null}
import { WordDocument } from "@reductoai/docx/node";

const doc = await WordDocument.open("msa.docx");
doc.revisionAuthor = "Legal Review";
doc.changeTrackingMode = "TrackAll";
```

From now on, each supported edit is a revision by `revisionAuthor`. Set `changeTrackingMode = "Off"` to make clean edits again.

## Replace, insert and delete

```ts theme={null}
// Replace: a deletion of the old text and an insertion of the new text
for (const hit of doc.body.search("30 days").items) {
  hit.insertText("15 business days", "Replace");
}

// Insert at the end of a paragraph
const clause = doc.body.paragraphs.items[1];
clause.getRange("End").insertText(" Time is of the essence.", "End");

// A new paragraph is a tracked insertion too
doc.body.insertParagraph("This clause is new.", "End");

// Delete
doc.body.search("without limitation, ").getFirst().delete();

await doc.save("msa-redline.docx");
```

Search is scoped to a story. `doc.body.search` does not search text boxes, headers, footers or notes; `doc.search` adds the body's text boxes. Search headers and footers through their own handles, for example `section.getHeader("Primary").search(...)`.

## Comment on a change

```ts theme={null}
const fee = doc.body.search("60 days", { matchCase: true }).getFirst();
fee.insertText("45 days", "Replace");
fee.insertComment("Finance asked for net-45.");
```

A comment takes its author from `revisionAuthor`. See [Comments](https://docs.reducto.ai/office/docx/recipes/comments.md) for replies and resolve.

## Read the revisions

```ts theme={null}
for (const rev of doc.revisions.items) {
  console.log(rev.type, rev.author, rev.date, JSON.stringify(rev.text));
}
// Delete  Legal Review  …  "30 days"
// Insert  Legal Review  …  "15 business days"
// Insert  Legal Review  …  " Time is of the essence."
```

`rev.getRange()` gives the text as a `Range`, and `rev.getRange().paragraph` gives its paragraph. A paragraph or range also has `getTrackedChanges()`.

`doc.revisions` groups changes as Word's Reviewing Pane does, in Word's order.

What joins into one revision:

* Adjacent insertions or deletions by one author are one revision, also across paragraphs.
* Format changes join only in one paragraph, and only when they record the same old formatting.
* Neighbouring paragraph format changes join when the paragraphs have the same new formatting and the changes record the same properties, whatever the old values.
* A format change on text that the author's next insertion continues joins that insertion's format change.
* Cell, row and table format changes are one revision for each run of adjacent rows by one author. Its text is those rows.
* A move is one revision for each side.

Tables:

* New or deleted cells of a column list their text first, then one `CellInsertion` or `CellDeletion` from the first cell to the end of the last cell's row.
* In an inserted row, another author's deletion is one revision for each cell. The deletion in the first cell comes before the row.

Order:

* A revision at the start of a paragraph, table or section comes before that paragraph's, table's or section's own format change.
* A deleted row comes before its insertion when both cover the same row.

The `text` of a revision:

* A section's format change has the whole section as its text.
* An equation's text is its letters as Word shows them, such as `𝑥−1`.
* A picture reads as `/`.
* A format change on a field code reads as the code.

Some changes are not listed, as in Word. `acceptAllRevisions()` and `rejectAllRevisions()` still settle them:

* A format change that the style already gives (bold on a bold heading).
* A table's own format change with no cell or row format change by its author.

`getTrackedChanges()` keeps a finer list. Use it when you must settle one cell or one paragraph alone.

### Before and after text

```ts theme={null}
const before = doc.body.getReviewedText("Original").value;
const after = doc.body.getReviewedText("Current").value;
```

This is the fastest way to give an LLM, a diff tool or a test both versions.

## Accept and reject

```ts theme={null}
// One change
const first = doc.revisions.getFirst();
first.reject();

// Changes by one author
for (const rev of doc.revisions.items) {
  if (rev.author === "Counterparty") rev.accept();
}

// Everything
doc.acceptAllRevisions(); // or doc.rejectAllRevisions()
```

After `accept()` or `reject()`, the handle is no longer valid. Read `doc.revisions` again for the new list.

## Render the redline

To get a PDF that shows the changes, as Word prints with *All Markup*:

```sh theme={null}
npx docx pdf msa-redline.docx -o msa-redline.pdf --tracked-changes inline --comments balloons
```

From code on node: `await doc.toPdf("msa-redline.pdf", { trackedChanges: "inline", comments: "balloons" })`. See [PDF: show tracked changes and comments](https://docs.reducto.ai/office/docx/conversion/pdf.md#node-show-tracked-changes-and-comments).

## Redline from an LLM

A common pattern: an LLM proposes edits as find-and-replace pairs, and OfficeJS applies them as tracked changes for a human to review.

```ts theme={null}
type Edit = { find: string; replace: string; reason?: string };

function applyEdits(doc: WordDocument, edits: Edit[]): string[] {
  const missed: string[] = [];
  doc.changeTrackingMode = "TrackAll";
  for (const edit of edits) {
    const hit = doc.body.search(edit.find, { matchCase: true }).getFirstOrNullObject();
    if (hit.isNullObject) {
      missed.push(edit.find);
      continue;
    }
    hit.insertText(edit.replace, "Replace");
    if (edit.reason) hit.insertComment(edit.reason);
  }
  return missed;
}
```

Give the model the text from `doc.body.text` or `await doc.readPage(n)`, and ask for quotes that occur once. Report `missed` back to the model so it can try again.

## Redline in the editor

The [editor](https://docs.reducto.ai/office/docx/ui/editor.md) has a *Suggesting* mode: the user's typing is tracked, and the review margin shows changes and comments. From code:

```ts theme={null}
editor.model.setSuggesting(true);
editor.model.setRevisionAuthor("Jordan Ruiz"); // author of the user's changes and comments
editor.model.review.accept("all"); // or reject, or { id } for one change
```

To apply OfficeJS edits to the document that the editor shows, see [Agent edits](https://docs.reducto.ai/office/docx/ui/agent-edits.md).
