CodeVetter · Repo Unpack · Data flow
excalidraw/excalidraw
A scene is an ordered list of elements plus AppState, with image bytes kept in a separate BinaryFiles map. Local edits pass through the Store, which both feeds undo history and the public onChange/onIncrement callbacks. The app then fans changes into localStorage, IndexedDB, and — when a room is open — an encrypted socket broadcast plus a Firebase transaction. Anything loaded back in goes through restoreElements/restoreAppState and, for multiplayer, reconcileElements on version plus versionNonce.
- Elements carry collab metadata on the base type: monotonically increasing version, random versionNonce for tie-breaks, fractional index (string brand) for z-order, updated timestamp, and isDeleted. index is kept aligned with array order by syncMovedIndices and syncInvalidIndices.
- Local autosave is owned by LocalData.save, debounced by SAVE_TO_LOCAL_STORAGE_TIMEOUT (300ms). It writes non-deleted elements to localStorage key excalidraw and cleared app state to excalidraw-state, then puts image binaries in IndexedDB database files-db / store files-store via idb-keyval. QuotaExceededError flips localStorageQuotaExceededAtom. Saves are skipped when document.hidden or the collaboration locker is held.
- The app onChange callback is the fan-out. If collabAPI.isCollaborating() it calls collabAPI.syncElements(elements). Otherwise, when LocalData.isSavePaused() is false, it calls LocalData.save and afterwards rewrites image elements whose status should become saved via newElementWith.
- Cross-tab sync stores timestamps under version-dataState and version-files. updateBrowserStateVersion writes Date.now() into both localStorage and an in-memory LOCAL_STATE_VERSIONS map. On focus or visibility the app calls isBrowserStorageStateNewer and, for files, LocalData.fileStorage.getFiles for image ids not already in memory.
- Socket payloads are JSON, UTF-8 encoded, then AES-GCM encrypted with the room key. Portal._broadcastSocketData emits WS_EVENTS.SERVER (server-broadcast) or SERVER_VOLATILE. broadcastScene sends only elements whose version is newer than broadcastedElementVersions unless syncAll is set, and SCENE_INIT requires syncAll. File upload is throttled at FILE_UPLOAD_TIMEOUT (300ms) and flips image status to saved so peers know to pull bytes.
- Firebase scene documents store {sceneVersion, ciphertext: Bytes, iv: Bytes}. saveToFirebase runs a Firestore transaction on scenes/{roomId}: if the doc exists it decrypts the previous elements, reconcileElements against the local syncable set, and writes the merged ciphertext. A WeakMap FirebaseSceneVersionCache skips writes when the socket already persisted that getSceneVersion.
- reconcileElements keeps the local element when it is being edited (editingTextElement, resizingElement, newElement), when local.version is greater, or when versions match and local.versionNonce is less than or equal to the remote nonce. Fractional indices are revalidated in dev and test (validateFractionalIndices throws); in production the check is throttled to once a minute and does not throw.
- Syncable elements exclude invisibly small elements. Deleted elements stay syncable only until DELETED_ELEMENT_TIMEOUT (24h) so peers can observe the deletion, then they drop out of getSyncableElements.
- Startup scene load order in initializeScene: importFromLocalStorage, then optionally #json= via importFromBackend (decompress + decrypt, falling back to legacy_decodeFromBackend), then #url= via fetch + loadFromBlob, then #room= via collabAPI.startCollaboration. External scenes prompt with openConfirmModal unless the canvas is empty or the link is a collab room. Non-room imports then history.replaceState back to the origin.
- Share-link import tries the new compressed format first (decompressData with decryptionKey). On failure legacy_decodeFromBackend slices a 12-byte IV off the front, and if that throws it retries with a zero IV for the oldest files.
- Keys are 128-bit AES-GCM (ENCRYPTION_KEY_BITS). generateEncryptionKey uses crypto.subtle.generateKey and exports the JWK k field. getCryptoKey imports alg A128GCM. IVs are 12 random bytes from crypto.getRandomValues. Room ids are 10 random bytes hex-encoded (ROOM_ID_BYTES).
- Collab image bytes and share-link image bytes use different Storage prefixes: FIREBASE_STORAGE_PREFIXES.collabFiles is /files/rooms and shareLinkFiles is /files/shareLinks. Cache-Control on upload is public, max-age=31536000.