fix: smooth out schema-version edges

packages/excalidraw/components/PublishLibrary.tsx

@@ -9,6 +9,7 @@ import {
   chunk,
   getExportSource,
 } from "@excalidraw/common";
+import { SCHEMA_VERSIONS } from "../data/schema";
 
 import { EditorLocalStorage } from "../data/EditorLocalStorage";
 import { canvasToBlob, resizeImageFile } from "../data/blob";
@@ -280,6 +281,7 @@ const PublishLibrary = ({
     const libContent: ExportedLibraryData = {
       type: EXPORT_DATA_TYPES.excalidrawLibrary,
       version: VERSIONS.excalidrawLibrary,
+      schemaVersion: SCHEMA_VERSIONS.latest,
       source: getExportSource(),
       libraryItems: clonedLibItems,
     };

packages/excalidraw/data/blob.ts

@@ -235,7 +235,11 @@ export const parseLibraryJSON = (
     throw new Error("Invalid library");
   }
   const libraryItems = data.libraryItems || data.library;
-  return restoreLibraryItems(libraryItems, defaultStatus);
+  return restoreLibraryItems(
+    libraryItems,
+    defaultStatus,
+    resolveSchemaVersion(data.schemaVersion, SCHEMA_VERSIONS.initial),
+  );
 };
 
 export const loadLibraryFromBlob = async (

packages/excalidraw/data/json.ts

@@ -131,6 +131,7 @@ export const serializeLibraryAsJSON = (libraryItems: LibraryItems) => {
   const data: ExportedLibraryData = {
     type: EXPORT_DATA_TYPES.excalidrawLibrary,
     version: VERSIONS.excalidrawLibrary,
+    schemaVersion: SCHEMA_VERSIONS.latest,
     source: getExportSource(),
     libraryItems,
   };

packages/excalidraw/data/library.ts

@@ -33,6 +33,7 @@ import { t } from "../i18n";
 
 import { loadLibraryFromBlob } from "./blob";
 import { restoreLibraryItems } from "./restore";
+import { resolveSchemaVersion, SCHEMA_VERSIONS } from "./schema";
 
 import type App from "../components/App";
 
@@ -65,9 +66,10 @@ type LibraryUpdate = {
   updatedItems: Map<LibraryItem["id"], LibraryItem>;
 };
 
-// an object so that we can later add more properties to it without breaking,
-// such as schema version
-export type LibraryPersistedData = { libraryItems: LibraryItems };
+export type LibraryPersistedData = {
+  libraryItems: LibraryItems;
+  schemaVersion?: number;
+};
 
 const onLibraryUpdateEmitter = new Emitter<
   [update: LibraryUpdate, libraryItems: LibraryItems]
@@ -89,7 +91,9 @@ export interface LibraryPersistenceAdapter {
      * purposes, in which case host app can implement more aggressive caching.
      */
     source: LibraryAdatapterSource;
-  }): MaybePromise<{ libraryItems: LibraryItems_anyVersion } | null>;
+  }): MaybePromise<
+    { libraryItems: LibraryItems_anyVersion; schemaVersion?: number } | null
+  >;
   /** Should persist to the database as is (do no change the data structure). */
   save(libraryData: LibraryPersistedData): MaybePromise<void>;
 }
