@lapis-notes/api 0.1.4 → 0.2.1

package/dist/editor-save-context.d.ts

@@ -3,7 +3,10 @@ export interface EditorSaveSnapshot {
     sequence: number;
     documentGeneration: number;
 }
-/** One document's queued saves and failures; the editor supplies shared serialization. */
+/**
+ * One document's queued saves and failures; the editor supplies shared
+ * serialization.
+ */
 export declare class EditorSaveContext {
     #private;
     private readonly options;
@@ -15,6 +18,14 @@ export declare class EditorSaveContext {
         released(): void;
     });
     get dirty(): boolean;
+    get latest(): EditorSaveSnapshot | undefined;
+    /** A protected explicit recovery may acknowledge the latest retained snapshot. */
+    accept(snapshot: EditorSaveSnapshot): void;
+    /**
+     * Discard only after the recovery owner has revalidated the external
+     * snapshot.
+     */
+    discard(): void;
     queue(snapshot: EditorSaveSnapshot, explicit?: boolean): Promise<void> | undefined;
     flushSave(): Promise<void> | undefined;
     cancelSave(): void;

package/dist/editor-save-context.js

@@ -1,5 +1,8 @@
 import debounce from "lodash-es/debounce";
-/** One document's queued saves and failures; the editor supplies shared serialization. */
+/**
+ * One document's queued saves and failures; the editor supplies shared
+ * serialization.
+ */
 export class EditorSaveContext {
     options;
     #latest;
@@ -28,6 +31,34 @@ export class EditorSaveContext {
             !!this.#failure ||
             this.#unverified);
     }
+    get latest() {
+        return this.#latest;
+    }
+    /** A protected explicit recovery may acknowledge the latest retained snapshot. */
+    accept(snapshot) {
+        this.#reset();
+        this.#completed = Math.max(this.#completed, snapshot.sequence);
+        this.options.saved(snapshot);
+        this.#releaseIfClean();
+    }
+    /**
+     * Discard only after the recovery owner has revalidated the external
+     * snapshot.
+     */
+    discard() {
+        this.#reset();
+        this.#completed = Math.max(this.#completed, this.#latest?.sequence ?? 0);
+        this.#latest = undefined;
+        this.#releaseIfClean();
+    }
+    #reset() {
+        if (this.#pending.size)
+            throw new Error("Editor recovery requires settled saves");
+        this.cancelChange();
+        this.cancelSave();
+        this.#failure = undefined;
+        this.#unverified = false;
+    }
     queue(snapshot, explicit = false) {
         this.#latest = snapshot;
         if (this.options.unownedExternal)

package/dist/editor-view-registry.d.ts

@@ -1,10 +1,15 @@
 import { EventDispatcher } from "./events";
+export type ExtensionRegistrationOptions = {
+    fileIcon?: string;
+};
 export type EditorViewPriority = "default" | "option" | "exclusive";
 export type EditorViewContribution = {
     id: string;
     viewType?: string;
     label: string;
     description?: string;
+    /** Registered API icon ID used for matching file rows. */
+    fileIcon?: string;
     filenamePatterns?: string[];
     priority?: EditorViewPriority;
     pluginId?: string;
@@ -23,8 +28,13 @@ export type EditorViewRegistryChange = {
 export declare class EditorViewRegistry extends EventDispatcher<{
     changed: [change: EditorViewRegistryChange];
 }> {
+    private readonly layers;
     private readonly views;
     register(contribution: EditorViewContribution): () => void;
+    /** Overlay runtime metadata on the same plugin's admitted manifest entry. */
+    overlay(contribution: EditorViewContribution): () => void;
+    private removeLayer;
+    private setVisible;
     upsert(contribution: EditorViewContribution): () => void;
     update(id: string, contribution: Partial<EditorViewContribution>): boolean;
     removeFilenamePatterns(id: string, patterns: readonly string[]): boolean;

package/dist/editor-view-registry.js

@@ -19,6 +19,7 @@ function normalizeContribution(contribution) {
         id,
         viewType: normalizeString(contribution.viewType ?? id),
         label,
+        fileIcon: contribution.fileIcon?.trim() || undefined,
         filenamePatterns: uniqueStrings(contribution.filenamePatterns),
         priority: contribution.priority ?? "option",
     };
@@ -35,6 +36,7 @@ function mergeContribution(current, next) {
     };
 }
 export class EditorViewRegistry extends EventDispatcher {
+    layers = new Map();
     views = new Map();
     register(contribution) {
         const normalized = normalizeContribution(contribution);
@@ -42,12 +44,48 @@ export class EditorViewRegistry extends EventDispatcher {
             console.warn(`Editor view ${normalized.id} is already registered.`);
             return () => { };
         }
+        const owner = {};
+        this.layers.set(normalized.id, [{ owner, contribution: normalized }]);
         this.views.set(normalized.id, normalized);
         this.emit("changed", { id: normalized.id, action: "registered" });
         return () => {
-            this.unregister(normalized.id);
+            this.removeLayer(normalized.id, owner);
         };
     }
+    /** Overlay runtime metadata on the same plugin's admitted manifest entry. */
+    overlay(contribution) {
+        const current = this.views.get(contribution.id);
+        if (!current)
+            return this.register(contribution);
+        const normalized = mergeContribution(current, contribution);
+        const owner = {};
+        this.layers.get(normalized.id).push({ owner, contribution: normalized });
+        this.views.set(normalized.id, normalized);
+        this.emit("changed", { id: normalized.id, action: "updated" });
+        return () => this.removeLayer(normalized.id, owner);
+    }
+    removeLayer(id, owner) {
+        const entries = this.layers.get(id);
+        const index = entries?.findIndex((entry) => entry.owner === owner) ?? -1;
+        if (!entries || index < 0)
+            return;
+        const visible = index === entries.length - 1;
+        entries.splice(index, 1);
+        if (!entries.length) {
+            this.unregister(id);
+            return;
+        }
+        if (visible) {
+            this.views.set(id, entries.at(-1).contribution);
+            this.emit("changed", { id, action: "updated" });
+        }
+    }
+    setVisible(id, contribution) {
+        this.views.set(id, contribution);
+        const top = this.layers.get(id)?.at(-1);
+        if (top)
+            top.contribution = contribution;
+    }
     upsert(contribution) {
         const normalized = normalizeContribution(contribution);
         const existing = this.views.get(normalized.id);
@@ -55,7 +93,7 @@ export class EditorViewRegistry extends EventDispatcher {
             return this.register(normalized);
         }
         const merged = mergeContribution(existing, normalized);
-        this.views.set(merged.id, merged);
+        this.setVisible(merged.id, merged);
         this.emit("changed", { id: merged.id, action: "updated" });
         return () => { };
     }
@@ -70,7 +108,7 @@ export class EditorViewRegistry extends EventDispatcher {
             id: existing.id,
             label: contribution.label ?? existing.label,
         });
-        this.views.set(existing.id, merged);
+        this.setVisible(existing.id, merged);
         this.emit("changed", { id: existing.id, action: "updated" });
         return true;
     }
@@ -86,14 +124,16 @@ export class EditorViewRegistry extends EventDispatcher {
         }
         if (filenamePatterns.length === 0 && existing.source === "compat") {
             this.views.delete(id);
+            this.layers.delete(id);
             this.emit("changed", { id, action: "unregistered" });
             return true;
         }
-        this.views.set(id, { ...existing, filenamePatterns });
+        this.setVisible(id, { ...existing, filenamePatterns });
         this.emit("changed", { id, action: "updated" });
         return true;
     }
     unregister(id) {
+        this.layers.delete(id);
         const deleted = this.views.delete(id);
         if (deleted) {
             this.emit("changed", { id, action: "unregistered" });

package/dist/editor.svelte.js

@@ -1,10 +1,11 @@
-import { Annotation, Compartment, 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 { 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 {
@@ -50,32 +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;
-                },
-            })),
-            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,
-        ],
+        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,
@@ -169,7 +173,13 @@ export class Editor extends EventDispatcher {
     #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,
@@ -179,15 +189,15 @@ export class Editor extends EventDispatcher {
         };
         document.saves = new EditorSaveContext({
             unownedExternal: persistence === "external" && !writer,
-            serialize: (run) => {
-                const result = this.#writeTail.then(run);
-                this.#writeTail = result.catch(() => undefined);
-                return result;
-            },
+            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 (persistence === "vault" && file)
+                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 });
@@ -209,10 +219,69 @@ export class Editor extends EventDispatcher {
                 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 (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;
                 },
@@ -294,7 +363,10 @@ export class Editor extends EventDispatcher {
             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. */
+    /**
+     * 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");
@@ -331,6 +403,14 @@ export class Editor extends EventDispatcher {
         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,
@@ -427,7 +507,9 @@ export class Editor extends EventDispatcher {
     }
     save = Object.assign(() => {
         this.#assertWritable();
-        return this.#currentDocument().saves.queue(this.captureChange(this.getValue()), true);
+        const document = this.#currentDocument();
+        document.unregister?.changed();
+        return document.saves.queue(this.captureChange(this.getValue()), true);
     }, {
         flush: () => this.#document?.saves.flushSave(),
         cancel: () => {
@@ -444,7 +526,10 @@ export class Editor extends EventDispatcher {
     /** Queue the latest editor contents for persistence/change notification. */
     queueChange(data) {
         this.#assertWritable();
-        this.#currentDocument().saves.queue(this.captureChange(data));
+        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() {
@@ -534,6 +619,8 @@ export class Editor extends EventDispatcher {
                         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 ||
@@ -575,10 +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.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 ?? "" },
@@ -592,6 +679,8 @@ export class Editor extends EventDispatcher {
             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 ?? "");
@@ -609,6 +698,8 @@ export class Editor extends EventDispatcher {
     #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({

package/dist/embed-registry.d.ts

@@ -1,4 +1,5 @@
 import type { App } from "./context.svelte";
+import type { TFile } from "./storage/fs";
 export type EmbedViewHandle = {
     destroy?: () => void | Promise<void>;
 };
@@ -7,9 +8,18 @@ export type EmbedView = (props: {
     containerEl: HTMLElement;
     state: Record<string, any>;
 }) => void | EmbedViewHandle;
+export type MarkdownEmbedContext = {
+    app: App;
+    containerEl: HTMLElement;
+    file: TFile;
+};
+export type MarkdownEmbedder = (props: MarkdownEmbedContext) => false | EmbedViewHandle;
 export declare class EmbedRegistry {
+    #private;
     readonly embedByExtension: Record<string, EmbedView>;
     constructor();
+    registerMarkdownEmbedder(embedder: MarkdownEmbedder): () => void;
+    renderMarkdownEmbed(props: MarkdownEmbedContext): false | EmbedViewHandle;
     register(extension: string, view: EmbedView): () => void;
     get(extension: string): EmbedView | null;
 }

package/dist/embed-registry.js

@@ -1,6 +1,21 @@
 export class EmbedRegistry {
     embedByExtension = {};
+    #markdownEmbedders = [];
     constructor() { }
+    registerMarkdownEmbedder(embedder) {
+        this.#markdownEmbedders = [...this.#markdownEmbedders, embedder];
+        return () => {
+            this.#markdownEmbedders = this.#markdownEmbedders.filter((candidate) => candidate !== embedder);
+        };
+    }
+    renderMarkdownEmbed(props) {
+        for (const embedder of this.#markdownEmbedders) {
+            const handle = embedder(props);
+            if (handle !== false)
+                return handle;
+        }
+        return false;
+    }
     register(extension, view) {
         const normalizedExtension = extension.toLowerCase();
         this.embedByExtension[normalizedExtension] = view;

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

@@ -0,0 +1,2 @@
+/** Keep primary failures intact; cleanup may only re-report their object refs. */
+export declare function unreportedCleanup(cleanup: readonly unknown[], primary: readonly unknown[]): unknown[];

package/dist/file-editing-failures.js

@@ -0,0 +1,29 @@
+/** Keep primary failures intact; cleanup may only re-report their object refs. */
+export function unreportedCleanup(cleanup, primary) {
+    const reported = new Set();
+    const remember = (error) => {
+        if (error === null || typeof error !== "object" || reported.has(error))
+            return;
+        reported.add(error);
+        if (error instanceof AggregateError)
+            error.errors.forEach(remember);
+    };
+    primary.forEach(remember);
+    const retained = (error, ancestors) => {
+        if (reported.has(error))
+            return [];
+        if (!(error instanceof AggregateError) || ancestors.has(error))
+            return [error];
+        const next = new Set(ancestors).add(error);
+        const errors = error.errors.flatMap((child) => retained(child, next));
+        if (errors.length === error.errors.length &&
+            errors.every((child, index) => child === error.errors[index]))
+            return [error];
+        return errors.length
+            ? [
+                new AggregateError(errors, error.message, "cause" in error ? { cause: error.cause } : undefined),
+            ]
+            : [];
+    };
+    return cleanup.flatMap((error) => retained(error, new Set()));
+}

package/dist/file-editing-native-issues.d.ts

@@ -0,0 +1,19 @@
+import type { NativeEditingIssue, NativeRegisteredEditingSession } from "./native-editing-session";
+export interface NativeEditingProblemIssue extends NativeEditingIssue {
+    readonly registration: string;
+}
+type Entry = {
+    path: string;
+    session: NativeRegisteredEditingSession;
+    retry(check: () => void): Promise<void>;
+};
+/** App-local failures remain visible even when native admission never succeeded. */
+export declare class FileEditingNativeIssues {
+    #private;
+    get entries(): readonly NativeEditingProblemIssue[];
+    subscribe(listener: () => void): () => void;
+    /** @internal The editing registry owns registration and its guarded retry. */
+    register(path: string, session: NativeRegisteredEditingSession, retry: Entry["retry"]): () => void;
+    retry(captured: NativeEditingProblemIssue): Promise<void>;
+}
+export {};

package/dist/file-editing-native-issues.js

@@ -0,0 +1,65 @@
+/** App-local failures remain visible even when native admission never succeeded. */
+export class FileEditingNativeIssues {
+    #entries = new Map();
+    #listeners = new Set();
+    get entries() {
+        return [...this.#entries].flatMap(([registration, entry]) => {
+            const issue = entry.session.issue;
+            return issue ? [Object.freeze({ ...issue, registration })] : [];
+        });
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        listener();
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    /** @internal The editing registry owns registration and its guarded retry. */
+    register(path, session, retry) {
+        const registration = crypto.randomUUID();
+        this.#entries.set(registration, { path, session, retry });
+        const stop = session.subscribe(() => this.#notify());
+        this.#notify();
+        return () => {
+            stop();
+            if (this.#entries.delete(registration))
+                this.#notify();
+        };
+    }
+    retry(captured) {
+        try {
+            const entry = this.#require(captured);
+            return entry.retry(() => {
+                this.#require(captured);
+            });
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    #require(captured) {
+        const entry = this.#entries.get(captured.registration);
+        const issue = entry?.session.issue;
+        if (!entry ||
+            entry.path !== captured.path ||
+            !issue ||
+            issue.id !== captured.id ||
+            issue.path !== captured.path ||
+            issue.phase !== captured.phase ||
+            captured.status !== "failed" ||
+            issue.status !== "failed")
+            throw new Error("Editing admission changed; refresh Problems");
+        return entry;
+    }
+    #notify() {
+        for (const listener of this.#listeners) {
+            try {
+                listener();
+            }
+            catch (error) {
+                console.error("Editing admission subscriber failed", error);
+            }
+        }
+    }
+}