Getting a scene in and out: data/ import and export

Chapter V

This module follows a dropped file — a .excalidraw JSON, or a PNG/SVG carrying an embedded scene — through data/blob.ts and data/json.ts back into live elements and appState, and then traces the mirror-image export path in data/index.ts and data/json.ts that serializes the Scene back out. The throughline is that persistence code is not a special App-level channel: it decodes/encodes bytes, then hands the result to the same Scene.replaceAllElements / updateScene commit point and the same Actions dispatch you've already seen used for drawing.

Figure I · pipelineFrom a browser drop event to elements in the Scene

4 stages

Press play — or step through the pipeline stage by stage.

walkthrough

Inside loadSceneOrLibraryFromBlob

packages/excalidraw/data/blob.ts · lines 138–195

lines 138–144

The signature carries the two pieces of context an import needs beyond the file itself: localAppState/localElements (the current Scene, used to repair bindings and preserve scroll position) and an optional native FileSystemFileHandle so later saves can write back to the same file.

line 146

It hands the raw blob to parseFileContents first, so by this point any PNG/SVG-embedded payload has already been unwrapped into a plain JSON string - this function never has to know it was looking at an image.

lines 148–159

JSON.parse turns the text into an object; if that fails on a file whose type is a recognized image, the failure is reclassified as ImageSceneDataError rather than a generic parse error - that's the signal App later uses to fall back to inserting the file as a plain picture instead of showing a corrupt-file message.

lines 160–181

This is the branch that matters for a .excalidraw drop: elements go through restoreElements (repairing bindings, dropping invisible elements) and appState through restoreAppState, seeded with the local theme/fileHandle and merged against whatever appState the file carried. The output is exactly the { elements, appState, files } triple that the Scene-commit step already knows how to consume.

lines 182–186

The same dropped-file plumbing also recognizes an .excalidrawlib payload by its content shape (not its file extension) and routes it to the library system instead of the Scene.

lines 187–195

Anything that's neither a valid scene nor a valid library collapses to one generic "invalid file" error, while an ImageSceneDataError is deliberately rethrown unchanged so the caller can distinguish "this image just has no embedded scene" from "this file is garbage".

138export const loadSceneOrLibraryFromBlob = async (139  blob: Blob | File,140  /** @see restore.localAppState */141  localAppState: AppState | null,142  localElements: readonly ExcalidrawElement[] | null,143  /** FileSystemFileHandle. Defaults to `blob.handle` if defined, otherwise null. */144  fileHandle?: FileSystemFileHandle | null,145) => {146  const contents = await parseFileContents(blob);147  let data;148  try {149    try {150      data = JSON.parse(contents);151    } catch (error: any) {152      if (isSupportedImageFile(blob)) {153        throw new ImageSceneDataError(154          "Image doesn't contain scene",155          "IMAGE_NOT_CONTAINS_SCENE_DATA",156        );157      }158      throw error;159    }160    if (isValidExcalidrawData(data)) {161      return {162        type: MIME_TYPES.excalidraw,163        data: {164          elements: restoreElements(data.elements, localElements, {165            repairBindings: true,166            deleteInvisibleElements: true,167          }),168          appState: restoreAppState(169            {170              theme: localAppState?.theme,171              fileHandle: fileHandle || blob.handle || null,172              ...cleanAppStateForExport(data.appState || {}),173              ...(localAppState174                ? getScrollToContentState(data.elements || [], localAppState)175                : {}),176            },177            localAppState,178          ),179          files: data.files || {},180        },181      };182    } else if (isValidLibrary(data)) {183      return {184        type: MIME_TYPES.excalidrawlib,185        data,186      };187    }188    throw new Error("Error: invalid file");189  } catch (error: any) {190    if (error instanceof ImageSceneDataError) {191      throw error;192    }193    throw new Error("Error: invalid file");194  }195};

step 1 of 6

32const parseFileContents = async (blob: Blob | File): Promise<string> => {33  let contents: string;3435  if (blob.type === MIME_TYPES.png) {36    try {37      return await (await import("./image")).decodePngMetadata(blob);38    } catch (error: any) {39      if (error.message === "INVALID") {40        throw new ImageSceneDataError(41          "Image doesn't contain scene",42          "IMAGE_NOT_CONTAINS_SCENE_DATA",43        );44      } else {45        throw new ImageSceneDataError("Error: cannot restore image");46      }47    }48  } else {49    if ("text" in Blob) {50      contents = await blob.text();51    } else {52      contents = await new Promise((resolve) => {53        const reader = new FileReader();54        reader.readAsText(blob, "utf8");55        reader.onloadend = () => {56          if (reader.readyState === FileReader.DONE) {57            resolve(reader.result as string);58          }59        };60      });61    }62    if (blob.type === MIME_TYPES.svg) {63      try {64        return decodeSvgBase64Payload({65          svg: contents,66        });67      } catch (error: any) {68        if (error.message === "INVALID") {69          throw new ImageSceneDataError(70            "Image doesn't contain scene",71            "IMAGE_NOT_CONTAINS_SCENE_DATA",72          );73        } else {74          throw new ImageSceneDataError("Error: cannot restore image");75        }76      }77    }78  }79  return contents;80};