@@ -99,7 +103,9 @@ export interface LibraryMigrationAdapter {
    * loads data from legacy data source. Returns `null` if no data is
    * to be migrated.
    */
-  load(): MaybePromise<{ libraryItems: LibraryItems_anyVersion } | null>;
+  load(): MaybePromise<
+    { libraryItems: LibraryItems_anyVersion; schemaVersion?: number } | null
+  >;
 
   /** clears entire storage afterwards */
   clear(): MaybePromise<void>;
@@ -554,7 +560,13 @@ class AdapterTransaction {
       new Promise<LibraryItems>(async (resolve, reject) => {
         try {
           const data = await adapter.load({ source });
-          resolve(restoreLibraryItems(data?.libraryItems || [], "published"));
+          resolve(
+            restoreLibraryItems(
+              data?.libraryItems || [],
+              "published",
+              resolveSchemaVersion(data?.schemaVersion, SCHEMA_VERSIONS.initial),
+            ),
+          );
         } catch (error: any) {
           reject(error);
         }
@@ -662,7 +674,10 @@ const persistLibraryUpdate = async (
       const version = getLibraryItemsHash(nextLibraryItems);
 
       if (version !== lastSavedLibraryItemsHash) {
-        await adapter.save({ libraryItems: nextLibraryItems });
+        await adapter.save({
+          libraryItems: nextLibraryItems,
+          schemaVersion: SCHEMA_VERSIONS.latest,
+        });
       }
 
       lastSavedLibraryItemsHash = version;
@@ -862,6 +877,10 @@ export const useHandleLibrary = (
                 restoredData = restoreLibraryItems(
                   libraryData.libraryItems || [],
                   "published",
+                  resolveSchemaVersion(
+                    libraryData.schemaVersion,
+                    SCHEMA_VERSIONS.initial,
+                  ),
                 );
 
                 // we don't queue this operation because it's running inside

packages/excalidraw/data/restore.ts

@@ -81,6 +81,7 @@ import {
   getNormalizedGridStep,
   getNormalizedZoom,
 } from "../scene";
+import { migrateElementsBySchema, SCHEMA_VERSIONS } from "./schema";
 
 import type {
   AppState,
@@ -956,9 +957,15 @@ export const restoreAppState = (
   };
 };
 
-const restoreLibraryItem = (libraryItem: LibraryItem) => {
+const restoreLibraryItem = (
+  libraryItem: LibraryItem,
+  schemaVersion: number,
+) => {
   const elements = restoreElements(
-    getNonDeletedElements(libraryItem.elements),
+    migrateElementsBySchema(
+      getNonDeletedElements(libraryItem.elements),
+      schemaVersion,
+    ),
     null,
   );
   return elements.length ? { ...libraryItem, elements } : null;
@@ -967,6 +974,7 @@ const restoreLibraryItem = (libraryItem: LibraryItem) => {
 export const restoreLibraryItems = (
   libraryItems: ImportedDataState["libraryItems"] = [],
   defaultStatus: LibraryItem["status"],
+  schemaVersion: number = SCHEMA_VERSIONS.latest,
 ) => {
   const restoredItems: LibraryItem[] = [];
   for (const item of libraryItems) {
@@ -977,7 +985,7 @@ export const restoreLibraryItems = (
         elements: item,
         id: randomId(),
         created: Date.now(),
-      });
+      }, schemaVersion);
       if (restoredItem) {
         restoredItems.push(restoredItem);
       }
@@ -991,7 +999,7 @@ export const restoreLibraryItems = (
         id: _item.id || randomId(),
         status: _item.status || defaultStatus,
         created: _item.created || Date.now(),
-      });
+      }, schemaVersion);
       if (restoredItem) {
         restoredItems.push(restoredItem);
       }

packages/excalidraw/data/types.ts

@@ -54,6 +54,7 @@ export interface ImportedDataState {
 export interface ExportedLibraryData {
   type: string;
   version: typeof VERSIONS.excalidrawLibrary;
+  schemaVersion: number;
   source: string;
   libraryItems: LibraryItems;
 }

packages/excalidraw/tests/data/restore.test.ts

@@ -1,7 +1,12 @@
 import { pointFrom } from "@excalidraw/math";
 import { vi } from "vitest";
 
-import { DEFAULT_SIDEBAR, FONT_FAMILY, ROUNDNESS } from "@excalidraw/common";
+import {
+  DEFAULT_ELEMENT_PROPS,
+  DEFAULT_SIDEBAR,
+  FONT_FAMILY,
+  ROUNDNESS,
+} from "@excalidraw/common";
 
 import { newElementWith } from "@excalidraw/element";
 import * as sizeHelpers from "@excalidraw/element";
@@ -19,6 +24,7 @@ import type { NormalizedZoomValue } from "@excalidraw/excalidraw/types";
 
 import { API } from "../helpers/api";
 import * as restore from "../../data/restore";
+import { SCHEMA_VERSIONS } from "../../data/schema";
 import { getDefaultAppState } from "../../appState";
 
 import type { ImportedDataState } from "../../data/types";
@@ -96,6 +102,53 @@ describe("restoreElements", () => {
     expect(restoredFrame.backgroundColor).toBe("#ffc9c9");
   });
 
+  it("should restore library frame backgrounds by default", () => {
+    const frame = API.createElement({
+      type: "frame",
+      backgroundColor: "#a5d8ff",
+    });
+
+    const restoredLibraryItems = restore.restoreLibraryItems(
+      [
+        {
+          id: "library-item-1",
+          status: "published",
+          elements: [frame],
+          created: Date.now(),
+        },
+      ],
+      "published",
+    );
+
+    expect(
+      (restoredLibraryItems[0].elements[0] as ExcalidrawElement).backgroundColor,
+    ).toBe("#a5d8ff");
+  });
+
+  it("should normalize legacy library frame backgrounds when schema is old", () => {
+    const frame = API.createElement({
+      type: "frame",
+      backgroundColor: "#a5d8ff",
+    });
+
+    const restoredLibraryItems = restore.restoreLibraryItems(
+      [
+        {
+          id: "library-item-1",
+          status: "published",
+          elements: [frame],
+          created: Date.now(),
+        },
+      ],
+      "published",
+      SCHEMA_VERSIONS.initial,
+    );
+
+    expect(
+      (restoredLibraryItems[0].elements[0] as ExcalidrawElement).backgroundColor,
+    ).toBe(DEFAULT_ELEMENT_PROPS.backgroundColor);
+  });
+
   it("should restore text element correctly passing value for each attribute", () => {
     const textElement = API.createElement({
       type: "text",

packages/excalidraw/tests/library.test.tsx

@@ -11,6 +11,7 @@ import type { ExcalidrawGenericElement } from "@excalidraw/element/types";
 import { parseLibraryJSON } from "../data/blob";
 import { serializeLibraryAsJSON } from "../data/json";
 import { distributeLibraryItemsOnSquareGrid } from "../data/library";
+import { SCHEMA_VERSIONS } from "../data/schema";
 import { Excalidraw } from "../index";
 
 import { API } from "./helpers/api";
@@ -167,6 +168,13 @@ describe("library", () => {
     });
   });
 
+  it("should include schema version when serializing library", () => {
+    const serialized = serializeLibraryAsJSON([]);
+    const parsed = JSON.parse(serialized);
+
+    expect(parsed.schemaVersion).toBe(SCHEMA_VERSIONS.latest);
+  });
+
   // NOTE: mocked to test logic, not actual drag&drop via UI
   it("drop library item onto canvas", async () => {
     expect(h.elements).toEqual([]);