SuperDoc

Browser-Based Contract Redlining: Tracked Changes, Document Comparison and Content Controls

Browser-Based Contract Redlining: Tracked Changes, Document Comparison and Content Controls

For a legal-tech or contract lifecycle management product, redlining is not a feature you can approximate. The counterparty’s lawyer will open the document in Microsoft Word. If your product’s proposed changes do not appear there as real Word tracked changes, attributed to the right person and acceptable or rejectable one by one, your product has failed at the moment that matters most.

That is a hard requirement for a browser-based editor. In our view, a generic rich-text editor that converts the document to HTML and back cannot meet it reliably, and an editor that works on the DOCX format itself can.

This article looks at how to build browser-based contract redlining with SuperDoc, a DOCX editor that you embed as a Word document editor in your web app. SuperDoc’s editor code is open source under AGPLv3, while its DOCX Engine is a separately licensed, proprietary component. We introduced SuperDoc in What Is SuperDoc?. Here we go deeper into four capabilities a redlining product needs: suggesting mode, document comparison, content controls for templates, and legal-specific structures. We are equally direct about the current limitations. Facts about SuperDoc come from its documentation and release notes, checked on 9 October 2026. SuperDoc ships frequently, so check the current documentation before you build. The design recommendations are ours.

Suggesting Mode: Every Edit Becomes a Tracked Change

SuperDoc has three document modes:

Mode What happens Use it when
editing “The text changes directly.” “Changes should become part of the document.”
suggesting “The edit becomes a tracked change.” “Another person should review the proposed change.”
viewing “Editing is disabled.” “A person should read without changing the DOCX.”

Setting up a reviewer takes two things, the mode and the user:

import type { Config } from 'superdoc';

export const reviewOptions = {
  documentMode: 'suggesting',
  user: {
    name: 'Jordan Lee',
    email: 'jordan@example.com',
  },
} satisfies Pick<Config, 'documentMode' | 'user'>;

“The user value identifies the author of the tracked change.” SuperDoc’s documentation adds that “Your application supplies the signed-in user’s identity instead of this example user. You do not need to enable tracking separately.” The mode can also be changed at run time with superdoc.setDocumentMode('viewing').

Reviewing proposals

Reviewers accept or reject changes in the built-in interface. SuperDoc’s documentation describes the two decisions: Accept “Keeps the proposed result and removes its revision mark.” Reject “Removes the proposed edit and its revision mark. For a deletion, the original text returns.” Your application can also decide changes through the Document API, guarded by the document revision it last read:

const decisionReceipt = await doc.trackChanges.decide(
  { decision: 'accept', target: { kind: 'id', id: detail.id } },
  { expectedRevision: changes.evaluatedRevision },
);

A few behaviours matter for legal workflows:

  • Display is not decision. The viewing options original, markup and final “only change the display. The proposal remains in the DOCX.” In SuperDoc’s words: “A clean-looking final view is not an accepted document.”
  • Export does not resolve anything. “Exporting does not accept pending changes.” The counterparty receives the proposals as tracked changes, which is exactly what you want.
  • You can separate proposing from deciding. Setting interaction.trackedChanges.allowDecisions to false lets a user propose changes without being able to accept or reject them. But SuperDoc is explicit that “Browser controls are not an authorization boundary: protect document access and saving on your backend.”

Comments that survive the round trip

Negotiation happens in comments as much as in changes. SuperDoc stores them in the document: “Comments, replies, authors, and resolved status are stored in the DOCX.” Its documentation recommends confirming the round trip by exporting, opening the file in Word and checking that the thread, its replies and the resolved status are intact. Note that “Resolving a thread is not deleting it.”

Document Comparison That Produces Tracked Changes

Contract workflows constantly need comparison: the counterparty’s returned draft against the version you sent, or a negotiated contract against your standard template. The useful output is not a separate report but a document in which the differences appear as tracked changes.

SuperDoc’s Document API supports this. “The workflow is diff.capture on the target, diff.compare against the base, then diff.apply with changeMode: 'tracked'”:

const targetSnapshot = await targetDoc.diff.capture();

const diff = await baseDoc.diff.compare({ targetSnapshot });

const trackedEligibility = diff.applyEligibility?.tracked;
if (trackedEligibility?.status !== 'candidate') {
  throw new Error(`Tracked apply is blocked: ${JSON.stringify(trackedEligibility?.blockers ?? [])}`);
}

const result = await baseDoc.diff.apply({ diff, changeMode: 'tracked' });

A recent release added word-level redlines: “Document comparison generates tracked changes at word granularity, matching Word’s native behavior.” Changes appear at word level, which matters a great deal to a lawyer reading the redline.

Comparison fails closed, and you should want it to

SuperDoc’s comparison is conservative by design: “an unsupported family fails the whole call closed, with no partial output and no mutation, rather than silently applying a broader replacement than requested.” For legal documents, a comparison that refuses is far better than one that quietly marks a whole section as replaced.

SuperDoc publishes a matrix of what is supported. In summary, as documented today:

  • Body text changes are supported in direct and tracked modes. So are verified run-formatting changes and tables, with eligibility “authoritative for the exact table shape”.
  • Header and footer content edits are supported in both modes. Header and footer structural changes are supported in direct mode only.
  • Existing footnote and endnote content is supported in both modes.
  • Documents that already contain pending revisions are supported “when the target revision set can be reconciled exactly”.
  • Images, fields and cross-references are supported in verified cases and can fail closed otherwise.
  • Content controls are not supported. “Unsupported: an SDT in the body currently fails the body family closed, including edits elsewhere in that body.”

