@lapis-notes/api 0.1.4 → 0.2.1

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

@@ -1,28 +1,76 @@
-/** Independent file writers implement this contract without importing a renderer. */
+import { FileTextConflictRegistry } from "./file-text-conflicts";
+import { FileEditingNativeIssues } from "./file-editing-native-issues";
+import { NativeEditingRecovery } from "./native-editing-recovery";
+import type { NativeEditingIntents } from "./native-editing-intents";
+import { type NativeEditingSession, type FileEditingRegistration } from "./native-editing-session";
+export type { NativeEditingSession, FileEditingRegistration, } from "./native-editing-session";
+export * from "./file-text-conflicts";
+export * from "./file-text-persistence";
+export type { NativeEditingProblemIssue } from "./file-editing-native-issues";
+/**
+ * Independent file writers implement this contract without importing a
+ * renderer.
+ */
 export interface FileEditingSession {
+    /** Required only when the App selects native editing intents. */
+    readonly native?: NativeEditingSession;
     /** 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. */
+    /**
+     * 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.
+ * 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;
+    private readonly native?;
+    readonly textConflicts: FileTextConflictRegistry;
+    readonly nativeIssues: FileEditingNativeIssues;
+    readonly nativeRecovery: NativeEditingRecovery | undefined;
+    constructor(native?: NativeEditingIntents | undefined);
+    /** Hosts preflight before disposing the App, preserving failed-leave recovery. */
+    preflightNativeRecovery(): Promise<void>;
+    get closed(): boolean;
+    /**
+     * Schedule owned event projection between mutations without acquiring an
+     * editing guard. Guard callbacks may schedule this but must not await it.
+     */
+    afterMutations<T>(operation: () => Promise<T>): Promise<T>;
+    /** Includes retained writers; a failing dirty getter cannot waive protection. */
+    hasDirty(path?: string): boolean;
+    /** Admit a multi-step file operation before its first asynchronous boundary. */
+    track<T>(operation: () => Promise<T>): Promise<T>;
+    /**
+     * Hosts drain admitted operations before entering their global teardown
+     * guard.
+     */
+    settleOperations(): Promise<void>;
+    register(path: string, session: FileEditingSession): FileEditingRegistration;
     /** 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.
+     * 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. */
+    /** Admit a one-shot writer only after existing document writers settle. */
+    mutate(path: string, create: () => FileEditingSession): Promise<void>;
+    /** Recover one retained writer while protecting all other writers of its file. */
+    recover<T>(session: FileEditingSession, operation: () => Promise<T>): Promise<T>;
+    /**
+     * Stop admission immediately, drain callbacks and retry failed
+     * persistence/cleanup.
+     */
     dispose(): Promise<void>;
 }

package/dist/file-editing-sessions.js

