@lapis-notes/api 0.1.4 → 0.2.0

package/dist/vault-changes.d.ts

@@ -0,0 +1,37 @@
+import type { App } from "./context.svelte";
+/** One App owns watching, reconciliation and retirement for its live Vault. */
+export declare class VaultChangeService {
+    private readonly app;
+    private watcher;
+    private starting;
+    private stopping;
+    private processing;
+    private timer;
+    private generation;
+    private active;
+    private registered;
+    private dirty;
+    private uncertain;
+    private failures;
+    private readonly hints;
+    private stopProjection;
+    private readonly projections;
+    constructor(app: App);
+    start(): Promise<void>;
+    /**
+     * Retire callbacks synchronously, then drain registration, native IO and
+     * scans.
+     */
+    stop(): Promise<void>;
+    /**
+     * Flush pending hints now; explicit calls also retry a previously failed
+     * scan.
+     */
+    settle(): Promise<void>;
+    private live;
+    private clearTimer;
+    private report;
+    private schedule;
+    private changed;
+    private drain;
+}

package/dist/vault-changes.js

@@ -0,0 +1,228 @@
+import { DirectoryWatcher, TFile, } from "./storage/fs";
+import { projectVaultChange } from "./vault-change-views";
+/** One App owns watching, reconciliation and retirement for its live Vault. */
+export class VaultChangeService {
+    app;
+    watcher;
+    starting;
+    stopping;
+    processing;
+    timer;
+    generation = 0;
+    active = false;
+    registered = false;
+    dirty = false;
+    uncertain = false;
+    failures = 0;
+    hints = new Map();
+    stopProjection;
+    projections = new Set();
+    constructor(app) {
+        this.app = app;
+    }
+    start() {
+        if (this.starting)
+            return this.starting;
+        if (this.active)
+            return this.settle();
+        const run = async () => {
+            const retiring = this.stop();
+            const requested = this.generation;
+            await retiring;
+            if (this.generation !== requested)
+                return;
+            const generation = ++this.generation;
+            this.active = true;
+            this.dirty = true;
+            const watcher = new DirectoryWatcher(this.app.vault.adapter);
+            this.watcher = watcher;
+            const projection = this.app.vault.on("all", (event, file, context) => {
+                if (!this.live(generation) || !(file instanceof TFile))
+                    return;
+                const snapshot = file.copy(), details = { ...context };
+                const pending = this.app.fileEditingSessions.track(() => this.app.fileEditingSessions.afterMutations(() => projectVaultChange(this.app, event, snapshot, details, () => this.live(generation))));
+                this.projections.add(pending);
+                void pending
+                    .catch((error) => this.report(error))
+                    .finally(() => this.projections.delete(pending));
+            });
+            this.stopProjection = () => this.app.vault.offref(projection);
+            watcher.on("all", (event) => {
+                if (this.live(generation))
+                    this.changed(event, generation);
+            });
+            const subscription = watcher.watch("/", { recursive: true });
+            await subscription.ready;
+            if (!this.live(generation))
+                return;
+            this.registered = true;
+            await this.drain(generation);
+        };
+        const pending = run()
+            .catch(async (error) => {
+            this.active = false;
+            this.registered = false;
+            ++this.generation;
+            this.clearTimer();
+            this.stopProjection?.();
+            this.stopProjection = undefined;
+            try {
+                await this.watcher?.close();
+            }
+            catch (cleanup) {
+                throw new AggregateError([error, cleanup], "Vault watch startup and cleanup failed");
+            }
+            this.watcher = undefined;
+            throw error;
+        })
+            .finally(() => {
+            if (this.starting === pending)
+                this.starting = undefined;
+        });
+        this.starting = pending;
+        return pending;
+    }
+    /**
+     * Retire callbacks synchronously, then drain registration, native IO and
+     * scans.
+     */
+    stop() {
+        this.active = false;
+        this.registered = false;
+        ++this.generation;
+        this.clearTimer();
+        this.stopProjection?.();
+        this.stopProjection = undefined;
+        this.hints.clear();
+        this.dirty = false;
+        this.uncertain = false;
+        if (this.stopping)
+            return this.stopping;
+        const watcher = this.watcher;
+        const pending = Promise.allSettled([
+            watcher?.close(),
+            this.processing,
+            this.starting,
+            ...this.projections,
+        ])
+            .then((results) => {
+            const errors = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+            if (errors.length)
+                throw new AggregateError(errors, "Vault watch cleanup failed");
+            if (this.watcher === watcher)
+                this.watcher = undefined;
+        })
+            .finally(() => {
+            if (this.stopping === pending)
+                this.stopping = undefined;
+        });
+        this.stopping = pending;
+        return pending;
+    }
+    /**
+     * Flush pending hints now; explicit calls also retry a previously failed
+     * scan.
+     */
+    async settle() {
+        await this.starting;
+        this.clearTimer();
+        if (this.active && this.registered) {
+            await this.drain(this.generation);
+            while (this.projections.size)
+                await Promise.all([...this.projections]);
+        }
+    }
+    live(generation) {
+        return this.active && this.generation === generation;
+    }
+    clearTimer() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+    report(error) {
+        this.app.notifications.notify({
+            id: "vault-watch-reconciliation",
+            title: "File changes need attention",
+            message: error instanceof Error ? error.message : String(error),
+            severity: "error",
+            source: "vault",
+        });
+    }
+    schedule(generation, delay = 40) {
+        if (!this.registered || this.timer || !this.live(generation))
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.drain(generation).catch(() => { });
+        }, delay);
+    }
+    changed(event, generation) {
+        this.dirty = true;
+        if (event.type === "error") {
+            this.uncertain = true;
+            this.hints.clear();
+            this.report(event.error);
+        }
+        else if (!this.uncertain) {
+            const previous = event.previousPath
+                ? this.hints.get(event.previousPath)
+                : this.hints.get(event.path);
+            const hint = {
+                ...event,
+                previousPath: previous?.previousPath ?? event.previousPath,
+            };
+            if (event.previousPath)
+                this.hints.delete(event.previousPath);
+            this.hints.set(event.path, hint);
+            const bytes = [...this.hints.values()].reduce((sum, value) => sum +
+                new TextEncoder().encode(value.path + (value.previousPath ?? ""))
+                    .byteLength +
+                96, 0);
+            if (event.path === "/" ||
+                !event.path ||
+                this.hints.size > 2048 ||
+                bytes > 128 * 1024) {
+                this.uncertain = true;
+                this.hints.clear();
+            }
+        }
+        this.schedule(generation);
+    }
+    drain(generation) {
+        if (this.processing)
+            return this.processing;
+        const run = async () => {
+            while (this.live(generation) && this.dirty) {
+                const hints = this.uncertain ? [] : [...this.hints.values()];
+                this.hints.clear();
+                this.dirty = false;
+                this.uncertain = false;
+                try {
+                    await this.app.vault.reconcile(hints, () => this.live(generation), {
+                        external: true,
+                    });
+                    while (this.projections.size)
+                        await Promise.all([...this.projections]);
+                    this.failures = 0;
+                }
+                catch (error) {
+                    if (this.live(generation)) {
+                        this.dirty = true;
+                        this.uncertain = true;
+                        this.report(error);
+                        if (++this.failures <= 4)
+                            this.schedule(generation, 250 * 2 ** (this.failures - 1));
+                    }
+                    throw error;
+                }
+            }
+        };
+        const pending = run().finally(() => {
+            if (this.processing === pending)
+                this.processing = undefined;
+        });
+        this.processing = pending;
+        return pending;
+    }
+}

