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

package/dist/superdoc.umd.js

@@ -35746,7 +35746,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     static getStoredSuperdocVersion(docx) {
       return SuperConverter.getStoredCustomProperty(docx, "SuperdocVersion");
     }
-    static setStoredSuperdocVersion(docx = this.convertedXml, version2 = "2.0.0-next.22") {
+    static setStoredSuperdocVersion(docx = this.convertedXml, version2 = "2.0.0-next.23") {
       return SuperConverter.setStoredCustomProperty(docx, "SuperdocVersion", version2, false);
     }
     /**
@@ -42903,15 +42903,15 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     /** @type {any} */
     eventHandler
   );
-  var define_process_default$a = { env: { NODE_ENV: "production" } };
-  const isNode = typeof define_process_default$a !== "undefined" && define_process_default$a.release && /node|io\.js/.test(define_process_default$a.release.name) && Object.prototype.toString.call(typeof define_process_default$a !== "undefined" ? define_process_default$a : 0) === "[object process]";
+  var define_process_default$b = { env: { NODE_ENV: "production" } };
+  const isNode = typeof define_process_default$b !== "undefined" && define_process_default$b.release && /node|io\.js/.test(define_process_default$b.release.name) && Object.prototype.toString.call(typeof define_process_default$b !== "undefined" ? define_process_default$b : 0) === "[object process]";
   const isBrowser$4 = typeof window !== "undefined" && typeof document !== "undefined" && !isNode;
   let params;
   const computeParams = () => {
     if (params === void 0) {
       if (isNode) {
         params = create$4();
-        const pargs = define_process_default$a.argv;
+        const pargs = define_process_default$b.argv;
         let currParamName = null;
         for (let i2 = 0; i2 < pargs.length; i2++) {
           const parg = pargs[i2];
@@ -42946,12 +42946,12 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     return params;
   };
   const hasParam = (name) => computeParams().has(name);
-  const getVariable = (name) => isNode ? undefinedToNull(define_process_default$a.env[name.toUpperCase().replaceAll("-", "_")]) : undefinedToNull(varStorage.getItem(name));
+  const getVariable = (name) => isNode ? undefinedToNull(define_process_default$b.env[name.toUpperCase().replaceAll("-", "_")]) : undefinedToNull(varStorage.getItem(name));
   const hasConf = (name) => hasParam("--" + name) || getVariable(name) !== null;
   hasConf("production");
-  const forceColor = isNode && isOneOf(define_process_default$a.env.FORCE_COLOR, ["true", "1", "2"]);
+  const forceColor = isNode && isOneOf(define_process_default$b.env.FORCE_COLOR, ["true", "1", "2"]);
   forceColor || !hasParam("--no-colors") && // @todo deprecate --no-colors
-  !hasConf("no-color") && (!isNode || define_process_default$a.stdout.isTTY) && (!isNode || hasParam("--color") || getVariable("COLORTERM") !== null || (getVariable("TERM") || "").includes("color"));
+  !hasConf("no-color") && (!isNode || define_process_default$b.stdout.isTTY) && (!isNode || hasParam("--color") || getVariable("COLORTERM") !== null || (getVariable("TERM") || "").includes("color"));
   const doc$1 = (
     /** @type {Document} */
     typeof document !== "undefined" ? document : {}
@@ -45110,6 +45110,37 @@ Please report this to https://github.com/markedjs/marked.`, e) {
       return new OxmlNode(config2);
     }
   }
+  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 i2 = 0; i2 < items.length; i2 += 1) {
@@ -52701,7 +52732,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     }
     return String(value);
   }
