@harbour-enterprises/superdoc 2.0.0-next.22 → 2.0.0-next.23

package/dist/chunks/{index-BYTMVIbP.cjs → index-BihcZqMS.cjs}

@@ -1,9 +1,9 @@
 "use strict";
 const jszip = require("./jszip-C8_CqJxM.cjs");
 const helpers$1 = require("./helpers-nOdwpmwb.cjs");
-const superEditor_converter = require("./SuperConverter-BgQ_7WLE.cjs");
-require("./jszip.min-BPh2MMAa.cjs");
+const superEditor_converter = require("./SuperConverter-H5PfOKjB.cjs");
 const vue = require("./vue-De9wkgLl.cjs");
+require("./jszip.min-BPh2MMAa.cjs");
 const eventemitter3 = require("./eventemitter3-BQuRcMPI.cjs");
 const uuid = require("./uuid-R7L08bOx.cjs");
 const blankDocx = require("./blank-docx-DfW3Eeh2.cjs");
@@ -9053,6 +9053,37 @@ class OxmlNode extends Node$1 {
     return new OxmlNode(config);
   }
 }
+class EditorError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EditorError";
+  }
+}
+class InvalidStateError extends EditorError {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidStateError";
+  }
+}
+class NoSourcePathError extends EditorError {
+  constructor(message) {
+    super(message);
+    this.name = "NoSourcePathError";
+  }
+}
+class FileSystemNotAvailableError extends EditorError {
+  constructor(message) {
+    super(message);
+    this.name = "FileSystemNotAvailableError";
+  }
+}
+class DocumentLoadError extends EditorError {
+  constructor(message, cause) {
+    super(message);
+    this.name = "DocumentLoadError";
+    this.cause = cause;
+  }
+}
 const first = (commands2) => (props) => {
   const items = typeof commands2 === "function" ? commands2(props) : commands2;
   for (let i = 0; i < items.length; i += 1) {
@@ -14884,7 +14915,7 @@ const canUseDOM = () => {
     return false;
   }
 };
-const summaryVersion = "2.0.0-next.22";
+const summaryVersion = "2.0.0-next.23";
 const nodeKeys = ["group", "content", "marks", "inline", "atom", "defining", "code", "tableRole", "summary"];
 const markKeys = ["group", "inclusive", "excludes", "spanning", "code"];
 function mapAttributes(attrs) {
@@ -15368,14 +15399,37 @@ class ProseMirrorRenderer {
 }
 class Editor extends EventEmitter {
   /**
-   * Create a new Editor instance
+   * Create a new Editor instance.
+   *
+   * **Legacy mode (backward compatible):**
+   * When `content` or `fileSource` is provided, the editor initializes synchronously
+   * with the document loaded immediately. This preserves existing behavior where
+   * `editor.view` is available right after construction.
+   *
+   * **New mode (document lifecycle API):**
+   * When no `content` or `fileSource` is provided, only core services (extensions,
+   * commands, schema) are initialized. Call `editor.open()` to load a document.
+   *
    * @param options - Editor configuration options
+   *
+   * @example
+   * ```typescript
+   * // Legacy mode (still works)
+   * const editor = new Editor({ content: docx, element: el });
+   * console.log(editor.view.state.doc); // Works immediately
+   *
+   * // New mode
+   * const editor = new Editor({ element: el });
+   * await editor.open('/path/to/doc.docx');
+   * ```
    */
   constructor(options) {
     super();
     this.extensionStorage = {};
     this.#renderer = null;
     this.#isDestroyed = false;
+    this.#editorLifecycleState = "initialized";
+    this.#sourcePath = null;
     this.presentationEditor = null;
     this.isFocused = false;
     this.fontsImported = [];
@@ -15488,18 +15542,25 @@ class Editor extends EventEmitter {
     this.#checkHeadless(resolvedOptions);
     this.setOptions(resolvedOptions);
     this.#renderer = resolvedOptions.renderer ?? (domAvailable ? new ProseMirrorRenderer() : null);
-    const modes = {
-      docx: () => this.#init(),
-      text: () => this.#initRichText(),
-      html: () => this.#initRichText(),
-      default: () => {
-        console.log("Not implemented.");
-      }
-    };
-    const initMode = modes[this.options.mode] ?? modes.default;
     const { setHighContrastMode } = useHighContrastMode();
     this.setHighContrastMode = setHighContrastMode;
-    initMode();
+    const useNewApiMode = resolvedOptions.deferDocumentLoad === true;
+    if (useNewApiMode) {
+      this.#initCore();
+      this.#editorLifecycleState = "initialized";
+    } else {
+      const modes = {
+        docx: () => this.#init(),
+        text: () => this.#initRichText(),
+        html: () => this.#initRichText(),
+        default: () => {
+          console.log("Not implemented.");
+        }
+      };
+      const initMode = modes[this.options.mode] ?? modes.default;
+      initMode();
+      this.#editorLifecycleState = "ready";
+    }
   }
   /**
    * Command service for handling editor commands
@@ -15507,6 +15568,8 @@ class Editor extends EventEmitter {
   #commandService;
   #renderer;
   #isDestroyed;
+  #editorLifecycleState;
+  #sourcePath;
   /**
    * Getter which indicates if any changes happen in Editor
    */
@@ -15531,6 +15594,303 @@ class Editor extends EventEmitter {
       this.emit("create", { editor: this });
     }, 0);
   }
+  /**
+   * Assert that the editor is in one of the allowed states.
+   * Throws InvalidStateError if not.
+   */
+  #assertState(...allowed) {
+    if (!allowed.includes(this.#editorLifecycleState)) {
+      throw new InvalidStateError(
+        `Invalid operation: editor is in '${this.#editorLifecycleState}' state, expected one of: ${allowed.join(", ")}`
+      );
+    }
+  }
+  /**
+   * Wraps an async operation with state transitions for safe lifecycle management.
+   *
+   * This method ensures atomic state transitions during async operations:
+   * 1. Sets state to `during` before executing the operation
+   * 2. On success: sets state to `success` and returns the operation result
+   * 3. On error: sets state to `failure` and re-throws the error
+   *
+   * This prevents race conditions and ensures the editor is always in a valid state,
+   * even when operations fail.
+   *
+   * @template T - The return type of the operation
+   * @param during - State to set while the operation is running
+   * @param success - State to set if the operation succeeds
+   * @param failure - State to set if the operation fails
+   * @param operation - Async operation to execute
+   * @returns Promise resolving to the operation's return value
+   * @throws Re-throws any error from the operation after setting failure state
+   *
+   * @example
+   * ```typescript
+   * // Used internally for save operations:
+   * await this.#withState('saving', 'ready', 'ready', async () => {
+   *   const data = await this.exportDocument();
+   *   await this.#writeToPath(path, data);
+   * });
+   * ```
+   */
+  async #withState(during, success, failure, operation) {
+    this.#editorLifecycleState = during;
+    try {
+      const result = await operation();
+      this.#editorLifecycleState = success;
+      return result;
+    } catch (error) {
+      this.#editorLifecycleState = failure;
+      throw error;
+    }
+  }
+  /**
+   * Initialize core editor services for new lifecycle API mode.
+   *
+   * When `deferDocumentLoad: true` is set, this method initializes only the
+   * document-independent components:
+   * - Extension service (loads and configures all extensions)
+   * - Command service (registers all editor commands)
+   * - ProseMirror schema (derived from extensions, reusable across documents)
+   *
+   * These services are created once during construction and reused when opening
+   * different documents via the `open()` method. This enables efficient document
+   * switching without recreating the entire editor infrastructure.
+   *
+   * Called exclusively from the constructor when `deferDocumentLoad` is true.
+   *
+   * @remarks
+   * This is part of the new lifecycle API that separates editor initialization
+   * from document loading. The schema and extensions remain constant while
+   * documents can be opened, closed, and reopened.
+   *
+   * @see #loadDocument - Loads document-specific state after core initialization
+   */
+  #initCore() {
+    if (!this.options.extensions?.length) {
+      this.options.extensions = this.options.mode === "docx" ? getStarterExtensions() : getRichTextExtensions();
+    }
+    this.#createExtensionService();
+    this.#createCommandService();
+    this.#createSchema();
+    this.#registerEventListeners();
+  }
+  /**
+   * Register all event listeners from options.
+   *
+   * Called once during core initialization. These listeners persist across
+   * document open/close cycles since the callbacks are set at construction time.
+   */
+  #registerEventListeners() {
+    this.on("create", this.options.onCreate);
+    this.on("update", this.options.onUpdate);
+    this.on("selectionUpdate", this.options.onSelectionUpdate);
+    this.on("transaction", this.options.onTransaction);
+    this.on("focus", this.#onFocus.bind(this));
+    this.on("blur", this.options.onBlur);
+    this.on("destroy", this.options.onDestroy);
+    this.on("trackedChangesUpdate", this.options.onTrackedChangesUpdate);
+    this.on("commentsLoaded", this.options.onCommentsLoaded);
+    this.on("commentClick", this.options.onCommentClicked);
+    this.on("commentsUpdate", this.options.onCommentsUpdate);
+    this.on("locked", this.options.onDocumentLocked);
+    this.on("collaborationReady", this.#onCollaborationReady.bind(this));
+    this.on("comment-positions", this.options.onCommentLocationsUpdate);
+    this.on("list-definitions-change", this.options.onListDefinitionsChange);
+    this.on("fonts-resolved", this.options.onFontsResolved);
+    this.on("exception", this.options.onException);
+  }
+  /**
+   * Load a document into the editor from various source types.
+   *
+   * This method handles the complete document loading pipeline:
+   * 1. **Source resolution**: Determines source type (path/File/Blob/Buffer/blank)
+   * 2. **Content loading**:
+   *    - String path: Reads file from disk (Node.js) or fetches URL (browser)
+   *    - File/Blob: Extracts docx archive data
+   *    - Buffer: Processes binary data (Node.js)
+   *    - undefined/null: Creates blank document
+   * 3. **Document initialization**: Creates converter, media, fonts, initial state
+   * 4. **View mounting**: Attaches ProseMirror view (unless headless)
+   * 5. **Event wiring**: Connects all lifecycle event handlers
+   *
+   * Called by `open()` after state validation, wrapped in `#withState()` for
+   * atomic state transitions.
+   *
+   * @param source - Document source:
+   *   - `string`: File path (Node.js reads from disk, browser fetches as URL)
+   *   - `File | Blob`: Browser file object or blob
+   *   - `Buffer`: Node.js buffer containing docx data
+   *   - `undefined | null`: Creates a blank document
+   * @param options - Document-level options (mode, comments, styles, etc.)
+   * @returns Promise that resolves when document is fully loaded and ready
+   * @throws {DocumentLoadError} If any step of document loading fails. The error
+   *   wraps the underlying cause for debugging.
+   *
+   * @remarks
+   * - Sets `#sourcePath` for path-based sources (enables `save()`)
+   * - Sets `#sourcePath = null` for Blob/Buffer sources (requires `saveTo()`)
+   * - In browser, string paths are treated as URLs to fetch
+   * - In Node.js, string paths are read from the filesystem
+   *
+   * @see open - Public API that calls this method
+   * @see #unloadDocument - Cleanup counterpart that reverses this process
+   */
+  async #loadDocument(source, options) {
+    try {
+      const resolvedMode = options?.mode ?? this.options.mode ?? "docx";
+      const resolvedOptions = {
+        ...this.options,
+        mode: resolvedMode,
+        isCommentsEnabled: options?.isCommentsEnabled ?? this.options.isCommentsEnabled,
+        suppressDefaultDocxStyles: options?.suppressDefaultDocxStyles ?? this.options.suppressDefaultDocxStyles,
+        documentMode: options?.documentMode ?? this.options.documentMode ?? "editing",
+        html: options?.html,
+        markdown: options?.markdown,
+        jsonOverride: options?.json ?? null
+      };
+      if (typeof source === "string") {
+        if (typeof vue.process$1 !== "undefined" && vue.process$1.versions?.node) {
+          const fs = require("fs");
+          const buffer = fs.readFileSync(source);
+          const [docx, _media, mediaFiles, fonts] = await Editor.loadXmlData(buffer, true);
+          resolvedOptions.content = docx;
+          resolvedOptions.mediaFiles = mediaFiles;
+          resolvedOptions.fonts = fonts;
+          resolvedOptions.fileSource = buffer;
+          this.#sourcePath = source;
+        } else {
+          const response = await fetch(source);
+          const blob = await response.blob();
+          const [docx, _media, mediaFiles, fonts] = await Editor.loadXmlData(blob);
+          resolvedOptions.content = docx;
+          resolvedOptions.mediaFiles = mediaFiles;
+          resolvedOptions.fonts = fonts;
+          resolvedOptions.fileSource = blob;
+          this.#sourcePath = source.split("/").pop() || null;
+        }
+      } else if (source != null && typeof source === "object") {
+        const isNodeBuffer = typeof jszip.Buffer !== "undefined" && (jszip.Buffer.isBuffer(source) || source instanceof jszip.Buffer);
+        const isBlob = typeof Blob !== "undefined" && source instanceof Blob;
+        const isArrayBuffer = source instanceof ArrayBuffer;
+        const hasArrayBuffer = typeof source === "object" && "buffer" in source && source.buffer instanceof ArrayBuffer;
+        if (isNodeBuffer || isBlob || isArrayBuffer || hasArrayBuffer) {
+          const [docx, _media, mediaFiles, fonts] = await Editor.loadXmlData(
+            source,
+            isNodeBuffer
+          );
+          resolvedOptions.content = docx;
+          resolvedOptions.mediaFiles = mediaFiles;
+          resolvedOptions.fonts = fonts;
+          resolvedOptions.fileSource = source;
+          this.#sourcePath = null;
+        } else {
+          const [docx, _media, mediaFiles, fonts] = await Editor.loadXmlData(source, false);
+          resolvedOptions.content = docx;
+          resolvedOptions.mediaFiles = mediaFiles;
+          resolvedOptions.fonts = fonts;
+          resolvedOptions.fileSource = source;
+          this.#sourcePath = null;
+        }
+      } else {
+        resolvedOptions.content = options?.content ?? [];
+        resolvedOptions.mediaFiles = options?.mediaFiles ?? {};
+        resolvedOptions.fonts = options?.fonts ?? {};
+        resolvedOptions.fileSource = null;
+        resolvedOptions.isNewFile = !options?.content;
+        this.#sourcePath = null;
+      }
+      this.setOptions(resolvedOptions);
+      this.#createConverter();
+      this.#initMedia();
+      const shouldMountRenderer = this.#shouldMountRenderer();
+      if (shouldMountRenderer) {
+        this.#initContainerElement(this.options);
+        this.#initFonts();
+      }
+      this.#createInitialState({ includePlugins: !shouldMountRenderer });
+      if (!shouldMountRenderer) {
+        const tr = this.state.tr.setMeta("forcePluginPass", true).setMeta("addToHistory", false);
+        this.#dispatchTransaction(tr);
+      }
+      if (shouldMountRenderer) {
+        this.mount(this.options.element);
+        this.#configureStateWithExtensionPlugins();
+      }
+      if (!shouldMountRenderer) {
+        this.#emitCreateAsync();
+      }
+      if (shouldMountRenderer) {
+        this.initDefaultStyles();
+        this.#checkFonts();
+      }
+      const shouldMigrateListsOnInit = Boolean(
+        this.options.markdown || this.options.html || this.options.loadFromSchema || this.options.jsonOverride || this.options.mode === "html" || this.options.mode === "text"
+      );
+      if (shouldMigrateListsOnInit) {
+        this.migrateListsToV2();
+      }
+      this.setDocumentMode(this.options.documentMode, "init");
+      this.initializeCollaborationData();
+      if (!this.options.ydoc && !this.options.isChildEditor) {
+        this.#initComments();
+      }
+      if (shouldMountRenderer) {
+        this.#initDevTools();
+        this.#registerCopyHandler();
+      }
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      throw new DocumentLoadError(`Failed to load document: ${err.message}`, err);
+    }
+  }
+  /**
+   * Unload the current document and clean up all document-specific resources.
+   *
+   * This method performs a complete cleanup of document state while preserving
+   * the core editor services (schema, extensions, commands) for reuse:
+   *
+   * **Resources cleaned up:**
+   * - ProseMirror view (unmounted from DOM)
+   * - Header/footer editors (destroyed)
+   * - Document converter instance
+   * - Media references and image storage
+   * - Source path reference
+   * - Document-specific options (content, fileSource, initialState)
+   * - ProseMirror editor state
+   *
+   * **Resources preserved:**
+   * - ProseMirror schema
+   * - Extension service and registered extensions
+   * - Command service and registered commands
+   * - Event listeners (registered once during core init, reused across documents)
+   *
+   * After cleanup, the editor transitions to 'closed' state and can be reopened
+   * with a new document via `open()`.
+   *
+   * Called by `close()` after emitting the `documentClose` event.
+   *
+   * @remarks
+   * This is a critical part of the document lifecycle API that enables efficient
+   * document switching. By preserving schema and extensions, we avoid expensive
+   * reinitialization when opening multiple documents sequentially.
+   *
+   * @see close - Public API that calls this method
+   * @see #loadDocument - Counterpart method that loads document resources
+   */
+  #unloadDocument() {
+    this.unmount();
+    this.destroyHeaderFooterEditors();
+    this.converter = void 0;
+    if (this.storage.image) {
+      this.storage.image.media = {};
+    }
+    this.#sourcePath = null;
+    this.options.initialState = null;
+    this.options.content = "";
+    this.options.fileSource = null;
+    this._state = void 0;
+  }
   /**
    * Initialize the editor with the given options
    */
