superdoc 2.29.0 → 2.30.0-next.19

package/README.md

@@ -1,6 +1,11 @@
 # superdoc
 
-Browser editor for opening, editing, and rendering DOCX files.
+Browser DOCX editor for reviewing, filling, and editing Word documents. Edits
+write back to OOXML without an HTML conversion step. Use the built-in UI or
+build your own. For headless or agent workflows, use
+[`@superdoc/sdk`](https://www.npmjs.com/package/@superdoc/sdk).
+
+[Live demo](https://www.superdoc.dev) · [Documentation](https://docs.superdoc.dev) · [GitHub](https://github.com/superdoc/docx-editor)
 
 ## Install
 
@@ -8,49 +13,146 @@ Browser editor for opening, editing, and rendering DOCX files.
 npm install superdoc
 ```
 
+The imports below need a bundler such as Vite or webpack.
+
 ## Quick start
 
+```html
+<div id="toolbar"></div>
+<div id="editor" style="height: 100vh"></div>
+```
+
 ```js
 import { SuperDoc } from 'superdoc';
 import 'superdoc/style.css';
 
-const editor = new SuperDoc({
+const superdoc = new SuperDoc({
   selector: '#editor',
-  document: '/document.docx',
+  document: '/sample.docx', // URL, File, or Blob; omit for a blank document
+  documentMode: 'editing', // 'editing' | 'suggesting' | 'viewing'
+  user: { name: 'Ada Lovelace', email: 'ada@superdoc.dev' },
+  ui: { toolbar: { container: '#toolbar' } },
+  onReady: ({ superdoc }) => {
+    console.log('Document ready');
+  },
 });
 ```
 
-See the [editor quick start](https://docs.superdoc.dev/editor/quickstart) for a complete example and the
-[SuperDoc documentation](https://docs.superdoc.dev) for configuration and APIs.
+## Common tasks
 
-See [package compatibility](https://docs.superdoc.dev/resources/package-compatibility) for the peer dependency policy and current-version inspection commands.
+### Export the edited DOCX
 
-## License
+```js
+await superdoc.export({ exportedName: 'sample-edited' }); // downloads sample-edited.docx
+const docx = await superdoc.export({ triggerDownload: false }); // returns the file instead
+```
+
+Exports keep tracked changes and comments by default. See
+[export options](https://docs.superdoc.dev/editor/export-options) to accept
+changes or remove comments in the exported copy.
 
-AGPL-3.0. Commercial licenses are available from [SuperDoc](https://www.superdoc.dev).
+### Record edits as tracked changes
 
-## Navigate to a bookmark
+Set `documentMode: 'suggesting'` and a `user` so each change has an author.
+Switch modes later with:
 
-After the V2 browser editor is ready, navigate by an exact bookmark name:
+```js
+superdoc.setDocumentMode('suggesting');
+```
+
+### Find and replace text
+
+Use the Document API at `superdoc.activeEditor.doc` after `onReady`. Find a
+target with `query.match`, then pass that target to the mutation:
 
 ```js
-const result = await editor.ui.bookmarks.navigateTo('Terms');
+onReady: async ({ superdoc }) => {
+  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: 'Amazing' },
+    require: 'exactlyOne',
+  });
+  const item = match.items[0];
+  if (!item || item.matchKind !== 'text') throw new Error('Text not found.');
+
+  const receipt = await doc.replace(
+    { target: item.target, text: 'Northstar' },
+    { changeMode: 'tracked', expectedRevision: match.evaluatedRevision },
+  );
+  if (!receipt.success) throw new Error(receipt.failure?.message ?? 'Replace failed.');
+},
+```
+
+### Add a comment
+
+Every edit changes the document revision, so query again after an edit instead
+of reusing an earlier `match`:
+
+```js
+const match = await doc.query.match({
+  select: { type: 'text', pattern: 'Confidential Information' },
+  require: 'exactlyOne',
+});
+const item = match.items[0];
+if (!item || item.matchKind !== 'text') throw new Error('Text not found.');
+
+const receipt = await doc.comments.create(
+  { target: item.target, text: 'Confirm this definition.' },
+  { expectedRevision: match.evaluatedRevision },
+);
+if (!receipt.success) throw new Error(receipt.failure?.message ?? 'Comment failed.');
+```
+
+### Navigate to a bookmark
+
+After the document is ready, navigate by an exact bookmark name:
+
+```js
+const result = await superdoc.ui.bookmarks.navigateTo('Terms');
 if (!result.success) console.log(result.reason);
 ```
 
-You can also pass a `BookmarkAddress` returned by `editor.activeEditor.doc.bookmarks.get()`
-or `.list()`. The method reveals the bookmark's start and selects its complete range,
-including across paragraphs. A collapsed bookmark places a caret. It supports editing,
-suggesting, and viewing modes. Navigation stays local in a shared room and does not change
-content or another client's selection. It does not take native keyboard focus.
+You can also pass a `BookmarkAddress` from `doc.bookmarks.get()` or `.list()`.
+Navigation scrolls to the bookmark and selects its range without changing
+content or other collaborators' selections. Pass
+`{ block: 'start', behavior: 'auto' }` as a second argument to change
+alignment or scrolling. Only body bookmarks are supported; other targets
+return `{ success: false, reason: 'target-unresolved' }`. The handle and
+address types are exported from `superdoc/ui`.
+
+## Common mistakes
 
-Scrolling defaults to instant, centered navigation. Pass `{ block: 'start', behavior: 'auto' }`
-as a second argument to change alignment or scrolling behavior.
+| Wrong | Right |
+| --- | --- |
+| `documentMode: 'edit'`, `'view'`, or `'suggest'` | `'editing'`, `'viewing'`, or `'suggesting'` |
+| Importing `SuperDoc` without `superdoc/style.css` | Import both |
+| `modules: { collaboration: { ydoc, provider } }` (V1) | `document: { url, collaboration: { providerType, serverUrl, documentId } }` |
+| `Editor`, `superdoc/super-editor`, ProseMirror commands, or plugin keys (V1) | The Document API at `superdoc.activeEditor.doc` |
+| Calling the Document API before the document loads | Call it inside `onReady` |
+| Building edit targets from DOM positions or OOXML IDs | Use the `target` returned by `doc.query.match` |
+| Importing `superdoc` in Node.js | Use `@superdoc/sdk` |
+
+`documentMode` controls editor behavior only. Your application still manages
+who may open or change a document.
+
+## Related packages
+
+- [`@superdoc/react`](https://www.npmjs.com/package/@superdoc/react) and [`@superdoc/vue`](https://www.npmjs.com/package/@superdoc/vue): framework wrappers for this editor.
+- [`@superdoc/sdk`](https://www.npmjs.com/package/@superdoc/sdk): Node.js SDK for headless editing and agent toolkits. Python and Rust SDKs are listed in the [documentation](https://docs.superdoc.dev).
+- [`@superdoc/mcp`](https://www.npmjs.com/package/@superdoc/mcp): MCP server for AI agents.
+
+## Documentation
+
+- [Editor quick start](https://docs.superdoc.dev/editor/quickstart)
+- [Configuration](https://docs.superdoc.dev/editor/configuration)
+- [Document modes](https://docs.superdoc.dev/editor/document-modes)
+- [Export options](https://docs.superdoc.dev/editor/export-options)
+- [Package compatibility](https://docs.superdoc.dev/resources/package-compatibility): peer dependency policy and version inspection.
+- [`llms.txt`](https://docs.superdoc.dev/llms.txt): machine-readable index of the documentation for coding agents.
+
+## License
 
-The first release supports body bookmarks. Non-body and table-column bookmarks, malformed,
-missing, deleted, or ambiguous targets return `{ success: false, ok: false, reason: 'target-unresolved' }`.
-Name-only lookup requires a unique match across the document; an explicit body address scopes
-lookup to the body. Resolution or reveal failure preserves the existing selection. Navigation
-abandons stale work after content changes, document replacement, or a newer request, and times
-out after 15 seconds. Missing editor or host capabilities return their readiness or availability
-reason. The handle and address types are exported from `superdoc/ui`.
+AGPL-3.0. [Commercial licenses](https://www.superdoc.dev/#pricing) are
+available for proprietary deployments.

package/dist/chunks/{FindReplaceSurface-B_5ggdWg.es.js → FindReplaceSurface-BEnRLpD9.es.js}

@@ -1,4 +1,4 @@
-import { D as normalizeClass, F as openBlock, G as toDisplayString, N as onMounted, a as computed, at as withModifiers, c as createCommentVNode, h as defineComponent, it as withKeys, l as createElementBlock, t as _plugin_vue_export_helper_default, u as createElementVNode, z as ref } from "./_plugin-vue_export-helper-DRPRMkeA.es.js";
+import { D as normalizeClass, F as openBlock, G as toDisplayString, N as onMounted, a as computed, at as withModifiers, c as createCommentVNode, h as defineComponent, it as withKeys, l as createElementBlock, t as _plugin_vue_export_helper_default, u as createElementVNode, z as ref } from "./_plugin-vue_export-helper-CmkaJDnr.es.js";
 //#region src/components/surfaces/FindReplaceSurface.vue?vue&type=script&setup=true&lang.ts
 var _hoisted_1 = ["onKeydown"];
 var _hoisted_2 = { class: "sd-find-replace__row" };

package/dist/chunks/{FindReplaceSurface-fVHxPXtn.cjs → FindReplaceSurface-DWXgWgg7.cjs}

@@ -1,4 +1,4 @@
-const require__plugin_vue_export_helper = require("./_plugin-vue_export-helper-BkbCxNeT.cjs");
+const require__plugin_vue_export_helper = require("./_plugin-vue_export-helper-BzM2_tVU.cjs");
 //#region src/components/surfaces/FindReplaceSurface.vue?vue&type=script&setup=true&lang.ts
 var _hoisted_1 = ["onKeydown"];
 var _hoisted_2 = { class: "sd-find-replace__row" };

package/dist/chunks/{PasswordPromptSurface-CZqhDQQ1.es.js → PasswordPromptSurface-DjV1JgjD.es.js}

@@ -1,4 +1,4 @@
-import { F as openBlock, G as toDisplayString, a as computed, at as withModifiers, c as createCommentVNode, et as vModelText, h as defineComponent, it as withKeys, l as createElementBlock, rt as withDirectives, t as _plugin_vue_export_helper_default, u as createElementVNode, z as ref } from "./_plugin-vue_export-helper-DRPRMkeA.es.js";
+import { F as openBlock, G as toDisplayString, a as computed, at as withModifiers, c as createCommentVNode, et as vModelText, h as defineComponent, it as withKeys, l as createElementBlock, rt as withDirectives, t as _plugin_vue_export_helper_default, u as createElementVNode, z as ref } from "./_plugin-vue_export-helper-CmkaJDnr.es.js";
 //#region src/components/surfaces/PasswordPromptSurface.vue?vue&type=script&setup=true&lang.ts
 var _hoisted_1 = ["onKeydown"];
 var _hoisted_2 = ["id"];

package/dist/chunks/{PasswordPromptSurface-x8GNmMJT.cjs → PasswordPromptSurface-VFPnQOML.cjs}

@@ -1,4 +1,4 @@
-const require__plugin_vue_export_helper = require("./_plugin-vue_export-helper-BkbCxNeT.cjs");
+const require__plugin_vue_export_helper = require("./_plugin-vue_export-helper-BzM2_tVU.cjs");
 //#region src/components/surfaces/PasswordPromptSurface.vue?vue&type=script&setup=true&lang.ts
 var _hoisted_1 = ["onKeydown"];
 var _hoisted_2 = ["id"];

package/dist/chunks/{PdfViewer-CW09MNrB.es.js → PdfViewer-C2r-K8zC.es.js}

@@ -1,4 +1,4 @@
-import { B as renderList, F as openBlock, N as onMounted, T as mergeProps, W as shallowRef, a as computed, c as createCommentVNode, h as defineComponent, j as onBeforeUnmount, k as normalizeStyle, l as createElementBlock, n as Fragment, p as createVNode, s as createBlock, t as _plugin_vue_export_helper_default, tt as watch, u as createElementVNode, w as markRaw, z as ref } from "./_plugin-vue_export-helper-DRPRMkeA.es.js";
+import { B as renderList, F as openBlock, N as onMounted, T as mergeProps, W as shallowRef, a as computed, c as createCommentVNode, h as defineComponent, j as onBeforeUnmount, k as normalizeStyle, l as createElementBlock, n as Fragment, p as createVNode, s as createBlock, t as _plugin_vue_export_helper_default, tt as watch, u as createElementVNode, w as markRaw, z as ref } from "./_plugin-vue_export-helper-CmkaJDnr.es.js";
 import { t as isFiniteNumber } from "./is-finite-number-BpL4F38c.es.js";
 import { t as PDF_TO_CSS_UNITS } from "./constants-BvNs_ybI.es.js";
 //#region src/core/pdf/helpers/floor.ts

package/dist/chunks/{PdfViewer-CkrAHpC-.cjs → PdfViewer-DYTbPVUr.cjs}

@@ -1,4 +1,4 @@
-const require__plugin_vue_export_helper = require("./_plugin-vue_export-helper-BkbCxNeT.cjs");
+const require__plugin_vue_export_helper = require("./_plugin-vue_export-helper-BzM2_tVU.cjs");
 const require_is_finite_number = require("./is-finite-number-BEXgTRgc.cjs");
 const require_constants = require("./constants-BeeNZoQp.cjs");
 //#region src/core/pdf/helpers/floor.ts

package/dist/chunks/{_plugin-vue_export-helper-BkbCxNeT.cjs → _plugin-vue_export-helper-BzM2_tVU.cjs}

@@ -2,6 +2,9 @@
 function isPlainObject(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function isObjectRecord(value) {
+	return typeof value === "object" && value !== null;
+}
 function isThenable(value) {
 	return (typeof value === "object" || typeof value === "function") && value !== null && "then" in value && typeof value.then === "function";
 }
@@ -352,6 +355,12 @@ Object.defineProperty(exports, "inject", {
 		return inject;
 	}
 });
+Object.defineProperty(exports, "isObjectRecord", {
+	enumerable: true,
+	get: function() {
+		return isObjectRecord;
+	}
+});
 Object.defineProperty(exports, "isPlainObject", {
 	enumerable: true,
 	get: function() {

package/dist/chunks/{_plugin-vue_export-helper-DRPRMkeA.es.js → _plugin-vue_export-helper-CmkaJDnr.es.js}

@@ -2,6 +2,9 @@
 function isPlainObject(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function isObjectRecord(value) {
+	return typeof value === "object" && value !== null;
+}
 function isThenable(value) {
 	return (typeof value === "object" || typeof value === "function") && value !== null && "then" in value && typeof value.then === "function";
 }
@@ -226,4 +229,4 @@ var _plugin_vue_export_helper_default = (sfc, props) => {
 	return target;
 };
 //#endregion
-export { vModelSelect as $, onActivated as A, renderList as B, isRef as C, normalizeClass as D, nextTick as E, openBlock as F, toDisplayString as G, resolveDirective as H, provide as I, toRefs as J, toRaw as K, reactive as L, onDeactivated as M, onMounted as N, normalizeProps as O, onScopeDispose as P, vModelCheckbox as Q, readonly as R, isReactive as S, mergeProps as T, resolveDynamicComponent as U, renderSlot as V, shallowRef as W, useAttrs as X, unref as Y, useSlots as Z, getCurrentInstance as _, computed as a, withModifiers as at, hasInjectionContext as b, createCommentVNode as c, createStaticVNode as d, vModelText as et, createTextVNode as f, effectScope as g, defineComponent as h, Transition as i, withKeys as it, onBeforeUnmount as j, normalizeStyle as k, createElementBlock as l, defineAsyncComponent as m, Fragment as n, withCtx as nt, createApp as o, isPlainObject as ot, createVNode as p, toRef as q, Teleport as r, withDirectives as rt, createBlock as s, isThenable as st, _plugin_vue_export_helper_default as t, watch as tt, createElementVNode as u, getCurrentScope as v, markRaw as w, inject as x, h as y, ref as z };
+export { vModelSelect as $, onActivated as A, renderList as B, isRef as C, normalizeClass as D, nextTick as E, openBlock as F, toDisplayString as G, resolveDirective as H, provide as I, toRefs as J, toRaw as K, reactive as L, onDeactivated as M, onMounted as N, normalizeProps as O, onScopeDispose as P, vModelCheckbox as Q, readonly as R, isReactive as S, mergeProps as T, resolveDynamicComponent as U, renderSlot as V, shallowRef as W, useAttrs as X, unref as Y, useSlots as Z, getCurrentInstance as _, computed as a, withModifiers as at, hasInjectionContext as b, createCommentVNode as c, isThenable as ct, createStaticVNode as d, vModelText as et, createTextVNode as f, effectScope as g, defineComponent as h, Transition as i, withKeys as it, onBeforeUnmount as j, normalizeStyle as k, createElementBlock as l, defineAsyncComponent as m, Fragment as n, withCtx as nt, createApp as o, isObjectRecord as ot, createVNode as p, toRef as q, Teleport as r, withDirectives as rt, createBlock as s, isPlainObject as st, _plugin_vue_export_helper_default as t, watch as tt, createElementVNode as u, getCurrentScope as v, markRaw as w, inject as x, h as y, ref as z };