@lapis-notes/api 0.1.3 → 0.2.0

package/dist/editor.svelte.js

@@ -1,9 +1,11 @@
-import { Annotation, EditorState, Transaction, StateField, EditorSelection as CodeMirrorSelection, } from "@codemirror/state";
+import { Annotation, Compartment, EditorState, StateEffect, Transaction, StateField, EditorSelection as CodeMirrorSelection, } from "@codemirror/state";
 import { EditorView } from "@codemirror/view";
 import { redo as redoCommand, undo as undoCommand } from "@codemirror/commands";
 import { EventDispatcher } from "./events";
-import debounce from "lodash-es/debounce";
+import { tick } from "svelte";
+import { EditorSaveContext, } from "./editor-save-context";
 import { resolveApplication } from "./application-compatibility";
+import { FileTextPersistence } from "./file-text-persistence";
 export const editorViewField = StateField.define({
     create() {
         return {
@@ -49,26 +51,35 @@ export function createEditorState(editor, doc, extensions = [], selection) {
     return EditorState.create({
         doc,
         selection,
-        extensions: [
-            editorViewField.init(() => ({
-                get app() {
-                    return editor.app;
-                },
-                editor,
-                get file() {
-                    return editor.file;
-                },
-            })),
-            EditorView.updateListener.of((v) => {
-                if (v.docChanged &&
-                    !v.transactions.some((it) => it.annotation(syncAnnotation))) {
-                    editor.queueChange(v.state.doc.toString());
-                }
-            }),
-            ...extensions,
-        ],
+        extensions: editorStateExtensions(editor, extensions),
     });
 }
+function editorStateExtensions(editor, extensions) {
+    return [
+        editorViewField.init(() => ({
+            get app() {
+                return editor.app;
+            },
+            editor,
+            get file() {
+                return editor.file;
+            },
+        })),
+        editor.protectionExtensions(),
+        EditorState.transactionFilter.of((transaction) => transaction.docChanged &&
+            editor.editingProtected &&
+            !transaction.annotation(syncAnnotation)
+            ? []
+            : transaction),
+        EditorView.updateListener.of((v) => {
+            if (v.docChanged &&
+                !v.transactions.some((it) => it.annotation(syncAnnotation))) {
+                editor.queueChange(v.state.doc.toString());
+            }
+        }),
+        ...extensions,
+    ];
+}
 export function createEditor(editor, doc, ...extensions) {
     return new EditorView({
         doc,
@@ -97,21 +108,380 @@ export class Editor extends EventDispatcher {
     data;
     extensions;
     view;
-    file = $state(null);
-    persistence = "vault";
+    #file = $state.raw(null);
+    #persistence = "vault";
+    #externalWriter;
+    #editingProtected = $state(0);
+    #protection = new Compartment();
+    #documents = new Set();
+    #document;
     id = crypto.randomUUID();
     destroyed = false;
     application;
-    pendingChange = debounce(async (content) => {
-        if (this.data === content) {
+    #writeTail = Promise.resolve();
+    #sequence = 0;
+    #completedSequence = 0;
+    #documentGeneration = 0;
+    #fileReadGeneration = 0;
+    #refreshError;
+    #loading;
+    #controlledLoad = false;
+    get file() {
+        return this.#file;
+    }
+    set file(file) {
+        if (file === this.#file && file?.path === this.#document?.path)
+            return;
+        this.#assertWritable();
+        const next = this.#createDocument(this.app, file, this.#persistence, this.#externalWriter);
+        this.#retireDocument();
+        this.#file = file;
+        this.#document = next;
+        this.#documentGeneration++;
+    }
+    get persistence() {
+        return this.#persistence;
+    }
+    set persistence(value) {
+        if (value === this.#persistence)
             return;
+        this.#assertWritable();
+        const next = this.#createDocument(this.app, this.#file, value, this.#externalWriter);
+        this.#retireDocument();
+        this.#persistence = value;
+        this.#document = next;
+        this.#documentGeneration++;
+    }
+    /** Capture an explicit asynchronous owner for external-mode persistence. */
+    setExternalPersistenceWriter(writer) {
+        if (writer === this.#externalWriter)
+            return this;
+        this.#assertWritable();
+        const next = this.#createDocument(this.app, this.#file, this.#persistence, writer);
+        this.#retireDocument();
+        this.#externalWriter = writer;
+        this.#document = next;
+        this.#documentGeneration++;
+        return this;
+    }
+    #assertWritable() {
+        if (this.destroyed)
+            throw new Error("Editor is destroyed");
+        if (this.editingProtected)
+            throw new Error("Editor editing is protected");
+    }
+    #retireDocument() {
+        this.#document?.saves.retire();
+    }
+    #serializeWrite(run) {
+        const result = this.#writeTail.then(run);
+        this.#writeTail = result.catch(() => undefined);
+        return result;
+    }
+    #createDocument(application, file, persistence, writer) {
+        const initialText = this.data;
+        const document = {
+            application,
+            file,
+            path: file?.path,
+            persistence,
+            writer,
+        };
+        document.saves = new EditorSaveContext({
+            unownedExternal: persistence === "external" && !writer,
+            serialize: (run) => this.#serializeWrite(run),
+            persist: async (snapshot) => {
+                if (document.unregister?.native)
+                    await document.unregister.ready();
+                if (file?.path !== document.path)
+                    throw new Error("Editor persistence target changed");
+                if (document.text)
+                    await document.text.persist(snapshot.content);
+                else if (persistence === "vault" && file)
+                    await application.vault.modify(file, snapshot.content);
+                else if (persistence === "external" && writer)
+                    await writer({ application, file, content: snapshot.content });
+            },
+            saved: (snapshot) => {
+                this.#completedSequence = Math.max(this.#completedSequence, snapshot.sequence);
+                if (!this.destroyed &&
+                    this.#document === document &&
+                    this.app === application &&
+                    this.file === file &&
+                    snapshot.documentGeneration === this.#documentGeneration) {
+                    this.data = snapshot.content;
+                    if (snapshot.content === this.getValue())
+                        this.onChange(snapshot.content);
+                }
+            },
+            released: () => {
+                document.unregister?.();
+                this.#documents.delete(document);
+            },
+        });
+        if (persistence === "vault" &&
+            file &&
+            application.vault.supportsConditionalTextWrites) {
+            document.text = new FileTextPersistence({
+                vault: application.vault,
+                file,
+                baseline: this.data,
+                conflicts: application.fileEditingSessions.textConflicts,
+                local: () => document.saves.latest?.content ?? this.data,
+                protect: () => ({
+                    release: !this.destroyed && this.#document === document
+                        ? this.#holdEditing()
+                        : () => undefined,
+                    saved: () => {
+                        const snapshot = document.saves.latest;
+                        if (!snapshot)
+                            throw new Error("No retained editor snapshot");
+                        document.saves.accept(snapshot);
+                    },
+                    reset: (contents) => {
+                        if (!this.destroyed && this.#document === document) {
+                            this.#replaceContent(contents);
+                            this.onChange(contents);
+                        }
+                        document.saves.discard();
+                    },
+                }),
+                settle: async () => {
+                    await document.loading;
+                    try {
+                        await document.saves.flush(false);
+                    }
+                    catch (error) {
+                        if (!document.text?.hasConflict)
+                            throw error;
+                    }
+                },
+                serialize: (run) => this.#serializeWrite(run),
+            });
         }
-        if (this.file && this.persistence === "vault") {
-            await this.app.vault.modify(this.file, content);
+        if (file) {
+            if (!application.fileEditingSessions)
+                throw new Error("App has no file editing-session registry");
+            document.unregister = application.fileEditingSessions.register(file.path, {
+                native: {
+                    hold: () => this.#holdEditing(),
+                    savedText: () => document.text
+                        ? document.text.baseline
+                        : (document.saves.latest?.content ?? initialText),
+                    refreshSavedText: (contents) => {
+                        if (document.loading || document.saves.dirty || !document.text)
+                            throw new Error("Native editor refresh requires clean conditional text authority");
+                        document.text.acceptBaseline(contents);
+                        if (!this.destroyed &&
+                            this.#document === document &&
+                            contents !== null) {
+                            if (this.getValue() !== contents)
+                                this.#replaceContent(contents);
+                            this.data = contents;
+                            this.onChange(contents);
+                        }
+                    },
+                },
+                get dirty() {
+                    return !!document.loading || document.saves.dirty;
+                },
+                flush: async () => {
+                    await document.loading;
+                    await document.saves.flush();
+                },
+                protect: () => this.#protectDocument(document),
+            });
         }
-        this.data = content;
-        this.onChange(content);
-    }, 500);
+        this.#documents.add(document);
+        return document;
+    }
+    #currentDocument() {
+        return (this.#document ??= this.#createDocument(this.app, this.file, this.persistence, this.#externalWriter));
+    }
+    captureChange(content) {
+        return {
+            content,
+            documentGeneration: this.#documentGeneration,
+            sequence: ++this.#sequence,
+        };
+    }
+    get hasUnsavedChanges() {
+        return ((!this.destroyed && this.getValue() !== this.data) ||
+            [...this.#documents].some((document) => document.saves.dirty));
+    }
+    get editingProtected() {
+        return this.destroyed || this.#editingProtected > 0;
+    }
+    /** Native CodeMirror protection, retained whenever editor state is rebuilt. */
+    protectionExtensions() {
+        return this.#protection.of([
+            EditorState.readOnly.of(this.editingProtected),
+            EditorView.editable.of(!this.editingProtected),
+        ]);
+    }
+    #holdEditing() {
+        this.#editingProtected++;
+        this.#updateProtection();
+        let held = true;
+        return () => {
+            if (!held)
+                return;
+            held = false;
+            this.#editingProtected--;
+            this.#updateProtection();
+        };
+    }
+    #updateProtection() {
+        if (!this.destroyed)
+            this.view.dispatch({
+                effects: this.#protection.reconfigure([
+                    EditorState.readOnly.of(this.editingProtected),
+                    EditorView.editable.of(!this.editingProtected),
+                ]),
+            });
+    }
+    async #protectDocument(document) {
+        if (document.persistence === "external" && !document.writer)
+            throw new Error("External editor persistence requires an explicit writer for protection");
+        const release = !this.destroyed && (this.#document === document || !!document.loading)
+            ? this.#holdEditing()
+            : () => undefined;
+        try {
+            await tick();
+            await document.loading;
+            await document.saves.flush();
+            return release;
+        }
+        catch (error) {
+            release();
+            throw error;
+        }
+    }
+    /** Protect the current document and drain its captured persistence. */
+    protect() {
+        if (this.destroyed)
+            return Promise.reject(new Error("Editor is destroyed"));
+        return this.#protectDocument(this.#currentDocument());
+    }
+    /**
+     * Register and protect a target, then publish its file and contents
+     * atomically.
+     */
+    async loadDocument(file, read, publish) {
+        if (this.destroyed)
+            throw new Error("Editor is destroyed");
+        if (this.#editingProtected > (this.#loading ? 1 : 0))
+            throw new Error("Editor editing is protected");
+        const application = this.app, path = file.path;
+        // Admission failure leaves any previous load and binding untouched.
+        const document = this.#createDocument(application, file, this.persistence, this.#externalWriter);
+        const release = this.#holdEditing();
+        let cancelRead;
+        const cancellation = new Promise((resolve) => {
+            cancelRead = resolve;
+        });
+        let finish;
+        document.loading = new Promise((resolve) => {
+            finish = resolve;
+        });
+        let canceled = false, completed = false;
+        const load = {
+            cancel: () => {
+                if (completed || canceled)
+                    return;
+                canceled = true;
+                cancelRead({ canceled: true });
+                document.loading = undefined;
+                document.saves.retire();
+                finish();
+                release();
+                if (this.#loading === load)
+                    this.#loading = undefined;
+            },
+        };
+        this.#loading?.cancel();
+        this.#loading = load;
+        let published = false;
+        try {
+            if (document.unregister?.native) {
+                const admission = await Promise.race([
+                    document.unregister.ready().then(() => ({ ready: true })),
+                    cancellation,
+                ]);
+                if ("canceled" in admission || canceled)
+                    return false;
+            }
+            const drained = await Promise.race([
+                this.flushChanges().then(() => ({ drained: true })),
+                cancellation,
+            ]);
+            if ("canceled" in drained || canceled)
+                return false;
+            const result = await Promise.race([
+                Promise.resolve()
+                    .then(read)
+                    .then((contents) => ({ contents })),
+                cancellation,
+            ]);
+            if ("canceled" in result || canceled)
+                return false;
+            if (this.destroyed || this.app !== application || file.path !== path)
+                throw new Error("Editor document load authority changed");
+            const previous = {
+                document: this.#document,
+                file: this.#file,
+                data: this.data,
+                state: this.view.state,
+                extensions: this.extensions,
+            };
+            this.#document = document;
+            this.#file = file;
+            try {
+                this.#controlledLoad = true;
+                this.setValue(result.contents);
+                publish?.(result.contents);
+                if (this.destroyed || canceled)
+                    throw new Error("Editor document load canceled during publication");
+                if (this.app !== application || file.path !== path)
+                    throw new Error("Editor document load authority changed");
+                published = true;
+                previous.document?.saves.retire();
+            }
+            catch (error) {
+                this.#document = previous.document;
+                this.#file = previous.file;
+                this.data = previous.data;
+                this.extensions = previous.extensions;
+                this.#documentGeneration++;
+                if (!this.destroyed)
+                    this.view.setState(previous.state);
+                throw error;
+            }
+            finally {
+                this.#controlledLoad = false;
+            }
+            return true;
+        }
+        finally {
+            if (!canceled) {
+                completed = true;
+                document.loading = undefined;
+                if (!published)
+                    document.saves.retire();
+                finish();
+                release();
+            }
+            if (this.#loading === load)
+                this.#loading = undefined;
+        }
+    }
+    /** Cancel a pending publication while observing any late read result. */
+    cancelDocumentLoad() {
+        this.#loading?.cancel();
+    }
+    get refreshError() {
+        return this.#refreshError;
+    }
     constructor(data = "", extensions = [], application) {
         super();
         this.data = data;
@@ -121,19 +491,32 @@ export class Editor extends EventDispatcher {
     }
     /** Bind this editor to the application that owns its view. */
     bindApplication(application) {
+        if (this.application === application)
+            return this;
+        this.#assertWritable();
+        const next = this.#createDocument(application, this.#file, this.#persistence, this.#externalWriter);
+        this.#retireDocument();
         this.application = application;
+        this.#document = next;
+        this.#documentGeneration++;
         return this;
     }
     /** The owning application, with the global alias retained as fallback. */
     get app() {
         return resolveApplication(this.application);
     }
-    save = debounce(() => {
-        if (this.file) {
-            return this.app.vault.modify(this.file, this.getValue());
-        }
-        return Promise.resolve();
-    }, 500);
+    save = Object.assign(() => {
+        this.#assertWritable();
+        const document = this.#currentDocument();
+        document.unregister?.changed();
+        return document.saves.queue(this.captureChange(this.getValue()), true);
+    }, {
+        flush: () => this.#document?.saves.flushSave(),
+        cancel: () => {
+            this.#assertWritable();
+            this.#document?.saves.cancelSave();
+        },
+    });
     get cm() {
         return this.view;
     }
@@ -142,15 +525,41 @@ export class Editor extends EventDispatcher {
     }
     /** Queue the latest editor contents for persistence/change notification. */
     queueChange(data) {
-        this.pendingChange(data);
-    }
-    /** Flush the latest queued change before a view or embedded surface closes. */
-    flushChanges() {
-        return Promise.resolve(this.pendingChange.flush()).then(() => undefined);
+        this.#assertWritable();
+        const document = this.#currentDocument();
+        document.unregister?.changed();
+        document.saves.queue(this.captureChange(data));
+        document.text?.updateLocal(data);
+    }
+    /** Drain every captured document, including failed or retired saves. */
+    async flushChanges() {
+        const errors = new Map();
+        const visited = new Set();
+        let sequence, generation;
+        do {
+            sequence = this.#sequence;
+            generation = this.#documentGeneration;
+            const documents = [...this.#documents];
+            const results = await Promise.allSettled(documents.map((document) => {
+                const retry = !visited.has(document);
+                visited.add(document);
+                return document.saves.flush(retry);
+            }));
+            results.forEach((result, index) => {
+                if (result.status === "rejected")
+                    errors.set(documents[index], result.reason);
+            });
+        } while (sequence !== this.#sequence ||
+            generation !== this.#documentGeneration);
+        if (errors.size === 1)
+            throw errors.values().next().value;
+        if (errors.size)
+            throw new AggregateError([...errors.values()], "Editor persistence failed");
     }
     /** Cancel a queued change when the owning document is intentionally reset. */
     cancelPendingChanges() {
-        this.pendingChange.cancel();
+        this.#assertWritable();
+        this.#document?.saves.cancelChange();
     }
     getValue() {
         return this.view.state.doc.toString();
@@ -159,16 +568,25 @@ export class Editor extends EventDispatcher {
         this.view.requestMeasure();
     }
     destroy() {
-        if (this.destroyed) {
+        if (this.destroyed)
             return;
-        }
         this.destroyed = true;
-        this.pendingChange.cancel();
-        this.save.cancel();
+        this.cancelDocumentLoad();
+        for (const document of this.#documents)
+            document.saves.retire();
         this.view.destroy();
     }
+    /** Stop editing immediately and await all retained document persistence. */
+    async dispose() {
+        this.destroy();
+        await this.flushChanges();
+    }
     trackChanges(callback) {
-        const editorUpdated = this.app.workspace.on("editor-updated", (editor, transactions) => {
+        const owner = this.app;
+        let active = true;
+        const editorUpdated = owner.workspace.on("editor-updated", (editor, transactions) => {
+            if (!active || this.destroyed || this.app !== owner)
+                return;
             if (editor.id !== this.id && editor.file?.path === this.file?.path) {
                 if (this.getValue() !== editor.getValue()) {
                     this.view.dispatch(...transactions);
@@ -177,22 +595,62 @@ export class Editor extends EventDispatcher {
                 }
             }
         });
-        const fileChanged = this.app.workspace.on("file-change", (file, event) => {
+        const fileChanged = owner.workspace.on("file-change", (file, event) => {
+            if (!active || this.destroyed || this.app !== owner)
+                return;
             if (file.path === this.file?.path) {
                 if (event !== "delete" && file) {
-                    this.app.vault.read(file).then((contents) => {
+                    const application = this.app, target = this.file, path = target?.path;
+                    const readGeneration = ++this.#fileReadGeneration, documentGeneration = this.#documentGeneration;
+                    const sequence = this.#sequence, completed = this.#completedSequence;
+                    void application.vault
+                        .read(file)
+                        .then((contents) => {
+                        if (!active ||
+                            this.destroyed ||
+                            this.app !== application ||
+                            this.file !== target ||
+                            this.file?.path !== path ||
+                            this.#fileReadGeneration !== readGeneration ||
+                            this.#documentGeneration !== documentGeneration ||
+                            this.#sequence !== sequence ||
+                            this.#completedSequence !== completed)
+                            return;
+                        this.#refreshError = undefined;
+                        if (this.getValue() === contents) {
+                            this.data = contents;
+                            if (!this.#document?.saves.dirty)
+                                this.#document?.text?.acceptBaseline(contents);
+                            return;
+                        }
+                        if (this.getValue() !== this.data ||
+                            this.#document?.saves.dirty)
+                            return;
                         if (this.getValue() !== contents) {
-                            this.replaceContent(contents);
+                            this.#replaceContent(contents);
                             this.onChange(this.getValue());
                             callback?.(this.getValue(), this);
                         }
+                    })
+                        .catch((error) => {
+                        if (active &&
+                            !this.destroyed &&
+                            this.app === application &&
+                            this.file?.path === path &&
+                            this.#fileReadGeneration === readGeneration &&
+                            this.file === target &&
+                            this.#documentGeneration === documentGeneration &&
+                            this.#sequence === sequence &&
+                            this.#completedSequence === completed)
+                            this.#refreshError = error;
                     });
                 }
             }
         });
         return () => {
-            this.app.workspace.offref(editorUpdated);
-            this.app.workspace.offref(fileChanged);
+            active = false;
+            owner.workspace.offref(editorUpdated);
+            owner.workspace.offref(fileChanged);
         };
     }
     updateExtensions(extensions, context) {
@@ -204,11 +662,10 @@ export class Editor extends EventDispatcher {
             }
             span.setAttribute("editor.extension_count", editorExtensions.length);
             span.setAttribute("file.extension", ext ?? "");
-            const content = this.getValue();
-            const selection = this.view.state.selection;
             this.extensions = editorExtensions;
-            this.data = content;
-            this.view.setState(createEditorState(this, content, this.extensions, selection));
+            this.view.dispatch({
+                effects: StateEffect.reconfigure.of(editorStateExtensions(this, this.extensions)),
+            });
             return this;
         }, {
             attributes: { "file.extension": this.file?.extension ?? "" },
@@ -216,6 +673,14 @@ export class Editor extends EventDispatcher {
         });
     }
     setValue(content) {
+        if (!this.#controlledLoad)
+            this.#assertWritable();
+        else if (this.destroyed)
+            throw new Error("Editor is destroyed");
+        this.#documentGeneration++;
+        this.#refreshError = undefined;
+        if (!this.#document?.saves.dirty)
+            this.#document?.text?.acceptBaseline(content);
         this.app.telemetry.measure("editor.set_value", (span) => {
             span.setAttribute("editor.content_length", content.length);
             span.setAttribute("file.extension", this.file?.extension ?? "");
@@ -227,6 +692,14 @@ export class Editor extends EventDispatcher {
         });
     }
     replaceContent(content, options = {}) {
+        this.#assertWritable();
+        this.#replaceContent(content, options);
+    }
+    #replaceContent(content, options = {}) {
+        this.#documentGeneration++;
+        this.#refreshError = undefined;
+        if (!this.#document?.saves.dirty)
+            this.#document?.text?.acceptBaseline(content);
         this.data = content;
         const annotations = [syncAnnotation.of(true)];
         this.view.dispatch({