superdoc 2.4.0-next.9 → 2.5.0

package/README.md

@@ -1,106 +1,28 @@
-# SuperDoc
+# superdoc
 
-> The document engine for DOCX files.
+Browser editor for opening, editing, and rendering DOCX files.
 
-[![Documentation](https://img.shields.io/badge/docs-available-1355ff.svg)](https://docs.superdoc.dev/)
-[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-1355ff.svg)](https://www.gnu.org/licenses/agpl-3.0)
-[![npm version](https://img.shields.io/npm/v/superdoc.svg?color=1355ff)](https://www.npmjs.com/package/superdoc)
-[![codecov](https://codecov.io/gh/superdoc/docx-editor/branch/main/graph/badge.svg)](https://codecov.io/gh/superdoc/docx-editor)
-[![Discord](https://img.shields.io/badge/discord-join-1355ff)](https://discord.com/invite/b9UuaZRyaB)
-
-SuperDoc renders and edits DOCX files in the browser. Built on OOXML — not bolted onto HTML. As you type, you write directly to the XML. Import a document, edit it, export it. Nothing lost.
-
-## Features
-
-- **Real DOCX, not rich text** — Built on OOXML. Real pagination, section breaks, headers/footers, complex tables. Not a contenteditable wrapper with export bolted on.
-- **Self-hosted** — Runs entirely in the browser. Your documents never leave your servers.
-- **Any framework** — React, Vue, Angular, Svelte, vanilla JS. One component, zero lock-in.
-- **Real-time collaboration** — Yjs-based CRDT. Multiplayer editing with comments, tracked changes, and automatic conflict resolution.
-- **Built for agents** — [SDK](https://www.npmjs.com/package/@superdoc-dev/sdk), [CLI](https://www.npmjs.com/package/@superdoc-dev/cli), and [MCP server](https://www.npmjs.com/package/@superdoc-dev/mcp) let LLMs read, edit, and save .docx files programmatically.
-- **Dual licensed** — AGPLv3 for community use. [Commercial license](https://www.superdocportal.dev/get-in-touch) for proprietary deployments.
-
-## Quick start
+## Install
 
 ```bash
 npm install superdoc
 ```
 
-```javascript
-import 'superdoc/style.css';
-import { SuperDoc } from 'superdoc';
-
-const superdoc = new SuperDoc({
-  selector: '#superdoc',
-  documentMode: 'editing',
-  documents: [
-    {
-      id: 'my-doc-id',
-      type: 'docx',
-      data: fileObject,
-    },
-  ],
-});
-```
-
-Supported document modes are `editing`, `viewing`, and `suggesting`. Do not use `edit`, `view`, or `suggest`.
-
-### Browser Document API contract
-
-`superdoc.activeEditor.doc` is the browser-facing v2 Document API facade. In the
-browser it is intentionally async-capable, so custom UI code must tolerate
-promise-returning reads and writes, including the default worker-backed runtime.
-SDK/headless document-automation surfaces remain synchronous; this async
-contract is specific to the browser `superdoc` package.
-
-### Vanilla wrapper for a DOCX file
-
-When an agent needs to create a small vanilla JS wrapper around a DOCX `File`, use this shape:
+## Quick start
 
-```javascript
+```js
 import { SuperDoc } from 'superdoc';
 import 'superdoc/style.css';
 
-export function embedSuperDoc({ file }) {
-  return new SuperDoc({
-    selector: '#editor',
-    documentMode: 'editing',
-    documents: [
-      {
-        id: 'contract',
-        type: 'docx',
-        data: file,
-      },
-    ],
-  });
-}
-```
-
-For React, Vue, and other frameworks, see the [documentation](https://docs.superdoc.dev).
-
-### Using an AI coding agent?
-
-```bash
-claude mcp add superdoc -- npx @superdoc-dev/mcp   # connect agent to DOCX files
+const editor = new SuperDoc({
+  selector: '#editor',
+  document: '/document.docx',
+});
 ```
 
-## Documentation
-
-[docs.superdoc.dev](https://docs.superdoc.dev) — installation, integration guides, collaboration setup, API reference, and more.
-
-## Contributing
-
-Check the [issue tracker](https://github.com/superdoc/docx-editor/issues) for open issues, or read the [Contributing Guide](../../CONTRIBUTING.md) to get started. Bug reports with reproduction .docx files are especially valuable.
-
-## Community
-
-- [Discord](https://discord.com/invite/b9UuaZRyaB) — Chat with the team and other contributors
-- [Email](mailto:q@superdoc.dev) — Reach the team directly
+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.
 
 ## License
 
-- Open source: [GNU Affero General Public License v3.0](https://www.gnu.org/licenses/agpl-3.0.html)
-- Commercial: [Enterprise License](https://www.superdocportal.dev/get-in-touch)
-
----
-
-Created and maintained by [Harbour](https://www.superdoc.dev) and the SuperDoc community.
+AGPL-3.0. Commercial licenses are available from [SuperDoc](https://www.superdoc.dev).

package/dist/chunks/{FindReplaceSurface-9VkPw_-X.cjs → FindReplaceSurface-0p7EtMZh.cjs}

@@ -1,6 +1,6 @@
-const require_rolldown_runtime = require("./rolldown-runtime-1Y-nnZJ3.cjs");
-const require__plugin_vue_export_helper = require("./_plugin-vue_export-helper-CZ1Nl59K.cjs");
+const require__plugin_vue_export_helper = require("./_plugin-vue_export-helper-SDR04tiH.cjs");
 let vue = require("vue");
+//#region src/components/surfaces/FindReplaceSurface.vue
 var _hoisted_1 = ["onKeydown"];
 var _hoisted_2 = { class: "sd-find-replace__row" };
 var _hoisted_3 = [
@@ -341,5 +341,6 @@ var _sfc_main = {
 		};
 	}
 };
-var FindReplaceSurface_default = /* @__PURE__ */ require__plugin_vue_export_helper.__plugin_vue_export_helper_default(_sfc_main, [["__scopeId", "data-v-41f37c29"]]);
+var FindReplaceSurface_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_vue_export_helper_default(_sfc_main, [["__scopeId", "data-v-41f37c29"]]);
+//#endregion
 exports.default = FindReplaceSurface_default;

package/dist/chunks/{FindReplaceSurface-BuvaIrQ5.es.js → FindReplaceSurface-40AnrqWk.es.js}

@@ -1,5 +1,6 @@
-import { t as __plugin_vue_export_helper_default } from "./_plugin-vue_export-helper-DSMAhhwD.es.js";
+import { t as _plugin_vue_export_helper_default } from "./_plugin-vue_export-helper-BOaGB7Aw.es.js";
 import { computed, createCommentVNode, createElementBlock, createElementVNode, normalizeClass, onMounted, openBlock, ref, toDisplayString, withKeys, withModifiers } from "vue";
+//#region src/components/surfaces/FindReplaceSurface.vue
 var _hoisted_1 = ["onKeydown"];
 var _hoisted_2 = { class: "sd-find-replace__row" };
 var _hoisted_3 = [
@@ -67,7 +68,7 @@ var _hoisted_20 = {
 	"aria-hidden": "true"
 };
 var _hoisted_21 = { class: "sd-find-replace__error-text" };
-var FindReplaceSurface_default = /* @__PURE__ */ __plugin_vue_export_helper_default({
+var FindReplaceSurface_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 	__name: "FindReplaceSurface",
 	props: {
 		surfaceId: {
@@ -340,4 +341,5 @@ var FindReplaceSurface_default = /* @__PURE__ */ __plugin_vue_export_helper_defa
 		};
 	}
 }, [["__scopeId", "data-v-41f37c29"]]);
+//#endregion
 export { FindReplaceSurface_default as default };

package/dist/chunks/{PasswordPromptSurface-Bu5xHm91.cjs → PasswordPromptSurface-31lYPcCK.cjs}

@@ -1,6 +1,6 @@
-const require_rolldown_runtime = require("./rolldown-runtime-1Y-nnZJ3.cjs");
-const require__plugin_vue_export_helper = require("./_plugin-vue_export-helper-CZ1Nl59K.cjs");
+const require__plugin_vue_export_helper = require("./_plugin-vue_export-helper-SDR04tiH.cjs");
 let vue = require("vue");
+//#region src/components/surfaces/PasswordPromptSurface.vue
 var _hoisted_1 = ["onKeydown"];
 var _hoisted_2 = ["id"];
 var _hoisted_3 = { class: "sd-password-prompt__description" };
@@ -109,5 +109,6 @@ var _sfc_main = {
 		};
 	}
 };
-var PasswordPromptSurface_default = /* @__PURE__ */ require__plugin_vue_export_helper.__plugin_vue_export_helper_default(_sfc_main, [["__scopeId", "data-v-ecf7f6fb"]]);
+var PasswordPromptSurface_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_vue_export_helper_default(_sfc_main, [["__scopeId", "data-v-ecf7f6fb"]]);
+//#endregion
 exports.default = PasswordPromptSurface_default;

package/dist/chunks/{PasswordPromptSurface-Bz9_sKhX.es.js → PasswordPromptSurface-CwYeO3iQ.es.js}

@@ -1,5 +1,6 @@
-import { t as __plugin_vue_export_helper_default } from "./_plugin-vue_export-helper-DSMAhhwD.es.js";
+import { t as _plugin_vue_export_helper_default } from "./_plugin-vue_export-helper-BOaGB7Aw.es.js";
 import { computed, createCommentVNode, createElementBlock, createElementVNode, openBlock, ref, toDisplayString, vModelText, withDirectives, withKeys, withModifiers } from "vue";
+//#region src/components/surfaces/PasswordPromptSurface.vue
 var _hoisted_1 = ["onKeydown"];
 var _hoisted_2 = ["id"];
 var _hoisted_3 = { class: "sd-password-prompt__description" };
@@ -17,7 +18,7 @@ var _hoisted_6 = {
 var _hoisted_7 = { class: "sd-password-prompt__actions" };
 var _hoisted_8 = ["disabled"];
 var _hoisted_9 = ["disabled"];
-var PasswordPromptSurface_default = /* @__PURE__ */ __plugin_vue_export_helper_default({
+var PasswordPromptSurface_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 	__name: "PasswordPromptSurface",
 	props: {
 		surfaceId: {
@@ -108,4 +109,5 @@ var PasswordPromptSurface_default = /* @__PURE__ */ __plugin_vue_export_helper_d
 		};
 	}
 }, [["__scopeId", "data-v-ecf7f6fb"]]);
+//#endregion
 export { PasswordPromptSurface_default as default };

package/dist/chunks/{PdfViewer-CdVGB6Fe.es.js → PdfViewer-D8h7LRZy.es.js}

@@ -1,11 +1,14 @@
-import { t as __plugin_vue_export_helper_default } from "./_plugin-vue_export-helper-DSMAhhwD.es.js";
-import { n as PDF_TO_CSS_UNITS, t as OUTPUT_SCALE } from "./constants-BfH0br5u.es.js";
+import { t as _plugin_vue_export_helper_default } from "./_plugin-vue_export-helper-BOaGB7Aw.es.js";
+import { t as PDF_TO_CSS_UNITS } from "./constants-B6VBlmKp.es.js";
 import { Fragment, computed, createBlock, createCommentVNode, createElementBlock, createElementVNode, createVNode, markRaw, mergeProps, normalizeStyle, onBeforeUnmount, onMounted, openBlock, ref, renderList, shallowRef, watch } from "vue";
-const floor = (val, precision) => {
+//#region src/core/pdf/helpers/floor.js
+var floor = (val, precision) => {
 	const multiplier = 10 ** (precision || 0);
 	return Math.floor(val * multiplier) / multiplier;
 };
-const readFileAsArrayBuffer = (blob) => {
+//#endregion
+//#region src/core/pdf/helpers/read-file.js
+var readFileAsArrayBuffer = (blob) => {
 	return new Promise((resolve, reject) => {
 		const reader = new FileReader();
 		reader.onload = (event) => resolve(event.target.result);
@@ -13,22 +16,71 @@ const readFileAsArrayBuffer = (blob) => {
 		reader.readAsDataURL(blob);
 	});
 };
-const range = (start, end) => {
+//#endregion
+//#region src/core/pdf/helpers/range.js
+var range = (start, end) => {
 	const length = end - start;
 	return Array.from({ length }, (_, i) => start + i);
 };
-const createPDFConfig = (config) => {
+//#endregion
+//#region src/core/pdf/pdf-adapter.js
+/**
+* @typedef {import('pdfjs-dist').PDFDocumentProxy} PDFDocumentProxy
+* @typedef {import('pdfjs-dist').PDFPageProxy} PDFPageProxy
+*/
+/**
+* @typedef {'pdfjs'} AdapterType
+*/
+/**
+* @typedef {Object} PDFConfig
+* @property {AdapterType} adapter
+* @property {any} [pdfLib]
+* @property {string} [workerSrc]
+* @property {boolean} [setWorker]
+*/
+/**
+* @typedef {Object} PDFJSConfig
+* @property {any} pdfLib
+* @property {string} [workerSrc]
+* @property {boolean} [setWorker]
+*/
+/**
+* @typedef {Object} RenderPagesOptions
+* @property {string} documentId
+* @property {PDFDocumentProxy} pdfDocument
+* @property {HTMLElement} viewerContainer
+* @property {function(string, ...any): void} [emit]
+*/
+/**
+* @typedef {Object} PageSize
+* @property {number} width
+* @property {number} height
+*/
+/**
+* @param {Partial<PDFConfig>} [config]
+* @returns {PDFConfig}
+*/
+var createPDFConfig = (config) => {
 	return {
 		adapter: "pdfjs",
 		...config
 	};
 };
+/**
+* @abstract
+*/
 var PDFAdapter = class PDFAdapter {
+	/**
+	* @throws {Error}
+	*/
 	constructor() {
 		if (Object.getPrototypeOf(this).constructor === PDFAdapter) throw new Error("Abstract class should not be instantiated");
 	}
 };
 var PDFJSAdapter = class extends PDFAdapter {
+	/**
+	* @param {PDFJSConfig} config
+	*/
 	constructor(config) {
 		super();
 		this.pdfLib = config.pdfLib;
@@ -36,15 +88,30 @@ var PDFJSAdapter = class extends PDFAdapter {
 		if (config.setWorker) if (this.workerSrc) this.pdfLib.GlobalWorkerOptions.workerSrc = config.workerSrc;
 		else this.pdfLib.GlobalWorkerOptions.workerSrc = getWorkerSrcFromCDN(this.pdfLib.version);
 	}
+	/**
+	* @param {string | ArrayBuffer | Uint8Array} file
+	* @returns {Promise<PDFDocumentProxy>}
+	*/
 	async getDocument(file) {
 		return await this.pdfLib.getDocument(file).promise;
 	}
+	/**
+	* @param {PDFDocumentProxy} pdf
+	* @param {number} firstPage
+	* @param {number} lastPage
+	* @returns {Promise<PDFPageProxy[]>}
+	*/
 	async getPages(pdf, firstPage, lastPage) {
 		const pagesPromises = range(firstPage, lastPage + 1).map((num) => pdf.getPage(num));
 		return await Promise.all(pagesPromises);
 	}
 };
 var PDFAdapterFactory = class {
+	/**
+	* @param {PDFJSConfig & {adapter: AdapterType}} config
+	* @returns {PDFAdapter}
+	* @throws {Error}
+	*/
 	static create(config) {
 		const adapters = {
 			pdfjs: () => {
@@ -57,12 +124,18 @@ var PDFAdapterFactory = class {
 		return (adapters[config.adapter] ?? adapters.default)();
 	}
 };
+/**
+* @param {number} version
+* @returns {string}
+*/
 function getWorkerSrcFromCDN(version) {
 	return `https://cdnjs.cloudflare.com/ajax/libs/pdf.js/${version}/pdf.worker.min.mjs`;
 }
+//#endregion
+//#region src/components/PdfViewer/PdfViewerPage.vue
 var _hoisted_1$1 = ["data-page-id", "data-page-number"];
 var _hoisted_2 = { class: "sd-pdf-viewer-page__canvas-wrapper" };
-var PdfViewerPage_default = /* @__PURE__ */ __plugin_vue_export_helper_default({
+var PdfViewerPage_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 	__name: "PdfViewerPage",
 	props: {
 		config: {
@@ -161,9 +234,8 @@ var PdfViewerPage_default = /* @__PURE__ */ __plugin_vue_export_helper_default({
 		});
 		const pageStyle = computed(() => {
 			const { width: widthPt, height: heightPt } = getPagePtSize();
-			const scaleFactor = getScaleFactor();
 			return {
-				"--scale-factor": `${scaleFactor}`,
+				"--scale-factor": `${getScaleFactor()}`,
 				width: `calc(var(--scale-factor) * ${widthPt}px)`,
 				height: `calc(var(--scale-factor) * ${heightPt}px)`
 			};
@@ -224,7 +296,7 @@ var PdfViewerPage_default = /* @__PURE__ */ __plugin_vue_export_helper_default({
 				await renderTask.promise;
 				const size = getPageSize();
 				const originalPt = getPagePtSize();
-				emit("page-rendered", {
+				const payload = {
 					page: props.page,
 					documentId: props.page.documentId,
 					pageIndex: pageIdx.value,
@@ -233,7 +305,8 @@ var PdfViewerPage_default = /* @__PURE__ */ __plugin_vue_export_helper_default({
 					height: size.height,
 					originalWidth: originalPt.width * PDF_TO_CSS_UNITS,
 					originalHeight: originalPt.height * PDF_TO_CSS_UNITS
-				});
+				};
+				emit("page-rendered", payload);
 			} catch (e) {
 				destroyRenderTask();
 				emit("page-error", props.page);
@@ -306,7 +379,7 @@ var PdfViewerPage_default = /* @__PURE__ */ __plugin_vue_export_helper_default({
 		};
 	}
 }, [["__scopeId", "data-v-d7a9857d"]]);
-var PdfViewerDocument_default = /* @__PURE__ */ __plugin_vue_export_helper_default({
+var PdfViewerDocument_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 	__name: "PdfViewerDocument",
 	props: {
 		config: {
@@ -376,8 +449,10 @@ var PdfViewerDocument_default = /* @__PURE__ */ __plugin_vue_export_helper_defau
 		};
 	}
 }, [["__scopeId", "data-v-2152178b"]]);
+//#endregion
+//#region src/components/PdfViewer/PdfViewer.vue
 var _hoisted_1 = { class: "sd-pdf-viewer__main" };
-var PdfViewer_default = /* @__PURE__ */ __plugin_vue_export_helper_default({
+var PdfViewer_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 	__name: "PdfViewer",
 	props: {
 		config: {
@@ -389,6 +464,11 @@ var PdfViewer_default = /* @__PURE__ */ __plugin_vue_export_helper_default({
 			required: true
 		},
 		fileId: { type: String },
+		/**
+		* Zoom scale to render the first paint at (1 = 100%). The host seeds
+		* this from `config.zoom.initial` so a PDF never flashes 100% before
+		* a watcher catches up; later changes still arrive via updateScale().
+		*/
 		initialScale: {
 			type: Number,
 			default: 1
@@ -447,16 +527,19 @@ var PdfViewer_default = /* @__PURE__ */ __plugin_vue_export_helper_default({
 			renderedPages.value = 0;
 		}
 		function updateScale(nextScale) {
-			scale.value = floor(nextScale, 2);
+			const roundedScale = floor(nextScale, 2);
+			scale.value = roundedScale;
 		}
 		__expose({ updateScale });
 		async function getDocument(file) {
 			if (!file) return;
 			try {
 				const result = await readFileAsArrayBuffer(file);
+				const documentId = props.fileId || generateDocumentId("document");
+				const pdfjsDocument = await pdfAdapter.getDocument(result);
 				pdf.value = {
-					documentId: props.fileId || generateDocumentId("document"),
-					pdfjsDocument: markRaw(await pdfAdapter.getDocument(result))
+					documentId,
+					pdfjsDocument: markRaw(pdfjsDocument)
 				};
 				emit("document-loaded", file);
 			} catch (e) {
@@ -480,9 +563,9 @@ var PdfViewer_default = /* @__PURE__ */ __plugin_vue_export_helper_default({
 						pdfjsPage: markRaw(pdfjsPage)
 					};
 				};
-				const pages$1 = pdfjsPages.map(mapPages);
-				updatePages(pages$1);
-				emit("pages-loaded", pages$1);
+				const pages = pdfjsPages.map(mapPages);
+				updatePages(pages);
+				emit("pages-loaded", pages);
 			} catch (e) {
 				emit("document-error", e);
 				console.error(e);
@@ -528,4 +611,5 @@ var PdfViewer_default = /* @__PURE__ */ __plugin_vue_export_helper_default({
 		};
 	}
 }, [["__scopeId", "data-v-05c9d9b5"]]);
+//#endregion
 export { PdfViewer_default as default };