What's New in SuperDoc v2? The OOXML Engine, the Document API and What Changes for Integrators

Most major version numbers mark an accumulation of features. SuperDoc v2 marks a change of foundations. The browser DOCX editor that many teams adopted as “a Word editor built on ProseMirror” now runs on a different document model. That decision reaches into almost every part of the product: how documents are rendered, how code changes them, how extensions work, how collaboration is wired, and how the software is licensed.

If your integration mounts the editor, sets a document mode and exports the result, much of v2 will feel familiar. If your integration reaches into editor internals, v2 is a redesign of your integration layer. In this article we set out what’s new in SuperDoc v2, what each change means in practice, and where we think teams should focus. We are writing from the perspective of a consultancy currently implementing SuperDoc for a SaaS company in the audit sector. If SuperDoc is new to you, start with our introduction: What Is SuperDoc?

SuperDoc v2 at a Glance

A few facts about the release itself are useful before the architecture.

• v2 is the current release line. SuperDoc’s migration guide states that “SuperDoc v2 is the current latest release” and that the core editor “keeps the unscoped superdoc package name”.
• The first stable v2 release is 2.3.0. It was published to npm on 28 July 2026. Version numbers 2.1 and 2.2 on the superdoc package name belong to an unrelated package published in 2016–2017. The npm registry marks those versions with the note “Package rebuilt and renamed in 2025”, so do not go looking for a SuperDoc 2.0.0 or 2.1.0.
• It is moving quickly. Eleven minor releases appeared on npm between 2.3.0 on 28 July and 2.13.0 on 8 September.
• v1 has not stopped overnight. The 1.x line kept receiving releases after v2 shipped: 1.46.0 on 5 August and 1.46.3 on 26 August.

We have not found a published support end date for v1 in SuperDoc’s documentation. Our view is that teams should plan their move deliberately rather than assume the 1.x line will be maintained indefinitely.

1. A New Document Model: OOXML Instead of ProseMirror

This is the change everything else follows from. SuperDoc’s documentation summarises it in two sentences:

“SuperDoc v1 used ProseMirror as its authoritative browser editing model. V2 uses OOXML-backed document state instead, with the same document engine and Document API contract across browser and supported headless workflows.”

ProseMirror is a widely used open-source toolkit for building rich-text editors. It brings its own document schema, state and transaction model. In v1, the published package declared ProseMirror’s packages as peer dependencies, and a DOCX file was translated into a ProseMirror document for editing. In v2 those peer dependencies are gone. The engine reads the OOXML package (the XML parts, relationships and media inside a .docx) into its own editable state. It paginates that state with its own layout engine, and the browser DOM becomes a painted view of the document rather than the document itself.

Why does this matter to anyone who is not a SuperDoc engineer?

• Fidelity. When the authoritative model is the Word document structure, there is less translation between what Word stores and what the editor understands. Fewer document features fall through the gaps between two models.
• One engine everywhere. The same engine and operation contract now serve the browser editor and the headless SDKs. A server-side batch job and a user in the browser are operating on the same model, with the same semantics.
• A clean contract. Because the internal model is no longer ProseMirror, v2 no longer hands integrators ProseMirror objects to manipulate. That is the source of most of the migration work. It is also the source of most of the long-term stability gains.

2. The Document API Becomes the Integration Contract

In v1, a common way to read or change a document from code was to reach through the editor to its ProseMirror state and commands. In v2, the supported route is the Document API. SuperDoc describes it as “the operation contract for reading and changing a SuperDoc document”, and says that “Browser and headless hosts expose the same operation names and data shapes.”

Most workflows follow four steps: query the document, keep the returned target, apply a mutation to that target, and inspect the receipt. Replacing a term as a tracked change looks like this in the browser, following the pattern in SuperDoc’s documentation:

const doc = superdoc.activeEditor?.doc;
if (!doc) throw new Error('The active document is unavailable.');

const match = await doc.query.match({
  select: { type: 'text', pattern: 'termination' },
  require: 'first',
});

const result = match.items[0];
if (!result || result.matchKind !== 'text') {
  throw new Error('No matching text found.');
}

await doc.replace(
  { target: result.target, text: 'cancellation' },
  { changeMode: 'tracked' },
);

Several design choices are worth noticing.

Targets come from the document, not the screen. The documentation is explicit: “Do not derive mutation locations from rendered DOM nodes or copied text offsets.” If the document changes, you query again rather than trusting an old position.

Receipts are part of the contract. “Treat the receipt as part of the contract. Do not infer success from a repaint, a changed file size, or the absence of an error.”

Browser calls are asynchronous. In the browser the API is Promise-shaped, because the v2 facade can route work through a worker. SuperDoc’s summary: “The host decides how a call runs. The Document API decides what the call means.”

Capabilities are discoverable. Support can vary by runtime and document state. SuperDoc recommends checking doc.capabilities() before presenting an operation to a user.

