@excalidraw/excalidraw 0.17.1-7500-ac247a0 → 0.17.1-b7babe5

package/dist/excalidraw/data/index.js

@@ -1,15 +1,15 @@
 import { copyBlobToClipboardAsPng, copyTextToSystemClipboard, } from "../clipboard";
-import { DEFAULT_EXPORT_PADDING, isFirefox, MIME_TYPES } from "../constants";
+import { DEFAULT_EXPORT_PADDING, DEFAULT_FILENAME, isFirefox, MIME_TYPES, } from "../constants";
 import { getNonDeletedElements } from "../element";
 import { isFrameLikeElement } from "../element/typeChecks";
 import { t } from "../i18n";
-import { elementsOverlappingBBox } from "../../utils/index";
 import { isSomeElementSelected, getSelectedElements } from "../scene";
 import { exportToCanvas, exportToSvg } from "../scene/export";
 import { cloneJSON } from "../utils";
 import { canvasToBlob } from "./blob";
 import { fileSave } from "./filesystem";
 import { serializeAsJSON } from "./json";
+import { getElementsOverlappingFrame } from "../frame";
 export { loadFromBlob } from "./blob";
 export { loadFromJSON, saveAsJSON } from "./json";
 export const prepareElementsForExport = (elements, { selectedElementIds }, exportSelectionOnly) => {
@@ -26,11 +26,7 @@ export const prepareElementsForExport = (elements, { selectedElementIds }, expor
         if (exportedElements.length === 1 &&
             isFrameLikeElement(exportedElements[0])) {
             exportingFrame = exportedElements[0];
-            exportedElements = elementsOverlappingBBox({
-                elements,
-                bounds: exportingFrame,
-                type: "overlap",
-            });
+            exportedElements = getElementsOverlappingFrame(elements, exportingFrame);
         }
         else if (exportedElements.length > 1) {
             exportedElements = getSelectedElements(elements, { selectedElementIds }, {
@@ -44,12 +40,12 @@ export const prepareElementsForExport = (elements, { selectedElementIds }, expor
         exportedElements: cloneJSON(exportedElements),
     };
 };
-export const exportCanvas = async (type, elements, appState, files, { exportBackground, exportPadding = DEFAULT_EXPORT_PADDING, viewBackgroundColor, name, fileHandle = null, exportingFrame = null, }) => {
+export const exportCanvas = async (type, elements, appState, files, { exportBackground, exportPadding = DEFAULT_EXPORT_PADDING, viewBackgroundColor, name = appState.name || DEFAULT_FILENAME, fileHandle = null, exportingFrame = null, }) => {
     if (elements.length === 0) {
         throw new Error(t("alerts.cannotExportEmptyCanvas"));
     }
     if (type === "svg" || type === "clipboard-svg") {
-        const tempSvg = await exportToSvg(elements, {
+        const svgPromise = exportToSvg(elements, {
             exportBackground,
             exportWithDarkMode: appState.exportWithDarkMode,
             viewBackgroundColor,
@@ -58,7 +54,9 @@ export const exportCanvas = async (type, elements, appState, files, { exportBack
             exportEmbedScene: appState.exportEmbedScene && type === "svg",
         }, files, { exportingFrame });
         if (type === "svg") {
-            return await fileSave(new Blob([tempSvg.outerHTML], { type: MIME_TYPES.svg }), {
+            return fileSave(svgPromise.then((svg) => {
+                return new Blob([svg.outerHTML], { type: MIME_TYPES.svg });
+            }), {
                 description: "Export to SVG",
                 name,
                 extension: appState.exportEmbedScene ? "excalidraw.svg" : "svg",
@@ -66,7 +64,13 @@ export const exportCanvas = async (type, elements, appState, files, { exportBack
             });
         }
         else if (type === "clipboard-svg") {
-            await copyTextToSystemClipboard(tempSvg.outerHTML);
+            const svg = await svgPromise.then((svg) => svg.outerHTML);
+            try {
+                await copyTextToSystemClipboard(svg);
+            }
+            catch (e) {
+                throw new Error(t("errors.copyToSystemClipboardFailed"));
+            }
             return;
         }
     }
@@ -77,14 +81,14 @@ export const exportCanvas = async (type, elements, appState, files, { exportBack
         exportingFrame,
     });
     if (type === "png") {
-        let blob = await canvasToBlob(tempCanvas);
+        let blob = canvasToBlob(tempCanvas);
         if (appState.exportEmbedScene) {
-            blob = await (await import("./image")).encodePngMetadata({
+            blob = blob.then((blob) => import("./image").then(({ encodePngMetadata }) => encodePngMetadata({
                 blob,
                 metadata: serializeAsJSON(elements, appState, files, "local"),
-            });
+            })));
         }
-        return await fileSave(blob, {
+        return fileSave(blob, {
             description: "Export to PNG",
             name,
             // FIXME reintroduce `excalidraw.png` when most people upgrade away
@@ -101,7 +105,7 @@ export const exportCanvas = async (type, elements, appState, files, { exportBack
         catch (error) {
             console.warn(error);
             if (error.name === "CANVAS_POSSIBLY_TOO_BIG") {
-                throw error;
+                throw new Error(t("canvasError.canvasTooBig"));
             }
             // TypeError *probably* suggests ClipboardItem not defined, which
             // people on Firefox can enable through a flag, so let's tell them.

package/dist/excalidraw/data/json.d.ts

@@ -2,7 +2,7 @@ import { ExcalidrawElement } from "../element/types";
 import { AppState, BinaryFiles, LibraryItems } from "../types";
 import { ImportedDataState, ImportedLibraryData } from "./types";
 export declare const serializeAsJSON: (elements: readonly ExcalidrawElement[], appState: Partial<AppState>, files: BinaryFiles, type: "local" | "database") => string;
-export declare const saveAsJSON: (elements: readonly ExcalidrawElement[], appState: AppState, files: BinaryFiles) => Promise<{
+export declare const saveAsJSON: (elements: readonly ExcalidrawElement[], appState: AppState, files: BinaryFiles, name?: string) => Promise<{
     fileHandle: import("browser-fs-access").FileSystemHandle | null;
 }>;
 export declare const loadFromJSON: (localAppState: AppState, localElements: readonly ExcalidrawElement[] | null) => Promise<import("./restore").RestoredDataState>;

package/dist/excalidraw/data/json.js

@@ -1,6 +1,6 @@
 import { fileOpen, fileSave } from "./filesystem";
 import { cleanAppStateForExport, clearAppStateForDatabase } from "../appState";
-import { EXPORT_DATA_TYPES, EXPORT_SOURCE, MIME_TYPES, VERSIONS, } from "../constants";
+import { DEFAULT_FILENAME, EXPORT_DATA_TYPES, EXPORT_SOURCE, MIME_TYPES, VERSIONS, } from "../constants";
 import { clearElementsForDatabase, clearElementsForExport } from "../element";
 import { isImageFileHandle, loadFromBlob, normalizeFile } from "./blob";
 /**
@@ -36,13 +36,15 @@ export const serializeAsJSON = (elements, appState, files, type) => {
     };
     return JSON.stringify(data, null, 2);
 };
-export const saveAsJSON = async (elements, appState, files) => {
+export const saveAsJSON = async (elements, appState, files, 
+/** filename */
+name = appState.name || DEFAULT_FILENAME) => {
     const serialized = serializeAsJSON(elements, appState, files, "local");
     const blob = new Blob([serialized], {
         type: MIME_TYPES.excalidraw,
     });
     const fileHandle = await fileSave(blob, {
-        name: appState.name,
+        name,
         extension: "excalidraw",
         description: "Excalidraw file",
         fileHandle: isImageFileHandle(appState.fileHandle)

package/dist/excalidraw/data/library.d.ts

@@ -1,13 +1,53 @@
-import { LibraryItems, ExcalidrawImperativeAPI, LibraryItemsSource } from "../types";
+import { LibraryItems, ExcalidrawImperativeAPI, LibraryItemsSource, LibraryItems_anyVersion } from "../types";
 import type App from "../components/App";
 import { ExcalidrawElement } from "../element/types";
+import { MaybePromise } from "../utility-types";
+export type LibraryPersistedData = {
+    libraryItems: LibraryItems;
+};
+export type LibraryAdatapterSource = "load" | "save";
+export interface LibraryPersistenceAdapter {
+    /**
+     * Should load data that were previously saved into the database using the
+     * `save` method. Should throw if saving fails.
+     *
+     * Will be used internally in multiple places, such as during save to
+     * in order to reconcile changes with latest store data.
+     */
+    load(metadata: {
+        /**
+         * Indicates whether we're loading data for save purposes, or reading
+         * purposes, in which case host app can implement more aggressive caching.
+         */
+        source: LibraryAdatapterSource;
+    }): MaybePromise<{
+        libraryItems: LibraryItems_anyVersion;
+    } | null>;
+    /** Should persist to the database as is (do no change the data structure). */
+    save(libraryData: LibraryPersistedData): MaybePromise<void>;
+}
+export interface LibraryMigrationAdapter {
+    /**
+     * loads data from legacy data source. Returns `null` if no data is
+     * to be migrated.
+     */
+    load(): MaybePromise<{
+        libraryItems: LibraryItems_anyVersion;
+    } | null>;
+    /** clears entire storage afterwards */
+    clear(): MaybePromise<void>;
+}
 export declare const libraryItemsAtom: import("jotai").PrimitiveAtom<{
     status: "loading" | "loaded";
+    /** indicates whether library is initialized with library items (has gone
+     * through at least one update). Used in UI. Specific to this atom only. */
     isInitialized: boolean;
     libraryItems: LibraryItems;
 }> & {
     init: {
         status: "loading" | "loaded";
+        /** indicates whether library is initialized with library items (has gone
+         * through at least one update). Used in UI. Specific to this atom only. */
         isInitialized: boolean;
         libraryItems: LibraryItems;
     };
@@ -17,10 +57,9 @@ export declare const libraryItemsAtom: import("jotai").PrimitiveAtom<{
 export declare const mergeLibraryItems: (localItems: LibraryItems, otherItems: LibraryItems) => LibraryItems;
 declare class Library {
     /** latest libraryItems */
-    private lastLibraryItems;
-    /** indicates whether library is initialized with library items (has gone
-     * though at least one update) */
-    private isInitialized;
+    private currLibraryItems;
+    /** snapshot of library items since last onLibraryChange call */
+    private prevLibraryItems;
     private app;
     constructor(app: App);
     private updateQueue;
@@ -48,7 +87,20 @@ export declare const parseLibraryTokensFromUrl: () => {
     libraryUrl: string;
     idToken: string | null;
 } | null;
-export declare const useHandleLibrary: ({ excalidrawAPI, getInitialLibraryItems, }: {
+export declare const getLibraryItemsHash: (items: LibraryItems) => number;
+export declare const useHandleLibrary: (opts: {
     excalidrawAPI: ExcalidrawImperativeAPI | null;
-    getInitialLibraryItems?: (() => LibraryItemsSource) | undefined;
-}) => void;
+} & ({
+    /** @deprecated we recommend using `opts.adapter` instead */
+    getInitialLibraryItems?: () => MaybePromise<LibraryItemsSource>;
+} | {
+    adapter: LibraryPersistenceAdapter;
+    /**
+     * Adapter that takes care of loading data from legacy data store.
+     * Supply this if you want to migrate data on initial load from legacy
+     * data store.
+     *
+     * Can be a different LibraryPersistenceAdapter.
+     */
+    migrationAdapter?: LibraryMigrationAdapter;
+})) => void;

package/dist/excalidraw/data/library.js

@@ -8,8 +8,12 @@ import { t } from "../i18n";
 import { useEffect, useRef } from "react";
 import { URL_HASH_KEYS, URL_QUERY_KEYS, APP_NAME, EVENT, DEFAULT_SIDEBAR, LIBRARY_SIDEBAR_TAB, } from "../constants";
 import { libraryItemSvgsCache } from "../hooks/useLibraryItemSvg";
-import { cloneJSON } from "../utils";
-export const libraryItemsAtom = atom({ status: "loaded", isInitialized: true, libraryItems: [] });
+import { arrayToMap, cloneJSON, preventUnload, promiseTry, resolvablePromise, } from "../utils";
+import { Emitter } from "../emitter";
+import { Queue } from "../queue";
+import { hashElementsVersion, hashString } from "../element";
+const onLibraryUpdateEmitter = new Emitter();
+export const libraryItemsAtom = atom({ status: "loaded", isInitialized: false, libraryItems: [] });
 const cloneLibraryItems = (libraryItems) => cloneJSON(libraryItems);
 /**
  * checks if library item does not exist already in current library
@@ -39,12 +43,36 @@ export const mergeLibraryItems = (localItems, otherItems) => {
     }
     return [...newItems, ...localItems];
 };
+/**
+ * Returns { deletedItems, addedItems } maps of all added and deleted items
+ * since last onLibraryChange event.
+ *
+ * Host apps are recommended to diff with the latest state they have.
+ */
+const createLibraryUpdate = (prevLibraryItems, nextLibraryItems) => {
+    const nextItemsMap = arrayToMap(nextLibraryItems);
+    const update = {
+        deletedItems: new Map(),
+        addedItems: new Map(),
+    };
+    for (const item of prevLibraryItems) {
+        if (!nextItemsMap.has(item.id)) {
+            update.deletedItems.set(item.id, item);
+        }
+    }
+    const prevItemsMap = arrayToMap(prevLibraryItems);
+    for (const item of nextLibraryItems) {
+        if (!prevItemsMap.has(item.id)) {
+            update.addedItems.set(item.id, item);
+        }
+    }
+    return update;
+};
 class Library {
     /** latest libraryItems */
-    lastLibraryItems = [];
-    /** indicates whether library is initialized with library items (has gone
-     * though at least one update) */
-    isInitialized = false;
+    currLibraryItems = [];
+    /** snapshot of library items since last onLibraryChange call */
+    prevLibraryItems = cloneLibraryItems(this.currLibraryItems);
     app;
     constructor(app) {
         this.app = app;
@@ -55,21 +83,25 @@ class Library {
     };
     notifyListeners = () => {
         if (this.updateQueue.length > 0) {
-            jotaiStore.set(libraryItemsAtom, {
+            jotaiStore.set(libraryItemsAtom, (s) => ({
                 status: "loading",
-                libraryItems: this.lastLibraryItems,
-                isInitialized: this.isInitialized,
-            });
+                libraryItems: this.currLibraryItems,
+                isInitialized: s.isInitialized,
+            }));
         }
         else {
-            this.isInitialized = true;
             jotaiStore.set(libraryItemsAtom, {
                 status: "loaded",
-                libraryItems: this.lastLibraryItems,
-                isInitialized: this.isInitialized,
+                libraryItems: this.currLibraryItems,
+                isInitialized: true,
             });
             try {
-                this.app.props.onLibraryChange?.(cloneLibraryItems(this.lastLibraryItems));
+                const prevLibraryItems = this.prevLibraryItems;
+                this.prevLibraryItems = cloneLibraryItems(this.currLibraryItems);
+                const nextLibraryItems = cloneLibraryItems(this.currLibraryItems);
+                this.app.props.onLibraryChange?.(nextLibraryItems);
+                // for internal use in `useHandleLibrary` hook
+                onLibraryUpdateEmitter.trigger(createLibraryUpdate(prevLibraryItems, nextLibraryItems), nextLibraryItems);
             }
             catch (error) {
                 console.error(error);
@@ -78,9 +110,8 @@ class Library {
     };
     /** call on excalidraw instance unmount */
     destroy = () => {
-        this.isInitialized = false;
         this.updateQueue = [];
-        this.lastLibraryItems = [];
+        this.currLibraryItems = [];
         jotaiStore.set(libraryItemSvgsCache, new Map());
         // TODO uncomment after/if we make jotai store scoped to each excal instance
         // jotaiStore.set(libraryItemsAtom, {
@@ -99,7 +130,7 @@ class Library {
         return new Promise(async (resolve) => {
             try {
                 const libraryItems = await (this.getLastUpdateTask() ||
-                    this.lastLibraryItems);
+                    this.currLibraryItems);
                 if (this.updateQueue.length > 0) {
                     resolve(this.getLatestLibrary());
                 }
@@ -108,7 +139,7 @@ class Library {
                 }
             }
             catch (error) {
-                return resolve(this.lastLibraryItems);
+                return resolve(this.currLibraryItems);
             }
         });
     };
@@ -126,7 +157,7 @@ class Library {
                 try {
                     const source = await (typeof libraryItems === "function" &&
                         !(libraryItems instanceof Blob)
-                        ? libraryItems(this.lastLibraryItems)
+                        ? libraryItems(this.currLibraryItems)
                         : libraryItems);
                     let nextItems;
                     if (source instanceof Blob) {
@@ -146,7 +177,7 @@ class Library {
                             this.app.focusContainer();
                         }
                         if (merge) {
-                            resolve(mergeLibraryItems(this.lastLibraryItems, nextItems));
+                            resolve(mergeLibraryItems(this.currLibraryItems, nextItems));
                         }
                         else {
                             resolve(nextItems);
@@ -178,10 +209,10 @@ class Library {
             try {
                 await this.getLastUpdateTask();
                 if (typeof libraryItems === "function") {
-                    libraryItems = libraryItems(this.lastLibraryItems);
+                    libraryItems = libraryItems(this.currLibraryItems);
                 }
-                this.lastLibraryItems = cloneLibraryItems(await libraryItems);
-                resolve(this.lastLibraryItems);
+                this.currLibraryItems = cloneLibraryItems(await libraryItems);
+                resolve(this.currLibraryItems);
             }
             catch (error) {
                 reject(error);
@@ -190,7 +221,7 @@ class Library {
             .catch((error) => {
             if (error.name === "AbortError") {
                 console.warn("Library update aborted by user");
-                return this.lastLibraryItems;
+                return this.currLibraryItems;
             }
             throw error;
         })
@@ -291,12 +322,105 @@ export const parseLibraryTokensFromUrl = () => {
         : null;
     return libraryUrl ? { libraryUrl, idToken } : null;
 };
-export const useHandleLibrary = ({ excalidrawAPI, getInitialLibraryItems, }) => {
-    const getInitialLibraryRef = useRef(getInitialLibraryItems);
+class AdapterTransaction {
+    static queue = new Queue();
+    static async getLibraryItems(adapter, source, _queue = true) {
+        const task = () => new Promise(async (resolve, reject) => {
+            try {
+                const data = await adapter.load({ source });
+                resolve(restoreLibraryItems(data?.libraryItems || [], "published"));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        if (_queue) {
+            return AdapterTransaction.queue.push(task);
+        }
+        return task();
+    }
+    static run = async (adapter, fn) => {
+        const transaction = new AdapterTransaction(adapter);
+        return AdapterTransaction.queue.push(() => fn(transaction));
+    };
+    // ------------------
+    adapter;
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    getLibraryItems(source) {
+        return AdapterTransaction.getLibraryItems(this.adapter, source, false);
+    }
+}
+let lastSavedLibraryItemsHash = 0;
+let librarySaveCounter = 0;
+export const getLibraryItemsHash = (items) => {
+    return hashString(items
+        .map((item) => {
+        return `${item.id}:${hashElementsVersion(item.elements)}`;
+    })
+        .sort()
+        .join());
+};
+const persistLibraryUpdate = async (adapter, update) => {
+    try {
+        librarySaveCounter++;
+        return await AdapterTransaction.run(adapter, async (transaction) => {
+            const nextLibraryItemsMap = arrayToMap(await transaction.getLibraryItems("save"));
+            for (const [id] of update.deletedItems) {
+                nextLibraryItemsMap.delete(id);
+            }
+            const addedItems = [];
+            // we want to merge current library items with the ones stored in the
+            // DB so that we don't lose any elements that for some reason aren't
+            // in the current editor library, which could happen when:
+            //
+            // 1. we haven't received an update deleting some elements
+            //    (in which case it's still better to keep them in the DB lest
+            //     it was due to a different reason)
+            // 2. we keep a single DB for all active editors, but the editors'
+            //    libraries aren't synced or there's a race conditions during
+            //    syncing
+            // 3. some other race condition, e.g. during init where emit updates
+            //    for partial updates (e.g. you install a 3rd party library and
+            //    init from DB only after — we emit events for both updates)
+            for (const [id, item] of update.addedItems) {
+                if (nextLibraryItemsMap.has(id)) {
+                    // replace item with latest version
+                    // TODO we could prefer the newer item instead
+                    nextLibraryItemsMap.set(id, item);
+                }
+                else {
+                    // we want to prepend the new items with the ones that are already
+                    // in DB to preserve the ordering we do in editor (newly added
+                    // items are added to the beginning)
+                    addedItems.push(item);
+                }
+            }
+            const nextLibraryItems = addedItems.concat(Array.from(nextLibraryItemsMap.values()));
+            const version = getLibraryItemsHash(nextLibraryItems);
+            if (version !== lastSavedLibraryItemsHash) {
+                await adapter.save({ libraryItems: nextLibraryItems });
+            }
+            lastSavedLibraryItemsHash = version;
+            return nextLibraryItems;
+        });
+    }
+    finally {
+        librarySaveCounter--;
+    }
+};
+export const useHandleLibrary = (opts) => {
+    const { excalidrawAPI } = opts;
+    const optsRef = useRef(opts);
+    optsRef.current = opts;
+    const isLibraryLoadedRef = useRef(false);
     useEffect(() => {
         if (!excalidrawAPI) {
             return;
         }
+        // reset on editor remount (excalidrawAPI changed)
+        isLibraryLoadedRef.current = false;
         const importLibraryFromURL = async ({ libraryUrl, idToken, }) => {
             const libraryPromise = new Promise(async (resolve, reject) => {
                 try {
@@ -357,20 +481,165 @@ export const useHandleLibrary = ({ excalidrawAPI, getInitialLibraryItems, }) =>
             }
         };
         // -------------------------------------------------------------------------
-        // ------ init load --------------------------------------------------------
-        if (getInitialLibraryRef.current) {
-            excalidrawAPI.updateLibrary({
-                libraryItems: getInitialLibraryRef.current(),
-            });
-        }
+        // ---------------------------------- init ---------------------------------
+        // -------------------------------------------------------------------------
         const libraryUrlTokens = parseLibraryTokensFromUrl();
         if (libraryUrlTokens) {
             importLibraryFromURL(libraryUrlTokens);
         }
+        // ------ (A) init load (legacy) -------------------------------------------
+        if ("getInitialLibraryItems" in optsRef.current &&
+            optsRef.current.getInitialLibraryItems) {
+            console.warn("useHandleLibrar `opts.getInitialLibraryItems` is deprecated. Use `opts.adapter` instead.");
+            Promise.resolve(optsRef.current.getInitialLibraryItems())
+                .then((libraryItems) => {
+                excalidrawAPI.updateLibrary({
+                    libraryItems,
+                    // merge with current library items because we may have already
+                    // populated it (e.g. by installing 3rd party library which can
+                    // happen before the DB data is loaded)
+                    merge: true,
+                });
+            })
+                .catch((error) => {
+                console.error(`UseHandeLibrary getInitialLibraryItems failed: ${error?.message}`);
+            });
+        }
+        // -------------------------------------------------------------------------
         // --------------------------------------------------------- init load -----
+        // -------------------------------------------------------------------------
+        // ------ (B) data source adapter ------------------------------------------
+        if ("adapter" in optsRef.current && optsRef.current.adapter) {
+            const adapter = optsRef.current.adapter;
+            const migrationAdapter = optsRef.current.migrationAdapter;
+            const initDataPromise = resolvablePromise();
+            // migrate from old data source if needed
+            // (note, if `migrate` function is defined, we always migrate even
+            //  if the data has already been migrated. In that case it'll be a no-op,
+            //  though with several unnecessary steps — we will still load latest
+            //  DB data during the `persistLibraryChange()` step)
+            // -----------------------------------------------------------------------
+            if (migrationAdapter) {
+                initDataPromise.resolve(promiseTry(migrationAdapter.load)
+                    .then(async (libraryData) => {
+                    let restoredData = null;
+                    try {
+                        // if no library data to migrate, assume no migration needed
+                        // and skip persisting to new data store, as well as well
+                        // clearing the old store via `migrationAdapter.clear()`
+                        if (!libraryData) {
+                            return AdapterTransaction.getLibraryItems(adapter, "load");
+                        }
+                        restoredData = restoreLibraryItems(libraryData.libraryItems || [], "published");
+                        // we don't queue this operation because it's running inside
+                        // a promise that's running inside Library update queue itself
+                        const nextItems = await persistLibraryUpdate(adapter, createLibraryUpdate([], restoredData));
+                        try {
+                            await migrationAdapter.clear();
+                        }
+                        catch (error) {
+                            console.error(`couldn't delete legacy library data: ${error.message}`);
+                        }
+                        // migration suceeded, load migrated data
+                        return nextItems;
+                    }
+                    catch (error) {
+                        console.error(`couldn't migrate legacy library data: ${error.message}`);
+                        // migration failed, load data from previous store, if any
+                        return restoredData;
+                    }
+                })
+                    // errors caught during `migrationAdapter.load()`
+                    .catch((error) => {
+                    console.error(`error during library migration: ${error.message}`);
+                    // as a default, load latest library from current data source
+                    return AdapterTransaction.getLibraryItems(adapter, "load");
+                }));
+            }
+            else {
+                initDataPromise.resolve(promiseTry(AdapterTransaction.getLibraryItems, adapter, "load"));
+            }
+            // load initial (or migrated) library
+            excalidrawAPI
+                .updateLibrary({
+                libraryItems: initDataPromise.then((libraryItems) => {
+                    const _libraryItems = libraryItems || [];
+                    lastSavedLibraryItemsHash = getLibraryItemsHash(_libraryItems);
+                    return _libraryItems;
+                }),
+                // merge with current library items because we may have already
+                // populated it (e.g. by installing 3rd party library which can
+                // happen before the DB data is loaded)
+                merge: true,
+            })
+                .finally(() => {
+                isLibraryLoadedRef.current = true;
+            });
+        }
+        // ---------------------------------------------- data source datapter -----
         window.addEventListener(EVENT.HASHCHANGE, onHashChange);
         return () => {
             window.removeEventListener(EVENT.HASHCHANGE, onHashChange);
         };
-    }, [excalidrawAPI]);
+    }, [
+        // important this useEffect only depends on excalidrawAPI so it only reruns
+        // on editor remounts (the excalidrawAPI changes)
+        excalidrawAPI,
+    ]);
+    // This effect is run without excalidrawAPI dependency so that host apps
+    // can run this hook outside of an active editor instance and the library
+    // update queue/loop survives editor remounts
+    //
+    // This effect is still only meant to be run if host apps supply an persitence
+    // adapter. If we don't have access to it, it the update listener doesn't
+    // do anything.
+    useEffect(() => {
+        // on update, merge with current library items and persist
+        // -----------------------------------------------------------------------
+        const unsubOnLibraryUpdate = onLibraryUpdateEmitter.on(async (update, nextLibraryItems) => {
+            const isLoaded = isLibraryLoadedRef.current;
+            // we want to operate with the latest adapter, but we don't want this
+            // effect to rerun on every adapter change in case host apps' adapter
+            // isn't stable
+            const adapter = ("adapter" in optsRef.current && optsRef.current.adapter) || null;
+            try {
+                if (adapter) {
+                    if (
+                    // if nextLibraryItems hash identical to previously saved hash,
+                    // exit early, even if actual upstream state ends up being
+                    // different (e.g. has more data than we have locally), as it'd
+                    // be low-impact scenario.
+                    lastSavedLibraryItemsHash !==
+                        getLibraryItemsHash(nextLibraryItems)) {
+                        await persistLibraryUpdate(adapter, update);
+                    }
+                }
+            }
+            catch (error) {
+                console.error(`couldn't persist library update: ${error.message}`, update);
+                // currently we only show error if an editor is loaded
+                if (isLoaded && optsRef.current.excalidrawAPI) {
+                    optsRef.current.excalidrawAPI.updateScene({
+                        appState: {
+                            errorMessage: t("errors.saveLibraryError"),
+                        },
+                    });
+                }
+            }
+        });
+        const onUnload = (event) => {
+            if (librarySaveCounter) {
+                preventUnload(event);
+            }
+        };
+        window.addEventListener(EVENT.BEFORE_UNLOAD, onUnload);
+        return () => {
+            window.removeEventListener(EVENT.BEFORE_UNLOAD, onUnload);
+            unsubOnLibraryUpdate();
+            lastSavedLibraryItemsHash = 0;
+            librarySaveCounter = 0;
+        };
+    }, [
+    // this effect must not have any deps so it doesn't rerun
+    ]);
 };