packages/excalidraw/data/blob.ts · lines 32–80

Figure II · A PNG exported with "embed scene" checked isn't just pixels: encodePngMetadata slips a compressed copy of the .excalidraw JSON into a PNG tEXt metadata chunk, a spot ordinary image viewers ignore. Think of it as a shipping container with the original packing invoice zip-tied to the inside wall - a photo viewer only ever unpacks the crate (the pixels), but parseFileContents always checks for that zip-tied invoice first via decodePngMetadata (and the SVG branch does the same via a hidden XML comment and decodeSvgBase64Payload). That's why dragging an exported PNG/SVG back onto the canvas can restore the original editable drawing instead of inserting a picture.

52export const serializeAsJSON = (53  elements: readonly ExcalidrawElement[],54  appState: Partial<AppState>,55  files: BinaryFiles,56  type: "local" | "database",57): string => {58  const data: ExportedDataState = {59    type: EXPORT_DATA_TYPES.excalidraw,60    version: VERSIONS.excalidraw,61    source: getExportSource(),62    elements,63    appState:64      type === "local"65        ? cleanAppStateForExport(appState)66        : clearAppStateForDatabase(appState),67    files:68      type === "local"69        ? filterOutDeletedFiles(elements, files)70        : // will be stripped from JSON71          undefined,72  };7374  return JSON.stringify(data, null, 2);75};7677export const saveAsJSON = async ({78  data,79  filename,80  fileHandle,81}: {82  data: MaybePromise<JSONExportData>;83  filename: string;84  fileHandle: AppState["fileHandle"];85}) => {86  const blob = Promise.resolve(data).then(({ elements, appState, files }) => {87    const serialized = serializeAsJSON(elements, appState, files, "local");88    return new Blob([serialized], {89      type: MIME_TYPES.excalidraw,90    });91  });9293  const savedFileHandle = await fileSave(blob, {94    name: filename,95    extension: "excalidraw",96    description: "Excalidraw file",97    fileHandle: isImageFileHandle(fileHandle) ? null : fileHandle,98  });99  return { fileHandle: savedFileHandle };100};

packages/excalidraw/data/json.ts · lines 52–100

Figure III · serializeAsJSON builds the exact envelope - type: "excalidraw", version, source, elements, appState, files - that isValidExcalidrawData checks for on the way in, and that loadSceneOrLibraryFromBlob then reads into restoreElements/restoreAppState. saveAsJSON does nothing more than call serializeAsJSON, wrap the string in a Blob, and hand it to fileSave: import and export are reading and writing the same on-disk shape from opposite ends.

Connects

Persistence rides the same two rails you already know — Dropping a file doesn't reach into the Scene directly, and saving doesn't either. On the way in, App.loadFileToCanvas hands loadSceneOrLibraryFromBlob's result to this.syncActionResult, which calls this.scene.replaceAllElements - the identical commit point from "End to end: a user drags on the canvas to draw a rectangle" and from App.updateScene. On the way out, actionSaveToActiveFile and actionSaveFileToDisk in actionExport.tsx are ordinary registered Actions, the same registration pattern from "Actions: the general mechanism behind every state change" - their perform() just calls saveAsJSON with the current elements/appState/files. Import and export are producers/consumers of the Scene API, not a parallel system.

packages/excalidraw/components/App.tsx · syncActionResult :12499–12508packages/excalidraw/components/App.tsx · replaceAllElements :2816–2828packages/excalidraw/actions/actionExport.tsx · saveAsJSON :300–335

checkpoint

Checkpoint

Answered in place — nothing is graded, everything is explained. 0 / 2 passed

You export a drawing to PNG with "embed scene" enabled, then later drag that PNG back onto the canvas. Why do you get the original editable elements back instead of just an inserted picture?

After loadSceneOrLibraryFromBlob returns a parsed { elements, appState, files } object, what actually makes those elements the live scene content?