SuperDoc notes that its matrix was verified against particular pre-release versions of its SDK and engine. Treat it as a guide and test against the release you deploy.

The Template Gotcha: Content Controls Stop Comparison

That last limitation deserves its own section, because it collides with the next capability.

Contract templates are usually built with Word content controls, the structured fields for party names, dates, amounts and optional clauses. In the DOCX they are w:sdt elements, and SuperDoc’s comparison matrix lists them as unsupported: a single one in the document body makes comparison of the whole body fail closed, including edits elsewhere in that body. Release v2.20.0 includes diff fixes involving inline content controls, so check whether this still applies to the release you deploy.

This is our analysis of how to design around it until SuperDoc’s support changes:

  • Decide per document type which workflow it needs. Templates that are filled and then negotiated may need comparison more than they need live controls during negotiation. Templates that are only ever filled may not need comparison at all.
  • Consider when controls are needed. Content controls are most valuable while a document is being generated and filled. Whether they need to remain during negotiation is a design question for your product.
  • Check eligibility before promising a redline. Use the applyEligibility result, as in the example above, to tell the user clearly when a comparison cannot be produced, rather than failing silently.
  • Track the releases. Content control support in comparison is the kind of capability that changes between releases. Re-test when you upgrade.

Content Controls for Template Fields

For generating and filling contracts, content controls are the right tool. “Content controls are stored as w:sdt elements in the DOCX. You do not need to edit that XML to use the Document API.” For typed inputs, SuperDoc supports “text, checkbox, date, and choice controls”, and it maps Word’s identifiers directly: Tag to properties.tag, Title to properties.alias and ID to id.

Inserting a field from your application:

import type { BrowserDocumentApi, SelectionTarget } from 'superdoc/ui';

export async function addClientNameField(doc: BrowserDocumentApi, selection: SelectionTarget) {
  return doc.create.contentControl({
    kind: 'inline',
    controlType: 'text',
    tag: 'client.legalName',
    alias: 'Client legal name',
    at: selection,
  });
}

Locking a field uses Word’s own lock modes: unlocked, sdtLocked (the control cannot be deleted), contentLocked (its contents cannot be edited) and sdtContentLocked (both). SuperDoc notes that “Locks travel with the DOCX and constrain normal editing in SuperDoc and Word. They do not authenticate users or decide who may access or save the file.” A locked clause in your template stays locked when the counterparty opens it in Word, but it is a guard against accidents, not a security control.

Legal-Grade Structures

Legal documents have structures that general-purpose editors rarely handle. SuperDoc’s Document API includes operation families for several of them:

  • Tables of authorities: “Table of authorities lifecycle and TA entry operations”, including inserting, configuring and rebuilding the table and managing its entries.
  • Citations: “Citation, source, and bibliography lifecycle operations”, covering citations, sources and bibliographies.
  • Document protection: “Document-level protection state and editing restriction operations”. Note that the documentation states “Only readOnly mode is supported in v1” for applying an editing restriction.
  • Permission ranges: “Permission range exception operations for protected documents.”

Limitations to Plan For

  • No PDF from the editor. “The browser Editor exports DOCX; it does not convert the document to PDF or HTML through this method.” Many contract workflows need a PDF at signature. Plan a separate conversion step.
  • Clean copies need care. “Export preserves comments by default.” The documentation notes that the default v2 worker runtime “does not support commentsType: 'clean': export rejects instead of returning a copy without comments”, and that the v2 editor “does not apply isFinalDoc during export”. Producing a clean execution copy is something to design, not assume.
  • Version history is your application’s job. “SuperDoc exports and opens the files; your application decides when to create a version and where to store it.” For negotiation, every round should be an immutable version.
  • Fonts affect pagination. If a font is unavailable, “different glyph widths can change line and page breaks.” In legal documents, page references matter. Supply the fonts your templates use, where their licences permit web delivery, or accept that page layout in the browser may differ from Word.

One more point. We do not publish fidelity benchmarks for SuperDoc, and the SuperDoc DOCX Engine licence restricts benchmarking the engine. Our recommendation is to test with your own templates and real negotiated documents, opening the results in Word, before you commit.

When a Browser Editor Is the Right Choice

SuperDoc is not the only way to put Word editing in a legal product. Office add-ins run inside Word itself, and Microsoft’s own editors can be embedded through WOPI or SharePoint Embedded. Our view: a browser editor like SuperDoc suits products that need the editing experience inside their own interface, documents kept in their own infrastructure, and programmatic control over changes. Microsoft’s routes suit products whose users live in Word and whose documents can be handled by Microsoft’s services. We compared the options in How Does SuperDoc v2 Compare to CSPP WOPI? and Do Microsoft Office Add-Ins Work with SuperDoc v2?, and covered add-ins for legal software in Enhancing Legal Software Development with Custom Word Add-Ins.

How McKenna Consultants Can Help

McKenna Consultants builds document experiences for legal SaaS and other document-centred products, across embedded browser editors, Microsoft’s WOPI and SharePoint Embedded platforms, and Word add-ins. We can help you design a redlining workflow, build it on SuperDoc, plan around today’s limitations, and test it against your own documents.

Contact us to discuss contract redlining in your product, or read more about our systems integration services.

Sources

All sources checked on 9 October 2026.

Related Articles

Related Case Studies

View all case studies

Have a question about this topic?

Our team would be happy to discuss this further with you.

Get in Touch