# SuperDoc dropped ProseMirror because server use needed a simulated DOM, and its pull requests are closed to outsiders

> SuperDoc is a document engine that reads and writes DOCX packages directly instead of converting them through HTML, which is what lets the same document interface run in a browser, in Node, from Python, from a command line and through an MCP server. The repository is unusually opinionated in two places: the second version exists because the first needed a fake browser to run headless, and outside contributors are asked to file issues rather than pull requests.

**superdoc/docx-editor** — Build AI agents that work with DOCX

- Repository: https://github.com/superdoc/docx-editor
- Website: https://superdoc.dev
- Stars: 1,078 · Forks: 221
- Language: TypeScript
- License: AGPL-3.0
- Published: 2026-09-15 · Updated: 2026-09-15 · Language: en
- Canonical page: https://hysenlabs.com/projects/superdoc-docx-editor

## The second version exists because the first needed a fake browser

The architecture rationale is the most useful paragraph in the file, and it is a migration story. The first version used ProseMirror as its authoritative browser editing model, which is the right choice for a rich text editor and the wrong one for a DOCX, because a DOCX is a package of related XML parts, relationships and assets rather than one editor tree. Two consequences followed. Server use required simulating a browser DOM to run the editor headlessly. And collaboration needed a separate synchronization layer, because only the visible text was in the shared model while the rest of the package was not. The second version replaces that with an OOXML-backed document model that reads progressively, renders bounded windows, runs without a browser DOM, and synchronizes both document content and package state through one collaboration model. That is the whole reason the server-side SDKs exist.

## One document interface across a browser, two SDKs, a CLI and an MCP server

The interface is described as one thing reachable five ways: in the browser, through a Node SDK, through a Python SDK that lives inside the monorepo rather than on a public registry, through a command line package, and through an MCP server. Each of those is separately published under the project's scope. The verbs are the same in all of them, query, target, change, and inspect receipts, and that last one is unusual enough to notice: operations return a receipt you can inspect rather than a boolean. For agent use the design choice is stated plainly, agents are meant to call supported document operations instead of editing raw XML, and the engine takes care of the underlying parts and relationships. That is the right boundary for a model, since hand-written XML against a package format is exactly where an agent produces confident nonsense.

## Mounting takes two elements and a separately imported stylesheet

The quick start is short enough to reproduce from memory. One install command, then two empty elements in the page, one for the toolbar and one for the editor, because the engine mounts into containers you provide rather than creating its own. Then a stylesheet import and a constructor:

```html
<div id="superdoc-toolbar"></div>
<div id="superdoc"></div>
```

```javascript
import 'superdoc/style.css';
import { SuperDoc } from 'superdoc';

const superdoc = new SuperDoc({
  selector: '#superdoc',
  toolbar: '#superdoc-toolbar',
  document: '/sample.docx',
  documentMode: 'editing',
});
```

The document option takes a URL, a file object or a blob, and leaving it out starts with a blank document rather than an error. Two small constraints come with that. The stylesheet is a separate import, so a host application with its own design system has to decide who owns the typography. And the two element contract means the editor cannot be mounted into a shadow root or a single container without a wrapper.

## Nine packages carry the layout engine and their build order is a script

The root manifest is a private monorepo named for the product, and one of its scripts is a hand written topological sort. Rebuilding types runs pnpm with workspace concurrency set to one, filtering a list of nine packages in a fixed order: a common package, then word layout, contracts, a DOM contract, resolved layout, geometry utilities, the style engine, a measuring DOM, the layout engine and the layout bridge, followed by a separate painter DOM build. Reading that list tells you the internal shape of the thing. There is an explicit contract for the DOM, a separate package for measuring it, a separate one for painting it, and a layout engine split across several layers. Serialising the concurrency is the point: these packages build on each other, and the script encodes that ordering in a single line rather than deriving it from the workspace manifest.

## There is a test suite named after document privacy