Edits can be planned. Mutation plans let you “Validate several document edits, then apply them together against one document revision”. That matters when an automated step, an AI suggestion for instance, needs to make several related changes or none.

For product teams, the significance is that document automation stops being a matter of clever editor hacking. It becomes an API you can test, review and reason about, and the same calls work on the server.

3. A UI Controller Instead of Editor Internals

Custom interfaces were a strength of SuperDoc v1, and they remain one. The plumbing has changed. In v2, each SuperDoc instance owns a UI controller, exposed as superdoc.ui. It publishes reactive state (whether bold is active, which tracked change is selected, what the current selection is) and routes UI actions to public commands.

There are framework bindings for both major front-end ecosystems: hooks and providers from superdoc/ui/react, and composables from superdoc/ui/vue. You can keep SuperDoc’s built-in toolbar, configure it, or render your own controls while SuperDoc continues to render the document canvas.

Navigation follows the same pattern. Scrolling to a comment, tracked change or content control goes through the controller, for example superdoc.ui.trackChanges.scrollTo(changeId), not through DOM lookups. That matters because of the next change.

4. A New Rendering Pipeline: Progressive and Virtualised

v2 opens and renders documents progressively. SuperDoc’s migration guide makes onReady the boundary: “V2 opens and renders the DOCX progressively, so readiness is the public boundary for starting product interaction.” The layout engine paginates the document, and SuperDoc virtualises paginated documents by default, so pages outside the visible window have no DOM at all.

For users working on long documents, such as a hundred-page audit file or a contract with extensive schedules, virtualisation is what keeps the editor responsive. For integrators, it means old habits like document.querySelector('[data-track-change-id="…"]') become unreliable: the element you are looking for may simply not exist yet. That is why v2 routes navigation through the controller, which can mount the target page when it needs to.

The engine also runs work in module workers. If your JavaScript is served from a different origin from your application, the migration guide explains how to serve the document, collaboration and review-index worker assets from your own origin.

5. Extensions Without Schema Access

v2 introduces defineSuperDocExtension as the way to extend the editor, and it is deliberately narrower than v1’s extension model. SuperDoc’s migration reference says:

“v2 extensions receive commands, anchors, and decorations. They do not receive ProseMirror state, custom schema, or mutable DOM, so extensions that defined custom nodes or marks may have no v2 equivalent.”

This is the change most likely to cause real redesign work. If your v1 integration invented its own node or mark types to carry application data, there is no direct port. The v2 answer is to put that data into structures a Word document natively understands. SuperDoc’s guidance on storing application data in a DOCX maps the options:

Our view is that this is a healthy constraint. Data held in proprietary editor nodes is invisible to Microsoft Word and every other DOCX tool. Data held in content controls and custom XML parts survives in standard OOXML, where other tools can read it. The Office Open XML standard was built to carry this kind of information.

6. Collaboration, Re-engineered

Real-time collaboration in v1 asked the integrator to supply an external Yjs document and provider. v2 takes a different approach. In the words of the migration guide, v2 “takes a supported provider target … and owns the provider lifecycle.” The published v2 package declares optional peer support for Hocuspocus and Liveblocks providers. Liveblocks is new compared with v1.

Two consequences matter.

• Rooms are not compatible across versions. “V2 collaboration rooms use a different document format and require a separate migration. Do not connect a v2 editor directly to an existing v1 collaboration room.”
• The upgrade path is being actively worked on. The 2.13.0 release notes (8 September) list a fix for “Collaboration fidelity — DOCX documents maintain full formatting and metadata through v1-to-v2 room upgrades”. The same release added “Custom collaboration worker providers” for teams that need their own transport.

If your product uses collaboration, treat it as its own workstream. We return to this in the upgrade guide.

7. Word Structures as First-Class Operations

The Document API is not limited to text. SuperDoc’s architecture documentation groups its operations into families:

• Read and discover: queries, extraction, document info, Markdown and HTML views.
• Edit and review: insert, replace, delete, format, comments, tracked changes, history and diffing.
• Structure and media: sections, tables, headers, footers, page setup, images and alternative text.
• Word data and controls: content controls, bookmarks, fields, footnotes, custom XML and protection.
• Produce output: DOCX export and template application.

The release notes since v2 shipped show where the engineering effort is going: fidelity on real-world documents. Examples include:

• 2.10.0 (28 August): “Live field updates — cross-reference, note, and style reference fields update as you edit”, and constraint validation when creating content controls.
• 2.11.0 (1 September): support for custom footnote numbering, and hyperlinks “preserved when copying text, including namespace-variant and Strict OOXML formats”.
• 2.13.0 (8 September): round-trip fidelity work, including that “Heading levels 7–9 now round-trip correctly”, plus ruler-based page margin adjustment.

8. The Same Engine Behind Automation and Agents

Because the engine and the Document API are shared, v2 makes SuperDoc’s headless tooling a first-class part of the product. The tooling comprises:

• the Node.js SDK (@superdoc/sdk)
• the Python SDK (superdoc-sdk)
• a CLI
• an MCP server that lets coding agents open, edit and save DOCX files

A tracked change created by a server-side job and one created by a user in the browser are now the same kind of object, produced by the same engine.

For document-centric SaaS products, this is the change with the largest strategic upside in our view. You can run AI-assisted review on the server, deliver its proposals as tracked changes, and let a professional accept or reject them in the browser editor. All of this happens on one document model, with no translation layer to lose fidelity in between.

9. Packaging and Licensing Changes

Two packaging changes affect every upgrade.

A smaller public surface. v2 removes the v1 package subpaths that exposed internals. These include superdoc/super-editor, superdoc/converter, superdoc/docx-zipper, superdoc/file-zipper, superdoc/types and the superdoc/headless-toolbar family. The React wrapper has moved too: “@superdoc-dev/react is the v1 wrapper. Install @superdoc/react for v2.”

A proprietary DOCX engine. v2’s superdoc package depends on a separately published engine package, @superdoc/docx-engine, which first appeared on npm on 16 July 2026. Its licence, dated 14 July 2026, states: “DOCX Engine, published as @superdoc/docx-engine, is proprietary software and is not open source. The open-source SuperDoc editor and the proprietary DOCX Engine are separately licensed components.”

The engine may be used “solely as a dependency of SuperDoc”. Without a separate agreement, permitted uses are those allowed under the AGPLv3 licence that covers SuperDoc’s open-source code. Production and commercial use is otherwise governed by your agreement with SuperDoc. The licence also restricts reverse engineering and the use of the engine to build or assist competing products.

For organisations that adopted SuperDoc v1 purely on its AGPLv3 terms, this is a material change, and it belongs in front of your legal and procurement teams before the engineering work starts. We are not lawyers, and nothing here is legal advice. Our point is simply that a v2 upgrade is a licensing event as well as a code change.

What SuperDoc v2 Means in Practice

Pulling the threads together, here is our reading.

1. Simple integrations will move easily. The migration guide says it directly: “If your v1 application mounts SuperDoc from the package root, waits for readiness, and exports through the same instance, most of that integration remains valid.”
2. Deep integrations need a redesign, not a find-and-replace. Code that used ProseMirror state, custom nodes or marks, DOM selectors or v1 helper objects must be re-expressed through the Document API, the UI controller and v2 extensions.
3. The benefits are durable. An explicit API contract, a shared browser and headless engine, and data stored in standard OOXML structures make integrations less brittle across future upgrades.
4. Pin and test. With a release cadence measured in days, pin exact versions. Run every upgrade against a corpus of your own documents before it reaches users.
5. Start the licensing review now. It has the longest lead time of anything on this list.

How McKenna Consultants Can Help

McKenna Consultants is implementing SuperDoc for a SaaS company in the audit and compliance sector, and we have been building custom software since 2004. Alongside SuperDoc, we work extensively with Microsoft’s document platforms, from WOPI integrations to SharePoint Embedded. That gives us a practical, vendor-neutral view of the options.

We can help you assess what v2 means for your codebase, design a migration that keeps v1 running until v2 is proven on your documents, and rebuild custom editing, review and AI workflows on the Document API. Get in touch to discuss your SuperDoc integration.

Sources

• SuperDoc documentation — SuperDoc Editor overview: “What changed in v2?”, the move from ProseMirror to OOXML-backed document state.
• SuperDoc documentation — Migrate from v1: v2 as the latest release, package names, the React wrapper rename, progressive rendering, collaboration room compatibility, worker assets and removed subpaths.
• SuperDoc documentation — Removed in v2: v2 extension model and removed v1 internals.
• SuperDoc documentation — Document API mental model: query, target, mutate and receipt; Promise-shaped browser calls.
• SuperDoc documentation — How SuperDoc works: shared engine across browser and headless surfaces; Document API operation families; doc.capabilities().
• SuperDoc documentation — Store application data in DOCX: content controls, anchored metadata, custom XML, citations and fields.
• SuperDoc documentation — Tune performance for large documents: default virtualisation of paginated documents and module workers.
• SuperDoc documentation — Agents and automation overview: Node.js and Python SDKs, CLI and MCP server.
• SuperDoc documentation — SuperDoc DOCX Engine Proprietary License: licence version 2026-07-14; proprietary status and authorised use of @superdoc/docx-engine.
• SuperDoc on GitHub — release notes for 2.10.0, 2.11.0 and 2.13.0.
• npm registry — superdoc package versions: publication dates of 2.3.0 to 2.13.0 and of the 1.46.x releases, ProseMirror peer dependencies in 1.x, Hocuspocus and Liveblocks peers in 2.x, and the deprecation note on the unrelated 2.1 and 2.2 versions.
• npm registry — @superdoc/docx-engine: first publication date.
• Microsoft Learn — About the Open XML SDK: Open XML as an open standard implemented by multiple applications.