-  var define_process_default$9 = { env: { NODE_ENV: "production" } };
+  var define_process_default$a = { env: { NODE_ENV: "production" } };
   let activeEffectScope;
   class EffectScope {
     constructor(detached = false) {
@@ -53160,7 +53191,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     notify(debugInfo) {
       startBatch();
       try {
-        if (!!(define_process_default$9.env.NODE_ENV !== "production")) ;
+        if (!!(define_process_default$a.env.NODE_ENV !== "production")) ;
         for (let link2 = this.subs; link2; link2 = link2.prevSub) {
           if (link2.sub.notify()) {
             ;
@@ -54308,7 +54339,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     }
     return value;
   }
-  var define_process_default$8 = { env: { NODE_ENV: "production" } };
+  var define_process_default$9 = { env: { NODE_ENV: "production" } };
   const stack$1 = [];
   let isWarning = false;
   function warn$1$1(msg2, ...args) {
@@ -54585,7 +54616,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
       for (flushIndex = 0; flushIndex < queue.length; flushIndex++) {
         const job = queue[flushIndex];
         if (job && !(job.flags & 8)) {
-          if (!!(define_process_default$8.env.NODE_ENV !== "production") && check(job)) ;
+          if (!!(define_process_default$9.env.NODE_ENV !== "production") && check(job)) ;
           if (job.flags & 4) {
             job.flags &= ~1;
           }
@@ -56737,7 +56768,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     try {
       if (vnode.shapeFlag & 4) {
         const proxyToUse = withProxy || proxy;
-        const thisProxy = !!(define_process_default$8.env.NODE_ENV !== "production") && setupState.__isScriptSetup ? new Proxy(proxyToUse, {
+        const thisProxy = !!(define_process_default$9.env.NODE_ENV !== "production") && setupState.__isScriptSetup ? new Proxy(proxyToUse, {
           get(target, key2, receiver) {
             warn$1$1(
               `Property '${String(
@@ -56752,7 +56783,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
             thisProxy,
             proxyToUse,
             renderCache,
-            !!(define_process_default$8.env.NODE_ENV !== "production") ? shallowReadonly(props) : props,
+            !!(define_process_default$9.env.NODE_ENV !== "production") ? shallowReadonly(props) : props,
             setupState,
             data,
             ctx2
@@ -56761,11 +56792,11 @@ Please report this to https://github.com/markedjs/marked.`, e) {
         fallthroughAttrs = attrs;
       } else {
         const render22 = Component;
-        if (!!(define_process_default$8.env.NODE_ENV !== "production") && attrs === props) ;
+        if (!!(define_process_default$9.env.NODE_ENV !== "production") && attrs === props) ;
         result = normalizeVNode(
           render22.length > 1 ? render22(
-            !!(define_process_default$8.env.NODE_ENV !== "production") ? shallowReadonly(props) : props,
-            !!(define_process_default$8.env.NODE_ENV !== "production") ? {
+            !!(define_process_default$9.env.NODE_ENV !== "production") ? shallowReadonly(props) : props,
+            !!(define_process_default$9.env.NODE_ENV !== "production") ? {
               get attrs() {
                 markAttrsAccessed();
                 return shallowReadonly(attrs);
@@ -56774,7 +56805,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
               emit: emit2
             } : { attrs, slots, emit: emit2 }
           ) : render22(
-            !!(define_process_default$8.env.NODE_ENV !== "production") ? shallowReadonly(props) : props,
+            !!(define_process_default$9.env.NODE_ENV !== "production") ? shallowReadonly(props) : props,
             null
           )
         );
@@ -57196,7 +57227,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
       return rawSlot;
     }
     const normalized = withCtx((...args) => {
-      if (!!(define_process_default$8.env.NODE_ENV !== "production") && currentInstance && !(ctx2 === null && currentRenderingInstance) && !(ctx2 && ctx2.root !== currentInstance.root)) ;
+      if (!!(define_process_default$9.env.NODE_ENV !== "production") && currentInstance && !(ctx2 === null && currentRenderingInstance) && !(ctx2 && ctx2.root !== currentInstance.root)) ;
       return normalizeSlotValue(rawSlot(...args));
     }, ctx2);
     normalized._c = false;
@@ -61406,7 +61437,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
       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) {
@@ -61888,16 +61919,40 @@ Please report this to https://github.com/markedjs/marked.`, e) {
       }
     }
   }
+  var define_process_default$8 = { env: { NODE_ENV: "production" } };
   class Editor extends EventEmitter$1 {
     /**
-     * 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 = [];
@@ -62010,18 +62065,25 @@ Please report this to https://github.com/markedjs/marked.`, e) {
       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$1();
       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
@@ -62029,6 +62091,8 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     #commandService;
     #renderer;
     #isDestroyed;
+    #editorLifecycleState;
+    #sourcePath;
     /**
      * Getter which indicates if any changes happen in Editor
      */
@@ -62053,6 +62117,303 @@ Please report this to https://github.com/markedjs/marked.`, e) {
         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 define_process_default$8 !== "undefined" && define_process_default$8.versions?.node) {
+            const fs = require("fs");
+            const buffer2 = fs.readFileSync(source);
+            const [docx, _media, mediaFiles, fonts] = await Editor.loadXmlData(buffer2, true);
+            resolvedOptions.content = docx;
+            resolvedOptions.mediaFiles = mediaFiles;
+            resolvedOptions.fonts = fonts;
+            resolvedOptions.fileSource = buffer2;
+            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 Buffer !== "undefined" && (Buffer.isBuffer(source) || source instanceof 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
      */
@@ -62217,6 +62578,25 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     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.
      *
@@ -62314,19 +62694,19 @@ Please report this to https://github.com/markedjs/marked.`, e) {
       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");
@@ -63374,16 +63754,289 @@ Please report this to https://github.com/markedjs/marked.`, e) {
         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, config2) {
+      const hasElement = config2?.element != null || config2?.selector != null;
+      const resolvedConfig = {
+        mode: "docx",
+        isHeadless: !hasElement,
+        ...config2
+      };
+      const {
+        // OpenOptions (document-level)
+        html: html2,
+        markdown,
+        isCommentsEnabled,
+        suppressDefaultDocxStyles,
+        documentMode,
+        content: content2,
+        mediaFiles,
+        fonts,
+        // Everything else is EditorOptions
+        ...editorConfig
+      } = resolvedConfig;
+      const openOptions = {
+        mode: resolvedConfig.mode,
+        html: html2,
+        markdown,
+        isCommentsEnabled,
+        suppressDefaultDocxStyles,
+        documentMode,
+        content: content2,
+        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(path2, options) {
+      this.#assertState("ready");
+      await this.#withState("saving", "ready", "ready", async () => {
+        const data = await this.exportDocument(options);
+        await this.#writeToPath(path2, data);
+        this.#sourcePath = path2;
+      });
+    }
+    /**
+     * 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(path2, data) {
+      const isNode2 = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" && globalThis.process.versions?.node != null;
+      const hasNodeBuffer = typeof Buffer !== "undefined" && typeof Buffer.isBuffer === "function";
+      if (isNode2 || hasNodeBuffer) {
+        try {
+          const fs = require("fs");
+          const buffer2 = Buffer.isBuffer(data) ? data : Buffer.from(await data.arrayBuffer());
+          fs.writeFileSync(path2, buffer2);
+          return;
+        } catch {
+        }
+      }
+      if (typeof window !== "undefined" && "showSaveFilePicker" in window) {
+        const handle2 = await window.showSaveFilePicker({
+          suggestedName: path2.split("/").pop() || "document.docx",
+          types: [
+            {
+              description: "Word Document",
+              accept: { "application/vnd.openxmlformats-officedocument.wordprocessingml.document": [".docx"] }
+            }
+          ]
+        });
+        const writable = await handle2.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 {
@@ -63415,7 +64068,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
      * 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");
@@ -141731,7 +142384,7 @@ ${reason}`);
       this.config.colors = shuffleArray(this.config.colors);
       this.userColorMap = /* @__PURE__ */ new Map();
       this.colorIndex = 0;
-      this.version = "2.0.0-next.22";
+      this.version = "2.0.0-next.23";
       this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
       this.superdocId = config2.superdocId || v4();
       this.colors = this.config.colors;