Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
import { type LoroDoc, LoroMap, LoroText } from 'loro-crdt';
import {
DocxAgentError,
type DocxAgentOperation,
MAX_DOCX_OPERATIONS,
occurrences,
preview,
READ_BUDGET,
} from './agent-types';
import { keysBetween } from './fractional-index';
import {
encodeWrappers,
isDeleted,
isInserted,
markRevision,
Revisor,
revisionDate,
tagAttribute,
tracksRevisions,
type Wrapper,
withMarkRevision,
withParagraphChange,
withRowDeleted,
wrappersOf,
} from './revisions';
import {
findStyle,
type ParagraphStyleInfo,
paragraphStylesFromXml,
} from './styles';
import {
readWordComments,
type WordComment,
WordCommentWriter,
} from './word-comments';
/**
* AI tool requests on a Word document in the shared format the DOCX engine
* writes (format version 2): every block is a map in `wordBlocks` (`k`
* kind, `p` parent, `o` position key, `x` properties as XML) and every
* paragraph's text is rich text whose marks are its formatting (`r:w:b` →
* `<w:b/>`, ...). Edits land as ordinary CRDT operations, so open editors
* patch them in and concurrent typing elsewhere merges.
*/
/** Containers of the shared format. */
export const WORD_CONTAINERS = {
meta: 'docxMeta',
parts: 'wordParts',
blocks: 'wordBlocks',
} as const;
export const WORD_FORMAT_VERSION = 2;
/** Stands in for objects (pictures, fields, note references) in the text. */
const OBJECT = '';
const WORDML_NS =
'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
type Attributes = Record<string, string>;
type Span = { insert: string; attributes?: Attributes };
/** One block of the body as stored. */
export type WordBlock = {
id: string;
kind: string;
parent: string;
key: string;
props: string;
map: LoroMap;
};
/** A paragraph's text as a reader sees it, with where each character is. */
type Visible = {
text: string;
/** Index in the stored text of each visible character. */
at: number[];
/** Attributes of each visible character. */
attrs: Attributes[];
};
function field(map: LoroMap, key: string): string {
const value = map.get(key);
return typeof value === 'string' ? value : '';
}
/** Text that is not part of what a paragraph says: field codes, deleted
* text and markers between runs. */
function hidden(attrs: Attributes): boolean {
if ('instr' in attrs || 'mark' in attrs || 'obj' in attrs) return true;
const wrap = attrs.wrap;
return !!wrap && /<[\w]*:?del[\s>/]|<[\w]*:?moveFrom[\s>/]/.test(wrap);
}
/** Whether a run property mark turns its toggle on (`<w:b/>`, not `w:val="0"`). */
function on(xml: string | undefined): boolean {
if (!xml) return false;
const val = /:val="([^"]*)"/.exec(xml)?.[1];
return val === undefined || !['0', 'false', 'off', 'none'].includes(val);
}
/** The document's shared copy, read for an agent. */
export class WordDocument {
readonly blocks = new Map<string, WordBlock>();
private readonly children = new Map<string, WordBlock[]>();
/** The prefix the document binds to WordprocessingML. */
readonly w: string;
constructor(readonly doc: LoroDoc) {
doc.configDefaultTextStyle({ expand: 'none' });
const map = doc.getMap(WORD_CONTAINERS.blocks);
for (const id of map.keys()) {
const value = map.get(id);
if (!(value instanceof LoroMap)) continue;
const kind = field(value, 'k');
if (!kind) continue;
this.blocks.set(id, {
id,
kind,
parent: field(value, 'p'),
key: field(value, 'o'),
props: field(value, 'x'),
map: value,
});
}
this.reindex();
this.w = this.prefix();
}
private reindex() {
this.children.clear();
for (const block of this.blocks.values()) {
// Blocks whose parent is gone (a concurrent delete) are not shown.
if (block.parent && !this.blocks.has(block.parent)) continue;
const list = this.children.get(block.parent) ?? [];
list.push(block);
this.children.set(block.parent, list);
}
for (const list of this.children.values())
list.sort((a, b) =>
a.key < b.key ? -1 : a.key > b.key ? 1 : a.id < b.id ? -1 : 1
);
}
private prefix(): string {
const parts = this.doc.getMap(WORD_CONTAINERS.parts);
for (const name of parts.keys()) {
if (!name.endsWith('document.xml') && !name.endsWith('document2.xml'))
continue;
const shell = parts.get(name);
if (typeof shell !== 'string') continue;
const match = new RegExp(
`xmlns:(\\w+)="${WORDML_NS.replace(/[./]/g, '\\$&')}"`
).exec(shell);
if (match) return match[1];
}
return 'w';
}
/** Children of a block (`''` for the body), in order. */
kids(parent: string): WordBlock[] {
return this.children.get(parent) ?? [];
}
/** A part's text by name (with or without the leading slash). */
part(name: string): string | undefined {
const parts = this.doc.getMap(WORD_CONTAINERS.parts);
const value = parts.get(`/${name}`) ?? parts.get(name);
return typeof value === 'string' ? value : undefined;
}
text(block: WordBlock): LoroText {
const value = block.map.get('t');
if (value instanceof LoroText) return value;
return block.map.setContainer('t', new LoroText());
}
spans(block: WordBlock): Span[] {
return this.text(block).toDelta() as Span[];
}
visible(block: WordBlock): Visible {
const out: Visible = { text: '', at: [], attrs: [] };
let index = 0;
for (const span of this.spans(block)) {
const attrs = span.attributes ?? {};
const skip = hidden(attrs);
for (const unit of span.insert) {
// Code units, as the shared text counts them.
for (let i = 0; i < unit.length; i++) {
if (!skip && unit !== OBJECT) {
out.text += unit[i];
out.at.push(index);
out.attrs.push(attrs);
}
index++;
}
}
}
return out;
}
/** The value of a property child (`pStyle`, `jc`...) of a block's XML. */
propVal(block: WordBlock, local: string): string | null {
const re = new RegExp(
`<${this.w}:${local}\\b[^>]*\\b${this.w}:val="([^"]*)"`
);
return re.exec(block.props)?.[1] ?? null;
}
hasProp(block: WordBlock, local: string): boolean {
return new RegExp(`<${this.w}:${local}[\\s>/]`).test(block.props);
}
/** Removes a block and everything in it. */
remove(block: WordBlock) {
const map = this.doc.getMap(WORD_CONTAINERS.blocks);
const walk = (b: WordBlock) => {
for (const kid of this.kids(b.id)) walk(kid);
map.delete(b.id);
this.blocks.delete(b.id);
};
walk(block);
this.reindex();
}
/** Adds a paragraph next to `anchor`. */
addParagraph(
anchor: WordBlock,
after: boolean,
props: string,
spans: Span[]
): WordBlock {
const siblings = this.kids(anchor.parent);
const index = siblings.indexOf(anchor);
const low = after ? anchor.key : (siblings[index - 1]?.key ?? null);
const high = after ? (siblings[index + 1]?.key ?? null) : anchor.key;
const [key] = keysBetween(low || null, high || null, 1);
const id = newBlockId();
const map = this.doc
.getMap(WORD_CONTAINERS.blocks)
.setContainer(id, new LoroMap());
map.set('k', 'p');
map.set('p', anchor.parent);
map.set('o', key);
map.set('a', '');
map.set('x', props);
const text = map.setContainer('t', new LoroText());
if (spans.length) text.applyDelta(spans);
const block: WordBlock = {
id,
kind: 'p',
parent: anchor.parent,
key,
props,
map,
};
this.blocks.set(id, block);
this.reindex();
return block;
}
setProps(block: WordBlock, props: string) {
block.map.set('x', props);
block.props = props;
}
private commentsById?: Map<string, WordComment>;
/** The document's Word comments, by id. */
comments(): Map<string, WordComment> {
this.commentsById ??= readWordComments(this.doc);
return this.commentsById;
}
/** Whether the document records edits as tracked changes. */
tracksChanges(): boolean {
return tracksRevisions(this.part('word/settings.xml'));
}
/** Paragraphs inside a block (itself, for a paragraph), in order. */
paragraphsIn(block: WordBlock): WordBlock[] {
if (block.kind === 'p') return [block];
return this.kids(block.id).flatMap((kid) => this.paragraphsIn(kid));
}
}
/** A fresh block id in the engine's style (base 36), unlikely to collide. */
function newBlockId(): string {
const bytes = new Uint8Array(8);
crypto.getRandomValues(bytes);
let n = 0n;
for (const b of bytes) n = (n << 8n) | BigInt(b);
return `g${n.toString(36)}`;
}
/** Whether the document is in the engine's shared format. */
export function isWordFormat(doc: LoroDoc): boolean {
return (
doc.getMap(WORD_CONTAINERS.meta).get('formatVersion') ===
WORD_FORMAT_VERSION
);
}
/** The run formatting an agent can change, as mark keys and values. */
export function formatMarks(
w: string,
format: {
bold?: boolean;
italic?: boolean;
underline?: boolean;
strikethrough?: boolean;
}
): Attributes {
const marks: Attributes = {};
const flag = (local: string, value: boolean | undefined) => {
if (value === undefined) return;
marks[`r:${w}:${local}`] = value
? `<${w}:${local}/>`
: `<${w}:${local} ${w}:val="0"/>`;
};
flag('b', format.bold);
flag('i', format.italic);
flag('strike', format.strikethrough);
if (format.underline !== undefined)
marks[`r:${w}:u`] =
`<${w}:u ${w}:val="${format.underline ? 'single' : 'none'}"/>`;
return marks;
}
/** Which of the four toggles a character's marks turn on. */
export function formatOf(w: string, attrs: Attributes) {
return {
bold: on(attrs[`r:${w}:b`]),
italic: on(attrs[`r:${w}:i`]),
underline: on(attrs[`r:${w}:u`]),
strikethrough: on(attrs[`r:${w}:strike`]),
};
}
/** The formatting text typed in place of other text takes: its run
* properties and wrappers, not object or marker keys. */
export function typingAttributes(attrs: Attributes | undefined): Attributes {
const out: Attributes = {};
for (const [key, value] of Object.entries(attrs ?? {}))
if (key.startsWith('r:') || key.startsWith('ra:') || key === 'wrap')
out[key] = value;
return out;
}
const quote = (text: string) => `"${preview(text, 60)}"`;
const KINDS = ['bold', 'italic', 'underline', 'strikethrough'] as const;
/** Formatted spans worth telling a reader about, e.g. `bold: "Agreement"`. */
function formattingNotes(word: WordDocument, visible: Visible): string[] {
const spans: Record<(typeof KINDS)[number], string[]> = {
bold: [],
italic: [],
underline: [],
strikethrough: [],
};
const open: Partial<Record<(typeof KINDS)[number], string>> = {};
const n = visible.text.length;
for (let i = 0; i < n; i++) {
const format = formatOf(word.w, visible.attrs[i]);
for (const kind of KINDS) {
if (format[kind]) open[kind] = (open[kind] ?? '') + visible.text[i];
if ((!format[kind] || i === n - 1) && open[kind]) {
if (open[kind]!.trim()) spans[kind].push(open[kind]!);
open[kind] = undefined;
}
}
}
return KINDS.flatMap((kind) => {
const list = spans[kind];
if (list.length === 0) return [];
if (list.length === 1 && list[0] === visible.text) return [`${kind}: all`];
const shown = list.slice(0, 6).map(quote).join(', ');
return [`${kind}: ${shown}${list.length > 6 ? ', …' : ''}`];
});
}
const COMMENT_MARK =
/<[\w]*:?(commentRangeStart|commentRangeEnd|commentReference)\b[^>]*:id="([^"]*)"/;
/** Where Word comments sit in a paragraph's visible text. */
class CommentRanges {
readonly starts = new Map<string, number>();
readonly ends = new Map<string, number>();
readonly order: string[] = [];
/** Notes a comment marker found at visible offset `at`. */
see(markup: string, at: number) {
const found = COMMENT_MARK.exec(markup);
if (!found) return;
const [, kind, id] = found;
if (kind === 'commentRangeEnd') this.ends.set(id, at);
else if (!this.starts.has(id)) {
this.starts.set(id, at);
this.order.push(id);
}
}
/** `comment 3 by Jane Doe on "Term": ...` for each known comment. */
notes(comments: Map<string, WordComment>, text: string): string[] {
return this.order.flatMap((id) => {
const comment = comments.get(id);
if (!comment) return [];
const from = this.starts.get(id);
const anchor = text.slice(from, this.ends.get(id) ?? from).trim();
const body = preview(comment.text.replace(/\n/g, ' '), 300);
return [
`comment ${id} by ${comment.author || 'unknown author'}${anchor ? ` on ${quote(anchor)}` : ''}: ${body}`,
];
});
}
}
/** The tracked change a span of text is part of, with its author. */
function spanRevision(
attrs: Attributes
): { kind: string; author: string | null } | null {
const stack: Wrapper[] = wrappersOf(attrs);
const deleted = stack.find(isDeleted);
if (deleted)
return { kind: 'deleted', author: tagAttribute(deleted[0], 'author') };
const inserted = stack.find(isInserted);
if (inserted)
return { kind: 'inserted', author: tagAttribute(inserted[0], 'author') };
const change = Object.entries(attrs).find(([k]) =>
k.endsWith(':rPrChange')
)?.[1];
return change
? { kind: 'formatting changed', author: tagAttribute(change, 'author') }
: null;
}
/** Tracked changes and Word comments in a paragraph, e.g.
* `deleted by Jane Doe: "two (2)"` or `comment 3 by Jane Doe on "Term": ...`. */
function annotationNotes(word: WordDocument, block: WordBlock): string[] {
type Run = { kind: string; author: string; text: string };
const runs: Run[] = [];
const ranges = new CommentRanges();
let text = '';
for (const span of word.spans(block)) {
const attrs = span.attributes ?? {};
const markup = attrs.mark ?? attrs.obj;
if (markup) ranges.see(markup, text.length);
const content = span.insert.split(OBJECT).join('');
if (markup || 'instr' in attrs || !content) continue;
const revision = spanRevision(attrs);
if (revision) {
const author = revision.author || 'unknown author';
const last = runs[runs.length - 1];
if (last?.kind === revision.kind && last.author === author)
last.text += content;
else runs.push({ kind: revision.kind, author, text: content });
}
// Deleted text is not part of what the paragraph now says.
if (revision?.kind !== 'deleted') text += content;
}
const notes = runs
.filter((run) => run.text.trim())
.slice(0, 12)
.map((run) => `${run.kind} by ${run.author}: ${quote(run.text)}`);
if (runs.length > 12) notes.push('… more tracked changes');
return [...notes, ...ranges.notes(word.comments(), text)];
}
/** Tracked changes to a paragraph itself: its mark and its properties. */
function paragraphRevision(block: WordBlock): string | null {
const mark = markRevision(block.props);
if (mark)
return mark.inserted
? `inserted paragraph by ${mark.author || 'unknown author'}`
: `paragraph mark deleted by ${mark.author || 'unknown author'}`;
const change = /<[\w]*:?pPrChange\b[^>]*>/.exec(block.props)?.[0];
if (change)
return `properties changed by ${tagAttribute(change, 'author') || 'unknown author'}`;
return null;
}
function paragraphLines(
word: WordDocument,
block: WordBlock,
label: string,
indent: string
): string[] {
const traits = [
word.propVal(block, 'pStyle'),
word.propVal(block, 'jc'),
word.hasProp(block, 'numPr') ? 'numbered' : null,
paragraphRevision(block),
].filter(Boolean);
const visible = word.visible(block);
const text = visible.text.replace(/\n/g, '↵');
const head = `${indent}${label}paragraph ${block.id}${traits.length ? ` (${traits.join(', ')})` : ''}`;
const notes = [
...(text ? formattingNotes(word, visible) : []),
...annotationNotes(word, block),
].map((note) => `${indent} ${note}`);
if (!text) return [`${head} (empty)`, ...notes];
return [head, `${indent} ${text}`, ...notes];
}
function contentLines(
word: WordDocument,
parent: string,
indent: string
): string[] {
return word
.kids(parent)
.flatMap((block) => blockLines(word, block, '', indent));
}
function blockLines(
word: WordDocument,
block: WordBlock,
label: string,
indent: string
): string[] {
switch (block.kind) {
case 'p':
return paragraphLines(word, block, label, indent);
case 'tbl': {
const rows = word.kids(block.id).filter((r) => r.kind === 'tr');
const columns = Math.max(
0,
...rows.map(
(r) => word.kids(r.id).filter((c) => c.kind === 'tc').length
)
);
const lines = [
`${indent}${label}table ${block.id}, ${rows.length} rows x ${columns} columns`,
];
rows.forEach((row, r) => {
word
.kids(row.id)
.filter((c) => c.kind === 'tc')
.forEach((cell, c) => {
lines.push(`${indent} row ${r + 1}, cell ${c + 1}:`);
lines.push(...contentLines(word, cell.id, `${indent} `));
});
});
return lines;
}
case 'sdt': {
const title =
/:(?:alias|tag|docPartGallery)\b[^>]*:val="([^"]*)"/.exec(
block.props
)?.[1] ?? null;
return [
`${indent}${label}content control ${block.id}${title ? ` (${title})` : ''}`,
...contentLines(word, block.id, `${indent} `),
];
}
default:
// Bookmarks and other markers between paragraphs carry no content.
return [];
}
}
function styles(word: WordDocument): ParagraphStyleInfo[] {
return paragraphStylesFromXml(word.part('word/styles.xml'));
}
/** The document as text an agent can act on: every block with its id. */
export function describeWord(
doc: LoroDoc,
options: { start?: number; count?: number } = {}
): string {
const word = new WordDocument(doc);
const top = word.kids('');
const start = Math.max(1, Math.floor(options.start ?? 1));
const end = Math.min(
top.length,
options.count
? start - 1 + Math.max(1, Math.floor(options.count))
: Infinity
);
const all = styles(word);
const used = new Set<string>();
const body: string[] = [];
let size = 0;
let next: number | null = null;
for (let number = start; number <= end; number++) {
const block = top[number - 1];
const lines = blockLines(word, block, `#${number} `, '');
const length = lines.reduce((sum, line) => sum + line.length + 1, 0);
if (size + length > READ_BUDGET && body.length > 0) {
next = number;
break;
}
size += length;
body.push(...lines);
for (const line of lines) {
const style = /^\s*(?:#\d+ )?paragraph \S+ \(([^,)]+)/.exec(line)?.[1];
if (style) used.add(style);
}
}
const styleList = [
...all.filter((s) => used.has(s.id)),
...all.filter((s) => !used.has(s.id)),
]
.slice(0, 40)
.map((s) => s.id);
const header = [
`Word document with ${top.length} blocks${start > 1 || end < top.length ? `; showing #${start}-#${next ? next - 1 : end}` : ''}.`,
'Ids are stable: pass them to EditWordDocument. Text is shown plain, as if tracked changes were accepted; lines like `bold: "..."` list formatted spans, `inserted by`/`deleted by` lines list tracked changes and `comment` lines list Word comments. ↵ is a line break inside a paragraph.',
word.tracksChanges()
? 'Track Changes is on: edits are recorded as tracked changes unless trackChanges is false.'
: 'Track Changes is off: edits apply directly unless trackChanges is true (use true for a redline).',
...(styleList.length
? [
`Paragraph styles: ${styleList.join(', ')}${all.length > 40 ? ', …' : ''}.`,
]
: []),
'',
];
const footer = next
? [
'',
`… ${top.length - next + 1} more blocks. Read again with start=${next} to continue.`,
]
: [];
return [...header, ...body, ...footer].join('\n');
}
/** The top-level block holding a block. */
function topOf(word: WordDocument, block: WordBlock): WordBlock {
let at = block;
while (at.parent) {
const parent = word.blocks.get(at.parent);
if (!parent) break;
at = parent;
}
return at;
}
/** Paragraph properties without what belongs to that paragraph alone: its
* section break and recorded changes. */
function copiedProps(props: string): string {
return props
.replace(/<(\w+:)?sectPr\b[\s\S]*?<\/\1?sectPr>/g, '')
.replace(/<(\w+:)?sectPr\b[^>]*\/>/g, '')
.replace(/<(\w+:)?pPrChange\b[\s\S]*?<\/\1?pPrChange>/g, '')
.replace(/<(\w+:)?(ins|del)\b[^>]*\/>/g, '');
}
/** `w:pPr` XML naming a style, from a paragraph's properties. */
function withStyle(w: string, props: string, style: string): string {
const tag = `<${w}:pStyle ${w}:val="${style}"/>`;
if (!props.trim()) return `<${w}:pPr>${tag}</${w}:pPr>`;
if (new RegExp(`<${w}:pStyle\\b`).test(props))
return props.replace(new RegExp(`<${w}:pStyle\\b[^>]*/>`), tag);
if (/\/>\s*$/.test(props) && !props.includes('</'))
return props.replace(/\s*\/>\s*$/, `>${tag}</${w}:pPr>`);
// pStyle is the first property in schema order.
return props.replace(/^(\s*<[^>]+>)/, `$1${tag}`);
}
/** A stored range of a paragraph's text as its spans. */
function segments(
spans: Span[],
from: number,
to: number
): Array<{ length: number; attrs: Attributes }> {
const out: Array<{ length: number; attrs: Attributes }> = [];
let at = 0;
for (const span of spans) {
const end = at + span.insert.length;
const start = Math.max(at, from);
const stop = Math.min(end, to);
if (stop > start)
out.push({ length: stop - start, attrs: span.attributes ?? {} });
at = end;
if (at >= to) break;
}
return out;
}
class WordEditor {
readonly touched = new Set<string>();
readonly deleted: string[] = [];
/** Ids of the comments this edit added. */
readonly commented: string[] = [];
private readonly styles: ParagraphStyleInfo[];
private readonly comments: WordCommentWriter;
constructor(
readonly word: WordDocument,
/** Records the edit as tracked changes; `null` edits directly. */
private readonly rev: Revisor | null,
private readonly author: string,
private readonly date: string
) {
this.styles = styles(word);
this.comments = new WordCommentWriter(word.doc);
}
/** Writes what the edit adds outside the blocks (the comments part). */
finish() {
this.comments.flush();
}
private block(id: string): WordBlock {
const found = this.word.blocks.get(id);
if (!found)
throw new DocxAgentError(
`No paragraph or block has id ${id}. Read the document again for current ids.`
);
return found;
}
private paragraph(id: string): WordBlock {
const found = this.block(id);
if (found.kind !== 'p')
throw new DocxAgentError(
`${id} is a ${describeKind(found.kind)}, not a paragraph. Address the paragraphs inside it.`
);
return found;
}
private changed(block: WordBlock) {
this.touched.add(topOf(this.word, block).id);
}
/** The visible range `[start, end)` an operation addresses. */
private range(
block: WordBlock,
visible: Visible,
find: string | undefined,
occurrence: number | undefined
): [number, number] {
const text = visible.text;
if (find === undefined) return [0, text.length];
const matches = occurrences(text, find);
if (matches.length === 0)
throw new DocxAgentError(
`"${preview(find, 80)}" does not appear in paragraph ${block.id}, whose text is: "${preview(text)}"`
);
if (occurrence === undefined && matches.length > 1)
throw new DocxAgentError(
`"${preview(find, 80)}" appears ${matches.length} times in paragraph ${block.id}; pass occurrence (1-${matches.length}) or a longer find.`
);
const index = (occurrence ?? 1) - 1;
if (index < 0 || index >= matches.length)
throw new DocxAgentError(
`Paragraph ${block.id} has ${matches.length} occurrence(s) of "${preview(find, 80)}"; occurrence ${occurrence} is out of range.`
);
return [matches[index], matches[index] + find.length];
}
/** Stored offsets of a visible range (hidden text inside it goes too). */
private stored(
visible: Visible,
start: number,
end: number
): [number, number] {
if (start === end) {
const at =
start < visible.at.length
? visible.at[start]
: (visible.at[visible.at.length - 1] ?? -1) + 1;
return [at, at];
}
return [visible.at[start], visible.at[end - 1] + 1];
}
/** Replaces visible text `[start, end)` with `text`, formatted like the
* text it replaces (or the text before it). */
private replace(block: WordBlock, start: number, end: number, text: string) {
const visible = this.word.visible(block);
const [from, to] = this.stored(visible, start, end);
const like = visible.attrs[start] ?? visible.attrs[start - 1];
const delta: Array<Record<string, unknown>> = [];
if (from > 0) delta.push({ retain: from });
if (this.rev) {
// A tracked replacement: the old text is marked deleted and the new
// text follows it as the author's insertion.
this.markDeleted(block, from, to, delta);
if (text)
delta.push({
insert: text,
attributes: this.rev.inserted(
typingAttributes(like),
this.rev.wrapper('ins')
),
});
} else {
if (to > from) delta.push({ delete: to - from });
if (text) {
const attributes = typingAttributes(like);
delta.push(
Object.keys(attributes).length
? { insert: text, attributes }
: { insert: text }
);
}
}
if (delta.length) this.word.text(block).applyDelta(delta as never);
this.changed(block);
}
/** Appends to `delta` the operations marking stored `[from, to)` deleted
* by the author: text the author inserted is removed outright, while
* text already deleted and markers (bookmarks, comment ranges) stay. */
private markDeleted(
block: WordBlock,
from: number,
to: number,
delta: Array<Record<string, unknown>>
) {
const rev = this.rev!;
if (to <= from) return;
const del = rev.wrapper('del');
for (const { length, attrs } of segments(
this.word.spans(block),
from,
to
)) {
const stack = wrappersOf(attrs);
const deleted = stack.some(isDeleted);
if (!deleted && stack.some((w) => rev.owns(w))) {
delta.push({ delete: length });
} else if (deleted || 'mark' in attrs) {
delta.push({ retain: length });
} else {
delta.push({
retain: length,
attributes: { wrap: encodeWrappers([...stack, del]) },
});
}
}
}
private static singleLine(text: string, what: string) {
if (/[\r\n]/.test(text))
throw new DocxAgentError(
`${what} cannot contain a line break; use insertParagraph to add paragraphs.`
);
}
private resolveStyle(style: string): string {
const found = findStyle(this.styles, style);
if (!found)
throw new DocxAgentError(
`The document has no paragraph style "${style}". Its paragraph styles are: ${this.styles
.map((s) => s.id)
.join(', ')}.`
);
return found;
}
apply(operation: DocxAgentOperation) {
switch (operation.type) {
case 'replaceText': {
WordEditor.singleLine(operation.replace, 'replace');
if (!operation.find)
throw new DocxAgentError('find must not be empty.');
const block = this.paragraph(operation.paragraph);
const visible = this.word.visible(block);
const [start, end] = this.range(
block,
visible,
operation.find,
operation.occurrence
);
this.replace(block, start, end, operation.replace);
return;
}
case 'setText': {
WordEditor.singleLine(operation.text, 'text');
const block = this.paragraph(operation.paragraph);
const visible = this.word.visible(block);
this.replace(block, 0, visible.text.length, operation.text);
return;
}
case 'formatText': {
const { bold, italic, underline, strikethrough } = operation;
if (
[bold, italic, underline, strikethrough].every((v) => v === undefined)
)
throw new DocxAgentError(
'formatText needs at least one of bold, italic, underline or strikethrough.'
);
const block = this.paragraph(operation.paragraph);
const visible = this.word.visible(block);
const [start, end] = this.range(
block,
visible,
operation.find,
operation.occurrence
);
if (start === end) return;
const [from, to] = this.stored(visible, start, end);
const attributes = formatMarks(this.word.w, {
bold,
italic,
underline,
strikethrough,
});
const delta: Array<Record<string, unknown>> = [];
if (from > 0) delta.push({ retain: from });
if (this.rev) {
// Each run keeps the formatting it had in a w:rPrChange.
const key = `r:${this.word.w}:rPrChange`;
for (const segment of segments(this.word.spans(block), from, to)) {
const change = this.rev.formatChange(segment.attrs, {
...segment.attrs,
...attributes,
});
delta.push({
retain: segment.length,
attributes: change
? { ...attributes, [key]: change }
: attributes,
});
}
} else delta.push({ retain: to - from, attributes });
this.word.text(block).applyDelta(delta as never);
this.changed(block);
return;
}
case 'insertParagraph':
this.insert(operation);
return;
case 'delete':
this.delete(operation.id);
return;
case 'setStyle': {
const block = this.paragraph(operation.paragraph);
const style = this.resolveStyle(operation.style);
const props = withStyle(this.word.w, block.props, style);
this.word.setProps(
block,
this.rev
? withParagraphChange(this.word.w, block.props, props, this.rev)
: props
);
this.changed(block);
return;
}
case 'addComment':
this.comment(operation);
return;
}
}
/** Adds a Word comment: the comment in the comments part, its range
* markers around the text and its reference after it. */
private comment(
operation: Extract<DocxAgentOperation, { type: 'addComment' }>
) {
if (!operation.text.trim())
throw new DocxAgentError('addComment needs comment text.');
const block = this.paragraph(operation.paragraph);
const visible = this.word.visible(block);
const [start, end] = this.range(
block,
visible,
operation.find,
operation.occurrence
);
const [from, to] = this.stored(visible, start, end);
const id = this.comments.add(this.author, this.date, operation.text);
this.commented.push(id);
const w = this.word.w;
const marker = (local: string) => ({
insert: OBJECT,
attributes: { mark: `<${w}:${local} ${w}:id="${id}"/>` },
});
const delta: Array<Record<string, unknown>> = [];
if (from > 0) delta.push({ retain: from });
delta.push(marker('commentRangeStart'));
if (to > from) delta.push({ retain: to - from });
delta.push(marker('commentRangeEnd'), {
insert: OBJECT,
attributes: { obj: `<${w}:commentReference ${w}:id="${id}"/>` },
});
this.word.text(block).applyDelta(delta as never);
this.changed(block);
}
/** Paragraph properties for a paragraph added next to `anchor`. */
private newProps(anchor: WordBlock, style: string | undefined): string {
const w = this.word.w;
if (style !== undefined) return withStyle(w, '', this.resolveStyle(style));
if (anchor.kind !== 'p') return '';
// As Word does on Enter: a style that names a different next style (a
// heading, say) is followed by that style; any other paragraph is copied.
const current = this.word.propVal(anchor, 'pStyle');
const info = current
? this.styles.find((s) => s.id === current)
: undefined;
if (info?.next && info.next !== info.id) {
const next = this.styles.find((s) => s.id === info.next);
return next?.isDefault ? '' : withStyle(w, '', info.next);
}
return copiedProps(anchor.props);
}
private insert(
operation: Extract<DocxAgentOperation, { type: 'insertParagraph' }>
) {
const anchorId = operation.after ?? operation.before;
if (!anchorId || (operation.after && operation.before))
throw new DocxAgentError(
'insertParagraph needs exactly one of after or before.'
);
const anchor = this.block(anchorId);
if (anchor.kind === 'tr' || anchor.kind === 'tc')
throw new DocxAgentError(
`${anchorId} is a table ${anchor.kind === 'tr' ? 'row' : 'cell'}; insert next to a paragraph or the table instead.`
);
const props = this.newProps(anchor, operation.style);
// New text is formatted like the anchor's first character.
const like =
anchor.kind === 'p' && operation.style === undefined
? typingAttributes(this.word.visible(anchor).attrs[0])
: {};
const lines = operation.text.replace(/\r\n?/g, '\n').split('\n');
const after = operation.after !== undefined;
let at = anchor;
const ordered = after ? lines : [...lines].reverse();
for (const line of ordered) {
const rev = this.rev;
// Tracked: the text and the paragraph mark are the author's insertion.
const attributes = rev ? rev.inserted(like, rev.wrapper('ins')) : like;
const spans = line
? [
Object.keys(attributes).length
? { insert: line, attributes }
: { insert: line },
]
: [];
const markProps = rev
? withMarkRevision(this.word.w, props, rev.mark('ins'))
: props;
at = this.word.addParagraph(at, after, markProps, spans);
this.changed(at);
}
}
private delete(id: string) {
const block = this.block(id);
if (this.rev && block.kind !== 'tr' && block.kind !== 'tc') {
this.deleteTracked(block, this.rev);
return;
}
if (!block.parent) {
if (this.word.kids('').length === 1)
throw new DocxAgentError(
'The document must keep at least one block; use setText to clear it instead.'
);
this.word.remove(block);
this.touched.delete(block.id);
this.deleted.push(block.id);
return;
}
const parent = this.word.blocks.get(block.parent);
if (
parent?.kind === 'tc' &&
!this.word
.kids(parent.id)
.some((b) => b.id !== block.id && (b.kind === 'p' || b.kind === 'tbl'))
)
throw new DocxAgentError(
`Paragraph ${id} is the only paragraph in its table cell; use setText with empty text to clear it.`
);
const top = topOf(this.word, block);
this.word.remove(block);
this.touched.add(top.id);
}
/** Deletes a block as a tracked change: its paragraphs' text and marks
* are marked deleted (and a table's rows), so the deletion can be
* accepted or rejected. Markers with no content go outright. */
private deleteTracked(block: WordBlock, rev: Revisor) {
if (block.kind !== 'p' && block.kind !== 'tbl' && block.kind !== 'sdt') {
const top = topOf(this.word, block);
this.word.remove(block);
if (top === block) this.deleted.push(block.id);
else this.touched.add(top.id);
return;
}
const top = topOf(this.word, block);
if (block.kind === 'tbl')
for (const row of this.word.kids(block.id).filter((r) => r.kind === 'tr'))
this.word.setProps(row, withRowDeleted(this.word.w, row.props, rev));
for (const paragraph of this.word.paragraphsIn(block))
this.deleteParagraphTracked(paragraph, rev);
if (this.word.blocks.has(top.id)) this.touched.add(top.id);
else this.deleted.push(top.id);
}
private deleteParagraphTracked(block: WordBlock, rev: Revisor) {
const length = this.word.text(block).length;
const delta: Array<Record<string, unknown>> = [];
this.markDeleted(block, 0, length, delta);
if (delta.length) this.word.text(block).applyDelta(delta as never);
const mark = markRevision(block.props);
if (mark && !mark.inserted) return;
if (mark?.inserted && mark.author === rev.author) {
// A paragraph the author added and nothing else is in goes outright
// (the document keeps at least one block).
const only = !block.parent && this.word.kids('').length === 1;
if (this.word.text(block).length === 0 && !only) this.word.remove(block);
return;
}
// The last paragraph of a cell or the document keeps its mark.
const siblings = this.word
.kids(block.parent)
.filter((b) => b.kind === 'p' || b.kind === 'tbl' || b.kind === 'sdt');
if (siblings[siblings.length - 1] === block) return;
this.word.setProps(
block,
withMarkRevision(this.word.w, block.props, rev.mark('del'))
);
}
}
function describeKind(kind: string): string {
switch (kind) {
case 'tbl':
return 'table';
case 'tr':
return 'table row';
case 'tc':
return 'table cell';
case 'sdt':
return 'content control';
default:
return 'block';
}
}
/** How an edit is recorded. */
export type WordEditOptions = {
/** Record tracked changes; omitted to follow the document's setting. */
trackChanges?: boolean;
/** The name tracked changes and comments are attributed to. */
author?: string;
/** When the edit is made (tests pin it). */
now?: Date;
};
/** The author Word shows when none is given, as the engine does. */
const DEFAULT_AUTHOR = 'Author';
/**
* Applies `operations` to the shared document in one commit and describes
* the blocks they changed. Any failure throws before anything is committed;
* the caller drops the document then, so nothing reaches anyone.
*/
export function editWord(
doc: LoroDoc,
operations: readonly DocxAgentOperation[],
options: WordEditOptions = {}
): string {
if (operations.length === 0 || operations.length > MAX_DOCX_OPERATIONS)
throw new DocxAgentError(
`Send between 1 and ${MAX_DOCX_OPERATIONS} operations.`
);
const word = new WordDocument(doc);
const author = options.author?.trim() || DEFAULT_AUTHOR;
const date = revisionDate(options.now);
const tracked = options.trackChanges ?? word.tracksChanges();
const editor = new WordEditor(
word,
tracked ? new Revisor(word.w, author, date) : null,
author,
date
);
operations.forEach((operation, index) => {
try {
editor.apply(operation);
} catch (error) {
if (error instanceof DocxAgentError)
throw new DocxAgentError(
`Operation ${index + 1} (${operation.type}) failed, so nothing was changed: ${error.message}`
);
throw error;
}
});
editor.finish();
doc.commit({ origin: 'docx-agent' });
// How the changed blocks read now, for the agent to check.
const after = new WordDocument(doc);
const top = after.kids('');
const count = operations.length;
const edits = operations.filter((o) => o.type !== 'addComment').length;
const lines = [
`Applied ${count} operation${count === 1 ? '' : 's'}. Everyone with the document open sees the change now.`,
];
if (edits)
lines.push(
tracked
? `Edits are tracked changes by ${author}, which can be accepted or rejected in Word.`
: 'Edits were applied directly, not as tracked changes.'
);
if (editor.commented.length)
lines.push(
`Added Word comment${editor.commented.length === 1 ? '' : 's'} ${editor.commented.join(', ')} by ${author}; they are saved in the file.`
);
if (editor.deleted.length)
lines.push(`Deleted blocks: ${editor.deleted.join(', ')}.`);
const touched = top.filter((b) => editor.touched.has(b.id));
if (touched.length) {
lines.push('', 'Changed blocks as they now read:');
let size = 0;
for (const block of touched) {
const shown = blockLines(after, block, `#${top.indexOf(block) + 1} `, '');
size += shown.join('\n').length;
if (size > READ_BUDGET) {
lines.push('… (more changed blocks; read the document to see them)');
break;
}
lines.push(...shown);
}
}
return lines.join('\n');
}