@lapis-notes/api 0.1.3 → 0.1.4

package/dist/editor.svelte.js

@@ -1,8 +1,9 @@
-import { Annotation, EditorState, Transaction, StateField, EditorSelection as CodeMirrorSelection, } from "@codemirror/state";
+import { Annotation, Compartment, EditorState, 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";
 export const editorViewField = StateField.define({
     create() {
@@ -59,6 +60,12 @@ export function createEditorState(editor, doc, extensions = [], selection) {
                     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))) {
@@ -97,21 +104,304 @@ 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();
+    }
+    #createDocument(application, file, persistence, writer) {
+        const document = {
+            application,
+            file,
+            path: file?.path,
+            persistence,
+            writer,
+        };
+        document.saves = new EditorSaveContext({
+            unownedExternal: persistence === "external" && !writer,
+            serialize: (run) => {
+                const result = this.#writeTail.then(run);
+                this.#writeTail = result.catch(() => undefined);
+                return result;
+            },
+            persist: async (snapshot) => {
+                if (file?.path !== document.path)
+                    throw new Error("Editor persistence target changed");
+                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 (file) {
+            if (!application.fileEditingSessions)
+                throw new Error("App has no file editing-session registry");
+            document.unregister = application.fileEditingSessions.register(file.path, {
+                get dirty() {
+                    return !!document.loading || document.saves.dirty;
+                },
+                flush: async () => {
+                    await document.loading;
+                    await document.saves.flush();
+                },
+                protect: () => this.#protectDocument(document),
+            });
         }
-        if (this.file && this.persistence === "vault") {
-            await this.app.vault.modify(this.file, content);
+        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;
         }
-        this.data = content;
-        this.onChange(content);
-    }, 500);
+        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 {
+            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 +411,30 @@ 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();
+        return this.#currentDocument().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 +443,38 @@ 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();
+        this.#currentDocument().saves.queue(this.captureChange(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 +483,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 +510,60 @@ 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;
+                            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) {
@@ -207,7 +578,6 @@ export class Editor extends EventDispatcher {
             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));
             return this;
         }, {
@@ -216,6 +586,12 @@ 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;
         this.app.telemetry.measure("editor.set_value", (span) => {
             span.setAttribute("editor.content_length", content.length);
             span.setAttribute("file.extension", this.file?.extension ?? "");
@@ -227,6 +603,12 @@ export class Editor extends EventDispatcher {
         });
     }
     replaceContent(content, options = {}) {
+        this.#assertWritable();
+        this.#replaceContent(content, options);
+    }
+    #replaceContent(content, options = {}) {
+        this.#documentGeneration++;
+        this.#refreshError = undefined;
         this.data = content;
         const annotations = [syncAnnotation.of(true)];
         this.view.dispatch({

package/dist/file-editing-sessions.d.ts

@@ -0,0 +1,28 @@
+/** Independent file writers implement this contract without importing a renderer. */
+export interface FileEditingSession {
+    /** Includes queued, in-flight and failed persistence. */
+    readonly dirty: boolean;
+    flush(): Promise<void>;
+    /** Block edits before yielding; drain pending saves and return an idempotent release. */
+    protect(): Promise<() => void | Promise<void>>;
+}
+/**
+ * An App-owned persistence and protection boundary for independent file writers.
+ * Hosts must register every writer before selecting this as an apply guard.
+ */
+export declare class FileEditingSessionRegistry {
+    #private;
+    register(path: string, session: FileEditingSession): () => void;
+    /** Flush the captured sessions; protection is required for mutation admission. */
+    flush(path?: string): Promise<{
+        flushed: boolean;
+        path?: string;
+    }>;
+    /**
+     * Serialize mutations, holding matching sessions protected throughout the callback.
+     * Callbacks and session methods must not re-enter queued registry operations.
+     */
+    guard<T>(path: string | undefined, operation: () => Promise<T>): Promise<T>;
+    /** Stop admission immediately, drain callbacks and retry failed persistence/cleanup. */
+    dispose(): Promise<void>;
+}