@@ -1,3 +1,10 @@
+import { FileTextConflictRegistry } from "./file-text-conflicts";
+import { FileEditingNativeIssues } from "./file-editing-native-issues";
+import { NativeEditingRecovery } from "./native-editing-recovery";
+import { unreportedCleanup } from "./file-editing-failures";
+import { NativeRegisteredEditingSession, } from "./native-editing-session";
+export * from "./file-text-conflicts";
+export * from "./file-text-persistence";
 function filePath(path) {
     if (typeof path !== "string" || /[\\\0]/u.test(path))
         throw new Error("Editing sessions require a vault-relative file path");
@@ -19,18 +26,99 @@ function failures(results) {
     return results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
 }
 /**
- * An App-owned persistence and protection boundary for independent file writers.
- * Hosts must register every writer before selecting this as an apply guard.
+ * An App-owned persistence and protection boundary for independent file
+ * writers. Hosts must register every writer before selecting this as an apply
+ * guard.
  */
 export class FileEditingSessionRegistry {
+    native;
+    textConflicts = new FileTextConflictRegistry();
+    nativeIssues = new FileEditingNativeIssues();
+    nativeRecovery;
     #sessions = new Map();
     #barriers = new Map();
     #releases = new Set();
     #held = new Set();
+    #pendingOperations = new Set();
     #tail = Promise.resolve();
     #closing = false;
     #closed = false;
     #disposal;
+    constructor(native) {
+        this.native = native;
+        this.nativeRecovery = native
+            ? new NativeEditingRecovery(native, (run) => this.track(run))
+            : undefined;
+    }
+    /** Hosts preflight before disposing the App, preserving failed-leave recovery. */
+    async preflightNativeRecovery() {
+        await this.settleOperations();
+        // Observe already admitted work without retrying a failed transition.
+        let tail;
+        do {
+            tail = this.#tail;
+            await tail;
+            await Promise.all([...this.#sessions.values()].map((entry) => entry.native?.settle()));
+        } while (tail !== this.#tail);
+        await this.nativeRecovery?.assertClear();
+        if (this.nativeIssues.entries.length)
+            throw new Error("Unresolved editing admission requires review in Problems");
+    }
+    get closed() {
+        return this.#closing;
+    }
+    /**
+     * Schedule owned event projection between mutations without acquiring an
+     * editing guard. Guard callbacks may schedule this but must not await it.
+     */
+    afterMutations(operation) {
+        return this.#enqueue(operation);
+    }
+    /** Includes retained writers; a failing dirty getter cannot waive protection. */
+    hasDirty(path) {
+        const scope = path === undefined ? undefined : filePath(path);
+        return this.#matching(scope).some(({ session }) => {
+            try {
+                return session.dirty;
+            }
+            catch {
+                return true;
+            }
+        });
+    }
+    /** Admit a multi-step file operation before its first asynchronous boundary. */
+    track(operation) {
+        try {
+            this.#assertOpen();
+            let resolve;
+            let reject;
+            const pending = new Promise((done, fail) => {
+                resolve = done;
+                reject = fail;
+            });
+            this.#pendingOperations.add(pending);
+            void pending.then(() => this.#pendingOperations.delete(pending), () => this.#pendingOperations.delete(pending));
+            try {
+                void operation().then(resolve, reject);
+            }
+            catch (error) {
+                reject(error);
+            }
+            return pending;
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    /**
+     * Hosts drain admitted operations before entering their global teardown
+     * guard.
+     */
+    async settleOperations() {
+        this.#assertOpen();
+        while (this.#pendingOperations.size)
+            await Promise.all([...this.#pendingOperations]);
+    }
     register(path, session) {
         this.#assertOpen();
         const capturedPath = filePath(path);
@@ -46,17 +134,27 @@ export class FileEditingSessionRegistry {
             throw new Error("An editing session cannot change its registered file");
         if (!entry) {
             entry = { path: capturedPath, session, references: 0 };
+            if (this.native) {
+                entry.native = new NativeRegisteredEditingSession(session, this.native, capturedPath, () => this.#closing || entry.references === 0);
+                entry.session = entry.native;
+                this.#observeNativeIssues(entry);
+            }
             this.#sessions.set(session, entry);
         }
         entry.references++;
         let registered = true;
-        return () => {
+        return Object.assign(() => {
             if (!registered)
                 return;
             registered = false;
             entry.references--;
             this.#prune(entry);
-        };
+        }, {
+            native: !!entry.native,
+            ready: () => entry.native?.ready() ?? Promise.resolve(),
+            changed: () => entry.native?.changed(),
+            idle: () => entry.native?.idle() ?? Promise.resolve(),
+        });
     }
     /** Flush the captured sessions; protection is required for mutation admission. */
     async flush(path) {
@@ -78,8 +176,9 @@ export class FileEditingSessionRegistry {
         });
     }
     /**
-     * Serialize mutations, holding matching sessions protected throughout the callback.
-     * Callbacks and session methods must not re-enter queued registry operations.
+     * Serialize mutations, holding matching sessions protected throughout the
+     * callback. Callbacks and session methods must not re-enter queued registry
+     * operations.
      */
     guard(path, operation) {
         try {
@@ -91,7 +190,51 @@ export class FileEditingSessionRegistry {
             return Promise.reject(error);
         }
     }
-    /** Stop admission immediately, drain callbacks and retry failed persistence/cleanup. */
+    /** Admit a one-shot writer only after existing document writers settle. */
+    mutate(path, create) {
+        const scope = filePath(path);
+        return this.guard(scope, async () => {
+            const session = create();
+            if (!session ||
+                typeof session.flush !== "function" ||
+                typeof session.protect !== "function" ||
+                typeof session.dirty !== "boolean")
+                throw new Error("Invalid file editing session");
+            const entry = { path: scope, session, references: 0 };
+            if (this.native) {
+                const native = new NativeRegisteredEditingSession(session, this.native, scope, () => true);
+                Object.assign(entry, { native, session: native });
+                this.#observeNativeIssues(entry);
+            }
+            this.#sessions.set(session, entry);
+            try {
+                await entry.session.flush();
+                if (session.dirty)
+                    throw new Error(`File mutation remains dirty: ${scope}`);
+            }
+            finally {
+                this.#prune(entry);
+            }
+        });
+    }
+    /** Recover one retained writer while protecting all other writers of its file. */
+    recover(session, operation) {
+        const entry = this.#sessions.get(session);
+        if (!entry || this.#closed)
+            return Promise.reject(new Error("File writer is unavailable"));
+        return this.#enqueue(async () => {
+            try {
+                return await this.#guard(entry.path, operation, true, entry);
+            }
+            finally {
+                this.#prune(entry);
+            }
+        }, true);
+    }
+    /**
+     * Stop admission immediately, drain callbacks and retry failed
+     * persistence/cleanup.
+     */
     dispose() {
         if (this.#disposal)
             return this.#disposal;
@@ -101,6 +244,8 @@ export class FileEditingSessionRegistry {
             if (this.#closed)
                 return;
             await this.#guard(undefined, async () => undefined, true);
+            for (const entry of this.#sessions.values())
+                entry.stopNativeIssues?.();
             this.#sessions.clear();
             this.#closed = true;
         })();
@@ -114,9 +259,12 @@ export class FileEditingSessionRegistry {
         if (this.#closing)
             throw new Error("File editing-session registry is closed");
     }
-    #enqueue(operation) {
+    #enqueue(operation, recovery = false) {
         const run = this.#tail.then(() => {
-            this.#assertOpen();
+            if (!recovery)
+                this.#assertOpen();
+            else if (this.#closed)
+                throw new Error("File editing-session registry is closed");
             return operation();
         });
         this.#tail = run.then(() => undefined, () => undefined);
@@ -129,16 +277,38 @@ export class FileEditingSessionRegistry {
         // A detached writer's failed or in-flight persistence remains a barrier.
         if (entry.references ||
             this.#held.has(entry) ||
-            this.#sessions.get(entry.session) !== entry)
+            ![...this.#sessions.values()].includes(entry))
             return;
         try {
-            if (!entry.session.dirty)
-                this.#sessions.delete(entry.session);
+            if (entry.session.dirty)
+                return;
+            if (entry.native && !entry.native.retired) {
+                if (!entry.retirement) {
+                    entry.retirement = this.#enqueue(() => this.#guard(entry.path, async () => undefined), this.#closing);
+                    void entry.retirement.catch(() => {
+                        entry.retirement = undefined;
+                    });
+                }
+                return;
+            }
+            for (const [session, registered] of this.#sessions)
+                if (registered === entry) {
+                    this.#sessions.delete(session);
+                    entry.stopNativeIssues?.();
+                }
         }
         catch {
             // A failing dirty-state getter must not silently remove a writer.
         }
     }
+    #observeNativeIssues(entry) {
+        if (!entry.native)
+            return;
+        entry.stopNativeIssues = this.nativeIssues.register(entry.path, entry.native, (check) => this.track(() => this.#enqueue(async () => {
+            check();
+            await this.#guard(entry.path, async () => undefined);
+        })));
+    }
     async #release(pending) {
         const results = await Promise.allSettled(pending.map(async (lease) => {
             await lease.release();
@@ -151,12 +321,12 @@ export class FileEditingSessionRegistry {
                 this.#barriers.delete(barrier);
         return failures(results);
     }
-    async #guard(path, operation, shutdown = false) {
+    async #guard(path, operation, shutdown = false, excluded) {
         // A previous release failure must be repaired before another mutation starts.
         throwFailures(await this.#release([...this.#releases]));
         const barrier = {};
         this.#barriers.set(barrier, path);
-        const entries = this.#matching(path);
+        const entries = this.#matching(path).filter((entry) => entry !== excluded);
         for (const entry of entries)
             this.#held.add(entry);
         let result;
@@ -184,7 +354,7 @@ export class FileEditingSessionRegistry {
         catch (error) {
             errors.push(error);
         }
-        errors.push(...(await this.#release([...this.#releases].filter((lease) => lease.barrier === barrier))));
+        errors.push(...unreportedCleanup(await this.#release([...this.#releases].filter((lease) => lease.barrier === barrier)), errors));
         for (const entry of entries) {
             if (![...this.#releases].some((lease) => lease.entry === entry)) {
                 this.#held.delete(entry);

package/dist/file-manager.d.ts

@@ -1,6 +1,11 @@
 import type { App } from "./context.svelte";
 import { TFile } from "./storage/fs";
 import type { DataWriteOptions, TAbstractFile, TFolder } from "./storage/fs";
+import { type FileTextMutationOptions } from "./file-text-mutation";
+export type FrontmatterMutationOptions = FileTextMutationOptions & {
+    /** The record shown by a Properties controller before its current edit. */
+    expectedFrontmatter?: Record<string, unknown>;
+};
 /**
  * High-level helpers for vault file operations that need metadata-aware
  * follow-up work.
@@ -31,6 +36,8 @@ export declare class FileManager {
      * @public
      */
     getNewFileParent(sourcePath: string, newFilePath?: string): TFolder;
+    /** New-file intent; exclusive-capable hosts never fall back to overwrite. */
+    createFile(path: string, data: string | ArrayBuffer, options?: DataWriteOptions): Promise<TFile>;
     getAvailablePathForAttachment(filename: string, sourcePath?: string): string;
     /**
      * Rename or move a file safely, and update all links to it depending on the
@@ -87,5 +94,5 @@ export declare class FileManager {
      * @throws Any errors that your callback function throws
      * @public
      */
-    processFrontMatter(file: TFile, fn: (frontmatter: any) => void, options?: DataWriteOptions): Promise<void>;
+    processFrontMatter(file: TFile, fn: (frontmatter: any) => void, options?: FrontmatterMutationOptions): Promise<void>;
 }

package/dist/file-manager.js

@@ -3,6 +3,7 @@ import { TFile } from "./storage/fs";
 import { joinPath } from "./storage/path";
 import { defaultLinkSettings, generateInternalLink, } from "./links";
 import { parseLinktext } from "./utils";
+import { mutateFileText, } from "./file-text-mutation";
 const FRONTMATTER_RETRY_ERROR = "__lapis_frontmatter_retry__";
 function linkOffsets(position) {
     if (!position || typeof position !== "object")
@@ -28,7 +29,9 @@ export class FileManager {
         return JSON.parse(JSON.stringify(frontmatter));
     }
     async readFrontmatterSeed(file, content) {
-        const cachedFrontmatter = (await this.app.metadataCache.getFileCacheAsync(file))?.frontmatter;
+        const cachedFrontmatter = content !== undefined && this.app.vault.supportsConditionalTextWrites
+            ? undefined
+            : (await this.app.metadataCache.getFileCacheAsync(file))?.frontmatter;
         if (cachedFrontmatter && typeof cachedFrontmatter === "object") {
             return this.cloneFrontmatter(cachedFrontmatter);
         }
@@ -151,6 +154,18 @@ export class FileManager {
     getNewFileParent(sourcePath, newFilePath) {
         return this.app.vault.getRoot();
     }
+    /** New-file intent; exclusive-capable hosts never fall back to overwrite. */
+    createFile(path, data, options) {
+        return this.app.fileEditingSessions.track(async () => {
+            await this.app.vault.load();
+            if (this.app.vault.adapter.getCapabilities?.()
+                .exclusiveCreate === true)
+                return this.app.vault.createExclusive(path, data, options);
+            return typeof data === "string"
+                ? this.app.vault.create(path, data, options)
+                : this.app.vault.createBinary(path, data, options);
+        });
+    }
     getAvailablePathForAttachment(filename, sourcePath) {
         const parent = this.getNewFileParent(sourcePath ?? "", filename);
         const extMatch = /(\.[^.]*)$/.exec(filename);
@@ -210,8 +225,13 @@ export class FileManager {
      * @param file
      * @public
      */
-    trashFile(file) {
-        return this.app.vault.trash(file, true);
+    async trashFile(file) {
+        const capturedPath = file.path;
+        await this.app.fileEditingSessions.guard(undefined, async () => {
+            if (file.path !== capturedPath)
+                throw new Error("Trash target changed during editor admission");
+            await this.app.vault.trash(file, true);
+        });
     }
     promptForDeletion(file) {
         return this.trashFile(file);
@@ -268,6 +288,20 @@ export class FileManager {
      * @public
      */
     processFrontMatter(file, fn, options) {
+        if (this.app.vault.supportsConditionalTextWrites) {
+            let matches = true;
+            return mutateFileText(this.app, file, async (snapshot) => {
+                const seed = await this.readFrontmatterSeed(file, snapshot);
+                matches =
+                    options?.expectedFrontmatter === undefined ||
+                        this.isFrontmatterEqual(seed, options.expectedFrontmatter);
+                const next = this.cloneFrontmatter(seed);
+                fn(next);
+                return this.isFrontmatterEqual(seed, next)
+                    ? snapshot
+                    : this.writeUpdatedFrontmatter(file, snapshot, next);
+            }, { ...options, validateBaseline: () => matches });
+        }
         const attempt = async () => {
             const snapshot = await this.app.vault.read(file);
             const seedFrontmatter = await this.readFrontmatterSeed(file, snapshot);

package/dist/file-state-store.d.ts

@@ -0,0 +1,5 @@
+import type { App } from "./context.svelte";
+/** Capture the acknowledged state while the owner loads, before edits begin. */
+export declare function readFileState(app: App, path: string, reset?: (text: string) => void | Promise<void>): Promise<string | null>;
+/** Register synchronously so shutdown cannot overtake initial read or write IO. */
+export declare function saveFileState(app: App, path: string, text: string): Promise<void>;

package/dist/file-state-store.js

@@ -0,0 +1,34 @@
+import { FileTextStateWriter } from "./file-text-state-writer";
+import { TFile } from "./storage/fs";
+import { normalizePath } from "./storage/path";
+const stores = new WeakMap();
+function writer(app, path, baseline, reset = () => { }) {
+    path = normalizePath(path).replace(/^\/+/, "");
+    let store = stores.get(app);
+    if (!store)
+        stores.set(app, (store = new Map()));
+    let entry = store.get(path);
+    if (!entry) {
+        const file = app.vault.getFileByPath(path) ??
+            new TFile(path, { ctime: 0, mtime: 0, size: 0 }, null);
+        entry = new FileTextStateWriter(app, file, baseline, reset, {
+            recoverOutsideQueue: true,
+        });
+        store.set(path, entry);
+    }
+    return entry;
+}
+/** Capture the acknowledged state while the owner loads, before edits begin. */
+export async function readFileState(app, path, reset) {
+    const state = app.vault.supportsConditionalTextWrites
+        ? writer(app, path, undefined, reset)
+        : undefined;
+    const adapter = app.vault.adapter;
+    const text = (await adapter.exists(path)) ? await adapter.read(path) : null;
+    state?.acceptBaseline(text);
+    return text;
+}
+/** Register synchronously so shutdown cannot overtake initial read or write IO. */
+export function saveFileState(app, path, text) {
+    return writer(app, path).set(text);
+}

package/dist/file-text-conflicts.d.ts

@@ -0,0 +1,25 @@
+export type FileTextResolution = "keep-local" | "use-external";
+/** A captured recovery decision; stale objects cannot resolve newer conflicts. */
+export interface FileTextConflict {
+    readonly id: string;
+    readonly path: string;
+    readonly baseline: string | null;
+    readonly local: string;
+    /** Undefined means the authoritative disk read failed; null means deletion. */
+    readonly external: string | null | undefined;
+    readonly readError?: string;
+    resolve(choice: FileTextResolution): Promise<void>;
+    /** Persist reviewed merge text against this exact disk snapshot. */
+    resolveMerged(contents: string): Promise<void>;
+    refresh(): Promise<void>;
+}
+/** App-owned text recovery, independent of the lifetime of individual views. */
+export declare class FileTextConflictRegistry {
+    #private;
+    get entries(): readonly FileTextConflict[];
+    subscribe(listener: (entries: readonly FileTextConflict[]) => void): () => void;
+    /** @internal Writer-owned publication; hosts consume entries and their actions. */
+    publish(conflict: FileTextConflict): void;
+    /** @internal Release only after persistence or an explicit discard succeeds. */
+    clear(id: string): void;
+}

package/dist/file-text-conflicts.js

@@ -0,0 +1,35 @@
+/** App-owned text recovery, independent of the lifetime of individual views. */
+export class FileTextConflictRegistry {
+    #entries = new Map();
+    #listeners = new Set();
+    get entries() {
+        return [...this.#entries.values()];
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        listener(this.entries);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    /** @internal Writer-owned publication; hosts consume entries and their actions. */
+    publish(conflict) {
+        this.#entries.set(conflict.id, Object.freeze(conflict));
+        this.#notify();
+    }
+    /** @internal Release only after persistence or an explicit discard succeeds. */
+    clear(id) {
+        if (this.#entries.delete(id))
+            this.#notify();
+    }
+    #notify() {
+        for (const listener of this.#listeners) {
+            try {
+                listener(this.entries);
+            }
+            catch (error) {
+                console.error("Text conflict subscriber failed", error);
+            }
+        }
+    }
+}

package/dist/file-text-mutation.d.ts

@@ -0,0 +1,13 @@
+import type { App } from "./context.svelte";
+import type { TFile, DataWriteOptions } from "./storage/fs";
+export type FileTextMutationOptions = DataWriteOptions & {
+    /**
+     * A presentation-owned snapshot; omit to transform the authoritative latest
+     * text.
+     */
+    expectedText?: string | null;
+    onSaved?(text: string): void;
+    onReset?(text: string, expected: string | null): void;
+    validateBaseline?(): boolean;
+};
+export declare function mutateFileText(app: App, file: TFile, transform: (text: string) => Promise<string>, options?: FileTextMutationOptions): Promise<void>;