New

docx-editor 1.x has shipped. Vue support, i18n, agents. Read the migration guide →

Agent framework

Agents. Word JS API parity

Office.js verb mapping. Migrating a Word add-in to this toolkit is a rename. Parity is enforced at compile time.

Why parity matters

The toolkit shadows the shape of Microsoft's Office.js Word API on purpose. If your model has been trained on Office.js examples, it picks up our tools without re-prompting. If you're migrating a Word add-in, the rename map below is the only diff.

WordCompatBridge is a TypeScript type alias that formally documents every method we mirror. A compile-time static assertion fails the build if a method goes out of sync.

Verb map

Office.jsDOCX Editor toolkitNotes
Range.insertComment(text)addComment({ paraId, text })We address by stable paraId, not by Range.
Body.search(query)findText({ query })Returns paragraphs with paraIds.
Comment.reply(text)replyComment({ commentId, text })
Comment.resolved = trueresolveComment({ commentId })
Range.scrollIntoView()scroll({ paraId })
Range.insertText(text, location)suggestChange({ paraId, ... })Inserts as a tracked change.
Range.font.bold = trueapplyFormatting({ paraId, bold: true })
Range.paragraphFormat.styleName = "Heading 1"setParagraphStyle({ paraId, style: "Heading1" })

Addressing model

Office.js uses Range objects that are live and tied to a document model. JSON-RPC tool transports can't ferry live objects, they need a string ID that survives serialization, network round-trips, and concurrent edits.

The toolkit uses Word's w14:paraId attribute. Every paragraph in a Word-authored .docx has one. They're stable across edits, concurrent collaboration, and tool loop iterations. read_document returns paragraphs tagged with their paraId; every mutate tool takes a paraId as input.

Migrating a Word add-in

  1. Replace Word.run(async (context) => { ... }) with a DocxReviewer.fromBuffer(buffer) (headless) or useDocxAgentTools({ editorRef }) (live editor) wiring.
  2. Replace Range-based addressing with paraId-based addressing. Use findText or read_document to resolve a paragraph first.
  3. Replace each Office.js method call with its tool equivalent from the table above.

For agents you're writing fresh, you don't need this mapping at all, just call the tools directly.

Where to go next