Most of the test surface is conventional: a wrapper script for the whole suite, a bench mode behind an environment flag, a slow lane that delegates to a memory test in a layout test package, a coverage wrapper, and coverage reporting configured at the root. Two entries are not conventional. One runs the test runner against a separate configuration file, and the other is a standalone Node script whose name is a check rather than a test. Both are about document privacy, which tells you something about the project's worries that no feature list would: when you render documents you did not create, content leaks out of them, and this team built a lane to catch that. There is also an inspect mode that launches the debugger on a fixed debug port and disables file parallelism, which is the shape of a race condition someone could not reproduce otherwise.

## The examples enumerate the surface, and skip the document parts the prose claims

There are eleven example directories, and together they are the most honest map of what works: collaboration, content controls, custom interface, document comparison, document modes, proofing, a React integration, batch work through the SDK, search, a vanilla integration, and version history. Read against the feature claims, the gaps are informative. The prose says pagination, sections, headers, footers and tables stay document structures rather than being flattened, and not one example covers a header, a footer, a table or a section break. Document comparison and document modes come closest, since both imply multi-part documents, but neither is about page furniture. If your use case is a report with a running header, treat that as untested rather than as supported.

## Outside pull requests are not accepted, and the licence is copyleft

The contribution model is stated in one line that will stop most readers: community contributions start with an issue, and pull requests are limited to repository collaborators. Bug reports, feature requests and technical investigations are welcome; patches from outside the collaborator set are not, and the contributing guide is pointed at for why. Security problems go through the platform's private advisory channel instead. The repository root explains the shape of the team: an agent instruction file, a contributor licence agreement file, a second agent file, a code of conduct, a security policy, a third party licences file, a secret scanning configuration, a commit message linter and a coverage configuration. Licensing is dual: AGPL version 3 for open source use, with a commercial licence available for proprietary deployments. For a document engine aimed at agents inside other products, that copyleft term is the adoption question.

## Conclusion

This is the rare document tool where the agent story and the human editing story share one code path rather than two, and that is worth the licence. Two things to settle first. AGPL with a commercial option is a real constraint if you intend to expose a service built on it, so decide that before writing the integration rather than after. And build your acceptance tests against the example directories rather than the feature list, because the examples cover collaboration, comparison, content controls, proofing and version history but not headers, footers, tables or section breaks, which the prose claims are native structures. If you need those, verify them yourself before committing.

## FAQ

### What is SuperDoc?

A document engine for DOCX files that renders and edits them in the browser and exposes the same document interface for server-side automation and agent workflows. It is built directly on the underlying office format, so edits are written back to the XML without an HTML conversion step, and pagination, sections, headers, footers and tables stay document structures.

### How do I install and mount SuperDoc?

Install the package, then provide two elements in the page, one for the toolbar and one for the editor, import the stylesheet and the class, and construct it with a selector, a toolbar selector, a document and a document mode. The document option accepts a URL, a file object or a blob, and omitting it starts with a blank document.

### Can SuperDoc run without a browser and without a server?

In the browser it needs no server of its own and collaborates through a shared document model. The second version was rebuilt specifically so it runs without a browser DOM, which is what lets the same interface be used from the Node and Python SDKs, the command line package and an MCP server.

### What licence is SuperDoc released under?

AGPL version 3 for open source use, with a commercial licence available for proprietary deployments. The repository itself is a private monorepo and the published packages sit under the project's own scope.

### Can I send a pull request to SuperDoc?

Not as an outside contributor. The readme says community contributions start with an issue covering bugs, features or technical investigations, and that pull requests are limited to repository collaborators. Suspected security vulnerabilities go through the platform's private security advisory channel instead.

## Sources

- [License: AGPL-3.0](https://github.com/superdoc/docx-editor/blob/main/LICENSE)
- [Project website](https://superdoc.dev)
- [README](https://github.com/superdoc/docx-editor/blob/main/README.md)
- [Releases](https://github.com/superdoc/docx-editor/releases)
- [superdoc/docx-editor on GitHub](https://github.com/superdoc/docx-editor)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/superdoc-docx-editor