@lapis-notes/api 0.1.3 → 0.2.0

package/dist/diagnostics.js

@@ -58,9 +58,15 @@ export function bindRuntimePluginDiagnostics(plugins, diagnostics) {
             return;
         publish();
     });
+    const unloadedRef = plugins.on("plugin-unloaded", (id) => {
+        if (!pluginFailures.delete(id))
+            return;
+        publish();
+    });
     return () => {
         plugins.offref(errorRef);
         plugins.offref(enabledRef);
+        plugins.offref(unloadedRef);
     };
 }
 export function diagnosticResourceForPath(path) {

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

@@ -0,0 +1,35 @@
+export interface EditorSaveSnapshot {
+    content: string;
+    sequence: number;
+    documentGeneration: number;
+}
+/**
+ * One document's queued saves and failures; the editor supplies shared
+ * serialization.
+ */
+export declare class EditorSaveContext {
+    #private;
+    private readonly options;
+    constructor(options: {
+        serialize(run: () => Promise<void>): Promise<void>;
+        persist(snapshot: EditorSaveSnapshot): Promise<void>;
+        saved(snapshot: EditorSaveSnapshot): void;
+        unownedExternal: boolean;
+        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;
+    cancelChange(): void;
+    flush(retryFailed?: boolean): Promise<void>;
+    retire(): void;
+}

package/dist/editor-save-context.js

@@ -0,0 +1,132 @@
+import debounce from "lodash-es/debounce";
+/**
+ * One document's queued saves and failures; the editor supplies shared
+ * serialization.
+ */
+export class EditorSaveContext {
+    options;
+    #latest;
+    #completed = 0;
+    #failure;
+    #waitingChange;
+    #waitingSave;
+    #pending = new Set();
+    #retired = false;
+    #unverified = false;
+    #change = debounce((snapshot) => {
+        this.#waitingChange = undefined;
+        return this.#enqueue(snapshot);
+    }, 500);
+    #save = debounce((snapshot) => {
+        this.#waitingSave = undefined;
+        return this.#enqueue(snapshot);
+    }, 500);
+    constructor(options) {
+        this.options = options;
+    }
+    get dirty() {
+        return (!!this.#waitingChange ||
+            !!this.#waitingSave ||
+            this.#pending.size > 0 ||
+            !!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)
+            this.#unverified = true;
+        if (explicit) {
+            this.#waitingSave = snapshot;
+            return this.#save(snapshot);
+        }
+        this.#waitingChange = snapshot;
+        return this.#change(snapshot);
+    }
+    flushSave() {
+        return this.#save.flush();
+    }
+    cancelSave() {
+        this.#save.cancel();
+        this.#waitingSave = undefined;
+    }
+    cancelChange() {
+        this.#change.cancel();
+        this.#waitingChange = undefined;
+    }
+    #flushPending() {
+        this.#change.flush();
+        this.#save.flush();
+    }
+    #enqueue(snapshot) {
+        const flight = this.options.serialize(async () => {
+            if (snapshot.sequence <= this.#completed)
+                return;
+            await this.options.persist(snapshot);
+            this.options.saved(snapshot);
+            this.#completed = snapshot.sequence;
+            if (this.#failure && this.#failure.snapshot.sequence <= snapshot.sequence)
+                this.#failure = undefined;
+        });
+        this.#pending.add(flight);
+        // Observe failures even when a debounce caller does not await its result.
+        void flight.then(() => {
+            this.#pending.delete(flight);
+            this.#releaseIfClean();
+        }, (error) => {
+            this.#failure = { snapshot, error };
+            this.#pending.delete(flight);
+        });
+        return flight;
+    }
+    async flush(retryFailed = true) {
+        const retry = this.#failure;
+        this.#flushPending();
+        if (retryFailed && retry && this.#latest === retry.snapshot)
+            this.#enqueue(retry.snapshot);
+        do {
+            await Promise.allSettled([...this.#pending]);
+            this.#flushPending();
+        } while (this.#pending.size > 0);
+        if (this.#failure)
+            throw this.#failure.error;
+        this.#releaseIfClean();
+    }
+    retire() {
+        this.#retired = true;
+        // Retiring a context never replaces another context's debounce payload.
+        this.#flushPending();
+        this.#releaseIfClean();
+    }
+    #releaseIfClean() {
+        if (this.#retired && !this.dirty)
+            this.options.released();
+    }
+}

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.d.ts

@@ -43,6 +43,12 @@ export interface EditorTransaction {
 }
 /** Controls whether an editor persists its own debounced document changes. */
 export type EditorPersistence = "vault" | "external";
+export interface EditorPersistenceRequest {
+    readonly content: string;
+    readonly file: TFile | null;
+    readonly application: App;
+}
+export type EditorPersistenceWriter = (request: EditorPersistenceRequest) => Promise<void>;
 export interface MarkdownFileInfo {
     /** @public */
     app: App;
@@ -70,10 +76,20 @@ export declare class Editor extends EventDispatcher<{
     readonly id: `${string}-${string}-${string}-${string}-${string}`;
     private destroyed;
     private application;
-    private readonly pendingChange;
     constructor(data?: string, extensions?: Extension[], application?: App);
     /** Bind this editor to the application that owns its view. */
     bindApplication(application: App): this;
+    /** Capture an explicit asynchronous owner for external-mode persistence. */
+    setExternalPersistenceWriter(writer?: EditorPersistenceWriter): this;
+    get hasUnsavedChanges(): boolean;
+    get editingProtected(): boolean;
+    get refreshError(): unknown;
+    /** Protect the current document and drain its captured persistence. */
+    protect(): Promise<() => void>;
+    /** Register and protect a target, then publish its file and contents atomically. */
+    loadDocument(file: TFile, read: () => Promise<string>, publish?: (contents: string) => void): Promise<boolean>;
+    /** Cancel a pending publication while observing any late read result. */
+    cancelDocumentLoad(): void;
     /** The owning application, with the global alias retained as fallback. */
     get app(): App;
     readonly save: import("lodash-es").DebouncedFunc<() => Promise<void>>;
@@ -88,6 +104,8 @@ export declare class Editor extends EventDispatcher<{
     getValue(): string;
     refresh(): void;
     destroy(): void;
+    /** Stop editing immediately and await all retained document persistence. */
+    dispose(): Promise<void>;
     trackChanges(callback?: (data: string, editor: Editor) => void): () => void;
     updateExtensions(extensions: Extension[], context?: Record<string, any>): this;
     setValue(content: string): void;