feat: image support (#4011)

Co-authored-by: Emil Atanasov <heitara@gmail.com>
Co-authored-by: Aakansha Doshi <aakansha1216@gmail.com>

.eslintignore

 firebase/
 dist/
 public/workbox
+src/packages/excalidraw/types

package.json

     "@testing-library/react": "11.2.6",
     "@tldraw/vec": "0.0.106",
     "@types/jest": "26.0.22",
+    "@types/pica": "5.1.3",
     "@types/react": "17.0.3",
     "@types/react-dom": "17.0.3",
     "@types/socket.io-client": "1.4.36",
     "clsx": "1.1.1",
+    "fake-indexeddb": "3.1.3",
     "firebase": "8.3.3",
     "i18next-browser-languagedetector": "6.1.0",
+    "idb-keyval": "5.1.3",
+    "image-blob-reduce": "3.0.1",
     "lodash.throttle": "4.1.1",
     "nanoid": "3.1.22",
     "open-color": "1.8.0",

src/actions/actionCanvas.tsx

 
 export const actionClearCanvas = register({
   name: "clearCanvas",
-  perform: (elements, appState) => {
+  perform: (elements, appState, _, app) => {
+    app.imageCache.clear();
     return {
       elements: elements.map((element) =>
         newElementWith(element, { isDeleted: true }),
       ),
       appState: {
         ...getDefaultAppState(),
+        files: {},
         theme: appState.theme,
         elementLocked: appState.elementLocked,
         exportBackground: appState.exportBackground,

src/actions/actionClipboard.tsx

 
 export const actionCopy = register({
   name: "copy",
-  perform: (elements, appState) => {
-    copyToClipboard(getNonDeletedElements(elements), appState);
+  perform: (elements, appState, _, app) => {
+    copyToClipboard(getNonDeletedElements(elements), appState, app.files);
 
     return {
       commitToHistory: false,
           ? selectedElements
           : getNonDeletedElements(elements),
         appState,
+        app.files,
         appState,
       );
       return {
           ? selectedElements
           : getNonDeletedElements(elements),
         appState,
+        app.files,
         appState,
       );
       return {

src/actions/actionExport.tsx

 
 export const actionSaveToActiveFile = register({
   name: "saveToActiveFile",
-  perform: async (elements, appState, value) => {
+  perform: async (elements, appState, value, app) => {
     const fileHandleExists = !!appState.fileHandle;
 
     try {
       const { fileHandle } = isImageFileHandle(appState.fileHandle)
-        ? await resaveAsImageWithScene(elements, appState)
-        : await saveAsJSON(elements, appState);
+        ? await resaveAsImageWithScene(elements, appState, app.files)
+        : await saveAsJSON(elements, appState, app.files);
 
       return {
         commitToHistory: false,
 
 export const actionSaveFileToDisk = register({
   name: "saveFileToDisk",
-  perform: async (elements, appState, value) => {
+  perform: async (elements, appState, value, app) => {
     try {
-      const { fileHandle } = await saveAsJSON(elements, {
-        ...appState,
-        fileHandle: null,
-      });
+      const { fileHandle } = await saveAsJSON(
+        elements,
+        {
+          ...appState,
+          fileHandle: null,
+        },
+        app.files,
+      );
       return { commitToHistory: false, appState: { ...appState, fileHandle } };
     } catch (error) {
       if (error?.name !== "AbortError") {
 
 export const actionLoadScene = register({
   name: "loadScene",
-  perform: async (elements, appState) => {
+  perform: async (elements, appState, _, app) => {
     try {
       const {
         elements: loadedElements,
         appState: loadedAppState,
+        files,
       } = await loadFromJSON(appState, elements);
       return {
         elements: loadedElements,
         appState: loadedAppState,
+        files,
         commitToHistory: true,
       };
     } catch (error) {
       return {
         elements,
         appState: { ...appState, errorMessage: error.message },
+        files: app.files,
         commitToHistory: false,
       };
     }

src/actions/actionFinalize.tsx

     }
 
     let newElements = elements;
+
+    if (appState.pendingImageElement) {
+      mutateElement(appState.pendingImageElement, { isDeleted: true }, false);
+    }
+
     if (window.document.activeElement instanceof HTMLElement) {
       focusContainer();
     }
                 [multiPointElement.id]: true,
               }
             : appState.selectedElementIds,
+        pendingImageElement: null,
       },
       commitToHistory: appState.elementType === "freedraw",
     };

src/actions/actionFlip.ts

   appState: AppState,
   flipDirection: "horizontal" | "vertical",
 ): ExcalidrawElement[] => {
-  for (let i = 0; i < elements.length; i++) {
-    flipElement(elements[i], appState);
+  elements.forEach((element) => {
+    flipElement(element, appState);
     // If vertical flip, rotate an extra 180
     if (flipDirection === "vertical") {
-      rotateElement(elements[i], Math.PI);
+      rotateElement(element, Math.PI);
     }
-  }
+  });
   return elements;
 };
 

src/actions/actionProperties.tsx

   getTargetElements,
   isSomeElementSelected,
 } from "../scene";
+import { hasStrokeColor } from "../scene/comparisons";
 import { register } from "./register";
 
 const changeProperty = (
   perform: (elements, appState, value) => {
     return {
       ...(value.currentItemStrokeColor && {
-        elements: changeProperty(elements, appState, (el) =>
-          newElementWith(el, {
-            strokeColor: value.currentItemStrokeColor,
-          }),
-        ),
+        elements: changeProperty(elements, appState, (el) => {
+          return hasStrokeColor(el.type)
+            ? newElementWith(el, {
+                strokeColor: value.currentItemStrokeColor,
+              })
+            : el;
+        }),
       }),
       appState: {
         ...appState,

src/actions/manager.tsx

   PanelComponentProps,
 } from "./types";
 import { ExcalidrawElement } from "../element/types";
-import { AppProps, AppState } from "../types";
+import { AppClassProperties, AppState } from "../types";
 import { MODES } from "../constants";
-import Library from "../data/library";
-
-// This is the <App> component, but for now we don't care about anything but its
-// `canvas` state.
-type App = {
-  canvas: HTMLCanvasElement | null;
-  focusContainer: () => void;
-  props: AppProps;
-  library: Library;
-};
 
 export class ActionManager implements ActionsManagerInterface {
   actions = {} as ActionsManagerInterface["actions"];
 
   getAppState: () => Readonly<AppState>;
   getElementsIncludingDeleted: () => readonly ExcalidrawElement[];
-  app: App;
+  app: AppClassProperties;
 
   constructor(
     updater: UpdaterFn,
     getAppState: () => AppState,
     getElementsIncludingDeleted: () => readonly ExcalidrawElement[],
-    app: App,
+    app: AppClassProperties,
   ) {
     this.updater = (actionResult) => {
       if (actionResult && "then" in actionResult) {

src/actions/types.ts

 import React from "react";
 import { ExcalidrawElement } from "../element/types";
-import { AppState, ExcalidrawProps } from "../types";
-import Library from "../data/library";
+import {
+  AppClassProperties,
+  AppState,
+  ExcalidrawProps,
+  BinaryFiles,
+} from "../types";
 import { ToolButtonSize } from "../components/ToolButton";
 
 /** if false, the action should be prevented */
         AppState,
         "offsetTop" | "offsetLeft" | "width" | "height"
       > | null;
+      files?: BinaryFiles | null;
       commitToHistory: boolean;
       syncHistory?: boolean;
+      replaceFiles?: boolean;
     }
   | false;
 
-type AppAPI = {
-  canvas: HTMLCanvasElement | null;
-  focusContainer(): void;
-  library: Library;
-};
-
 type ActionFn = (
   elements: readonly ExcalidrawElement[],
   appState: Readonly<AppState>,
   formData: any,
-  app: AppAPI,
+  app: AppClassProperties,
 ) => ActionResult | Promise<ActionResult>;
 
 export type UpdaterFn = (res: ActionResult) => void;

src/appState.ts

     zenModeEnabled: false,
     zoom: { value: 1 as NormalizedZoomValue, translation: { x: 0, y: 0 } },
     viewModeEnabled: false,
+    pendingImageElement: null,
   };
 };
 
     browser: boolean;
     /** whether to keep when exporting to file/database */
     export: boolean;
+    /** server (shareLink/collab/...) */
+    server: boolean;
   },
   T extends Record<keyof AppState, Values>
 >(
   config: { [K in keyof T]: K extends keyof AppState ? T[K] : never },
 ) => config)({
-  theme: { browser: true, export: false },
-  collaborators: { browser: false, export: false },
-  currentChartType: { browser: true, export: false },
-  currentItemBackgroundColor: { browser: true, export: false },
-  currentItemEndArrowhead: { browser: true, export: false },
-  currentItemFillStyle: { browser: true, export: false },
-  currentItemFontFamily: { browser: true, export: false },
-  currentItemFontSize: { browser: true, export: false },
-  currentItemLinearStrokeSharpness: { browser: true, export: false },
-  currentItemOpacity: { browser: true, export: false },
-  currentItemRoughness: { browser: true, export: false },
-  currentItemStartArrowhead: { browser: true, export: false },
-  currentItemStrokeColor: { browser: true, export: false },
-  currentItemStrokeSharpness: { browser: true, export: false },
-  currentItemStrokeStyle: { browser: true, export: false },
-  currentItemStrokeWidth: { browser: true, export: false },
-  currentItemTextAlign: { browser: true, export: false },
-  cursorButton: { browser: true, export: false },
-  draggingElement: { browser: false, export: false },
-  editingElement: { browser: false, export: false },
-  editingGroupId: { browser: true, export: false },
-  editingLinearElement: { browser: false, export: false },
-  elementLocked: { browser: true, export: false },
-  elementType: { browser: true, export: false },
-  errorMessage: { browser: false, export: false },
-  exportBackground: { browser: true, export: false },
-  exportEmbedScene: { browser: true, export: false },
-  exportScale: { browser: true, export: false },
-  exportWithDarkMode: { browser: true, export: false },
-  fileHandle: { browser: false, export: false },
-  gridSize: { browser: true, export: true },
-  height: { browser: false, export: false },
-  isBindingEnabled: { browser: false, export: false },
-  isLibraryOpen: { browser: false, export: false },
-  isLoading: { browser: false, export: false },
-  isResizing: { browser: false, export: false },
-  isRotating: { browser: false, export: false },
-  lastPointerDownWith: { browser: true, export: false },
-  multiElement: { browser: false, export: false },
-  name: { browser: true, export: false },
-  offsetLeft: { browser: false, export: false },
-  offsetTop: { browser: false, export: false },
-  openMenu: { browser: true, export: false },
-  openPopup: { browser: false, export: false },
-  pasteDialog: { browser: false, export: false },
-  previousSelectedElementIds: { browser: true, export: false },
-  resizingElement: { browser: false, export: false },
-  scrolledOutside: { browser: true, export: false },
-  scrollX: { browser: true, export: false },
-  scrollY: { browser: true, export: false },
-  selectedElementIds: { browser: true, export: false },
-  selectedGroupIds: { browser: true, export: false },
-  selectionElement: { browser: false, export: false },
-  shouldCacheIgnoreZoom: { browser: true, export: false },
-  showHelpDialog: { browser: false, export: false },
-  showStats: { browser: true, export: false },
-  startBoundElement: { browser: false, export: false },
-  suggestedBindings: { browser: false, export: false },
-  toastMessage: { browser: false, export: false },
-  viewBackgroundColor: { browser: true, export: true },
-  width: { browser: false, export: false },
-  zenModeEnabled: { browser: true, export: false },
-  zoom: { browser: true, export: false },
-  viewModeEnabled: { browser: false, export: false },
+  theme: { browser: true, export: false, server: false },
+  collaborators: { browser: false, export: false, server: false },
+  currentChartType: { browser: true, export: false, server: false },
+  currentItemBackgroundColor: { browser: true, export: false, server: false },
+  currentItemEndArrowhead: { browser: true, export: false, server: false },
+  currentItemFillStyle: { browser: true, export: false, server: false },
+  currentItemFontFamily: { browser: true, export: false, server: false },
+  currentItemFontSize: { browser: true, export: false, server: false },
+  currentItemLinearStrokeSharpness: {
+    browser: true,
+    export: false,
+    server: false,
+  },
+  currentItemOpacity: { browser: true, export: false, server: false },
+  currentItemRoughness: { browser: true, export: false, server: false },
+  currentItemStartArrowhead: { browser: true, export: false, server: false },
+  currentItemStrokeColor: { browser: true, export: false, server: false },
+  currentItemStrokeSharpness: { browser: true, export: false, server: false },
+  currentItemStrokeStyle: { browser: true, export: false, server: false },
+  currentItemStrokeWidth: { browser: true, export: false, server: false },
+  currentItemTextAlign: { browser: true, export: false, server: false },
+  cursorButton: { browser: true, export: false, server: false },
+  draggingElement: { browser: false, export: false, server: false },
+  editingElement: { browser: false, export: false, server: false },
+  editingGroupId: { browser: true, export: false, server: false },
+  editingLinearElement: { browser: false, export: false, server: false },
+  elementLocked: { browser: true, export: false, server: false },
+  elementType: { browser: true, export: false, server: false },
+  errorMessage: { browser: false, export: false, server: false },
+  exportBackground: { browser: true, export: false, server: false },
+  exportEmbedScene: { browser: true, export: false, server: false },
+  exportScale: { browser: true, export: false, server: false },
+  exportWithDarkMode: { browser: true, export: false, server: false },
+  fileHandle: { browser: false, export: false, server: false },
+  gridSize: { browser: true, export: true, server: true },
+  height: { browser: false, export: false, server: false },
+  isBindingEnabled: { browser: false, export: false, server: false },
+  isLibraryOpen: { browser: false, export: false, server: false },
+  isLoading: { browser: false, export: false, server: false },
+  isResizing: { browser: false, export: false, server: false },
+  isRotating: { browser: false, export: false, server: false },
+  lastPointerDownWith: { browser: true, export: false, server: false },
+  multiElement: { browser: false, export: false, server: false },
+  name: { browser: true, export: false, server: false },
+  offsetLeft: { browser: false, export: false, server: false },
+  offsetTop: { browser: false, export: false, server: false },
+  openMenu: { browser: true, export: false, server: false },
+  openPopup: { browser: false, export: false, server: false },
+  pasteDialog: { browser: false, export: false, server: false },
+  previousSelectedElementIds: { browser: true, export: false, server: false },
+  resizingElement: { browser: false, export: false, server: false },
+  scrolledOutside: { browser: true, export: false, server: false },
+  scrollX: { browser: true, export: false, server: false },
+  scrollY: { browser: true, export: false, server: false },
+  selectedElementIds: { browser: true, export: false, server: false },
+  selectedGroupIds: { browser: true, export: false, server: false },
+  selectionElement: { browser: false, export: false, server: false },
+  shouldCacheIgnoreZoom: { browser: true, export: false, server: false },
+  showHelpDialog: { browser: false, export: false, server: false },
+  showStats: { browser: true, export: false, server: false },
+  startBoundElement: { browser: false, export: false, server: false },
+  suggestedBindings: { browser: false, export: false, server: false },
+  toastMessage: { browser: false, export: false, server: false },
+  viewBackgroundColor: { browser: true, export: true, server: true },
+  width: { browser: false, export: false, server: false },
+  zenModeEnabled: { browser: true, export: false, server: false },
+  zoom: { browser: true, export: false, server: false },
+  viewModeEnabled: { browser: false, export: false, server: false },
+  pendingImageElement: { browser: false, export: false, server: false },
 });
 
-const _clearAppStateForStorage = <ExportType extends "export" | "browser">(
+const _clearAppStateForStorage = <
+  ExportType extends "export" | "browser" | "server"
+>(
   appState: Partial<AppState>,
   exportType: ExportType,
 ) => {
   for (const key of Object.keys(appState) as (keyof typeof appState)[]) {
     const propConfig = APP_STATE_STORAGE_CONF[key];
     if (propConfig?.[exportType]) {
-      // @ts-ignore see https://github.com/microsoft/TypeScript/issues/31445
-      stateForExport[key] = appState[key];
+      const nextValue = appState[key];
+
+      // https://github.com/microsoft/TypeScript/issues/31445
+      (stateForExport as any)[key] = nextValue;
     }
   }
   return stateForExport;
 export const cleanAppStateForExport = (appState: Partial<AppState>) => {
   return _clearAppStateForStorage(appState, "export");
 };
+
+export const clearAppStateForDatabase = (appState: Partial<AppState>) => {
+  return _clearAppStateForStorage(appState, "server");
+};

src/clipboard.ts

   NonDeletedExcalidrawElement,
 } from "./element/types";
 import { getSelectedElements } from "./scene";
-import { AppState } from "./types";
+import { AppState, BinaryFiles } from "./types";
 import { SVG_EXPORT_TAG } from "./scene/export";
 import { tryParseSpreadsheet, Spreadsheet, VALID_SPREADSHEET } from "./charts";
-import { EXPORT_DATA_TYPES } from "./constants";
+import { EXPORT_DATA_TYPES, MIME_TYPES } from "./constants";
+import { isInitializedImageElement } from "./element/typeChecks";
 
 type ElementsClipboard = {
   type: typeof EXPORT_DATA_TYPES.excalidrawClipboard;
   elements: ExcalidrawElement[];
+  files: BinaryFiles | undefined;
 };
 
 export interface ClipboardData {
   spreadsheet?: Spreadsheet;
   elements?: readonly ExcalidrawElement[];
+  files?: BinaryFiles;
   text?: string;
   errorMessage?: string;
 }
 
 const clipboardContainsElements = (
   contents: any,
-): contents is { elements: ExcalidrawElement[] } => {
+): contents is { elements: ExcalidrawElement[]; files?: BinaryFiles } => {
   if (
     [
       EXPORT_DATA_TYPES.excalidraw,
 export const copyToClipboard = async (
   elements: readonly NonDeletedExcalidrawElement[],
   appState: AppState,
+  files: BinaryFiles,
 ) => {
+  const selectedElements = getSelectedElements(elements, appState);
   const contents: ElementsClipboard = {
     type: EXPORT_DATA_TYPES.excalidrawClipboard,
-    elements: getSelectedElements(elements, appState),
+    elements: selectedElements,
+    files: selectedElements.reduce((acc, element) => {
+      if (isInitializedImageElement(element) && files[element.fileId]) {
+        acc[element.fileId] = files[element.fileId];
+      }
+      return acc;
+    }, {} as BinaryFiles),
   };
   const json = JSON.stringify(contents);
   CLIPBOARD = json;
   try {
     const systemClipboardData = JSON.parse(systemClipboard);
     if (clipboardContainsElements(systemClipboardData)) {
-      return { elements: systemClipboardData.elements };
+      return {
+        elements: systemClipboardData.elements,
+        files: systemClipboardData.files,
+      };
     }
     return appClipboardData;
   } catch {
 
 export const copyBlobToClipboardAsPng = async (blob: Blob) => {
   await navigator.clipboard.write([
-    new window.ClipboardItem({ "image/png": blob }),
+    new window.ClipboardItem({ [MIME_TYPES.png]: blob }),
   ]);
 };
 

src/components/Actions.tsx

 import React from "react";
 import { ActionManager } from "../actions/manager";
 import { getNonDeletedElements } from "../element";
-import { ExcalidrawElement } from "../element/types";
+import { ExcalidrawElement, PointerType } from "../element/types";
 import { t } from "../i18n";
 import { useIsMobile } from "../components/App";
 import {
 import { capitalizeString, isTransparent, setCursorForShape } from "../utils";
 import Stack from "./Stack";
 import { ToolButton } from "./ToolButton";
+import { hasStrokeColor } from "../scene/comparisons";
 
 export const SelectedShapeActions = ({
   appState,
     hasBackground(elementType) ||
     targetElements.some((element) => hasBackground(element.type));
 
+  let commonSelectedType: string | null = targetElements[0]?.type || null;
+
+  for (const element of targetElements) {
+    if (element.type !== commonSelectedType) {
+      commonSelectedType = null;
+      break;
+    }
+  }
+
   return (
     <div className="panelColumn">
-      {renderAction("changeStrokeColor")}
+      {((hasStrokeColor(elementType) &&
+        elementType !== "image" &&
+        commonSelectedType !== "image") ||
+        targetElements.some((element) => hasStrokeColor(element.type))) &&
+        renderAction("changeStrokeColor")}
       {showChangeBackgroundIcons && renderAction("changeBackgroundColor")}
       {showFillIcons && renderAction("changeFillStyle")}
 
   canvas,
   elementType,
   setAppState,
+  onImageAction,
 }: {
   canvas: HTMLCanvasElement | null;
   elementType: ExcalidrawElement["type"];
   setAppState: React.Component<any, AppState>["setState"];
+  onImageAction: (data: { pointerType: PointerType | null }) => void;
 }) => (
   <>
     {SHAPES.map(({ value, icon, key }, index) => {
       const label = t(`toolBar.${value}`);
-      const letter = typeof key === "string" ? key : key[0];
-      const shortcut = `${capitalizeString(letter)} ${t("helpDialog.or")} ${
-        index + 1
-      }`;
+      const letter = key && (typeof key === "string" ? key : key[0]);
+      const shortcut = letter
+        ? `${capitalizeString(letter)} ${t("helpDialog.or")} ${index + 1}`
+        : `${index + 1}`;
       return (
         <ToolButton
           className="Shape"
           aria-label={capitalizeString(label)}
           aria-keyshortcuts={shortcut}
           data-testid={value}
-          onChange={() => {
+          onChange={({ pointerType }) => {
             setAppState({
               elementType: value,
               multiElement: null,
               selectedElementIds: {},
             });
             setCursorForShape(canvas, value);
-            setAppState({});
+            if (value === "image") {
+              onImageAction({ pointerType });
+            }
           }}
         />
       );

src/components/Card.scss

       .ToolIcon__label {
         color: $oc-white;
       }
+
+      .Spinner {
+        --spinner-color: #fff;
+      }
     }
   }
 }

src/components/HelpDialog.tsx

                   shortcuts={["Shift+P", "7"]}
                 />
                 <Shortcut label={t("toolBar.text")} shortcuts={["T", "8"]} />
+                <Shortcut label={t("toolBar.image")} shortcuts={["9"]} />
+                <Shortcut label={t("toolBar.library")} shortcuts={["0"]} />
                 <Shortcut
                   label={t("helpDialog.editSelectedShape")}
                   shortcuts={[

src/components/HintViewer.tsx

 
 import "./HintViewer.scss";
 import { AppState } from "../types";
-import { isLinearElement, isTextElement } from "../element/typeChecks";
+import {
+  isImageElement,
+  isLinearElement,
+  isTextElement,
+} from "../element/typeChecks";
 import { getShortcutKey } from "../utils";
 
 interface Hint {
     return t("hints.text");
   }
 
+  if (appState.elementType === "image" && appState.pendingImageElement) {
+    return t("hints.placeImage");
+  }
+
   const selectedElements = getSelectedElements(elements, appState);
   if (
     isResizing &&
     if (isLinearElement(targetElement) && targetElement.points.length === 2) {
       return t("hints.lockAngle");
     }
-    return t("hints.resize");
+    return isImageElement(targetElement)
+      ? t("hints.resizeImage")
+      : t("hints.resize");
   }
 
   if (isRotating && lastPointerDownWith === "mouse") {

src/components/ImageExportDialog.tsx

 import { useIsMobile } from "./App";
 import { getSelectedElements, isSomeElementSelected } from "../scene";
 import { exportToCanvas } from "../scene/export";
-import { AppState } from "../types";
+import { AppState, BinaryFiles } from "../types";
 import { Dialog } from "./Dialog";
 import { clipboard, exportImage } from "./icons";
 import Stack from "./Stack";
 const ImageExportModal = ({
   elements,
   appState,
+  files,
   exportPadding = DEFAULT_EXPORT_PADDING,
   actionManager,
   onExportToPng,
 }: {
   appState: AppState;
   elements: readonly NonDeletedExcalidrawElement[];
+  files: BinaryFiles;
   exportPadding?: number;
   actionManager: ActionsManagerInterface;
   onExportToPng: ExportCB;
     if (!previewNode) {
       return;
     }
-    try {
-      const canvas = exportToCanvas(exportedElements, appState, {
-        exportBackground,
-        viewBackgroundColor,
-        exportPadding,
-      });
-
-      // if converting to blob fails, there's some problem that will
-      // likely prevent preview and export (e.g. canvas too big)
-      canvasToBlob(canvas)
-        .then(() => {
+    exportToCanvas(exportedElements, appState, files, {
+      exportBackground,
+      viewBackgroundColor,
+      exportPadding,
+    })
+      .then((canvas) => {
+        // if converting to blob fails, there's some problem that will
+        // likely prevent preview and export (e.g. canvas too big)
+        return canvasToBlob(canvas).then(() => {
           renderPreview(canvas, previewNode);
-        })
-        .catch((error) => {
-          console.error(error);
-          renderPreview(new CanvasError(), previewNode);
         });
-    } catch (error) {
-      console.error(error);
-      renderPreview(new CanvasError(), previewNode);
-    }
+      })
+      .catch((error) => {
+        console.error(error);
+        renderPreview(new CanvasError(), previewNode);
+      });
   }, [
     appState,
+    files,
     exportedElements,
     exportBackground,
     exportPadding,
 export const ImageExportDialog = ({
   elements,
   appState,
+  files,
   exportPadding = DEFAULT_EXPORT_PADDING,
   actionManager,
   onExportToPng,
 }: {
   appState: AppState;
   elements: readonly NonDeletedExcalidrawElement[];
+  files: BinaryFiles;
   exportPadding?: number;
   actionManager: ActionsManagerInterface;
   onExportToPng: ExportCB;
           <ImageExportModal
             elements={elements}
             appState={appState}
+            files={files}
             exportPadding={exportPadding}
             actionManager={actionManager}
             onExportToPng={onExportToPng}

src/components/JSONExportDialog.tsx

 import { NonDeletedExcalidrawElement } from "../element/types";
 import { t } from "../i18n";
 import { useIsMobile } from "./App";
-import { AppState, ExportOpts } from "../types";
+import { AppState, ExportOpts, BinaryFiles } from "../types";
 import { Dialog } from "./Dialog";
 import { exportFile, exportToFileIcon, link } from "./icons";
 import { ToolButton } from "./ToolButton";
 const JSONExportModal = ({
   elements,
   appState,
+  files,
   actionManager,
   exportOpts,
   canvas,
 }: {
   appState: AppState;
+  files: BinaryFiles;
   elements: readonly NonDeletedExcalidrawElement[];
   actionManager: ActionsManagerInterface;
   onCloseRequest: () => void;
               title={t("exportDialog.link_button")}
               aria-label={t("exportDialog.link_button")}
               showAriaLabel={true}
-              onClick={() => onExportToBackend(elements, appState, canvas)}
+              onClick={() =>
+                onExportToBackend(elements, appState, files, canvas)
+              }
             />
           </Card>
         )}
         {exportOpts.renderCustomUI &&
-          exportOpts.renderCustomUI(elements, appState, canvas)}
+          exportOpts.renderCustomUI(elements, appState, files, canvas)}
       </div>
     </div>
   );
 export const JSONExportDialog = ({
   elements,
   appState,
+  files,
   actionManager,
   exportOpts,
   canvas,
 }: {
-  appState: AppState;
   elements: readonly NonDeletedExcalidrawElement[];
+  appState: AppState;
+  files: BinaryFiles;
   actionManager: ActionsManagerInterface;
   exportOpts: ExportOpts;
   canvas: HTMLCanvasElement | null;
           <JSONExportModal
             elements={elements}
             appState={appState}
+            files={files}
             actionManager={actionManager}
             onCloseRequest={handleClose}
             exportOpts={exportOpts}

src/components/LayerUI.tsx

   AppProps,
   AppState,
   ExcalidrawProps,
+  BinaryFiles,
   LibraryItem,
   LibraryItems,
 } from "../types";
 interface LayerUIProps {
   actionManager: ActionManager;
   appState: AppState;
+  files: BinaryFiles;
   canvas: HTMLCanvasElement | null;
   setAppState: React.Component<any, AppState>["setState"];
   elements: readonly NonDeletedExcalidrawElement[];
   focusContainer: () => void;
   library: Library;
   id: string;
+  onImageAction: (data: { insertOnCanvasDirectly: boolean }) => void;
 }
 
 const useOnClickOutside = (
   libraryReturnUrl,
   focusContainer,
   library,
+  files,
   id,
 }: {
   libraryItems: LibraryItems;
   onInsertShape: (elements: LibraryItem) => void;
   onAddToLibrary: (elements: LibraryItem) => void;
   theme: AppState["theme"];
+  files: BinaryFiles;
   setAppState: React.Component<any, AppState>["setState"];
   setLibraryItems: (library: LibraryItems) => void;
   libraryReturnUrl: ExcalidrawProps["libraryReturnUrl"];
         <Stack.Col key={x}>
           <LibraryUnit
             elements={libraryItems[y + x]}
+            files={files}
             pendingElements={
               shouldAddPendingElements ? pendingElements : undefined
             }
   onAddToLibrary,
   theme,
   setAppState,
+  files,
   libraryReturnUrl,
   focusContainer,
   library,
   onInsertShape: (elements: LibraryItem) => void;
   onAddToLibrary: () => void;
   theme: AppState["theme"];
+  files: BinaryFiles;
   setAppState: React.Component<any, AppState>["setState"];
   libraryReturnUrl: ExcalidrawProps["libraryReturnUrl"];
   focusContainer: () => void;
     "preloading" | "loading" | "ready"
   >("preloading");
 
-  const loadingTimerRef = useRef<NodeJS.Timeout | null>(null);
+  const loadingTimerRef = useRef<number | null>(null);
 
   useEffect(() => {
     Promise.race([
       new Promise((resolve) => {
-        loadingTimerRef.current = setTimeout(() => {
+        loadingTimerRef.current = window.setTimeout(() => {
           resolve("loading");
         }, 100);
       }),
 
   const addToLibrary = useCallback(
     async (elements: LibraryItem) => {
+      if (elements.some((element) => element.type === "image")) {
+        return setAppState({
+          errorMessage: "Support for adding images to the library coming soon!",
+        });
+      }
+
       const items = await library.loadLibrary();
       const nextItems = [...items, elements];
       onAddToLibrary();
           focusContainer={focusContainer}
           library={library}
           theme={theme}
+          files={files}
           id={id}
         />
       )}
 const LayerUI = ({
   actionManager,
   appState,
+  files,
   setAppState,
   canvas,
   elements,
   focusContainer,
   library,
   id,
+  onImageAction,
 }: LayerUIProps) => {
   const isMobile = useIsMobile();
 
       <JSONExportDialog
         elements={elements}
         appState={appState}
+        files={files}
         actionManager={actionManager}
         exportOpts={UIOptions.canvasActions.export}
         canvas={canvas}
     const createExporter = (type: ExportType): ExportCB => async (
       exportedElements,
     ) => {
-      const fileHandle = await exportCanvas(type, exportedElements, appState, {
-        exportBackground: appState.exportBackground,
-        name: appState.name,
-        viewBackgroundColor: appState.viewBackgroundColor,
-      })
+      const fileHandle = await exportCanvas(
+        type,
+        exportedElements,
+        appState,
+        files,
+        {
+          exportBackground: appState.exportBackground,
+          name: appState.name,
+          viewBackgroundColor: appState.viewBackgroundColor,
+        },
+      )
         .catch(muteFSAbortError)
         .catch((error) => {
           console.error(error);
       <ImageExportDialog
         elements={elements}
         appState={appState}
+        files={files}
         actionManager={actionManager}
         onExportToPng={createExporter("png")}
         onExportToSvg={createExporter("svg")}
       focusContainer={focusContainer}
       library={library}
       theme={appState.theme}
+      files={files}
       id={id}
     />
   ) : null;
                           canvas={canvas}
                           elementType={appState.elementType}
                           setAppState={setAppState}
+                          onImageAction={({ pointerType }) => {
+                            onImageAction({
+                              insertOnCanvasDirectly: pointerType !== "mouse",
+                            });
+                          }}
                         />
                       </Stack.Row>
                     </Island>
         renderCustomFooter={renderCustomFooter}
         viewModeEnabled={viewModeEnabled}
         showThemeBtn={showThemeBtn}
+        onImageAction={onImageAction}
         renderTopRightUI={renderTopRightUI}
       />
     </>

src/components/LibraryButton.tsx

           "zen-mode-visibility--hidden": appState.zenModeEnabled,
         },
       )}
-      title={`${capitalizeString(t("toolBar.library"))} — 9`}
+      title={`${capitalizeString(t("toolBar.library"))} — 0`}
       style={{ marginInlineStart: "var(--space-factor)" }}
     >
       <input
         }}
         checked={appState.isLibraryOpen}
         aria-label={capitalizeString(t("toolBar.library"))}
-        aria-keyshortcuts="9"
+        aria-keyshortcuts="0"
       />
       <div className="ToolIcon__icon">{LIBRARY_ICON}</div>
     </label>

src/components/LibraryUnit.tsx

 import { t } from "../i18n";
 import { useIsMobile } from "../components/App";
 import { exportToSvg } from "../scene/export";
-import { LibraryItem } from "../types";
+import { BinaryFiles, LibraryItem } from "../types";
 import "./LibraryUnit.scss";
 
 // fa-plus
 
 export const LibraryUnit = ({
   elements,
+  files,
   pendingElements,
   onRemoveFromLibrary,
   onClick,
 }: {
   elements?: LibraryItem;
+  files: BinaryFiles;
   pendingElements?: LibraryItem;
   onRemoveFromLibrary: () => void;
   onClick: () => void;
 }) => {
   const ref = useRef<HTMLDivElement | null>(null);
   useEffect(() => {
-    const elementsToRender = elements || pendingElements;
-    if (!elementsToRender) {
-      return;
-    }
-    let svg: SVGSVGElement;
-    const current = ref.current!;
-
     (async () => {
-      svg = await exportToSvg(elementsToRender, {
-        exportBackground: false,
-        viewBackgroundColor: oc.white,
-      });
-      for (const child of ref.current!.children) {
-        if (child.tagName !== "svg") {
-          continue;
-        }
-        current!.removeChild(child);
+      const elementsToRender = elements || pendingElements;
+      if (!elementsToRender) {
+        return;
       }
-      current!.appendChild(svg);
-    })();
-
-    return () => {
-      if (svg) {
-        current.removeChild(svg);
+      const svg = await exportToSvg(
+        elementsToRender,
+        {
+          exportBackground: false,
+          viewBackgroundColor: oc.white,
+        },
+        files,
+      );
+      if (ref.current) {
+        ref.current.innerHTML = svg.outerHTML;
       }
-    };
-  }, [elements, pendingElements]);
+    })();
+  }, [elements, pendingElements, files]);
 
   const [isHovered, setIsHovered] = useState(false);
   const isMobile = useIsMobile();

src/components/MobileMenu.tsx

   renderCustomFooter?: (isMobile: boolean, appState: AppState) => JSX.Element;
   viewModeEnabled: boolean;
   showThemeBtn: boolean;
+  onImageAction: (data: { insertOnCanvasDirectly: boolean }) => void;
   renderTopRightUI?: (
     isMobile: boolean,
     appState: AppState,
   renderCustomFooter,
   viewModeEnabled,
   showThemeBtn,
+  onImageAction,
   renderTopRightUI,
 }: MobileMenuProps) => {
   const renderToolbar = () => {
                       canvas={canvas}
                       elementType={appState.elementType}
                       setAppState={setAppState}
+                      onImageAction={({ pointerType }) => {
+                        onImageAction({
+                          insertOnCanvasDirectly: pointerType !== "mouse",
+                        });
+                      }}
                     />
                   </Stack.Row>
                 </Island>

src/components/PasteChartDialog.tsx

     const previewNode = previewRef.current!;
 
     (async () => {
-      svg = await exportToSvg(elements, {
-        exportBackground: false,
-        viewBackgroundColor: oc.white,
-      });
+      svg = await exportToSvg(
+        elements,
+        {
+          exportBackground: false,
+          viewBackgroundColor: oc.white,
+        },
+        null, // files
+      );
 
       previewNode.appendChild(svg);
 

src/components/Spinner.scss

+@import "open-color/open-color.scss";
+
+$duration: 1.6s;
+
+.excalidraw {
+  .Spinner {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    height: 100%;
+    margin-left: auto;
+    margin-right: auto;
+
+    --spinner-color: var(--icon-fill-color);
+
+    svg {
+      animation: rotate $duration linear infinite;
+      transform-origin: center center;
+    }
+
+    circle {
+      stroke: var(--spinner-color);
+      animation: dash $duration linear 0s infinite;
+      stroke-linecap: round;
+    }
+  }
+
+  @keyframes rotate {
+    100% {
+      transform: rotate(360deg);
+    }
+  }
+
+  @keyframes dash {
+    0% {
+      stroke-dasharray: 1, 300;
+      stroke-dashoffset: 0;
+    }
+    50% {
+      stroke-dasharray: 150, 300;
+      stroke-dashoffset: -200;
+    }
+    100% {
+      stroke-dasharray: 1, 300;
+      stroke-dashoffset: -280;
+    }
+  }
+}

src/components/Spinner.tsx

+import React from "react";
+
+import "./Spinner.scss";
+
+const Spinner = ({
+  size = "1em",
+  circleWidth = 8,
+}: {
+  size?: string | number;
+  circleWidth?: number;
+}) => {
+  return (
+    <div className="Spinner">
+      <svg viewBox="0 0 100 100" style={{ width: size, height: size }}>
+        <circle
+          cx="50"
+          cy="50"
+          r={50 - circleWidth / 2}
+          strokeWidth={circleWidth}
+          fill="none"
+          strokeMiterlimit="10"
+        />
+      </svg>
+    </div>
+  );
+};
+
+export default Spinner;

src/components/ToolButton.tsx

 import "./ToolIcon.scss";
 
-import React from "react";
+import React, { useEffect, useRef, useState } from "react";
 import clsx from "clsx";
 import { useExcalidrawContainer } from "./App";
+import { AbortError } from "../errors";
+import Spinner from "./Spinner";
+import { PointerType } from "../element/types";
 
 export type ToolButtonSize = "small" | "medium";
 
   | (ToolButtonBaseProps & {
       type: "button";
       children?: React.ReactNode;
-      onClick?(): void;
+      onClick?(event: React.MouseEvent): void;
     })
   | (ToolButtonBaseProps & {
       type: "icon";
   | (ToolButtonBaseProps & {
       type: "radio";
       checked: boolean;
-      onChange?(): void;
+      onChange?(data: { pointerType: PointerType | null }): void;
     });
 
 export const ToolButton = React.forwardRef((props: ToolButtonProps, ref) => {
   React.useImperativeHandle(ref, () => innerRef.current);
   const sizeCn = `ToolIcon_size_${props.size}`;
 
+  const [isLoading, setIsLoading] = useState(false);
+
+  const isMountedRef = useRef(true);
+
+  const onClick = async (event: React.MouseEvent) => {
+    const ret = "onClick" in props && props.onClick?.(event);
+
+    if (ret && "then" in ret) {
+      try {
+        setIsLoading(true);
+        await ret;
+      } catch (error) {
+        if (!(error instanceof AbortError)) {
+          throw error;
+        }
+      } finally {
+        if (isMountedRef.current) {
+          setIsLoading(false);
+        }
+      }
+    }
+  };
+
+  useEffect(
+    () => () => {
+      isMountedRef.current = false;
+    },
+    [],
+  );
+
+  const lastPointerTypeRef = useRef<PointerType | null>(null);
+
   if (props.type === "button" || props.type === "icon") {
     return (
       <button
         title={props.title}
         aria-label={props["aria-label"]}
         type="button"
-        onClick={props.onClick}
+        onClick={onClick}
         ref={innerRef}
+        disabled={isLoading}
       >
         {(props.icon || props.label) && (
           <div className="ToolIcon__icon" aria-hidden="true">
           </div>
         )}
         {props.showAriaLabel && (
-          <div className="ToolIcon__label">{props["aria-label"]}</div>
+          <div className="ToolIcon__label">
+            {props["aria-label"]} {isLoading && <Spinner />}
+          </div>
         )}
         {props.children}
       </button>
   }
 
   return (
-    <label className={clsx("ToolIcon", props.className)} title={props.title}>
+    <label
+      className={clsx("ToolIcon", props.className)}
+      title={props.title}
+      onPointerDown={(event) => {
+        lastPointerTypeRef.current = event.pointerType || null;
+      }}
+      onPointerUp={() => {
+        requestAnimationFrame(() => {
+          lastPointerTypeRef.current = null;
+        });
+      }}
+    >
       <input
         className={`ToolIcon_type_radio ${sizeCn}`}
         type="radio"
         aria-keyshortcuts={props["aria-keyshortcuts"]}
         data-testid={props["data-testid"]}
         id={`${excalId}-${props.id}`}
-        onChange={props.onChange}
+        onChange={() => {
+          props.onChange?.({ pointerType: lastPointerTypeRef.current });
+        }}
         checked={props.checked}
         ref={innerRef}
       />

src/components/ToolIcon.scss

   }
 
   .ToolIcon__label {
+    display: flex;
+    align-items: center;
     color: var(--icon-fill-color);
     font-family: var(--ui-font);
     margin: 0 0.8em;
     text-overflow: ellipsis;
+
+    .Spinner {
+      margin-left: 0.6em;
+    }
   }
 
   .ToolIcon_size_small .ToolIcon__icon {

src/constants.ts

 export const MIME_TYPES = {
   excalidraw: "application/vnd.excalidraw+json",
   excalidrawlib: "application/vnd.excalidrawlib+json",
+  json: "application/json",
+  svg: "image/svg+xml",
+  png: "image/png",
+  jpg: "image/jpeg",
+  gif: "image/gif",
+  binary: "application/octet-stream",
 } as const;
 
 export const EXPORT_DATA_TYPES = {
 } as const;
 
 // time in milliseconds
+export const IMAGE_RENDER_TIMEOUT = 500;
 export const TAP_TWICE_TIMEOUT = 300;
 export const TOUCH_CTX_MENU_TIMEOUT = 500;
 export const TITLE_TIMEOUT = 10000;
 
 export const EXPORT_SCALES = [1, 2, 3];
 export const DEFAULT_EXPORT_PADDING = 10; // px
+
+export const DEFAULT_MAX_IMAGE_WIDTH_OR_HEIGHT = 1440;
+
+export const ALLOWED_IMAGE_MIME_TYPES = [
+  MIME_TYPES.png,
+  MIME_TYPES.jpg,
+  MIME_TYPES.svg,
+  MIME_TYPES.gif,
+] as const;
+
+export const MAX_ALLOWED_FILE_BYTES = 2 * 1024 * 1024;
+
+export const SVG_NS = "http://www.w3.org/2000/svg";

src/data/blob.ts

+import { nanoid } from "nanoid";
 import { cleanAppStateForExport } from "../appState";
-import { EXPORT_DATA_TYPES } from "../constants";
+import {
+  ALLOWED_IMAGE_MIME_TYPES,
+  EXPORT_DATA_TYPES,
+  MIME_TYPES,
+} from "../constants";
 import { clearElementsForExport } from "../element";
-import { ExcalidrawElement } from "../element/types";
+import { ExcalidrawElement, FileId } from "../element/types";
 import { CanvasError } from "../errors";
 import { t } from "../i18n";
 import { calculateScrollCenter } from "../scene";
-import { AppState } from "../types";
+import { AppState, DataURL } from "../types";
 import { FileSystemHandle } from "./filesystem";
 import { isValidExcalidrawData } from "./json";
 import { restore } from "./restore";
 const parseFileContents = async (blob: Blob | File) => {
   let contents: string;
 
-  if (blob.type === "image/png") {
+  if (blob.type === MIME_TYPES.png) {
     try {
       return await (
         await import(/* webpackChunkName: "image" */ "./image")
       ).decodePngMetadata(blob);
     } catch (error) {
       if (error.message === "INVALID") {
-        throw new Error(t("alerts.imageDoesNotContainScene"));
+        throw new DOMException(
+          t("alerts.imageDoesNotContainScene"),
+          "EncodingError",
+        );
       } else {
-        throw new Error(t("alerts.cannotRestoreFromImage"));
+        throw new DOMException(
+          t("alerts.cannotRestoreFromImage"),
+          "EncodingError",
+        );
       }
     }
   } else {
         };
       });
     }
-    if (blob.type === "image/svg+xml") {
+    if (blob.type === MIME_TYPES.svg) {
       try {
         return await (
           await import(/* webpackChunkName: "image" */ "./image")
         });
       } catch (error) {
         if (error.message === "INVALID") {
-          throw new Error(t("alerts.imageDoesNotContainScene"));
+          throw new DOMException(
+            t("alerts.imageDoesNotContainScene"),
+            "EncodingError",
+          );
         } else {
-          throw new Error(t("alerts.cannotRestoreFromImage"));
+          throw new DOMException(
+            t("alerts.cannotRestoreFromImage"),
+            "EncodingError",
+          );
         }
       }
     }
     name = blob.name || "";
   }
   if (/\.(excalidraw|json)$/.test(name)) {
-    return "application/json";
+    return MIME_TYPES.json;
   } else if (/\.png$/.test(name)) {
-    return "image/png";
+    return MIME_TYPES.png;
   } else if (/\.jpe?g$/.test(name)) {
-    return "image/jpeg";
+    return MIME_TYPES.jpg;
   } else if (/\.svg$/.test(name)) {
-    return "image/svg+xml";
+    return MIME_TYPES.svg;
   }
   return "";
 };
   return type === "png" || type === "svg";
 };
 
+export const isSupportedImageFile = (
+  blob: Blob | null | undefined,
+): blob is Blob & { type: typeof ALLOWED_IMAGE_MIME_TYPES[number] } => {
+  const { type } = blob || {};
+  return (
+    !!type && (ALLOWED_IMAGE_MIME_TYPES as readonly string[]).includes(type)
+  );
+};
+
 export const loadFromBlob = async (
   blob: Blob,
   /** @see restore.localAppState */
             ? calculateScrollCenter(data.elements || [], localAppState, null)
             : {}),
         },
+        files: data.files,
       },
       localAppState,
       localElements,
     }
   });
 };
+
+/** generates SHA-1 digest from supplied file (if not supported, falls back
+    to a 40-char base64 random id) */
+export const generateIdFromFile = async (file: File) => {
+  let id: FileId;
+  try {
+    const hashBuffer = await window.crypto.subtle.digest(
+      "SHA-1",
+      await file.arrayBuffer(),
+    );
+    id =
+      // convert buffer to byte array
+      Array.from(new Uint8Array(hashBuffer))
+        // convert to hex string
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("") as FileId;
+  } catch (error) {
+    console.error(error);
+    // length 40 to align with the HEX length of SHA-1 (which is 160 bit)
+    id = nanoid(40) as FileId;
+  }
+
+  return id;
+};
+
+export const getDataURL = async (file: Blob | File): Promise<DataURL> => {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      const dataURL = reader.result as DataURL;
+      resolve(dataURL);
+    };
+    reader.onerror = (error) => reject(error);
+    reader.readAsDataURL(file);
+  });
+};
+
+export const dataURLToFile = (dataURL: DataURL, filename = "") => {
+  const dataIndexStart = dataURL.indexOf(",");
+  const byteString = atob(dataURL.slice(dataIndexStart + 1));
+  const mimeType = dataURL.slice(0, dataIndexStart).split(":")[1].split(";")[0];
+
+  const ab = new ArrayBuffer(byteString.length);
+  const ia = new Uint8Array(ab);
+  for (let i = 0; i < byteString.length; i++) {
+    ia[i] = byteString.charCodeAt(i);
+  }
+  return new File([ab], filename, { type: mimeType });
+};
+
+export const resizeImageFile = async (
+  file: File,
+  maxWidthOrHeight: number,
+): Promise<File> => {
+  // SVG files shouldn't a can't be resized
+  if (file.type === MIME_TYPES.svg) {
+    return file;
+  }
+
+  const [pica, imageBlobReduce] = await Promise.all([
+    import("pica").then((res) => res.default),
+    // a wrapper for pica for better API
+    import("image-blob-reduce").then((res) => res.default),
+  ]);
+
+  // CRA's minification settings break pica in WebWorkers, so let's disable
+  // them for now
+  // https://github.com/nodeca/image-blob-reduce/issues/21#issuecomment-757365513
+  const reduce = imageBlobReduce({
+    pica: pica({ features: ["js", "wasm"] }),
+  });
+
+  const fileType = file.type;
+
+  if (!isSupportedImageFile(file)) {
+    throw new Error(t("errors.unsupportedFileType"));
+  }
+
+  return new File(
+    [await reduce.toBlob(file, { max: maxWidthOrHeight })],
+    file.name,
+    { type: fileType },
+  );
+};
+
+export const SVGStringToFile = (SVGString: string, filename: string = "") => {
+  return new File([new TextEncoder().encode(SVGString)], filename, {
+    type: MIME_TYPES.svg,
+  }) as File & { type: typeof MIME_TYPES.svg };
+};

src/data/encode.ts

 import { deflate, inflate } from "pako";
+import { encryptData, decryptData } from "./encryption";
 
 // -----------------------------------------------------------------------------
 // byte (binary) strings
 // -----------------------------------------------------------------------------
 
 // fast, Buffer-compatible implem
-export const toByteString = (data: string | Uint8Array): Promise<string> => {
+export const toByteString = (
+  data: string | Uint8Array | ArrayBuffer,
+): Promise<string> => {
   return new Promise((resolve, reject) => {
     const blob =
       typeof data === "string"
         ? new Blob([new TextEncoder().encode(data)])
-        : new Blob([data]);
+        : new Blob([data instanceof Uint8Array ? data : new Uint8Array(data)]);
     const reader = new FileReader();
     reader.onload = (event) => {
       if (!event.target || typeof event.target.result !== "string") {
  *  due to reencoding
  */
 export const stringToBase64 = async (str: string, isByteString = false) => {
-  return isByteString ? btoa(str) : btoa(await toByteString(str));
+  return isByteString ? window.btoa(str) : window.btoa(await toByteString(str));
 };
 
 // async to align with stringToBase64
 export const base64ToString = async (base64: string, isByteString = false) => {
-  return isByteString ? atob(base64) : byteStringToString(atob(base64));
+  return isByteString
+    ? window.atob(base64)
+    : byteStringToString(window.atob(base64));
 };
 
 // -----------------------------------------------------------------------------
 
   return decoded;
 };
+
+// -----------------------------------------------------------------------------
+// binary encoding
+// -----------------------------------------------------------------------------
+
+type FileEncodingInfo = {
+  /* version 2 is the version we're shipping the initial image support with.
+    version 1 was a PR version that a lot of people were using anyway.
+    Thus, if there are issues we can check whether they're not using the
+    unoffic version */
+  version: 1 | 2;
+  compression: "pako@1" | null;
+  encryption: "AES-GCM" | null;
+};
+
+// -----------------------------------------------------------------------------
+const CONCAT_BUFFERS_VERSION = 1;
+/** how many bytes we use to encode how many bytes the next chunk has.
+ * Corresponds to DataView setter methods (setUint32, setUint16, etc).
+ *
+ * NOTE ! values must not be changed, which would be backwards incompatible !
+ */
+const VERSION_DATAVIEW_BYTES = 4;
+const NEXT_CHUNK_SIZE_DATAVIEW_BYTES = 4;
+// -----------------------------------------------------------------------------
+
+const DATA_VIEW_BITS_MAP = { 1: 8, 2: 16, 4: 32 } as const;
+
+// getter
+function dataView(buffer: Uint8Array, bytes: 1 | 2 | 4, offset: number): number;
+// setter
+function dataView(
+  buffer: Uint8Array,
+  bytes: 1 | 2 | 4,
+  offset: number,
+  value: number,
+): Uint8Array;
+/**
+ * abstraction over DataView that serves as a typed getter/setter in case
+ * you're using constants for the byte size and want to ensure there's no
+ * discrepenancy in the encoding across refactors.
+ *
+ * DataView serves for an endian-agnostic handling of numbers in ArrayBuffers.
+ */
+function dataView(
+  buffer: Uint8Array,
+  bytes: 1 | 2 | 4,
+  offset: number,
+  value?: number,
+): Uint8Array | number {
+  if (value != null) {
+    if (value > Math.pow(2, DATA_VIEW_BITS_MAP[bytes]) - 1) {
+      throw new Error(
+        `attempting to set value higher than the allocated bytes (value: ${value}, bytes: ${bytes})`,
+      );
+    }
+    const method = `setUint${DATA_VIEW_BITS_MAP[bytes]}` as const;
+    new DataView(buffer.buffer)[method](offset, value);
+    return buffer;
+  }
+  const method = `getUint${DATA_VIEW_BITS_MAP[bytes]}` as const;
+  return new DataView(buffer.buffer)[method](offset);
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Resulting concatenated buffer has this format:
+ *
+ * [
+ *   VERSION chunk (4 bytes)
+ *   LENGTH chunk 1 (4 bytes)
+ *   DATA chunk 1 (up to 2^32 bits)
+ *   LENGTH chunk 2 (4 bytes)
+ *   DATA chunk 2 (up to 2^32 bits)
+ *   ...
+ * ]
+ *
+ * @param buffers each buffer (chunk) must be at most 2^32 bits large (~4GB)
+ */
+const concatBuffers = (...buffers: Uint8Array[]) => {
+  const bufferView = new Uint8Array(
+    VERSION_DATAVIEW_BYTES +
+      NEXT_CHUNK_SIZE_DATAVIEW_BYTES * buffers.length +
+      buffers.reduce((acc, buffer) => acc + buffer.byteLength, 0),
+  );
+
+  let cursor = 0;
+
+  // as the first chunk we'll encode the version for backwards compatibility
+  dataView(bufferView, VERSION_DATAVIEW_BYTES, cursor, CONCAT_BUFFERS_VERSION);
+  cursor += VERSION_DATAVIEW_BYTES;
+
+  for (const buffer of buffers) {
+    dataView(
+      bufferView,
+      NEXT_CHUNK_SIZE_DATAVIEW_BYTES,
+      cursor,
+      buffer.byteLength,
+    );
+    cursor += NEXT_CHUNK_SIZE_DATAVIEW_BYTES;
+
+    bufferView.set(buffer, cursor);
+    cursor += buffer.byteLength;
+  }
+
+  return bufferView;
+};
+
+/** can only be used on buffers created via `concatBuffers()` */
+const splitBuffers = (concatenatedBuffer: Uint8Array) => {
+  const buffers = [];
+
+  let cursor = 0;
+
+  // first chunk is the version (ignored for now)
+  cursor += VERSION_DATAVIEW_BYTES;
+
+  while (true) {
+    const chunkSize = dataView(
+      concatenatedBuffer,
+      NEXT_CHUNK_SIZE_DATAVIEW_BYTES,
+      cursor,
+    );
+    cursor += NEXT_CHUNK_SIZE_DATAVIEW_BYTES;
+
+    buffers.push(concatenatedBuffer.slice(cursor, cursor + chunkSize));
+    cursor += chunkSize;
+    if (cursor >= concatenatedBuffer.byteLength) {
+      break;
+    }
+  }
+
+  return buffers;
+};
+
+// helpers for (de)compressing data with JSON metadata including encryption
+// -----------------------------------------------------------------------------
+
+/** @private */
+const _encryptAndCompress = async (
+  data: Uint8Array | string,
+  encryptionKey: string,
+) => {
+  const { encryptedBuffer, iv } = await encryptData(
+    encryptionKey,
+    deflate(data),
+  );
+
+  return { iv, buffer: new Uint8Array(encryptedBuffer) };
+};
+
+/**
+ * The returned buffer has following format:
+ * `[]` refers to a buffers wrapper (see `concatBuffers`)
+ *
+ * [
+ *   encodingMetadataBuffer,
+ *   iv,
+ *   [
+ *      contentsMetadataBuffer
+ *      contentsBuffer
+ *   ]
+ * ]
+ */
+export const compressData = async <T extends Record<string, any> = never>(
+  dataBuffer: Uint8Array,
+  options: {
+    encryptionKey: string;
+  } & ([T] extends [never]
+    ? {
+        metadata?: T;
+      }
+    : {
+        metadata: T;
+      }),
+): Promise<Uint8Array> => {
+  const fileInfo: FileEncodingInfo = {
+    version: 2,
+    compression: "pako@1",
+    encryption: "AES-GCM",
+  };
+
+  const encodingMetadataBuffer = new TextEncoder().encode(
+    JSON.stringify(fileInfo),
+  );
+
+  const contentsMetadataBuffer = new TextEncoder().encode(
+    JSON.stringify(options.metadata || null),
+  );
+
+  const { iv, buffer } = await _encryptAndCompress(
+    concatBuffers(contentsMetadataBuffer, dataBuffer),
+    options.encryptionKey,
+  );
+
+  return concatBuffers(encodingMetadataBuffer, iv, buffer);
+};
+
+/** @private */
+const _decryptAndDecompress = async (
+  iv: Uint8Array,
+  decryptedBuffer: Uint8Array,
+  decryptionKey: string,
+  isCompressed: boolean,
+) => {
+  decryptedBuffer = new Uint8Array(
+    await decryptData(iv, decryptedBuffer, decryptionKey),
+  );
+
+  if (isCompressed) {
+    return inflate(decryptedBuffer);
+  }
+
+  return decryptedBuffer;
+};
+
+export const decompressData = async <T extends Record<string, any>>(
+  bufferView: Uint8Array,
+  options: { decryptionKey: string },
+) => {
+  // first chunk is encoding metadata (ignored for now)
+  const [encodingMetadataBuffer, iv, buffer] = splitBuffers(bufferView);
+
+  const encodingMetadata: FileEncodingInfo = JSON.parse(
+    new TextDecoder().decode(encodingMetadataBuffer),
+  );
+
+  try {
+    const [contentsMetadataBuffer, contentsBuffer] = splitBuffers(
+      await _decryptAndDecompress(
+        iv,
+        buffer,
+        options.decryptionKey,
+        !!encodingMetadata.compression,
+      ),
+    );
+
+    const metadata = JSON.parse(
+      new TextDecoder().decode(contentsMetadataBuffer),
+    ) as T;
+
+    return {
+      /** metadata source is always JSON so we can decode it here */
+      metadata,
+      /** data can be anything so the caller must decode it */
+      data: contentsBuffer,
+    };
+  } catch (error) {
+    console.error(
+      `Error during decompressing and decrypting the file.`,
+      encodingMetadata,
+    );
+    throw error;
+  }
+};
+
+// -----------------------------------------------------------------------------

src/data/encryption.ts

+export const IV_LENGTH_BYTES = 12;
+
+export const createIV = () => {
+  const arr = new Uint8Array(IV_LENGTH_BYTES);
+  return window.crypto.getRandomValues(arr);
+};
+
+export const generateEncryptionKey = async () => {
+  const key = await window.crypto.subtle.generateKey(
+    {
+      name: "AES-GCM",
+      length: 128,
+    },
+    true, // extractable
+    ["encrypt", "decrypt"],
+  );
+  return (await window.crypto.subtle.exportKey("jwk", key)).k;
+};
+
+export const getImportedKey = (key: string, usage: KeyUsage) =>
+  window.crypto.subtle.importKey(
+    "jwk",
+    {
+      alg: "A128GCM",
+      ext: true,
+      k: key,
+      key_ops: ["encrypt", "decrypt"],
+      kty: "oct",
+    },
+    {
+      name: "AES-GCM",
+      length: 128,
+    },
+    false, // extractable
+    [usage],
+  );
+
+export const encryptData = async (
+  key: string,
+  data: Uint8Array | ArrayBuffer | Blob | File | string,
+): Promise<{ encryptedBuffer: ArrayBuffer; iv: Uint8Array }> => {
+  const importedKey = await getImportedKey(key, "encrypt");
+  const iv = createIV();
+  const buffer: ArrayBuffer | Uint8Array =
+    typeof data === "string"
+      ? new TextEncoder().encode(data)
+      : data instanceof Uint8Array
+      ? data
+      : data instanceof Blob
+      ? await data.arrayBuffer()
+      : data;
+
+  const encryptedBuffer = await window.crypto.subtle.encrypt(
+    {
+      name: "AES-GCM",
+      iv,
+    },
+    importedKey,
+    buffer as ArrayBuffer | Uint8Array,
+  );
+
+  return { encryptedBuffer, iv };
+};
+
+export const decryptData = async (
+  iv: Uint8Array,
+  encrypted: Uint8Array | ArrayBuffer,
+  privateKey: string,
+): Promise<ArrayBuffer> => {
+  const key = await getImportedKey(privateKey, "decrypt");
+  return window.crypto.subtle.decrypt(
+    {
+      name: "AES-GCM",
+      iv,
+    },
+    key,
+    encrypted,
+  );
+};

src/data/filesystem.ts

 import { debounce } from "../utils";
 
 type FILE_EXTENSION =
+  | "gif"
   | "jpg"
   | "png"
   | "svg"
   | "excalidraw"
   | "excalidrawlib";
 
-const FILE_TYPE_TO_MIME_TYPE: Record<FILE_EXTENSION, string> = {
-  jpg: "image/jpeg",
-  png: "image/png",
-  svg: "image/svg+xml",
-  json: "application/json",
-  excalidraw: MIME_TYPES.excalidraw,
-  excalidrawlib: MIME_TYPES.excalidrawlib,
-};
-
 const INPUT_CHANGE_INTERVAL_MS = 500;
 
 export const fileOpen = <M extends boolean | undefined = false>(opts: {
     : FileWithHandle[];
 
   const mimeTypes = opts.extensions?.reduce((mimeTypes, type) => {
-    mimeTypes.push(FILE_TYPE_TO_MIME_TYPE[type]);
+    mimeTypes.push(MIME_TYPES[type]);
 
     return mimeTypes;
   }, [] as string[]);

src/data/image.ts

   // insert metadata before last chunk (iEND)
   chunks.splice(-1, 0, metadataChunk);
 
-  return new Blob([encodePng(chunks)], { type: "image/png" });
+  return new Blob([encodePng(chunks)], { type: MIME_TYPES.png });
 };
 
 export const decodePngMetadata = async (blob: Blob) => {

src/data/index.ts

   copyBlobToClipboardAsPng,
   copyTextToSystemClipboard,
 } from "../clipboard";
-import { DEFAULT_EXPORT_PADDING } from "../constants";
+import { DEFAULT_EXPORT_PADDING, MIME_TYPES } from "../constants";
 import { NonDeletedExcalidrawElement } from "../element/types";
 import { t } from "../i18n";
 import { exportToCanvas, exportToSvg } from "../scene/export";
 import { ExportType } from "../scene/types";
-import { AppState } from "../types";
+import { AppState, BinaryFiles } from "../types";
 import { canvasToBlob } from "./blob";
 import { fileSave, FileSystemHandle } from "./filesystem";
 import { serializeAsJSON } from "./json";
   type: ExportType,
   elements: readonly NonDeletedExcalidrawElement[],
   appState: AppState,
+  files: BinaryFiles,
   {
     exportBackground,
     exportPadding = DEFAULT_EXPORT_PADDING,
     throw new Error(t("alerts.cannotExportEmptyCanvas"));
   }
   if (type === "svg" || type === "clipboard-svg") {
-    const tempSvg = await exportToSvg(elements, {
-      exportBackground,
-      exportWithDarkMode: appState.exportWithDarkMode,
-      viewBackgroundColor,
-      exportPadding,
-      exportScale: appState.exportScale,
-      exportEmbedScene: appState.exportEmbedScene && type === "svg",
-    });
+    const tempSvg = await exportToSvg(
+      elements,
+      {
+        exportBackground,
+        exportWithDarkMode: appState.exportWithDarkMode,
+        viewBackgroundColor,
+        exportPadding,
+        exportScale: appState.exportScale,
+        exportEmbedScene: appState.exportEmbedScene && type === "svg",
+      },
+      files,
+    );
     if (type === "svg") {
       return await fileSave(
-        new Blob([tempSvg.outerHTML], { type: "image/svg+xml" }),
+        new Blob([tempSvg.outerHTML], { type: MIME_TYPES.svg }),
         {
           name,
           extension: "svg",
     }
   }
 
-  const tempCanvas = exportToCanvas(elements, appState, {
+  const tempCanvas = await exportToCanvas(elements, appState, files, {
     exportBackground,
     viewBackgroundColor,
     exportPadding,
         await import(/* webpackChunkName: "image" */ "./image")
       ).encodePngMetadata({
         blob,
-        metadata: serializeAsJSON(elements, appState),
+        metadata: serializeAsJSON(elements, appState, files, "local"),
       });
     }
 

src/data/json.ts

 import { fileOpen, fileSave } from "./filesystem";
-import { cleanAppStateForExport } from "../appState";
+import { cleanAppStateForExport, clearAppStateForDatabase } from "../appState";
 import { EXPORT_DATA_TYPES, EXPORT_SOURCE, MIME_TYPES } from "../constants";
-import { clearElementsForExport } from "../element";
+import { clearElementsForDatabase, clearElementsForExport } from "../element";
 import { ExcalidrawElement } from "../element/types";
-import { AppState } from "../types";
+import { AppState, BinaryFiles } from "../types";
 import { isImageFileHandle, loadFromBlob } from "./blob";
 
 import {
 } from "./types";
 import Library from "./library";
 
+/**
+ * Strips out files which are only referenced by deleted elements
+ */
+const filterOutDeletedFiles = (
+  elements: readonly ExcalidrawElement[],
+  files: BinaryFiles,
+) => {
+  const nextFiles: BinaryFiles = {};
+  for (const element of elements) {
+    if (
+      !element.isDeleted &&
+      "fileId" in element &&
+      element.fileId &&
+      files[element.fileId]
+    ) {
+      nextFiles[element.fileId] = files[element.fileId];
+    }
+  }
+  return nextFiles;
+};
+
 export const serializeAsJSON = (
   elements: readonly ExcalidrawElement[],
   appState: Partial<AppState>,
+  files: BinaryFiles,
+  type: "local" | "database",
 ): string => {
   const data: ExportedDataState = {
     type: EXPORT_DATA_TYPES.excalidraw,
     version: 2,
     source: EXPORT_SOURCE,
-    elements: clearElementsForExport(elements),
-    appState: cleanAppStateForExport(appState),
+    elements:
+      type === "local"
+        ? clearElementsForExport(elements)
+        : clearElementsForDatabase(elements),
+    appState:
+      type === "local"
+        ? cleanAppStateForExport(appState)
+        : clearAppStateForDatabase(appState),
+    files:
+      type === "local"
+        ? filterOutDeletedFiles(elements, files)
+        : // will be stripped from JSON
+          undefined,
   };
 
   return JSON.stringify(data, null, 2);
 export const saveAsJSON = async (
   elements: readonly ExcalidrawElement[],
   appState: AppState,
+  files: BinaryFiles,
 ) => {
-  const serialized = serializeAsJSON(elements, appState);
+  const serialized = serializeAsJSON(elements, appState, files, "local");
   const blob = new Blob([serialized], {
     type: MIME_TYPES.excalidraw,
   });
     description: "Excalidraw files",
     // ToDo: Be over-permissive until https://bugs.webkit.org/show_bug.cgi?id=34442
     // gets resolved. Else, iOS users cannot open `.excalidraw` files.
-    /*
-    extensions: [".json", ".excalidraw", ".png", ".svg"],
-    mimeTypes: [
-      MIME_TYPES.excalidraw,
-      "application/json",
-      "image/png",
-      "image/svg+xml",
-    ],
-    */
+    // extensions: ["json", "excalidraw", "png", "svg"],
   });
   return loadFromBlob(blob, localAppState, localElements);
 };

src/data/resave.ts

 import { ExcalidrawElement } from "../element/types";
-import { AppState } from "../types";
+import { AppState, BinaryFiles } from "../types";
 import { exportCanvas } from ".";
 import { getNonDeletedElements } from "../element";
 import { getFileHandleType, isImageFileHandleType } from "./blob";
 export const resaveAsImageWithScene = async (
   elements: readonly ExcalidrawElement[],
   appState: AppState,
+  files: BinaryFiles,
 ) => {
   const { exportBackground, viewBackgroundColor, name, fileHandle } = appState;
 
     fileHandleType,
     getNonDeletedElements(elements),
     appState,
+    files,
     {
       exportBackground,
       viewBackgroundColor,

src/data/restore.ts

   ExcalidrawSelectionElement,
   FontFamilyValues,
 } from "../element/types";
-import { AppState, NormalizedZoomValue } from "../types";
+import { AppState, BinaryFiles, NormalizedZoomValue } from "../types";
 import { ImportedDataState } from "./types";
 import {
   getElementMap,
   diamond: true,
   ellipse: true,
   line: true,
+  image: true,
   arrow: true,
   freedraw: true,
 };
 export type RestoredDataState = {
   elements: ExcalidrawElement[];
   appState: RestoredAppState;
+  files: BinaryFiles;
 };
 
 const getFontFamilyByName = (fontFamilyName: string): FontFamilyValues => {
 
 const restoreElementWithProperties = <
   T extends ExcalidrawElement,
-  K extends keyof Omit<
-    Required<T>,
-    Exclude<keyof ExcalidrawElement, "type" | "x" | "y">
-  >
+  K extends Pick<T, keyof Omit<Required<T>, keyof ExcalidrawElement>>
 >(
   element: Required<T>,
-  extra: Pick<T, K>,
+  extra: Pick<
+    T,
+    // This extra Pick<T, keyof K> ensure no excess properties are passed.
+    // @ts-ignore TS complains here but type checks the call sites fine.
+    keyof K
+  > &
+    Partial<Pick<ExcalidrawElement, "type" | "x" | "y">>,
 ): T => {
   const base: Pick<T, keyof ExcalidrawElement> = {
-    type: (extra as Partial<T>).type || element.type,
+    type: extra.type || element.type,
     // all elements must have version > 0 so getSceneVersion() will pick up
     // newly added elements
     version: element.version || 1,
     roughness: element.roughness ?? 1,
     opacity: element.opacity == null ? 100 : element.opacity,
     angle: element.angle || 0,
-    x: (extra as Partial<T>).x ?? element.x ?? 0,
-    y: (extra as Partial<T>).y ?? element.y ?? 0,
+    x: extra.x ?? element.x ?? 0,
+    y: extra.y ?? element.y ?? 0,
     strokeColor: element.strokeColor,
     backgroundColor: element.backgroundColor,
     width: element.width || 0,
 
 const restoreElement = (
   element: Exclude<ExcalidrawElement, ExcalidrawSelectionElement>,
-): typeof element => {
+): typeof element | null => {
   switch (element.type) {
     case "text":
       let fontSize = element.fontSize;
         pressures: element.pressures,
       });
     }
+    case "image":
+      return restoreElementWithProperties(element, {
+        status: element.status || "pending",
+        fileId: element.fileId,
+        scale: element.scale || [1, 1],
+      });
     case "line":
     // @ts-ignore LEGACY type
     // eslint-disable-next-line no-fallthrough
     // filtering out selection, which is legacy, no longer kept in elements,
     // and causing issues if retained
     if (element.type !== "selection" && !isInvisiblySmallElement(element)) {
-      let migratedElement: ExcalidrawElement = restoreElement(element);
+      let migratedElement: ExcalidrawElement | null = restoreElement(element);
       if (migratedElement) {
         const localElement = localElementsMap?.[element.id];
         if (localElement && localElement.version > migratedElement.version) {
   return {
     elements: restoreElements(data?.elements, localElements),
     appState: restoreAppState(data?.appState, localAppState || null),
+    files: data?.files || {},
   };
 };

src/data/types.ts

 import { ExcalidrawElement } from "../element/types";
-import { AppState, LibraryItems } from "../types";
+import { AppState, BinaryFiles, LibraryItems } from "../types";
 import type { cleanAppStateForExport } from "../appState";
 
 export interface ExportedDataState {
   source: string;
   elements: readonly ExcalidrawElement[];
   appState: ReturnType<typeof cleanAppStateForExport>;
+  files: BinaryFiles | undefined;
 }
 
 export interface ImportedDataState {
   appState?: Readonly<Partial<AppState>> | null;
   scrollToContent?: boolean;
   libraryItems?: LibraryItems;
+  files?: BinaryFiles;
 }
 
 export interface ExportedLibraryData {

src/element/collision.ts

   ExcalidrawEllipseElement,
   NonDeleted,
   ExcalidrawFreeDrawElement,
+  ExcalidrawImageElement,
 } from "./types";
 
 import { getElementAbsoluteCoords, getCurvePathOps, Bounds } from "./bounds";
 import { Drawable } from "roughjs/bin/core";
 import { AppState } from "../types";
 import { getShapeForElement } from "../renderer/renderElement";
+import { isImageElement } from "./typeChecks";
 
 const isElementDraggableFromInside = (
   element: NonDeletedExcalidrawElement,
   if (element.type === "line") {
     return isDraggableFromInside && isPathALoop(element.points);
   }
-
-  return isDraggableFromInside;
+  return isDraggableFromInside || isImageElement(element);
 };
 
 export const hitTest = (
 const hitTestPointAgainstElement = (args: HitTestArgs): boolean => {
   switch (args.element.type) {
     case "rectangle":
+    case "image":
     case "text":
     case "diamond":
     case "ellipse":
 ): number => {
   switch (element.type) {
     case "rectangle":
+    case "image":
     case "text":
       return distanceToRectangle(element, point);
     case "diamond":
   element:
     | ExcalidrawRectangleElement
     | ExcalidrawTextElement
-    | ExcalidrawFreeDrawElement,
+    | ExcalidrawFreeDrawElement
+    | ExcalidrawImageElement,
   point: Point,
 ): number => {
   const [, pointRel, hwidth, hheight] = pointRelativeToElement(element, point);
   const nabs = Math.abs(n);
   switch (element.type) {
     case "rectangle":
+    case "image":
     case "text":
       return c / (hwidth * (nabs + q * mabs));
     case "diamond":
   let point;
   switch (element.type) {
     case "rectangle":
+    case "image":
     case "text":
     case "diamond":
       point = findFocusPointForRectangulars(element, focus, adjecentPointRel);
   let intersections: GA.Point[];
   switch (element.type) {
     case "rectangle":
+    case "image":
     case "text":
     case "diamond":
       const corners = getCorners(element);
 const getCorners = (
   element:
     | ExcalidrawRectangleElement
+    | ExcalidrawImageElement
     | ExcalidrawDiamondElement
     | ExcalidrawTextElement,
   scale: number = 1,
   const hy = (scale * element.height) / 2;
   switch (element.type) {
     case "rectangle":
+    case "image":
     case "text":
       return [
         GA.point(hx, hy),
 export const findFocusPointForRectangulars = (
   element:
     | ExcalidrawRectangleElement
+    | ExcalidrawImageElement
     | ExcalidrawDiamondElement
     | ExcalidrawTextElement,
   // Between -1 and 1 for how far away should the focus point be relative

src/element/dragElements.ts

   y: number,
   width: number,
   height: number,
-  isResizeWithSidesSameLength: boolean,
-  isResizeCenterPoint: boolean,
+  shouldMaintainAspectRatio: boolean,
+  shouldResizeFromCenter: boolean,
+  /** whether to keep given aspect ratio when `isResizeWithSidesSameLength` is
+      true */
+  widthAspectRatio?: number | null,
 ) => {
-  if (isResizeWithSidesSameLength) {
-    ({ width, height } = getPerfectElementSize(
-      elementType,
-      width,
-      y < originY ? -height : height,
-    ));
+  if (shouldMaintainAspectRatio) {
+    if (widthAspectRatio) {
+      height = width / widthAspectRatio;
+    } else {
+      ({ width, height } = getPerfectElementSize(
+        elementType,
+        width,
+        y < originY ? -height : height,
+      ));
 
-    if (height < 0) {
-      height = -height;
+      if (height < 0) {
+        height = -height;
+      }
     }
   }
 
   let newX = x < originX ? originX - width : originX;
   let newY = y < originY ? originY - height : originY;
 
-  if (isResizeCenterPoint) {
+  if (shouldResizeFromCenter) {
     width += width;
     height += height;
     newX = originX - width / 2;

src/element/image.ts

+// -----------------------------------------------------------------------------
+// ExcalidrawImageElement & related helpers
+// -----------------------------------------------------------------------------
+
+import { MIME_TYPES, SVG_NS } from "../constants";
+import { t } from "../i18n";
+import { AppClassProperties, DataURL, BinaryFiles } from "../types";
+import { isInitializedImageElement } from "./typeChecks";
+import {
+  ExcalidrawElement,
+  FileId,
+  InitializedExcalidrawImageElement,
+} from "./types";
+
+export const loadHTMLImageElement = (dataURL: DataURL) => {
+  return new Promise<HTMLImageElement>((resolve, reject) => {
+    const image = new Image();
+    image.onload = () => {
+      resolve(image);
+    };
+    image.onerror = (error) => {
+      reject(error);
+    };
+    image.src = dataURL;
+  });
+};
+
+/** NOTE: updates cache even if already populated with given image. Thus,
+ * you should filter out the images upstream if you want to optimize this. */
+export const updateImageCache = async ({
+  fileIds,
+  files,
+  imageCache,
+}: {
+  fileIds: FileId[];
+  files: BinaryFiles;
+  imageCache: AppClassProperties["imageCache"];
+}) => {
+  const updatedFiles = new Map<FileId, true>();
+  const erroredFiles = new Map<FileId, true>();
+
+  await Promise.all(
+    fileIds.reduce((promises, fileId) => {
+      const fileData = files[fileId as string];
+      if (fileData && !updatedFiles.has(fileId)) {
+        updatedFiles.set(fileId, true);
+        return promises.concat(
+          (async () => {
+            try {
+              if (fileData.mimeType === MIME_TYPES.binary) {
+                throw new Error("Only images can be added to ImageCache");
+              }
+
+              const imagePromise = loadHTMLImageElement(fileData.dataURL);
+              const data = {
+                image: imagePromise,
+                mimeType: fileData.mimeType,
+              } as const;
+              // store the promise immediately to indicate there's an in-progress
+              // initialization
+              imageCache.set(fileId, data);
+
+              const image = await imagePromise;
+
+              imageCache.set(fileId, { ...data, image });
+            } catch (error) {
+              erroredFiles.set(fileId, true);
+            }
+          })(),
+        );
+      }
+      return promises;
+    }, [] as Promise<any>[]),
+  );
+
+  return {
+    imageCache,
+    /** includes errored files because they cache was updated nonetheless */
+    updatedFiles,
+    /** files that failed when creating HTMLImageElement */
+    erroredFiles,
+  };
+};
+
+export const getInitializedImageElements = (
+  elements: readonly ExcalidrawElement[],
+) =>
+  elements.filter((element) =>
+    isInitializedImageElement(element),
+  ) as InitializedExcalidrawImageElement[];
+
+export const isHTMLSVGElement = (node: Node | null): node is SVGElement => {
+  // lower-casing due to XML/HTML convention differences
+  // https://johnresig.com/blog/nodename-case-sensitivity
+  return node?.nodeName.toLowerCase() === "svg";
+};
+
+export const normalizeSVG = async (SVGString: string) => {
+  const doc = new DOMParser().parseFromString(SVGString, MIME_TYPES.svg);
+  const svg = doc.querySelector("svg");
+  const errorNode = doc.querySelector("parsererror");
+  if (errorNode || !isHTMLSVGElement(svg)) {
+    throw new Error(t("errors.invalidSVGString"));
+  } else {
+    if (!svg.hasAttribute("xmlns")) {
+      svg.setAttribute("xmlns", SVG_NS);
+    }
+
+    return svg.outerHTML;
+  }
+};

src/element/index.ts

   newTextElement,
   updateTextElement,
   newLinearElement,
+  newImageElement,
   duplicateElement,
 } from "./newElement";
 export {
       : element,
   );
 
+export const clearElementsForDatabase = (
+  elements: readonly ExcalidrawElement[],
+) => _clearElements(elements);
+
 export const clearElementsForExport = (
   elements: readonly ExcalidrawElement[],
 ) => _clearElements(elements);

src/element/mutateElement.ts

 export const mutateElement = <TElement extends Mutable<ExcalidrawElement>>(
   element: TElement,
   updates: ElementUpdate<TElement>,
-) => {
+  informMutation = true,
+): TElement => {
   let didChange = false;
 
   // casting to any because can't use `in` operator
   // (see https://github.com/microsoft/TypeScript/issues/21732)
-  const { points } = updates as any;
+  const { points, fileId } = updates as any;
 
   if (typeof points !== "undefined") {
     updates = { ...getSizeFromPoints(points), ...updates };
     if (typeof value !== "undefined") {
       if (
         (element as any)[key] === value &&
-        // if object, always update in case its deep prop was mutated
-        (typeof value !== "object" || value === null || key === "groupIds")
+        // if object, always update because its attrs could have changed
+        // (except for specific keys we handle below)
+        (typeof value !== "object" ||
+          value === null ||
+          key === "groupIds" ||
+          key === "scale")
       ) {
         continue;
       }
 
-      if (key === "points") {
+      if (key === "scale") {
+        const prevScale = (element as any)[key];
+        const nextScale = value;
+        if (prevScale[0] === nextScale[0] && prevScale[1] === nextScale[1]) {
+          continue;
+        }
+      } else if (key === "points") {
         const prevPoints = (element as any)[key];
         const nextPoints = value;
         if (prevPoints.length === nextPoints.length) {
       didChange = true;
     }
   }
-
   if (!didChange) {
-    return;
+    return element;
   }
 
   if (
     typeof updates.height !== "undefined" ||
     typeof updates.width !== "undefined" ||
+    typeof fileId != "undefined" ||
     typeof points !== "undefined"
   ) {
     invalidateShapeForElement(element);
 
   element.version++;
   element.versionNonce = randomInteger();
-  Scene.getScene(element)?.informMutation();
+
+  if (informMutation) {
+    Scene.getScene(element)?.informMutation();
+  }
+
+  return element;
 };
 
 export const newElementWith = <TElement extends ExcalidrawElement>(
     if (typeof value !== "undefined") {
       if (
         (element as any)[key] === value &&
-        // if object, always update in case its deep prop was mutated
-        (typeof value !== "object" || value === null || key === "groupIds")
+        // if object, always update because its attrs could have changed
+        (typeof value !== "object" || value === null)
       ) {
         continue;
       }

src/element/newElement.ts

 import {
   ExcalidrawElement,
+  ExcalidrawImageElement,
   ExcalidrawTextElement,
   ExcalidrawLinearElement,
   ExcalidrawGenericElement,
   };
 };
 
+export const newImageElement = (
+  opts: {
+    type: ExcalidrawImageElement["type"];
+  } & ElementConstructorOpts,
+): NonDeleted<ExcalidrawImageElement> => {
+  return {
+    ..._newElementBase<ExcalidrawImageElement>("image", opts),
+    // in the future we'll support changing stroke color for some SVG elements,
+    // and `transparent` will likely mean "use original colors of the image"
+    strokeColor: "transparent",
+    status: "pending",
+    fileId: null,
+    scale: [1, 1],
+  };
+};
+
 // Simplified deep clone for the purpose of cloning ExcalidrawElement only
 // (doesn't clone Date, RegExp, Map, Set, Typed arrays etc.)
 //

src/element/resizeElements.ts

   transformHandleType: MaybeTransformHandleType,
   selectedElements: readonly NonDeletedExcalidrawElement[],
   resizeArrowDirection: "origin" | "end",
-  isRotateWithDiscreteAngle: boolean,
-  isResizeCenterPoint: boolean,
-  shouldKeepSidesRatio: boolean,
+  shouldRotateWithDiscreteAngle: boolean,
+  shouldResizeFromCenter: boolean,
+  shouldMaintainAspectRatio: boolean,
   pointerX: number,
   pointerY: number,
   centerX: number,
         element,
         pointerX,
         pointerY,
-        isRotateWithDiscreteAngle,
+        shouldRotateWithDiscreteAngle,
       );
       updateBoundElements(element);
     } else if (
       reshapeSingleTwoPointElement(
         element,
         resizeArrowDirection,
-        isRotateWithDiscreteAngle,
+        shouldRotateWithDiscreteAngle,
         pointerX,
         pointerY,
       );
       resizeSingleTextElement(
         element,
         transformHandleType,
-        isResizeCenterPoint,
+        shouldResizeFromCenter,
         pointerX,
         pointerY,
       );
     } else if (transformHandleType) {
       resizeSingleElement(
         pointerDownState.originalElements.get(element.id) as typeof element,
-        shouldKeepSidesRatio,
+        shouldMaintainAspectRatio,
         element,
         transformHandleType,
-        isResizeCenterPoint,
+        shouldResizeFromCenter,
         pointerX,
         pointerY,
       );
         selectedElements,
         pointerX,
         pointerY,
-        isRotateWithDiscreteAngle,
+        shouldRotateWithDiscreteAngle,
         centerX,
         centerY,
       );
   element: NonDeletedExcalidrawElement,
   pointerX: number,
   pointerY: number,
-  isRotateWithDiscreteAngle: boolean,
+  shouldRotateWithDiscreteAngle: boolean,
 ) => {
   const [x1, y1, x2, y2] = getElementAbsoluteCoords(element);
   const cx = (x1 + x2) / 2;
   const cy = (y1 + y2) / 2;
   let angle = (5 * Math.PI) / 2 + Math.atan2(pointerY - cy, pointerX - cx);
-  if (isRotateWithDiscreteAngle) {
+  if (shouldRotateWithDiscreteAngle) {
     angle += SHIFT_LOCKING_ANGLE / 2;
     angle -= angle % SHIFT_LOCKING_ANGLE;
   }
 export const reshapeSingleTwoPointElement = (
   element: NonDeleted<ExcalidrawLinearElement>,
   resizeArrowDirection: "origin" | "end",
-  isRotateWithDiscreteAngle: boolean,
+  shouldRotateWithDiscreteAngle: boolean,
   pointerX: number,
   pointerY: number,
 ) => {
           element.x + element.points[1][0] - rotatedX,
           element.y + element.points[1][1] - rotatedY,
         ];
-  if (isRotateWithDiscreteAngle) {
+  if (shouldRotateWithDiscreteAngle) {
     [width, height] = getPerfectElementSizeWithRotation(
       element.type,
       width,
 
 const getSidesForTransformHandle = (
   transformHandleType: TransformHandleType,
-  isResizeFromCenter: boolean,
+  shouldResizeFromCenter: boolean,
 ) => {
   return {
     n:
       /^(n|ne|nw)$/.test(transformHandleType) ||
-      (isResizeFromCenter && /^(s|se|sw)$/.test(transformHandleType)),
+      (shouldResizeFromCenter && /^(s|se|sw)$/.test(transformHandleType)),
     s:
       /^(s|se|sw)$/.test(transformHandleType) ||
-      (isResizeFromCenter && /^(n|ne|nw)$/.test(transformHandleType)),
+      (shouldResizeFromCenter && /^(n|ne|nw)$/.test(transformHandleType)),
     w:
       /^(w|nw|sw)$/.test(transformHandleType) ||
-      (isResizeFromCenter && /^(e|ne|se)$/.test(transformHandleType)),
+      (shouldResizeFromCenter && /^(e|ne|se)$/.test(transformHandleType)),
     e:
       /^(e|ne|se)$/.test(transformHandleType) ||
-      (isResizeFromCenter && /^(w|nw|sw)$/.test(transformHandleType)),
+      (shouldResizeFromCenter && /^(w|nw|sw)$/.test(transformHandleType)),
   };
 };
 
 const resizeSingleTextElement = (
   element: NonDeleted<ExcalidrawTextElement>,
   transformHandleType: "nw" | "ne" | "sw" | "se",
-  isResizeFromCenter: boolean,
+  shouldResizeFromCenter: boolean,
   pointerX: number,
   pointerY: number,
 ) => {
     const deltaX2 = (x2 - nextX2) / 2;
     const deltaY2 = (y2 - nextY2) / 2;
     const [nextElementX, nextElementY] = adjustXYWithRotation(
-      getSidesForTransformHandle(transformHandleType, isResizeFromCenter),
+      getSidesForTransformHandle(transformHandleType, shouldResizeFromCenter),
       element.x,
       element.y,
       element.angle,
 
 export const resizeSingleElement = (
   stateAtResizeStart: NonDeletedExcalidrawElement,
-  shouldKeepSidesRatio: boolean,
+  shouldMaintainAspectRatio: boolean,
   element: NonDeletedExcalidrawElement,
   transformHandleDirection: TransformHandleDirection,
-  isResizeFromCenter: boolean,
+  shouldResizeFromCenter: boolean,
   pointerX: number,
   pointerY: number,
 ) => {
   let eleNewHeight = element.height * scaleY;
 
   // adjust dimensions for resizing from center
-  if (isResizeFromCenter) {
+  if (shouldResizeFromCenter) {
     eleNewWidth = 2 * eleNewWidth - eleInitialWidth;
     eleNewHeight = 2 * eleNewHeight - eleInitialHeight;
   }
 
   // adjust dimensions to keep sides ratio
-  if (shouldKeepSidesRatio) {
+  if (shouldMaintainAspectRatio) {
     const widthRatio = Math.abs(eleNewWidth) / eleInitialWidth;
     const heightRatio = Math.abs(eleNewHeight) / eleInitialHeight;
     if (transformHandleDirection.length === 1) {
   }
 
   // Keeps opposite handle fixed during resize
-  if (shouldKeepSidesRatio) {
+  if (shouldMaintainAspectRatio) {
     if (["s", "n"].includes(transformHandleDirection)) {
       newTopLeft[0] = startCenter[0] - newBoundsWidth / 2;
     }
     }
   }
 
-  if (isResizeFromCenter) {
+  if (shouldResizeFromCenter) {
     newTopLeft[0] = startCenter[0] - Math.abs(newBoundsWidth) / 2;
     newTopLeft[1] = startCenter[1] - Math.abs(newBoundsHeight) / 2;
   }
     ...rescaledPoints,
   };
 
+  if ("scale" in element && "scale" in stateAtResizeStart) {
+    mutateElement(element, {
+      scale: [
+        // defaulting because scaleX/Y can be 0/-0
+        (Math.sign(scaleX) || stateAtResizeStart.scale[0]) *
+          stateAtResizeStart.scale[0],
+        (Math.sign(scaleY) || stateAtResizeStart.scale[1]) *
+          stateAtResizeStart.scale[1],
+      ],
+    });
+  }
+
   if (
     resizedElement.width !== 0 &&
     resizedElement.height !== 0 &&
   elements: readonly NonDeletedExcalidrawElement[],
   pointerX: number,
   pointerY: number,
-  isRotateWithDiscreteAngle: boolean,
+  shouldRotateWithDiscreteAngle: boolean,
   centerX: number,
   centerY: number,
 ) => {
   let centerAngle =
     (5 * Math.PI) / 2 + Math.atan2(pointerY - centerY, pointerX - centerX);
-  if (isRotateWithDiscreteAngle) {
+  if (shouldRotateWithDiscreteAngle) {
     centerAngle += SHIFT_LOCKING_ANGLE / 2;
     centerAngle -= centerAngle % SHIFT_LOCKING_ANGLE;
   }

src/element/typeChecks.ts

   ExcalidrawBindableElement,
   ExcalidrawGenericElement,
   ExcalidrawFreeDrawElement,
+  InitializedExcalidrawImageElement,
+  ExcalidrawImageElement,
 } from "./types";
 
 export const isGenericElement = (
   );
 };
 
+export const isInitializedImageElement = (
+  element: ExcalidrawElement | null,
+): element is InitializedExcalidrawImageElement => {
+  return !!element && element.type === "image" && !!element.fileId;
+};
+
+export const isImageElement = (
+  element: ExcalidrawElement | null,
+): element is ExcalidrawImageElement => {
+  return !!element && element.type === "image";
+};
+
 export const isTextElement = (
   element: ExcalidrawElement | null,
 ): element is ExcalidrawTextElement => {

src/element/types.ts

   type: "ellipse";
 };
 
+export type ExcalidrawImageElement = _ExcalidrawElementBase &
+  Readonly<{
+    type: "image";
+    fileId: FileId | null;
+    /** whether respective file is persisted */
+    status: "pending" | "saved" | "error";
+    /** X and Y scale factors <-1, 1>, used for image axis flipping */
+    scale: [number, number];
+  }>;
+
+export type InitializedExcalidrawImageElement = MarkNonNullable<
+  ExcalidrawImageElement,
+  "fileId"
+>;
+
 /**
  * These are elements that don't have any additional properties.
  */
   | ExcalidrawGenericElement
   | ExcalidrawTextElement
   | ExcalidrawLinearElement
-  | ExcalidrawFreeDrawElement;
+  | ExcalidrawFreeDrawElement
+  | ExcalidrawImageElement;
 
 export type NonDeleted<TElement extends ExcalidrawElement> = TElement & {
-  isDeleted: false;
+  isDeleted: boolean;
 };
 
 export type NonDeletedExcalidrawElement = NonDeleted<ExcalidrawElement>;
   | ExcalidrawRectangleElement
   | ExcalidrawDiamondElement
   | ExcalidrawEllipseElement
-  | ExcalidrawTextElement;
+  | ExcalidrawTextElement
+  | ExcalidrawImageElement;
 
 export type PointBinding = {
   elementId: ExcalidrawBindableElement["id"];
     simulatePressure: boolean;
     lastCommittedPoint: Point | null;
   }>;
+
+export type FileId = string & { _brand: "FileId" };

src/excalidraw-app/app_constants.ts

 // time constants (ms)
 export const SAVE_TO_LOCAL_STORAGE_TIMEOUT = 300;
 export const INITIAL_SCENE_UPDATE_TIMEOUT = 5000;
+export const FILE_UPLOAD_TIMEOUT = 300;
+export const LOAD_IMAGES_TIMEOUT = 500;
 export const SYNC_FULL_SCENE_INTERVAL_MS = 20000;
 
+export const FILE_UPLOAD_MAX_BYTES = 3 * 1024 * 1024; // 3 MiB
+// 1 year (https://stackoverflow.com/a/25201898/927631)
+export const FILE_CACHE_MAX_AGE_SEC = 31536000;
+
 export const BROADCAST = {
   SERVER_VOLATILE: "server-volatile-broadcast",
   SERVER: "server-broadcast",
   INIT = "SCENE_INIT",
   UPDATE = "SCENE_UPDATE",
 }
+
+export const FIREBASE_STORAGE_PREFIXES = {
+  shareLinkFiles: `/files/shareLinks`,
+  collabFiles: `/files/rooms`,
+};

src/excalidraw-app/collab/CollabWrapper.tsx

 import { ErrorDialog } from "../../components/ErrorDialog";
 import { APP_NAME, ENV, EVENT } from "../../constants";
 import { ImportedDataState } from "../../data/types";
-import { ExcalidrawElement } from "../../element/types";
+import {
+  ExcalidrawElement,
+  InitializedExcalidrawImageElement,
+} from "../../element/types";
 import {
   getElementMap,
   getSceneVersion,
 } from "../../packages/excalidraw/index";
 import { Collaborator, Gesture } from "../../types";
-import { resolvablePromise, withBatchedUpdates } from "../../utils";
 import {
+  preventUnload,
+  resolvablePromise,
+  withBatchedUpdates,
+} from "../../utils";
+import {
+  FILE_UPLOAD_MAX_BYTES,
+  FIREBASE_STORAGE_PREFIXES,
   INITIAL_SCENE_UPDATE_TIMEOUT,
+  LOAD_IMAGES_TIMEOUT,
   SCENE,
   SYNC_FULL_SCENE_INTERVAL_MS,
 } from "../app_constants";
 } from "../data";
 import {
   isSavedToFirebase,
+  loadFilesFromFirebase,
   loadFromFirebase,
+  saveFilesToFirebase,
   saveToFirebase,
 } from "../data/firebase";
 import {
 import { IDLE_THRESHOLD, ACTIVE_THRESHOLD } from "../../constants";
 import { trackEvent } from "../../analytics";
 import { isInvisiblySmallElement } from "../../element";
+import {
+  encodeFilesForUpload,
+  FileManager,
+  updateStaleImageStatuses,
+} from "../data/FileManager";
+import { AbortError } from "../../errors";
+import {
+  isImageElement,
+  isInitializedImageElement,
+} from "../../element/typeChecks";
+import { mutateElement } from "../../element/mutateElement";
 
 interface CollabState {
   modalIsShown: boolean;
   initializeSocketClient: CollabInstance["initializeSocketClient"];
   onCollabButtonClick: CollabInstance["onCollabButtonClick"];
   broadcastElements: CollabInstance["broadcastElements"];
+  fetchImageFilesFromFirebase: CollabInstance["fetchImageFilesFromFirebase"];
 }
 
 type ReconciledElements = readonly ExcalidrawElement[] & {
 
 interface Props {
   excalidrawAPI: ExcalidrawImperativeAPI;
+  onRoomClose?: () => void;
 }
 
 const {
 
 class CollabWrapper extends PureComponent<Props, CollabState> {
   portal: Portal;
+  fileManager: FileManager;
   excalidrawAPI: Props["excalidrawAPI"];
   isCollaborating: boolean = false;
   activeIntervalId: number | null;
   idleTimeoutId: number | null;
 
-  private socketInitializationTimer?: NodeJS.Timeout;
+  private socketInitializationTimer?: number;
   private lastBroadcastedOrReceivedSceneVersion: number = -1;
   private collaborators = new Map<string, Collaborator>();
 
       activeRoomLink: "",
     };
     this.portal = new Portal(this);
+    this.fileManager = new FileManager({
+      getFiles: async (fileIds) => {
+        const { roomId, roomKey } = this.portal;
+        if (!roomId || !roomKey) {
+          throw new AbortError();
+        }
+
+        return loadFilesFromFirebase(`files/rooms/${roomId}`, roomKey, fileIds);
+      },
+      saveFiles: async ({ addedFiles }) => {
+        const { roomId, roomKey } = this.portal;
+        if (!roomId || !roomKey) {
+          throw new AbortError();
+        }
+
+        return saveFilesToFirebase({
+          prefix: `${FIREBASE_STORAGE_PREFIXES.collabFiles}/${roomId}`,
+          files: await encodeFilesForUpload({
+            files: addedFiles,
+            encryptionKey: roomKey,
+            maxBytes: FILE_UPLOAD_MAX_BYTES,
+          }),
+        });
+      },
+    });
     this.excalidrawAPI = props.excalidrawAPI;
     this.activeIntervalId = null;
     this.idleTimeoutId = null;
 
     if (
       this.isCollaborating &&
-      !isSavedToFirebase(this.portal, syncableElements)
+      (this.fileManager.shouldPreventUnload(syncableElements) ||
+        !isSavedToFirebase(this.portal, syncableElements))
     ) {
       // this won't run in time if user decides to leave the site, but
       //  the purpose is to run in immediately after user decides to stay
       this.saveCollabRoomToFirebase(syncableElements);
 
-      event.preventDefault();
-      // NOTE: modern browsers no longer allow showing a custom message here
-      event.returnValue = "";
+      preventUnload(event);
     }
 
     if (this.isCollaborating || this.portal.roomId) {
       window.history.pushState({}, APP_NAME, window.location.origin);
       this.destroySocketClient();
       trackEvent("share", "room closed");
+
+      this.props.onRoomClose?.();
+
+      const elements = this.excalidrawAPI
+        .getSceneElementsIncludingDeleted()
+        .map((element) => {
+          if (isImageElement(element) && element.status === "saved") {
+            return mutateElement(element, { status: "pending" }, false);
+          }
+          return element;
+        });
+
+      this.excalidrawAPI.updateScene({
+        elements,
+        commitToHistory: false,
+      });
     }
   };
 
       });
       this.isCollaborating = false;
     }
+    this.lastBroadcastedOrReceivedSceneVersion = -1;
     this.portal.close();
+    this.fileManager.reset();
+  };
+
+  private fetchImageFilesFromFirebase = async (scene: {
+    elements: readonly ExcalidrawElement[];
+  }) => {
+    const unfetchedImages = scene.elements
+      .filter((element) => {
+        return (
+          isInitializedImageElement(element) &&
+          !this.fileManager.isFileHandled(element.fileId) &&
+          !element.isDeleted &&
+          element.status === "saved"
+        );
+      })
+      .map((element) => (element as InitializedExcalidrawImageElement).fileId);
+
+    return await this.fileManager.getFiles(unfetchedImages);
   };
 
   private initializeSocketClient = async (
         console.error(error);
       }
     } else {
-      const elements = this.excalidrawAPI.getSceneElements();
+      const elements = this.excalidrawAPI.getSceneElements().map((element) => {
+        if (isImageElement(element) && element.status === "saved") {
+          return mutateElement(
+            element,
+            { status: "pending" },
+            /* informMutation */ false,
+          );
+        }
+        return element;
+      });
       // remove deleted elements from elements array & history to ensure we don't
       // expose potentially sensitive user data in case user manually deletes
       // existing elements (or clears scene), which would otherwise be persisted
         elements,
         commitToHistory: true,
       });
+
+      this.broadcastElements(elements);
+
+      const syncableElements = this.getSyncableElements(elements);
+      this.saveCollabRoomToFirebase(syncableElements);
     }
 
     // fallback in case you're not alone in the room but still don't receive
     // initial SCENE_UPDATE message
-    this.socketInitializationTimer = setTimeout(() => {
+    this.socketInitializationTimer = window.setTimeout(() => {
       this.initializeSocket();
       scenePromise.resolve(null);
     }, INITIAL_SCENE_UPDATE_TIMEOUT);
     return newElements as ReconciledElements;
   };
 
+  private loadImageFiles = throttle(async () => {
+    const {
+      loadedFiles,
+      erroredFiles,
+    } = await this.fetchImageFilesFromFirebase({
+      elements: this.excalidrawAPI.getSceneElementsIncludingDeleted(),
+    });
+
+    this.excalidrawAPI.addFiles(loadedFiles);
+
+    updateStaleImageStatuses({
+      excalidrawAPI: this.excalidrawAPI,
+      erroredFiles,
+      elements: this.excalidrawAPI.getSceneElementsIncludingDeleted(),
+    });
+  }, LOAD_IMAGES_TIMEOUT);
+
   private handleRemoteSceneUpdate = (
     elements: ReconciledElements,
     { init = false }: { init?: boolean } = {},
     // undo, a user makes a change, and then try to redo, your element(s) will be lost. However,
     // right now we think this is the right tradeoff.
     this.excalidrawAPI.history.clear();
+
+    this.loadImageFiles();
   };
 
   private onPointerMove = () => {
     this.contextValue.initializeSocketClient = this.initializeSocketClient;
     this.contextValue.onCollabButtonClick = this.onCollabButtonClick;
     this.contextValue.broadcastElements = this.broadcastElements;
+    this.contextValue.fetchImageFilesFromFirebase = this.fetchImageFilesFromFirebase;
     return this.contextValue;
   };
 

src/excalidraw-app/collab/Portal.tsx

 import CollabWrapper from "./CollabWrapper";
 
 import { ExcalidrawElement } from "../../element/types";
-import { BROADCAST, SCENE } from "../app_constants";
+import { BROADCAST, FILE_UPLOAD_TIMEOUT, SCENE } from "../app_constants";
 import { UserIdleState } from "../../types";
 import { trackEvent } from "../../analytics";
+import { throttle } from "lodash";
+import { mutateElement } from "../../element/mutateElement";
 
 class Portal {
   collab: CollabWrapper;
     }
   }
 
+  queueFileUpload = throttle(async () => {
+    try {
+      await this.collab.fileManager.saveFiles({
+        elements: this.collab.excalidrawAPI.getSceneElementsIncludingDeleted(),
+        files: this.collab.excalidrawAPI.getFiles(),
+      });
+    } catch (error) {
+      this.collab.excalidrawAPI.updateScene({
+        appState: {
+          errorMessage: error.message,
+        },
+      });
+    }
+
+    this.collab.excalidrawAPI.updateScene({
+      elements: this.collab.excalidrawAPI
+        .getSceneElementsIncludingDeleted()
+        .map((element) => {
+          if (this.collab.fileManager.shouldUpdateImageElementStatus(element)) {
+            // this will signal collaborators to pull image data from server
+            // (using mutation instead of newElementWith otherwise it'd break
+            // in-progress dragging)
+            return mutateElement(
+              element,
+              { status: "saved" },
+              /* informMutation */ false,
+            );
+          }
+          return element;
+        }),
+    });
+  }, FILE_UPLOAD_TIMEOUT);
+
   broadcastScene = async (
     sceneType: SCENE.INIT | SCENE.UPDATE,
     syncableElements: ExcalidrawElement[],
       data as SocketUpdateData,
     );
 
+    this.queueFileUpload();
+
     if (syncAll && this.collab.isCollaborating) {
       await Promise.all([
         broadcastPromise,

src/excalidraw-app/components/ExportToExcalidrawPlus.tsx

 import { Card } from "../../components/Card";
 import { ToolButton } from "../../components/ToolButton";
 import { serializeAsJSON } from "../../data/json";
-import { getImportedKey, createIV, generateEncryptionKey } from "../data";
-import { loadFirebaseStorage } from "../data/firebase";
-import { NonDeletedExcalidrawElement } from "../../element/types";
-import { AppState } from "../../types";
+import { loadFirebaseStorage, saveFilesToFirebase } from "../data/firebase";
+import { FileId, NonDeletedExcalidrawElement } from "../../element/types";
+import { AppState, BinaryFileData, BinaryFiles } from "../../types";
 import { nanoid } from "nanoid";
 import { t } from "../../i18n";
 import { excalidrawPlusIcon } from "./icons";
-
-const encryptData = async (
-  key: string,
-  json: string,
-): Promise<{ blob: Blob; iv: Uint8Array }> => {
-  const importedKey = await getImportedKey(key, "encrypt");
-  const iv = createIV();
-  const encoded = new TextEncoder().encode(json);
-  const ciphertext = await window.crypto.subtle.encrypt(
-    {
-      name: "AES-GCM",
-      iv,
-    },
-    importedKey,
-    encoded,
-  );
-
-  return { blob: new Blob([new Uint8Array(ciphertext)]), iv };
-};
+import { encryptData, generateEncryptionKey } from "../../data/encryption";
+import { isInitializedImageElement } from "../../element/typeChecks";
+import { FILE_UPLOAD_MAX_BYTES } from "../app_constants";
+import { encodeFilesForUpload } from "../data/FileManager";
+import { MIME_TYPES } from "../../constants";
 
 const exportToExcalidrawPlus = async (
   elements: readonly NonDeletedExcalidrawElement[],
   appState: AppState,
+  files: BinaryFiles,
 ) => {
   const firebase = await loadFirebaseStorage();
 
   const id = `${nanoid(12)}`;
 
-  const key = (await generateEncryptionKey())!;
+  const encryptionKey = (await generateEncryptionKey())!;
   const encryptedData = await encryptData(
-    key,
-    serializeAsJSON(elements, appState),
+    encryptionKey,
+    serializeAsJSON(elements, appState, files, "database"),
   );
 
-  const blob = new Blob([encryptedData.iv, encryptedData.blob], {
-    type: "application/octet-stream",
-  });
+  const blob = new Blob(
+    [encryptedData.iv, new Uint8Array(encryptedData.encryptedBuffer)],
+    {
+      type: MIME_TYPES.binary,
+    },
+  );
 
   await firebase
     .storage()
     .ref(`/migrations/scenes/${id}`)
     .put(blob, {
       customMetadata: {
-        data: JSON.stringify({ version: 1, name: appState.name }),
+        data: JSON.stringify({ version: 2, name: appState.name }),
         created: Date.now().toString(),
       },
     });
 
-  window.open(`https://plus.excalidraw.com/import?excalidraw=${id},${key}`);
+  const filesMap = new Map<FileId, BinaryFileData>();
+  for (const element of elements) {
+    if (isInitializedImageElement(element) && files[element.fileId]) {
+      filesMap.set(element.fileId, files[element.fileId]);
+    }
+  }
+
+  if (filesMap.size) {
+    const filesToUpload = await encodeFilesForUpload({
+      files: filesMap,
+      encryptionKey,
+      maxBytes: FILE_UPLOAD_MAX_BYTES,
+    });
+
+    await saveFilesToFirebase({
+      prefix: `/migrations/files/scenes/${id}`,
+      files: filesToUpload,
+    });
+  }
+
+  window.open(
+    `https://plus.excalidraw.com/import?excalidraw=${id},${encryptionKey}`,
+  );
 };
 
 export const ExportToExcalidrawPlus: React.FC<{
   elements: readonly NonDeletedExcalidrawElement[];
   appState: AppState;
+  files: BinaryFiles;
   onError: (error: Error) => void;
-}> = ({ elements, appState, onError }) => {
+}> = ({ elements, appState, files, onError }) => {
   return (
     <Card color="indigo">
       <div className="Card-icon">{excalidrawPlusIcon}</div>
         showAriaLabel={true}
         onClick={async () => {
           try {
-            await exportToExcalidrawPlus(elements, appState);
+            await exportToExcalidrawPlus(elements, appState, files);
           } catch (error) {
             console.error(error);
             onError(new Error(t("exportDialog.excalidrawplus_exportError")));

src/excalidraw-app/data/FileManager.ts

+import { compressData } from "../../data/encode";
+import { mutateElement } from "../../element/mutateElement";
+import { isInitializedImageElement } from "../../element/typeChecks";
+import {
+  ExcalidrawElement,
+  ExcalidrawImageElement,
+  FileId,
+  InitializedExcalidrawImageElement,
+} from "../../element/types";
+import { t } from "../../i18n";
+import {
+  BinaryFileData,
+  BinaryFileMetadata,
+  ExcalidrawImperativeAPI,
+  BinaryFiles,
+} from "../../types";
+
+export class FileManager {
+  /** files being fetched */
+  private fetchingFiles = new Map<ExcalidrawImageElement["fileId"], true>();
+  /** files being saved */
+  private savingFiles = new Map<ExcalidrawImageElement["fileId"], true>();
+  /* files already saved to persistent storage */
+  private savedFiles = new Map<ExcalidrawImageElement["fileId"], true>();
+  private erroredFiles = new Map<ExcalidrawImageElement["fileId"], true>();
+
+  private _getFiles;
+  private _saveFiles;
+
+  constructor({
+    getFiles,
+    saveFiles,
+  }: {
+    getFiles: (
+      fileIds: FileId[],
+    ) => Promise<{
+      loadedFiles: BinaryFileData[];
+      erroredFiles: Map<FileId, true>;
+    }>;
+    saveFiles: (data: {
+      addedFiles: Map<FileId, BinaryFileData>;
+    }) => Promise<{
+      savedFiles: Map<FileId, true>;
+      erroredFiles: Map<FileId, true>;
+    }>;
+  }) {
+    this._getFiles = getFiles;
+    this._saveFiles = saveFiles;
+  }
+
+  /**
+   * returns whether file is already saved or being processed
+   */
+  isFileHandled = (id: FileId) => {
+    return (
+      this.savedFiles.has(id) ||
+      this.fetchingFiles.has(id) ||
+      this.savingFiles.has(id) ||
+      this.erroredFiles.has(id)
+    );
+  };
+
+  isFileSaved = (id: FileId) => {
+    return this.savedFiles.has(id);
+  };
+
+  saveFiles = async ({
+    elements,
+    files,
+  }: {
+    elements: readonly ExcalidrawElement[];
+    files: BinaryFiles;
+  }) => {
+    const addedFiles: Map<FileId, BinaryFileData> = new Map();
+
+    for (const element of elements) {
+      if (
+        isInitializedImageElement(element) &&
+        files[element.fileId] &&
+        !this.isFileHandled(element.fileId)
+      ) {
+        addedFiles.set(element.fileId, files[element.fileId]);
+        this.savingFiles.set(element.fileId, true);
+      }
+    }
+
+    try {
+      const { savedFiles, erroredFiles } = await this._saveFiles({
+        addedFiles,
+      });
+
+      for (const [fileId] of savedFiles) {
+        this.savedFiles.set(fileId, true);
+      }
+
+      return {
+        savedFiles,
+        erroredFiles,
+      };
+    } finally {
+      for (const [fileId] of addedFiles) {
+        this.savingFiles.delete(fileId);
+      }
+    }
+  };
+
+  getFiles = async (
+    ids: FileId[],
+  ): Promise<{
+    loadedFiles: BinaryFileData[];
+    erroredFiles: Map<FileId, true>;
+  }> => {
+    if (!ids.length) {
+      return {
+        loadedFiles: [],
+        erroredFiles: new Map(),
+      };
+    }
+    for (const id of ids) {
+      this.fetchingFiles.set(id, true);
+    }
+
+    try {
+      const { loadedFiles, erroredFiles } = await this._getFiles(ids);
+
+      for (const file of loadedFiles) {
+        this.savedFiles.set(file.id, true);
+      }
+      for (const [fileId] of erroredFiles) {
+        this.erroredFiles.set(fileId, true);
+      }
+
+      return { loadedFiles, erroredFiles };
+    } finally {
+      for (const id of ids) {
+        this.fetchingFiles.delete(id);
+      }
+    }
+  };
+
+  /** a file element prevents unload only if it's being saved regardless of
+   *  its `status`. This ensures that elements who for any reason haven't
+   *  beed set to `saved` status don't prevent unload in future sessions.
+   *  Technically we should prevent unload when the origin client haven't
+   *  yet saved the `status` update to storage, but that should be taken care
+   *  of during regular beforeUnload unsaved files check.
+   */
+  shouldPreventUnload = (elements: readonly ExcalidrawElement[]) => {
+    return elements.some((element) => {
+      return (
+        isInitializedImageElement(element) &&
+        !element.isDeleted &&
+        this.savingFiles.has(element.fileId)
+      );
+    });
+  };
+
+  /**
+   * helper to determine if image element status needs updating
+   */
+  shouldUpdateImageElementStatus = (
+    element: ExcalidrawElement,
+  ): element is InitializedExcalidrawImageElement => {
+    return (
+      isInitializedImageElement(element) &&
+      this.isFileSaved(element.fileId) &&
+      element.status === "pending"
+    );
+  };
+
+  reset() {
+    this.fetchingFiles.clear();
+    this.savingFiles.clear();
+    this.savedFiles.clear();
+    this.erroredFiles.clear();
+  }
+}
+
+export const encodeFilesForUpload = async ({
+  files,
+  maxBytes,
+  encryptionKey,
+}: {
+  files: Map<FileId, BinaryFileData>;
+  maxBytes: number;
+  encryptionKey: string;
+}) => {
+  const processedFiles: {
+    id: FileId;
+    buffer: Uint8Array;
+  }[] = [];
+
+  for (const [id, fileData] of files) {
+    const buffer = new TextEncoder().encode(fileData.dataURL);
+
+    const encodedFile = await compressData<BinaryFileMetadata>(buffer, {
+      encryptionKey,
+      metadata: {
+        id,
+        mimeType: fileData.mimeType,
+        created: Date.now(),
+      },
+    });
+
+    if (buffer.byteLength > maxBytes) {
+      throw new Error(
+        t("errors.fileTooBig", {
+          maxSize: `${Math.trunc(maxBytes / 1024 / 1024)}MB`,
+        }),
+      );
+    }
+
+    processedFiles.push({
+      id,
+      buffer: encodedFile,
+    });
+  }
+
+  return processedFiles;
+};
+
+export const updateStaleImageStatuses = (params: {
+  excalidrawAPI: ExcalidrawImperativeAPI;
+  erroredFiles: Map<FileId, true>;
+  elements: readonly ExcalidrawElement[];
+}) => {
+  if (!params.erroredFiles.size) {
+    return;
+  }
+  params.excalidrawAPI.updateScene({
+    elements: params.excalidrawAPI
+      .getSceneElementsIncludingDeleted()
+      .map((element) => {
+        if (
+          isInitializedImageElement(element) &&
+          params.erroredFiles.has(element.fileId)
+        ) {
+          return mutateElement(
+            element,
+            {
+              status: "error",
+            },
+            false,
+          );
+        }
+        return element;
+      }),
+  });
+};

src/excalidraw-app/data/firebase.ts

-import { getImportedKey } from "../data";
-import { createIV } from "./index";
-import { ExcalidrawElement } from "../../element/types";
+import { ExcalidrawElement, FileId } from "../../element/types";
 import { getSceneVersion } from "../../element";
 import Portal from "../collab/Portal";
 import { restoreElements } from "../../data/restore";
+import { BinaryFileData, BinaryFileMetadata, DataURL } from "../../types";
+import { FILE_CACHE_MAX_AGE_SEC } from "../app_constants";
+import { decompressData } from "../../data/encode";
+import { getImportedKey, createIV } from "../../data/encryption";
+import { MIME_TYPES } from "../../constants";
 
 // private
 // -----------------------------------------------------------------------------
 
+const FIREBASE_CONFIG = JSON.parse(process.env.REACT_APP_FIREBASE_CONFIG);
+
 let firebasePromise: Promise<
   typeof import("firebase/app").default
 > | null = null;
-let firestorePromise: Promise<any> | null = null;
-let firebseStoragePromise: Promise<any> | null = null;
+let firestorePromise: Promise<any> | null | true = null;
+let firebaseStoragePromise: Promise<any> | null | true = null;
+
+let isFirebaseInitialized = false;
 
 const _loadFirebase = async () => {
   const firebase = (
     await import(/* webpackChunkName: "firebase" */ "firebase/app")
   ).default;
 
-  const firebaseConfig = JSON.parse(process.env.REACT_APP_FIREBASE_CONFIG);
-  firebase.initializeApp(firebaseConfig);
+  if (!isFirebaseInitialized) {
+    try {
+      firebase.initializeApp(FIREBASE_CONFIG);
+    } catch (error) {
+      // trying initialize again throws. Usually this is harmless, and happens
+      // mainly in dev (HMR)
+      if (error.code === "app/duplicate-app") {
+        console.warn(error.name, error.code);
+      } else {
+        throw error;
+      }
+    }
+    isFirebaseInitialized = true;
+  }
 
   return firebase;
 };
     firestorePromise = import(
       /* webpackChunkName: "firestore" */ "firebase/firestore"
     );
+  }
+  if (firestorePromise !== true) {
     await firestorePromise;
+    firestorePromise = true;
   }
   return firebase;
 };
 
 export const loadFirebaseStorage = async () => {
   const firebase = await _getFirebase();
-  if (!firebseStoragePromise) {
-    firebseStoragePromise = import(
+  if (!firebaseStoragePromise) {
+    firebaseStoragePromise = import(
       /* webpackChunkName: "storage" */ "firebase/storage"
     );
-    await firebseStoragePromise;
+  }
+  if (firebaseStoragePromise !== true) {
+    await firebaseStoragePromise;
+    firebaseStoragePromise = true;
   }
   return firebase;
 };
 const decryptElements = async (
   key: string,
   iv: Uint8Array,
-  ciphertext: ArrayBuffer,
+  ciphertext: ArrayBuffer | Uint8Array,
 ): Promise<readonly ExcalidrawElement[]> => {
   const importedKey = await getImportedKey(key, "decrypt");
   const decrypted = await window.crypto.subtle.decrypt(
   );
 
   const decodedData = new TextDecoder("utf-8").decode(
-    new Uint8Array(decrypted) as any,
+    new Uint8Array(decrypted),
   );
   return JSON.parse(decodedData);
 };
 ): boolean => {
   if (portal.socket && portal.roomId && portal.roomKey) {
     const sceneVersion = getSceneVersion(elements);
+
     return firebaseSceneVersionCache.get(portal.socket) === sceneVersion;
   }
   // if no room exists, consider the room saved so that we don't unnecessarily
   return true;
 };
 
+export const saveFilesToFirebase = async ({
+  prefix,
+  files,
+}: {
+  prefix: string;
+  files: { id: FileId; buffer: Uint8Array }[];
+}) => {
+  const firebase = await loadFirebaseStorage();
+
+  const erroredFiles = new Map<FileId, true>();
+  const savedFiles = new Map<FileId, true>();
+
+  await Promise.all(
+    files.map(async ({ id, buffer }) => {
+      try {
+        await firebase
+          .storage()
+          .ref(`${prefix}/${id}`)
+          .put(
+            new Blob([buffer], {
+              type: MIME_TYPES.binary,
+            }),
+            {
+              cacheControl: `public, max-age=${FILE_CACHE_MAX_AGE_SEC}`,
+            },
+          );
+        savedFiles.set(id, true);
+      } catch (error) {
+        erroredFiles.set(id, true);
+      }
+    }),
+  );
+
+  return { savedFiles, erroredFiles };
+};
+
 export const saveToFirebase = async (
   portal: Portal,
   elements: readonly ExcalidrawElement[],
 
   return restoreElements(elements, null);
 };
+
+export const loadFilesFromFirebase = async (
+  prefix: string,
+  decryptionKey: string,
+  filesIds: readonly FileId[],
+) => {
+  const loadedFiles: BinaryFileData[] = [];
+  const erroredFiles = new Map<FileId, true>();
+
+  await Promise.all(
+    [...new Set(filesIds)].map(async (id) => {
+      try {
+        const url = `https://firebasestorage.googleapis.com/v0/b/${
+          FIREBASE_CONFIG.storageBucket
+        }/o/${encodeURIComponent(prefix.replace(/^\//, ""))}%2F${id}`;
+        const response = await fetch(`${url}?alt=media`);
+        if (response.status < 400) {
+          const arrayBuffer = await response.arrayBuffer();
+
+          const { data, metadata } = await decompressData<BinaryFileMetadata>(
+            new Uint8Array(arrayBuffer),
+            {
+              decryptionKey,
+            },
+          );
+
+          const dataURL = new TextDecoder().decode(data) as DataURL;
+
+          loadedFiles.push({
+            mimeType: metadata.mimeType || MIME_TYPES.binary,
+            id,
+            dataURL,
+            created: metadata?.created || Date.now(),
+          });
+        }
+      } catch (error) {
+        erroredFiles.set(id, true);
+        console.error(error);
+      }
+    }),
+  );
+
+  return { loadedFiles, erroredFiles };
+};

src/excalidraw-app/data/index.ts

+import {
+  createIV,
+  generateEncryptionKey,
+  getImportedKey,
+  IV_LENGTH_BYTES,
+} from "../../data/encryption";
 import { serializeAsJSON } from "../../data/json";
 import { restore } from "../../data/restore";
 import { ImportedDataState } from "../../data/types";
-import { ExcalidrawElement } from "../../element/types";
+import { isInitializedImageElement } from "../../element/typeChecks";
+import { ExcalidrawElement, FileId } from "../../element/types";
 import { t } from "../../i18n";
-import { AppState, UserIdleState } from "../../types";
+import {
+  AppState,
+  BinaryFileData,
+  BinaryFiles,
+  UserIdleState,
+} from "../../types";
+import { FILE_UPLOAD_MAX_BYTES } from "../app_constants";
+import { encodeFilesForUpload } from "./FileManager";
+import { saveFilesToFirebase } from "./firebase";
 
 const byteToHex = (byte: number): string => `0${byte.toString(16)}`.slice(-2);
 
   return Array.from(arr, byteToHex).join("");
 };
 
-export const generateEncryptionKey = async () => {
-  const key = await window.crypto.subtle.generateKey(
-    {
-      name: "AES-GCM",
-      length: 128,
-    },
-    true, // extractable
-    ["encrypt", "decrypt"],
-  );
-  return (await window.crypto.subtle.exportKey("jwk", key)).k;
-};
-
 export const SOCKET_SERVER = process.env.REACT_APP_SOCKET_SERVER_URL;
 
 export type EncryptedData = {
   _brand: "socketUpdateData";
 };
 
-const IV_LENGTH_BYTES = 12; // 96 bits
-
-export const createIV = () => {
-  const arr = new Uint8Array(IV_LENGTH_BYTES);
-  return window.crypto.getRandomValues(arr);
-};
-
 export const encryptAESGEM = async (
   data: Uint8Array,
   key: string,
     );
 
     const decodedData = new TextDecoder("utf-8").decode(
-      new Uint8Array(decrypted) as any,
+      new Uint8Array(decrypted),
     );
     return JSON.parse(decodedData);
   } catch (error) {
   return `${window.location.origin}${window.location.pathname}#room=${data.roomId},${data.roomKey}`;
 };
 
-export const getImportedKey = (key: string, usage: KeyUsage) =>
-  window.crypto.subtle.importKey(
-    "jwk",
-    {
-      alg: "A128GCM",
-      ext: true,
-      k: key,
-      key_ops: ["encrypt", "decrypt"],
-      kty: "oct",
-    },
-    {
-      name: "AES-GCM",
-      length: 128,
-    },
-    false, // extractable
-    [usage],
-  );
-
 export const decryptImported = async (
-  iv: ArrayBuffer,
+  iv: ArrayBuffer | Uint8Array,
   encrypted: ArrayBuffer,
   privateKey: string,
 ): Promise<ArrayBuffer> => {
 
       // We need to convert the decrypted array buffer to a string
       const string = new window.TextDecoder("utf-8").decode(
-        new Uint8Array(decrypted) as any,
+        new Uint8Array(decrypted),
       );
       data = JSON.parse(string);
     } else {
   return {
     elements: data.elements,
     appState: data.appState,
+    // note: this will always be empty because we're not storing files
+    // in the scene database/localStorage, and instead fetch them async
+    // from a different database
+    files: data.files,
     commitToHistory: false,
   };
 };
 export const exportToBackend = async (
   elements: readonly ExcalidrawElement[],
   appState: AppState,
+  files: BinaryFiles,
 ) => {
-  const json = serializeAsJSON(elements, appState);
+  const json = serializeAsJSON(elements, appState, files, "database");
   const encoded = new TextEncoder().encode(json);
 
-  const key = await window.crypto.subtle.generateKey(
+  const cryptoKey = await window.crypto.subtle.generateKey(
     {
       name: "AES-GCM",
       length: 128,
       name: "AES-GCM",
       iv,
     },
-    key,
+    cryptoKey,
     encoded,
   );
 
 
   // We use jwk encoding to be able to extract just the base64 encoded key.
   // We will hardcode the rest of the attributes when importing back the key.
-  const exportedKey = await window.crypto.subtle.exportKey("jwk", key);
+  const exportedKey = await window.crypto.subtle.exportKey("jwk", cryptoKey);
 
   try {
+    const filesMap = new Map<FileId, BinaryFileData>();
+    for (const element of elements) {
+      if (isInitializedImageElement(element) && files[element.fileId]) {
+        filesMap.set(element.fileId, files[element.fileId]);
+      }
+    }
+
+    const encryptionKey = exportedKey.k!;
+
+    const filesToUpload = await encodeFilesForUpload({
+      files: filesMap,
+      encryptionKey,
+      maxBytes: FILE_UPLOAD_MAX_BYTES,
+    });
+
     const response = await fetch(BACKEND_V2_POST, {
       method: "POST",
       body: payload,
       const url = new URL(window.location.href);
       // We need to store the key (and less importantly the id) as hash instead
       // of queryParam in order to never send it to the server
-      url.hash = `json=${json.id},${exportedKey.k!}`;
+      url.hash = `json=${json.id},${encryptionKey}`;
       const urlString = url.toString();
+
+      await saveFilesToFirebase({
+        prefix: `/files/shareLinks/${json.id}`,
+        files: filesToUpload,
+      });
+
       window.prompt(`🔒${t("alerts.uploadedSecurly")}`, urlString);
     } else if (json.error_class === "RequestTooLargeError") {
       window.alert(t("alerts.couldNotCreateShareableLinkTooBig"));

src/excalidraw-app/index.tsx

 import { ImportedDataState } from "../data/types";
 import {
   ExcalidrawElement,
+  FileId,
   NonDeletedExcalidrawElement,
 } from "../element/types";
 import { useCallbackRefState } from "../hooks/useCallbackRefState";
   defaultLang,
   languages,
 } from "../packages/excalidraw/index";
-import { AppState, LibraryItems, ExcalidrawImperativeAPI } from "../types";
+import {
+  AppState,
+  LibraryItems,
+  ExcalidrawImperativeAPI,
+  BinaryFileData,
+  BinaryFiles,
+} from "../types";
 import {
   debounce,
   getVersion,
+  preventUnload,
   ResolvablePromise,
   resolvablePromise,
 } from "../utils";
-import { SAVE_TO_LOCAL_STORAGE_TIMEOUT } from "./app_constants";
+import {
+  FIREBASE_STORAGE_PREFIXES,
+  SAVE_TO_LOCAL_STORAGE_TIMEOUT,
+} from "./app_constants";
 import CollabWrapper, {
   CollabAPI,
   CollabContext,
 import "./index.scss";
 import { ExportToExcalidrawPlus } from "./components/ExportToExcalidrawPlus";
 
+import { getMany, set, del, keys, createStore } from "idb-keyval";
+import { FileManager, updateStaleImageStatuses } from "./data/FileManager";
+import { mutateElement } from "../element/mutateElement";
+import { isInitializedImageElement } from "../element/typeChecks";
+import { loadFilesFromFirebase } from "./data/firebase";
+
+const filesStore = createStore("files-db", "files-store");
+
+const clearObsoleteFilesFromIndexedDB = async (opts: {
+  currentFileIds: FileId[];
+}) => {
+  const allIds = await keys(filesStore);
+  for (const id of allIds) {
+    if (!opts.currentFileIds.includes(id as FileId)) {
+      del(id, filesStore);
+    }
+  }
+};
+
+const localFileStorage = new FileManager({
+  getFiles(ids) {
+    return getMany(ids, filesStore).then(
+      (filesData: (BinaryFileData | undefined)[]) => {
+        const loadedFiles: BinaryFileData[] = [];
+        const erroredFiles = new Map<FileId, true>();
+        filesData.forEach((data, index) => {
+          const id = ids[index];
+          if (data) {
+            loadedFiles.push(data);
+          } else {
+            erroredFiles.set(id, true);
+          }
+        });
+
+        return { loadedFiles, erroredFiles };
+      },
+    );
+  },
+  async saveFiles({ addedFiles }) {
+    const savedFiles = new Map<FileId, true>();
+    const erroredFiles = new Map<FileId, true>();
+
+    await Promise.all(
+      [...addedFiles].map(async ([id, fileData]) => {
+        try {
+          await set(id, fileData, filesStore);
+          savedFiles.set(id, true);
+        } catch (error) {
+          console.error(error);
+          erroredFiles.set(id, true);
+        }
+      }),
+    );
+
+    return { savedFiles, erroredFiles };
+  },
+});
+
 const languageDetector = new LanguageDetector();
 languageDetector.init({
   languageUtils: {
 });
 
 const saveDebounced = debounce(
-  (elements: readonly ExcalidrawElement[], state: AppState) => {
-    saveToLocalStorage(elements, state);
+  async (
+    elements: readonly ExcalidrawElement[],
+    appState: AppState,
+    files: BinaryFiles,
+    onFilesSaved: () => void,
+  ) => {
+    saveToLocalStorage(elements, appState);
+
+    await localFileStorage.saveFiles({
+      elements,
+      files,
+    });
+
+    onFilesSaved();
   },
   SAVE_TO_LOCAL_STORAGE_TIMEOUT,
 );
 
 const initializeScene = async (opts: {
   collabAPI: CollabAPI;
-}): Promise<ImportedDataState | null> => {
+}): Promise<
+  { scene: ImportedDataState | null } & (
+    | { isExternalScene: true; id: string; key: string }
+    | { isExternalScene: false; id?: null; key?: null }
+  )
+> => {
   const searchParams = new URLSearchParams(window.location.search);
   const id = searchParams.get("id");
   const jsonBackendMatch = window.location.hash.match(
         !scene.elements.length ||
         window.confirm(t("alerts.loadSceneOverridePrompt"))
       ) {
-        return data;
+        return { scene: data, isExternalScene };
       }
     } catch (error) {
       return {
-        appState: {
-          errorMessage: t("alerts.invalidSceneUrl"),
+        scene: {
+          appState: {
+            errorMessage: t("alerts.invalidSceneUrl"),
+          },
         },
+        isExternalScene,
       };
     }
   }
 
   if (roomLinkData) {
-    return opts.collabAPI.initializeSocketClient(roomLinkData);
+    return {
+      scene: await opts.collabAPI.initializeSocketClient(roomLinkData),
+      isExternalScene: true,
+      id: roomLinkData.roomId,
+      key: roomLinkData.roomKey,
+    };
   } else if (scene) {
-    return scene;
+    return isExternalScene && jsonBackendMatch
+      ? {
+          scene,
+          isExternalScene,
+          id: jsonBackendMatch[1],
+          key: jsonBackendMatch[2],
+        }
+      : { scene, isExternalScene: false };
   }
-  return null;
+  return { scene: null, isExternalScene: false };
 };
 
 const PlusLinkJSX = (
       return;
     }
 
-    initializeScene({ collabAPI }).then((scene) => {
-      if (scene) {
-        try {
-          scene.libraryItems =
-            JSON.parse(
-              localStorage.getItem(
-                STORAGE_KEYS.LOCAL_STORAGE_LIBRARY,
-              ) as string,
-            ) || [];
-        } catch (e) {
-          console.error(e);
+    const loadImages = (
+      data: ResolutionType<typeof initializeScene>,
+      isInitialLoad = false,
+    ) => {
+      if (!data.scene) {
+        return;
+      }
+      if (collabAPI.isCollaborating()) {
+        if (data.scene.elements) {
+          collabAPI
+            .fetchImageFilesFromFirebase({
+              elements: data.scene.elements,
+            })
+            .then(({ loadedFiles, erroredFiles }) => {
+              excalidrawAPI.addFiles(loadedFiles);
+              updateStaleImageStatuses({
+                excalidrawAPI,
+                erroredFiles,
+                elements: excalidrawAPI.getSceneElementsIncludingDeleted(),
+              });
+            });
+        }
+      } else {
+        const fileIds =
+          data.scene.elements?.reduce((acc, element) => {
+            if (isInitializedImageElement(element)) {
+              return acc.concat(element.fileId);
+            }
+            return acc;
+          }, [] as FileId[]) || [];
+
+        if (data.isExternalScene) {
+          loadFilesFromFirebase(
+            `${FIREBASE_STORAGE_PREFIXES.shareLinkFiles}/${data.id}`,
+            data.key,
+            fileIds,
+          ).then(({ loadedFiles, erroredFiles }) => {
+            excalidrawAPI.addFiles(loadedFiles);
+            updateStaleImageStatuses({
+              excalidrawAPI,
+              erroredFiles,
+              elements: excalidrawAPI.getSceneElementsIncludingDeleted(),
+            });
+          });
+        } else if (isInitialLoad) {
+          if (fileIds.length) {
+            localFileStorage
+              .getFiles(fileIds)
+              .then(({ loadedFiles, erroredFiles }) => {
+                if (loadedFiles.length) {
+                  excalidrawAPI.addFiles(loadedFiles);
+                }
+                updateStaleImageStatuses({
+                  excalidrawAPI,
+                  erroredFiles,
+                  elements: excalidrawAPI.getSceneElementsIncludingDeleted(),
+                });
+              });
+          }
+          // on fresh load, clear unused files from IDB (from previous
+          // session)
+          clearObsoleteFilesFromIndexedDB({ currentFileIds: fileIds });
         }
       }
-      initialStatePromiseRef.current.promise.resolve(scene);
+
+      try {
+        data.scene.libraryItems =
+          JSON.parse(
+            localStorage.getItem(STORAGE_KEYS.LOCAL_STORAGE_LIBRARY) as string,
+          ) || [];
+      } catch (e) {
+        console.error(e);
+      }
+    };
+
+    initializeScene({ collabAPI }).then((data) => {
+      loadImages(data, /* isInitialLoad */ true);
+      initialStatePromiseRef.current.promise.resolve(data.scene);
     });
 
     const onHashChange = (event: HashChangeEvent) => {
         window.history.replaceState({}, "", event.oldURL);
         excalidrawAPI.importLibrary(libraryUrl, hash.get("token"));
       } else {
-        initializeScene({ collabAPI }).then((scene) => {
-          if (scene) {
+        initializeScene({ collabAPI }).then((data) => {
+          loadImages(data);
+          if (data.scene) {
             excalidrawAPI.updateScene({
-              ...scene,
-              appState: restoreAppState(scene.appState, null),
+              ...data.scene,
+              appState: restoreAppState(data.scene.appState, null),
             });
           }
         });
     };
   }, [collabAPI, excalidrawAPI]);
 
+  useEffect(() => {
+    const unloadHandler = (event: BeforeUnloadEvent) => {
+      saveDebounced.flush();
+
+      if (
+        excalidrawAPI &&
+        localFileStorage.shouldPreventUnload(excalidrawAPI.getSceneElements())
+      ) {
+        preventUnload(event);
+      }
+    };
+    window.addEventListener(EVENT.BEFORE_UNLOAD, unloadHandler);
+    return () => {
+      window.removeEventListener(EVENT.BEFORE_UNLOAD, unloadHandler);
+    };
+  }, [excalidrawAPI]);
+
   useEffect(() => {
     languageDetector.cacheUserLanguage(langCode);
   }, [langCode]);
   const onChange = (
     elements: readonly ExcalidrawElement[],
     appState: AppState,
+    files: BinaryFiles,
   ) => {
     if (collabAPI?.isCollaborating()) {
       collabAPI.broadcastElements(elements);
     } else {
-      // collab scenes are persisted to the server, so we don't have to persist
-      // them locally, which has the added benefit of not overwriting whatever
-      // the user was working on before joining
-      saveDebounced(elements, appState);
+      saveDebounced(elements, appState, files, () => {
+        if (excalidrawAPI) {
+          let didChange = false;
+
+          const elements = excalidrawAPI
+            .getSceneElementsIncludingDeleted()
+            .map((element) => {
+              if (localFileStorage.shouldUpdateImageElementStatus(element)) {
+                didChange = true;
+                return mutateElement(
+                  element,
+                  { status: "saved" },
+                  /* informMutation */ false,
+                );
+              }
+              return element;
+            });
+
+          if (didChange) {
+            excalidrawAPI.updateScene({
+              elements,
+            });
+          }
+        }
+      });
     }
   };
 
   const onExportToBackend = async (
     exportedElements: readonly NonDeletedExcalidrawElement[],
     appState: AppState,
+    files: BinaryFiles,
     canvas: HTMLCanvasElement | null,
   ) => {
     if (exportedElements.length === 0) {
     }
     if (canvas) {
       try {
-        await exportToBackend(exportedElements, {
-          ...appState,
-          viewBackgroundColor: appState.exportBackground
-            ? appState.viewBackgroundColor
-            : getDefaultAppState().viewBackgroundColor,
-        });
+        await exportToBackend(
+          exportedElements,
+          {
+            ...appState,
+            viewBackgroundColor: appState.exportBackground
+              ? appState.viewBackgroundColor
+              : getDefaultAppState().viewBackgroundColor,
+          },
+          files,
+        );
       } catch (error) {
         if (error.name !== "AbortError") {
           const { width, height } = canvas;
     localStorage.setItem(STORAGE_KEYS.LOCAL_STORAGE_LIBRARY, serializedItems);
   };
 
+  const onRoomClose = useCallback(() => {
+    localFileStorage.reset();
+  }, []);
+
   return (
     <>
       <Excalidraw
           canvasActions: {
             export: {
               onExportToBackend,
-              renderCustomUI: (elements, appState) => {
+              renderCustomUI: (elements, appState, files) => {
                 return (
                   <ExportToExcalidrawPlus
                     elements={elements}
                     appState={appState}
+                    files={files}
                     onError={(error) => {
                       excalidrawAPI?.updateScene({
                         appState: {
         onLibraryChange={onLibraryChange}
         autoFocus={true}
       />
-      {excalidrawAPI && <CollabWrapper excalidrawAPI={excalidrawAPI} />}
+      {excalidrawAPI && (
+        <CollabWrapper
+          excalidrawAPI={excalidrawAPI}
+          onRoomClose={onRoomClose}
+        />
+      )}
       {errorMessage && (
         <ErrorDialog
           message={errorMessage}

src/global.d.ts

 type MarkRequired<T, RK extends keyof T> = Exclude<T, RK> &
   Required<Pick<T, RK>>;
 
+type MarkNonNullable<T, K extends keyof T> = {
+  [P in K]-?: P extends K ? NonNullable<T[P]> : T[P];
+} &
+  { [P in keyof T]: T[P] };
+
 // PNG encoding/decoding
 // -----------------------------------------------------------------------------
 type TEXtChunk = { name: "tEXt"; data: Uint8Array };
 }
 
 declare module "*.scss";
+
+// --------------------------------------------------------------------------—
+// ensure Uint8Array isn't assignable to ArrayBuffer
+// (due to TS structural typing)
+// https://github.com/microsoft/TypeScript/issues/31311#issuecomment-490690695
+interface ArrayBuffer {
+  private _brand?: "ArrayBuffer";
+}
+interface Uint8Array {
+  private _brand?: "Uint8Array";
+}
+// --------------------------------------------------------------------------—
+
+// https://github.com/nodeca/image-blob-reduce/issues/23#issuecomment-783271848
+declare module "image-blob-reduce" {
+  import { PicaResizeOptions } from "pica";
+  namespace ImageBlobReduce {
+    interface ImageBlobReduce {
+      toBlob(file: File, options: ImageBlobReduceOptions): Promise<Blob>;
+    }
+
+    interface ImageBlobReduceStatic {
+      new (options?: any): ImageBlobReduce;
+
+      (options?: any): ImageBlobReduce;
+    }
+
+    interface ImageBlobReduceOptions extends PicaResizeOptions {
+      max: number;
+    }
+  }
+  const reduce: ImageBlobReduce.ImageBlobReduceStatic;
+  export = reduce;
+}

src/index-node.ts

     width: 0,
     height: 0,
   },
+  {}, // files
   {
     exportBackground: true,
     viewBackgroundColor: "#ffffff",

src/keys.ts

   D: "d",
   E: "e",
   G: "g",
+  I: "i",
   L: "l",
   O: "o",
   P: "p",
   key === KEYS.ARROW_DOWN ||
   key === KEYS.ARROW_UP;
 
-export const getResizeCenterPointKey = (event: MouseEvent | KeyboardEvent) =>
+export const shouldResizeFromCenter = (event: MouseEvent | KeyboardEvent) =>
   event.altKey;
 
-export const getResizeWithSidesSameLengthKey = (
-  event: MouseEvent | KeyboardEvent,
-) => event.shiftKey;
+export const shouldMaintainAspectRatio = (event: MouseEvent | KeyboardEvent) =>
+  event.shiftKey;
 
-export const getRotateWithDiscreteAngleKey = (
+export const shouldRotateWithDiscreteAngle = (
   event: MouseEvent | KeyboardEvent,
 ) => event.shiftKey;

src/locales/en.json

     "errorAddingToLibrary": "Couldn't add item to the library",
     "errorRemovingFromLibrary": "Couldn't remove item from the library",
     "confirmAddLibrary": "This will add {{numShapes}} shape(s) to your library. Are you sure?",
-    "imageDoesNotContainScene": "Importing images isn't supported at the moment.\n\nDid you want to import a scene? This image does not seem to contain any scene data. Have you enabled this during export?",
+    "imageDoesNotContainScene": "This image does not seem to contain any scene data. Have you enabled scene embedding during export?",
     "cannotRestoreFromImage": "Scene couldn't be restored from this image file",
     "invalidSceneUrl": "Couldn't import scene from the supplied URL. It's either malformed, or doesn't contain valid Excalidraw JSON data.",
     "resetLibrary": "This will clear your library. Are you sure?",
     "invalidEncryptionKey": "Encryption key must be of 22 characters. Live collaboration is disabled."
   },
+  "errors": {
+    "unsupportedFileType": "Unsupported file type.",
+    "imageInsertError": "Couldn't insert image. Try again later...",
+    "fileTooBig": "File is too big. Maximum allowed size is {{maxSize}}.",
+    "svgImageInsertError": "Couldn't insert SVG image. The SVG markup looks invalid.",
+    "invalidSVGString": "errors.invalidSVGString"
+  },
   "toolBar": {
     "selection": "Selection",
+    "image": "Insert image",
     "rectangle": "Rectangle",
     "diamond": "Diamond",
     "ellipse": "Ellipse",
     "linearElementMulti": "Click on last point or press Escape or Enter to finish",
     "lockAngle": "You can constrain angle by holding SHIFT",
     "resize": "You can constrain proportions by holding SHIFT while resizing,\nhold ALT to resize from the center",
+    "resizeImage": "You can resize freely by holding SHIFT,\nhold ALT to resize from the center",
     "rotate": "You can constrain angles by holding SHIFT while rotating",
     "lineEditor_info": "Double-click or press Enter to edit points",
     "lineEditor_pointSelected": "Press Delete to remove point, CtrlOrCmd+D to duplicate, or drag to move",
-    "lineEditor_nothingSelected": "Select a point to move or remove, or hold Alt and click to add new points"
+    "lineEditor_nothingSelected": "Select a point to move or remove, or hold Alt and click to add new points",
+    "placeImage": "Click to place the image, or click and drag to set its size manually"
   },
   "canvasError": {
     "cannotShowPreview": "Cannot show preview",

src/packages/excalidraw/CHANGELOG.md

 
 ## Unreleased
 
+- Image support.
+
+  NOTE: the unreleased API is highly unstable and may change significantly before the next stable release. As such it's largely undocumented at this point. You are encouraged to read through the [PR](https://github.com/excalidraw/excalidraw/pull/4011) description if you want to know more about the internals.
+
+  General notes:
+
+  - File data are encoded as DataURLs (base64) for portability reasons.
+
+  [ExcalidrawAPI](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#onLibraryChange):
+
+  - added `getFiles()` to get current `BinaryFiles` (`Record<FileId, BinaryFileData>`). It may contain files that aren't referenced by any element, so if you're persisting the files to a storage, you should compare them against stored elements.
+
+  Excalidraw app props:
+
+  - added `generateIdForFile(file: File)` optional prop so you can generate your own ids for added files.
+  - `onChange(elements, appState, files)` prop callback is now passed `BinaryFiles` as third argument.
+  - `onPaste(data, event)` data prop should contain `data.files` (`BinaryFiles`) if the elements pasted are referencing new files.
+  - `initialData` object now supports additional `files` (`BinaryFiles`) attribute.
+
+  Other notes:
+
+  - `.excalidraw` files may now contain top-level `files` key in format of `Record<FileId, BinaryFileData>` when exporting any (image) elements.
+  - Changes were made to various export utilityies exported from the package so that they take `files`. For now, TypeScript should help you figure the changes out.
+
 ## Excalidraw API
 
 ### Features
 - #### BREAKING CHANGE
   Use `location.hash` when importing libraries to fix installation issues. This will require host apps to add a `hashchange` listener and call the newly exposed `excalidrawAPI.importLibrary(url)` API when applicable [#3320](https://github.com/excalidraw/excalidraw/pull/3320). Check the [readme](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#importlibrary) for more details.
 - Append `location.pathname` to `libraryReturnUrl` default url [#3325](https://github.com/excalidraw/excalidraw/pull/3325).
+- Support image elements [#3424](https://github.com/excalidraw/excalidraw/pull/3424).
 
 ### Build
 

src/packages/excalidraw/README_NEXT.md

 | [`handleKeyboardGlobally`](#handleKeyboardGlobally) | boolean | false | Indicates whether to bind the keyboard events to document. |
 | [`onLibraryChange`](#onLibraryChange) | <pre>(items: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L200">LibraryItems</a>) => void &#124; Promise&lt;any&gt; </pre> |  | The callback if supplied is triggered when the library is updated and receives the library items. |
 | [`autoFocus`](#autoFocus) | boolean | false | Implies whether to focus the Excalidraw component on page load |
+| [`generateIdForFile`](#generateIdForFile) | `(file: File) => string | Promise<string>` | Allows you to override `id` generation for files added on canvas |
 
 ### Dimensions of Excalidraw
 
 | --- | --- | --- |
 | ready | `boolean` | This is set to true once Excalidraw is rendered |
 | readyPromise | [resolvablePromise](https://github.com/excalidraw/excalidraw/blob/master/src/utils.ts#L317) | This promise will be resolved with the api once excalidraw has rendered. This will be helpful when you want do some action on the host app once this promise resolves. For this to work you will have to pass ref as shown [here](#readyPromise) |
-| [updateScene](#updateScene) | <pre>(<a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L207">sceneData</a>)) => void </pre> | updates the scene with the sceneData |
+| [updateScene](#updateScene) | <pre>(scene: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L207">sceneData</a>) => void </pre> | updates the scene with the sceneData |
+| [addFiles](#addFiles) | <pre>(files: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts">BinaryFileData</a>) => void </pre> | add files data to the appState |
 | resetScene | `({ resetLoadingState: boolean }) => void` | Resets the scene. If `resetLoadingState` is passed as true then it will also force set the loading state to false. |
 | getSceneElementsIncludingDeleted | <pre> () => <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement[]</a></pre> | Returns all the elements including the deleted in the scene |
 | getSceneElements | <pre> () => <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement[]</a></pre> | Returns all the elements excluding the deleted in the scene |
 ### `updateScene`
 
 <pre>
-(<a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L207">sceneData</a>)) => void
+(scene: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L207">sceneData</a>) => void
 </pre>
 
 You can use this function to update the scene with the sceneData. It accepts the below attributes.
 | `collaborators` | <pre>Map<string, <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L29">Collaborator></a></pre> | The list of collaborators to be updated in the scene. |
 | `commitToHistory` | `boolean` | Implies if the `history (undo/redo)` should be recorded. Defaults to `false`. |
 
+### `addFiles`
+
+<pre>(files: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts">BinaryFileData</a>) => void </pre>
+
+Adds supplied files data to the `appState.files` cache, on top of existing files present in the cache.
+
 #### `onCollabButtonClick`
 
 This callback is triggered when clicked on the collab button in excalidraw. If not supplied, the collab dialog button is not rendered.
 
 This prop implies whether to focus the Excalidraw component on page load. Defaults to false.
 
+#### `generateIdForFile`
+
+Allows you to override `id` generation for files added on canvas (images). By default, an SHA-1 digest of the file is used.
+
+```
+(file: File) => string | Promise<string>
+```
+
 ### Does it support collaboration ?
 
 No, Excalidraw package doesn't come with collaboration built in, since the implementation is specific to each host app. We expose APIs which you can use to communicate with Excalidraw which you can use to implement it. You can check our own implementation [here](https://github.com/excalidraw/excalidraw/blob/master/src/excalidraw-app/index.tsx).

src/packages/excalidraw/index.tsx

     handleKeyboardGlobally = false,
     onLibraryChange,
     autoFocus = false,
+    generateIdForFile,
   } = props;
 
   const canvasActions = props.UIOptions?.canvasActions;
         handleKeyboardGlobally={handleKeyboardGlobally}
         onLibraryChange={onLibraryChange}
         autoFocus={autoFocus}
+        generateIdForFile={generateIdForFile}
       />
     </InitializeApp>
   );
 export { isLinearElement } from "../../element/typeChecks";
 
 export { FONT_FAMILY, THEME } from "../../constants";
+
+export {
+  mutateElement,
+  newElementWith,
+  bumpVersion,
+} from "../../element/mutateElement";

src/packages/utils.ts

   exportToSvg as _exportToSvg,
 } from "../scene/export";
 import { getDefaultAppState } from "../appState";
-import { AppState } from "../types";
+import { AppState, BinaryFiles } from "../types";
 import { ExcalidrawElement } from "../element/types";
 import { getNonDeletedElements } from "../element";
 import { restore } from "../data/restore";
+import { MIME_TYPES } from "../constants";
 
 type ExportOpts = {
   elements: readonly ExcalidrawElement[];
   appState?: Partial<Omit<AppState, "offsetTop" | "offsetLeft">>;
+  files: BinaryFiles | null;
   getDimensions?: (
     width: number,
     height: number,
 export const exportToCanvas = ({
   elements,
   appState,
+  files,
   getDimensions = (width, height) => ({ width, height, scale: 1 }),
 }: ExportOpts) => {
   const { elements: restoredElements, appState: restoredAppState } = restore(
   return _exportToCanvas(
     getNonDeletedElements(restoredElements),
     { ...restoredAppState, offsetTop: 0, offsetLeft: 0, width: 0, height: 0 },
+    files || {},
     { exportBackground, viewBackgroundColor },
     (width: number, height: number) => {
       const canvas = document.createElement("canvas");
   );
 };
 
-export const exportToBlob = (
+export const exportToBlob = async (
   opts: ExportOpts & {
     mimeType?: string;
     quality?: number;
   },
 ): Promise<Blob | null> => {
-  const canvas = exportToCanvas(opts);
+  const canvas = await exportToCanvas(opts);
 
-  let { mimeType = "image/png", quality } = opts;
+  let { mimeType = MIME_TYPES.png, quality } = opts;
 
-  if (mimeType === "image/png" && typeof quality === "number") {
-    console.warn(`"quality" will be ignored for "image/png" mimeType`);
+  if (mimeType === MIME_TYPES.png && typeof quality === "number") {
+    console.warn(`"quality" will be ignored for "${MIME_TYPES.png}" mimeType`);
   }
 
+  // typo in MIME type (should be "jpeg")
   if (mimeType === "image/jpg") {
-    mimeType = "image/jpeg";
+    mimeType = MIME_TYPES.jpg;
   }
 
   quality = quality ? quality : /image\/jpe?g/.test(mimeType) ? 0.92 : 0.8;
 export const exportToSvg = async ({
   elements,
   appState = getDefaultAppState(),
+  files = {},
   exportPadding,
 }: Omit<ExportOpts, "getDimensions"> & {
   exportPadding?: number;
     null,
     null,
   );
-  return _exportToSvg(getNonDeletedElements(restoredElements), {
-    ...restoredAppState,
-    exportPadding,
-  });
+  return _exportToSvg(
+    getNonDeletedElements(restoredElements),
+    {
+      ...restoredAppState,
+      exportPadding,
+    },
+    files,
+  );
 };
 
 export { serializeAsJSON } from "../data/json";

src/renderer/renderElement.ts

   Arrowhead,
   NonDeletedExcalidrawElement,
   ExcalidrawFreeDrawElement,
+  ExcalidrawImageElement,
 } from "../element/types";
 import {
   isTextElement,
   isLinearElement,
   isFreeDrawElement,
+  isInitializedImageElement,
 } from "../element/typeChecks";
 import {
   getDiamondPoints,
 import { RoughSVG } from "roughjs/bin/svg";
 import { RoughGenerator } from "roughjs/bin/generator";
 import { SceneState } from "../scene/types";
-import {
-  SVG_NS,
-  distance,
-  getFontString,
-  getFontFamilyString,
-  isRTL,
-} from "../utils";
+import { distance, getFontString, getFontFamilyString, isRTL } from "../utils";
 import { isPathALoop } from "../math";
 import rough from "roughjs/bin/rough";
-import { Zoom } from "../types";
+import { AppState, BinaryFiles, Zoom } from "../types";
 import { getDefaultAppState } from "../appState";
+import { MAX_DECIMALS_FOR_SVG_EXPORT, MIME_TYPES, SVG_NS } from "../constants";
 import { getStroke, StrokeOptions } from "perfect-freehand";
-import { MAX_DECIMALS_FOR_SVG_EXPORT } from "../constants";
 
 const defaultAppState = getDefaultAppState();
 
+const isPendingImageElement = (
+  element: ExcalidrawElement,
+  sceneState: SceneState,
+) =>
+  isInitializedImageElement(element) &&
+  !sceneState.imageCache.has(element.fileId);
+
 const getDashArrayDashed = (strokeWidth: number) => [8, 8 + strokeWidth];
 
 const getDashArrayDotted = (strokeWidth: number) => [1.5, 6 + strokeWidth];
 export interface ExcalidrawElementWithCanvas {
   element: ExcalidrawElement | ExcalidrawTextElement;
   canvas: HTMLCanvasElement;
+  theme: SceneState["theme"];
   canvasZoom: Zoom["value"];
   canvasOffsetX: number;
   canvasOffsetY: number;
 const generateElementCanvas = (
   element: NonDeletedExcalidrawElement,
   zoom: Zoom,
+  sceneState: SceneState,
 ): ExcalidrawElementWithCanvas => {
   const canvas = document.createElement("canvas");
   const context = canvas.getContext("2d")!;
 
   const rc = rough.canvas(canvas);
 
-  drawElementOnCanvas(element, rc, context);
+  if (
+    sceneState.theme === "dark" &&
+    isInitializedImageElement(element) &&
+    !isPendingImageElement(element, sceneState) &&
+    sceneState.imageCache.get(element.fileId)?.mimeType !== MIME_TYPES.svg
+  ) {
+    // using a stronger invert (100% vs our regular 93%) and saturate
+    // as a temp hack to make images in dark theme look closer to original
+    // color scheme (it's still not quite there and the clors look slightly
+    // desaturing/black is not as black, but...)
+    context.filter = "invert(100%) hue-rotate(180deg) saturate(1.25)";
+  }
+
+  drawElementOnCanvas(element, rc, context, sceneState);
   context.restore();
+
   return {
     element,
     canvas,
+    theme: sceneState.theme,
     canvasZoom: zoom.value,
     canvasOffsetX,
     canvasOffsetY,
   };
 };
 
+const IMAGE_PLACEHOLDER_IMG = document.createElement("img");
+IMAGE_PLACEHOLDER_IMG.src = `data:${MIME_TYPES.svg},${encodeURIComponent(
+  `<svg aria-hidden="true" focusable="false" data-prefix="fas" data-icon="image" class="svg-inline--fa fa-image fa-w-16" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path fill="#888" d="M464 448H48c-26.51 0-48-21.49-48-48V112c0-26.51 21.49-48 48-48h416c26.51 0 48 21.49 48 48v288c0 26.51-21.49 48-48 48zM112 120c-30.928 0-56 25.072-56 56s25.072 56 56 56 56-25.072 56-56-25.072-56-56-56zM64 384h384V272l-87.515-87.515c-4.686-4.686-12.284-4.686-16.971 0L208 320l-55.515-55.515c-4.686-4.686-12.284-4.686-16.971 0L64 336v48z"></path></svg>`,
+)}`;
+
+const IMAGE_ERROR_PLACEHOLDER_IMG = document.createElement("img");
+IMAGE_ERROR_PLACEHOLDER_IMG.src = `data:${MIME_TYPES.svg},${encodeURIComponent(
+  `<svg viewBox="0 0 668 668" xmlns="http://www.w3.org/2000/svg" xml:space="preserve" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2"><path d="M464 448H48c-26.51 0-48-21.49-48-48V112c0-26.51 21.49-48 48-48h416c26.51 0 48 21.49 48 48v288c0 26.51-21.49 48-48 48ZM112 120c-30.928 0-56 25.072-56 56s25.072 56 56 56 56-25.072 56-56-25.072-56-56-56ZM64 384h384V272l-87.515-87.515c-4.686-4.686-12.284-4.686-16.971 0L208 320l-55.515-55.515c-4.686-4.686-12.284-4.686-16.971 0L64 336v48Z" style="fill:#888;fill-rule:nonzero" transform="matrix(.81709 0 0 .81709 124.825 145.825)"/><path d="M256 8C119.034 8 8 119.033 8 256c0 136.967 111.034 248 248 248s248-111.034 248-248S392.967 8 256 8Zm130.108 117.892c65.448 65.448 70 165.481 20.677 235.637L150.47 105.216c70.204-49.356 170.226-44.735 235.638 20.676ZM125.892 386.108c-65.448-65.448-70-165.481-20.677-235.637L361.53 406.784c-70.203 49.356-170.226 44.736-235.638-20.676Z" style="fill:#888;fill-rule:nonzero" transform="matrix(.30366 0 0 .30366 506.822 60.065)"/></svg>`,
+)}`;
+
+const drawImagePlaceholder = (
+  element: ExcalidrawImageElement,
+  context: CanvasRenderingContext2D,
+  zoomValue: AppState["zoom"]["value"],
+) => {
+  context.fillStyle = "#E7E7E7";
+  context.fillRect(0, 0, element.width, element.height);
+
+  const imageMinWidthOrHeight = Math.min(element.width, element.height);
+
+  const size = Math.min(
+    imageMinWidthOrHeight,
+    Math.min(imageMinWidthOrHeight * 0.4, 100),
+  );
+
+  context.drawImage(
+    element.status === "error"
+      ? IMAGE_ERROR_PLACEHOLDER_IMG
+      : IMAGE_PLACEHOLDER_IMG,
+    element.width / 2 - size / 2,
+    element.height / 2 - size / 2,
+    size,
+    size,
+  );
+};
+
 const drawElementOnCanvas = (
   element: NonDeletedExcalidrawElement,
   rc: RoughCanvas,
   context: CanvasRenderingContext2D,
+  sceneState: SceneState,
 ) => {
   context.globalAlpha = element.opacity / 100;
   switch (element.type) {
       context.restore();
       break;
     }
+    case "image": {
+      const img = isInitializedImageElement(element)
+        ? sceneState.imageCache.get(element.fileId)?.image
+        : undefined;
+      if (img != null && !(img instanceof Promise)) {
+        context.drawImage(
+          img,
+          0 /* hardcoded for the selection box*/,
+          0,
+          element.width,
+          element.height,
+        );
+      } else {
+        drawImagePlaceholder(element, context, sceneState.zoom.value);
+      }
+      break;
+    }
     default: {
       if (isTextElement(element)) {
         const rtl = isRTL(element.text);
   switch (element.type) {
     case "rectangle":
     case "diamond":
+    case "image":
     case "ellipse": {
       options.fillStyle = element.fillStyle;
       options.fill =
         shape = [];
         break;
       }
-      case "text": {
+      case "text":
+      case "image": {
         // just to ensure we don't regenerate element.canvas on rerenders
         shape = [];
         break;
 
 const generateElementWithCanvas = (
   element: NonDeletedExcalidrawElement,
-  sceneState?: SceneState,
+  sceneState: SceneState,
 ) => {
   const zoom: Zoom = sceneState ? sceneState.zoom : defaultAppState.zoom;
   const prevElementWithCanvas = elementWithCanvasCache.get(element);
     prevElementWithCanvas &&
     prevElementWithCanvas.canvasZoom !== zoom.value &&
     !sceneState?.shouldCacheIgnoreZoom;
-  if (!prevElementWithCanvas || shouldRegenerateBecauseZoom) {
-    const elementWithCanvas = generateElementCanvas(element, zoom);
+
+  if (
+    !prevElementWithCanvas ||
+    shouldRegenerateBecauseZoom ||
+    prevElementWithCanvas.theme !== sceneState.theme
+  ) {
+    const elementWithCanvas = generateElementCanvas(element, zoom, sceneState);
 
     elementWithCanvasCache.set(element, elementWithCanvas);
 
 
   const cx = ((x1 + x2) / 2 + sceneState.scrollX) * window.devicePixelRatio;
   const cy = ((y1 + y2) / 2 + sceneState.scrollY) * window.devicePixelRatio;
+
+  const _isPendingImageElement = isPendingImageElement(element, sceneState);
+
+  const scaleXFactor =
+    "scale" in elementWithCanvas.element && !_isPendingImageElement
+      ? elementWithCanvas.element.scale[0]
+      : 1;
+  const scaleYFactor =
+    "scale" in elementWithCanvas.element && !_isPendingImageElement
+      ? elementWithCanvas.element.scale[1]
+      : 1;
+
   context.save();
-  context.scale(1 / window.devicePixelRatio, 1 / window.devicePixelRatio);
-  context.translate(cx, cy);
-  context.rotate(element.angle);
+  context.scale(
+    (1 / window.devicePixelRatio) * scaleXFactor,
+    (1 / window.devicePixelRatio) * scaleYFactor,
+  );
+  context.translate(cx * scaleXFactor, cy * scaleYFactor);
+  context.rotate(element.angle * scaleXFactor * scaleYFactor);
 
   context.drawImage(
     elementWithCanvas.canvas!,
         context.translate(cx, cy);
         context.rotate(element.angle);
         context.translate(-shiftX, -shiftY);
-        drawElementOnCanvas(element, rc, context);
+        drawElementOnCanvas(element, rc, context, sceneState);
         context.restore();
       }
 
     case "ellipse":
     case "line":
     case "arrow":
+    case "image":
     case "text": {
       generateElementShape(element, generator);
       if (renderOptimizations) {
         context.translate(cx, cy);
         context.rotate(element.angle);
         context.translate(-shiftX, -shiftY);
-        drawElementOnCanvas(element, rc, context);
+        drawElementOnCanvas(element, rc, context, sceneState);
         context.restore();
       }
       break;
   element: NonDeletedExcalidrawElement,
   rsvg: RoughSVG,
   svgRoot: SVGElement,
+  files: BinaryFiles,
   offsetX?: number,
   offsetY?: number,
 ) => {
       svgRoot.appendChild(node);
       break;
     }
+    case "image": {
+      const fileData =
+        isInitializedImageElement(element) && files[element.fileId];
+      if (fileData) {
+        const symbolId = `image-${fileData.id}`;
+        let symbol = svgRoot.querySelector(`#${symbolId}`);
+        if (!symbol) {
+          symbol = svgRoot.ownerDocument!.createElementNS(SVG_NS, "symbol");
+          symbol.id = symbolId;
+
+          const image = svgRoot.ownerDocument!.createElementNS(SVG_NS, "image");
+
+          image.setAttribute("width", "100%");
+          image.setAttribute("height", "100%");
+          image.setAttribute("href", fileData.dataURL);
+
+          symbol.appendChild(image);
+
+          svgRoot.prepend(symbol);
+        }
+
+        const use = svgRoot.ownerDocument!.createElementNS(SVG_NS, "use");
+        use.setAttribute("href", `#${symbolId}`);
+
+        use.setAttribute("width", `${Math.round(element.width)}`);
+        use.setAttribute("height", `${Math.round(element.height)}`);
+
+        use.setAttribute(
+          "transform",
+          `translate(${offsetX || 0} ${
+            offsetY || 0
+          }) rotate(${degree} ${cx} ${cy})`,
+        );
+
+        svgRoot.appendChild(use);
+      }
+      break;
+    }
     default: {
       if (isTextElement(element)) {
         const opacity = element.opacity / 100;

src/renderer/renderScene.ts

 import { RoughSVG } from "roughjs/bin/svg";
 import oc from "open-color";
 
-import { AppState, Zoom } from "../types";
+import { AppState, BinaryFiles, Zoom } from "../types";
 import {
   ExcalidrawElement,
   NonDeletedExcalidrawElement,
   rc: RoughCanvas,
   canvas: HTMLCanvasElement,
   sceneState: SceneState,
-  // extra options, currently passed by export helper
+  // extra options passed to the renderer
   {
     renderScrollbars = true,
     renderSelection = true,
     // doesn't guarantee pixel-perfect output.
     renderOptimizations = false,
     renderGrid = true,
+    /** when exporting the behavior is slightly different (e.g. we can't use
+        CSS filters) */
+    isExport = false,
   }: {
     renderScrollbars?: boolean;
     renderSelection?: boolean;
     renderOptimizations?: boolean;
     renderGrid?: boolean;
+    isExport?: boolean;
   } = {},
 ) => {
   if (canvas === null) {
   const normalizedCanvasWidth = canvas.width / scale;
   const normalizedCanvasHeight = canvas.height / scale;
 
-  if (sceneState.exportWithDarkMode) {
+  if (isExport && sceneState.theme === "dark") {
     context.filter = THEME_FILTER;
   }
 
   elements: readonly NonDeletedExcalidrawElement[],
   rsvg: RoughSVG,
   svgRoot: SVGElement,
+  files: BinaryFiles,
   {
     offsetX = 0,
     offsetY = 0,
           element,
           rsvg,
           svgRoot,
+          files,
           element.x + offsetX,
           element.y + offsetY,
         );

src/scene/comparisons.ts

   type === "diamond" ||
   type === "line";
 
+export const hasStrokeColor = (type: string) => type !== "image";
+
 export const hasStrokeWidth = (type: string) =>
   type === "rectangle" ||
   type === "ellipse" ||

src/scene/export.ts

 import { NonDeletedExcalidrawElement } from "../element/types";
 import { getCommonBounds } from "../element/bounds";
 import { renderScene, renderSceneToSvg } from "../renderer/renderScene";
-import { distance, SVG_NS } from "../utils";
-import { AppState } from "../types";
-import { DEFAULT_EXPORT_PADDING, THEME_FILTER } from "../constants";
+import { distance } from "../utils";
+import { AppState, BinaryFiles } from "../types";
+import { DEFAULT_EXPORT_PADDING, SVG_NS, THEME_FILTER } from "../constants";
 import { getDefaultAppState } from "../appState";
 import { serializeAsJSON } from "../data/json";
+import {
+  getInitializedImageElements,
+  updateImageCache,
+} from "../element/image";
 
 export const SVG_EXPORT_TAG = `<!-- svg-source:excalidraw -->`;
 
-export const exportToCanvas = (
+export const exportToCanvas = async (
   elements: readonly NonDeletedExcalidrawElement[],
   appState: AppState,
+  files: BinaryFiles,
   {
     exportBackground,
     exportPadding = DEFAULT_EXPORT_PADDING,
 
   const { canvas, scale = 1 } = createCanvas(width, height);
 
+  const defaultAppState = getDefaultAppState();
+
+  const { imageCache } = await updateImageCache({
+    imageCache: new Map(),
+    fileIds: getInitializedImageElements(elements).map(
+      (element) => element.fileId,
+    ),
+    files,
+  });
+
   renderScene(
     elements,
     appState,
     canvas,
     {
       viewBackgroundColor: exportBackground ? viewBackgroundColor : null,
-      exportWithDarkMode: appState.exportWithDarkMode,
       scrollX: -minX + exportPadding,
       scrollY: -minY + exportPadding,
-      zoom: getDefaultAppState().zoom,
+      zoom: defaultAppState.zoom,
       remotePointerViewportCoords: {},
       remoteSelectedElementIds: {},
       shouldCacheIgnoreZoom: false,
       remotePointerUsernames: {},
       remotePointerUserStates: {},
+      theme: appState.exportWithDarkMode ? "dark" : "light",
+      imageCache,
     },
     {
       renderScrollbars: false,
       renderSelection: false,
-      renderOptimizations: false,
+      renderOptimizations: true,
       renderGrid: false,
+      isExport: true,
     },
   );
 
     exportWithDarkMode?: boolean;
     exportEmbedScene?: boolean;
   },
+  files: BinaryFiles | null,
 ): Promise<SVGSVGElement> => {
   const {
     exportPadding = DEFAULT_EXPORT_PADDING,
       metadata = await (
         await import(/* webpackChunkName: "image" */ "../../src/data/image")
       ).encodeSvgMetadata({
-        text: serializeAsJSON(elements, appState),
+        text: serializeAsJSON(elements, appState, files || {}, "local"),
       });
     } catch (err) {
       console.error(err);
   }
 
   const rsvg = rough.svg(svgRoot);
-  renderSceneToSvg(elements, rsvg, svgRoot, {
+  renderSceneToSvg(elements, rsvg, svgRoot, files || {}, {
     offsetX: -minX + exportPadding,
     offsetY: -minY + exportPadding,
   });

src/scene/types.ts

 import { ExcalidrawTextElement } from "../element/types";
-import { Zoom } from "../types";
+import { AppClassProperties, AppState, Zoom } from "../types";
 
 export type SceneState = {
   scrollX: number;
   scrollY: number;
   // null indicates transparent bg
   viewBackgroundColor: string | null;
-  exportWithDarkMode?: boolean;
   zoom: Zoom;
   shouldCacheIgnoreZoom: boolean;
   remotePointerViewportCoords: { [id: string]: { x: number; y: number } };
   remoteSelectedElementIds: { [elementId: string]: string[] };
   remotePointerUsernames: { [id: string]: string };
   remotePointerUserStates: { [id: string]: string };
+  theme: AppState["theme"];
+  imageCache: AppClassProperties["imageCache"];
 };
 
 export type SceneScroll = {

src/shapes.tsx

     value: "text",
     key: KEYS.T,
   },
+  {
+    icon: (
+      // fa-image
+      <svg viewBox="0 0 512 512">
+        <path
+          fill="currentColor"
+          d="M464 64H48C21.49 64 0 85.49 0 112v288c0 26.51 21.49 48 48 48h416c26.51 0 48-21.49 48-48V112c0-26.51-21.49-48-48-48zm-6 336H54a6 6 0 0 1-6-6V118a6 6 0 0 1 6-6h404a6 6 0 0 1 6 6v276a6 6 0 0 1-6 6zM128 152c-22.091 0-40 17.909-40 40s17.909 40 40 40 40-17.909 40-40-17.909-40-40-40zM96 352h320v-80l-87.515-87.515c-4.686-4.686-12.284-4.686-16.971 0L192 304l-39.515-39.515c-4.686-4.686-12.284-4.686-16.971 0L96 304v48z"
+        ></path>
+      </svg>
+    ),
+    value: "image",
+    key: null,
+  },
 ] as const;
 
 export const findShapeByKey = (key: string) => {
   const shape = SHAPES.find((shape, index) => {
     return (
       key === (index + 1).toString() ||
-      (typeof shape.key === "string"
-        ? shape.key === key
-        : (shape.key as readonly string[]).includes(key))
+      (shape.key &&
+        (typeof shape.key === "string"
+          ? shape.key === key
+          : (shape.key as readonly string[]).includes(key)))
     );
   });
   return shape?.value || null;

src/tests/__snapshots__/contextmenu.test.tsx.snap

     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id1": true,
   },
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id1": true,
   },
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
     "id2": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
     "id2": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,

src/tests/__snapshots__/regressionTests.test.tsx.snap

     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
     "id1": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
     "id1": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
   },
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
     "id3": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
   },
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id2": true,
   },
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
   },
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
     "id1": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id1": true,
   },
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id2": true,
   },
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
     "id1": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
     "id1": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
   },
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
   },
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
     "id1": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
     "id2": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
     "id2": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
     "id2": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
     "id2": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
     "id1": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
     "id3": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": -5.416666666666667,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
   },
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
     "id1": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
     "id1": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 60,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id0": true,
   },
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id1": true,
     "id2": true,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {
     "id1": true,
   },
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 11.046099290780141,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,
     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,

src/tests/appState.test.tsx

 import ExcalidrawApp from "../excalidraw-app";
 import { API } from "./helpers/api";
 import { getDefaultAppState } from "../appState";
-import { EXPORT_DATA_TYPES } from "../constants";
+import { EXPORT_DATA_TYPES, MIME_TYPES } from "../constants";
 
 const { h } = window;
 
             elements: [API.createElement({ type: "rectangle", id: "A" })],
           }),
         ],
-        { type: "application/json" },
+        { type: MIME_TYPES.json },
       ),
     );
 

src/tests/collab.test.tsx

   const loadFromFirebase = async () => null;
   const saveToFirebase = () => {};
   const isSavedToFirebase = () => true;
+  const loadFilesFromFirebase = async () => ({
+    loadedFiles: [],
+    erroredFiles: [],
+  });
+  const saveFilesToFirebase = async () => ({
+    savedFiles: new Map(),
+    erroredFiles: new Map(),
+  });
 
   return {
     loadFromFirebase,
     saveToFirebase,
     isSavedToFirebase,
+    loadFilesFromFirebase,
+    saveFilesToFirebase,
   };
 });
 

src/tests/export.test.tsx

     const pngBlob = await API.loadFile("./fixtures/smiley.png");
     const pngBlobEmbedded = await encodePngMetadata({
       blob: pngBlob,
-      metadata: serializeAsJSON(testElements, h.state),
+      metadata: serializeAsJSON(testElements, h.state, {}, "local"),
     });
     API.drop(pngBlobEmbedded);
 
 
   it("test encoding/decoding scene for SVG export", async () => {
     const encoded = await encodeSvgMetadata({
-      text: serializeAsJSON(testElements, h.state),
+      text: serializeAsJSON(testElements, h.state, {}, "local"),
     });
     const decoded = JSON.parse(await decodeSvgMetadata({ svg: encoded }));
     expect(decoded.elements).toEqual([

src/tests/fixtures/diagramFixture.ts

     viewBackgroundColor: "#ffffff",
     gridSize: null,
   },
+  files: {},
 };
 
 export const diagramFactory = ({

src/tests/history.test.tsx

 import { getDefaultAppState } from "../appState";
 import { waitFor } from "@testing-library/react";
 import { createUndoAction, createRedoAction } from "../actions/actionHistory";
-import { EXPORT_DATA_TYPES } from "../constants";
+import { EXPORT_DATA_TYPES, MIME_TYPES } from "../constants";
 
 const { h } = window;
 
             elements: [API.createElement({ type: "rectangle", id: "B" })],
           }),
         ],
-        { type: "application/json" },
+        { type: MIME_TYPES.json },
       ),
     );
 

src/tests/packages/__snapshots__/utils.test.ts.snap

     "data": null,
     "shown": false,
   },
+  "pendingImageElement": null,
   "previousSelectedElementIds": Object {},
   "resizingElement": null,
   "scrollX": 0,

src/tests/packages/utils.test.ts

 import * as utils from "../../packages/utils";
 import { diagramFactory } from "../fixtures/diagramFixture";
 import * as mockedSceneExportUtils from "../../scene/export";
+import { MIME_TYPES } from "../../constants";
 
 jest.mock("../../scene/export", () => ({
   __esmodule: true,
 describe("exportToCanvas", () => {
   const EXPORT_PADDING = 10;
 
-  it("with default arguments", () => {
-    const canvas = utils.exportToCanvas({
+  it("with default arguments", async () => {
+    const canvas = await utils.exportToCanvas({
       ...diagramFactory({ elementOverrides: { width: 100, height: 100 } }),
     });
 
     expect(canvas.height).toBe(100 + 2 * EXPORT_PADDING);
   });
 
-  it("when custom width and height", () => {
-    const canvas = utils.exportToCanvas({
+  it("when custom width and height", async () => {
+    const canvas = await utils.exportToCanvas({
       ...diagramFactory({ elementOverrides: { width: 100, height: 100 } }),
       getDimensions: () => ({ width: 200, height: 200, scale: 1 }),
     });
       const blob = await utils.exportToBlob({
         ...diagramFactory(),
         getDimensions: (width, height) => ({ width, height, scale: 1 }),
+        // testing typo in MIME type (jpg → jpeg)
         mimeType: "image/jpg",
       });
-      expect(blob?.type).toBe("image/jpeg");
+      expect(blob?.type).toBe(MIME_TYPES.jpg);
     });
 
     it("should default to image/png", async () => {
       const blob = await utils.exportToBlob({
         ...diagramFactory(),
       });
-      expect(blob?.type).toBe("image/png");
+      expect(blob?.type).toBe(MIME_TYPES.png);
     });
 
     it("should warn when using quality with image/png", async () => {
 
       await utils.exportToBlob({
         ...diagramFactory(),
-        mimeType: "image/png",
+        mimeType: MIME_TYPES.png,
         quality: 1,
       });
 
       expect(consoleSpy).toHaveBeenCalledWith(
-        '"quality" will be ignored for "image/png" mimeType',
+        `"quality" will be ignored for "${MIME_TYPES.png}" mimeType`,
       );
     });
   });

src/tests/scene/__snapshots__/export.test.ts.snap

 exports[`exportToSvg with exportEmbedScene 1`] = `
 "
   <!-- svg-source:excalidraw -->
-  <!-- payload-type:application/vnd.excalidraw+json --><!-- payload-version:2 --><!-- payload-start -->eyJ2ZXJzaW9uIjoiMSIsImVuY29kaW5nIjoiYnN0cmluZyIsImNvbXByZXNzZWQiOnRydWUsImVuY29kZWQiOiJ4nO1SQW7CMFx1MDAxMLzzisi9XCKRpIFQbrRUVaWqPXBAatWDiTexhbGD7Vx1MDAwMFx1MDAxMeLvtVx1MDAxZEjaqP1BfbC0szO76/WcXHUwMDA2QYBMXVx1MDAwMppcdTAwMDVcYo5cdTAwMTnmjCh8QEOH70FpJoVNxT7WslKZZ1JjytloxKVcdTAwMTVQqU3DXHUwMDA3XHUwMDBlW1x1MDAxMEZbxoeNg+Dkb5thxKn2K7V7m+dcdTAwMWImSLzLtunLYv707qWedLScJErauHaNb9M2PjBiqMWiMGwxXG6soKZcdTAwMDdiUXA3Zodoo+RcdTAwMDZcdTAwMWUkl8pccnJcdTAwMTP607Ve42xTKFlcdNJxojHG67zj5Izzpal5s1x1MDAwMJzRSlx1MDAwMep1WF1H7OGtTku74E5lW1x1MDAxNlSA1j80ssRcdTAwMTkzde9Vbr7ymfjtfvbrU6zKS1x1MDAxZKRd8G0yXHUwMDAw4ksl0WSc3oXTNtP9b1x1MDAxNId99FVcbv/XUTSdhmFcdTAwMTKnk5bB9MJ+tfFlc8w1dHt0K3xsbNCMKirO2/TVaIThrVx1MDAxNFx1MDAwNHn8PPz3yr9X/vRcbnDOSlxyXHUwMDE3r9jbv1x1MDAwN+GyXFxcdTAwMWFsXHUwMDFjpXFcdTAwMGXaMzjc//I3uT9Of1x1MDAxZZy/XHUwMDAw6cxEtiJ9<!-- payload-end -->
+  <!-- payload-type:application/vnd.excalidraw+json --><!-- payload-version:2 --><!-- payload-start -->eyJ2ZXJzaW9uIjoiMSIsImVuY29kaW5nIjoiYnN0cmluZyIsImNvbXByZXNzZWQiOnRydWUsImVuY29kZWQiOiJ4nO1SQW7CMFx1MDAxMLzzisi9XCKRpIFQbrRUVaWqPXBAatWDiTexhbGD7Vx1MDAwMFx1MDAxMeLvtVx1MDAxZEjaqP1BfbC045nd9e6cXHUwMDA2QYBMXVx1MDAwMppcdTAwMDVcYo5cdTAwMTnmjCh8QEOH70FpJoV9in2sZaUyz6TGlLPRiEsroFKbhlx1MDAwZlx1MDAxY7YgjLaMXHUwMDBmXHUwMDFiXHUwMDA3wcnf9oVcdTAwMTGn2q/U7m2eb5gg8S7bpi+L+dO7l3rS0XKSKGnj2lx1MDAxNb5N2/jAiKFcdTAwMTaLwrDFKLCCmlx1MDAxZYhFwV2bXHUwMDFkoo2SXHUwMDFieJBcXCrXyE3oT1d6jbNNoWQlSMeJxlx1MDAxOK/zjpMzzpem5s1cdTAwMDBwRitcdTAwMDWoV2F1bbGHtzot7YA7lS1ZUFx1MDAwMVr/0MhcdTAwMTJnzNS9X7n+ymfip/vZz0+xKi95kHbBt85cdTAwMDCIT5VEk3F6XHUwMDE3TtuXbr9RXHUwMDFj9tFXKfyuo2g6XHLDJE4nLYPphV218WlzzDV0c3QjfGxs0LQqKs7b56vRXGLDWylcYvL4efjvlX+v/OlcdTAwMTXgnJVcdTAwMWEuXrG3/1x1MDAwZsJluTTYOErjXHUwMDFjtGdwuP9lN7k/Tu+d5nZcdTAwMDOu2uk8OH9cdTAwMDFcZrNI1SJ9<!-- payload-end -->
   <defs>
     <style>
       @font-face {

src/tests/scene/export.test.ts

   const DEFAULT_OPTIONS = {
     exportBackground: false,
     viewBackgroundColor: "#ffffff",
+    files: {},
   };
 
   it("with default arguments", async () => {
-    const svgElement = await exportUtils.exportToSvg(ELEMENTS, DEFAULT_OPTIONS);
+    const svgElement = await exportUtils.exportToSvg(
+      ELEMENTS,
+      DEFAULT_OPTIONS,
+      null,
+    );
 
     expect(svgElement).toMatchSnapshot();
   });
   it("with background color", async () => {
     const BACKGROUND_COLOR = "#abcdef";
 
-    const svgElement = await exportUtils.exportToSvg(ELEMENTS, {
-      ...DEFAULT_OPTIONS,
-      exportBackground: true,
-      viewBackgroundColor: BACKGROUND_COLOR,
-    });
+    const svgElement = await exportUtils.exportToSvg(
+      ELEMENTS,
+      {
+        ...DEFAULT_OPTIONS,
+        exportBackground: true,
+        viewBackgroundColor: BACKGROUND_COLOR,
+      },
+      null,
+    );
 
     expect(svgElement.querySelector("rect")).toHaveAttribute(
       "fill",
   });
 
   it("with dark mode", async () => {
-    const svgElement = await exportUtils.exportToSvg(ELEMENTS, {
-      ...DEFAULT_OPTIONS,
-      exportWithDarkMode: true,
-    });
+    const svgElement = await exportUtils.exportToSvg(
+      ELEMENTS,
+      {
+        ...DEFAULT_OPTIONS,
+        exportWithDarkMode: true,
+      },
+      null,
+    );
 
     expect(svgElement.getAttribute("filter")).toMatchInlineSnapshot(
       `"themeFilter"`,
   });
 
   it("with exportPadding", async () => {
-    const svgElement = await exportUtils.exportToSvg(ELEMENTS, {
-      ...DEFAULT_OPTIONS,
-      exportPadding: 0,
-    });
+    const svgElement = await exportUtils.exportToSvg(
+      ELEMENTS,
+      {
+        ...DEFAULT_OPTIONS,
+        exportPadding: 0,
+      },
+      null,
+    );
 
     expect(svgElement).toHaveAttribute("height", ELEMENT_HEIGHT.toString());
     expect(svgElement).toHaveAttribute("width", ELEMENT_WIDTH.toString());
   it("with scale", async () => {
     const SCALE = 2;
 
-    const svgElement = await exportUtils.exportToSvg(ELEMENTS, {
-      ...DEFAULT_OPTIONS,
-      exportPadding: 0,
-      exportScale: SCALE,
-    });
+    const svgElement = await exportUtils.exportToSvg(
+      ELEMENTS,
+      {
+        ...DEFAULT_OPTIONS,
+        exportPadding: 0,
+        exportScale: SCALE,
+      },
+      null,
+    );
 
     expect(svgElement).toHaveAttribute(
       "height",
   });
 
   it("with exportEmbedScene", async () => {
-    const svgElement = await exportUtils.exportToSvg(ELEMENTS, {
-      ...DEFAULT_OPTIONS,
-      exportEmbedScene: true,
-    });
+    const svgElement = await exportUtils.exportToSvg(
+      ELEMENTS,
+      {
+        ...DEFAULT_OPTIONS,
+        exportEmbedScene: true,
+      },
+      null,
+    );
     expect(svgElement.innerHTML).toMatchSnapshot();
   });
 });

src/tests/test-utils.ts

 import { getSelectedElements } from "../scene/selection";
 import { ExcalidrawElement } from "../element/types";
 
+require("fake-indexeddb/auto");
+
 const customQueries = {
   ...queries,
   ...toolQueries,

src/types.ts

   Arrowhead,
   ChartType,
   FontFamilyValues,
+  FileId,
+  ExcalidrawImageElement,
   Theme,
 } from "./element/types";
 import { SHAPES } from "./shapes";
 import { ClipboardData } from "./clipboard";
 import { isOverScrollBars } from "./scene";
 import { MaybeTransformHandleType } from "./element/transformHandles";
-import { FileSystemHandle } from "./data/filesystem";
+import Library from "./data/library";
+import type { FileSystemHandle } from "./data/filesystem";
+import type { ALLOWED_IMAGE_MIME_TYPES, MIME_TYPES } from "./constants";
 
 export type Point = Readonly<RoughPoint>;
 
   };
 };
 
+export type DataURL = string & { _brand: "DataURL" };
+
+export type BinaryFileData = {
+  mimeType:
+    | typeof ALLOWED_IMAGE_MIME_TYPES[number]
+    // future user or unknown file type
+    | typeof MIME_TYPES.binary;
+  id: FileId;
+  dataURL: DataURL;
+  created: number;
+};
+
+export type BinaryFileMetadata = Omit<BinaryFileData, "dataURL">;
+
+export type BinaryFiles = Record<ExcalidrawElement["id"], BinaryFileData>;
+
 export type AppState = {
   isLoading: boolean;
   errorMessage: string | null;
         shown: true;
         data: Spreadsheet;
       };
+  /** imageElement waiting to be placed on canvas */
+  pendingImageElement: NonDeleted<ExcalidrawImageElement> | null;
 };
 
 export type NormalizedZoomValue = number & { _brand: "normalizedZoom" };
   onChange?: (
     elements: readonly ExcalidrawElement[],
     appState: AppState,
+    files: BinaryFiles,
   ) => void;
   initialData?: ImportedDataState | null | Promise<ImportedDataState | null>;
   excalidrawRef?: ForwardRef<ExcalidrawAPIRefValue>;
   handleKeyboardGlobally?: boolean;
   onLibraryChange?: (libraryItems: LibraryItems) => void | Promise<any>;
   autoFocus?: boolean;
+  generateIdForFile?: (file: File) => string | Promise<string>;
 }
 
 export type SceneData = {
   onExportToBackend?: (
     exportedElements: readonly NonDeletedExcalidrawElement[],
     appState: AppState,
+    files: BinaryFiles,
     canvas: HTMLCanvasElement | null,
   ) => void;
   renderCustomUI?: (
     exportedElements: readonly NonDeletedExcalidrawElement[],
     appState: AppState,
+    files: BinaryFiles,
     canvas: HTMLCanvasElement | null,
   ) => JSX.Element;
 };
   handleKeyboardGlobally: boolean;
 };
 
+/** A subset of App class properties that we need to use elsewhere
+ * in the app, eg Manager. Factored out into a separate type to keep DRY. */
+export type AppClassProperties = {
+  props: AppProps;
+  canvas: HTMLCanvasElement | null;
+  focusContainer(): void;
+  library: Library;
+  imageCache: Map<
+    FileId,
+    {
+      image: HTMLImageElement | Promise<HTMLImageElement>;
+      mimeType: typeof ALLOWED_IMAGE_MIME_TYPES[number];
+    }
+  >;
+  files: BinaryFiles;
+};
+
 export type PointerDownState = Readonly<{
   // The first position at which pointerDown happened
   origin: Readonly<{ x: number; y: number }>;
   scrollToContent: InstanceType<typeof App>["scrollToContent"];
   getSceneElements: InstanceType<typeof App>["getSceneElements"];
   getAppState: () => InstanceType<typeof App>["state"];
+  getFiles: () => InstanceType<typeof App>["files"];
   refresh: InstanceType<typeof App>["refresh"];
   importLibrary: InstanceType<typeof App>["importLibraryFromUrl"];
   setToastMessage: InstanceType<typeof App>["setToastMessage"];
+  addFiles: (data: BinaryFileData[]) => void;
   readyPromise: ResolvablePromise<ExcalidrawImperativeAPI>;
   ready: true;
   id: string;

src/utils.ts

 import { unstable_batchedUpdates } from "react-dom";
 import { isDarwin } from "./keys";
 
-export const SVG_NS = "http://www.w3.org/2000/svg";
-
 let mockDateTime: string | null = null;
 
 export const setDateTimeForTests = (dateTime: string) => {
   }
   if (shape === "selection") {
     resetCursor(canvas);
-  } else {
+    // do nothing if image tool is selected which suggests there's
+    // a image-preview set as the cursor
+  } else if (shape !== "image") {
     canvas.style.cursor = CURSOR_TYPE.CROSSHAIR;
   }
 };
     parent = parent.parentElement;
   }
 };
+
+export const preventUnload = (event: BeforeUnloadEvent) => {
+  event.preventDefault();
+  // NOTE: modern browsers no longer allow showing a custom message here
+  event.returnValue = "";
+};

yarn.lock

   version "4.0.0"
   resolved "https://registry.npmjs.org/@types/parse-json/-/parse-json-4.0.0.tgz"
 
+"@types/pica@5.1.3":
+  version "5.1.3"
+  resolved "https://registry.yarnpkg.com/@types/pica/-/pica-5.1.3.tgz#5ef64529a1f83f7d6586a8bf75a8a00be32aca02"
+  integrity sha512-13SEyETRE5psd9bE0AmN+0M1tannde2fwHfLVaVIljkbL9V0OfFvKwCicyeDvVYLkmjQWEydbAlsDsmjrdyTOg==
+
 "@types/prettier@^2.0.0":
   version "2.2.3"
   resolved "https://registry.yarnpkg.com/@types/prettier/-/prettier-2.2.3.tgz#ef65165aea2924c9359205bf748865b8881753c0"
   version "1.0.0"
   resolved "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.0.tgz"
 
+base64-arraybuffer-es6@^0.7.0:
+  version "0.7.0"
+  resolved "https://registry.yarnpkg.com/base64-arraybuffer-es6/-/base64-arraybuffer-es6-0.7.0.tgz#dbe1e6c87b1bf1ca2875904461a7de40f21abc86"
+  integrity sha512-ESyU/U1CFZDJUdr+neHRhNozeCv72Y7Vm0m1DCbjX3KBjT6eYocvAJlSk6+8+HkVwXlT1FNxhGW6q3UKAlCvvw==
+
 base64-arraybuffer@0.1.4:
   version "0.1.4"
   resolved "https://registry.npmjs.org/base64-arraybuffer/-/base64-arraybuffer-0.1.4.tgz"
   version "3.6.5"
   resolved "https://registry.npmjs.org/core-js/-/core-js-3.6.5.tgz"
 
-core-js@^2.4.0:
+core-js@^2.4.0, core-js@^2.5.3:
   version "2.6.12"
   resolved "https://registry.yarnpkg.com/core-js/-/core-js-2.6.12.tgz#d9333dfa7b065e347cc5682219d6f690859cc2ec"
 
   version "2.1.0"
   resolved "https://registry.yarnpkg.com/domelementtype/-/domelementtype-2.1.0.tgz#a851c080a6d1c3d94344aed151d99f669edf585e"
 
+domexception@^1.0.1:
+  version "1.0.1"
+  resolved "https://registry.yarnpkg.com/domexception/-/domexception-1.0.1.tgz#937442644ca6a31261ef36e3ec677fe805582c90"
+  integrity sha512-raigMkn7CJNNo6Ihro1fzG7wr3fHuYVytzquZKX5n0yizGsTcYgzdIUwj1X9pK0VvjeihV+XiclP+DjwbsSKug==
+  dependencies:
+    webidl-conversions "^4.0.2"
+
 domexception@^2.0.1:
   version "2.0.1"
   resolved "https://registry.npmjs.org/domexception/-/domexception-2.0.1.tgz"
   version "1.3.0"
   resolved "https://registry.npmjs.org/extsprintf/-/extsprintf-1.3.0.tgz"
 
+fake-indexeddb@3.1.3:
+  version "3.1.3"
+  resolved "https://registry.yarnpkg.com/fake-indexeddb/-/fake-indexeddb-3.1.3.tgz#76d59146a6b994b9bb50ac9949cbd96ad6cca760"
+  integrity sha512-kpWYPIUGmxW8Q7xG7ampGL63fU/kYNukrIyy9KFj3+KVlFbE/SmvWebzWXBiCMeR0cPK6ufDoGC7MFkPhPLH9w==
+  dependencies:
+    realistic-structured-clone "^2.0.1"
+    setimmediate "^1.0.5"
+
 fast-deep-equal@^3.1.1:
   version "3.1.3"
   resolved "https://registry.yarnpkg.com/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz#3a7d56b559d6cbc3eb512325244e619a65c6c525"
     pify "^2.0.0"
     pinkie-promise "^2.0.0"
 
+glur@^1.1.2:
+  version "1.1.2"
+  resolved "https://registry.yarnpkg.com/glur/-/glur-1.1.2.tgz#f20ea36db103bfc292343921f1f91e83c3467689"
+  integrity sha1-8g6jbbEDv8KSNDkh8fkeg8NGdok=
+
 google-auth-library@^6.1.1, google-auth-library@^6.1.2, google-auth-library@^6.1.3:
   version "6.1.6"
   resolved "https://registry.yarnpkg.com/google-auth-library/-/google-auth-library-6.1.6.tgz#deacdcdb883d9ed6bac78bb5d79a078877fdf572"
   dependencies:
     postcss "^7.0.14"
 
+idb-keyval@5.1.3:
+  version "5.1.3"
+  resolved "https://registry.yarnpkg.com/idb-keyval/-/idb-keyval-5.1.3.tgz#6ef5dff371897c23f144322dc6374eadd6a345d9"
+  integrity sha512-N9HbCK/FaXSRVI+k6Xq4QgWxbcZRUv+SfG1y7HJ28JdV8yEJu6k+C/YLea7npGckX2DQJeEVuMc4bKOBeU/2LQ==
+  dependencies:
+    safari-14-idb-fix "^1.0.4"
+
 idb@3.0.2:
   version "3.0.2"
   resolved "https://registry.npmjs.org/idb/-/idb-3.0.2.tgz"
   version "5.1.8"
   resolved "https://registry.npmjs.org/ignore/-/ignore-5.1.8.tgz"
 
+image-blob-reduce@3.0.1:
+  version "3.0.1"
+  resolved "https://registry.yarnpkg.com/image-blob-reduce/-/image-blob-reduce-3.0.1.tgz#812be7655a552031635799ae64e846b106f7a489"
+  integrity sha512-/VmmWgIryG/wcn4TVrV7cC4mlfUC/oyiKIfSg5eVM3Ten/c1c34RJhMYKCWTnoSMHSqXLt3tsrBR4Q2HInvN+Q==
+  dependencies:
+    pica "^7.1.0"
+
 immediate@~3.0.5:
   version "3.0.6"
   resolved "https://registry.npmjs.org/immediate/-/immediate-3.0.6.tgz"
   dependencies:
     lodash.keys "~2.4.1"
 
-"lodash@>=3.5 <5", lodash@^4.17.10, lodash@^4.17.11, lodash@^4.17.14, lodash@^4.17.15, lodash@^4.17.19, lodash@^4.17.20, lodash@^4.17.21, lodash@^4.17.5:
+"lodash@>=3.5 <5", lodash@^4.17.10, lodash@^4.17.11, lodash@^4.17.14, lodash@^4.17.15, lodash@^4.17.19, lodash@^4.17.20, lodash@^4.17.21, lodash@^4.17.5, lodash@^4.7.0:
   version "4.17.21"
   resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.21.tgz#679591c564c3bffaae8454cf0b3df370c3d6911c"
 
     dns-packet "^1.3.1"
     thunky "^1.0.2"
 
+multimath@^2.0.0:
+  version "2.0.0"
+  resolved "https://registry.yarnpkg.com/multimath/-/multimath-2.0.0.tgz#0d37acf67c328f30e3d8c6b0d3209e6082710302"
+  integrity sha512-toRx66cAMJ+Ccz7pMIg38xSIrtnbozk0dchXezwQDMgQmbGpfxjtv68H+L00iFL8hxDaVjrmwAFSb3I6bg8Q2g==
+  dependencies:
+    glur "^1.1.2"
+    object-assign "^4.1.1"
+
 mute-stream@0.0.7:
   version "0.0.7"
   resolved "https://registry.npmjs.org/mute-stream/-/mute-stream-0.0.7.tgz"
   version "2.1.0"
   resolved "https://registry.npmjs.org/performance-now/-/performance-now-2.1.0.tgz"
 
+pica@^7.1.0:
+  version "7.1.0"
+  resolved "https://registry.yarnpkg.com/pica/-/pica-7.1.0.tgz#eb0b11abb3f2234ba8bdd0a839460f8fcd20e32a"
+  integrity sha512-4D1E1lssL/yJD4La23Kbh5CSJPeXMO8NgJTsR/VWtG7aV92fD2g2t/PABg/Abp8Ug3yJNw7y7x1ftkJuIPLpEw==
+  dependencies:
+    glur "^1.1.2"
+    inherits "^2.0.3"
+    multimath "^2.0.0"
+    object-assign "^4.1.1"
+    webworkify "^1.5.0"
+
 picomatch@^2.0.4, picomatch@^2.0.5, picomatch@^2.2.1, picomatch@^2.2.2:
   version "2.2.2"
   resolved "https://registry.npmjs.org/picomatch/-/picomatch-2.2.2.tgz"
   dependencies:
     picomatch "^2.2.1"
 
+realistic-structured-clone@^2.0.1:
+  version "2.0.3"
+  resolved "https://registry.yarnpkg.com/realistic-structured-clone/-/realistic-structured-clone-2.0.3.tgz#8a252a87db8278d92267ad7a168c4f43fa485795"
+  integrity sha512-XYTwWZi5+lU4Wf+rnsQ7pukN9hF2cbJJf/yruBr1w23WhGflM6WoTBkdMVAun+oHFW2mV7UquyYo5oOI7YLJrQ==
+  dependencies:
+    core-js "^2.5.3"
+    domexception "^1.0.1"
+    typeson "^6.1.0"
+    typeson-registry "^1.0.0-alpha.20"
+
 recursive-readdir@2.2.2:
   version "2.2.2"
   resolved "https://registry.npmjs.org/recursive-readdir/-/recursive-readdir-2.2.2.tgz"
   dependencies:
     tslib "^1.9.0"
 
+safari-14-idb-fix@^1.0.4:
+  version "1.0.4"
+  resolved "https://registry.yarnpkg.com/safari-14-idb-fix/-/safari-14-idb-fix-1.0.4.tgz#5c68ba63e2a8ae0d89a0aa1e13fe89e3aef7da19"
+  integrity sha512-4+Y2baQdgJpzu84d0QjySl70Kyygzf0pepVg8NVg4NnQEPpfC91fAn0baNvtStlCjUUxxiu0BOMiafa98fRRuA==
+
 safe-buffer@5.1.2, safe-buffer@~5.1.0, safe-buffer@~5.1.1:
   version "5.1.2"
   resolved "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz"
     is-plain-object "^2.0.3"
     split-string "^3.0.1"
 
-setimmediate@^1.0.4, setimmediate@~1.0.4:
+setimmediate@^1.0.4, setimmediate@^1.0.5, setimmediate@~1.0.4:
   version "1.0.5"
   resolved "https://registry.npmjs.org/setimmediate/-/setimmediate-1.0.5.tgz"
 
   dependencies:
     punycode "^2.1.1"
 
+tr46@^2.1.0:
+  version "2.1.0"
+  resolved "https://registry.yarnpkg.com/tr46/-/tr46-2.1.0.tgz#fa87aa81ca5d5941da8cbf1f9b749dc969a4e240"
+  integrity sha512-15Ih7phfcdP5YxqiB+iDtLoaTz4Nd35+IiAv0kQ5FNKHzXgdWqPoTIqEDDJmXceQt4JZk6lVPT8lnDlPpGDppw==
+  dependencies:
+    punycode "^2.1.1"
+
 "traverse@>=0.3.0 <0.4":
   version "0.3.9"
   resolved "https://registry.npmjs.org/traverse/-/traverse-0.3.9.tgz"
   resolved "https://registry.yarnpkg.com/typescript/-/typescript-4.2.4.tgz#8610b59747de028fda898a8aef0e103f156d0961"
   integrity sha512-V+evlYHZnQkaz8TRBuxTA92yZBPotr5H+WhQ7bD3hZUndx5tGOa1fuCgeSjxAzM1RiN5IzvadIXTVefuuwZCRg==
 
+typeson-registry@^1.0.0-alpha.20:
+  version "1.0.0-alpha.39"
+  resolved "https://registry.yarnpkg.com/typeson-registry/-/typeson-registry-1.0.0-alpha.39.tgz#9e0f5aabd5eebfcffd65a796487541196f4b1211"
+  integrity sha512-NeGDEquhw+yfwNhguLPcZ9Oj0fzbADiX4R0WxvoY8nGhy98IbzQy1sezjoEFWOywOboj/DWehI+/aUlRVrJnnw==
+  dependencies:
+    base64-arraybuffer-es6 "^0.7.0"
+    typeson "^6.0.0"
+    whatwg-url "^8.4.0"
+
+typeson@^6.0.0, typeson@^6.1.0:
+  version "6.1.0"
+  resolved "https://registry.yarnpkg.com/typeson/-/typeson-6.1.0.tgz#5b2a53705a5f58ff4d6f82f965917cabd0d7448b"
+  integrity sha512-6FTtyGr8ldU0pfbvW/eOZrEtEkczHRUtduBnA90Jh9kMPCiFNnXIon3vF41N0S4tV1HHQt4Hk1j4srpESziCaA==
+
 unbox-primitive@^1.0.0:
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/unbox-primitive/-/unbox-primitive-1.0.1.tgz#085e215625ec3162574dc8859abee78a59b14471"
   dependencies:
     defaults "^1.0.3"
 
+webidl-conversions@^4.0.2:
+  version "4.0.2"
+  resolved "https://registry.yarnpkg.com/webidl-conversions/-/webidl-conversions-4.0.2.tgz#a855980b1f0b6b359ba1d5d9fb39ae941faa63ad"
+  integrity sha512-YQ+BmxuTgd6UXZW3+ICGfyqRyHXVlD5GtQr5+qjiNW7bF0cqrzX500HVXPBOvgXb5YnzDd+h0zqyv61KUD7+Sg==
+
 webidl-conversions@^5.0.0:
   version "5.0.0"
   resolved "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-5.0.0.tgz"
   version "0.1.4"
   resolved "https://registry.npmjs.org/websocket-extensions/-/websocket-extensions-0.1.4.tgz"
 
+webworkify@^1.5.0:
+  version "1.5.0"
+  resolved "https://registry.yarnpkg.com/webworkify/-/webworkify-1.5.0.tgz#734ad87a774de6ebdd546e1d3e027da5b8f4a42c"
+  integrity sha512-AMcUeyXAhbACL8S2hqqdqOLqvJ8ylmIbNwUIqQujRSouf4+eUFaXbG6F1Rbu+srlJMmxQWsiU7mOJi0nMBfM1g==
+
 whatwg-encoding@^1.0.5:
   version "1.0.5"
   resolved "https://registry.npmjs.org/whatwg-encoding/-/whatwg-encoding-1.0.5.tgz"
     tr46 "^2.0.2"
     webidl-conversions "^6.1.0"
 
+whatwg-url@^8.4.0:
+  version "8.7.0"
+  resolved "https://registry.yarnpkg.com/whatwg-url/-/whatwg-url-8.7.0.tgz#656a78e510ff8f3937bc0bcbe9f5c0ac35941b77"
+  integrity sha512-gAojqb/m9Q8a5IV96E3fHJM70AzCkgt4uXYX2O7EmuyOnLrViCQlsEBmF9UQIu3/aeAIp2U17rtbpZWNntQqdg==
+  dependencies:
+    lodash "^4.7.0"
+    tr46 "^2.1.0"
+    webidl-conversions "^6.1.0"
+
 which-boxed-primitive@^1.0.2:
   version "1.0.2"
   resolved "https://registry.yarnpkg.com/which-boxed-primitive/-/which-boxed-primitive-1.0.2.tgz#13757bc89b209b049fe5d86430e21cf40a89a8e6"