Merge branch 'master' into mrazator/delta-based-sync

excalidraw-app/App.tsx

@@ -1,3 +1,7 @@
+import Slider from "rc-slider";
+
+import "rc-slider/assets/index.css";
+
 import {
   Excalidraw,
   LiveCollaborationTrigger,
@@ -30,6 +34,7 @@ import {
   resolvablePromise,
   isRunningInIframe,
   isDevEnv,
+  assertNever,
 } from "@excalidraw/common";
 import polyfill from "@excalidraw/excalidraw/polyfill";
 import { useCallback, useEffect, useRef, useState } from "react";
@@ -56,6 +61,7 @@ import {
   parseLibraryTokensFromUrl,
   useHandleLibrary,
 } from "@excalidraw/excalidraw/data/library";
+import { StoreDelta, DurableStoreIncrement, EphemeralStoreIncrement, StoreIncrement } from "@excalidraw/excalidraw/store";
 
 import type { RemoteExcalidrawElement } from "@excalidraw/excalidraw/data/reconcile";
 import type { RestoredDataState } from "@excalidraw/excalidraw/data/restore";
@@ -63,6 +69,7 @@ import type {
   FileId,
   NonDeletedExcalidrawElement,
   OrderedExcalidrawElement,
+  SceneElementsMap,
 } from "@excalidraw/element/types";
 import type {
   AppState,
@@ -92,6 +99,7 @@ import Collab, {
   collabAPIAtom,
   isCollaboratingAtom,
   isOfflineAtom,
+  syncApiAtom,
 } from "./collab/Collab";
 import { AppFooter } from "./components/AppFooter";
 import { AppMainMenu } from "./components/AppMainMenu";
@@ -368,11 +376,40 @@ const ExcalidrawWrapper = () => {
 
   const [, setShareDialogState] = useAtom(shareDialogStateAtom);
   const [collabAPI] = useAtom(collabAPIAtom);
+  const [syncAPI] = useAtom(syncApiAtom);
+  const [sliderVersion, setSliderVersion] = useState(0);
+  const [acknowledgedDeltas, setAcknowledgedDeltas] = useState<StoreDelta[]>(
+    [],
+  );
+  const acknowledgedDeltasRef = useRef<StoreDelta[]>(acknowledgedDeltas);
   const [isCollaborating] = useAtomWithInitialValue(isCollaboratingAtom, () => {
     return isCollaborationLink(window.location.href);
   });
   const collabError = useAtomValue(collabErrorIndicatorAtom);
 
+  useEffect(() => {
+    acknowledgedDeltasRef.current = acknowledgedDeltas;
+  }, [acknowledgedDeltas]);
+
+  useEffect(() => {
+    const interval = setInterval(() => {
+      const deltas = syncAPI?.acknowledgedDeltas ?? [];
+
+      // CFDO: buffer local deltas as well, not only acknowledged ones
+      if (deltas.length > acknowledgedDeltasRef.current.length) {
+        setAcknowledgedDeltas([...deltas]);
+        setSliderVersion(deltas.length);
+      }
+    }, 1000);
+
+    syncAPI?.connect();
+
+    return () => {
+      syncAPI?.disconnect();
+      clearInterval(interval);
+    };
+  }, [syncAPI]);
+
   useHandleLibrary({
     excalidrawAPI,
     adapter: LibraryIndexedDBAdapter,
@@ -675,6 +712,34 @@ const ExcalidrawWrapper = () => {
     }
   };
 
+  const onIncrement = (
+    increment: DurableStoreIncrement | EphemeralStoreIncrement,
+  ) => {
+    try {
+      if (!syncAPI) {
+        return;
+      }
+
+      if (StoreIncrement.isDurable(increment)) {
+        // push only if there are element changes
+        if (!increment.delta.elements.isEmpty()) {
+          syncAPI.push(increment.delta);
+        }
+
+        return;
+      }
+
+      if (StoreIncrement.isEphemeral(increment)) {
+        syncAPI.relay(increment.change);
+        return;
+      }
+
+      assertNever(increment, `Unknown increment type`);
+    } catch (e) {
+      console.error("Error during onIncrement handler", e);
+    }
+  };
+
   const [latestShareableLink, setLatestShareableLink] = useState<string | null>(
     null,
   );
@@ -797,6 +862,57 @@ const ExcalidrawWrapper = () => {
     },
   };
 
+  const debouncedTimeTravel = debounce(
+    (value: number, direction: "forward" | "backward") => {
+      if (!excalidrawAPI) {
+        return;
+      }
+
+      let nextAppState = excalidrawAPI.getAppState();
+      // CFDO: retrieve the scene map already
+      let nextElements = new Map(
+        excalidrawAPI.getSceneElements().map((x) => [x.id, x]),
+      ) as SceneElementsMap;
+
+      let deltas: StoreDelta[] = [];
+
+      // CFDO I: going both in collaborative setting means the (acknowledge) deltas need to have applied latest changes
+      switch (direction) {
+        case "forward": {
+          deltas = acknowledgedDeltas.slice(sliderVersion, value) ?? [];
+          break;
+        }
+        case "backward": {
+          deltas = acknowledgedDeltas
+            .slice(value)
+            .reverse()
+            .map((x) => StoreDelta.inverse(x));
+          break;
+        }
+        default:
+          assertNever(direction, `Unknown direction: ${direction}`);
+      }
+
+      for (const delta of deltas) {
+        [nextElements, nextAppState] = excalidrawAPI.store.applyDeltaTo(
+          delta,
+          nextElements,
+          nextAppState,
+        );
+      }
+
+      excalidrawAPI?.updateScene({
+        appState: {
+          ...nextAppState,
+          viewModeEnabled: value !== acknowledgedDeltas.length,
+        },
+        elements: Array.from(nextElements.values()),
+        captureUpdate: CaptureUpdateAction.NEVER,
+      });
+    },
+    0,
+  );
+
   return (
     <div
       style={{ height: "100%" }}
@@ -804,9 +920,45 @@ const ExcalidrawWrapper = () => {
         "is-collaborating": isCollaborating,
       })}
     >
+      <Slider
+        style={{
+          position: "fixed",
+          bottom: "25px",
+          zIndex: 999,
+          width: "60%",
+          left: "25%",
+        }}
+        step={1}
+        min={0}
+        max={acknowledgedDeltas.length}
+        value={sliderVersion}
+        onChange={(value) => {
+          const nextSliderVersion = value as number;
+          // CFDO: in safari the whole canvas gets selected when dragging
+          if (nextSliderVersion !== acknowledgedDeltas.length) {
+            // don't listen to updates in the detached mode
+            syncAPI?.disconnect();
+          } else {
+            // reconnect once we're back to the latest version
+            syncAPI?.connect();
+          }
+
+          if (nextSliderVersion === sliderVersion) {
+            return;
+          }
+
+          debouncedTimeTravel(
+            nextSliderVersion,
+            nextSliderVersion < sliderVersion ? "backward" : "forward",
+          );
+
+          setSliderVersion(nextSliderVersion);
+        }}
+      />
       <Excalidraw
         excalidrawAPI={excalidrawRefCallback}
         onChange={onChange}
+        onIncrement={onIncrement}
         initialData={initialStatePromiseRef.current.promise}
         isCollaborating={isCollaborating}
         onPointerUpdate={collabAPI?.onPointerUpdate}
@@ -885,7 +1037,6 @@ const ExcalidrawWrapper = () => {
         />
         <OverwriteConfirmDialog>
           <OverwriteConfirmDialog.Actions.ExportToImage />
-          <OverwriteConfirmDialog.Actions.SaveToDisk />
           {excalidrawAPI && (
             <OverwriteConfirmDialog.Action
               title={t("overwriteConfirm.action.excalidrawPlus.title")}

excalidraw-app/app_constants.ts

@@ -45,6 +45,7 @@ export const STORAGE_KEYS = {
   VERSION_FILES: "version-files",
 
   IDB_LIBRARY: "excalidraw-library",
+  IDB_SYNC: "excalidraw-sync",
 
   // do not use apart from migrations
   __LEGACY_LOCAL_STORAGE_LIBRARY: "excalidraw-library",

excalidraw-app/collab/Collab.tsx

@@ -73,7 +73,7 @@ import {
   FileManager,
   updateStaleImageStatuses,
 } from "../data/FileManager";
-import { LocalData } from "../data/LocalData";
+import { LocalData, SyncIndexedDBAdapter } from "../data/LocalData";
 import {
   isSavedToFirebase,
   loadFilesFromFirebase,
@@ -95,6 +95,7 @@ import type {
   SyncableExcalidrawElement,
 } from "../data";
 
+export const syncApiAtom = atom<SyncClient | null>(null);
 export const collabAPIAtom = atom<CollabAPI | null>(null);
 export const isCollaboratingAtom = atom(false);
 export const isOfflineAtom = atom(false);
@@ -241,6 +242,12 @@ class Collab extends PureComponent<CollabProps, CollabState> {
 
     appJotaiStore.set(collabAPIAtom, collabAPI);
 
+    SyncClient.create(this.excalidrawAPI, SyncIndexedDBAdapter).then(
+      (syncAPI) => {
+        appJotaiStore.set(syncApiAtom, syncAPI);
+      },
+    );
+
     if (isTestEnv() || isDevEnv()) {
       window.collab = window.collab || ({} as Window["collab"]);
       Object.defineProperties(window, {
@@ -274,6 +281,8 @@ class Collab extends PureComponent<CollabProps, CollabState> {
       window.clearTimeout(this.idleTimeoutId);
       this.idleTimeoutId = null;
     }
+
+    appJotaiStore.get(syncApiAtom)?.disconnect();
     this.onUmmount?.();
   }
 

excalidraw-app/data/LocalData.ts

@@ -27,6 +27,8 @@ import {
   get,
 } from "idb-keyval";
 
+import { StoreDelta } from "@excalidraw/excalidraw/store";
+
 import type { LibraryPersistedData } from "@excalidraw/excalidraw/data/library";
 import type { ImportedDataState } from "@excalidraw/excalidraw/data/types";
 import type { ExcalidrawElement, FileId } from "@excalidraw/element/types";
@@ -35,7 +37,7 @@ import type {
   BinaryFileData,
   BinaryFiles,
 } from "@excalidraw/excalidraw/types";
-import type { MaybePromise } from "@excalidraw/common/utility-types";
+import type { DTO, MaybePromise } from "@excalidraw/common/utility-types";
 
 import { SAVE_TO_LOCAL_STORAGE_TIMEOUT, STORAGE_KEYS } from "../app_constants";
 
@@ -104,13 +106,12 @@ export class LocalData {
       files: BinaryFiles,
       onFilesSaved: () => void,
     ) => {
-      saveDataStateToLocalStorage(elements, appState);
-
-      await this.fileStorage.saveFiles({
-        elements,
-        files,
-      });
-      onFilesSaved();
+      // saveDataStateToLocalStorage(elements, appState);
+      // await this.fileStorage.saveFiles({
+      //   elements,
+      //   files,
+      // });
+      // onFilesSaved();
     },
     SAVE_TO_LOCAL_STORAGE_TIMEOUT,
   );
@@ -256,3 +257,60 @@ export class LibraryLocalStorageMigrationAdapter {
     localStorage.removeItem(STORAGE_KEYS.__LEGACY_LOCAL_STORAGE_LIBRARY);
   }
 }
+
+type SyncDeltaPersistedData = DTO<StoreDelta>[];
+
+type SyncMetaPersistedData = {
+  lastAcknowledgedVersion: number;
+};
+
+export class SyncIndexedDBAdapter {
+  /** IndexedDB database and store name */
+  private static idb_name = STORAGE_KEYS.IDB_SYNC;
+  /** library data store keys */
+  private static deltasKey = "deltas";
+  private static metadataKey = "metadata";
+
+  private static store = createStore(
+    `${SyncIndexedDBAdapter.idb_name}-db`,
+    `${SyncIndexedDBAdapter.idb_name}-store`,
+  );
+
+  static async loadDeltas() {
+    const deltas = await get<SyncDeltaPersistedData>(
+      SyncIndexedDBAdapter.deltasKey,
+      SyncIndexedDBAdapter.store,
+    );
+
+    if (deltas?.length) {
+      return deltas.map((storeDeltaDTO) => StoreDelta.restore(storeDeltaDTO));
+    }
+
+    return null;
+  }
+
+  static async saveDeltas(data: SyncDeltaPersistedData): Promise<void> {
+    return set(
+      SyncIndexedDBAdapter.deltasKey,
+      data,
+      SyncIndexedDBAdapter.store,
+    );
+  }
+
+  static async loadMetadata() {
+    const metadata = await get<SyncMetaPersistedData>(
+      SyncIndexedDBAdapter.metadataKey,
+      SyncIndexedDBAdapter.store,
+    );
+
+    return metadata || null;
+  }
+
+  static async saveMetadata(data: SyncMetaPersistedData): Promise<void> {
+    return set(
+      SyncIndexedDBAdapter.metadataKey,
+      data,
+      SyncIndexedDBAdapter.store,
+    );
+  }
+}

excalidraw-app/package.json

@@ -33,6 +33,7 @@
     "i18next-browser-languagedetector": "6.1.4",
     "idb-keyval": "6.0.3",
     "jotai": "2.11.0",
+    "rc-slider": "11.1.7",
     "react": "19.0.0",
     "react-dom": "19.0.0",
     "socket.io-client": "4.7.2",

excalidraw-app/tests/collab.test.tsx

@@ -122,7 +122,7 @@ describe("collaboration", () => {
       expect(h.elements).toEqual([expect.objectContaining(rect1Props)]);
     });
 
-    const undoAction = createUndoAction(h.history, h.store);
+    const undoAction = createUndoAction(h.history);
     act(() => h.app.actionManager.executeAction(undoAction));
 
     // with explicit undo (as addition) we expect our item to be restored from the snapshot!
@@ -154,7 +154,7 @@ describe("collaboration", () => {
       expect(h.elements).toEqual([expect.objectContaining(rect1Props)]);
     });
 
-    const redoAction = createRedoAction(h.history, h.store);
+    const redoAction = createRedoAction(h.history);
     act(() => h.app.actionManager.executeAction(redoAction));
 
     // with explicit redo (as removal) we again restore the element from the snapshot!

packages/common/src/utility-types.ts

@@ -66,5 +66,10 @@ export type MakeBrand<T extends string> = {
 /** Maybe just promise or already fulfilled one! */
 export type MaybePromise<T> = T | Promise<T>;
 
+/** Strip all the methods or functions from a type */
+export type DTO<T> = {
+  [K in keyof T as T[K] extends Function ? never : K]: T[K];
+};
+
 // get union of all keys from the union of types
 export type AllPossibleKeys<T> = T extends any ? keyof T : never;

packages/deltas/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@excalidraw/deltas",
+  "version": "0.0.1",
+  "main": "./dist/prod/index.js",
+  "type": "module",
+  "module": "./dist/prod/index.js",
+  "exports": {
+    ".": {
+      "development": "./dist/dev/index.js",
+      "default": "./dist/prod/index.js"
+    }
+  },
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist/*"
+  ],
+  "description": "Excalidraw utilities for handling deltas",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "keywords": [
+    "excalidraw",
+    "excalidraw-deltas"
+  ],
+  "dependencies": {
+    "nanoid": "5.0.9",
+    "roughjs": "4.6.6"
+  },
+  "devDependencies": {},
+  "bugs": "https://github.com/excalidraw/excalidraw/issues",
+  "repository": "https://github.com/excalidraw/excalidraw",
+  "scripts": {
+    "gen:types": "rm -rf types && tsc",
+    "build:esm": "rm -rf dist && node ../../scripts/buildShared.js && yarn gen:types",
+    "pack": "yarn build:umd && yarn pack"
+  }
+}

packages/deltas/src/common/delta.ts

@@ -0,0 +1,357 @@
+import { arrayToObject, assertNever } from "./utils";
+
+/**
+ * Represents the difference between two objects of the same type.
+ *
+ * Both `deleted` and `inserted` partials represent the same set of added, removed or updated properties, where:
+ * - `deleted` is a set of all the deleted values
+ * - `inserted` is a set of all the inserted (added, updated) values
+ *
+ * Keeping it as pure object (without transient state, side-effects, etc.), so we won't have to instantiate it on load.
+ */
+export class Delta<T> {
+  private constructor(
+    public readonly deleted: Partial<T>,
+    public readonly inserted: Partial<T>,
+  ) {}
+
+  public static create<T>(
+    deleted: Partial<T>,
+    inserted: Partial<T>,
+    modifier?: (delta: Partial<T>) => Partial<T>,
+    modifierOptions?: "deleted" | "inserted",
+  ) {
+    const modifiedDeleted =
+      modifier && modifierOptions !== "inserted" ? modifier(deleted) : deleted;
+    const modifiedInserted =
+      modifier && modifierOptions !== "deleted" ? modifier(inserted) : inserted;
+
+    return new Delta(modifiedDeleted, modifiedInserted);
+  }
+
+  /**
+   * Calculates the delta between two objects.
+   *
+   * @param prevObject - The previous state of the object.
+   * @param nextObject - The next state of the object.
+   *
+   * @returns new delta instance.
+   */
+  public static calculate<T extends { [key: string]: any }>(
+    prevObject: T,
+    nextObject: T,
+    modifier?: (partial: Partial<T>) => Partial<T>,
+    postProcess?: (
+      deleted: Partial<T>,
+      inserted: Partial<T>,
+    ) => [Partial<T>, Partial<T>],
+  ): Delta<T> {
+    if (prevObject === nextObject) {
+      return Delta.empty();
+    }
+
+    const deleted = {} as Partial<T>;
+    const inserted = {} as Partial<T>;
+
+    // O(n^3) here for elements, but it's not as bad as it looks:
+    // - we do this only on store recordings, not on every frame (not for ephemerals)
+    // - we do this only on previously detected changed elements
+    // - we do shallow compare only on the first level of properties (not going any deeper)
+    // - # of properties is reasonably small
+    for (const key of this.distinctKeysIterator(
+      "full",
+      prevObject,
+      nextObject,
+    )) {
+      deleted[key as keyof T] = prevObject[key];
+      inserted[key as keyof T] = nextObject[key];
+    }
+
+    const [processedDeleted, processedInserted] = postProcess
+      ? postProcess(deleted, inserted)
+      : [deleted, inserted];
+
+    return Delta.create(processedDeleted, processedInserted, modifier);
+  }
+
+  public static empty() {
+    return new Delta({}, {});
+  }
+
+  public static isEmpty<T>(delta: Delta<T>): boolean {
+    return (
+      !Object.keys(delta.deleted).length && !Object.keys(delta.inserted).length
+    );
+  }
+
+  /**
+   * Merges deleted and inserted object partials.
+   */
+  public static mergeObjects<T extends { [key: string]: unknown }>(
+    prev: T,
+    added: T,
+    removed: T,
+  ) {
+    const cloned = { ...prev };
+
+    for (const key of Object.keys(removed)) {
+      delete cloned[key];
+    }
+
+    return { ...cloned, ...added };
+  }
+
+  /**
+   * Merges deleted and inserted array partials.
+   */
+  public static mergeArrays<T>(
+    prev: readonly T[] | null,
+    added: readonly T[] | null | undefined,
+    removed: readonly T[] | null | undefined,
+    predicate?: (value: T) => string,
+  ) {
+    return Object.values(
+      Delta.mergeObjects(
+        arrayToObject(prev ?? [], predicate),
+        arrayToObject(added ?? [], predicate),
+        arrayToObject(removed ?? [], predicate),
+      ),
+    );
+  }
+
+  /**
+   * Diff object partials as part of the `postProcess`.
+   */
+  public static diffObjects<T, K extends keyof T, V extends T[K][keyof T[K]]>(
+    deleted: Partial<T>,
+    inserted: Partial<T>,
+    property: K,
+    setValue: (prevValue: V | undefined) => V,
+  ) {
+    if (!deleted[property] && !inserted[property]) {
+      return;
+    }
+
+    if (
+      typeof deleted[property] === "object" ||
+      typeof inserted[property] === "object"
+    ) {
+      type RecordLike = Record<string, V | undefined>;
+
+      const deletedObject: RecordLike = deleted[property] ?? {};
+      const insertedObject: RecordLike = inserted[property] ?? {};
+
+      const deletedDifferences = Delta.getLeftDifferences(
+        deletedObject,
+        insertedObject,
+      ).reduce((acc, curr) => {
+        acc[curr] = setValue(deletedObject[curr]);
+        return acc;
+      }, {} as RecordLike);
+
+      const insertedDifferences = Delta.getRightDifferences(
+        deletedObject,
+        insertedObject,
+      ).reduce((acc, curr) => {
+        acc[curr] = setValue(insertedObject[curr]);
+        return acc;
+      }, {} as RecordLike);
+
+      if (
+        Object.keys(deletedDifferences).length ||
+        Object.keys(insertedDifferences).length
+      ) {
+        Reflect.set(deleted, property, deletedDifferences);
+        Reflect.set(inserted, property, insertedDifferences);
+      } else {
+        Reflect.deleteProperty(deleted, property);
+        Reflect.deleteProperty(inserted, property);
+      }
+    }
+  }
+
+  /**
+   * Diff array partials as part of the `postProcess`.
+   */
+  public static diffArrays<T, K extends keyof T, V extends T[K]>(
+    deleted: Partial<T>,
+    inserted: Partial<T>,
+    property: K,
+    groupBy: (value: V extends ArrayLike<infer T> ? T : never) => string,
+  ) {
+    if (!deleted[property] && !inserted[property]) {
+      return;
+    }
+
+    if (Array.isArray(deleted[property]) || Array.isArray(inserted[property])) {
+      const deletedArray = (
+        Array.isArray(deleted[property]) ? deleted[property] : []
+      ) as [];
+      const insertedArray = (
+        Array.isArray(inserted[property]) ? inserted[property] : []
+      ) as [];
+
+      const deletedDifferences = arrayToObject(
+        Delta.getLeftDifferences(
+          arrayToObject(deletedArray, groupBy),
+          arrayToObject(insertedArray, groupBy),
+        ),
+      );
+      const insertedDifferences = arrayToObject(
+        Delta.getRightDifferences(
+          arrayToObject(deletedArray, groupBy),
+          arrayToObject(insertedArray, groupBy),
+        ),
+      );
+
+      if (
+        Object.keys(deletedDifferences).length ||
+        Object.keys(insertedDifferences).length
+      ) {
+        const deletedValue = deletedArray.filter(
+          (x) => deletedDifferences[groupBy ? groupBy(x) : String(x)],
+        );
+        const insertedValue = insertedArray.filter(
+          (x) => insertedDifferences[groupBy ? groupBy(x) : String(x)],
+        );
+
+        Reflect.set(deleted, property, deletedValue);
+        Reflect.set(inserted, property, insertedValue);
+      } else {
+        Reflect.deleteProperty(deleted, property);
+        Reflect.deleteProperty(inserted, property);
+      }
+    }
+  }
+
+  /**
+   * Compares if object1 contains any different value compared to the object2.
+   */
+  public static isLeftDifferent<T extends {}>(
+    object1: T,
+    object2: T,
+    skipShallowCompare = false,
+  ): boolean {
+    const anyDistinctKey = this.distinctKeysIterator(
+      "left",
+      object1,
+      object2,
+      skipShallowCompare,
+    ).next().value;
+
+    return !!anyDistinctKey;
+  }
+
+  /**
+   * Compares if object2 contains any different value compared to the object1.
+   */
+  public static isRightDifferent<T extends {}>(
+    object1: T,
+    object2: T,
+    skipShallowCompare = false,
+  ): boolean {
+    const anyDistinctKey = this.distinctKeysIterator(
+      "right",
+      object1,
+      object2,
+      skipShallowCompare,
+    ).next().value;
+
+    return !!anyDistinctKey;
+  }
+
+  /**
+   * Returns all the object1 keys that have distinct values.
+   */
+  public static getLeftDifferences<T extends {}>(
+    object1: T,
+    object2: T,
+    skipShallowCompare = false,
+  ) {
+    return Array.from(
+      this.distinctKeysIterator("left", object1, object2, skipShallowCompare),
+    );
+  }
+
+  /**
+   * Returns all the object2 keys that have distinct values.
+   */
+  public static getRightDifferences<T extends {}>(
+    object1: T,
+    object2: T,
+    skipShallowCompare = false,
+  ) {
+    return Array.from(
+      this.distinctKeysIterator("right", object1, object2, skipShallowCompare),
+    );
+  }
+
+  /**
+   * Iterator comparing values of object properties based on the passed joining strategy.
+   *
+   * @yields keys of properties with different values
+   *
+   * WARN: it's based on shallow compare performed only on the first level and doesn't go deeper than that.
+   */
+  private static *distinctKeysIterator<T extends {}>(
+    join: "left" | "right" | "full",
+    object1: T,
+    object2: T,
+    skipShallowCompare = false,
+  ) {
+    if (object1 === object2) {
+      return;
+    }
+
+    let keys: string[] = [];
+
+    if (join === "left") {
+      keys = Object.keys(object1);
+    } else if (join === "right") {
+      keys = Object.keys(object2);
+    } else if (join === "full") {
+      keys = Array.from(
+        new Set([...Object.keys(object1), ...Object.keys(object2)]),
+      );
+    } else {
+      assertNever(join, "Unknown distinctKeysIterator's join param");
+    }
+
+    for (const key of keys) {
+      const object1Value = object1[key as keyof T];
+      const object2Value = object2[key as keyof T];
+
+      if (object1Value !== object2Value) {
+        if (
+          !skipShallowCompare &&
+          typeof object1Value === "object" &&
+          typeof object2Value === "object" &&
+          object1Value !== null &&
+          object2Value !== null &&
+          this.isShallowEqual(object1Value, object2Value)
+        ) {
+          continue;
+        }
+
+        yield key;
+      }
+    }
+  }
+
+  private static isShallowEqual(object1: any, object2: any) {
+    const keys1 = Object.keys(object1);
+    const keys2 = Object.keys(object1);
+
+    if (keys1.length !== keys2.length) {
+      return false;
+    }
+
+    for (const key of keys1) {
+      if (object1[key] !== object2[key]) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+}

packages/deltas/src/common/interfaces.ts

@@ -0,0 +1,21 @@
+/**
+ * Encapsulates a set of application-level `Delta`s.
+ */
+export interface DeltaContainer<T> {
+  /**
+   * Inverses the `Delta`s while creating a new `DeltaContainer` instance.
+   */
+  inverse(): DeltaContainer<T>;
+
+  /**
+   * Applies the `Delta`s to the previous object.
+   *
+   * @returns a tuple of the next object `T` with applied `Delta`s, and `boolean`, indicating whether the applied deltas resulted in a visible change.
+   */
+  applyTo(previous: T, ...options: unknown[]): [T, boolean];
+
+  /**
+   * Checks whether all `Delta`s are empty.
+   */
+  isEmpty(): boolean;
+}

packages/deltas/src/common/utils.ts

@@ -0,0 +1,149 @@
+import { Random } from "roughjs/bin/math";
+import { nanoid } from "nanoid";
+
+import type {
+  AppState,
+  ObservedAppState,
+  ElementsMap,
+  ExcalidrawElement,
+  ElementUpdate,
+} from "../excalidraw-types";
+
+/**
+ * Transform array into an object, use only when array order is irrelevant.
+ */
+export const arrayToObject = <T>(
+  array: readonly T[],
+  groupBy?: (value: T) => string | number,
+) =>
+  array.reduce((acc, value) => {
+    acc[groupBy ? groupBy(value) : String(value)] = value;
+    return acc;
+  }, {} as { [key: string]: T });
+
+/**
+ * Transforms array of elements with `id` property into into a Map grouped by `id`.
+ */
+export const elementsToMap = <T extends { id: string }>(
+  items: readonly T[],
+) => {
+  return items.reduce((acc: Map<string, T>, element) => {
+    acc.set(element.id, element);
+    return acc;
+  }, new Map());
+};
+
+// --
+
+// hidden non-enumerable property for runtime checks
+const hiddenObservedAppStateProp = "__observedAppState";
+
+export const getObservedAppState = (appState: AppState): ObservedAppState => {
+  const observedAppState = {
+    name: appState.name,
+    editingGroupId: appState.editingGroupId,
+    viewBackgroundColor: appState.viewBackgroundColor,
+    selectedElementIds: appState.selectedElementIds,
+    selectedGroupIds: appState.selectedGroupIds,
+    editingLinearElementId: appState.editingLinearElement?.elementId || null,
+    selectedLinearElementId: appState.selectedLinearElement?.elementId || null,
+    croppingElementId: appState.croppingElementId,
+  };
+
+  Reflect.defineProperty(observedAppState, hiddenObservedAppStateProp, {
+    value: true,
+    enumerable: false,
+  });
+
+  return observedAppState;
+};
+
+// ------------------------------------------------------------
+
+export const assertNever = (value: never, message: string): never => {
+  throw new Error(`${message}: "${value}".`);
+};
+
+// ------------------------------------------------------------
+
+export const getNonDeletedGroupIds = (elements: ElementsMap) => {
+  const nonDeletedGroupIds = new Set<string>();
+
+  for (const [, element] of elements) {
+    // defensive check
+    if (element.isDeleted) {
+      continue;
+    }
+
+    // defensive fallback
+    for (const groupId of element.groupIds ?? []) {
+      nonDeletedGroupIds.add(groupId);
+    }
+  }
+
+  return nonDeletedGroupIds;
+};
+
+// ------------------------------------------------------------
+
+export const isTestEnv = () => import.meta.env.MODE === "test";
+
+export const isDevEnv = () => import.meta.env.MODE === "development";
+
+export const isServerEnv = () => import.meta.env.MODE === "server";
+
+export const shouldThrow = () => isDevEnv() || isTestEnv() || isServerEnv();
+
+// ------------------------------------------------------------
+
+let random = new Random(Date.now());
+let testIdBase = 0;
+
+export const randomInteger = () => Math.floor(random.next() * 2 ** 31);
+
+export const reseed = (seed: number) => {
+  random = new Random(seed);
+  testIdBase = 0;
+};
+
+export const randomId = () => (isTestEnv() ? `id${testIdBase++}` : nanoid());
+
+// ------------------------------------------------------------
+
+export const getUpdatedTimestamp = () => (isTestEnv() ? 1 : Date.now());
+
+// ------------------------------------------------------------
+
+export const newElementWith = <TElement extends ExcalidrawElement>(
+  element: TElement,
+  updates: ElementUpdate<TElement>,
+  /** pass `true` to always regenerate */
+  force = false,
+): TElement => {
+  let didChange = false;
+  for (const key in updates) {
+    const value = (updates as any)[key];
+    if (typeof value !== "undefined") {
+      if (
+        (element as any)[key] === value &&
+        // if object, always update because its attrs could have changed
+        (typeof value !== "object" || value === null)
+      ) {
+        continue;
+      }
+      didChange = true;
+    }
+  }
+
+  if (!didChange && !force) {
+    return element;
+  }
+
+  return {
+    ...element,
+    ...updates,
+    updated: getUpdatedTimestamp(),
+    version: element.version + 1,
+    versionNonce: randomInteger(),
+  };
+};

packages/deltas/src/containers/appstate.ts

@@ -0,0 +1,404 @@
+import { Delta } from "../common/delta";
+import {
+  assertNever,
+  getNonDeletedGroupIds,
+  getObservedAppState,
+  isDevEnv,
+  isTestEnv,
+  shouldThrow,
+} from "../common/utils";
+
+import type { DeltaContainer } from "../common/interfaces";
+import type {
+  AppState,
+  ObservedAppState,
+  DTO,
+  SceneElementsMap,
+  ValueOf,
+  ObservedElementsAppState,
+  ObservedStandaloneAppState,
+  SubtypeOf,
+} from "../excalidraw-types";
+
+export class AppStateDelta implements DeltaContainer<AppState> {
+  private constructor(public readonly delta: Delta<ObservedAppState>) {}
+
+  public static calculate<T extends ObservedAppState>(
+    prevAppState: T,
+    nextAppState: T,
+  ): AppStateDelta {
+    const delta = Delta.calculate(
+      prevAppState,
+      nextAppState,
+      undefined,
+      AppStateDelta.postProcess,
+    );
+
+    return new AppStateDelta(delta);
+  }
+
+  public static restore(appStateDeltaDTO: DTO<AppStateDelta>): AppStateDelta {
+    const { delta } = appStateDeltaDTO;
+    return new AppStateDelta(delta);
+  }
+
+  public static empty() {
+    return new AppStateDelta(Delta.create({}, {}));
+  }
+
+  public inverse(): AppStateDelta {
+    const inversedDelta = Delta.create(this.delta.inserted, this.delta.deleted);
+    return new AppStateDelta(inversedDelta);
+  }
+
+  public applyTo(
+    appState: AppState,
+    nextElements: SceneElementsMap,
+  ): [AppState, boolean] {
+    try {
+      const {
+        selectedElementIds: removedSelectedElementIds = {},
+        selectedGroupIds: removedSelectedGroupIds = {},
+      } = this.delta.deleted;
+
+      const {
+        selectedElementIds: addedSelectedElementIds = {},
+        selectedGroupIds: addedSelectedGroupIds = {},
+        selectedLinearElementId,
+        editingLinearElementId,
+        ...directlyApplicablePartial
+      } = this.delta.inserted;
+
+      const mergedSelectedElementIds = Delta.mergeObjects(
+        appState.selectedElementIds,
+        addedSelectedElementIds,
+        removedSelectedElementIds,
+      );
+
+      const mergedSelectedGroupIds = Delta.mergeObjects(
+        appState.selectedGroupIds,
+        addedSelectedGroupIds,
+        removedSelectedGroupIds,
+      );
+
+      //   const selectedLinearElement =
+      //     selectedLinearElementId && nextElements.has(selectedLinearElementId)
+      //       ? new LinearElementEditor(
+      //           nextElements.get(
+      //             selectedLinearElementId,
+      //           ) as NonDeleted<ExcalidrawLinearElement>,
+      //         )
+      //       : null;
+
+      //   const editingLinearElement =
+      //     editingLinearElementId && nextElements.has(editingLinearElementId)
+      //       ? new LinearElementEditor(
+      //           nextElements.get(
+      //             editingLinearElementId,
+      //           ) as NonDeleted<ExcalidrawLinearElement>,
+      //         )
+      //       : null;
+
+      const nextAppState = {
+        ...appState,
+        ...directlyApplicablePartial,
+        selectedElementIds: mergedSelectedElementIds,
+        selectedGroupIds: mergedSelectedGroupIds,
+        // selectedLinearElement:
+        //   typeof selectedLinearElementId !== "undefined"
+        //     ? selectedLinearElement // element was either inserted or deleted
+        //     : appState.selectedLinearElement, // otherwise assign what we had before
+        // editingLinearElement:
+        //   typeof editingLinearElementId !== "undefined"
+        //     ? editingLinearElement // element was either inserted or deleted
+        //     : appState.editingLinearElement, // otherwise assign what we had before
+      };
+
+      const constainsVisibleChanges = this.filterInvisibleChanges(
+        appState,
+        nextAppState,
+        nextElements,
+      );
+
+      return [nextAppState, constainsVisibleChanges];
+    } catch (e) {
+      // shouldn't really happen, but just in case
+      console.error(`Couldn't apply appstate delta`, e);
+
+      if (shouldThrow()) {
+        throw e;
+      }
+
+      return [appState, false];
+    }
+  }
+
+  public isEmpty(): boolean {
+    return Delta.isEmpty(this.delta);
+  }
+
+  /**
+   * It is necessary to post process the partials in case of reference values,
+   * for which we need to calculate the real diff between `deleted` and `inserted`.
+   */
+  private static postProcess<T extends ObservedAppState>(
+    deleted: Partial<T>,
+    inserted: Partial<T>,
+  ): [Partial<T>, Partial<T>] {
+    try {
+      Delta.diffObjects(
+        deleted,
+        inserted,
+        "selectedElementIds",
+        // ts language server has a bit trouble resolving this, so we are giving it a little push
+        (_) => true as ValueOf<T["selectedElementIds"]>,
+      );
+      Delta.diffObjects(
+        deleted,
+        inserted,
+        "selectedGroupIds",
+        (prevValue) => (prevValue ?? false) as ValueOf<T["selectedGroupIds"]>,
+      );
+    } catch (e) {
+      // if postprocessing fails it does not make sense to bubble up, but let's make sure we know about it
+      console.error(`Couldn't postprocess appstate change deltas.`);
+
+      if (isDevEnv() || isTestEnv()) {
+        throw e;
+      }
+    } finally {
+      return [deleted, inserted];
+    }
+  }
+
+  /**
+   * Mutates `nextAppState` be filtering out state related to deleted elements.
+   *
+   * @returns `true` if a visible change is found, `false` otherwise.
+   */
+  private filterInvisibleChanges(
+    prevAppState: AppState,
+    nextAppState: AppState,
+    nextElements: SceneElementsMap,
+  ): boolean {
+    // TODO: #7348 we could still get an empty undo/redo, as we assume that previous appstate does not contain references to deleted elements
+    // which is not always true - i.e. now we do cleanup appstate during history, but we do not do it during remote updates
+    const prevObservedAppState = getObservedAppState(prevAppState);
+    const nextObservedAppState = getObservedAppState(nextAppState);
+
+    const containsStandaloneDifference = Delta.isRightDifferent(
+      AppStateDelta.stripElementsProps(prevObservedAppState),
+      AppStateDelta.stripElementsProps(nextObservedAppState),
+    );
+
+    const containsElementsDifference = Delta.isRightDifferent(
+      AppStateDelta.stripStandaloneProps(prevObservedAppState),
+      AppStateDelta.stripStandaloneProps(nextObservedAppState),
+    );
+
+    if (!containsStandaloneDifference && !containsElementsDifference) {
+      // no change in appstate was detected
+      return false;
+    }
+
+    const visibleDifferenceFlag = {
+      value: containsStandaloneDifference,
+    };
+
+    if (containsElementsDifference) {
+      // filter invisible changes on each iteration
+      const changedElementsProps = Delta.getRightDifferences(
+        AppStateDelta.stripStandaloneProps(prevObservedAppState),
+        AppStateDelta.stripStandaloneProps(nextObservedAppState),
+      ) as Array<keyof ObservedElementsAppState>;
+
+      let nonDeletedGroupIds = new Set<string>();
+
+      if (
+        changedElementsProps.includes("editingGroupId") ||
+        changedElementsProps.includes("selectedGroupIds")
+      ) {
+        // this one iterates through all the non deleted elements, so make sure it's not done twice
+        nonDeletedGroupIds = getNonDeletedGroupIds(nextElements);
+      }
+
+      // check whether delta properties are related to the existing non-deleted elements
+      for (const key of changedElementsProps) {
+        switch (key) {
+          case "selectedElementIds":
+            nextAppState[key] = AppStateDelta.filterSelectedElements(
+              nextAppState[key],
+              nextElements,
+              visibleDifferenceFlag,
+            );
+
+            break;
+          case "selectedGroupIds":
+            nextAppState[key] = AppStateDelta.filterSelectedGroups(
+              nextAppState[key],
+              nonDeletedGroupIds,
+              visibleDifferenceFlag,
+            );
+
+            break;
+          case "croppingElementId": {
+            const croppingElementId = nextAppState[key];
+            const element =
+              croppingElementId && nextElements.get(croppingElementId);
+
+            if (element && !element.isDeleted) {
+              visibleDifferenceFlag.value = true;
+            } else {
+              nextAppState[key] = null;
+            }
+            break;
+          }
+          case "editingGroupId":
+            const editingGroupId = nextAppState[key];
+
+            if (!editingGroupId) {
+              // previously there was an editingGroup (assuming visible), now there is none
+              visibleDifferenceFlag.value = true;
+            } else if (nonDeletedGroupIds.has(editingGroupId)) {
+              // previously there wasn't an editingGroup, now there is one which is visible
+              visibleDifferenceFlag.value = true;
+            } else {
+              // there was assigned an editingGroup now, but it's related to deleted element
+              nextAppState[key] = null;
+            }
+
+            break;
+          case "selectedLinearElementId":
+          case "editingLinearElementId":
+            const appStateKey = AppStateDelta.convertToAppStateKey(key);
+            const linearElement = nextAppState[appStateKey];
+
+            if (!linearElement) {
+              // previously there was a linear element (assuming visible), now there is none
+              visibleDifferenceFlag.value = true;
+            } else {
+              const element = nextElements.get(linearElement.elementId);
+
+              if (element && !element.isDeleted) {
+                // previously there wasn't a linear element, now there is one which is visible
+                visibleDifferenceFlag.value = true;
+              } else {
+                // there was assigned a linear element now, but it's deleted
+                nextAppState[appStateKey] = null;
+              }
+            }
+
+            break;
+          default: {
+            assertNever(key, `Unknown ObservedElementsAppState's key "${key}"`);
+          }
+        }
+      }
+    }
+
+    return visibleDifferenceFlag.value;
+  }
+
+  private static convertToAppStateKey(
+    key: keyof Pick<
+      ObservedElementsAppState,
+      "selectedLinearElementId" | "editingLinearElementId"
+    >,
+  ): keyof Pick<AppState, "selectedLinearElement" | "editingLinearElement"> {
+    switch (key) {
+      case "selectedLinearElementId":
+        return "selectedLinearElement";
+      case "editingLinearElementId":
+        return "editingLinearElement";
+    }
+  }
+
+  private static filterSelectedElements(
+    selectedElementIds: AppState["selectedElementIds"],
+    elements: SceneElementsMap,
+    visibleDifferenceFlag: { value: boolean },
+  ) {
+    const ids = Object.keys(selectedElementIds);
+
+    if (!ids.length) {
+      // previously there were ids (assuming related to visible elements), now there are none
+      visibleDifferenceFlag.value = true;
+      return selectedElementIds;
+    }
+
+    const nextSelectedElementIds = { ...selectedElementIds };
+
+    for (const id of ids) {
+      const element = elements.get(id);
+
+      if (element && !element.isDeleted) {
+        // there is a selected element id related to a visible element
+        visibleDifferenceFlag.value = true;
+      } else {
+        delete nextSelectedElementIds[id];
+      }
+    }
+
+    return nextSelectedElementIds;
+  }
+
+  private static filterSelectedGroups(
+    selectedGroupIds: AppState["selectedGroupIds"],
+    nonDeletedGroupIds: Set<string>,
+    visibleDifferenceFlag: { value: boolean },
+  ) {
+    const ids = Object.keys(selectedGroupIds);
+
+    if (!ids.length) {
+      // previously there were ids (assuming related to visible groups), now there are none
+      visibleDifferenceFlag.value = true;
+      return selectedGroupIds;
+    }
+
+    const nextSelectedGroupIds = { ...selectedGroupIds };
+
+    for (const id of Object.keys(nextSelectedGroupIds)) {
+      if (nonDeletedGroupIds.has(id)) {
+        // there is a selected group id related to a visible group
+        visibleDifferenceFlag.value = true;
+      } else {
+        delete nextSelectedGroupIds[id];
+      }
+    }
+
+    return nextSelectedGroupIds;
+  }
+
+  private static stripElementsProps(
+    delta: Partial<ObservedAppState>,
+  ): Partial<ObservedStandaloneAppState> {
+    // WARN: Do not remove the type-casts as they here to ensure proper type checks
+    const {
+      editingGroupId,
+      selectedGroupIds,
+      selectedElementIds,
+      editingLinearElementId,
+      selectedLinearElementId,
+      croppingElementId,
+      ...standaloneProps
+    } = delta as ObservedAppState;
+
+    return standaloneProps as SubtypeOf<
+      typeof standaloneProps,
+      ObservedStandaloneAppState
+    >;
+  }
+
+  private static stripStandaloneProps(
+    delta: Partial<ObservedAppState>,
+  ): Partial<ObservedElementsAppState> {
+    // WARN: Do not remove the type-casts as they here to ensure proper type checks
+    const { name, viewBackgroundColor, ...elementsProps } =
+      delta as ObservedAppState;
+
+    return elementsProps as SubtypeOf<
+      typeof elementsProps,
+      ObservedElementsAppState
+    >;
+  }
+}

packages/deltas/src/containers/elements.ts

@@ -0,0 +1,825 @@
+import { Delta } from "../common/delta";
+import { newElementWith, shouldThrow } from "../common/utils";
+
+import type { DeltaContainer } from "../common/interfaces";
+import type {
+  ExcalidrawElement,
+  ElementUpdate,
+  Ordered,
+  SceneElementsMap,
+  DTO,
+  OrderedExcalidrawElement,
+  ExcalidrawImageElement,
+} from "../excalidraw-types";
+
+// CFDO: consider adding here (nonnullable) version & versionNonce & updated (so that we have correct versions when recunstructing from remote)
+type ElementPartial<T extends ExcalidrawElement = ExcalidrawElement> =
+  ElementUpdate<Ordered<T>>;
+
+/**
+ * Elements delta is a low level primitive to encapsulate property changes between two sets of elements.
+ * It does so by encapsulating forward and backward `Delta`s, allowing to time-travel in both directions.
+ */
+export class ElementsDelta implements DeltaContainer<SceneElementsMap> {
+  private constructor(
+    public readonly added: Record<string, Delta<ElementPartial>>,
+    public readonly removed: Record<string, Delta<ElementPartial>>,
+    public readonly updated: Record<string, Delta<ElementPartial>>,
+  ) {}
+
+  public static create(
+    added: Record<string, Delta<ElementPartial>>,
+    removed: Record<string, Delta<ElementPartial>>,
+    updated: Record<string, Delta<ElementPartial>>,
+    options: {
+      shouldRedistribute: boolean;
+    } = {
+      shouldRedistribute: false,
+      // CFDO: don't forget to re-enable
+    },
+  ) {
+    const { shouldRedistribute } = options;
+    let delta: ElementsDelta;
+
+    if (shouldRedistribute) {
+      const nextAdded: Record<string, Delta<ElementPartial>> = {};
+      const nextRemoved: Record<string, Delta<ElementPartial>> = {};
+      const nextUpdated: Record<string, Delta<ElementPartial>> = {};
+
+      const deltas = [
+        ...Object.entries(added),
+        ...Object.entries(removed),
+        ...Object.entries(updated),
+      ];
+
+      for (const [id, delta] of deltas) {
+        if (this.satisfiesAddition(delta)) {
+          nextAdded[id] = delta;
+        } else if (this.satisfiesRemoval(delta)) {
+          nextRemoved[id] = delta;
+        } else {
+          nextUpdated[id] = delta;
+        }
+      }
+
+      delta = new ElementsDelta(nextAdded, nextRemoved, nextUpdated);
+    } else {
+      delta = new ElementsDelta(added, removed, updated);
+    }
+
+    if (shouldThrow()) {
+      ElementsDelta.validate(delta, "added", this.satisfiesAddition);
+      ElementsDelta.validate(delta, "removed", this.satisfiesRemoval);
+      ElementsDelta.validate(delta, "updated", this.satisfiesUpdate);
+    }
+
+    return delta;
+  }
+
+  public static restore(elementsDeltaDTO: DTO<ElementsDelta>): ElementsDelta {
+    const { added, removed, updated } = elementsDeltaDTO;
+    return ElementsDelta.create(added, removed, updated);
+  }
+
+  private static satisfiesAddition = ({
+    deleted,
+    inserted,
+  }: Delta<ElementPartial>) =>
+    // dissallowing added as "deleted", which could cause issues when resolving conflicts
+    deleted.isDeleted === true && !inserted.isDeleted;
+
+  private static satisfiesRemoval = ({
+    deleted,
+    inserted,
+  }: Delta<ElementPartial>) =>
+    !deleted.isDeleted && inserted.isDeleted === true;
+
+  private static satisfiesUpdate = ({
+    deleted,
+    inserted,
+  }: Delta<ElementPartial>) => !!deleted.isDeleted === !!inserted.isDeleted;
+
+  private static validate(
+    elementsDelta: ElementsDelta,
+    type: "added" | "removed" | "updated",
+    satifies: (delta: Delta<ElementPartial>) => boolean,
+  ) {
+    for (const [id, delta] of Object.entries(elementsDelta[type])) {
+      if (!satifies(delta)) {
+        console.error(
+          `Broken invariant for "${type}" delta, element "${id}", delta:`,
+          delta,
+        );
+        throw new Error(`ElementsDelta invariant broken for element "${id}".`);
+      }
+    }
+  }
+
+  /**
+   * Calculates the `Delta`s between the previous and next set of elements.
+   *
+   * @param prevElements - Map representing the previous state of elements.
+   * @param nextElements - Map representing the next state of elements.
+   *
+   * @returns `ElementsDelta` instance representing the `Delta` changes between the two sets of elements.
+   */
+  public static calculate<T extends OrderedExcalidrawElement>(
+    prevElements: Map<string, T>,
+    nextElements: Map<string, T>,
+  ): ElementsDelta {
+    if (prevElements === nextElements) {
+      return ElementsDelta.empty();
+    }
+
+    const added: Record<string, Delta<ElementPartial>> = {};
+    const removed: Record<string, Delta<ElementPartial>> = {};
+    const updated: Record<string, Delta<ElementPartial>> = {};
+
+    // this might be needed only in same edge cases, like during collab, when `isDeleted` elements get removed or when we (un)intentionally remove the elements
+    for (const prevElement of prevElements.values()) {
+      const nextElement = nextElements.get(prevElement.id);
+
+      if (!nextElement) {
+        const deleted = { ...prevElement, isDeleted: false } as ElementPartial;
+        const inserted = { isDeleted: true } as ElementPartial;
+
+        const delta = Delta.create(
+          deleted,
+          inserted,
+          ElementsDelta.stripIrrelevantProps,
+        );
+
+        removed[prevElement.id] = delta;
+      }
+    }
+
+    for (const nextElement of nextElements.values()) {
+      const prevElement = prevElements.get(nextElement.id);
+
+      if (!prevElement) {
+        const deleted = { isDeleted: true } as ElementPartial;
+        const inserted = {
+          ...nextElement,
+          isDeleted: false,
+        } as ElementPartial;
+
+        const delta = Delta.create(
+          deleted,
+          inserted,
+          ElementsDelta.stripIrrelevantProps,
+        );
+
+        added[nextElement.id] = delta;
+
+        continue;
+      }
+
+      if (prevElement.versionNonce !== nextElement.versionNonce) {
+        const delta = Delta.calculate<ElementPartial>(
+          prevElement,
+          nextElement,
+          ElementsDelta.stripIrrelevantProps,
+          ElementsDelta.postProcess,
+        );
+
+        if (
+          // making sure we don't get here some non-boolean values (i.e. undefined, null, etc.)
+          typeof prevElement.isDeleted === "boolean" &&
+          typeof nextElement.isDeleted === "boolean" &&
+          prevElement.isDeleted !== nextElement.isDeleted
+        ) {
+          // notice that other props could have been updated as well
+          if (prevElement.isDeleted && !nextElement.isDeleted) {
+            added[nextElement.id] = delta;
+          } else {
+            removed[nextElement.id] = delta;
+          }
+
+          continue;
+        }
+
+        // making sure there are at least some changes
+        if (!Delta.isEmpty(delta)) {
+          updated[nextElement.id] = delta;
+        }
+      }
+    }
+
+    return ElementsDelta.create(added, removed, updated);
+  }
+
+  public static empty() {
+    return ElementsDelta.create({}, {}, {});
+  }
+
+  public inverse(): ElementsDelta {
+    const inverseInternal = (deltas: Record<string, Delta<ElementPartial>>) => {
+      const inversedDeltas: Record<string, Delta<ElementPartial>> = {};
+
+      for (const [id, delta] of Object.entries(deltas)) {
+        inversedDeltas[id] = Delta.create(delta.inserted, delta.deleted);
+      }
+
+      return inversedDeltas;
+    };
+
+    const added = inverseInternal(this.added);
+    const removed = inverseInternal(this.removed);
+    const updated = inverseInternal(this.updated);
+
+    // notice we inverse removed with added not to break the invariants
+    // notice we force generate a new id
+    return ElementsDelta.create(removed, added, updated);
+  }
+
+  public isEmpty(): boolean {
+    return (
+      Object.keys(this.added).length === 0 &&
+      Object.keys(this.removed).length === 0 &&
+      Object.keys(this.updated).length === 0
+    );
+  }
+
+  /**
+   * Update delta/s based on the existing elements.
+   *
+   * @param elements current elements
+   * @param modifierOptions defines which of the delta (`deleted` or `inserted`) will be updated
+   * @returns new instance with modified delta/s
+   */
+  public applyLatestChanges(
+    elements: SceneElementsMap,
+    modifierOptions: "deleted" | "inserted",
+  ): ElementsDelta {
+    const modifier =
+      (element: OrderedExcalidrawElement) => (partial: ElementPartial) => {
+        const latestPartial: { [key: string]: unknown } = {};
+
+        for (const key of Object.keys(partial) as Array<keyof typeof partial>) {
+          // do not update following props:
+          // - `boundElements`, as it is a reference value which is postprocessed to contain only deleted/inserted keys
+          switch (key) {
+            case "boundElements":
+              latestPartial[key] = partial[key];
+              break;
+            default:
+              latestPartial[key] = element[key];
+          }
+        }
+
+        return latestPartial;
+      };
+
+    const applyLatestChangesInternal = (
+      deltas: Record<string, Delta<ElementPartial>>,
+    ) => {
+      const modifiedDeltas: Record<string, Delta<ElementPartial>> = {};
+
+      for (const [id, delta] of Object.entries(deltas)) {
+        const existingElement = elements.get(id);
+
+        if (existingElement) {
+          const modifiedDelta = Delta.create(
+            delta.deleted,
+            delta.inserted,
+            modifier(existingElement),
+            modifierOptions,
+          );
+
+          modifiedDeltas[id] = modifiedDelta;
+        } else {
+          modifiedDeltas[id] = delta;
+        }
+      }
+
+      return modifiedDeltas;
+    };
+
+    const added = applyLatestChangesInternal(this.added);
+    const removed = applyLatestChangesInternal(this.removed);
+    const updated = applyLatestChangesInternal(this.updated);
+
+    return ElementsDelta.create(added, removed, updated, {
+      shouldRedistribute: true, // redistribute the deltas as `isDeleted` could have been updated
+    });
+  }
+
+  // CFDO: does it make sense having a separate snapshot?
+  public applyTo(
+    elements: SceneElementsMap,
+    elementsSnapshot: Map<string, OrderedExcalidrawElement>,
+  ): [SceneElementsMap, boolean] {
+    const nextElements = new Map(elements) as SceneElementsMap;
+    let changedElements: Map<string, OrderedExcalidrawElement>;
+
+    const flags = {
+      containsVisibleDifference: false,
+      containsZindexDifference: false,
+    };
+
+    // mimic a transaction by applying deltas into `nextElements` (always new instance, no mutation)
+    try {
+      const applyDeltas = ElementsDelta.createApplier(
+        nextElements,
+        elementsSnapshot,
+        flags,
+      );
+
+      const addedElements = applyDeltas("added", this.added);
+      const removedElements = applyDeltas("removed", this.removed);
+      const updatedElements = applyDeltas("updated", this.updated);
+
+      // CFDO I: don't forget to fix this part
+      // const affectedElements = this.resolveConflicts(elements, nextElements);
+
+      // TODO: #7348 validate elements semantically and syntactically the changed elements, in case they would result data integrity issues
+      changedElements = new Map([
+        ...addedElements,
+        ...removedElements,
+        ...updatedElements,
+        // ...affectedElements,
+      ]);
+    } catch (e) {
+      console.error(`Couldn't apply elements delta`, e);
+
+      if (shouldThrow()) {
+        throw e;
+      }
+
+      // should not really happen, but just in case we cannot apply deltas, let's return the previous elements with visible change set to `true`
+      // even though there is obviously no visible change, returning `false` could be dangerous, as i.e.:
+      // in the worst case, it could lead into iterating through the whole stack with no possibility to redo
+      // instead, the worst case when returning `true` is an empty undo / redo
+      return [elements, true];
+    }
+
+    try {
+      // CFDO I: don't forget to fix this part
+      // // TODO: #7348 refactor away mutations below, so that we couldn't end up in an incosistent state
+      // ElementsDelta.redrawTextBoundingBoxes(nextElements, changedElements);
+      // // the following reorder performs also mutations, but only on new instances of changed elements
+      // // (unless something goes really bad and it fallbacks to fixing all invalid indices)
+      // nextElements = ElementsDelta.reorderElements(
+      //   nextElements,
+      //   changedElements,
+      //   flags,
+      // );
+      // // Need ordered nextElements to avoid z-index binding issues
+      // ElementsDelta.redrawBoundArrows(nextElements, changedElements);
+    } catch (e) {
+      console.error(
+        `Couldn't mutate elements after applying elements change`,
+        e,
+      );
+
+      if (shouldThrow()) {
+        throw e;
+      }
+    } finally {
+      return [nextElements, flags.containsVisibleDifference];
+    }
+  }
+
+  private static createApplier =
+    (
+      nextElements: SceneElementsMap,
+      snapshot: Map<string, OrderedExcalidrawElement>,
+      flags: {
+        containsVisibleDifference: boolean;
+        containsZindexDifference: boolean;
+      },
+    ) =>
+    (
+      type: "added" | "removed" | "updated",
+      deltas: Record<string, Delta<ElementPartial>>,
+    ) => {
+      const getElement = ElementsDelta.createGetter(
+        type,
+        nextElements,
+        snapshot,
+        flags,
+      );
+
+      return Object.entries(deltas).reduce((acc, [id, delta]) => {
+        const element = getElement(id, delta.inserted);
+
+        if (element) {
+          const newElement = ElementsDelta.applyDelta(element, delta, flags);
+          nextElements.set(newElement.id, newElement);
+          acc.set(newElement.id, newElement);
+        }
+
+        return acc;
+      }, new Map<string, OrderedExcalidrawElement>());
+    };
+
+  private static createGetter =
+    (
+      type: "added" | "removed" | "updated",
+      elements: SceneElementsMap,
+      snapshot: Map<string, OrderedExcalidrawElement>,
+      flags: {
+        containsVisibleDifference: boolean;
+        containsZindexDifference: boolean;
+      },
+    ) =>
+    (id: string, partial: ElementPartial) => {
+      let element = elements.get(id);
+
+      if (!element) {
+        // always fallback to the local snapshot, in cases when we cannot find the element in the elements array
+        element = snapshot.get(id);
+
+        if (element) {
+          // as the element was brought from the snapshot, it automatically results in a possible zindex difference
+          flags.containsZindexDifference = true;
+
+          // as the element was force deleted, we need to check if adding it back results in a visible change
+          if (
+            partial.isDeleted === false ||
+            (partial.isDeleted !== true && element.isDeleted === false)
+          ) {
+            flags.containsVisibleDifference = true;
+          }
+        } else if (type === "added") {
+          // for additions the element does not have to exist (i.e. remote update)
+          // CFDO II: the version itself might be different!
+          element = newElementWith(
+            { id, version: 1 } as OrderedExcalidrawElement,
+            {
+              ...partial,
+            },
+          );
+        }
+      }
+
+      return element;
+    };
+
+  private static applyDelta(
+    element: OrderedExcalidrawElement,
+    delta: Delta<ElementPartial>,
+    flags: {
+      containsVisibleDifference: boolean;
+      containsZindexDifference: boolean;
+    } = {
+      // by default we don't care about about the flags
+      containsVisibleDifference: true,
+      containsZindexDifference: true,
+    },
+  ) {
+    const { boundElements, ...directlyApplicablePartial } = delta.inserted;
+
+    if (
+      delta.deleted.boundElements?.length ||
+      delta.inserted.boundElements?.length
+    ) {
+      const mergedBoundElements = Delta.mergeArrays(
+        element.boundElements,
+        delta.inserted.boundElements,
+        delta.deleted.boundElements,
+        (x) => x.id,
+      );
+
+      Object.assign(directlyApplicablePartial, {
+        boundElements: mergedBoundElements,
+      });
+    }
+
+    // CFDO: this looks wrong
+    if (element.type === "image") {
+      const _delta = delta as Delta<ElementPartial<ExcalidrawImageElement>>;
+      // we want to override `crop` only if modified so that we don't reset
+      // when undoing/redoing unrelated change
+      if (_delta.deleted.crop || _delta.inserted.crop) {
+        Object.assign(directlyApplicablePartial, {
+          // apply change verbatim
+          crop: _delta.inserted.crop ?? null,
+        });
+      }
+    }
+
+    if (!flags.containsVisibleDifference) {
+      // strip away fractional index, as even if it would be different, it doesn't have to result in visible change
+      const { index, ...rest } = directlyApplicablePartial;
+      const containsVisibleDifference = ElementsDelta.checkForVisibleDifference(
+        element,
+        rest,
+      );
+
+      flags.containsVisibleDifference = containsVisibleDifference;
+    }
+
+    if (!flags.containsZindexDifference) {
+      flags.containsZindexDifference =
+        delta.deleted.index !== delta.inserted.index;
+    }
+
+    return newElementWith(element, directlyApplicablePartial);
+  }
+
+  /**
+   * Check for visible changes regardless of whether they were removed, added or updated.
+   */
+  private static checkForVisibleDifference(
+    element: OrderedExcalidrawElement,
+    partial: ElementPartial,
+  ) {
+    if (element.isDeleted && partial.isDeleted !== false) {
+      // when it's deleted and partial is not false, it cannot end up with a visible change
+      return false;
+    }
+
+    if (element.isDeleted && partial.isDeleted === false) {
+      // when we add an element, it results in a visible change
+      return true;
+    }
+
+    if (element.isDeleted === false && partial.isDeleted) {
+      // when we remove an element, it results in a visible change
+      return true;
+    }
+
+    // check for any difference on a visible element
+    return Delta.isRightDifferent(element, partial);
+  }
+
+  // /**
+  //  * Resolves conflicts for all previously added, removed and updated elements.
+  //  * Updates the previous deltas with all the changes after conflict resolution.
+  //  *
+  //  * // CFDO: revisit since arrow seem often redrawn incorrectly
+  //  *
+  //  * @returns all elements affected by the conflict resolution
+  //  */
+  // private resolveConflicts(
+  //   prevElements: SceneElementsMap,
+  //   nextElements: SceneElementsMap,
+  // ) {
+  //   const nextAffectedElements = new Map<string, OrderedExcalidrawElement>();
+  //   const updater = (
+  //     element: ExcalidrawElement,
+  //     updates: ElementUpdate<ExcalidrawElement>,
+  //   ) => {
+  //     const nextElement = nextElements.get(element.id); // only ever modify next element!
+  //     if (!nextElement) {
+  //       return;
+  //     }
+
+  //     let affectedElement: OrderedExcalidrawElement;
+
+  //     if (prevElements.get(element.id) === nextElement) {
+  //       // create the new element instance in case we didn't modify the element yet
+  //       // so that we won't end up in an incosistent state in case we would fail in the middle of mutations
+  //       affectedElement = newElementWith(
+  //         nextElement,
+  //         updates as ElementUpdate<OrderedExcalidrawElement>,
+  //       );
+  //     } else {
+  //       affectedElement = mutateElement(
+  //         nextElement,
+  //         updates as ElementUpdate<OrderedExcalidrawElement>,
+  //       );
+  //     }
+
+  //     nextAffectedElements.set(affectedElement.id, affectedElement);
+  //     nextElements.set(affectedElement.id, affectedElement);
+  //   };
+
+  //   // removed delta is affecting the bindings always, as all the affected elements of the removed elements need to be unbound
+  //   for (const id of Object.keys(this.removed)) {
+  //     ElementsDelta.unbindAffected(prevElements, nextElements, id, updater);
+  //   }
+
+  //   // added delta is affecting the bindings always, all the affected elements of the added elements need to be rebound
+  //   for (const id of Object.keys(this.added)) {
+  //     ElementsDelta.rebindAffected(prevElements, nextElements, id, updater);
+  //   }
+
+  //   // updated delta is affecting the binding only in case it contains changed binding or bindable property
+  //   for (const [id] of Array.from(Object.entries(this.updated)).filter(
+  //     ([_, delta]) =>
+  //       Object.keys({ ...delta.deleted, ...delta.inserted }).find((prop) =>
+  //         bindingProperties.has(prop as BindingProp | BindableProp),
+  //       ),
+  //   )) {
+  //     const updatedElement = nextElements.get(id);
+  //     if (!updatedElement || updatedElement.isDeleted) {
+  //       // skip fixing bindings for updates on deleted elements
+  //       continue;
+  //     }
+
+  //     ElementsDelta.rebindAffected(prevElements, nextElements, id, updater);
+  //   }
+
+  //   // filter only previous elements, which were now affected
+  //   const prevAffectedElements = new Map(
+  //     Array.from(prevElements).filter(([id]) => nextAffectedElements.has(id)),
+  //   );
+
+  //   // calculate complete deltas for affected elements, and assign them back to all the deltas
+  //   // technically we could do better here if perf. would become an issue
+  //   const { added, removed, updated } = ElementsDelta.calculate(
+  //     prevAffectedElements,
+  //     nextAffectedElements,
+  //   );
+
+  //   for (const [id, delta] of Object.entries(added)) {
+  //     this.added[id] = delta;
+  //   }
+
+  //   for (const [id, delta] of Object.entries(removed)) {
+  //     this.removed[id] = delta;
+  //   }
+
+  //   for (const [id, delta] of Object.entries(updated)) {
+  //     this.updated[id] = delta;
+  //   }
+
+  //   return nextAffectedElements;
+  // }
+
+  // /**
+  //  * Non deleted affected elements of removed elements (before and after applying delta),
+  //  * should be unbound ~ bindings should not point from non deleted into the deleted element/s.
+  //  */
+  // private static unbindAffected(
+  //   prevElements: SceneElementsMap,
+  //   nextElements: SceneElementsMap,
+  //   id: string,
+  //   updater: (
+  //     element: ExcalidrawElement,
+  //     updates: ElementUpdate<ExcalidrawElement>,
+  //   ) => void,
+  // ) {
+  //   // the instance could have been updated, so make sure we are passing the latest element to each function below
+  //   const prevElement = () => prevElements.get(id); // element before removal
+  //   const nextElement = () => nextElements.get(id); // element after removal
+
+  //   BoundElement.unbindAffected(nextElements, prevElement(), updater);
+  //   BoundElement.unbindAffected(nextElements, nextElement(), updater);
+
+  //   BindableElement.unbindAffected(nextElements, prevElement(), updater);
+  //   BindableElement.unbindAffected(nextElements, nextElement(), updater);
+  // }
+
+  // /**
+  //  * Non deleted affected elements of added or updated element/s (before and after applying delta),
+  //  * should be rebound (if possible) with the current element ~ bindings should be bidirectional.
+  //  */
+  // private static rebindAffected(
+  //   prevElements: SceneElementsMap,
+  //   nextElements: SceneElementsMap,
+  //   id: string,
+  //   updater: (
+  //     element: ExcalidrawElement,
+  //     updates: ElementUpdate<ExcalidrawElement>,
+  //   ) => void,
+  // ) {
+  //   // the instance could have been updated, so make sure we are passing the latest element to each function below
+  //   const prevElement = () => prevElements.get(id); // element before addition / update
+  //   const nextElement = () => nextElements.get(id); // element after addition / update
+
+  //   BoundElement.unbindAffected(nextElements, prevElement(), updater);
+  //   BoundElement.rebindAffected(nextElements, nextElement(), updater);
+
+  //   BindableElement.unbindAffected(
+  //     nextElements,
+  //     prevElement(),
+  //     (element, updates) => {
+  //       // we cannot rebind arrows with bindable element so we don't unbind them at all during rebind (we still need to unbind them on removal)
+  //       // TODO: #7348 add startBinding / endBinding to the `BoundElement` context so that we could rebind arrows and remove this condition
+  //       if (isTextElement(element)) {
+  //         updater(element, updates);
+  //       }
+  //     },
+  //   );
+  //   BindableElement.rebindAffected(nextElements, nextElement(), updater);
+  // }
+
+  // private static redrawTextBoundingBoxes(
+  //   elements: SceneElementsMap,
+  //   changed: Map<string, OrderedExcalidrawElement>,
+  // ) {
+  //   const boxesToRedraw = new Map<
+  //     string,
+  //     { container: OrderedExcalidrawElement; boundText: ExcalidrawTextElement }
+  //   >();
+
+  //   for (const element of changed.values()) {
+  //     if (isBoundToContainer(element)) {
+  //       const { containerId } = element as ExcalidrawTextElement;
+  //       const container = containerId ? elements.get(containerId) : undefined;
+
+  //       if (container) {
+  //         boxesToRedraw.set(container.id, {
+  //           container,
+  //           boundText: element as ExcalidrawTextElement,
+  //         });
+  //       }
+  //     }
+
+  //     if (hasBoundTextElement(element)) {
+  //       const boundTextElementId = getBoundTextElementId(element);
+  //       const boundText = boundTextElementId
+  //         ? elements.get(boundTextElementId)
+  //         : undefined;
+
+  //       if (boundText) {
+  //         boxesToRedraw.set(element.id, {
+  //           container: element,
+  //           boundText: boundText as ExcalidrawTextElement,
+  //         });
+  //       }
+  //     }
+  //   }
+
+  //   for (const { container, boundText } of boxesToRedraw.values()) {
+  //     if (container.isDeleted || boundText.isDeleted) {
+  //       // skip redraw if one of them is deleted, as it would not result in a meaningful redraw
+  //       continue;
+  //     }
+
+  //     redrawTextBoundingBox(boundText, container, elements, false);
+  //   }
+  // }
+
+  // private static redrawBoundArrows(
+  //   elements: SceneElementsMap,
+  //   changed: Map<string, OrderedExcalidrawElement>,
+  // ) {
+  //   for (const element of changed.values()) {
+  //     if (!element.isDeleted && isBindableElement(element)) {
+  //       updateBoundElements(element, elements, {
+  //         changedElements: changed,
+  //       });
+  //     }
+  //   }
+  // }
+
+  // private static reorderElements(
+  //   elements: SceneElementsMap,
+  //   changed: Map<string, OrderedExcalidrawElement>,
+  //   flags: {
+  //     containsVisibleDifference: boolean;
+  //     containsZindexDifference: boolean;
+  //   },
+  // ) {
+  //   if (!flags.containsZindexDifference) {
+  //     return elements;
+  //   }
+
+  //   const unordered = Array.from(elements.values());
+  //   const ordered = orderByFractionalIndex([...unordered]);
+  //   const moved = Delta.getRightDifferences(unordered, ordered, true).reduce(
+  //     (acc, arrayIndex) => {
+  //       const candidate = unordered[Number(arrayIndex)];
+  //       if (candidate && changed.has(candidate.id)) {
+  //         acc.set(candidate.id, candidate);
+  //       }
+
+  //       return acc;
+  //     },
+  //     new Map(),
+  //   );
+
+  //   if (!flags.containsVisibleDifference && moved.size) {
+  //     // we found a difference in order!
+  //     flags.containsVisibleDifference = true;
+  //   }
+
+  //   // synchronize all elements that were actually moved
+  //   // could fallback to synchronizing all invalid indices
+  //   return elementsToMap(syncMovedIndices(ordered, moved)) as typeof elements;
+  // }
+
+  /**
+   * It is necessary to post process the partials in case of reference values,
+   * for which we need to calculate the real diff between `deleted` and `inserted`.
+   */
+  private static postProcess(
+    deleted: ElementPartial,
+    inserted: ElementPartial,
+  ): [ElementPartial, ElementPartial] {
+    try {
+      Delta.diffArrays(deleted, inserted, "boundElements", (x) => x.id);
+    } catch (e) {
+      // if postprocessing fails, it does not make sense to bubble up, but let's make sure we know about it
+      console.error(`Couldn't postprocess elements delta.`);
+
+      if (shouldThrow()) {
+        throw e;
+      }
+    } finally {
+      return [deleted, inserted];
+    }
+  }
+
+  private static stripIrrelevantProps(
+    partial: Partial<OrderedExcalidrawElement>,
+  ): ElementPartial {
+    const { id, updated, version, versionNonce, ...strippedPartial } = partial;
+
+    return strippedPartial;
+  }
+}

packages/deltas/src/excalidraw-types.d.ts

@@ -0,0 +1,26 @@
+export type {
+  AppState,
+  ObservedElementsAppState,
+  ObservedStandaloneAppState,
+  ObservedAppState,
+} from "@excalidraw/excalidraw/dist/excalidraw/types";
+export type {
+  DTO,
+  SubtypeOf,
+  ValueOf,
+} from "@excalidraw/excalidraw/dist/excalidraw/utility-types";
+
+export type {
+  ExcalidrawElement,
+  ExcalidrawImageElement,
+  ExcalidrawTextElement,
+  Ordered,
+  OrderedExcalidrawElement,
+  SceneElementsMap,
+  ElementsMap,
+} from "@excalidraw/excalidraw/dist/excalidraw/element/types";
+export type { ElementUpdate } from "@excalidraw/excalidraw/dist/excalidraw/element/mutateElement";
+export type {
+  BindableProp,
+  BindingProp,
+} from "@excalidraw/excalidraw/dist/excalidraw/element/binding";

packages/deltas/src/index.ts

@@ -0,0 +1,5 @@
+export type { DeltaContainer } from "./common/interfaces";
+
+export { Delta } from "./common/delta";
+export { ElementsDelta } from "./containers/elements";
+export { AppStateDelta } from "./containers/appstate";

packages/deltas/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "strict": true,
+    "outDir": "dist/types",
+    "skipLibCheck": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "allowSyntheticDefaultImports": true,
+    "module": "ESNext",
+    "moduleResolution": "Node",
+  },
+  "exclude": [
+    "**/*.test.*",
+    "**/tests/*",
+    "types",
+    "dist",
+  ],
+}

packages/element/src/linearElementEditor.ts

@@ -807,7 +807,7 @@ export class LinearElementEditor {
         });
         ret.didAddPoint = true;
       }
-      store.shouldCaptureIncrement();
+      store.scheduleCapture();
       ret.linearElementEditor = {
         ...linearElementEditor,
         pointerDownState: {

packages/excalidraw/.gitignore

@@ -1,2 +1,3 @@
 node_modules
 types
+.wrangler

packages/excalidraw/actions/actionHistory.tsx

@@ -10,7 +10,6 @@ import { t } from "../i18n";
 import { CaptureUpdateAction } from "../store";
 
 import type { History } from "../history";
-import type { Store } from "../store";
 import type { AppClassProperties, AppState } from "../types";
 import type { Action, ActionResult } from "./types";
 
@@ -47,9 +46,9 @@ const executeHistoryAction = (
   return { captureUpdate: CaptureUpdateAction.EVENTUALLY };
 };
 
-type ActionCreator = (history: History, store: Store) => Action;
+type ActionCreator = (history: History) => Action;
 
-export const createUndoAction: ActionCreator = (history, store) => ({
+export const createUndoAction: ActionCreator = (history) => ({
   name: "undo",
   label: "buttons.undo",
   icon: UndoIcon,
@@ -57,11 +56,7 @@ export const createUndoAction: ActionCreator = (history, store) => ({
   viewMode: false,
   perform: (elements, appState, value, app) =>
     executeHistoryAction(app, appState, () =>
-      history.undo(
-        arrayToMap(elements) as SceneElementsMap, // TODO: #7348 refactor action manager to already include `SceneElementsMap`
-        appState,
-        store.snapshot,
-      ),
+      history.undo(arrayToMap(elements) as SceneElementsMap, appState),
     ),
   keyTest: (event) =>
     event[KEYS.CTRL_OR_CMD] && matchKey(event, KEYS.Z) && !event.shiftKey,
@@ -88,19 +83,15 @@ export const createUndoAction: ActionCreator = (history, store) => ({
   },
 });
 
-export const createRedoAction: ActionCreator = (history, store) => ({
+export const createRedoAction: ActionCreator = (history) => ({
   name: "redo",
   label: "buttons.redo",
   icon: RedoIcon,
   trackEvent: { category: "history" },
   viewMode: false,
-  perform: (elements, appState, _, app) =>
+  perform: (elements, appState, __, app) =>
     executeHistoryAction(app, appState, () =>
-      history.redo(
-        arrayToMap(elements) as SceneElementsMap, // TODO: #7348 refactor action manager to already include `SceneElementsMap`
-        appState,
-        store.snapshot,
-      ),
+      history.redo(arrayToMap(elements) as SceneElementsMap, appState),
     ),
   keyTest: (event) =>
     (event[KEYS.CTRL_OR_CMD] && event.shiftKey && matchKey(event, KEYS.Z)) ||

packages/excalidraw/components/App.tsx

@@ -756,7 +756,7 @@ class App extends React.Component<AppProps, AppState> {
     this.visibleElements = [];
 
     this.store = new Store();
-    this.history = new History();
+    this.history = new History(this.store);
 
     if (excalidrawAPI) {
       const api: ExcalidrawImperativeAPI = {
@@ -766,6 +766,7 @@ class App extends React.Component<AppProps, AppState> {
         addFiles: this.addFiles,
         resetScene: this.resetScene,
         getSceneElementsIncludingDeleted: this.getSceneElementsIncludingDeleted,
+        store: this.store,
         history: {
           clear: this.resetHistory,
         },
@@ -786,6 +787,7 @@ class App extends React.Component<AppProps, AppState> {
         updateFrameRendering: this.updateFrameRendering,
         toggleSidebar: this.toggleSidebar,
         onChange: (cb) => this.onChangeEmitter.on(cb),
+        onIncrement: (cb) => this.store.onStoreIncrementEmitter.on(cb),
         onPointerDown: (cb) => this.onPointerDownEmitter.on(cb),
         onPointerUp: (cb) => this.onPointerUpEmitter.on(cb),
         onScrollChange: (cb) => this.onScrollChangeEmitter.on(cb),
@@ -804,15 +806,11 @@ class App extends React.Component<AppProps, AppState> {
     };
 
     this.fonts = new Fonts(this.scene);
-    this.history = new History();
+    this.history = new History(this.store);
 
     this.actionManager.registerAll(actions);
-    this.actionManager.registerAction(
-      createUndoAction(this.history, this.store),
-    );
-    this.actionManager.registerAction(
-      createRedoAction(this.history, this.store),
-    );
+    this.actionManager.registerAction(createUndoAction(this.history));
+    this.actionManager.registerAction(createRedoAction(this.history));
   }
 
   private onWindowMessage(event: MessageEvent) {
@@ -1878,6 +1876,10 @@ class App extends React.Component<AppProps, AppState> {
     return this.scene.getElementsIncludingDeleted();
   };
 
+  public getSceneElementsMapIncludingDeleted = () => {
+    return this.scene.getElementsMapIncludingDeleted();
+  };
+
   public getSceneElements = () => {
     return this.scene.getNonDeletedElements();
   };
@@ -2194,11 +2196,7 @@ class App extends React.Component<AppProps, AppState> {
       return;
     }
 
-    if (actionResult.captureUpdate === CaptureUpdateAction.NEVER) {
-      this.store.shouldUpdateSnapshot();
-    } else if (actionResult.captureUpdate === CaptureUpdateAction.IMMEDIATELY) {
-      this.store.shouldCaptureIncrement();
-    }
+    this.store.scheduleAction(actionResult.captureUpdate);
 
     let didUpdate = false;
 
@@ -2271,10 +2269,7 @@ class App extends React.Component<AppProps, AppState> {
       didUpdate = true;
     }
 
-    if (
-      !didUpdate &&
-      actionResult.captureUpdate !== CaptureUpdateAction.EVENTUALLY
-    ) {
+    if (!didUpdate) {
       this.scene.triggerUpdate();
     }
   });
@@ -2527,7 +2522,8 @@ class App extends React.Component<AppProps, AppState> {
     }
 
     this.store.onStoreIncrementEmitter.on((increment) => {
-      this.history.record(increment.elementsChange, increment.appStateChange);
+      this.history.record(increment);
+      this.props.onIncrement?.(increment);
     });
 
     this.scene.onUpdate(this.triggerRender);
@@ -3337,7 +3333,7 @@ class App extends React.Component<AppProps, AppState> {
       this.addMissingFiles(opts.files);
     }
 
-    this.store.shouldCaptureIncrement();
+    this.store.scheduleCapture();
 
     const nextElementsToSelect =
       excludeElementsInFramesFromSelection(duplicatedElements);
@@ -3598,7 +3594,7 @@ class App extends React.Component<AppProps, AppState> {
       PLAIN_PASTE_TOAST_SHOWN = true;
     }
 
-    this.store.shouldCaptureIncrement();
+    this.store.scheduleCapture();
   }
 
   setAppState: React.Component<any, AppState>["setState"] = (
@@ -3954,52 +3950,48 @@ class App extends React.Component<AppProps, AppState> {
        */
       captureUpdate?: SceneData["captureUpdate"];
     }) => {
-      const nextElements = syncInvalidIndices(sceneData.elements ?? []);
+      // flush all pending updates (if any), most of the time it should be a no-op
+      flushSync(() => {});
 
-      if (
-        sceneData.captureUpdate &&
-        sceneData.captureUpdate !== CaptureUpdateAction.EVENTUALLY
-      ) {
-        const prevCommittedAppState = this.store.snapshot.appState;
-        const prevCommittedElements = this.store.snapshot.elements;
+      // flush all incoming updates immediately, so that they couldn't be batched with other updates, having different `storeAction`
+      flushSync(() => {
+        const { elements, appState, collaborators, captureUpdate } = sceneData;
 
-        const nextCommittedAppState = sceneData.appState
-          ? Object.assign({}, prevCommittedAppState, sceneData.appState) // new instance, with partial appstate applied to previously captured one, including hidden prop inside `prevCommittedAppState`
-          : prevCommittedAppState;
+        const nextElements = elements
+          ? syncInvalidIndices(elements)
+          : undefined;
 
-        const nextCommittedElements = sceneData.elements
-          ? this.store.filterUncomittedElements(
-              this.scene.getElementsMapIncludingDeleted(), // Only used to detect uncomitted local elements
-              arrayToMap(nextElements), // We expect all (already reconciled) elements
-            )
-          : prevCommittedElements;
+        if (captureUpdate) {
+          const prevCommittedAppState = this.store.snapshot.appState;
+          const prevCommittedElements = this.store.snapshot.elements;
 
-        // WARN: store action always performs deep clone of changed elements, for ephemeral remote updates (i.e. remote dragging, resizing, drawing) we might consider doing something smarter
-        // do NOT schedule store actions (execute after re-render), as it might cause unexpected concurrency issues if not handled well
-        if (sceneData.captureUpdate === CaptureUpdateAction.IMMEDIATELY) {
-          this.store.captureIncrement(
-            nextCommittedElements,
-            nextCommittedAppState,
-          );
-        } else if (sceneData.captureUpdate === CaptureUpdateAction.NEVER) {
-          this.store.updateSnapshot(
-            nextCommittedElements,
-            nextCommittedAppState,
-          );
+          const nextCommittedAppState = appState
+            ? Object.assign({}, prevCommittedAppState, appState) // new instance, with partial appstate applied to previously captured one, including hidden prop inside `prevCommittedAppState`
+            : prevCommittedAppState;
+
+          const nextCommittedElements = elements
+            ? this.store.filterUncomittedElements(
+                this.scene.getElementsMapIncludingDeleted(), // only used to detect uncomitted local elements
+                arrayToMap(nextElements ?? []), // we expect all (already reconciled) elements
+              )
+            : prevCommittedElements;
+
+          this.store.scheduleAction(captureUpdate);
+          this.store.commit(nextCommittedElements, nextCommittedAppState);
         }
-      }
 
-      if (sceneData.appState) {
-        this.setState(sceneData.appState);
-      }
+        if (appState) {
+          this.setState(appState);
+        }
 
-      if (sceneData.elements) {
-        this.scene.replaceAllElements(nextElements);
-      }
+        if (nextElements) {
+          this.scene.replaceAllElements(nextElements);
+        }
 
-      if (sceneData.collaborators) {
-        this.setState({ collaborators: sceneData.collaborators });
-      }
+        if (collaborators) {
+          this.setState({ collaborators });
+        }
+      });
     },
   );
 
@@ -4464,7 +4456,7 @@ class App extends React.Component<AppProps, AppState> {
                 this.state.editingLinearElement.elementId !==
                   selectedElements[0].id
               ) {
-                this.store.shouldCaptureIncrement();
+                this.store.scheduleCapture();
                 if (!isElbowArrow(selectedElement)) {
                   this.setState({
                     editingLinearElement: new LinearElementEditor(
@@ -4790,7 +4782,7 @@ class App extends React.Component<AppProps, AppState> {
       } as const;
 
       if (nextActiveTool.type === "freedraw") {
-        this.store.shouldCaptureIncrement();
+        this.store.scheduleCapture();
       }
 
       if (nextActiveTool.type === "lasso") {
@@ -5007,7 +4999,7 @@ class App extends React.Component<AppProps, AppState> {
           ]);
         }
         if (!isDeleted || isExistingElement) {
-          this.store.shouldCaptureIncrement();
+          this.store.scheduleCapture();
         }
 
         flushSync(() => {
@@ -5420,7 +5412,7 @@ class App extends React.Component<AppProps, AppState> {
   };
 
   private startImageCropping = (image: ExcalidrawImageElement) => {
-    this.store.shouldCaptureIncrement();
+    this.store.scheduleCapture();
     this.setState({
       croppingElementId: image.id,
     });
@@ -5428,7 +5420,7 @@ class App extends React.Component<AppProps, AppState> {
 
   private finishImageCropping = () => {
     if (this.state.croppingElementId) {
-      this.store.shouldCaptureIncrement();
+      this.store.scheduleCapture();
       this.setState({
         croppingElementId: null,
       });
@@ -5463,7 +5455,7 @@ class App extends React.Component<AppProps, AppState> {
             selectedElements[0].id) &&
         !isElbowArrow(selectedElements[0])
       ) {
-        this.store.shouldCaptureIncrement();
+        this.store.scheduleCapture();
         this.setState({
           editingLinearElement: new LinearElementEditor(
             selectedElements[0],
@@ -5491,7 +5483,7 @@ class App extends React.Component<AppProps, AppState> {
           : -1;
 
         if (midPoint && midPoint > -1) {
-          this.store.shouldCaptureIncrement();
+          this.store.scheduleCapture();
           LinearElementEditor.deleteFixedSegment(
             selectedElements[0],
             this.scene,
@@ -5553,7 +5545,7 @@ class App extends React.Component<AppProps, AppState> {
         getSelectedGroupIdForElement(hitElement, this.state.selectedGroupIds);
 
       if (selectedGroupId) {
-        this.store.shouldCaptureIncrement();
+        this.store.scheduleCapture();
         this.setState((prevState) => ({
           ...prevState,
           ...selectGroupsForSelectedElements(
@@ -9072,7 +9064,7 @@ class App extends React.Component<AppProps, AppState> {
 
       if (isLinearElement(newElement)) {
         if (newElement!.points.length > 1) {
-          this.store.shouldCaptureIncrement();
+          this.store.scheduleCapture();
         }
         const pointerCoords = viewportCoordsToSceneCoords(
           childEvent,
@@ -9345,7 +9337,7 @@ class App extends React.Component<AppProps, AppState> {
       }
 
       if (resizingElement) {
-        this.store.shouldCaptureIncrement();
+        this.store.scheduleCapture();
       }
 
       if (resizingElement && isInvisiblySmallElement(resizingElement)) {
@@ -9685,7 +9677,7 @@ class App extends React.Component<AppProps, AppState> {
           this.state.selectedElementIds,
         )
       ) {
-        this.store.shouldCaptureIncrement();
+        this.store.scheduleCapture();
       }
 
       if (
@@ -9778,7 +9770,7 @@ class App extends React.Component<AppProps, AppState> {
     this.elementsPendingErasure = new Set();
 
     if (didChange) {
-      this.store.shouldCaptureIncrement();
+      this.store.scheduleCapture();
       this.scene.replaceAllElements(elements);
     }
   };
@@ -10457,9 +10449,9 @@ class App extends React.Component<AppProps, AppState> {
       if (ret.type === MIME_TYPES.excalidraw) {
         // restore the fractional indices by mutating elements
         syncInvalidIndices(elements.concat(ret.data.elements));
-
         // update the store snapshot for old elements, otherwise we would end up with duplicated fractional indices on undo
-        this.store.updateSnapshot(arrayToMap(elements), this.state);
+        this.store.scheduleAction(CaptureUpdateAction.NEVER);
+        this.store.commit(arrayToMap(elements), this.state);
 
         this.setState({ isLoading: true });
         this.syncActionResult({

packages/excalidraw/delta.ts

@@ -54,9 +54,9 @@ import type {
   SceneElementsMap,
 } from "@excalidraw/element/types";
 
-import type { SubtypeOf, ValueOf } from "@excalidraw/common/utility-types";
+import type { DTO, SubtypeOf, ValueOf } from "@excalidraw/common/utility-types";
 
-import { getObservedAppState } from "./store";
+import { getObservedAppState, StoreSnapshot } from "./store";
 
 import type {
   AppState,
@@ -74,7 +74,7 @@ import type {
  *
  * Keeping it as pure object (without transient state, side-effects, etc.), so we won't have to instantiate it on load.
  */
-class Delta<T> {
+export class Delta<T> {
   private constructor(
     public readonly deleted: Partial<T>,
     public readonly inserted: Partial<T>,
@@ -386,6 +386,8 @@ class Delta<T> {
       );
     }
 
+    // CFDO: order the keys based on the most common ones to change
+    // (i.e. x/y, width/height, isDeleted, etc.) for quick exit
     for (const key of keys) {
       const object1Value = object1[key as keyof T];
       const object2Value = object2[key as keyof T];
@@ -409,51 +411,56 @@ class Delta<T> {
 }
 
 /**
- * Encapsulates the modifications captured as `Delta`/s.
+ * Encapsulates a set of application-level `Delta`s.
  */
-interface Change<T> {
+interface DeltaContainer<T> {
   /**
-   * Inverses the `Delta`s inside while creating a new `Change`.
+   * Inverses the `Delta`s while creating a new `DeltaContainer` instance.
    */
-  inverse(): Change<T>;
+  inverse(): DeltaContainer<T>;
 
   /**
-   * Applies the `Change` to the previous object.
+   * Applies the `Delta`s to the previous object.
    *
-   * @returns a tuple of the next object `T` with applied change, and `boolean`, indicating whether the applied change resulted in a visible change.
+   * @returns a tuple of the next object `T` with applied `Delta`s, and `boolean`, indicating whether the applied deltas resulted in a visible change.
    */
   applyTo(previous: T, ...options: unknown[]): [T, boolean];
 
   /**
-   * Checks whether there are actually `Delta`s.
+   * Checks whether all `Delta`s are empty.
    */
   isEmpty(): boolean;
 }
 
-export class AppStateChange implements Change<AppState> {
-  private constructor(private readonly delta: Delta<ObservedAppState>) {}
+export class AppStateDelta implements DeltaContainer<AppState> {
+  private constructor(public readonly delta: Delta<ObservedAppState>) {}
 
   public static calculate<T extends ObservedAppState>(
     prevAppState: T,
     nextAppState: T,
-  ): AppStateChange {
+  ): AppStateDelta {
     const delta = Delta.calculate(
       prevAppState,
       nextAppState,
       undefined,
-      AppStateChange.postProcess,
+      AppStateDelta.postProcess,
     );
 
-    return new AppStateChange(delta);
+    return new AppStateDelta(delta);
+  }
+
+  public static restore(appStateDeltaDTO: DTO<AppStateDelta>): AppStateDelta {
+    const { delta } = appStateDeltaDTO;
+    return new AppStateDelta(delta);
   }
 
   public static empty() {
-    return new AppStateChange(Delta.create({}, {}));
+    return new AppStateDelta(Delta.create({}, {}));
   }
 
-  public inverse(): AppStateChange {
+  public inverse(): AppStateDelta {
     const inversedDelta = Delta.create(this.delta.inserted, this.delta.deleted);
-    return new AppStateChange(inversedDelta);
+    return new AppStateDelta(inversedDelta);
   }
 
   public applyTo(
@@ -530,7 +537,7 @@ export class AppStateChange implements Change<AppState> {
       return [nextAppState, constainsVisibleChanges];
     } catch (e) {
       // shouldn't really happen, but just in case
-      console.error(`Couldn't apply appstate change`, e);
+      console.error(`Couldn't apply appstate delta`, e);
 
       if (isTestEnv() || isDevEnv()) {
         throw e;
@@ -594,13 +601,13 @@ export class AppStateChange implements Change<AppState> {
     const nextObservedAppState = getObservedAppState(nextAppState);
 
     const containsStandaloneDifference = Delta.isRightDifferent(
-      AppStateChange.stripElementsProps(prevObservedAppState),
-      AppStateChange.stripElementsProps(nextObservedAppState),
+      AppStateDelta.stripElementsProps(prevObservedAppState),
+      AppStateDelta.stripElementsProps(nextObservedAppState),
     );
 
     const containsElementsDifference = Delta.isRightDifferent(
-      AppStateChange.stripStandaloneProps(prevObservedAppState),
-      AppStateChange.stripStandaloneProps(nextObservedAppState),
+      AppStateDelta.stripStandaloneProps(prevObservedAppState),
+      AppStateDelta.stripStandaloneProps(nextObservedAppState),
     );
 
     if (!containsStandaloneDifference && !containsElementsDifference) {
@@ -615,8 +622,8 @@ export class AppStateChange implements Change<AppState> {
     if (containsElementsDifference) {
       // filter invisible changes on each iteration
       const changedElementsProps = Delta.getRightDifferences(
-        AppStateChange.stripStandaloneProps(prevObservedAppState),
-        AppStateChange.stripStandaloneProps(nextObservedAppState),
+        AppStateDelta.stripStandaloneProps(prevObservedAppState),
+        AppStateDelta.stripStandaloneProps(nextObservedAppState),
       ) as Array<keyof ObservedElementsAppState>;
 
       let nonDeletedGroupIds = new Set<string>();
@@ -633,7 +640,7 @@ export class AppStateChange implements Change<AppState> {
       for (const key of changedElementsProps) {
         switch (key) {
           case "selectedElementIds":
-            nextAppState[key] = AppStateChange.filterSelectedElements(
+            nextAppState[key] = AppStateDelta.filterSelectedElements(
               nextAppState[key],
               nextElements,
               visibleDifferenceFlag,
@@ -641,7 +648,7 @@ export class AppStateChange implements Change<AppState> {
 
             break;
           case "selectedGroupIds":
-            nextAppState[key] = AppStateChange.filterSelectedGroups(
+            nextAppState[key] = AppStateDelta.filterSelectedGroups(
               nextAppState[key],
               nonDeletedGroupIds,
               visibleDifferenceFlag,
@@ -677,7 +684,7 @@ export class AppStateChange implements Change<AppState> {
             break;
           case "selectedLinearElementId":
           case "editingLinearElementId":
-            const appStateKey = AppStateChange.convertToAppStateKey(key);
+            const appStateKey = AppStateDelta.convertToAppStateKey(key);
             const linearElement = nextAppState[appStateKey];
 
             if (!linearElement) {
@@ -814,59 +821,72 @@ export class AppStateChange implements Change<AppState> {
   }
 }
 
-type ElementPartial<T extends ExcalidrawElement = ExcalidrawElement> = Omit<
-  ElementUpdate<Ordered<T>>,
-  "seed"
->;
+// CFDO: consider adding here (nonnullable) version & versionNonce & updated (so that we have correct versions when recunstructing from remote)
+type ElementPartial<T extends ExcalidrawElement = ExcalidrawElement> =
+  ElementUpdate<Ordered<T>>;
 
 /**
- * Elements change is a low level primitive to capture a change between two sets of elements.
+ * Elements delta is a low level primitive to encapsulate property changes between two sets of elements.
  * It does so by encapsulating forward and backward `Delta`s, allowing to time-travel in both directions.
  */
-export class ElementsChange implements Change<SceneElementsMap> {
+export class ElementsDelta implements DeltaContainer<SceneElementsMap> {
   private constructor(
-    private readonly added: Map<string, Delta<ElementPartial>>,
-    private readonly removed: Map<string, Delta<ElementPartial>>,
-    private readonly updated: Map<string, Delta<ElementPartial>>,
+    public readonly added: Record<string, Delta<ElementPartial>>,
+    public readonly removed: Record<string, Delta<ElementPartial>>,
+    public readonly updated: Record<string, Delta<ElementPartial>>,
   ) {}
 
   public static create(
-    added: Map<string, Delta<ElementPartial>>,
-    removed: Map<string, Delta<ElementPartial>>,
-    updated: Map<string, Delta<ElementPartial>>,
-    options = { shouldRedistribute: false },
+    added: Record<string, Delta<ElementPartial>>,
+    removed: Record<string, Delta<ElementPartial>>,
+    updated: Record<string, Delta<ElementPartial>>,
+    options: {
+      shouldRedistribute: boolean;
+    } = {
+      shouldRedistribute: false,
+    },
   ) {
-    let change: ElementsChange;
+    const { shouldRedistribute } = options;
+    let delta: ElementsDelta;
 
-    if (options.shouldRedistribute) {
-      const nextAdded = new Map<string, Delta<ElementPartial>>();
-      const nextRemoved = new Map<string, Delta<ElementPartial>>();
-      const nextUpdated = new Map<string, Delta<ElementPartial>>();
+    if (shouldRedistribute) {
+      const nextAdded: Record<string, Delta<ElementPartial>> = {};
+      const nextRemoved: Record<string, Delta<ElementPartial>> = {};
+      const nextUpdated: Record<string, Delta<ElementPartial>> = {};
 
-      const deltas = [...added, ...removed, ...updated];
+      const deltas = [
+        ...Object.entries(added),
+        ...Object.entries(removed),
+        ...Object.entries(updated),
+      ];
 
       for (const [id, delta] of deltas) {
         if (this.satisfiesAddition(delta)) {
-          nextAdded.set(id, delta);
+          nextAdded[id] = delta;
         } else if (this.satisfiesRemoval(delta)) {
-          nextRemoved.set(id, delta);
+          nextRemoved[id] = delta;
         } else {
-          nextUpdated.set(id, delta);
+          nextUpdated[id] = delta;
         }
       }
 
-      change = new ElementsChange(nextAdded, nextRemoved, nextUpdated);
+      delta = new ElementsDelta(nextAdded, nextRemoved, nextUpdated);
     } else {
-      change = new ElementsChange(added, removed, updated);
+      delta = new ElementsDelta(added, removed, updated);
     }
 
     if (isTestEnv() || isDevEnv()) {
-      ElementsChange.validate(change, "added", this.satisfiesAddition);
-      ElementsChange.validate(change, "removed", this.satisfiesRemoval);
-      ElementsChange.validate(change, "updated", this.satisfiesUpdate);
+      ElementsDelta.validate(delta, "added", this.satisfiesAddition);
+      ElementsDelta.validate(delta, "removed", this.satisfiesRemoval);
+      ElementsDelta.validate(delta, "updated", this.satisfiesUpdate);
     }
 
-    return change;
+    return delta;
+  }
+
+  public static restore(elementsDeltaDTO: DTO<ElementsDelta>): ElementsDelta {
+    const { added, removed, updated } = elementsDeltaDTO;
+    return ElementsDelta.create(added, removed, updated);
   }
 
   private static satisfiesAddition = ({
@@ -888,17 +908,17 @@ export class ElementsChange implements Change<SceneElementsMap> {
   }: Delta<ElementPartial>) => !!deleted.isDeleted === !!inserted.isDeleted;
 
   private static validate(
-    change: ElementsChange,
+    elementsDelta: ElementsDelta,
     type: "added" | "removed" | "updated",
     satifies: (delta: Delta<ElementPartial>) => boolean,
   ) {
-    for (const [id, delta] of change[type].entries()) {
+    for (const [id, delta] of Object.entries(elementsDelta[type])) {
       if (!satifies(delta)) {
         console.error(
           `Broken invariant for "${type}" delta, element "${id}", delta:`,
           delta,
         );
-        throw new Error(`ElementsChange invariant broken for element "${id}".`);
+        throw new Error(`ElementsDelta invariant broken for element "${id}".`);
       }
     }
   }
@@ -909,19 +929,19 @@ export class ElementsChange implements Change<SceneElementsMap> {
    * @param prevElements - Map representing the previous state of elements.
    * @param nextElements - Map representing the next state of elements.
    *
-   * @returns `ElementsChange` instance representing the `Delta` changes between the two sets of elements.
+   * @returns `ElementsDelta` instance representing the `Delta` changes between the two sets of elements.
    */
   public static calculate<T extends OrderedExcalidrawElement>(
     prevElements: Map<string, T>,
     nextElements: Map<string, T>,
-  ): ElementsChange {
+  ): ElementsDelta {
     if (prevElements === nextElements) {
-      return ElementsChange.empty();
+      return ElementsDelta.empty();
     }
 
-    const added = new Map<string, Delta<ElementPartial>>();
-    const removed = new Map<string, Delta<ElementPartial>>();
-    const updated = new Map<string, Delta<ElementPartial>>();
+    const added: Record<string, Delta<ElementPartial>> = {};
+    const removed: Record<string, Delta<ElementPartial>> = {};
+    const updated: Record<string, Delta<ElementPartial>> = {};
 
     // this might be needed only in same edge cases, like during collab, when `isDeleted` elements get removed or when we (un)intentionally remove the elements
     for (const prevElement of prevElements.values()) {
@@ -934,10 +954,10 @@ export class ElementsChange implements Change<SceneElementsMap> {
         const delta = Delta.create(
           deleted,
           inserted,
-          ElementsChange.stripIrrelevantProps,
+          ElementsDelta.stripIrrelevantProps,
         );
 
-        removed.set(prevElement.id, delta);
+        removed[prevElement.id] = delta;
       }
     }
 
@@ -954,10 +974,10 @@ export class ElementsChange implements Change<SceneElementsMap> {
         const delta = Delta.create(
           deleted,
           inserted,
-          ElementsChange.stripIrrelevantProps,
+          ElementsDelta.stripIrrelevantProps,
         );
 
-        added.set(nextElement.id, delta);
+        added[nextElement.id] = delta;
 
         continue;
       }
@@ -966,8 +986,8 @@ export class ElementsChange implements Change<SceneElementsMap> {
         const delta = Delta.calculate<ElementPartial>(
           prevElement,
           nextElement,
-          ElementsChange.stripIrrelevantProps,
-          ElementsChange.postProcess,
+          ElementsDelta.stripIrrelevantProps,
+          ElementsDelta.postProcess,
         );
 
         if (
@@ -978,9 +998,9 @@ export class ElementsChange implements Change<SceneElementsMap> {
         ) {
           // notice that other props could have been updated as well
           if (prevElement.isDeleted && !nextElement.isDeleted) {
-            added.set(nextElement.id, delta);
+            added[nextElement.id] = delta;
           } else {
-            removed.set(nextElement.id, delta);
+            removed[nextElement.id] = delta;
           }
 
           continue;
@@ -988,24 +1008,24 @@ export class ElementsChange implements Change<SceneElementsMap> {
 
         // making sure there are at least some changes
         if (!Delta.isEmpty(delta)) {
-          updated.set(nextElement.id, delta);
+          updated[nextElement.id] = delta;
         }
       }
     }
 
-    return ElementsChange.create(added, removed, updated);
+    return ElementsDelta.create(added, removed, updated);
   }
 
   public static empty() {
-    return ElementsChange.create(new Map(), new Map(), new Map());
+    return ElementsDelta.create({}, {}, {});
   }
 
-  public inverse(): ElementsChange {
-    const inverseInternal = (deltas: Map<string, Delta<ElementPartial>>) => {
-      const inversedDeltas = new Map<string, Delta<ElementPartial>>();
+  public inverse(): ElementsDelta {
+    const inverseInternal = (deltas: Record<string, Delta<ElementPartial>>) => {
+      const inversedDeltas: Record<string, Delta<ElementPartial>> = {};
 
-      for (const [id, delta] of deltas.entries()) {
-        inversedDeltas.set(id, Delta.create(delta.inserted, delta.deleted));
+      for (const [id, delta] of Object.entries(deltas)) {
+        inversedDeltas[id] = Delta.create(delta.inserted, delta.deleted);
       }
 
       return inversedDeltas;
@@ -1016,14 +1036,15 @@ export class ElementsChange implements Change<SceneElementsMap> {
     const updated = inverseInternal(this.updated);
 
     // notice we inverse removed with added not to break the invariants
-    return ElementsChange.create(removed, added, updated);
+    // notice we force generate a new id
+    return ElementsDelta.create(removed, added, updated);
   }
 
   public isEmpty(): boolean {
     return (
-      this.added.size === 0 &&
-      this.removed.size === 0 &&
-      this.updated.size === 0
+      Object.keys(this.added).length === 0 &&
+      Object.keys(this.removed).length === 0 &&
+      Object.keys(this.updated).length === 0
     );
   }
 
@@ -1034,7 +1055,10 @@ export class ElementsChange implements Change<SceneElementsMap> {
    * @param modifierOptions defines which of the delta (`deleted` or `inserted`) will be updated
    * @returns new instance with modified delta/s
    */
-  public applyLatestChanges(elements: SceneElementsMap): ElementsChange {
+  public applyLatestChanges(
+    elements: SceneElementsMap,
+    modifierOptions: "deleted" | "inserted",
+  ): ElementsDelta {
     const modifier =
       (element: OrderedExcalidrawElement) => (partial: ElementPartial) => {
         const latestPartial: { [key: string]: unknown } = {};
@@ -1055,11 +1079,11 @@ export class ElementsChange implements Change<SceneElementsMap> {
       };
 
     const applyLatestChangesInternal = (
-      deltas: Map<string, Delta<ElementPartial>>,
+      deltas: Record<string, Delta<ElementPartial>>,
     ) => {
-      const modifiedDeltas = new Map<string, Delta<ElementPartial>>();
+      const modifiedDeltas: Record<string, Delta<ElementPartial>> = {};
 
-      for (const [id, delta] of deltas.entries()) {
+      for (const [id, delta] of Object.entries(deltas)) {
         const existingElement = elements.get(id);
 
         if (existingElement) {
@@ -1067,12 +1091,12 @@ export class ElementsChange implements Change<SceneElementsMap> {
             delta.deleted,
             delta.inserted,
             modifier(existingElement),
-            "inserted",
+            modifierOptions,
           );
 
-          modifiedDeltas.set(id, modifiedDelta);
+          modifiedDeltas[id] = modifiedDelta;
         } else {
-          modifiedDeltas.set(id, delta);
+          modifiedDeltas[id] = delta;
         }
       }
 
@@ -1083,14 +1107,17 @@ export class ElementsChange implements Change<SceneElementsMap> {
     const removed = applyLatestChangesInternal(this.removed);
     const updated = applyLatestChangesInternal(this.updated);
 
-    return ElementsChange.create(added, removed, updated, {
+    return ElementsDelta.create(added, removed, updated, {
       shouldRedistribute: true, // redistribute the deltas as `isDeleted` could have been updated
     });
   }
 
   public applyTo(
     elements: SceneElementsMap,
-    snapshot: Map<string, OrderedExcalidrawElement>,
+    elementsSnapshot: Map<
+      string,
+      OrderedExcalidrawElement
+    > = StoreSnapshot.empty().elements,
   ): [SceneElementsMap, boolean] {
     let nextElements = toBrandedType<SceneElementsMap>(new Map(elements));
     let changedElements: Map<string, OrderedExcalidrawElement>;
@@ -1102,15 +1129,15 @@ export class ElementsChange implements Change<SceneElementsMap> {
 
     // mimic a transaction by applying deltas into `nextElements` (always new instance, no mutation)
     try {
-      const applyDeltas = ElementsChange.createApplier(
+      const applyDeltas = ElementsDelta.createApplier(
         nextElements,
-        snapshot,
+        elementsSnapshot,
         flags,
       );
 
-      const addedElements = applyDeltas(this.added);
-      const removedElements = applyDeltas(this.removed);
-      const updatedElements = applyDeltas(this.updated);
+      const addedElements = applyDeltas("added", this.added);
+      const removedElements = applyDeltas("removed", this.removed);
+      const updatedElements = applyDeltas("updated", this.updated);
 
       const affectedElements = this.resolveConflicts(elements, nextElements);
 
@@ -1122,7 +1149,7 @@ export class ElementsChange implements Change<SceneElementsMap> {
         ...affectedElements,
       ]);
     } catch (e) {
-      console.error(`Couldn't apply elements change`, e);
+      console.error(`Couldn't apply elements delta`, e);
 
       if (isTestEnv() || isDevEnv()) {
         throw e;
@@ -1138,7 +1165,7 @@ export class ElementsChange implements Change<SceneElementsMap> {
     try {
       // the following reorder performs also mutations, but only on new instances of changed elements
       // (unless something goes really bad and it fallbacks to fixing all invalid indices)
-      nextElements = ElementsChange.reorderElements(
+      nextElements = ElementsDelta.reorderElements(
         nextElements,
         changedElements,
         flags,
@@ -1149,9 +1176,9 @@ export class ElementsChange implements Change<SceneElementsMap> {
       // so we are creating a temp scene just to query and mutate elements
       const tempScene = new Scene(nextElements);
 
-      ElementsChange.redrawTextBoundingBoxes(tempScene, changedElements);
+      ElementsDelta.redrawTextBoundingBoxes(tempScene, changedElements);
       // Need ordered nextElements to avoid z-index binding issues
-      ElementsChange.redrawBoundArrows(tempScene, changedElements);
+      ElementsDelta.redrawBoundArrows(tempScene, changedElements);
     } catch (e) {
       console.error(
         `Couldn't mutate elements after applying elements change`,
@@ -1166,36 +1193,42 @@ export class ElementsChange implements Change<SceneElementsMap> {
     }
   }
 
-  private static createApplier = (
-    nextElements: SceneElementsMap,
-    snapshot: Map<string, OrderedExcalidrawElement>,
-    flags: {
-      containsVisibleDifference: boolean;
-      containsZindexDifference: boolean;
-    },
-  ) => {
-    const getElement = ElementsChange.createGetter(
-      nextElements,
-      snapshot,
-      flags,
-    );
+  private static createApplier =
+    (
+      nextElements: SceneElementsMap,
+      snapshot: Map<string, OrderedExcalidrawElement>,
+      flags: {
+        containsVisibleDifference: boolean;
+        containsZindexDifference: boolean;
+      },
+    ) =>
+    (
+      type: "added" | "removed" | "updated",
+      deltas: Record<string, Delta<ElementPartial>>,
+    ) => {
+      const getElement = ElementsDelta.createGetter(
+        type,
+        nextElements,
+        snapshot,
+        flags,
+      );
 
-    return (deltas: Map<string, Delta<ElementPartial>>) =>
-      Array.from(deltas.entries()).reduce((acc, [id, delta]) => {
+      return Object.entries(deltas).reduce((acc, [id, delta]) => {
         const element = getElement(id, delta.inserted);
 
         if (element) {
-          const newElement = ElementsChange.applyDelta(element, delta, flags);
+          const newElement = ElementsDelta.applyDelta(element, delta, flags);
           nextElements.set(newElement.id, newElement);
           acc.set(newElement.id, newElement);
         }
 
         return acc;
       }, new Map<string, OrderedExcalidrawElement>());
-  };
+    };
 
   private static createGetter =
     (
+      type: "added" | "removed" | "updated",
       elements: SceneElementsMap,
       snapshot: Map<string, OrderedExcalidrawElement>,
       flags: {
@@ -1221,6 +1254,15 @@ export class ElementsChange implements Change<SceneElementsMap> {
           ) {
             flags.containsVisibleDifference = true;
           }
+        } else if (type === "added") {
+          // for additions the element does not have to exist (i.e. remote update)
+          // CFDO II: the version itself might be different!
+          element = newElementWith(
+            { id, version: 1 } as OrderedExcalidrawElement,
+            {
+              ...partial,
+            },
+          );
         }
       }
 
@@ -1257,6 +1299,7 @@ export class ElementsChange implements Change<SceneElementsMap> {
       });
     }
 
+    // CFDO: this looks wrong
     if (isImageElement(element)) {
       const _delta = delta as Delta<ElementPartial<ExcalidrawImageElement>>;
       // we want to override `crop` only if modified so that we don't reset
@@ -1272,8 +1315,10 @@ export class ElementsChange implements Change<SceneElementsMap> {
     if (!flags.containsVisibleDifference) {
       // strip away fractional as even if it would be different, it doesn't have to result in visible change
       const { index, ...rest } = directlyApplicablePartial;
-      const containsVisibleDifference =
-        ElementsChange.checkForVisibleDifference(element, rest);
+      const containsVisibleDifference = ElementsDelta.checkForVisibleDifference(
+        element,
+        rest,
+      );
 
       flags.containsVisibleDifference = containsVisibleDifference;
     }
@@ -1316,6 +1361,8 @@ export class ElementsChange implements Change<SceneElementsMap> {
    * Resolves conflicts for all previously added, removed and updated elements.
    * Updates the previous deltas with all the changes after conflict resolution.
    *
+   * // CFDO: revisit since arrow seem often redrawn incorrectly
+   *
    * @returns all elements affected by the conflict resolution
    */
   private resolveConflicts(
@@ -1354,20 +1401,21 @@ export class ElementsChange implements Change<SceneElementsMap> {
     };
 
     // removed delta is affecting the bindings always, as all the affected elements of the removed elements need to be unbound
-    for (const [id] of this.removed) {
-      ElementsChange.unbindAffected(prevElements, nextElements, id, updater);
+    for (const id of Object.keys(this.removed)) {
+      ElementsDelta.unbindAffected(prevElements, nextElements, id, updater);
     }
 
     // added delta is affecting the bindings always, all the affected elements of the added elements need to be rebound
-    for (const [id] of this.added) {
-      ElementsChange.rebindAffected(prevElements, nextElements, id, updater);
+    for (const id of Object.keys(this.added)) {
+      ElementsDelta.rebindAffected(prevElements, nextElements, id, updater);
     }
 
     // updated delta is affecting the binding only in case it contains changed binding or bindable property
-    for (const [id] of Array.from(this.updated).filter(([_, delta]) =>
-      Object.keys({ ...delta.deleted, ...delta.inserted }).find((prop) =>
-        bindingProperties.has(prop as BindingProp | BindableProp),
-      ),
+    for (const [id] of Array.from(Object.entries(this.updated)).filter(
+      ([_, delta]) =>
+        Object.keys({ ...delta.deleted, ...delta.inserted }).find((prop) =>
+          bindingProperties.has(prop as BindingProp | BindableProp),
+        ),
     )) {
       const updatedElement = nextElements.get(id);
       if (!updatedElement || updatedElement.isDeleted) {
@@ -1375,7 +1423,7 @@ export class ElementsChange implements Change<SceneElementsMap> {
         continue;
       }
 
-      ElementsChange.rebindAffected(prevElements, nextElements, id, updater);
+      ElementsDelta.rebindAffected(prevElements, nextElements, id, updater);
     }
 
     // filter only previous elements, which were now affected
@@ -1385,21 +1433,21 @@ export class ElementsChange implements Change<SceneElementsMap> {
 
     // calculate complete deltas for affected elements, and assign them back to all the deltas
     // technically we could do better here if perf. would become an issue
-    const { added, removed, updated } = ElementsChange.calculate(
+    const { added, removed, updated } = ElementsDelta.calculate(
       prevAffectedElements,
       nextAffectedElements,
     );
 
-    for (const [id, delta] of added) {
-      this.added.set(id, delta);
+    for (const [id, delta] of Object.entries(added)) {
+      this.added[id] = delta;
     }
 
-    for (const [id, delta] of removed) {
-      this.removed.set(id, delta);
+    for (const [id, delta] of Object.entries(removed)) {
+      this.removed[id] = delta;
     }
 
-    for (const [id, delta] of updated) {
-      this.updated.set(id, delta);
+    for (const [id, delta] of Object.entries(updated)) {
+      this.updated[id] = delta;
     }
 
     return nextAffectedElements;
@@ -1572,7 +1620,7 @@ export class ElementsChange implements Change<SceneElementsMap> {
       Delta.diffArrays(deleted, inserted, "boundElements", (x) => x.id);
     } catch (e) {
       // if postprocessing fails, it does not make sense to bubble up, but let's make sure we know about it
-      console.error(`Couldn't postprocess elements change deltas.`);
+      console.error(`Couldn't postprocess elements delta.`);
 
       if (isTestEnv() || isDevEnv()) {
         throw e;
@@ -1585,8 +1633,7 @@ export class ElementsChange implements Change<SceneElementsMap> {
   private static stripIrrelevantProps(
     partial: Partial<OrderedExcalidrawElement>,
   ): ElementPartial {
-    const { id, updated, version, versionNonce, seed, ...strippedPartial } =
-      partial;
+    const { id, updated, version, versionNonce, ...strippedPartial } = partial;
 
     return strippedPartial;
   }

packages/excalidraw/history.ts

@@ -1,11 +1,12 @@
 import type { SceneElementsMap } from "@excalidraw/element/types";
 
 import { Emitter } from "./emitter";
+import { type Store, StoreDelta, StoreIncrement } from "./store";
 
-import type { AppStateChange, ElementsChange } from "./change";
-import type { Snapshot } from "./store";
 import type { AppState } from "./types";
 
+export class HistoryEntry extends StoreDelta {}
+
 type HistoryStack = HistoryEntry[];
 
 export class HistoryChangedEvent {
@@ -20,8 +21,8 @@ export class History {
     [HistoryChangedEvent]
   >();
 
-  private readonly undoStack: HistoryStack = [];
-  private readonly redoStack: HistoryStack = [];
+  public readonly undoStack: HistoryStack = [];
+  public readonly redoStack: HistoryStack = [];
 
   public get isUndoStackEmpty() {
     return this.undoStack.length === 0;
@@ -31,6 +32,8 @@ export class History {
     return this.redoStack.length === 0;
   }
 
+  constructor(private readonly store: Store) {}
+
   public clear() {
     this.undoStack.length = 0;
     this.redoStack.length = 0;
@@ -39,17 +42,18 @@ export class History {
   /**
    * Record a local change which will go into the history
    */
-  public record(
-    elementsChange: ElementsChange,
-    appStateChange: AppStateChange,
-  ) {
-    const entry = HistoryEntry.create(appStateChange, elementsChange);
+  public record(increment: StoreIncrement) {
+    if (
+      StoreIncrement.isDurable(increment) &&
+      !increment.delta.isEmpty() &&
+      !(increment.delta instanceof HistoryEntry)
+    ) {
+      // construct history entry, so once it's emitted, it's not recorded again
+      const entry = HistoryEntry.inverse(increment.delta);
 
-    if (!entry.isEmpty()) {
-      // we have the latest changes, no need to `applyLatest`, which is done within `History.push`
-      this.undoStack.push(entry.inverse());
+      this.undoStack.push(entry);
 
-      if (!entry.elementsChange.isEmpty()) {
+      if (!entry.elements.isEmpty()) {
         // don't reset redo stack on local appState changes,
         // as a simple click (unselect) could lead to losing all the redo entries
         // only reset on non empty elements changes!
@@ -62,29 +66,19 @@ export class History {
     }
   }
 
-  public undo(
-    elements: SceneElementsMap,
-    appState: AppState,
-    snapshot: Readonly<Snapshot>,
-  ) {
+  public undo(elements: SceneElementsMap, appState: AppState) {
     return this.perform(
       elements,
       appState,
-      snapshot,
       () => History.pop(this.undoStack),
       (entry: HistoryEntry) => History.push(this.redoStack, entry, elements),
     );
   }
 
-  public redo(
-    elements: SceneElementsMap,
-    appState: AppState,
-    snapshot: Readonly<Snapshot>,
-  ) {
+  public redo(elements: SceneElementsMap, appState: AppState) {
     return this.perform(
       elements,
       appState,
-      snapshot,
       () => History.pop(this.redoStack),
       (entry: HistoryEntry) => History.push(this.undoStack, entry, elements),
     );
@@ -93,7 +87,6 @@ export class History {
   private perform(
     elements: SceneElementsMap,
     appState: AppState,
-    snapshot: Readonly<Snapshot>,
     pop: () => HistoryEntry | null,
     push: (entry: HistoryEntry) => void,
   ): [SceneElementsMap, AppState] | void {
@@ -104,6 +97,7 @@ export class History {
         return;
       }
 
+      let prevSnapshot = this.store.snapshot;
       let nextElements = elements;
       let nextAppState = appState;
       let containsVisibleChange = false;
@@ -112,9 +106,18 @@ export class History {
       while (historyEntry) {
         try {
           [nextElements, nextAppState, containsVisibleChange] =
-            historyEntry.applyTo(nextElements, nextAppState, snapshot);
+            this.store.applyDeltaTo(historyEntry, nextElements, nextAppState, {
+              triggerIncrement: true,
+              updateSnapshot: true,
+            });
+
+          prevSnapshot = this.store.snapshot;
+        } catch (e) {
+          console.error("Failed to apply history entry:", e);
+          // rollback to the previous snapshot, so that we don't end up in an incosistent state
+          this.store.snapshot = prevSnapshot;
         } finally {
-          // make sure to always push / pop, even if the increment is corrupted
+          // make sure to always push, even if the delta is corrupted
           push(historyEntry);
         }
 
@@ -125,6 +128,10 @@ export class History {
         historyEntry = pop();
       }
 
+      if (nextElements === null || nextAppState === null) {
+        return;
+      }
+
       return [nextElements, nextAppState];
     } finally {
       // trigger the history change event before returning completely
@@ -154,59 +161,13 @@ export class History {
     entry: HistoryEntry,
     prevElements: SceneElementsMap,
   ) {
-    const updatedEntry = entry.inverse().applyLatestChanges(prevElements);
+    const inversedEntry = HistoryEntry.inverse(entry);
+    const updatedEntry = HistoryEntry.applyLatestChanges(
+      inversedEntry,
+      prevElements,
+      "inserted",
+    );
+
     return stack.push(updatedEntry);
   }
 }
-
-export class HistoryEntry {
-  private constructor(
-    public readonly appStateChange: AppStateChange,
-    public readonly elementsChange: ElementsChange,
-  ) {}
-
-  public static create(
-    appStateChange: AppStateChange,
-    elementsChange: ElementsChange,
-  ) {
-    return new HistoryEntry(appStateChange, elementsChange);
-  }
-
-  public inverse(): HistoryEntry {
-    return new HistoryEntry(
-      this.appStateChange.inverse(),
-      this.elementsChange.inverse(),
-    );
-  }
-
-  public applyTo(
-    elements: SceneElementsMap,
-    appState: AppState,
-    snapshot: Readonly<Snapshot>,
-  ): [SceneElementsMap, AppState, boolean] {
-    const [nextElements, elementsContainVisibleChange] =
-      this.elementsChange.applyTo(elements, snapshot.elements);
-
-    const [nextAppState, appStateContainsVisibleChange] =
-      this.appStateChange.applyTo(appState, nextElements);
-
-    const appliedVisibleChanges =
-      elementsContainVisibleChange || appStateContainsVisibleChange;
-
-    return [nextElements, nextAppState, appliedVisibleChanges];
-  }
-
-  /**
-   * Apply latest (remote) changes to the history entry, creates new instance of `HistoryEntry`.
-   */
-  public applyLatestChanges(elements: SceneElementsMap): HistoryEntry {
-    const updatedElementsChange =
-      this.elementsChange.applyLatestChanges(elements);
-
-    return HistoryEntry.create(this.appStateChange, updatedElementsChange);
-  }
-
-  public isEmpty(): boolean {
-    return this.appStateChange.isEmpty() && this.elementsChange.isEmpty();
-  }
-}

packages/excalidraw/hooks/useOutsideClick.ts

@@ -31,7 +31,7 @@ export function useOutsideClick<T extends HTMLElement>(
         return;
       }
 
-      const isInsideOverride = isInside?.(_event, ref.current);
+      const isInsideOverride = isInside?.(_event as any, ref.current);
 
       if (isInsideOverride === true) {
         return;

packages/excalidraw/index.tsx

@@ -23,6 +23,7 @@ polyfill();
 const ExcalidrawBase = (props: ExcalidrawProps) => {
   const {
     onChange,
+    onIncrement,
     initialData,
     excalidrawAPI,
     isCollaborating = false,
@@ -114,6 +115,7 @@ const ExcalidrawBase = (props: ExcalidrawProps) => {
       <InitializeApp langCode={langCode} theme={theme}>
         <App
           onChange={onChange}
+          onIncrement={onIncrement}
           initialData={initialData}
           excalidrawAPI={excalidrawAPI}
           isCollaborating={isCollaborating}

packages/excalidraw/store.ts

@@ -1,18 +1,30 @@
-import { isDevEnv, isShallowEqual, isTestEnv } from "@excalidraw/common";
+import {
+  arrayToMap,
+  assertNever,
+  isDevEnv,
+  isTestEnv,
+  randomId,
+} from "@excalidraw/common";
 
+import { hashElementsVersion } from "@excalidraw/element";
 import { deepCopyElement } from "@excalidraw/element/duplicate";
-
 import { newElementWith } from "@excalidraw/element/mutateElement";
+import { syncMovedIndices } from "@excalidraw/element/fractionalIndex";
 
-import type { OrderedExcalidrawElement } from "@excalidraw/element/types";
+import type {
+  ExcalidrawElement,
+  OrderedExcalidrawElement,
+  SceneElementsMap,
+} from "@excalidraw/element/types";
 
-import type { ValueOf } from "@excalidraw/common/utility-types";
+import type { DTO, ValueOf } from "@excalidraw/common/utility-types";
 
 import { getDefaultAppState } from "./appState";
-import { AppStateChange, ElementsChange } from "./change";
 
 import { Emitter } from "./emitter";
 
+import { ElementsDelta, AppStateDelta, Delta } from "./delta";
+
 import type { AppState, ObservedAppState } from "./types";
 
 // hidden non-enumerable property for runtime checks
@@ -43,12 +55,13 @@ const isObservedAppState = (
 ): appState is ObservedAppState =>
   !!Reflect.get(appState, hiddenObservedAppStateProp);
 
+// CFDO: consider adding a "remote" action, which should perform update but never be emitted (so that it we don't have to filter it when pushing it into sync api)
 export const CaptureUpdateAction = {
   /**
    * Immediately undoable.
    *
-   * Use for updates which should be captured.
-   * Should be used for most of the local updates.
+   * Use for updates which should be captured as durable deltas.
+   * Should be used for most of the local updates (except ephemerals such as dragging or resizing).
    *
    * These updates will _immediately_ make it to the local undo / redo stacks.
    */
@@ -56,7 +69,7 @@ export const CaptureUpdateAction = {
   /**
    * Never undoable.
    *
-   * Use for updates which should never be recorded, such as remote updates
+   * Use for updates which should never be captured as deltas, such as remote updates
    * or scene initialization.
    *
    * These updates will _never_ make it to the local undo / redo stacks.
@@ -79,160 +92,169 @@ export const CaptureUpdateAction = {
 export type CaptureUpdateActionType = ValueOf<typeof CaptureUpdateAction>;
 
 /**
- * Represent an increment to the Store.
+ * Store which captures the observed changes and emits them as `StoreIncrement` events.
  */
-class StoreIncrementEvent {
-  constructor(
-    public readonly elementsChange: ElementsChange,
-    public readonly appStateChange: AppStateChange,
-  ) {}
-}
-
-/**
- * Store which captures the observed changes and emits them as `StoreIncrementEvent` events.
- *
- * @experimental this interface is experimental and subject to change.
- */
-export interface IStore {
-  onStoreIncrementEmitter: Emitter<[StoreIncrementEvent]>;
-  get snapshot(): Snapshot;
-  set snapshot(snapshot: Snapshot);
-
-  /**
-   * Use to schedule update of the snapshot, useful on updates for which we don't need to calculate increments (i.e. remote updates).
-   */
-  shouldUpdateSnapshot(): void;
-
-  /**
-   * Use to schedule calculation of a store increment.
-   */
-  shouldCaptureIncrement(): void;
-
-  /**
-   * Based on the scheduled operation, either only updates store snapshot or also calculates increment and emits the result as a `StoreIncrementEvent`.
-   *
-   * @emits StoreIncrementEvent when increment is calculated.
-   */
-  commit(
-    elements: Map<string, OrderedExcalidrawElement> | undefined,
-    appState: AppState | ObservedAppState | undefined,
-  ): void;
-
-  /**
-   * Clears the store instance.
-   */
-  clear(): void;
-
-  /**
-   * Filters out yet uncomitted elements from `nextElements`, which are part of in-progress local async actions (ephemerals) and thus were not yet commited to the snapshot.
-   *
-   * This is necessary in updates in which we receive reconciled elements, already containing elements which were not yet captured by the local store (i.e. collab).
-   */
-  filterUncomittedElements(
-    prevElements: Map<string, OrderedExcalidrawElement>,
-    nextElements: Map<string, OrderedExcalidrawElement>,
-  ): Map<string, OrderedExcalidrawElement>;
-}
-
-export class Store implements IStore {
+export class Store {
   public readonly onStoreIncrementEmitter = new Emitter<
-    [StoreIncrementEvent]
+    [DurableStoreIncrement | EphemeralStoreIncrement]
   >();
 
   private scheduledActions: Set<CaptureUpdateActionType> = new Set();
-  private _snapshot = Snapshot.empty();
+  private _snapshot = StoreSnapshot.empty();
 
   public get snapshot() {
     return this._snapshot;
   }
 
-  public set snapshot(snapshot: Snapshot) {
+  public set snapshot(snapshot: StoreSnapshot) {
     this._snapshot = snapshot;
   }
 
-  // TODO: Suspicious that this is called so many places. Seems error-prone.
-  public shouldCaptureIncrement = () => {
-    this.scheduleAction(CaptureUpdateAction.IMMEDIATELY);
-  };
-
-  public shouldUpdateSnapshot = () => {
-    this.scheduleAction(CaptureUpdateAction.NEVER);
-  };
-
-  private scheduleAction = (action: CaptureUpdateActionType) => {
+  public scheduleAction(action: CaptureUpdateActionType) {
     this.scheduledActions.add(action);
     this.satisfiesScheduledActionsInvariant();
-  };
+  }
 
-  public commit = (
+  /**
+   * Use to schedule a delta calculation, which will consquentially be emitted as `DurableStoreIncrement` and pushed in the undo stack.
+   */
+  // TODO: Suspicious that this is called so many places. Seems error-prone.
+  public scheduleCapture() {
+    this.scheduleAction(CaptureUpdateAction.IMMEDIATELY);
+  }
+
+  private get scheduledAction() {
+    // Capture has a precedence over update, since it also performs snapshot update
+    if (this.scheduledActions.has(CaptureUpdateAction.IMMEDIATELY)) {
+      return CaptureUpdateAction.IMMEDIATELY;
+    }
+
+    // Update has a precedence over none, since it also emits an (ephemeral) increment
+    if (this.scheduledActions.has(CaptureUpdateAction.NEVER)) {
+      return CaptureUpdateAction.NEVER;
+    }
+
+    // CFDO: maybe it should be explicitly set so that we don't clone on every single component update
+    // Emit ephemeral increment, don't update the snapshot
+    return CaptureUpdateAction.EVENTUALLY;
+  }
+
+  /**
+   * Performs the incoming `CaptureUpdateAction` and emits the corresponding `StoreIncrement`.
+   * Emits `DurableStoreIncrement` when action is "capture", emits `EphemeralStoreIncrement` otherwise.
+   *
+   * @emits StoreIncrement
+   */
+  public commit(
     elements: Map<string, OrderedExcalidrawElement> | undefined,
     appState: AppState | ObservedAppState | undefined,
-  ): void => {
+  ): void {
     try {
-      // Capture has precedence since it also performs update
-      if (this.scheduledActions.has(CaptureUpdateAction.IMMEDIATELY)) {
-        this.captureIncrement(elements, appState);
-      } else if (this.scheduledActions.has(CaptureUpdateAction.NEVER)) {
-        this.updateSnapshot(elements, appState);
+      const { scheduledAction } = this;
+
+      switch (scheduledAction) {
+        case CaptureUpdateAction.IMMEDIATELY:
+          this.snapshot = this.captureDurableIncrement(elements, appState);
+          break;
+        case CaptureUpdateAction.NEVER:
+          this.snapshot = this.emitEphemeralIncrement(elements);
+          break;
+        case CaptureUpdateAction.EVENTUALLY:
+          // ÇFDO: consider perf. optimisation without creating a snapshot if it is not updated in the end, it shall not be needed (more complex though)
+          this.emitEphemeralIncrement(elements);
+          return;
+        default:
+          assertNever(scheduledAction, `Unknown store action`);
       }
     } finally {
       this.satisfiesScheduledActionsInvariant();
       // Defensively reset all scheduled actions, potentially cleans up other runtime garbage
       this.scheduledActions = new Set();
     }
-  };
+  }
 
-  public captureIncrement = (
+  /**
+   * Performs delta calculation and emits the increment.
+   *
+   * @emits StoreIncrement.
+   */
+  private captureDurableIncrement(
     elements: Map<string, OrderedExcalidrawElement> | undefined,
     appState: AppState | ObservedAppState | undefined,
-  ) => {
+  ) {
     const prevSnapshot = this.snapshot;
-    const nextSnapshot = this.snapshot.maybeClone(elements, appState);
+    const nextSnapshot = this.snapshot.maybeClone(elements, appState, {
+      shouldIgnoreCache: true,
+    });
 
     // Optimisation, don't continue if nothing has changed
-    if (prevSnapshot !== nextSnapshot) {
-      // Calculate and record the changes based on the previous and next snapshot
-      const elementsChange = nextSnapshot.meta.didElementsChange
-        ? ElementsChange.calculate(prevSnapshot.elements, nextSnapshot.elements)
-        : ElementsChange.empty();
-
-      const appStateChange = nextSnapshot.meta.didAppStateChange
-        ? AppStateChange.calculate(prevSnapshot.appState, nextSnapshot.appState)
-        : AppStateChange.empty();
-
-      if (!elementsChange.isEmpty() || !appStateChange.isEmpty()) {
-        // Notify listeners with the increment
-        this.onStoreIncrementEmitter.trigger(
-          new StoreIncrementEvent(elementsChange, appStateChange),
-        );
-      }
-
-      // Update snapshot
-      this.snapshot = nextSnapshot;
+    if (prevSnapshot === nextSnapshot) {
+      return prevSnapshot;
     }
-  };
+    // Calculate the deltas based on the previous and next snapshot
+    const elementsDelta = nextSnapshot.metadata.didElementsChange
+      ? ElementsDelta.calculate(prevSnapshot.elements, nextSnapshot.elements)
+      : ElementsDelta.empty();
 
-  public updateSnapshot = (
+    const appStateDelta = nextSnapshot.metadata.didAppStateChange
+      ? AppStateDelta.calculate(prevSnapshot.appState, nextSnapshot.appState)
+      : AppStateDelta.empty();
+
+    if (!elementsDelta.isEmpty() || !appStateDelta.isEmpty()) {
+      const delta = StoreDelta.create(elementsDelta, appStateDelta);
+      const change = StoreChange.create(prevSnapshot, nextSnapshot);
+      const increment = new DurableStoreIncrement(change, delta);
+
+      // Notify listeners with the increment
+      this.onStoreIncrementEmitter.trigger(increment);
+    }
+
+    return nextSnapshot;
+  }
+
+  /**
+   * When change is detected, emits an ephemeral increment and returns the next snapshot.
+   *
+   * @emits EphemeralStoreIncrement
+   */
+  private emitEphemeralIncrement(
     elements: Map<string, OrderedExcalidrawElement> | undefined,
-    appState: AppState | ObservedAppState | undefined,
-  ) => {
-    const nextSnapshot = this.snapshot.maybeClone(elements, appState);
+  ) {
+    const prevSnapshot = this.snapshot;
+    const nextSnapshot = this.snapshot.maybeClone(elements, undefined);
 
-    if (this.snapshot !== nextSnapshot) {
-      // Update snapshot
-      this.snapshot = nextSnapshot;
+    if (prevSnapshot === nextSnapshot) {
+      // nothing has changed
+      return prevSnapshot;
     }
-  };
 
-  public filterUncomittedElements = (
-    prevElements: Map<string, OrderedExcalidrawElement>,
-    nextElements: Map<string, OrderedExcalidrawElement>,
-  ) => {
+    const change = StoreChange.create(prevSnapshot, nextSnapshot);
+    const increment = new EphemeralStoreIncrement(change);
+
+    // Notify listeners with the increment
+    // CFDO: consider having this async instead, possibly should also happen after the component updates;
+    // or get rid of filtering local in progress elements, switch to unidirectional store flow and keep it synchronous
+    this.onStoreIncrementEmitter.trigger(increment);
+
+    return nextSnapshot;
+  }
+
+  /**
+   * Filters out yet uncomitted elements from `nextElements`, which are part of in-progress local async actions (ephemerals) and thus were not yet commited to the snapshot.
+   *
+   * This is necessary in updates in which we receive reconciled elements, already containing elements which were not yet captured by the local store (i.e. collab).
+   */
+  public filterUncomittedElements(
+    prevElements: Map<string, ExcalidrawElement>,
+    nextElements: Map<string, ExcalidrawElement>,
+  ): Map<string, OrderedExcalidrawElement> {
+    const movedElements = new Map<string, ExcalidrawElement>();
+
     for (const [id, prevElement] of prevElements.entries()) {
       const nextElement = nextElements.get(id);
 
       if (!nextElement) {
-        // Nothing to care about here, elements were forcefully deleted
+        // Nothing to care about here, element was forcefully deleted
         continue;
       }
 
@@ -243,21 +265,86 @@ export class Store implements IStore {
         // Detected yet uncomitted local element
         nextElements.delete(id);
       } else if (elementSnapshot.version < prevElement.version) {
-        // Element was already commited, but the snapshot version is lower than current current local version
+        // Element was already commited, but the snapshot version is lower than current local version
         nextElements.set(id, elementSnapshot);
+        // Mark the element as potentially moved, as it could have
+        movedElements.set(id, elementSnapshot);
       }
     }
 
-    return nextElements;
-  };
+    // Make sure to sync only potentially invalid indices for all elements restored from the snapshot
+    const syncedElements = syncMovedIndices(
+      Array.from(nextElements.values()),
+      movedElements,
+    );
 
-  public clear = (): void => {
-    this.snapshot = Snapshot.empty();
+    return arrayToMap(syncedElements);
+  }
+
+  /**
+   * Apply and emit increment.
+   *
+   * @emits StoreIncrement when increment is applied.
+   */
+  public applyDeltaTo(
+    delta: StoreDelta,
+    elements: SceneElementsMap,
+    appState: AppState,
+    options: {
+      triggerIncrement: boolean;
+      updateSnapshot: boolean;
+    } = {
+      triggerIncrement: false,
+      updateSnapshot: false,
+    },
+  ): [SceneElementsMap, AppState, boolean] {
+    const [nextElements, elementsContainVisibleChange] = delta.elements.applyTo(
+      elements,
+      this.snapshot.elements,
+    );
+
+    const [nextAppState, appStateContainsVisibleChange] =
+      delta.appState.applyTo(appState, nextElements);
+
+    const appliedVisibleChanges =
+      elementsContainVisibleChange || appStateContainsVisibleChange;
+
+    const prevSnapshot = this.snapshot;
+    const nextSnapshot = this.snapshot.maybeClone(nextElements, nextAppState, {
+      shouldIgnoreCache: true,
+    });
+
+    if (options.triggerIncrement) {
+      const change = StoreChange.create(prevSnapshot, nextSnapshot);
+      const increment = new DurableStoreIncrement(change, delta);
+      this.onStoreIncrementEmitter.trigger(increment);
+    }
+
+    // CFDO II: maybe I should not update the snapshot here so that it always syncs ephemeral change after durable change,
+    // so that clients exchange the latest element versions between each other,
+    // meaning if it will be ignored on other clients, other clients would initiate a relay with current version instead of doing nothing
+    if (options.updateSnapshot) {
+      this.snapshot = nextSnapshot;
+    }
+
+    return [nextElements, nextAppState, appliedVisibleChanges];
+  }
+
+  /**
+   * Clears the store instance.
+   */
+  public clear(): void {
+    this.snapshot = StoreSnapshot.empty();
     this.scheduledActions = new Set();
-  };
+  }
 
-  private satisfiesScheduledActionsInvariant = () => {
-    if (!(this.scheduledActions.size >= 0 && this.scheduledActions.size <= 3)) {
+  private satisfiesScheduledActionsInvariant() {
+    if (
+      !(
+        this.scheduledActions.size >= 0 &&
+        this.scheduledActions.size <= Object.keys(CaptureUpdateAction).length
+      )
+    ) {
       const message = `There can be at most three store actions scheduled at the same time, but there are "${this.scheduledActions.size}".`;
       console.error(message, this.scheduledActions.values());
 
@@ -265,14 +352,162 @@ export class Store implements IStore {
         throw new Error(message);
       }
     }
-  };
+  }
 }
 
-export class Snapshot {
+/**
+ * Repsents a change to the store containg changed elements and appState.
+ */
+export class StoreChange {
+  // CFDO: consider adding (observed & syncable) appState, though bare in mind that it's processed on every component update,
+  // so figuring out what has changed should ideally be just quick reference checks
+  private constructor(
+    public readonly elements: Record<string, OrderedExcalidrawElement>,
+  ) {}
+
+  public static create(
+    prevSnapshot: StoreSnapshot,
+    nextSnapshot: StoreSnapshot,
+  ) {
+    const changedElements = nextSnapshot.getChangedElements(prevSnapshot);
+    return new StoreChange(changedElements);
+  }
+}
+
+/**
+ * Encpasulates any change to the store (durable or ephemeral).
+ */
+export abstract class StoreIncrement {
+  protected constructor(
+    public readonly type: "durable" | "ephemeral",
+    public readonly change: StoreChange,
+  ) {}
+
+  public static isDurable(
+    increment: StoreIncrement,
+  ): increment is DurableStoreIncrement {
+    return increment.type === "durable";
+  }
+
+  public static isEphemeral(
+    increment: StoreIncrement,
+  ): increment is EphemeralStoreIncrement {
+    return increment.type === "ephemeral";
+  }
+}
+
+/**
+ * Represents a durable change to the store.
+ */
+export class DurableStoreIncrement extends StoreIncrement {
+  constructor(
+    public readonly change: StoreChange,
+    public readonly delta: StoreDelta,
+  ) {
+    super("durable", change);
+  }
+}
+
+/**
+ * Represents an ephemeral change to the store.
+ */
+export class EphemeralStoreIncrement extends StoreIncrement {
+  constructor(public readonly change: StoreChange) {
+    super("ephemeral", change);
+  }
+}
+
+/**
+ * Represents a captured delta by the Store.
+ */
+export class StoreDelta {
+  protected constructor(
+    public readonly id: string,
+    public readonly elements: ElementsDelta,
+    public readonly appState: AppStateDelta,
+  ) {}
+
+  /**
+   * Create a new instance of `StoreDelta`.
+   */
+  public static create(
+    elements: ElementsDelta,
+    appState: AppStateDelta,
+    opts: {
+      id: string;
+    } = {
+      id: randomId(),
+    },
+  ) {
+    return new this(opts.id, elements, appState);
+  }
+
+  /**
+   * Restore a store delta instance from a DTO.
+   */
+  public static restore(storeDeltaDTO: DTO<StoreDelta>) {
+    const { id, elements, appState } = storeDeltaDTO;
+    return new this(
+      id,
+      ElementsDelta.restore(elements),
+      AppStateDelta.restore(appState),
+    );
+  }
+
+  /**
+   * Parse and load the delta from the remote payload.
+   */
+  public static load({
+    id,
+    elements: { added, removed, updated },
+  }: DTO<StoreDelta>) {
+    const elements = ElementsDelta.create(added, removed, updated, {
+      shouldRedistribute: false,
+    });
+
+    return new this(id, elements, AppStateDelta.empty());
+  }
+
+  /**
+   * Inverse store delta, creates new instance of `StoreDelta`.
+   */
+  public static inverse(delta: StoreDelta): StoreDelta {
+    return this.create(delta.elements.inverse(), delta.appState.inverse());
+  }
+
+  /**
+   * Apply latest (remote) changes to the delta, creates new instance of `StoreDelta`.
+   */
+  public static applyLatestChanges(
+    delta: StoreDelta,
+    elements: SceneElementsMap,
+    modifierOptions: "deleted" | "inserted",
+  ): StoreDelta {
+    return this.create(
+      delta.elements.applyLatestChanges(elements, modifierOptions),
+      delta.appState,
+      {
+        id: delta.id,
+      },
+    );
+  }
+
+  public isEmpty() {
+    return this.elements.isEmpty() && this.appState.isEmpty();
+  }
+}
+
+/**
+ * Represents a snapshot of the captured or updated changes in the store,
+ * used for producing deltas and emitting `DurableStoreIncrement`s.
+ */
+export class StoreSnapshot {
+  private _lastChangedElementsHash: number = 0;
+
   private constructor(
     public readonly elements: Map<string, OrderedExcalidrawElement>,
     public readonly appState: ObservedAppState,
-    public readonly meta: {
+    public readonly metadata: {
       didElementsChange: boolean;
       didAppStateChange: boolean;
       isEmpty?: boolean;
@@ -284,15 +519,43 @@ export class Snapshot {
   ) {}
 
   public static empty() {
-    return new Snapshot(
+    return new StoreSnapshot(
       new Map(),
       getObservedAppState(getDefaultAppState() as AppState),
       { didElementsChange: false, didAppStateChange: false, isEmpty: true },
     );
   }
 
+  public getChangedElements(prevSnapshot: StoreSnapshot) {
+    const changedElements: Record<string, OrderedExcalidrawElement> = {};
+
+    for (const [id, nextElement] of this.elements.entries()) {
+      // Due to the structural clone inside `maybeClone`, we can perform just these reference checks
+      if (prevSnapshot.elements.get(id) !== nextElement) {
+        changedElements[id] = nextElement;
+      }
+    }
+
+    return changedElements;
+  }
+
+  public getChangedAppState(
+    prevSnapshot: StoreSnapshot,
+  ): Partial<ObservedAppState> {
+    return Delta.getRightDifferences(
+      prevSnapshot.appState,
+      this.appState,
+    ).reduce(
+      (acc, key) =>
+        Object.assign(acc, {
+          [key]: this.appState[key as keyof ObservedAppState],
+        }),
+      {} as Partial<ObservedAppState>,
+    );
+  }
+
   public isEmpty() {
-    return this.meta.isEmpty;
+    return this.metadata.isEmpty;
   }
 
   /**
@@ -303,8 +566,16 @@ export class Snapshot {
   public maybeClone(
     elements: Map<string, OrderedExcalidrawElement> | undefined,
     appState: AppState | ObservedAppState | undefined,
+    options: {
+      shouldIgnoreCache: boolean;
+    } = {
+      shouldIgnoreCache: false,
+    },
   ) {
-    const nextElementsSnapshot = this.maybeCreateElementsSnapshot(elements);
+    const nextElementsSnapshot = this.maybeCreateElementsSnapshot(
+      elements,
+      options,
+    );
     const nextAppStateSnapshot = this.maybeCreateAppStateSnapshot(appState);
 
     let didElementsChange = false;
@@ -322,10 +593,14 @@ export class Snapshot {
       return this;
     }
 
-    const snapshot = new Snapshot(nextElementsSnapshot, nextAppStateSnapshot, {
-      didElementsChange,
-      didAppStateChange,
-    });
+    const snapshot = new StoreSnapshot(
+      nextElementsSnapshot,
+      nextAppStateSnapshot,
+      {
+        didElementsChange,
+        didAppStateChange,
+      },
+    );
 
     return snapshot;
   }
@@ -352,26 +627,29 @@ export class Snapshot {
   }
 
   private detectChangedAppState(nextObservedAppState: ObservedAppState) {
-    return !isShallowEqual(this.appState, nextObservedAppState, {
-      selectedElementIds: isShallowEqual,
-      selectedGroupIds: isShallowEqual,
-    });
+    // CFDO: could we optimize by checking only reference changes? (i.e. selectedElementIds should be stable now); this is not used for now
+    return Delta.isRightDifferent(this.appState, nextObservedAppState);
   }
 
   private maybeCreateElementsSnapshot(
     elements: Map<string, OrderedExcalidrawElement> | undefined,
+    options: {
+      shouldIgnoreCache: boolean;
+    } = {
+      shouldIgnoreCache: false,
+    },
   ) {
     if (!elements) {
       return this.elements;
     }
 
-    const didElementsChange = this.detectChangedElements(elements);
+    const changedElements = this.detectChangedElements(elements, options);
 
-    if (!didElementsChange) {
+    if (!changedElements?.size) {
       return this.elements;
     }
 
-    const elementsSnapshot = this.createElementsSnapshot(elements);
+    const elementsSnapshot = this.createElementsSnapshot(changedElements);
     return elementsSnapshot;
   }
 
@@ -382,68 +660,87 @@ export class Snapshot {
    */
   private detectChangedElements(
     nextElements: Map<string, OrderedExcalidrawElement>,
+    options: {
+      shouldIgnoreCache: boolean;
+    } = {
+      shouldIgnoreCache: false,
+    },
   ) {
     if (this.elements === nextElements) {
-      return false;
+      return;
     }
 
-    if (this.elements.size !== nextElements.size) {
-      return true;
-    }
+    const changedElements: Map<string, OrderedExcalidrawElement> = new Map();
 
-    // loop from right to left as changes are likelier to happen on new elements
-    const keys = Array.from(nextElements.keys());
+    for (const [id, prevElement] of this.elements) {
+      const nextElement = nextElements.get(id);
 
-    for (let i = keys.length - 1; i >= 0; i--) {
-      const prev = this.elements.get(keys[i]);
-      const next = nextElements.get(keys[i]);
-      if (
-        !prev ||
-        !next ||
-        prev.id !== next.id ||
-        prev.versionNonce !== next.versionNonce
-      ) {
-        return true;
-      }
-    }
-
-    return false;
-  }
-
-  /**
-   * Perform structural clone, cloning only elements that changed.
-   */
-  private createElementsSnapshot(
-    nextElements: Map<string, OrderedExcalidrawElement>,
-  ) {
-    const clonedElements = new Map();
-
-    for (const [id, prevElement] of this.elements.entries()) {
-      // Clone previous elements, never delete, in case nextElements would be just a subset of previous elements
-      // i.e. during collab, persist or whenenever isDeleted elements get cleared
-      if (!nextElements.get(id)) {
-        // When we cannot find the prev element in the next elements, we mark it as deleted
-        clonedElements.set(
+      if (!nextElement) {
+        // element was deleted
+        changedElements.set(
           id,
           newElementWith(prevElement, { isDeleted: true }),
         );
-      } else {
-        clonedElements.set(id, prevElement);
       }
     }
 
-    for (const [id, nextElement] of nextElements.entries()) {
-      const prevElement = clonedElements.get(id);
+    for (const [id, nextElement] of nextElements) {
+      const prevElement = this.elements.get(id);
 
-      // At this point our elements are reconcilled already, meaning the next element is always newer
       if (
         !prevElement || // element was added
-        (prevElement && prevElement.versionNonce !== nextElement.versionNonce) // element was updated
+        prevElement.version < nextElement.version // element was updated
       ) {
-        clonedElements.set(id, deepCopyElement(nextElement));
+        changedElements.set(id, nextElement);
       }
     }
 
+    if (!changedElements.size) {
+      return;
+    }
+
+    // if we wouldn't ignore a cache, durable increment would be skipped
+    // in case there was an ephemeral increment emitter just before
+    // with the same changed elements
+    if (options.shouldIgnoreCache) {
+      return changedElements;
+    }
+
+    // due to snapshot containing only durable changes,
+    // we might have already processed these elements in a previous run,
+    // hence additionally check whether the hash of the elements has changed
+    // since if it didn't, we don't need to process them again
+    // otherwise we would have ephemeral increments even for component updates unrelated to elements
+    const changedElementsHash = hashElementsVersion(
+      Array.from(changedElements.values()),
+    );
+
+    if (this._lastChangedElementsHash === changedElementsHash) {
+      return;
+    }
+
+    this._lastChangedElementsHash = changedElementsHash;
+    return changedElements;
+  }
+
+  /**
+   * Perform structural clone, deep cloning only elements that changed.
+   */
+  private createElementsSnapshot(
+    changedElements: Map<string, OrderedExcalidrawElement>,
+  ) {
+    const clonedElements = new Map();
+
+    for (const [id, prevElement] of this.elements) {
+      // Clone previous elements, never delete, in case nextElements would be just a subset of previous elements
+      // i.e. during collab, persist or whenenever isDeleted elements get cleared
+      clonedElements.set(id, prevElement);
+    }
+
+    for (const [id, changedElement] of changedElements) {
+      clonedElements.set(id, deepCopyElement(changedElement));
+    }
+
     return clonedElements;
   }
 }

packages/excalidraw/subset/harfbuzz/harfbuzz-loader.ts

@@ -26,7 +26,7 @@ const load = (): Promise<{
     try {
       const module = await WebAssembly.instantiate(binary);
       const harfbuzzJsWasm = module.instance.exports;
-      // @ts-expect-error since `.buffer` is custom prop
+      // @ts-expect-error
       const heapu8 = new Uint8Array(harfbuzzJsWasm.memory.buffer);
 
       const hbSubset = {

packages/excalidraw/tests/history.test.tsx

@@ -45,12 +45,12 @@ import {
 } from "../actions";
 import { createUndoAction, createRedoAction } from "../actions/actionHistory";
 import { actionToggleViewMode } from "../actions/actionToggleViewMode";
+import { CaptureUpdateAction, StoreDelta } from "../store";
 import { getDefaultAppState } from "../appState";
-import { HistoryEntry } from "../history";
 import { Excalidraw } from "../index";
 import * as StaticScene from "../renderer/staticScene";
-import { Snapshot, CaptureUpdateAction } from "../store";
-import { AppStateChange, ElementsChange } from "../change";
+
+import { ElementsDelta, AppStateDelta } from "../delta.js";
 
 import { API } from "./helpers/api";
 import { Keyboard, Pointer, UI } from "./helpers/ui";
@@ -82,13 +82,52 @@ const checkpoint = (name: string) => {
     ...strippedAppState
   } = h.state;
   expect(strippedAppState).toMatchSnapshot(`[${name}] appState`);
-  expect(h.history).toMatchSnapshot(`[${name}] history`);
   expect(h.elements.length).toMatchSnapshot(`[${name}] number of elements`);
   h.elements
     .map(({ seed, versionNonce, ...strippedElement }) => strippedElement)
     .forEach((element, i) =>
       expect(element).toMatchSnapshot(`[${name}] element ${i}`),
     );
+
+  const stripSeed = (deltas: Record<string, { deleted: any; inserted: any }>) =>
+    Object.entries(deltas).reduce((acc, curr) => {
+      const { inserted, deleted, ...rest } = curr[1];
+
+      delete inserted.seed;
+      delete deleted.seed;
+
+      acc[curr[0]] = {
+        inserted,
+        deleted,
+        ...rest,
+      };
+
+      return acc;
+    }, {} as Record<string, any>);
+
+  expect(
+    h.history.undoStack.map((x) => ({
+      ...x,
+      elementsChange: {
+        ...x.elements,
+        added: stripSeed(x.elements.added),
+        removed: stripSeed(x.elements.updated),
+        updated: stripSeed(x.elements.removed),
+      },
+    })),
+  ).toMatchSnapshot(`[${name}] undo stack`);
+
+  expect(
+    h.history.redoStack.map((x) => ({
+      ...x,
+      elementsChange: {
+        ...x.elements,
+        added: stripSeed(x.elements.added),
+        removed: stripSeed(x.elements.updated),
+        updated: stripSeed(x.elements.removed),
+      },
+    })),
+  ).toMatchSnapshot(`[${name}] redo stack`);
 };
 
 const renderStaticScene = vi.spyOn(StaticScene, "renderStaticScene");
@@ -116,12 +155,12 @@ describe("history", () => {
 
       API.setElements([rect]);
 
-      const corrupedEntry = HistoryEntry.create(
-        AppStateChange.empty(),
-        ElementsChange.empty(),
+      const corrupedEntry = StoreDelta.create(
+        ElementsDelta.empty(),
+        AppStateDelta.empty(),
       );
 
-      vi.spyOn(corrupedEntry, "applyTo").mockImplementation(() => {
+      vi.spyOn(corrupedEntry.elements, "applyTo").mockImplementation(() => {
         throw new Error("Oh no, I am corrupted!");
       });
 
@@ -136,7 +175,6 @@ describe("history", () => {
             h.history.undo(
               arrayToMap(h.elements) as SceneElementsMap,
               appState,
-              Snapshot.empty(),
             ) as any,
         );
       } catch (e) {
@@ -157,7 +195,6 @@ describe("history", () => {
             h.history.redo(
               arrayToMap(h.elements) as SceneElementsMap,
               appState,
-              Snapshot.empty(),
             ) as any,
         );
       } catch (e) {
@@ -454,8 +491,8 @@ describe("history", () => {
         expect(h.history.isUndoStackEmpty).toBeTruthy();
       });
 
-      const undoAction = createUndoAction(h.history, h.store);
-      const redoAction = createRedoAction(h.history, h.store);
+      const undoAction = createUndoAction(h.history);
+      const redoAction = createRedoAction(h.history);
       // noop
       API.executeAction(undoAction);
       expect(h.elements).toEqual([
@@ -531,8 +568,8 @@ describe("history", () => {
         expect.objectContaining({ id: "B", isDeleted: false }),
       ]);
 
-      const undoAction = createUndoAction(h.history, h.store);
-      const redoAction = createRedoAction(h.history, h.store);
+      const undoAction = createUndoAction(h.history);
+      const redoAction = createRedoAction(h.history);
       API.executeAction(undoAction);
 
       expect(API.getSnapshot()).toEqual([
@@ -1713,8 +1750,8 @@ describe("history", () => {
         />,
       );
 
-      const undoAction = createUndoAction(h.history, h.store);
-      const redoAction = createRedoAction(h.history, h.store);
+      const undoAction = createUndoAction(h.history);
+      const redoAction = createRedoAction(h.history);
 
       await waitFor(() => {
         expect(h.elements).toEqual([expect.objectContaining({ id: "A" })]);
@@ -1763,7 +1800,7 @@ describe("history", () => {
         />,
       );
 
-      const undoAction = createUndoAction(h.history, h.store);
+      const undoAction = createUndoAction(h.history);
 
       await waitFor(() => {
         expect(h.elements).toEqual([expect.objectContaining({ id: "A" })]);
@@ -3500,7 +3537,7 @@ describe("history", () => {
           expect(h.elements).toEqual([
             expect.objectContaining({
               id: container.id,
-              // rebound the text as we captured the full bidirectional binding in history!
+              // rebound the text as we recorded the full bidirectional binding in history!
               boundElements: [{ id: text.id, type: "text" }],
               isDeleted: false,
             }),

packages/excalidraw/types.ts

@@ -51,7 +51,11 @@ import type Library from "./data/library";
 import type { FileSystemHandle } from "./data/filesystem";
 import type { ContextMenuItems } from "./components/ContextMenu";
 import type { SnapLine } from "./snapping";
-import type { CaptureUpdateActionType } from "./store";
+import type {
+  CaptureUpdateActionType,
+  DurableStoreIncrement,
+  EphemeralStoreIncrement,
+} from "./store";
 import type { ImportedDataState } from "./data/types";
 
 import type { Language } from "./i18n";
@@ -518,6 +522,9 @@ export interface ExcalidrawProps {
     appState: AppState,
     files: BinaryFiles,
   ) => void;
+  onIncrement?: (
+    event: DurableStoreIncrement | EphemeralStoreIncrement,
+  ) => void;
   initialData?:
     | (() => MaybePromise<ExcalidrawInitialDataState | null>)
     | MaybePromise<ExcalidrawInitialDataState | null>;
@@ -793,6 +800,7 @@ export interface ExcalidrawImperativeAPI {
   history: {
     clear: InstanceType<typeof App>["resetHistory"];
   };
+  store: InstanceType<typeof App>["store"];
   getSceneElements: InstanceType<typeof App>["getSceneElements"];
   getAppState: () => InstanceType<typeof App>["state"];
   getFiles: () => InstanceType<typeof App>["files"];
@@ -820,6 +828,9 @@ export interface ExcalidrawImperativeAPI {
       files: BinaryFiles,
     ) => void,
   ) => UnsubscribeCallback;
+  onIncrement: (
+    callback: (event: DurableStoreIncrement | EphemeralStoreIncrement) => void,
+  ) => UnsubscribeCallback;
   onPointerDown: (
     callback: (
       activeTool: AppState["activeTool"],

scripts/buildShared.js

@@ -0,0 +1,39 @@
+const fs = require("fs");
+const { build } = require("esbuild");
+
+const rawConfig = {
+  entryPoints: ["src/index.ts"],
+  bundle: true,
+  format: "esm",
+  metafile: true,
+  treeShaking: true,
+  external: ["*.scss"],
+};
+
+const createESMRawBuild = async () => {
+  // Development unminified build with source maps
+  const dev = await build({
+    ...rawConfig,
+    outdir: "dist/dev",
+    sourcemap: true,
+    define: {
+      "import.meta.env": JSON.stringify({ DEV: true }),
+    },
+  });
+
+  fs.writeFileSync("meta-dev.json", JSON.stringify(dev.metafile));
+
+  // production minified build without sourcemaps
+  const prod = await build({
+    ...rawConfig,
+    outdir: "dist/prod",
+    minify: true,
+    define: {
+      "import.meta.env": JSON.stringify({ PROD: true }),
+    },
+  });
+
+  fs.writeFileSync("meta-prod.json", JSON.stringify(prod.metafile));
+};
+
+createESMRawBuild();

yarn.lock

@@ -4049,6 +4049,11 @@ chrome-trace-event@^1.0.2:
   resolved "https://registry.yarnpkg.com/chrome-trace-event/-/chrome-trace-event-1.0.4.tgz#05bffd7ff928465093314708c93bdfa9bd1f0f5b"
   integrity sha512-rNjApaLzuwaOTjCiT8lSDdGN1APCiqkChLMJxJPWLunPAt5fy8xgU9/jNOchV84wfIxrA0lRQB7oCT8jrn/wrQ==
 
+classnames@^2.2.5:
+  version "2.5.1"
+  resolved "https://registry.yarnpkg.com/classnames/-/classnames-2.5.1.tgz#ba774c614be0f016da105c858e7159eae8e7687b"
+  integrity sha512-saHYOzhIQs6wy2sVxTM6bUDsQO4F50V9RQ22qBpEdCW+I+/Wmke2HOl6lS6dTpdxVhb88/I6+Hs+438c3lfUow==
+
 clean-css@^5.2.2:
   version "5.3.3"
   resolved "https://registry.yarnpkg.com/clean-css/-/clean-css-5.3.3.tgz#b330653cd3bd6b75009cc25c714cae7b93351ccd"
@@ -7400,6 +7405,11 @@ nanoid@4.0.2:
   resolved "https://registry.yarnpkg.com/nanoid/-/nanoid-4.0.2.tgz#140b3c5003959adbebf521c170f282c5e7f9fb9e"
   integrity sha512-7ZtY5KTCNheRGfEFxnedV5zFiORN1+Y1N6zvPTnHQd8ENUvfaDBeuJDZb2bN/oXwXxu3qkTXDzy57W5vAmDTBw==
 
+nanoid@5.0.9:
+  version "5.0.9"
+  resolved "https://registry.yarnpkg.com/nanoid/-/nanoid-5.0.9.tgz#977dcbaac055430ce7b1e19cf0130cea91a20e50"
+  integrity sha512-Aooyr6MXU6HpvvWXKoVoXwKMs/KyVakWwg7xQfv5/S/RIgJMy0Ifa45H9qqYy7pTCszrHzP21Uk4PZq2HpEM8Q==
+
 nanoid@^3.3.2:
   version "3.3.9"
   resolved "https://registry.yarnpkg.com/nanoid/-/nanoid-3.3.9.tgz#e0097d8e026b3343ff053e9ccd407360a03f503a"
@@ -8062,6 +8072,23 @@ randombytes@^2.1.0:
   dependencies:
     safe-buffer "^5.1.0"
 
+rc-slider@11.1.7:
+  version "11.1.7"
+  resolved "https://registry.yarnpkg.com/rc-slider/-/rc-slider-11.1.7.tgz#3de333b1ec84d53a7bda2f816bb4779423628f09"
+  integrity sha512-ytYbZei81TX7otdC0QvoYD72XSlxvTihNth5OeZ6PMXyEDq/vHdWFulQmfDGyXK1NwKwSlKgpvINOa88uT5g2A==
+  dependencies:
+    "@babel/runtime" "^7.10.1"
+    classnames "^2.2.5"
+    rc-util "^5.36.0"
+
+rc-util@^5.36.0:
+  version "5.43.0"
+  resolved "https://registry.yarnpkg.com/rc-util/-/rc-util-5.43.0.tgz#bba91fbef2c3e30ea2c236893746f3e9b05ecc4c"
+  integrity sha512-AzC7KKOXFqAdIBqdGWepL9Xn7cm3vnAmjlHqUnoQaTMZYhM4VlXGLkkHHxj/BZ7Td0+SOPKB4RGPboBVKT9htw==
+  dependencies:
+    "@babel/runtime" "^7.18.3"
+    react-is "^18.2.0"
+
 react-dom@19.0.0:
   version "19.0.0"
   resolved "https://registry.yarnpkg.com/react-dom/-/react-dom-19.0.0.tgz#43446f1f01c65a4cd7f7588083e686a6726cfb57"
@@ -8079,7 +8106,7 @@ react-is@^17.0.1:
   resolved "https://registry.yarnpkg.com/react-is/-/react-is-17.0.2.tgz#e691d4a8e9c789365655539ab372762b0efb54f0"
   integrity sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==
 
-react-is@^18.0.0:
+react-is@^18.0.0, react-is@^18.2.0:
   version "18.3.1"
   resolved "https://registry.yarnpkg.com/react-is/-/react-is-18.3.1.tgz#e83557dc12eae63a99e003a46388b1dcbb44db7e"
   integrity sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==
@@ -8364,6 +8391,16 @@ roughjs@4.6.4:
     points-on-curve "^0.2.0"
     points-on-path "^0.2.1"
 
+roughjs@4.6.6:
+  version "4.6.6"
+  resolved "https://registry.yarnpkg.com/roughjs/-/roughjs-4.6.6.tgz#1059f49a5e0c80dee541a005b20cc322b222158b"
+  integrity sha512-ZUz/69+SYpFN/g/lUlo2FXcIjRkSu3nDarreVdGGndHEBJ6cXPdKguS8JGxwj5HA5xIbVKSmLgr5b3AWxtRfvQ==
+  dependencies:
+    hachure-fill "^0.5.2"
+    path-data-parser "^0.1.0"
+    points-on-curve "^0.2.0"
+    points-on-path "^0.2.1"
+
 rrweb-cssom@^0.6.0:
   version "0.6.0"
   resolved "https://registry.yarnpkg.com/rrweb-cssom/-/rrweb-cssom-0.6.0.tgz#ed298055b97cbddcdeb278f904857629dec5e0e1"