@@ -15695,6 +16055,25 @@ class Editor extends EventEmitter {
   get state() {
     return this._state;
   }
+  /**
+   * Get the current editor lifecycle state.
+   *
+   * @returns The current lifecycle state ('initialized', 'documentLoading', 'ready', 'saving', 'closed', 'destroyed')
+   */
+  get lifecycleState() {
+    return this.#editorLifecycleState;
+  }
+  /**
+   * Get the source path of the currently opened document.
+   *
+   * Returns the file path if the document was opened from a path (Node.js),
+   * or null if opened from a Blob/Buffer or created as a blank document.
+   *
+   * In browsers, this is only a suggested filename, not an actual filesystem path.
+   */
+  get sourcePath() {
+    return this.#sourcePath;
+  }
   /**
    * Replace the editor state entirely.
    *
@@ -15792,19 +16171,19 @@ class Editor extends EventEmitter {
     if (this.options.role === "viewer") cleanedMode = "viewing";
     if (this.options.role === "suggester" && cleanedMode === "editing") cleanedMode = "suggesting";
     if (cleanedMode === "viewing") {
-      this.commands.toggleTrackChangesShowOriginal();
+      this.commands.toggleTrackChangesShowOriginal?.();
       this.setEditable(false, false);
       this.setOptions({ documentMode: "viewing" });
       if (pm) pm.classList.add("view-mode");
     } else if (cleanedMode === "suggesting") {
-      this.commands.disableTrackChangesShowOriginal();
-      this.commands.enableTrackChanges();
+      this.commands.disableTrackChangesShowOriginal?.();
+      this.commands.enableTrackChanges?.();
       this.setOptions({ documentMode: "suggesting" });
       this.setEditable(true, false);
       if (pm) pm.classList.remove("view-mode");
     } else if (cleanedMode === "editing") {
-      this.commands.disableTrackChangesShowOriginal();
-      this.commands.disableTrackChanges();
+      this.commands.disableTrackChangesShowOriginal?.();
+      this.commands.disableTrackChanges?.();
       this.setEditable(true, false);
       this.setOptions({ documentMode: "editing" });
       if (pm) pm.classList.remove("view-mode");
@@ -16852,16 +17231,289 @@ class Editor extends EventEmitter {
       console.error(err);
     }
   }
+  // ============================================================================
+  // Document Lifecycle API
+  // ============================================================================
+  /**
+   * Open a document in the editor.
+   *
+   * @param source - Document source:
+   *   - `string` - File path (Node.js reads from disk, browser fetches URL)
+   *   - `File | Blob` - Browser file object
+   *   - `Buffer` - Node.js buffer
+   *   - `undefined` - Creates a blank document
+   * @param options - Document options (mode, comments, etc.)
+   * @returns Promise that resolves when document is loaded
+   *
+   * @throws {InvalidStateError} If editor is not in 'initialized' or 'closed' state
+   * @throws {DocumentLoadError} If document loading fails
+   *
+   * @example
+   * ```typescript
+   * const editor = new Editor({ element: myDiv });
+   *
+   * // Open from file path (Node.js)
+   * await editor.open('/path/to/document.docx');
+   *
+   * // Open from File object (browser)
+   * await editor.open(fileInput.files[0]);
+   *
+   * // Open blank document
+   * await editor.open();
+   *
+   * // Open with options
+   * await editor.open('/path/to/doc.docx', { isCommentsEnabled: true });
+   * ```
+   */
+  async open(source, options) {
+    this.#assertState("initialized", "closed");
+    await this.#withState("documentLoading", "ready", "closed", async () => {
+      await this.#loadDocument(source, options);
+    });
+    this.emit("documentOpen", { editor: this, sourcePath: this.#sourcePath });
+  }
+  /**
+   * Static factory method for one-liner document opening.
+   * Creates an Editor instance and opens the document in one call.
+   *
+   * Smart defaults enable minimal configuration:
+   * - No element/selector → headless mode
+   * - No extensions → uses getStarterExtensions() for docx, getRichTextExtensions() for text/html
+   * - No mode → defaults to 'docx'
+   *
+   * @param source - Document source (path, File, Blob, Buffer, or undefined for blank)
+   * @param config - Combined editor and document options (all optional)
+   * @returns Promise resolving to the ready Editor instance
+   *
+   * @example
+   * ```typescript
+   * // Minimal headless usage - just works!
+   * const editor = await Editor.open('/path/to/doc.docx');
+   *
+   * // With options
+   * const editor = await Editor.open('/path/to/doc.docx', {
+   *   isCommentsEnabled: true,
+   * });
+   *
+   * // With UI element (automatically not headless)
+   * const editor = await Editor.open('/path/to/doc.docx', {
+   *   element: document.getElementById('editor'),
+   * });
+   *
+   * // Blank document
+   * const editor = await Editor.open();
+   * ```
+   */
+  static async open(source, config) {
+    const hasElement = config?.element != null || config?.selector != null;
+    const resolvedConfig = {
+      mode: "docx",
+      isHeadless: !hasElement,
+      ...config
+    };
+    const {
+      // OpenOptions (document-level)
+      html,
+      markdown,
+      isCommentsEnabled,
+      suppressDefaultDocxStyles,
+      documentMode,
+      content,
+      mediaFiles,
+      fonts,
+      // Everything else is EditorOptions
+      ...editorConfig
+    } = resolvedConfig;
+    const openOptions = {
+      mode: resolvedConfig.mode,
+      html,
+      markdown,
+      isCommentsEnabled,
+      suppressDefaultDocxStyles,
+      documentMode,
+      content,
+      mediaFiles,
+      fonts
+    };
+    const editor = new Editor({ ...editorConfig, deferDocumentLoad: true });
+    await editor.open(source, openOptions);
+    return editor;
+  }
+  /**
+   * Close the current document.
+   *
+   * This unloads the document but keeps the editor instance alive.
+   * The editor can be reused by calling `open()` again.
+   *
+   * This method is idempotent - calling it when already closed is a no-op.
+   *
+   * @example
+   * ```typescript
+   * await editor.open('/doc1.docx');
+   * // ... work with document ...
+   * editor.close();
+   *
+   * await editor.open('/doc2.docx');  // Reuse the same editor
+   * ```
+   */
+  close() {
+    if (this.#editorLifecycleState === "closed" || this.#editorLifecycleState === "initialized") {
+      return;
+    }
+    if (this.#editorLifecycleState === "destroyed") {
+      return;
+    }
+    this.#assertState("ready");
+    this.emit("documentClose", { editor: this });
+    this.#unloadDocument();
+    this.#editorLifecycleState = "closed";
+  }
+  /**
+   * Save the document to the original source path.
+   *
+   * Only works if the document was opened from a file path.
+   * If opened from Blob/Buffer or created blank, use `saveTo()` or `exportDocument()`.
+   *
+   * @param options - Save options (comments, final doc, etc.)
+   * @throws {InvalidStateError} If editor is not in 'ready' state
+   * @throws {NoSourcePathError} If no source path is available
+   * @throws {FileSystemNotAvailableError} If file system access is not available
+   *
+   * @example
+   * ```typescript
+   * const editor = await Editor.open('/path/to/doc.docx');
+   * // ... make changes ...
+   * await editor.save();  // Saves back to /path/to/doc.docx
+   * ```
+   */
+  async save(options) {
+    this.#assertState("ready");
+    if (!this.#sourcePath) {
+      throw new NoSourcePathError("No source path. Use saveTo(path) or exportDocument() instead.");
+    }
+    await this.#withState("saving", "ready", "ready", async () => {
+      const data = await this.exportDocument(options);
+      await this.#writeToPath(this.#sourcePath, data);
+    });
+  }
+  /**
+   * Save the document to a specific path.
+   *
+   * Updates the source path to the new location after saving.
+   *
+   * @param path - File path to save to
+   * @param options - Save options
+   * @throws {InvalidStateError} If editor is not in 'ready' state
+   * @throws {FileSystemNotAvailableError} If file system access is not available
+   *
+   * @example
+   * ```typescript
+   * const editor = await Editor.open(blobData);  // No source path
+   * await editor.saveTo('/path/to/new-doc.docx');
+   * await editor.save();  // Now saves to /path/to/new-doc.docx
+   * ```
+   */
+  async saveTo(path, options) {
+    this.#assertState("ready");
+    await this.#withState("saving", "ready", "ready", async () => {
+      const data = await this.exportDocument(options);
+      await this.#writeToPath(path, data);
+      this.#sourcePath = path;
+    });
+  }
+  /**
+   * Export the document as a Blob or Buffer.
+   *
+   * This is a convenience wrapper around `exportDocx()` that returns
+   * the document data without writing to a file.
+   *
+   * @param options - Export options
+   * @returns Promise resolving to Blob (browser) or Buffer (Node.js)
+   * @throws {InvalidStateError} If editor is not in 'ready' state
+   *
+   * @example
+   * ```typescript
+   * const blob = await editor.exportDocument();
+   *
+   * // Create download link in browser
+   * const url = URL.createObjectURL(blob);
+   * const a = document.createElement('a');
+   * a.href = url;
+   * a.download = 'document.docx';
+   * a.click();
+   * ```
+   */
+  async exportDocument(options) {
+    this.#assertState("ready", "saving");
+    const result = await this.exportDocx({
+      isFinalDoc: options?.isFinalDoc,
+      commentsType: options?.commentsType,
+      comments: options?.comments,
+      fieldsHighlightColor: options?.fieldsHighlightColor
+    });
+    return result;
+  }
+  /**
+   * Writes document data to a file path.
+   *
+   * **Browser behavior:**
+   * In browsers, the `path` parameter is only used as a suggested filename.
+   * The File System Access API shows a save dialog and the user chooses the actual location.
+   *
+   * **Node.js behavior:**
+   * The path is an actual filesystem path, written directly.
+   */
+  async #writeToPath(path, data) {
+    const isNode2 = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" && globalThis.process.versions?.node != null;
+    const hasNodeBuffer = typeof jszip.Buffer !== "undefined" && typeof jszip.Buffer.isBuffer === "function";
+    if (isNode2 || hasNodeBuffer) {
+      try {
+        const fs = require("fs");
+        const buffer = jszip.Buffer.isBuffer(data) ? data : jszip.Buffer.from(await data.arrayBuffer());
+        fs.writeFileSync(path, buffer);
+        return;
+      } catch {
+      }
+    }
+    if (typeof window !== "undefined" && "showSaveFilePicker" in window) {
+      const handle = await window.showSaveFilePicker({
+        suggestedName: path.split("/").pop() || "document.docx",
+        types: [
+          {
+            description: "Word Document",
+            accept: { "application/vnd.openxmlformats-officedocument.wordprocessingml.document": [".docx"] }
+          }
+        ]
+      });
+      const writable = await handle.createWritable();
+      await writable.write(data);
+      await writable.close();
+      return;
+    }
+    throw new FileSystemNotAvailableError(
+      "File System Access API not available. Use exportDocument() to get the document data and handle the download manually."
+    );
+  }
   /**
    * Destroy the editor and clean up resources
    */
   destroy() {
+    if (this.#editorLifecycleState === "ready") {
+      this.close();
+    }
+    if (this.#editorLifecycleState === "destroyed") {
+      return;
+    }
     this.#isDestroyed = true;
     this.emit("destroy");
     this.unmount();
     this.destroyHeaderFooterEditors();
     this.#endCollaboration();
     this.removeAllListeners();
+    this.extensionService = void 0;
+    this.schema = void 0;
+    this.#commandService = void 0;
+    this.#editorLifecycleState = "destroyed";
   }
   destroyHeaderFooterEditors() {
     try {
@@ -16893,7 +17545,7 @@ class Editor extends EventEmitter {
    * Process collaboration migrations
    */
   processCollaborationMigrations() {
-    console.debug("[checkVersionMigrations] Current editor version", "2.0.0-next.22");
+    console.debug("[checkVersionMigrations] Current editor version", "2.0.0-next.23");
     if (!this.options.ydoc) return;
     const metaMap = this.options.ydoc.getMap("meta");
     let docVersion = metaMap.get("version");