package/dist/view.svelte.d.ts

@@ -4,7 +4,12 @@ import type { Menu } from "./menu.svelte";
 import { Editor } from "./editor.svelte";
 import type { App } from "./context.svelte";
 import "./enhance";
-import { EventDispatcher, type EventNames, type EventRef, type ValidEventTypes } from "./events";
+import {
+  EventDispatcher,
+  type EventNames,
+  type EventRef,
+  type ValidEventTypes,
+} from "./events";
 import type { Scope } from "./command.svelte";
 /**
  * Base lifecycle helper used throughout the public API.
@@ -14,70 +19,89 @@ import type { Scope } from "./command.svelte";
  *
  * @public
  */
-export declare abstract class Component<Events extends ValidEventTypes = Record<string, any>> extends EventDispatcher<Events> {
-    children: Component[];
-    private unloaders;
-    loaded: boolean;
-    protected _containerEl: HTMLElement;
-    get containerEl(): HTMLElement;
-    set containerEl(el: HTMLElement);
-    /**
-     * Load this component and its children
-     *
-     * @public
-     */
-    load(): void;
-    /**
-     * Override this to load your component
-     *
-     * @abstract
-     * @public
-     */
-    onload(): Promise<void> | void;
-    protected loadAsync(): Promise<void>;
-    /**
-     * Unload this component and its children
-     *
-     * @public
-     */
-    unload(): void;
-    protected unloadAsync(): Promise<void>;
-    /**
-     * Override this to unload your component
-     *
-     * @abstract
-     * @public
-     */
-    onunload(): void;
-    private cleanupAsync;
-    /**
-     * Adds a child component, loading it if this component is loaded
-     *
-     * @public
-     */
-    addChild<T extends Component>(component: T): T;
-    /**
-     * Removes a child component, unloading it
-     *
-     * @public
-     */
-    removeChild<T extends Component>(component: T): T;
-    /**
-     * Registers a callback to be called when unloading
-     *
-     * @public
-     */
-    register(cb: () => any): void;
-    registerEvent<T extends ValidEventTypes, K extends EventNames<T>>(eventRef: EventRef<T, K, any>): void;
-    registerInterval(id: ReturnType<typeof setInterval>): void;
-    /**
-     * Registers an DOM event to be detached when unloading
-     *
-     * @public
-     */
-    registerDomEvent<K extends keyof HTMLElementEventMap>(el: HTMLElement, type: K, callback: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
-    registerDomEvent<K extends keyof DocumentEventMap>(el: Document, type: K, callback: (this: HTMLElement, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
-    registerDomEvent<K extends keyof WindowEventMap>(el: Window, type: K, callback: (this: HTMLElement, ev: WindowEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+export declare abstract class Component<
+  Events extends ValidEventTypes = Record<string, any>,
+> extends EventDispatcher<Events> {
+  children: Component[];
+  private unloaders;
+  loaded: boolean;
+  protected _containerEl: HTMLElement;
+  get containerEl(): HTMLElement;
+  set containerEl(el: HTMLElement);
+  /**
+   * Load this component and its children
+   *
+   * @public
+   */
+  load(): void;
+  /**
+   * Override this to load your component
+   *
+   * @abstract
+   * @public
+   */
+  onload(): Promise<void> | void;
+  protected loadAsync(): Promise<void>;
+  /**
+   * Unload this component and its children
+   *
+   * @public
+   */
+  unload(): void;
+  protected unloadAsync(): Promise<void>;
+  /**
+   * Override this to unload your component
+   *
+   * @abstract
+   * @public
+   */
+  onunload(): void;
+  private cleanupAsync;
+  /**
+   * Adds a child component, loading it if this component is loaded
+   *
+   * @public
+   */
+  addChild<T extends Component>(component: T): T;
+  /**
+   * Removes a child component, unloading it
+   *
+   * @public
+   */
+  removeChild<T extends Component>(component: T): T;
+  /**
+   * Registers a callback to be called when unloading
+   *
+   * @public
+   */
+  register(cb: () => any): void;
+  registerEvent<T extends ValidEventTypes, K extends EventNames<T>>(
+    eventRef: EventRef<T, K, any>,
+  ): void;
+  registerInterval(id: ReturnType<typeof setInterval>): void;
+  /**
+   * Registers an DOM event to be detached when unloading
+   *
+   * @public
+   */
+  registerDomEvent<K extends keyof HTMLElementEventMap>(
+    el: HTMLElement,
+    type: K,
+    callback: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  registerDomEvent<K extends keyof DocumentEventMap>(
+    el: Document,
+    type: K,
+    callback: (this: HTMLElement, ev: DocumentEventMap[K]) => any,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  registerDomEvent<K extends keyof WindowEventMap>(
+    el: Window,
+    type: K,
+    callback: (this: HTMLElement, ev: WindowEventMap[K]) => any,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
 }
 /**
  * Additional metadata returned from view-state transitions.
@@ -85,13 +109,13 @@ export declare abstract class Component<Events extends ValidEventTypes = Record<
  * @public
  */
 export interface ViewStateResult {
-    /**
-     * Set this to true to indicate that there is a state change which should be
-     * recorded in the navigation history.
-     *
-     * @public
-     */
-    history: boolean;
+  /**
+   * Set this to true to indicate that there is a state change which should be
+   * recorded in the navigation history.
+   *
+   * @public
+   */
+  history: boolean;
 }
 /**
  * Serialized workspace state for a single leaf.
@@ -99,27 +123,27 @@ export interface ViewStateResult {
  * @public
  */
 export interface ViewState {
-    /** @public */
-    type: string;
-    /** @public */
-    state?: Record<string, unknown>;
-    /** @public */
-    active?: boolean;
-    /** @public */
-    pinned?: boolean;
-    /** @public */
-    group?: WorkspaceLeaf;
+  /** @public */
+  type: string;
+  /** @public */
+  state?: Record<string, unknown>;
+  /** @public */
+  active?: boolean;
+  /** @public */
+  pinned?: boolean;
+  /** @public */
+  group?: WorkspaceLeaf;
 }
 /**
- * Header breadcrumb contributed by a view. Keep the leaf filename in the
- * header title rather than this list.
+ * Header breadcrumb contributed by a view. Keep the leaf filename in the header
+ * title rather than this list.
  *
  * @public
  */
 export interface ViewBreadcrumb {
-    id: string;
-    label: string;
-    onSelect?: () => void;
+  id: string;
+  label: string;
+  onSelect?: () => void;
 }
 /**
  * Base class for anything that can be mounted inside a workspace leaf.
@@ -127,37 +151,41 @@ export interface ViewBreadcrumb {
  * @public
  */
 export declare abstract class View extends Component {
-    icon: string;
-    leaf: WorkspaceLeaf;
-    scope: Scope | null;
-    protected state: Record<string, unknown>;
-    constructor(leaf?: WorkspaceLeaf);
-    get containerEl(): HTMLElement;
-    get app(): App;
-    /** @public */
-    protected abstract onOpen(): Promise<void>;
-    /** @public */
-    protected abstract onClose(): Promise<void>;
-    /** @public */
-    abstract getViewType(): string;
-    getState(): Record<string, unknown>;
-    setState(state: Record<string, unknown>, result?: ViewStateResult): Promise<void>;
-    getIcon(): string;
-    abstract getDisplayText(): string;
-    getBreadcrumbFilePath(): string | null;
-    getBreadcrumbs(): ViewBreadcrumb[];
-    onPaneMenu(menu: Menu, source: "more-options" | "tab-header" | string): void;
+  icon: string;
+  leaf: WorkspaceLeaf;
+  scope: Scope | null;
+  protected state: Record<string, unknown>;
+  constructor(leaf?: WorkspaceLeaf);
+  get containerEl(): HTMLElement;
+  get app(): App;
+  /** @public */
+  protected abstract onOpen(): Promise<void>;
+  /** @public */
+  protected abstract onClose(): Promise<void>;
+  /** @public */
+  abstract getViewType(): string;
+  getState(): Record<string, unknown>;
+  setState(
+    state: Record<string, unknown>,
+    result?: ViewStateResult,
+  ): Promise<void>;
+  getIcon(): string;
+  abstract getDisplayText(): string;
+  getClosePersistenceScope(): "application" | "layout";
+  getBreadcrumbFilePath(): string | null;
+  getBreadcrumbs(): ViewBreadcrumb[];
+  onPaneMenu(menu: Menu, source: "more-options" | "tab-header" | string): void;
 }
 export declare class EmptyView extends View {
-    private component;
-    constructor(leaf?: WorkspaceLeaf);
-    protected onOpen(): Promise<void>;
-    protected onClose(): Promise<void>;
-    load(): void;
-    unload(): void;
-    getViewType(): string;
-    getDisplayText(): string;
-    getIcon(): string;
+  private component;
+  constructor(leaf?: WorkspaceLeaf);
+  protected onOpen(): Promise<void>;
+  protected onClose(): Promise<void>;
+  load(): void;
+  unload(): void;
+  getViewType(): string;
+  getDisplayText(): string;
+  getIcon(): string;
 }
 /**
  * View base class with an action bar and content area.
@@ -165,20 +193,25 @@ export declare class EmptyView extends View {
  * @public
  */
 export declare abstract class ItemView extends View {
-    actions: Array<{
-        icon: string;
-        title: string;
-        callback: (evt: MouseEvent) => any;
-        disabled?: boolean;
-    }>;
-    constructor(leaf?: WorkspaceLeaf);
-    get contentEl(): HTMLElement;
-    unload(): void;
-    addAction(icon: string, title: string, callback: (evt: MouseEvent) => any, options?: {
-        disabled?: boolean;
-    }): void;
-    protected onOpen(): Promise<void>;
-    protected onClose(): Promise<void>;
+  actions: Array<{
+    icon: string;
+    title: string;
+    callback: (evt: MouseEvent) => any;
+    disabled?: boolean;
+  }>;
+  constructor(leaf?: WorkspaceLeaf);
+  get contentEl(): HTMLElement;
+  unload(): void;
+  addAction(
+    icon: string,
+    title: string,
+    callback: (evt: MouseEvent) => any,
+    options?: {
+      disabled?: boolean;
+    },
+  ): void;
+  protected onOpen(): Promise<void>;
+  protected onClose(): Promise<void>;
 }
 /**
  * Item view base class that is backed by a vault file.
@@ -186,13 +219,13 @@ export declare abstract class ItemView extends View {
  * @public
  */
 export declare abstract class FileView extends ItemView {
-    file: TFile | null;
-    constructor(leaf?: WorkspaceLeaf);
-    getBreadcrumbFilePath(): string | null;
-    abstract onLoadFile(file: TFile): Promise<void>;
-    abstract onUnloadFile(file: TFile): Promise<void>;
-    abstract onRename(file: TFile): Promise<void>;
-    abstract canAcceptExtension(extension: string): boolean;
+  file: TFile | null;
+  constructor(leaf?: WorkspaceLeaf);
+  getBreadcrumbFilePath(): string | null;
+  abstract onLoadFile(file: TFile): Promise<void>;
+  abstract onUnloadFile(file: TFile): Promise<void>;
+  abstract onRename(file: TFile): Promise<void>;
+  abstract canAcceptExtension(extension: string): boolean;
 }
 /**
  * File view base class for text-backed editors.
@@ -200,16 +233,16 @@ export declare abstract class FileView extends ItemView {
  * @public
  */
 export declare abstract class TextFileView extends FileView {
-    editor: Editor;
-    data: string;
-    constructor(leaf?: WorkspaceLeaf);
-    get adapter(): DataAdapter;
-    abstract getViewData(): string;
-    abstract setViewData(data: string, clear?: boolean): void;
-    abstract clear(): void;
-    onLoadFile(file: TFile): Promise<void>;
-    getIcon(): string;
-    onRename(file: TFile): Promise<void>;
-    onUnloadFile(file: TFile): Promise<void>;
-    save(clear?: boolean): Promise<void>;
+  editor: Editor;
+  data: string;
+  constructor(leaf?: WorkspaceLeaf);
+  get adapter(): DataAdapter;
+  abstract getViewData(): string;
+  abstract setViewData(data: string, clear?: boolean): void;
+  abstract clear(): void;
+  onLoadFile(file: TFile): Promise<void>;
+  getIcon(): string;
+  onRename(file: TFile): Promise<void>;
+  onUnloadFile(file: TFile): Promise<void>;
+  save(clear?: boolean): Promise<void>;
 }

package/dist/view.svelte.js

@@ -208,8 +208,17 @@ export class View extends Component {
         return this.icon;
     }
     /**
-     * Vault path used for parent-path header breadcrumbs. File views return
-     * the open file; other views MAY return a related path or null.
+     * Layout-only views own no file writers and retain staged state outside their
+     * UI. Every other view keeps the complete application writer close guard.
+     *
+     * @public
+     */
+    getClosePersistenceScope() {
+        return "application";
+    }
+    /**
+     * Vault path used for parent-path header breadcrumbs. File views return the
+     * open file; other views MAY return a related path or null.
      *
      * @public
      */

package/dist/workspace-close-guard.d.ts

@@ -0,0 +1,3 @@
+import type { Workspace } from "./workspace.svelte";
+/** Keep the App's persistence barrier held through destructive shell changes. */
+export declare function workspaceCloseGuard(workspace: Workspace, hostDocuments?: () => Document[]): (ids: string[], remove: () => void) => Promise<void>;