@lapis-notes/api 0.1.3 → 0.2.0

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);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,76 @@
+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.
+     */
+    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;
+    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.
+     */
+    guard<T>(path: string | undefined, operation: () => Promise<T>): Promise<T>;
+    /** 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

@@ -0,0 +1,367 @@
+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");
+    const parts = path
+        .replace(/^\/+/, "")
+        .split("/")
+        .filter((part) => part !== "." && part !== "");
+    if (!parts.length || parts.some((part) => part === ".."))
+        throw new Error("Editing sessions require a vault-relative file path");
+    return parts.join("/");
+}
+function throwFailures(errors) {
+    if (errors.length === 1)
+        throw errors[0];
+    if (errors.length)
+        throw new AggregateError(errors, "File editing-session cleanup failed");
+}
+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.
+ */
+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);
+        if ([...this.#barriers.values()].some((scope) => scope === undefined || scope === capturedPath))
+            throw new Error(`File editing is protected: ${capturedPath}`);
+        if (!session ||
+            typeof session.flush !== "function" ||
+            typeof session.protect !== "function" ||
+            typeof session.dirty !== "boolean")
+            throw new Error("Invalid file editing session");
+        let entry = this.#sessions.get(session);
+        if (entry && entry.path !== capturedPath)
+            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 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) {
+        this.#assertOpen();
+        const scope = path === undefined ? undefined : filePath(path);
+        return this.#enqueue(async () => {
+            const entries = this.#matching(scope);
+            const results = await Promise.allSettled(entries.map(async (entry) => {
+                await entry.session.flush();
+                if (entry.session.dirty)
+                    throw new Error(`File editing session remains dirty: ${entry.path}`);
+                this.#prune(entry);
+            }));
+            throwFailures(failures(results));
+            return {
+                flushed: entries.length > 0,
+                ...(scope === undefined ? {} : { path: scope }),
+            };
+        });
+    }
+    /**
+     * Serialize mutations, holding matching sessions protected throughout the
+     * callback. Callbacks and session methods must not re-enter queued registry
+     * operations.
+     */
+    guard(path, operation) {
+        try {
+            this.#assertOpen();
+            const scope = path === undefined ? undefined : filePath(path);
+            return this.#enqueue(() => this.#guard(scope, operation));
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    /** 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;
+        this.#closing = true;
+        this.#disposal = (async () => {
+            await this.#tail;
+            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;
+        })();
+        // Keep closure permanent, but allow explicitly requested cleanup retries.
+        void this.#disposal.catch(() => {
+            this.#disposal = undefined;
+        });
+        return this.#disposal;
+    }
+    #assertOpen() {
+        if (this.#closing)
+            throw new Error("File editing-session registry is closed");
+    }
+    #enqueue(operation, recovery = false) {
+        const run = this.#tail.then(() => {
+            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);
+        return run;
+    }
+    #matching(path) {
+        return [...this.#sessions.values()].filter((entry) => path === undefined || entry.path === path);
+    }
+    #prune(entry) {
+        // A detached writer's failed or in-flight persistence remains a barrier.
+        if (entry.references ||
+            this.#held.has(entry) ||
+            ![...this.#sessions.values()].includes(entry))
+            return;
+        try {
+            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();
+            this.#releases.delete(lease);
+            this.#held.delete(lease.entry);
+            this.#prune(lease.entry);
+        }));
+        for (const barrier of this.#barriers.keys())
+            if (![...this.#releases].some((lease) => lease.barrier === barrier))
+                this.#barriers.delete(barrier);
+        return failures(results);
+    }
+    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).filter((entry) => entry !== excluded);
+        for (const entry of entries)
+            this.#held.add(entry);
+        let result;
+        const errors = [];
+        try {
+            const protectedEntries = [];
+            const admission = await Promise.allSettled(entries.map(async (entry) => {
+                const release = await entry.session.protect();
+                if (typeof release !== "function")
+                    throw new Error("Invalid editing-session protection release");
+                this.#releases.add({ barrier, entry, release });
+                protectedEntries.push(entry);
+            }));
+            const saved = await Promise.allSettled(protectedEntries.map(async (entry) => {
+                await entry.session.flush();
+                if (entry.session.dirty)
+                    throw new Error(`File editing session remains dirty: ${entry.path}`);
+                this.#prune(entry);
+            }));
+            throwFailures([...failures(admission), ...failures(saved)]);
+            if (!shutdown)
+                this.#assertOpen();
+            result = await operation();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        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);
+                this.#prune(entry);
+            }
+        }
+        throwFailures(errors);
+        return result;
+    }
+}

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
@@ -41,6 +48,7 @@ export declare class FileManager {
      * @public
      */
     renameFile(file: TAbstractFile, newPath: string): Promise<void>;
+    private renameProtectedFile;
     /**
      * Remove a file or a folder from the vault according the user's preferred
      * 'trash' options (either moving the file to .trash/ or the OS trash bin).
@@ -86,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>;
 }