Order based on fractional index in history action

Introducing independent change detection for appState and elements

Generalizing object change, cleanup, refactoring, comments, solving typing issues

Shaping increment, change, delta hierarchy

Structural clone of elements

Introducing store and incremental API

Disabling buttons for canvas actions, smaller store and changes improvements

Update history entry based on latest changes, iterate through the stack for visible changes to limit empty commands

Solving concurrency issues, solving (partly) linear element issues,  introducing commitToStore breaking change

Fixing existing tests, updating snapshots

Trying to be smarter on the appstate change detection

Extending collab test, refactoring action / updateScene params, bugfixes

Resetting snapshots

Resetting snapshots

UI / API tests for history - WIP

Changing actions related to the observed appstate to at least update the store snapshot - WIP

Adding skipping of snapshot update flag for most no-breaking changes compatible solution

Ignoring uncomitted elements from local async actions, updating store directly in updateScene

Bound element issues - WIP

dev-docs/docs/@excalidraw/excalidraw/api/children-components/sidebar.mdx

@@ -80,7 +80,7 @@ A given tab trigger button that switches to a given sidebar tab. It must be rend
 | `className` | `string` | No |  |
 | `style` | `React.CSSProperties` | No |  |
 
-You can use the [`ref.toggleSidebar({ name: "custom" })`](/docs/@excalidraw/excalidraw/api/props/ref#toggleSidebar) api to control the sidebar, but we export a trigger button to make UI use cases easier.
+You can use the [`ref.toggleSidebar({ name: "custom" })`](/docs/@excalidraw/excalidraw/api/props/excalidraw-api#toggleSidebar) api to control the sidebar, but we export a trigger button to make UI use cases easier.
 
 ## Example
 

dev-docs/docs/@excalidraw/excalidraw/api/excalidraw-element-skeleton.mdx

@@ -10,13 +10,17 @@ The [`ExcalidrawElementSkeleton`](https://github.com/excalidraw/excalidraw/blob/
 
 **_Signature_**
 
-<pre>
-  convertToExcalidrawElements(elements:{" "}
-  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/data/transform.ts#L133">
-    ExcalidrawElementSkeleton
-  </a>
-  )
-</pre>
+```ts
+convertToExcalidrawElements(
+  elements: ExcalidrawElementSkeleton,
+  opts?: { regenerateIds: boolean }
+): ExcalidrawElement[]
+```
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `elements` | [ExcalidrawElementSkeleton](https://github.com/excalidraw/excalidraw/blob/master/src/data/transform.ts#L137) |  | The Excalidraw element Skeleton which needs to be converted to Excalidraw elements. |
+| `opts` | `{ regenerateIds: boolean }` | ` {regenerateIds: true}` | By default `id` will be regenerated for all the elements irrespective of whether you pass the `id` so if you don't want the ids to regenerated, you can set this attribute to `false`. |
 
 **_How to use_**
 
@@ -24,13 +28,13 @@ The [`ExcalidrawElementSkeleton`](https://github.com/excalidraw/excalidraw/blob/
 import { convertToExcalidrawElements } from "@excalidraw/excalidraw";
 ```
 
-This function converts the Excalidraw Element Skeleton to excalidraw elements which could be then rendered on the canvas. Hence calling this function is necessary before passing it to APIs like [`initialData`](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api/props/initialdata), [`updateScene`](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api/props/ref#updatescene) if you are using the Skeleton API
+This function converts the Excalidraw Element Skeleton to excalidraw elements which could be then rendered on the canvas. Hence calling this function is necessary before passing it to APIs like [`initialData`](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api/props/initialdata), [`updateScene`](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api/props/excalidraw-api#updatescene) if you are using the Skeleton API
 
 ## Supported Features
 
 ### Rectangle, Ellipse, and Diamond
 
-To create these shapes you need to pass its `type` and `x` and `y` coordinates for position. The rest of the attributes are optional_.
+To create these shapes you need to pass its `type` and `x` and `y` coordinates for position. The rest of the attributes are optional\_.
 
 For the Skeleton API to work, `convertToExcalidrawElements` needs to be called before passing it to Excalidraw Component via initialData, updateScene or any such API.
 
@@ -427,3 +431,45 @@ convertToExcalidrawElements([
 ```
 
 ![image](https://github.com/excalidraw/excalidraw/assets/11256141/a8b047c8-2eed-4aea-82a2-e1e6bbddb8d4)
+
+### Frames
+
+To create a frame, you need to pass `type`, `children` (list of Excalidraw element ids). The rest of the attributes are optional.
+
+```ts
+{
+  type: "frame";
+  children: readonly ExcalidrawElement["id"][];
+  name?: string;
+ } & Partial<ExcalidrawFrameElement>);
+```
+
+```ts
+convertToExcalidrawElements([
+  {
+    "type": "rectangle",
+    "x": 10,
+    "y": 10,
+    "strokeWidth": 2,
+    "id": "1"
+  },
+  {
+    "type": "diamond",
+    "x": 120,
+    "y": 20,
+    "backgroundColor": "#fff3bf",
+    "strokeWidth": 2,
+    "label": {
+      "text": "HELLO EXCALIDRAW",
+      "strokeColor": "#099268",
+      "fontSize": 30
+    },
+    "id": "2"
+  },
+  {
+    "type": "frame",
+    "children": ["1", "2"],
+    "name": "My frame"
+  }]
+}
+```

dev-docs/docs/@excalidraw/excalidraw/api/props/excalidraw-api.mdx

@@ -1,29 +1,28 @@
-# ref
+# excalidrawAPI
 
 <pre>
-  <a href="https://reactjs.org/docs/refs-and-the-dom.html#creating-refs">
-    createRef
-  </a>{" "}
-  &#124;{" "}
-  <a href="https://reactjs.org/docs/hooks-reference.html#useref">useRef</a>{" "}
-  &#124;{" "}
-  <a href="https://reactjs.org/docs/refs-and-the-dom.html#callback-refs">
-    callbackRef
-  </a>{" "}
-  &#124; <br />
-  &#123; current: &#123; readyPromise: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/utils.ts#L460">
-    resolvablePromise
-  </a> } }
+  (api:{" "}
+  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L616">
+    ExcalidrawAPI
+  </a>
+  ) => void;
 </pre>
 
-You can pass a `ref` when you want to access some excalidraw APIs. We expose the below APIs:
+Once the callback is triggered, you will need to store the api in state to access it later.
+
+```jsx showLineNumbers
+export default function App() {
+  const [excalidrawAPI, setExcalidrawAPI] = useState(null);
+  return <Excalidraw excalidrawAPI={{(api)=> setExcalidrawAPI(api)}} />;
+}
+```
+
+You can use this prop when you want to access some [Excalidraw APIs](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L616). We expose the below APIs :point_down:
 
 | API | Signature | Usage |
 | --- | --- | --- |
-| ready | `boolean` | This is set to true once Excalidraw is rendered |
-| [readyPromise](#readypromise) | `function` | 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) | `function` | updates the scene with the sceneData |
-| [updateLibrary](#updatelibrary) | `function` | updates the scene with the sceneData |
+| [updateLibrary](#updatelibrary) | `function` | updates the library |
 | [addFiles](#addfiles) | `function` | add files data to the appState |
 | [resetScene](#resetscene) | `function` | Resets the scene. If `resetLoadingState` is passed as true then it will also force set the loading state to false. |
 | [getSceneElementsIncludingDeleted](#getsceneelementsincludingdeleted) | `function` | Returns all the elements including the deleted in the scene |
@@ -39,54 +38,15 @@ You can pass a `ref` when you want to access some excalidraw APIs. We expose the
 | [setCursor](#setcursor) | `function` | This API can be used to set customise the mouse cursor on the canvas |
 | [resetCursor](#resetcursor) | `function` | This API can be used to reset to default mouse cursor on the canvas |
 | [toggleMenu](#togglemenu) | `function` | Toggles specific menus on/off |
+| [onChange](#onChange) | `function` | Subscribes to change events |
+| [onPointerDown](#onPointerDown) | `function` | Subscribes to `pointerdown` events |
+| [onPointerUp](#onPointerUp) | `function` | Subscribes to `pointerup` events |
 
-## readyPromise
+:::info The `Ref` support has been removed in v0.17.0 so if you are using refs, please update the integration to use the `excalidrawAPI`.
 
-<pre>
-  const excalidrawRef = &#123; current:&#123; readyPromise:
-  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/utils.ts#L460">
-    &nbsp;resolvablePromise
-  </a>
-  &nbsp;&#125; &#125;
-</pre>
+Additionally `ready` and `readyPromise` from the API have been discontinued. These APIs were found to be superfluous, and as part of the effort to streamline the APIs and maintain simplicity, they were removed in version v0.17.0.
 
-Since plain object is passed as a `ref`, the `readyPromise` is resolved as soon as the component is mounted. Most of the time you will not need this unless you have a specific use case where you can't pass the `ref` in the react way and want to do some action on the host when this promise resolves.
-
-```jsx showLineNumbers
-const resolvablePromise = () => {
-  let resolve;
-  let reject;
-  const promise = new Promise((_resolve, _reject) => {
-    resolve = _resolve;
-    reject = _reject;
-  });
-  promise.resolve = resolve;
-  promise.reject = reject;
-  return promise;
-};
-
-const App = () => {
-  const excalidrawRef = useMemo(
-    () => ({
-      current: {
-        readyPromise: resolvablePromise(),
-      },
-    }),
-    [],
-  );
-
-  useEffect(() => {
-    excalidrawRef.current.readyPromise.then((api) => {
-      console.log("loaded", api);
-    });
-  }, [excalidrawRef]);
-  return (
-    <div style={{ height: "500px" }}>
-      <Excalidraw ref={excalidrawRef} />
-    </div>
-  );
-};
-```
+:::
 
 ## updateScene
 
@@ -105,7 +65,8 @@ You can use this function to update the scene with the sceneData. It accepts the
 | `elements` | [`ImportedDataState["elements"]`](https://github.com/excalidraw/excalidraw/blob/master/src/data/types.ts#L38) | The `elements` to be updated in the scene |
 | `appState` | [`ImportedDataState["appState"]`](https://github.com/excalidraw/excalidraw/blob/master/src/data/types.ts#L39) | The `appState` to be updated in the scene. |
 | `collaborators` | <code>Map<string, <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L37">Collaborator></a></code> | The list of collaborators to be updated in the scene. |
-| `commitToHistory` | `boolean` | Implies if the `history (undo/redo)` should be recorded. Defaults to `false`. |
+| `commitToStore` | `boolean` | Implies if the `store` should update it's snapshot, capture the update and calculates the diff. Captured changes are emmitted and listened to by other components, such as `History` for undo / redo purposes. Defaults to `false`. |
+| `skipSnapshotUpdate` | `boolean` | Implies whether the `store` should skip update of its snapshot, which is necessary for correct diff calculation. Relevant only when `elements` or `appState` are passed in. When `true`, `commitToStore` value will be ignored. Defaults to `false`. |
 
 ```jsx live
 function App() {
@@ -387,14 +348,25 @@ This API can be used to get the files present in the scene. It may contain files
 
 This API has the below signature. It sets the `tool` passed in param as the active tool.
 
-<pre>
-  (tool: <br /> &#123; type:{" "}
-  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/shapes.tsx#L15">
-    SHAPES
-  </a>
-  [number]["value"]&#124; "eraser" &#125; &#124;
-  <br /> &#123; type: "custom"; customType: string &#125;) => void
-</pre>
+```ts
+(
+  tool: (
+    | (
+        | { type: Exclude<ToolType, "image"> }
+        | {
+            type: Extract<ToolType, "image">;
+            insertOnCanvasDirectly?: boolean;
+          }
+      )
+    | { type: "custom"; customType: string }
+  ) & { locked?: boolean },
+) => {};
+```
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type` | [ToolType](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L91) | `selection` | The tool type which should be set as active tool. When setting `image` as active tool, the insertion onto canvas when using image tool is disabled by default, so you can enable it by setting `insertOnCanvasDirectly` to `true` |
+| `locked` | `boolean` | `false` | Indicates whether the the active tool should be locked. It behaves the same way when using the `lock` tool in the editor interface |
 
 ## setCursor
 
@@ -421,3 +393,51 @@ This API is especially useful when you render a custom [`<Sidebar/>`](/docs/@exc
 ```
 
 This API can be used to reset to default mouse cursor.
+
+## onChange
+
+```tsx
+(
+  callback: (
+    elements: readonly ExcalidrawElement[],
+    appState: AppState,
+    files: BinaryFiles,
+  ) => void
+) => () => void
+```
+
+Subscribes to change events, similar to [`props.onChange`](/docs/@excalidraw/excalidraw/api/props#onchange).
+
+Returns an unsubscribe function.
+
+## onPointerDown
+
+```tsx
+(
+  callback: (
+    activeTool: AppState["activeTool"],
+    pointerDownState: PointerDownState,
+    event: React.PointerEvent<HTMLElement>,
+  ) => void,
+) => () => void
+```
+
+Subscribes to canvas `pointerdown` events.
+
+Returns an unsubscribe function.
+
+## onPointerUp
+
+```tsx
+(
+  callback: (
+    activeTool: AppState["activeTool"],
+    pointerDownState: PointerDownState,
+    event: PointerEvent,
+  ) => void,
+) => () => void
+```
+
+Subscribes to canvas `pointerup` events.
+
+Returns an unsubscribe function.

dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdx

@@ -1,11 +1,11 @@
 # Props
 
-All `props` are *optional*.
+All `props` are _optional_.
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
-| [`initialData`](/docs/@excalidraw/excalidraw/api/props/initialdata) |  `object` &#124; `null` &#124; <code>Promise<object &#124; null></code> | `null` | The initial data with which app loads. |
-| [`ref`](/docs/@excalidraw/excalidraw/api/props/ref) | `object` | _ | `Ref` to be passed to Excalidraw |
+| [`initialData`](/docs/@excalidraw/excalidraw/api/props/initialdata) | `object` &#124; `null` &#124; <code>Promise<object &#124; null></code> | `null` | The initial data with which app loads. |
+| [`excalidrawAPI`](/docs/@excalidraw/excalidraw/api/props/excalidraw-api) | `function` | _ | Callback triggered with the excalidraw api once rendered |
 | [`isCollaborating`](#iscollaborating) | `boolean` | _ | This indicates if the app is in `collaboration` mode |
 | [`onChange`](#onchange) | `function` | _ | This callback is triggered whenever the component updates due to any change. This callback will receive the excalidraw `elements` and the current `app state`. |
 | [`onPointerUpdate`](#onpointerupdate) | `function` | _ | Callback triggered when mouse pointer is updated. |
@@ -37,7 +37,7 @@ Beyond attributes that Excalidraw elements already support, you can store `custo
 
 You can use this to add any extra information you need to keep track of.
 
-You can add `customData` to elements when passing them as [`initialData`](/docs/@excalidraw/excalidraw/api/props/initialdata), or using [`updateScene`](/docs/@excalidraw/excalidraw/api/props/ref#updatescene) / [`updateLibrary`](/docs/@excalidraw/excalidraw/api/props/ref#updatelibrary) afterwards.
+You can add `customData` to elements when passing them as [`initialData`](/docs/@excalidraw/excalidraw/api/props/initialdata), or using [`updateScene`](/docs/@excalidraw/excalidraw/api/props/excalidraw-api#updatescene) / [`updateLibrary`](/docs/@excalidraw/excalidraw/api/props/excalidraw-api#updatelibrary) afterwards.
 
 ```js showLineNumbers
 {
@@ -93,8 +93,16 @@ This callback is triggered when mouse pointer is updated.
 
 This prop if passed will be triggered on pointer down events and has the below signature.
 
+
 <pre>
-(activeTool: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L115"> AppState["activeTool"]</a>, pointerDownState: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L424">PointerDownState</a>) => void
+(activeTool:{" "}
+  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L115">
+    {" "}
+    AppState["activeTool"]
+  </a>
+  , pointerDownState: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L424">
+    PointerDownState
+  </a>) => void
 </pre>
 
 ### onScrollChange
@@ -110,7 +118,11 @@ This prop if passed will be triggered when canvas is scrolled and has the below
 This callback is triggered if passed when something is pasted into the scene. You can use this callback in case you want to do something additional when the paste event occurs.
 
 <pre>
-(data: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/clipboard.ts#L18">ClipboardData</a>, event: ClipboardEvent &#124; null) => boolean
+  (data:{" "}
+  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/clipboard.ts#L18">
+    ClipboardData
+  </a>
+  , event: ClipboardEvent &#124; null) => boolean
 </pre>
 
 This callback must return a `boolean` value or a [promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise) which resolves to a boolean value.
@@ -136,8 +148,11 @@ It is invoked with empty items when user clears the library. You can use this ca
 This prop if passed will be triggered when clicked on `link`. To handle the redirect yourself (such as when using your own router for internal links), you must call `event.preventDefault()`.
 
 <pre>
-(element: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L114">ExcalidrawElement</a>, 
- event: CustomEvent&lt;&#123; nativeEvent: MouseEvent }&gt;) => void
+  (element:{" "}
+  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L114">
+    ExcalidrawElement
+  </a>
+  , event: CustomEvent&lt;&#123; nativeEvent: MouseEvent }&gt;) => void
 </pre>
 
 Example:
@@ -180,30 +195,30 @@ import { defaultLang, languages } from "@excalidraw/excalidraw";
 
 ### viewModeEnabled
 
-This prop indicates whether the app is in `view mode`. When supplied, the value takes precedence over *intialData.appState.viewModeEnabled*, the `view mode` will be fully controlled by the host app, and users won't be able to toggle it from within the app.
+This prop indicates whether the app is in `view mode`. When supplied, the value takes precedence over _intialData.appState.viewModeEnabled_, the `view mode` will be fully controlled by the host app, and users won't be able to toggle it from within the app.
 
 ### zenModeEnabled
 
-This prop indicates whether the app is in `zen mode`. When supplied, the value takes precedence over *intialData.appState.zenModeEnabled*, the `zen mode` will be fully controlled by the host app, and users won't be able to toggle it from within the app.
+This prop indicates whether the app is in `zen mode`. When supplied, the value takes precedence over _intialData.appState.zenModeEnabled_, the `zen mode` will be fully controlled by the host app, and users won't be able to toggle it from within the app.
 
 ### gridModeEnabled
 
-This prop indicates whether the shows the grid. When supplied, the value takes precedence over *intialData.appState.gridModeEnabled*, the grid will be fully controlled by the host app, and users won't be able to toggle it from within the app.
+This prop indicates whether the shows the grid. When supplied, the value takes precedence over _intialData.appState.gridModeEnabled_, the grid will be fully controlled by the host app, and users won't be able to toggle it from within the app.
 
 ### libraryReturnUrl
 
 If supplied, this URL will be used when user tries to install a library from [libraries.excalidraw.com](https://libraries.excalidraw.com).  
-Defaults to *window.location.origin + window.location.pathname*. To install the libraries in the same tab from which it was opened, you need to set `window.name` (to any alphanumeric string) — if it's not set it will open in a new tab.
+Defaults to _window.location.origin + window.location.pathname_. To install the libraries in the same tab from which it was opened, you need to set `window.name` (to any alphanumeric string) — if it's not set it will open in a new tab.
 
 ### theme
 
-This prop controls Excalidraw's theme. When supplied, the value takes precedence over *intialData.appState.theme*, the theme will be fully controlled by the host app, and users won't be able to toggle it from within the app unless *UIOptions.canvasActions.toggleTheme* is set to `true`, in which case the `theme` prop will control Excalidraw's default theme with ability to allow theme switching (you must take care of updating the `theme` prop when you detect a change to `appState.theme` from the [onChange](#onchange) callback).
+This prop controls Excalidraw's theme. When supplied, the value takes precedence over _intialData.appState.theme_, the theme will be fully controlled by the host app, and users won't be able to toggle it from within the app unless _UIOptions.canvasActions.toggleTheme_ is set to `true`, in which case the `theme` prop will control Excalidraw's default theme with ability to allow theme switching (you must take care of updating the `theme` prop when you detect a change to `appState.theme` from the [onChange](#onchange) callback).
 
 You can use [`THEME`](/docs/@excalidraw/excalidraw/api/utils#theme) to specify the theme.
 
 ### name
 
-This prop sets the `name` of the drawing which will be used when exporting the drawing. When supplied, the value takes precedence over *intialData.appState.name*, the `name` will be fully controlled by host app and the users won't be able to edit from within Excalidraw.
+This prop sets the `name` of the drawing which will be used when exporting the drawing. When supplied, the value takes precedence over _intialData.appState.name_, the `name` will be fully controlled by host app and the users won't be able to edit from within Excalidraw.
 
 
 ### detectScroll
@@ -236,4 +251,4 @@ validateEmbeddable?: boolean | string[] | RegExp | RegExp[] | ((link: string) =>
 
 This is an optional property. By default we support a handful of well-known sites. You may allow additional sites or disallow the default ones by supplying a custom validator. If you pass `true`, all URLs will be allowed. You can also supply a list of hostnames, RegExp (or list of RegExp objects), or a function. If the function returns `undefined`, the built-in validator will be used.
 
-Supplying a list of hostnames (with or without `www.`) is the preferred way to allow a specific list of domains.
+Supplying a list of hostnames (with or without `www.`) is the preferred way to allow a specific list of domains.

dev-docs/docs/@excalidraw/excalidraw/api/props/ui-options.mdx

@@ -1,6 +1,6 @@
 # UIOptions
 
-This prop can be used to customise UI of Excalidraw. Currently we support customising [`canvasActions`](#canvasactions), [`dockedSidebarBreakpoint`](#dockedsidebarbreakpoint) and [`welcomeScreen`](#welcmescreen).
+This prop can be used to customise UI of Excalidraw. Currently we support customising [`canvasActions`](#canvasactions), [`dockedSidebarBreakpoint`](#dockedsidebarbreakpoint) [`welcomeScreen`](#welcmescreen) and [`tools`](#tools).
 
 <pre>
   &#123;
@@ -70,3 +70,12 @@ function App() {
   );
 }
 ```
+
+## tools
+
+This `prop ` controls the visibility of the tools in the editor.
+Currently you can control the visibility of `image` tool via this prop.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| image | boolean | true | Decides whether `image` tool should be visible.

dev-docs/docs/@excalidraw/excalidraw/api/utils/utils-intro.md

@@ -129,7 +129,7 @@ if (contents.type === MIME_TYPES.excalidraw) {
 
 <pre>
 loadSceneOrLibraryFromBlob(<br/>&nbsp;
-  blob: <a href="https://developer.mozilla.org/en-US/docs/Web/API/Blob">Blob</a>,
+  blob: <a href="https://developer.mozilla.org/en-US/docs/Web/API/Blob">Blob</a>,<br/>&nbsp;
   localAppState: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L95">AppState</a> | null,<br/>&nbsp;
   localElements: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L114">ExcalidrawElement[]</a> | null,<br/>&nbsp;
   fileHandle?: FileSystemHandle | null<br/>
@@ -164,9 +164,9 @@ import { isLinearElement } from "@excalidraw/excalidraw";
 
 **Signature**
 
-```tsx
+<pre>
 isLinearElement(elementType?: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L80">ExcalidrawElement</a>): boolean
-```
+</pre>
 
 ### getNonDeletedElements
 
@@ -195,8 +195,10 @@ import { mergeLibraryItems } from "@excalidraw/excalidraw";
 **_Signature_**
 
 <pre>
-mergeLibraryItems(localItems: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L250">LibraryItems</a>,<br/>&nbsp;
- otherItems: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L200">LibraryItems</a>) => <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L250">LibraryItems</a>
+mergeLibraryItems(<br/>&nbsp;
+  localItems: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L250">LibraryItems</a>,<br/>&nbsp;
+  otherItems: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L200">LibraryItems</a><br/>
+): <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L250">LibraryItems</a>
 </pre>
 
 ### parseLibraryTokensFromUrl
@@ -331,13 +333,15 @@ const App = () => (
 render(<App />);
 ```
 
-The `device` has the following `attributes`
+The `device` has the following `attributes`, some grouped into `viewport` and `editor` objects, per context.
 
 | Name | Type | Description |
 | --- | --- | --- |
-| `isMobile` | `boolean` | Set to `true` when the device is `mobile` |
-| `isTouchScreen` | `boolean` | Set to `true` for `touch` devices |
-| `canDeviceFitSidebar` | `boolean` | Implies whether there is enough space to fit the `sidebar` |
+| `viewport.isMobile` | `boolean` | Set to `true` when viewport is in `mobile` breakpoint |
+| `viewport.isLandscape` | `boolean` | Set to `true` when the viewport is in `landscape` mode |
+| `editor.canFitSidebar` | `boolean` | Set to `true` if there's enough space to fit the `sidebar` |
+| `editor.isMobile` | `boolean` | Set to `true` when editor container is in `mobile` breakpoint |
+| `isTouchScreen` | `boolean` | Set to `true` for `touch` when touch event detected |
 
 ### i18n
 
@@ -382,3 +386,94 @@ function App() {
   );
 }
 ```
+
+### getCommonBounds
+
+This util can be used to get the common bounds of the passed elements.
+
+**_Signature_**
+
+```ts
+getCommonBounds(
+  elements: readonly ExcalidrawElement[]
+): readonly [
+  minX: number,
+  minY: number,
+  maxX: number,
+  maxY: number,
+]
+```
+
+**_How to use_**
+
+```js
+import { getCommonBounds } from "@excalidraw/excalidraw";
+```
+
+### elementsOverlappingBBox
+
+To filter `elements` that are inside, overlap, or contain the `bounds` rectangle.
+
+The bounds check is approximate and does not precisely follow the element's shape. You can also supply `errorMargin` which effectively makes the `bounds` larger by that amount.
+
+This API has 3 `type`s of operation: `overlap`, `contain`, and `inside`:
+
+- `overlap` - filters elements that are overlapping or inside bounds.
+- `contain` - filters elements that are inside bounds or bounds inside elements.
+- `inside` - filters elements that are inside bounds.
+
+**_Signature_**
+
+<pre>
+elementsOverlappingBBox(<br/>&nbsp;
+  elements: readonly NonDeletedExcalidrawElement[];<br/>&nbsp;
+  bounds: <a href="https://github.com/excalidraw/excalidraw/blob/9c425224c789d083bf16e0597ce4a429b9ee008e/src/element/bounds.ts#L37-L42">Bounds</a> | ExcalidrawElement;<br/>&nbsp;
+  errorMargin?: number;<br/>&nbsp;
+  type: "overlap" | "contain" | "inside";<br/>
+): NonDeletedExcalidrawElement[];
+</pre>
+
+**_How to use_**
+
+```js
+import { elementsOverlappingBBox } from "@excalidraw/excalidraw";
+```
+
+### isElementInsideBBox
+
+Lower-level API than `elementsOverlappingBBox` to check if a single `element` is inside `bounds`. If `eitherDirection=true`, returns `true` if `element` is fully inside `bounds` rectangle, or vice versa. When `false`, it returns `true` only for the former case.
+
+**_Signature_**
+
+<pre>
+isElementInsideBBox(<br/>&nbsp;
+  element: NonDeletedExcalidrawElement,<br/>&nbsp;
+  bounds: <a href="https://github.com/excalidraw/excalidraw/blob/9c425224c789d083bf16e0597ce4a429b9ee008e/src/element/bounds.ts#L37-L42">Bounds</a>,<br/>&nbsp;
+  eitherDirection = false,<br/>
+): boolean
+</pre>
+
+**_How to use_**
+
+```js
+import { isElementInsideBBox } from "@excalidraw/excalidraw";
+```
+
+### elementPartiallyOverlapsWithOrContainsBBox
+
+Checks if `element` is overlapping the `bounds` rectangle, or is fully inside.
+
+**_Signature_**
+
+<pre>
+elementPartiallyOverlapsWithOrContainsBBox(<br/>&nbsp;
+  element: NonDeletedExcalidrawElement,<br/>&nbsp;
+  bounds: <a href="https://github.com/excalidraw/excalidraw/blob/9c425224c789d083bf16e0597ce4a429b9ee008e/src/element/bounds.ts#L37-L42">Bounds</a>,<br/>
+): boolean
+</pre>
+
+**_How to use_**
+
+```js
+import { elementPartiallyOverlapsWithOrContainsBBox } from "@excalidraw/excalidraw";
+```

dev-docs/docs/@excalidraw/excalidraw/development.mdx

@@ -43,7 +43,7 @@ Once the version is released `@excalibot` will post a comment with the release v
 To release the next stable version follow the below steps:
 
 ```bash
-yarn prerelease version
+yarn prerelease:excalidraw
 ```
 
 You need to pass the `version` for which you want to create the release. This will make the changes needed before making the release like updating `package.json`, `changelog` and more.
@@ -51,7 +51,7 @@ You need to pass the `version` for which you want to create the release. This wi
 The next step is to run the `release` script:
 
 ```bash
-yarn release
+yarn release:excalidraw
 ```
 
 This will publish the package.

dev-docs/docs/@excalidraw/excalidraw/faq.mdx

@@ -31,6 +31,17 @@ We strongly recommend turning it off. You can follow the steps below on how to d
 If disabling this setting doesn't fix the display of text elements, please consider opening an [issue](https://github.com/excalidraw/excalidraw/issues/new) on our GitHub, or message us on [Discord](https://discord.gg/UexuTaE).
 
 
+### ReferenceError: process is not defined
+
+When using `vite` or any build tools, you will have to make sure the `process` is accessible as we are accessing `process.env.IS_PREACT` to decide whether to use `preact` build.
+
+Since Vite removes env variables by default, you can update the vite config to ensure its available :point_down:
+
+```
+ define: {
+    "process.env.IS_PREACT": process.env.IS_PREACT,
+  },
+```
 
 ## Need help?
 

dev-docs/docs/@excalidraw/excalidraw/integration.mdx

@@ -30,32 +30,17 @@ function App() {
 }
 ```
 
-### Rendering Excalidraw only on client
+### Next.js
 
 Since _Excalidraw_ doesn't support server side rendering, you should render the component once the host is `mounted`.
 
 Here are two ways on how you can render **Excalidraw** on **Next.js**.
 
-1. Importing Excalidraw once **client** is rendered.
 
-```jsx showLineNumbers
-import { useState, useEffect } from "react";
-export default function App() {
-  const [Excalidraw, setExcalidraw] = useState(null);
-  useEffect(() => {
-    import("@excalidraw/excalidraw").then((comp) =>
-      setExcalidraw(comp.Excalidraw),
-    );
-  }, []);
-  return <>{Excalidraw && <Excalidraw />}</>;
-}
-```
 
-Here is a working [demo](https://codesandbox.io/p/sandbox/excalidraw-with-next-5xb3d)
+1. Using **Next.js Dynamic** import [Recommended].
 
-2. Using **Next.js Dynamic** import.
-
-Since Excalidraw doesn't server side rendering so you can also use `dynamic import` to render by setting `ssr` to `false`. However one drawback is the `Refs` don't work with dynamic import in Next.js. We are working on overcoming this and have a better API.
+Since Excalidraw doesn't support server side rendering so you can also use `dynamic import` to render by setting `ssr` to `false`.
 
 ```jsx showLineNumbers
 import dynamic from "next/dynamic";
@@ -72,8 +57,47 @@ export default function App() {
 
 Here is a working [demo](https://codesandbox.io/p/sandbox/excalidraw-with-next-dynamic-k8yjq2).
 
+
+2. Importing Excalidraw once **client** is rendered.
+
+```jsx showLineNumbers
+import { useState, useEffect } from "react";
+export default function App() {
+  const [Excalidraw, setExcalidraw] = useState(null);
+  useEffect(() => {
+    import("@excalidraw/excalidraw").then((comp) =>
+      setExcalidraw(comp.Excalidraw),
+    );
+  }, []);
+  return <>{Excalidraw && <Excalidraw />}</>;
+}
+```
+
+Here is a working [demo](https://codesandbox.io/p/sandbox/excalidraw-with-next-5xb3d)
+
 The `types` are available at `@excalidraw/excalidraw/types`, you can view [example for typescript](https://codesandbox.io/s/excalidraw-types-9h2dm)
 
+### Preact
+
+Since we support `umd` build ships with `react/jsx-runtime` and `react-dom/client` inlined with the package. This conflicts with `Preact` and hence the build doesn't work directly with `Preact`.
+
+However we have shipped a separate build for `Preact` so if you are using `Preact` you need to set `process.env.IS_PREACT` to `true` to use the `Preact` build.
+
+Once the above `env` variable is set, you will be able to use the package in `Preact` as well.
+
+:::info
+
+When using `vite` or any build tools, you will have to make sure the `process` is accessible as we are accessing `process.env.IS_PREACT` to decide whether to use `preact` build.
+
+Since Vite removes env variables by default, you can update the vite config to ensure its available :point_down:
+
+```
+ define: {
+    "process.env.IS_PREACT": process.env.IS_PREACT,
+  },
+```
+::: 
+
 ## Browser
 
 To use it in a browser directly:

dev-docs/docusaurus.config.js

@@ -1,6 +1,11 @@
 // @ts-check
 // Note: type annotations allow type checking and IDEs autocompletion
 
+// Set the env variable to false so the excalidraw npm package doesn't throw
+// process undefined as docusaurus doesn't expose env variables by default
+
+process.env.IS_PREACT = "false";
+
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   title: "Excalidraw developer docs",
@@ -139,7 +144,15 @@ const config = {
       },
     }),
   themes: ["@docusaurus/theme-live-codeblock"],
-  plugins: ["docusaurus-plugin-sass"],
+  plugins: [
+    "docusaurus-plugin-sass",
+    [
+      "docusaurus2-dotenv",
+      {
+        systemvars: true,
+      },
+    ],
+  ],
 };
 
 module.exports = config;

dev-docs/package.json

@@ -18,7 +18,7 @@
     "@docusaurus/core": "2.2.0",
     "@docusaurus/preset-classic": "2.2.0",
     "@docusaurus/theme-live-codeblock": "2.2.0",
-    "@excalidraw/excalidraw": "0.15.2-eb020d0",
+    "@excalidraw/excalidraw": "0.17.0",
     "@mdx-js/react": "^1.6.22",
     "clsx": "^1.2.1",
     "docusaurus-plugin-sass": "0.2.3",
@@ -30,6 +30,7 @@
   "devDependencies": {
     "@docusaurus/module-type-aliases": "2.0.0-rc.1",
     "@tsconfig/docusaurus": "^1.0.5",
+    "docusaurus2-dotenv": "1.4.0",
     "typescript": "^4.7.4"
   },
   "browserslist": {

dev-docs/sidebars.js

@@ -53,7 +53,7 @@ const sidebars = {
               },
               items: [
                 "@excalidraw/excalidraw/api/props/initialdata",
-                "@excalidraw/excalidraw/api/props/ref",
+                "@excalidraw/excalidraw/api/props/excalidraw-api",
                 "@excalidraw/excalidraw/api/props/render-props",
                 "@excalidraw/excalidraw/api/props/ui-options",
               ],

dev-docs/yarn.lock

@@ -1718,10 +1718,10 @@
     url-loader "^4.1.1"
     webpack "^5.73.0"
 
-"@excalidraw/excalidraw@0.15.2-eb020d0":
-  version "0.15.2-eb020d0"
-  resolved "https://registry.yarnpkg.com/@excalidraw/excalidraw/-/excalidraw-0.15.2-eb020d0.tgz#25bd61e6f23da7c084fb16a3e0fe0dd9ad8e6533"
-  integrity sha512-TKGLzpOVqFQcwK1GFKTDXgg1s2U6tc5KE3qXuv87osbzOtftQn3x4+VH61vwdj11l00nEN80SMdXUC43T9uJqQ==
+"@excalidraw/excalidraw@0.17.0":
+  version "0.17.0"
+  resolved "https://registry.yarnpkg.com/@excalidraw/excalidraw/-/excalidraw-0.17.0.tgz#3c64aa8e36406ac171b008cfecbdce5bb0755725"
+  integrity sha512-NzP22v5xMqxYW27ZtTHhiGFe7kE8NeBk45aoeM/mDSkXiOXPDH+PcvwzHRN/Ei+Vj/0sTPHxejn8bZyRWKGjXg==
 
 "@hapi/hoek@^9.0.0":
   version "9.3.0"
@@ -3567,6 +3567,13 @@ docusaurus-plugin-sass@0.2.3:
   dependencies:
     sass-loader "^10.1.1"
 
+docusaurus2-dotenv@1.4.0:
+  version "1.4.0"
+  resolved "https://registry.yarnpkg.com/docusaurus2-dotenv/-/docusaurus2-dotenv-1.4.0.tgz#9ab900e29de9081f9f1f28f7224ff63760385641"
+  integrity sha512-iWqem5fnBAyeBBtX75Fxp71uUAnwFaXzOmade8zAhN4vL3RG9m27sLSRwjJGVVgIkEo3esjGyCcTGTiCjfi+sg==
+  dependencies:
+    dotenv-webpack "1.7.0"
+
 dom-converter@^0.2.0:
   version "0.2.0"
   resolved "https://registry.yarnpkg.com/dom-converter/-/dom-converter-0.2.0.tgz#6721a9daee2e293682955b6afe416771627bb768"
@@ -3652,6 +3659,25 @@ dot-prop@^5.2.0:
   dependencies:
     is-obj "^2.0.0"
 
+dotenv-defaults@^1.0.2:
+  version "1.1.1"
+  resolved "https://registry.yarnpkg.com/dotenv-defaults/-/dotenv-defaults-1.1.1.tgz#032c024f4b5906d9990eb06d722dc74cc60ec1bd"
+  integrity sha512-6fPRo9o/3MxKvmRZBD3oNFdxODdhJtIy1zcJeUSCs6HCy4tarUpd+G67UTU9tF6OWXeSPqsm4fPAB+2eY9Rt9Q==
+  dependencies:
+    dotenv "^6.2.0"
+
+dotenv-webpack@1.7.0:
+  version "1.7.0"
+  resolved "https://registry.yarnpkg.com/dotenv-webpack/-/dotenv-webpack-1.7.0.tgz#4384d8c57ee6f405c296278c14a9f9167856d3a1"
+  integrity sha512-wwNtOBW/6gLQSkb8p43y0Wts970A3xtNiG/mpwj9MLUhtPCQG6i+/DSXXoNN7fbPCU/vQ7JjwGmgOeGZSSZnsw==
+  dependencies:
+    dotenv-defaults "^1.0.2"
+
+dotenv@^6.2.0:
+  version "6.2.0"
+  resolved "https://registry.yarnpkg.com/dotenv/-/dotenv-6.2.0.tgz#941c0410535d942c8becf28d3f357dbd9d476064"
+  integrity sha512-HygQCKUBSFl8wKQZBSemMywRWcEDNidvNbjGVyZu3nbZ8qq9ubiPoGLMdRDpfSrpkkm9BXYFkpKxxFX38o/76w==
+
 duplexer3@^0.1.4:
   version "0.1.5"
   resolved "https://registry.yarnpkg.com/duplexer3/-/duplexer3-0.1.5.tgz#0b5e4d7bad5de8901ea4440624c8e1d20099217e"

excalidraw-app/collab/Collab.tsx

@@ -302,7 +302,6 @@ class Collab extends PureComponent<Props, CollabState> {
 
       this.excalidrawAPI.updateScene({
         elements,
-        commitToHistory: false,
       });
     }
   };
@@ -449,14 +448,12 @@ class Collab extends PureComponent<Props, CollabState> {
         }
         return element;
       });
-      // remove deleted elements from elements array & history to ensure we don't
+      // remove deleted elements from elements array 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
       // to database even if deleted before creating the room.
-      this.excalidrawAPI.history.clear();
       this.excalidrawAPI.updateScene({
         elements,
-        commitToHistory: true,
       });
 
       this.saveCollabRoomToFirebase(getSyncableElements(elements));
@@ -491,9 +488,7 @@ class Collab extends PureComponent<Props, CollabState> {
               this.initializeRoom({ fetchScene: false });
               const remoteElements = decryptedData.payload.elements;
               const reconciledElements = this.reconcileElements(remoteElements);
-              this.handleRemoteSceneUpdate(reconciledElements, {
-                init: true,
-              });
+              this.handleRemoteSceneUpdate(reconciledElements);
               // noop if already resolved via init from firebase
               scenePromise.resolve({
                 elements: reconciledElements,
@@ -649,21 +644,11 @@ class Collab extends PureComponent<Props, CollabState> {
     });
   }, LOAD_IMAGES_TIMEOUT);
 
-  private handleRemoteSceneUpdate = (
-    elements: ReconciledElements,
-    { init = false }: { init?: boolean } = {},
-  ) => {
+  private handleRemoteSceneUpdate = (elements: ReconciledElements) => {
     this.excalidrawAPI.updateScene({
       elements,
-      commitToHistory: !!init,
     });
 
-    // We haven't yet implemented multiplayer undo functionality, so we clear the undo stack
-    // when we receive any messages from another peer. This UX can be pretty rough -- if you
-    // 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();
   };
 

excalidraw-app/collab/Portal.tsx

@@ -18,7 +18,6 @@ import throttle from "lodash.throttle";
 import { newElementWith } from "../../src/element/mutateElement";
 import { BroadcastedExcalidrawElement } from "./reconciliation";
 import { encryptData } from "../../src/data/encryption";
-import { PRECEDING_ELEMENT_KEY } from "../../src/constants";
 
 class Portal {
   collab: TCollabClass;
@@ -150,11 +149,7 @@ class Portal {
               this.broadcastedElementVersions.get(element.id)!) &&
           isSyncableElement(element)
         ) {
-          acc.push({
-            ...element,
-            // z-index info for the reconciler
-            [PRECEDING_ELEMENT_KEY]: idx === 0 ? "^" : elements[idx - 1]?.id,
-          });
+          acc.push(element);
         }
         return acc;
       },

excalidraw-app/collab/reconciliation.ts

@@ -1,15 +1,13 @@
-import { PRECEDING_ELEMENT_KEY } from "../../src/constants";
 import { ExcalidrawElement } from "../../src/element/types";
 import { AppState } from "../../src/types";
-import { arrayToMapWithIndex } from "../../src/utils";
+import { arrayToMap } from "../../src/utils";
+import { orderByFractionalIndex } from "../../src/fractionalIndex";
 
 export type ReconciledElements = readonly ExcalidrawElement[] & {
   _brand: "reconciledElements";
 };
 
-export type BroadcastedExcalidrawElement = ExcalidrawElement & {
-  [PRECEDING_ELEMENT_KEY]?: string;
-};
+export type BroadcastedExcalidrawElement = ExcalidrawElement;
 
 const shouldDiscardRemoteElement = (
   localAppState: AppState,
@@ -21,7 +19,7 @@ const shouldDiscardRemoteElement = (
     // local element is being edited
     (local.id === localAppState.editingElement?.id ||
       local.id === localAppState.resizingElement?.id ||
-      local.id === localAppState.draggingElement?.id ||
+      local.id === localAppState.draggingElement?.id || // Is this still valid? As draggingElement is selection element, which is never part of the elements array
       // local element is newer
       local.version > remote.version ||
       // resolve conflicting edits deterministically by taking the one with
@@ -39,116 +37,43 @@ export const reconcileElements = (
   remoteElements: readonly BroadcastedExcalidrawElement[],
   localAppState: AppState,
 ): ReconciledElements => {
-  const localElementsData =
-    arrayToMapWithIndex<ExcalidrawElement>(localElements);
+  const localElementsData = arrayToMap(localElements);
+  const reconciledElements: ExcalidrawElement[] = [];
+  const added = new Set<string>();
 
-  const reconciledElements: ExcalidrawElement[] = localElements.slice();
-
-  const duplicates = new WeakMap<ExcalidrawElement, true>();
-
-  let cursor = 0;
-  let offset = 0;
-
-  let remoteElementIdx = -1;
+  // process remote elements
   for (const remoteElement of remoteElements) {
-    remoteElementIdx++;
+    if (localElementsData.has(remoteElement.id)) {
+      const localElement = localElementsData.get(remoteElement.id);
 
-    const local = localElementsData.get(remoteElement.id);
-
-    if (shouldDiscardRemoteElement(localAppState, local?.[0], remoteElement)) {
-      if (remoteElement[PRECEDING_ELEMENT_KEY]) {
-        delete remoteElement[PRECEDING_ELEMENT_KEY];
-      }
-
-      continue;
-    }
-
-    // Mark duplicate for removal as it'll be replaced with the remote element
-    if (local) {
-      // Unless the remote and local elements are the same element in which case
-      // we need to keep it as we'd otherwise discard it from the resulting
-      // array.
-      if (local[0] === remoteElement) {
+      if (
+        localElement &&
+        shouldDiscardRemoteElement(localAppState, localElement, remoteElement)
+      ) {
         continue;
-      }
-      duplicates.set(local[0], true);
-    }
-
-    // parent may not be defined in case the remote client is running an older
-    // excalidraw version
-    const parent =
-      remoteElement[PRECEDING_ELEMENT_KEY] ||
-      remoteElements[remoteElementIdx - 1]?.id ||
-      null;
-
-    if (parent != null) {
-      delete remoteElement[PRECEDING_ELEMENT_KEY];
-
-      // ^ indicates the element is the first in elements array
-      if (parent === "^") {
-        offset++;
-        if (cursor === 0) {
-          reconciledElements.unshift(remoteElement);
-          localElementsData.set(remoteElement.id, [
-            remoteElement,
-            cursor - offset,
-          ]);
-        } else {
-          reconciledElements.splice(cursor + 1, 0, remoteElement);
-          localElementsData.set(remoteElement.id, [
-            remoteElement,
-            cursor + 1 - offset,
-          ]);
-          cursor++;
-        }
       } else {
-        let idx = localElementsData.has(parent)
-          ? localElementsData.get(parent)![1]
-          : null;
-        if (idx != null) {
-          idx += offset;
-        }
-        if (idx != null && idx >= cursor) {
-          reconciledElements.splice(idx + 1, 0, remoteElement);
-          offset++;
-          localElementsData.set(remoteElement.id, [
-            remoteElement,
-            idx + 1 - offset,
-          ]);
-          cursor = idx + 1;
-        } else if (idx != null) {
-          reconciledElements.splice(cursor + 1, 0, remoteElement);
-          offset++;
-          localElementsData.set(remoteElement.id, [
-            remoteElement,
-            cursor + 1 - offset,
-          ]);
-          cursor++;
-        } else {
+        if (!added.has(remoteElement.id)) {
           reconciledElements.push(remoteElement);
-          localElementsData.set(remoteElement.id, [
-            remoteElement,
-            reconciledElements.length - 1 - offset,
-          ]);
+          added.add(remoteElement.id);
         }
       }
-      // no parent z-index information, local element exists → replace in place
-    } else if (local) {
-      reconciledElements[local[1]] = remoteElement;
-      localElementsData.set(remoteElement.id, [remoteElement, local[1]]);
-      // otherwise push to the end
     } else {
-      reconciledElements.push(remoteElement);
-      localElementsData.set(remoteElement.id, [
-        remoteElement,
-        reconciledElements.length - 1 - offset,
-      ]);
+      if (!added.has(remoteElement.id)) {
+        reconciledElements.push(remoteElement);
+        added.add(remoteElement.id);
+      }
     }
   }
 
-  const ret: readonly ExcalidrawElement[] = reconciledElements.filter(
-    (element) => !duplicates.has(element),
-  );
+  // process local elements
+  for (const localElement of localElements) {
+    if (!added.has(localElement.id)) {
+      reconciledElements.push(localElement);
+      added.add(localElement.id);
+    }
+  }
 
-  return ret as ReconciledElements;
+  return orderByFractionalIndex(
+    reconciledElements,
+  ) as readonly ExcalidrawElement[] as ReconciledElements;
 };

excalidraw-app/data/index.ts

@@ -278,7 +278,7 @@ export const loadScene = async (
     // in the scene database/localStorage, and instead fetch them async
     // from a different database
     files: data.files,
-    commitToHistory: false,
+    commitToStore: false,
   };
 };
 

excalidraw-app/index.tsx

@@ -409,7 +409,7 @@ const ExcalidrawWrapper = () => {
             excalidrawAPI.updateScene({
               ...data.scene,
               ...restore(data.scene, null, null, { repairBindings: true }),
-              commitToHistory: true,
+              commitToStore: true,
             });
           }
         });
@@ -590,6 +590,7 @@ const ExcalidrawWrapper = () => {
           if (didChange) {
             excalidrawAPI.updateScene({
               elements,
+              skipSnapshotUpdate: true,
             });
           }
         }

excalidraw-app/tests/collab.test.tsx

@@ -64,7 +64,7 @@ vi.mock("socket.io-client", () => {
 });
 
 describe("collaboration", () => {
-  it("creating room should reset deleted elements", async () => {
+  it("creating room should reset deleted elements while keeping store snapshot in sync", async () => {
     await render(<ExcalidrawApp />);
     // To update the scene with deleted elements before starting collab
     updateSceneData({
@@ -76,26 +76,43 @@ describe("collaboration", () => {
           isDeleted: true,
         }),
       ],
+      commitToStore: true,
     });
     await waitFor(() => {
+      expect(API.getUndoStack().length).toBe(1);
       expect(h.elements).toEqual([
         expect.objectContaining({ id: "A" }),
         expect.objectContaining({ id: "B", isDeleted: true }),
       ]);
-      expect(API.getStateHistory().length).toBe(1);
+      expect(Array.from(h.store.snapshot.elements.values())).toEqual([
+        expect.objectContaining({ id: "A" }),
+        expect.objectContaining({ id: "B", isDeleted: true }),
+      ]);
     });
     window.collab.startCollaboration(null);
     await waitFor(() => {
+      expect(API.getUndoStack().length).toBe(1);
       expect(h.elements).toEqual([expect.objectContaining({ id: "A" })]);
-      expect(API.getStateHistory().length).toBe(1);
+      // We never delete from the local store as it is used for correct diff calculation
+      expect(Array.from(h.store.snapshot.elements.values())).toEqual([
+        expect.objectContaining({ id: "A" }),
+        expect.objectContaining({ id: "B", isDeleted: true }),
+      ]);
     });
 
     const undoAction = createUndoAction(h.history);
     // noop
     h.app.actionManager.executeAction(undoAction);
+
+    // As it was introduced #2270, undo is a noop here, but we might want to re-enable it,
+    // since inability to undo your own deletions could be a bigger upsetting factor here
     await waitFor(() => {
+      expect(h.history.isUndoStackEmpty).toBeTruthy();
       expect(h.elements).toEqual([expect.objectContaining({ id: "A" })]);
-      expect(API.getStateHistory().length).toBe(1);
+      expect(Array.from(h.store.snapshot.elements.values())).toEqual([
+        expect.objectContaining({ id: "A" }),
+        expect.objectContaining({ id: "B", isDeleted: true }),
+      ]);
     });
   });
 });

excalidraw-app/tests/reconciliation.test.ts

@@ -1,5 +1,4 @@
 import { expect } from "chai";
-import { PRECEDING_ELEMENT_KEY } from "../../src/constants";
 import { ExcalidrawElement } from "../../src/element/types";
 import {
   BroadcastedExcalidrawElement,
@@ -15,7 +14,6 @@ type ElementLike = {
   id: string;
   version: number;
   versionNonce: number;
-  [PRECEDING_ELEMENT_KEY]?: string | null;
 };
 
 type Cache = Record<string, ExcalidrawElement | undefined>;
@@ -44,7 +42,6 @@ const createElement = (opts: { uid: string } | ElementLike) => {
     id,
     version,
     versionNonce: versionNonce || randomInteger(),
-    [PRECEDING_ELEMENT_KEY]: parent || null,
   };
 };
 
@@ -53,20 +50,15 @@ const idsToElements = (
   cache: Cache = {},
 ): readonly ExcalidrawElement[] => {
   return ids.reduce((acc, _uid, idx) => {
-    const {
-      uid,
-      id,
-      version,
-      [PRECEDING_ELEMENT_KEY]: parent,
-      versionNonce,
-    } = createElement(typeof _uid === "string" ? { uid: _uid } : _uid);
+    const { uid, id, version, versionNonce } = createElement(
+      typeof _uid === "string" ? { uid: _uid } : _uid,
+    );
     const cached = cache[uid];
     const elem = {
       id,
       version: version ?? 0,
       versionNonce,
       ...cached,
-      [PRECEDING_ELEMENT_KEY]: parent,
     } as BroadcastedExcalidrawElement;
     // @ts-ignore
     cache[uid] = elem;
@@ -77,7 +69,6 @@ const idsToElements = (
 
 const addParents = (elements: BroadcastedExcalidrawElement[]) => {
   return elements.map((el, idx, els) => {
-    el[PRECEDING_ELEMENT_KEY] = els[idx - 1]?.id || "^";
     return el;
   });
 };
@@ -389,13 +380,11 @@ describe("elements reconciliation", () => {
         id: "A",
         version: 1,
         versionNonce: 1,
-        [PRECEDING_ELEMENT_KEY]: null,
       },
       {
         id: "B",
         version: 1,
         versionNonce: 1,
-        [PRECEDING_ELEMENT_KEY]: null,
       },
     ];
 
@@ -408,13 +397,11 @@ describe("elements reconciliation", () => {
       id: "A",
       version: 1,
       versionNonce: 1,
-      [PRECEDING_ELEMENT_KEY]: null,
     };
     const el2 = {
       id: "B",
       version: 1,
       versionNonce: 1,
-      [PRECEDING_ELEMENT_KEY]: null,
     };
     testIdentical([el1, el2], [el2, el1], ["A", "B"]);
   });

package.json

@@ -37,6 +37,7 @@
     "eslint-plugin-react": "7.32.2",
     "fake-indexeddb": "3.1.7",
     "firebase": "8.3.3",
+    "fractional-indexing-jittered": "0.9.0",
     "i18next-browser-languagedetector": "6.1.4",
     "idb-keyval": "6.0.3",
     "image-blob-reduce": "3.0.1",
@@ -96,7 +97,7 @@
     "vitest-canvas-mock": "0.3.2"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": "18.0.0 - 20.x.x"
   },
   "homepage": ".",
   "name": "excalidraw",
@@ -128,8 +129,8 @@
     "test:coverage:watch": "vitest --coverage --watch",
     "test:ui": "yarn test --ui --coverage.enabled=true",
     "autorelease": "node scripts/autorelease.js",
-    "prerelease": "node scripts/prerelease.js",
+    "prerelease:excalidraw": "node scripts/prerelease.js",
     "build:preview": "yarn build && vite preview --port 5000",
-    "release": "node scripts/release.js"
+    "release:excalidraw": "node scripts/release.js"
   }
 }

src/actions/actionAddToLibrary.ts

@@ -3,6 +3,7 @@ import { deepCopyElement } from "../element/newElement";
 import { randomId } from "../random";
 import { t } from "../i18n";
 import { LIBRARY_DISABLED_TYPES } from "../constants";
+import { StoreAction } from "./types";
 
 export const actionAddToLibrary = register({
   name: "addToLibrary",
@@ -17,7 +18,7 @@ export const actionAddToLibrary = register({
     for (const type of LIBRARY_DISABLED_TYPES) {
       if (selectedElements.some((element) => element.type === type)) {
         return {
-          commitToHistory: false,
+          storeAction: StoreAction.NONE,
           appState: {
             ...appState,
             errorMessage: t(`errors.libraryElementTypeError.${type}`),
@@ -41,7 +42,7 @@ export const actionAddToLibrary = register({
       })
       .then(() => {
         return {
-          commitToHistory: false,
+          storeAction: StoreAction.NONE,
           appState: {
             ...appState,
             toast: { message: t("toast.addedToLibrary") },
@@ -50,7 +51,7 @@ export const actionAddToLibrary = register({
       })
       .catch((error) => {
         return {
-          commitToHistory: false,
+          storeAction: StoreAction.NONE,
           appState: {
             ...appState,
             errorMessage: error.message,

src/actions/actionAlign.tsx

@@ -9,6 +9,7 @@ import {
 } from "../components/icons";
 import { ToolButton } from "../components/ToolButton";
 import { getNonDeletedElements } from "../element";
+import { isFrameLikeElement } from "../element/typeChecks";
 import { ExcalidrawElement } from "../element/types";
 import { updateFrameMembershipOfSelectedElements } from "../frame";
 import { t } from "../i18n";
@@ -17,6 +18,7 @@ import { isSomeElementSelected } from "../scene";
 import { AppClassProperties, AppState } from "../types";
 import { arrayToMap, getShortcutKey } from "../utils";
 import { register } from "./register";
+import { StoreAction } from "./types";
 
 const alignActionsPredicate = (
   elements: readonly ExcalidrawElement[],
@@ -28,7 +30,7 @@ const alignActionsPredicate = (
   return (
     selectedElements.length > 1 &&
     // TODO enable aligning frames when implemented properly
-    !selectedElements.some((el) => el.type === "frame")
+    !selectedElements.some((el) => isFrameLikeElement(el))
   );
 };
 
@@ -62,7 +64,7 @@ export const actionAlignTop = register({
         position: "start",
         axis: "y",
       }),
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   keyTest: (event) =>
@@ -93,7 +95,7 @@ export const actionAlignBottom = register({
         position: "end",
         axis: "y",
       }),
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   keyTest: (event) =>
@@ -124,7 +126,7 @@ export const actionAlignLeft = register({
         position: "start",
         axis: "x",
       }),
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   keyTest: (event) =>
@@ -155,7 +157,7 @@ export const actionAlignRight = register({
         position: "end",
         axis: "x",
       }),
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   keyTest: (event) =>
@@ -186,7 +188,7 @@ export const actionAlignVerticallyCentered = register({
         position: "center",
         axis: "y",
       }),
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   PanelComponent: ({ elements, appState, updateData, app }) => (
@@ -213,7 +215,7 @@ export const actionAlignHorizontallyCentered = register({
         position: "center",
         axis: "x",
       }),
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   PanelComponent: ({ elements, appState, updateData, app }) => (

src/actions/actionBoundText.tsx

@@ -33,6 +33,7 @@ import { AppState } from "../types";
 import { Mutable } from "../utility-types";
 import { getFontString } from "../utils";
 import { register } from "./register";
+import { StoreAction } from "./types";
 
 export const actionUnbindText = register({
   name: "unbindText",
@@ -80,7 +81,7 @@ export const actionUnbindText = register({
     return {
       elements,
       appState,
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
 });
@@ -149,7 +150,7 @@ export const actionBindText = register({
     return {
       elements: pushTextAboveContainer(elements, container, textElement),
       appState: { ...appState, selectedElementIds: { [container.id]: true } },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
 });
@@ -299,7 +300,7 @@ export const actionWrapTextInContainer = register({
         ...appState,
         selectedElementIds: containerIds,
       },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
 });

src/actions/actionCanvas.tsx

@@ -1,7 +1,13 @@
 import { ColorPicker } from "../components/ColorPicker/ColorPicker";
 import { ZoomInIcon, ZoomOutIcon } from "../components/icons";
 import { ToolButton } from "../components/ToolButton";
-import { CURSOR_TYPE, MIN_ZOOM, THEME, ZOOM_STEP } from "../constants";
+import {
+  CURSOR_TYPE,
+  MAX_ZOOM,
+  MIN_ZOOM,
+  THEME,
+  ZOOM_STEP,
+} from "../constants";
 import { getCommonBounds, getNonDeletedElements } from "../element";
 import { ExcalidrawElement } from "../element/types";
 import { t } from "../i18n";
@@ -22,6 +28,7 @@ import {
 import { DEFAULT_CANVAS_BACKGROUND_PICKS } from "../colors";
 import { Bounds } from "../element/bounds";
 import { setCursor } from "../cursor";
+import { StoreAction } from "./types";
 
 export const actionChangeViewBackgroundColor = register({
   name: "changeViewBackgroundColor",
@@ -35,7 +42,9 @@ export const actionChangeViewBackgroundColor = register({
   perform: (_, appState, value) => {
     return {
       appState: { ...appState, ...value },
-      commitToHistory: !!value.viewBackgroundColor,
+      storeAction: !!value.viewBackgroundColor
+        ? StoreAction.CAPTURE
+        : StoreAction.NONE,
     };
   },
   PanelComponent: ({ elements, appState, updateData, appProps }) => {
@@ -88,7 +97,7 @@ export const actionClearCanvas = register({
             ? { ...appState.activeTool, type: "selection" }
             : appState.activeTool,
       },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
 });
@@ -110,16 +119,17 @@ export const actionZoomIn = register({
           appState,
         ),
       },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
-  PanelComponent: ({ updateData }) => (
+  PanelComponent: ({ updateData, appState }) => (
     <ToolButton
       type="button"
       className="zoom-in-button zoom-button"
       icon={ZoomInIcon}
       title={`${t("buttons.zoomIn")} — ${getShortcutKey("CtrlOrCmd++")}`}
       aria-label={t("buttons.zoomIn")}
+      disabled={appState.zoom.value >= MAX_ZOOM}
       onClick={() => {
         updateData(null);
       }}
@@ -147,16 +157,17 @@ export const actionZoomOut = register({
           appState,
         ),
       },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
-  PanelComponent: ({ updateData }) => (
+  PanelComponent: ({ updateData, appState }) => (
     <ToolButton
       type="button"
       className="zoom-out-button zoom-button"
       icon={ZoomOutIcon}
       title={`${t("buttons.zoomOut")} — ${getShortcutKey("CtrlOrCmd+-")}`}
       aria-label={t("buttons.zoomOut")}
+      disabled={appState.zoom.value <= MIN_ZOOM}
       onClick={() => {
         updateData(null);
       }}
@@ -184,7 +195,7 @@ export const actionResetZoom = register({
           appState,
         ),
       },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   PanelComponent: ({ updateData, appState }) => (
@@ -261,11 +272,25 @@ export const zoomToFit = ({
 
     // Apply clamping to newZoomValue to be between 10% and 3000%
     newZoomValue = Math.min(
-      Math.max(newZoomValue, 0.1),
-      30.0,
+      Math.max(newZoomValue, MIN_ZOOM),
+      MAX_ZOOM,
     ) as NormalizedZoomValue;
 
-    scrollX = (appState.width / 2) * (1 / newZoomValue) - centerX;
+    let appStateWidth = appState.width;
+
+    if (appState.openSidebar) {
+      const sidebarDOMElem = document.querySelector(
+        ".sidebar",
+      ) as HTMLElement | null;
+      const sidebarWidth = sidebarDOMElem?.offsetWidth ?? 0;
+      const isRTL = document.documentElement.getAttribute("dir") === "rtl";
+
+      appStateWidth = !isRTL
+        ? appState.width - sidebarWidth
+        : appState.width + sidebarWidth;
+    }
+
+    scrollX = (appStateWidth / 2) * (1 / newZoomValue) - centerX;
     scrollY = (appState.height / 2) * (1 / newZoomValue) - centerY;
   } else {
     newZoomValue = zoomValueToFitBoundsOnViewport(commonBounds, {
@@ -293,7 +318,7 @@ export const zoomToFit = ({
       scrollY,
       zoom: { value: newZoomValue },
     },
-    commitToHistory: false,
+    storeAction: StoreAction.NONE,
   };
 };
 
@@ -363,7 +388,7 @@ export const actionToggleTheme = register({
         theme:
           value || (appState.theme === THEME.LIGHT ? THEME.DARK : THEME.LIGHT),
       },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   keyTest: (event) => event.altKey && event.shiftKey && event.code === CODES.D,
@@ -400,7 +425,7 @@ export const actionToggleEraserTool = register({
         activeEmbeddable: null,
         activeTool,
       },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   keyTest: (event) => event.key === KEYS.E,
@@ -435,7 +460,7 @@ export const actionToggleHandTool = register({
         activeEmbeddable: null,
         activeTool,
       },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   keyTest: (event) =>

src/actions/actionClipboard.tsx

@@ -13,6 +13,7 @@ import { exportCanvas, prepareElementsForExport } from "../data/index";
 import { isTextElement } from "../element";
 import { t } from "../i18n";
 import { isFirefox } from "../constants";
+import { StoreAction } from "./types";
 
 export const actionCopy = register({
   name: "copy",
@@ -28,7 +29,7 @@ export const actionCopy = register({
       await copyToClipboard(elementsToCopy, app.files, event);
     } catch (error: any) {
       return {
-        commitToHistory: false,
+        storeAction: StoreAction.NONE,
         appState: {
           ...appState,
           errorMessage: error.message,
@@ -37,7 +38,7 @@ export const actionCopy = register({
     }
 
     return {
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   contextItemLabel: "labels.copy",
@@ -63,7 +64,7 @@ export const actionPaste = register({
 
       if (isFirefox) {
         return {
-          commitToHistory: false,
+          storeAction: StoreAction.NONE,
           appState: {
             ...appState,
             errorMessage: t("hints.firefox_clipboard_write"),
@@ -72,7 +73,7 @@ export const actionPaste = register({
       }
 
       return {
-        commitToHistory: false,
+        storeAction: StoreAction.NONE,
         appState: {
           ...appState,
           errorMessage: t("errors.asyncPasteFailedOnRead"),
@@ -85,7 +86,7 @@ export const actionPaste = register({
     } catch (error: any) {
       console.error(error);
       return {
-        commitToHistory: false,
+        storeAction: StoreAction.NONE,
         appState: {
           ...appState,
           errorMessage: t("errors.asyncPasteFailedOnParse"),
@@ -94,7 +95,7 @@ export const actionPaste = register({
     }
 
     return {
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   contextItemLabel: "labels.paste",
@@ -119,7 +120,7 @@ export const actionCopyAsSvg = register({
   perform: async (elements, appState, _data, app) => {
     if (!app.canvas) {
       return {
-        commitToHistory: false,
+        storeAction: StoreAction.NONE,
       };
     }
 
@@ -141,7 +142,7 @@ export const actionCopyAsSvg = register({
         },
       );
       return {
-        commitToHistory: false,
+        storeAction: StoreAction.NONE,
       };
     } catch (error: any) {
       console.error(error);
@@ -150,7 +151,7 @@ export const actionCopyAsSvg = register({
           ...appState,
           errorMessage: error.message,
         },
-        commitToHistory: false,
+        storeAction: StoreAction.NONE,
       };
     }
   },
@@ -166,7 +167,7 @@ export const actionCopyAsPng = register({
   perform: async (elements, appState, _data, app) => {
     if (!app.canvas) {
       return {
-        commitToHistory: false,
+        storeAction: StoreAction.NONE,
       };
     }
     const selectedElements = app.scene.getSelectedElements({
@@ -199,7 +200,7 @@ export const actionCopyAsPng = register({
             }),
           },
         },
-        commitToHistory: false,
+        storeAction: StoreAction.NONE,
       };
     } catch (error: any) {
       console.error(error);
@@ -208,7 +209,7 @@ export const actionCopyAsPng = register({
           ...appState,
           errorMessage: error.message,
         },
-        commitToHistory: false,
+        storeAction: StoreAction.NONE,
       };
     }
   },
@@ -238,7 +239,7 @@ export const copyText = register({
       .join("\n\n");
     copyTextToSystemClipboard(text);
     return {
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   predicate: (elements, appState, _, app) => {

src/actions/actionDeleteSelected.tsx

@@ -10,9 +10,10 @@ import { newElementWith } from "../element/mutateElement";
 import { getElementsInGroup } from "../groups";
 import { LinearElementEditor } from "../element/linearElementEditor";
 import { fixBindingsAfterDeletion } from "../element/binding";
-import { isBoundToContainer } from "../element/typeChecks";
+import { isBoundToContainer, isFrameLikeElement } from "../element/typeChecks";
 import { updateActiveTool } from "../utils";
 import { TrashIcon } from "../components/icons";
+import { StoreAction } from "./types";
 
 const deleteSelectedElements = (
   elements: readonly ExcalidrawElement[],
@@ -20,7 +21,7 @@ const deleteSelectedElements = (
 ) => {
   const framesToBeDeleted = new Set(
     getSelectedElements(
-      elements.filter((el) => el.type === "frame"),
+      elements.filter((el) => isFrameLikeElement(el)),
       appState,
     ).map((el) => el.id),
   );
@@ -109,7 +110,7 @@ export const actionDeleteSelected = register({
             ...nextAppState,
             editingLinearElement: null,
           },
-          commitToHistory: false,
+          storeAction: StoreAction.UPDATE,
         };
       }
 
@@ -141,7 +142,7 @@ export const actionDeleteSelected = register({
                 : [0],
           },
         },
-        commitToHistory: true,
+        storeAction: StoreAction.CAPTURE,
       };
     }
     let { elements: nextElements, appState: nextAppState } =
@@ -161,10 +162,12 @@ export const actionDeleteSelected = register({
         multiElement: null,
         activeEmbeddable: null,
       },
-      commitToHistory: isSomeElementSelected(
+      storeAction: isSomeElementSelected(
         getNonDeletedElements(elements),
         appState,
-      ),
+      )
+        ? StoreAction.CAPTURE
+        : StoreAction.NONE,
     };
   },
   contextItemLabel: "labels.delete",

src/actions/actionDistribute.tsx

@@ -5,6 +5,7 @@ import {
 import { ToolButton } from "../components/ToolButton";
 import { distributeElements, Distribution } from "../distribute";
 import { getNonDeletedElements } from "../element";
+import { isFrameLikeElement } from "../element/typeChecks";
 import { ExcalidrawElement } from "../element/types";
 import { updateFrameMembershipOfSelectedElements } from "../frame";
 import { t } from "../i18n";
@@ -13,13 +14,14 @@ import { isSomeElementSelected } from "../scene";
 import { AppClassProperties, AppState } from "../types";
 import { arrayToMap, getShortcutKey } from "../utils";
 import { register } from "./register";
+import { StoreAction } from "./types";
 
 const enableActionGroup = (appState: AppState, app: AppClassProperties) => {
   const selectedElements = app.scene.getSelectedElements(appState);
   return (
     selectedElements.length > 1 &&
     // TODO enable distributing frames when implemented properly
-    !selectedElements.some((el) => el.type === "frame")
+    !selectedElements.some((el) => isFrameLikeElement(el))
   );
 };
 
@@ -52,7 +54,7 @@ export const distributeHorizontally = register({
         space: "between",
         axis: "x",
       }),
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   keyTest: (event) =>
@@ -82,7 +84,7 @@ export const distributeVertically = register({
         space: "between",
         axis: "y",
       }),
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   keyTest: (event) =>

src/actions/actionDuplicateSelection.tsx

@@ -14,13 +14,13 @@ import {
 } from "../groups";
 import { AppState } from "../types";
 import { fixBindingsAfterDuplication } from "../element/binding";
-import { ActionResult } from "./types";
+import { ActionResult, StoreAction } from "./types";
 import { GRID_SIZE } from "../constants";
 import {
   bindTextToShapeAfterDuplication,
   getBoundTextElement,
 } from "../element/textElement";
-import { isBoundToContainer, isFrameElement } from "../element/typeChecks";
+import { isBoundToContainer, isFrameLikeElement } from "../element/typeChecks";
 import { normalizeElementOrder } from "../element/sortElements";
 import { DuplicateIcon } from "../components/icons";
 import {
@@ -31,6 +31,7 @@ import {
   excludeElementsInFramesFromSelection,
   getSelectedElements,
 } from "../scene/selection";
+import { fixFractionalIndices } from "../fractionalIndex";
 
 export const actionDuplicateSelection = register({
   name: "duplicateSelection",
@@ -47,13 +48,13 @@ export const actionDuplicateSelection = register({
       return {
         elements,
         appState: ret.appState,
-        commitToHistory: true,
+        storeAction: StoreAction.CAPTURE,
       };
     }
 
     return {
       ...duplicateElements(elements, appState),
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   contextItemLabel: "labels.duplicateSelection",
@@ -85,6 +86,7 @@ const duplicateElements = (
   const newElements: ExcalidrawElement[] = [];
   const oldElements: ExcalidrawElement[] = [];
   const oldIdToDuplicatedId = new Map();
+  const duplicatedElementsMap = new Map<string, ExcalidrawElement>();
 
   const duplicateAndOffsetElement = (element: ExcalidrawElement) => {
     const newElement = duplicateElement(
@@ -96,6 +98,7 @@ const duplicateElements = (
         y: element.y + GRID_SIZE / 2,
       },
     );
+    duplicatedElementsMap.set(newElement.id, newElement);
     oldIdToDuplicatedId.set(element.id, newElement.id);
     oldElements.push(element);
     newElements.push(newElement);
@@ -140,11 +143,11 @@ const duplicateElements = (
     }
 
     const boundTextElement = getBoundTextElement(element);
-    const isElementAFrame = isFrameElement(element);
+    const isElementAFrameLike = isFrameLikeElement(element);
 
     if (idsOfElementsToDuplicate.get(element.id)) {
       // if a group or a container/bound-text or frame, duplicate atomically
-      if (element.groupIds.length || boundTextElement || isElementAFrame) {
+      if (element.groupIds.length || boundTextElement || isElementAFrameLike) {
         const groupId = getSelectedGroupForElement(appState, element);
         if (groupId) {
           // TODO:
@@ -154,7 +157,7 @@ const duplicateElements = (
             sortedElements,
             groupId,
           ).flatMap((element) =>
-            isFrameElement(element)
+            isFrameLikeElement(element)
               ? [...getFrameChildren(elements, element.id), element]
               : [element],
           );
@@ -180,7 +183,7 @@ const duplicateElements = (
           );
           continue;
         }
-        if (isElementAFrame) {
+        if (isElementAFrameLike) {
           const elementsInFrame = getFrameChildren(sortedElements, element.id);
 
           elementsWithClones.push(
@@ -234,7 +237,10 @@ const duplicateElements = (
 
   // step (3)
 
-  const finalElements = finalElementsReversed.reverse();
+  const finalElements = fixFractionalIndices(
+    finalElementsReversed.reverse(),
+    duplicatedElementsMap,
+  );
 
   // ---------------------------------------------------------------------------
 

src/actions/actionElementLock.ts

@@ -1,8 +1,10 @@
 import { newElementWith } from "../element/mutateElement";
+import { isFrameLikeElement } from "../element/typeChecks";
 import { ExcalidrawElement } from "../element/types";
 import { KEYS } from "../keys";
 import { arrayToMap } from "../utils";
 import { register } from "./register";
+import { StoreAction } from "./types";
 
 const shouldLock = (elements: readonly ExcalidrawElement[]) =>
   elements.every((el) => !el.locked);
@@ -43,7 +45,7 @@ export const actionToggleElementLock = register({
           ? null
           : appState.selectedLinearElement,
       },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   contextItemLabel: (elements, appState, app) => {
@@ -51,7 +53,7 @@ export const actionToggleElementLock = register({
       selectedElementIds: appState.selectedElementIds,
       includeBoundTextElement: false,
     });
-    if (selected.length === 1 && selected[0].type !== "frame") {
+    if (selected.length === 1 && !isFrameLikeElement(selected[0])) {
       return selected[0].locked
         ? "labels.elementLock.unlock"
         : "labels.elementLock.lock";
@@ -97,7 +99,7 @@ export const actionUnlockAllElements = register({
           lockedElements.map((el) => [el.id, true]),
         ),
       },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   contextItemLabel: "labels.elementLock.unlockAll",

src/actions/actionExport.tsx

@@ -19,12 +19,16 @@ import { nativeFileSystemSupported } from "../data/filesystem";
 import { Theme } from "../element/types";
 
 import "../components/ToolIcon.scss";
+import { StoreAction } from "./types";
 
 export const actionChangeProjectName = register({
   name: "changeProjectName",
   trackEvent: false,
   perform: (_elements, appState, value) => {
-    return { appState: { ...appState, name: value }, commitToHistory: false };
+    return {
+      appState: { ...appState, name: value },
+      storeAction: StoreAction.UPDATE,
+    };
   },
   PanelComponent: ({ appState, updateData, appProps, data }) => (
     <ProjectName
@@ -45,7 +49,7 @@ export const actionChangeExportScale = register({
   perform: (_elements, appState, value) => {
     return {
       appState: { ...appState, exportScale: value },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   PanelComponent: ({ elements: allElements, appState, updateData }) => {
@@ -94,7 +98,7 @@ export const actionChangeExportBackground = register({
   perform: (_elements, appState, value) => {
     return {
       appState: { ...appState, exportBackground: value },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   PanelComponent: ({ appState, updateData }) => (
@@ -113,7 +117,7 @@ export const actionChangeExportEmbedScene = register({
   perform: (_elements, appState, value) => {
     return {
       appState: { ...appState, exportEmbedScene: value },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   PanelComponent: ({ appState, updateData }) => (
@@ -148,7 +152,7 @@ export const actionSaveToActiveFile = register({
         : await saveAsJSON(elements, appState, app.files);
 
       return {
-        commitToHistory: false,
+        storeAction: StoreAction.NONE,
         appState: {
           ...appState,
           fileHandle,
@@ -170,7 +174,7 @@ export const actionSaveToActiveFile = register({
       } else {
         console.warn(error);
       }
-      return { commitToHistory: false };
+      return { storeAction: StoreAction.NONE };
     }
   },
   keyTest: (event) =>
@@ -192,7 +196,7 @@ export const actionSaveFileToDisk = register({
         app.files,
       );
       return {
-        commitToHistory: false,
+        storeAction: StoreAction.NONE,
         appState: {
           ...appState,
           openDialog: null,
@@ -206,7 +210,7 @@ export const actionSaveFileToDisk = register({
       } else {
         console.warn(error);
       }
-      return { commitToHistory: false };
+      return { storeAction: StoreAction.NONE };
     }
   },
   keyTest: (event) =>
@@ -244,7 +248,7 @@ export const actionLoadScene = register({
         elements: loadedElements,
         appState: loadedAppState,
         files,
-        commitToHistory: true,
+        storeAction: StoreAction.CAPTURE,
       };
     } catch (error: any) {
       if (error?.name === "AbortError") {
@@ -255,7 +259,7 @@ export const actionLoadScene = register({
         elements,
         appState: { ...appState, errorMessage: error.message },
         files: app.files,
-        commitToHistory: false,
+        storeAction: StoreAction.NONE,
       };
     }
   },
@@ -268,7 +272,7 @@ export const actionExportWithDarkMode = register({
   perform: (_elements, appState, value) => {
     return {
       appState: { ...appState, exportWithDarkMode: value },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   PanelComponent: ({ appState, updateData }) => (

src/actions/actionFinalize.tsx

@@ -16,6 +16,7 @@ import {
 import { isBindingElement, isLinearElement } from "../element/typeChecks";
 import { AppState } from "../types";
 import { resetCursor } from "../cursor";
+import { StoreAction } from "./types";
 
 export const actionFinalize = register({
   name: "finalize",
@@ -49,7 +50,7 @@ export const actionFinalize = register({
             cursorButton: "up",
             editingLinearElement: null,
           },
-          commitToHistory: true,
+          storeAction: StoreAction.CAPTURE,
         };
       }
     }
@@ -190,7 +191,10 @@ export const actionFinalize = register({
             : appState.selectedLinearElement,
         pendingImageElementId: null,
       },
-      commitToHistory: appState.activeTool.type === "freedraw",
+      storeAction:
+        appState.activeTool.type === "freedraw"
+          ? StoreAction.CAPTURE
+          : StoreAction.UPDATE,
     };
   },
   keyTest: (event, appState) =>

src/actions/actionFlip.ts

@@ -13,6 +13,7 @@ import {
   unbindLinearElements,
 } from "../element/binding";
 import { updateFrameMembershipOfSelectedElements } from "../frame";
+import { StoreAction } from "./types";
 
 export const actionFlipHorizontal = register({
   name: "flipHorizontal",
@@ -25,7 +26,7 @@ export const actionFlipHorizontal = register({
         app,
       ),
       appState,
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   keyTest: (event) => event.shiftKey && event.code === CODES.H,
@@ -43,7 +44,7 @@ export const actionFlipVertical = register({
         app,
       ),
       appState,
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   keyTest: (event) =>

src/actions/actionFrame.ts

@@ -7,23 +7,28 @@ import { AppClassProperties, AppState } from "../types";
 import { updateActiveTool } from "../utils";
 import { setCursorForShape } from "../cursor";
 import { register } from "./register";
+import { isFrameLikeElement } from "../element/typeChecks";
+import { StoreAction } from "./types";
 
 const isSingleFrameSelected = (appState: AppState, app: AppClassProperties) => {
   const selectedElements = app.scene.getSelectedElements(appState);
 
-  return selectedElements.length === 1 && selectedElements[0].type === "frame";
+  return (
+    selectedElements.length === 1 && isFrameLikeElement(selectedElements[0])
+  );
 };
 
 export const actionSelectAllElementsInFrame = register({
   name: "selectAllElementsInFrame",
   trackEvent: { category: "canvas" },
   perform: (elements, appState, _, app) => {
-    const selectedFrame = app.scene.getSelectedElements(appState)[0];
+    const selectedElement =
+      app.scene.getSelectedElements(appState).at(0) || null;
 
-    if (selectedFrame && selectedFrame.type === "frame") {
+    if (isFrameLikeElement(selectedElement)) {
       const elementsInFrame = getFrameChildren(
         getNonDeletedElements(elements),
-        selectedFrame.id,
+        selectedElement.id,
       ).filter((element) => !(element.type === "text" && element.containerId));
 
       return {
@@ -35,14 +40,14 @@ export const actionSelectAllElementsInFrame = register({
             return acc;
           }, {} as Record<ExcalidrawElement["id"], true>),
         },
-        commitToHistory: false,
+        storeAction: StoreAction.CAPTURE,
       };
     }
 
     return {
       elements,
       appState,
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   contextItemLabel: "labels.selectAllElementsInFrame",
@@ -54,25 +59,30 @@ export const actionRemoveAllElementsFromFrame = register({
   name: "removeAllElementsFromFrame",
   trackEvent: { category: "history" },
   perform: (elements, appState, _, app) => {
-    const selectedFrame = app.scene.getSelectedElements(appState)[0];
+    const selectedElement =
+      app.scene.getSelectedElements(appState).at(0) || null;
 
-    if (selectedFrame && selectedFrame.type === "frame") {
+    if (isFrameLikeElement(selectedElement)) {
       return {
-        elements: removeAllElementsFromFrame(elements, selectedFrame, appState),
+        elements: removeAllElementsFromFrame(
+          elements,
+          selectedElement,
+          appState,
+        ),
         appState: {
           ...appState,
           selectedElementIds: {
-            [selectedFrame.id]: true,
+            [selectedElement.id]: true,
           },
         },
-        commitToHistory: true,
+        storeAction: StoreAction.CAPTURE,
       };
     }
 
     return {
       elements,
       appState,
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   contextItemLabel: "labels.removeAllElementsFromFrame",
@@ -94,7 +104,7 @@ export const actionupdateFrameRendering = register({
           enabled: !appState.frameRendering.enabled,
         },
       },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   contextItemLabel: "labels.updateFrameRendering",
@@ -122,7 +132,7 @@ export const actionSetFrameAsActiveTool = register({
           type: "frame",
         }),
       },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   keyTest: (event) =>

src/actions/actionGroup.tsx

@@ -22,11 +22,12 @@ import { AppClassProperties, AppState } from "../types";
 import { isBoundToContainer } from "../element/typeChecks";
 import {
   getElementsInResizingFrame,
-  getFrameElements,
-  groupByFrames,
+  getFrameLikeElements,
+  groupByFrameLikes,
   removeElementsFromFrame,
   replaceAllElementsInFrame,
 } from "../frame";
+import { StoreAction } from "./types";
 
 const allElementsInSameGroup = (elements: readonly ExcalidrawElement[]) => {
   if (elements.length >= 2) {
@@ -69,7 +70,7 @@ export const actionGroup = register({
     });
     if (selectedElements.length < 2) {
       // nothing to group
-      return { appState, elements, commitToHistory: false };
+      return { appState, elements, storeAction: StoreAction.NONE };
     }
     // if everything is already grouped into 1 group, there is nothing to do
     const selectedGroupIds = getSelectedGroupIds(appState);
@@ -89,7 +90,7 @@ export const actionGroup = register({
       ]);
       if (combinedSet.size === elementIdsInGroup.size) {
         // no incremental ids in the selected ids
-        return { appState, elements, commitToHistory: false };
+        return { appState, elements, storeAction: StoreAction.NONE };
       }
     }
 
@@ -102,7 +103,7 @@ export const actionGroup = register({
     // when it happens, we want to remove elements that are in the frame
     // and are going to be grouped from the frame (mouthful, I know)
     if (groupingElementsFromDifferentFrames) {
-      const frameElementsMap = groupByFrames(selectedElements);
+      const frameElementsMap = groupByFrameLikes(selectedElements);
 
       frameElementsMap.forEach((elementsInFrame, frameId) => {
         nextElements = removeElementsFromFrame(
@@ -155,7 +156,7 @@ export const actionGroup = register({
         ),
       },
       elements: nextElements,
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   contextItemLabel: "labels.group",
@@ -182,7 +183,7 @@ export const actionUngroup = register({
   perform: (elements, appState, _, app) => {
     const groupIds = getSelectedGroupIds(appState);
     if (groupIds.length === 0) {
-      return { appState, elements, commitToHistory: false };
+      return { appState, elements, storeAction: StoreAction.NONE, };
     }
 
     let nextElements = [...elements];
@@ -219,7 +220,7 @@ export const actionUngroup = register({
         .map((element) => element.frameId!),
     );
 
-    const targetFrames = getFrameElements(elements).filter((frame) =>
+    const targetFrames = getFrameLikeElements(elements).filter((frame) =>
       selectedElementFrameIds.has(frame.id),
     );
 
@@ -250,7 +251,7 @@ export const actionUngroup = register({
     return {
       appState: { ...appState, ...updateAppState },
       elements: nextElements,
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   keyTest: (event) =>

src/actions/actionHistory.tsx

@@ -1,62 +1,51 @@
-import { Action, ActionResult } from "./types";
+import { Action, ActionResult, StoreAction } from "./types";
 import { UndoIcon, RedoIcon } from "../components/icons";
 import { ToolButton } from "../components/ToolButton";
 import { t } from "../i18n";
-import History, { HistoryEntry } from "../history";
-import { ExcalidrawElement } from "../element/types";
+import { History } from "../history";
 import { AppState } from "../types";
 import { KEYS } from "../keys";
-import { newElementWith } from "../element/mutateElement";
-import { fixBindingsAfterDeletion } from "../element/binding";
 import { arrayToMap } from "../utils";
 import { isWindows } from "../constants";
+import { ExcalidrawElement } from "../element/types";
+import { fixBindingsAfterDeletion } from "../element/binding";
+import { orderByFractionalIndex } from "../fractionalIndex";
 
 const writeData = (
-  prevElements: readonly ExcalidrawElement[],
-  appState: AppState,
-  updater: () => HistoryEntry | null,
+  appState: Readonly<AppState>,
+  updater: () => [Map<string, ExcalidrawElement>, AppState] | void,
 ): ActionResult => {
-  const commitToHistory = false;
   if (
     !appState.multiElement &&
     !appState.resizingElement &&
     !appState.editingElement &&
     !appState.draggingElement
   ) {
-    const data = updater();
-    if (data === null) {
-      return { commitToHistory };
+    const result = updater();
+
+    if (!result) {
+      return { storeAction: StoreAction.NONE };
     }
 
-    const prevElementMap = arrayToMap(prevElements);
-    const nextElements = data.elements;
-    const nextElementMap = arrayToMap(nextElements);
-
-    const deletedElements = prevElements.filter(
-      (prevElement) => !nextElementMap.has(prevElement.id),
+    // TODO_UNDO: worth detecting z-index deltas or do we just order based on fractional indices?
+    const [nextElementsMap, nextAppState] = result;
+    const nextElements = orderByFractionalIndex(
+      Array.from(nextElementsMap.values()),
     );
-    const elements = nextElements
-      .map((nextElement) =>
-        newElementWith(
-          prevElementMap.get(nextElement.id) || nextElement,
-          nextElement,
-        ),
-      )
-      .concat(
-        deletedElements.map((prevElement) =>
-          newElementWith(prevElement, { isDeleted: true }),
-        ),
-      );
-    fixBindingsAfterDeletion(elements, deletedElements);
+
+    // TODO_UNDO: these are all deleted elements, but ideally we should get just those that were delted at this moment
+    const deletedElements = nextElements.filter((element) => element.isDeleted);
+    // TODO_UNDO: this doesn't really work for bound text
+    fixBindingsAfterDeletion(nextElements, deletedElements);
 
     return {
-      elements,
-      appState: { ...appState, ...data.appState },
-      commitToHistory,
-      syncHistory: true,
+      appState: nextAppState,
+      elements: nextElements,
+      storeAction: StoreAction.UPDATE,
     };
   }
-  return { commitToHistory };
+
+  return { storeAction: StoreAction.NONE };
 };
 
 type ActionCreator = (history: History) => Action;
@@ -65,7 +54,7 @@ export const createUndoAction: ActionCreator = (history) => ({
   name: "undo",
   trackEvent: { category: "history" },
   perform: (elements, appState) =>
-    writeData(elements, appState, () => history.undoOnce()),
+    writeData(appState, () => history.undo(arrayToMap(elements), appState)),
   keyTest: (event) =>
     event[KEYS.CTRL_OR_CMD] &&
     event.key.toLowerCase() === KEYS.Z &&
@@ -77,16 +66,16 @@ export const createUndoAction: ActionCreator = (history) => ({
       aria-label={t("buttons.undo")}
       onClick={updateData}
       size={data?.size || "medium"}
+      disabled={history.isUndoStackEmpty}
     />
   ),
-  commitToHistory: () => false,
 });
 
 export const createRedoAction: ActionCreator = (history) => ({
   name: "redo",
   trackEvent: { category: "history" },
   perform: (elements, appState) =>
-    writeData(elements, appState, () => history.redoOnce()),
+    writeData(appState, () => history.redo(arrayToMap(elements), appState)),
   keyTest: (event) =>
     (event[KEYS.CTRL_OR_CMD] &&
       event.shiftKey &&
@@ -99,7 +88,7 @@ export const createRedoAction: ActionCreator = (history) => ({
       aria-label={t("buttons.redo")}
       onClick={updateData}
       size={data?.size || "medium"}
+      disabled={history.isRedoStackEmpty}
     />
   ),
-  commitToHistory: () => false,
 });

src/actions/actionLinearEditor.ts

@@ -2,6 +2,7 @@ import { LinearElementEditor } from "../element/linearElementEditor";
 import { isLinearElement } from "../element/typeChecks";
 import { ExcalidrawLinearElement } from "../element/types";
 import { register } from "./register";
+import { StoreAction } from "./types";
 
 export const actionToggleLinearEditor = register({
   name: "toggleLinearEditor",
@@ -30,7 +31,7 @@ export const actionToggleLinearEditor = register({
         ...appState,
         editingLinearElement,
       },
-      commitToHistory: false,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   contextItemLabel: (elements, appState, app) => {

src/actions/actionMenu.tsx

@@ -4,6 +4,7 @@ import { t } from "../i18n";
 import { showSelectedShapeActions, getNonDeletedElements } from "../element";
 import { register } from "./register";
 import { KEYS } from "../keys";
+import { StoreAction } from "./types";
 
 export const actionToggleCanvasMenu = register({
   name: "toggleCanvasMenu",
@@ -13,7 +14,7 @@ export const actionToggleCanvasMenu = register({
       ...appState,
       openMenu: appState.openMenu === "canvas" ? null : "canvas",
     },
-    commitToHistory: false,
+    storeAction: StoreAction.NONE,
   }),
   PanelComponent: ({ appState, updateData }) => (
     <ToolButton
@@ -34,7 +35,7 @@ export const actionToggleEditMenu = register({
       ...appState,
       openMenu: appState.openMenu === "shape" ? null : "shape",
     },
-    commitToHistory: false,
+    storeAction: StoreAction.NONE,
   }),
   PanelComponent: ({ elements, appState, updateData }) => (
     <ToolButton
@@ -64,7 +65,7 @@ export const actionShortcuts = register({
         ...appState,
         openDialog: appState.openDialog === "help" ? null : "help",
       },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   keyTest: (event) => event.key === KEYS.QUESTION_MARK,

src/actions/actionNavigate.tsx

@@ -3,6 +3,7 @@ import { Avatar } from "../components/Avatar";
 import { centerScrollOn } from "../scene/scroll";
 import { Collaborator } from "../types";
 import { register } from "./register";
+import { StoreAction } from "./types";
 
 export const actionGoToCollaborator = register({
   name: "goToCollaborator",
@@ -11,7 +12,7 @@ export const actionGoToCollaborator = register({
   perform: (_elements, appState, value) => {
     const point = value as Collaborator["pointer"];
     if (!point) {
-      return { appState, commitToHistory: false };
+      return { appState, storeAction: StoreAction.NONE };
     }
 
     return {
@@ -28,7 +29,7 @@ export const actionGoToCollaborator = register({
         // Close mobile menu
         openMenu: appState.openMenu === "canvas" ? null : appState.openMenu,
       },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   PanelComponent: ({ updateData, data }) => {

src/actions/actionProperties.tsx

@@ -92,6 +92,7 @@ import {
 import { hasStrokeColor } from "../scene/comparisons";
 import { arrayToMap, getShortcutKey } from "../utils";
 import { register } from "./register";
+import { StoreAction } from "./types";
 
 const FONT_SIZE_RELATIVE_INCREASE_STEP = 0.1;
 
@@ -222,7 +223,7 @@ const changeFontSize = (
           ? [...newFontSizes][0]
           : fallbackValue ?? appState.currentItemFontSize,
     },
-    commitToHistory: true,
+    storeAction: StoreAction.CAPTURE,
   };
 };
 
@@ -251,7 +252,9 @@ export const actionChangeStrokeColor = register({
         ...appState,
         ...value,
       },
-      commitToHistory: !!value.currentItemStrokeColor,
+      storeAction: !!value.currentItemStrokeColor
+        ? StoreAction.CAPTURE
+        : StoreAction.NONE,
     };
   },
   PanelComponent: ({ elements, appState, updateData, appProps }) => (
@@ -294,7 +297,9 @@ export const actionChangeBackgroundColor = register({
         ...appState,
         ...value,
       },
-      commitToHistory: !!value.currentItemBackgroundColor,
+      storeAction: !!value.currentItemBackgroundColor
+        ? StoreAction.CAPTURE
+        : StoreAction.NONE,
     };
   },
   PanelComponent: ({ elements, appState, updateData, appProps }) => (
@@ -337,7 +342,7 @@ export const actionChangeFillStyle = register({
         }),
       ),
       appState: { ...appState, currentItemFillStyle: value },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   PanelComponent: ({ elements, appState, updateData }) => {
@@ -409,7 +414,7 @@ export const actionChangeStrokeWidth = register({
         }),
       ),
       appState: { ...appState, currentItemStrokeWidth: value },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   PanelComponent: ({ elements, appState, updateData }) => (
@@ -463,7 +468,7 @@ export const actionChangeSloppiness = register({
         }),
       ),
       appState: { ...appState, currentItemRoughness: value },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   PanelComponent: ({ elements, appState, updateData }) => (
@@ -513,7 +518,7 @@ export const actionChangeStrokeStyle = register({
         }),
       ),
       appState: { ...appState, currentItemStrokeStyle: value },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   PanelComponent: ({ elements, appState, updateData }) => (
@@ -567,7 +572,7 @@ export const actionChangeOpacity = register({
         true,
       ),
       appState: { ...appState, currentItemOpacity: value },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   PanelComponent: ({ elements, appState, updateData }) => (
@@ -725,7 +730,7 @@ export const actionChangeFontFamily = register({
         ...appState,
         currentItemFontFamily: value,
       },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   PanelComponent: ({ elements, appState, updateData }) => {
@@ -814,7 +819,7 @@ export const actionChangeTextAlign = register({
         ...appState,
         currentItemTextAlign: value,
       },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   PanelComponent: ({ elements, appState, updateData }) => {
@@ -894,7 +899,7 @@ export const actionChangeVerticalAlign = register({
       appState: {
         ...appState,
       },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   PanelComponent: ({ elements, appState, updateData }) => {
@@ -967,7 +972,7 @@ export const actionChangeRoundness = register({
         ...appState,
         currentItemRoundness: value,
       },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   PanelComponent: ({ elements, appState, updateData }) => {
@@ -1047,7 +1052,7 @@ export const actionChangeArrowhead = register({
           ? "currentItemStartArrowhead"
           : "currentItemEndArrowhead"]: value.type,
       },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   PanelComponent: ({ elements, appState, updateData }) => {

src/actions/actionSelectAll.ts

@@ -6,6 +6,7 @@ import { ExcalidrawElement } from "../element/types";
 import { isLinearElement } from "../element/typeChecks";
 import { LinearElementEditor } from "../element/linearElementEditor";
 import { excludeElementsInFramesFromSelection } from "../scene/selection";
+import { StoreAction } from "./types";
 
 export const actionSelectAll = register({
   name: "selectAll",
@@ -46,7 +47,7 @@ export const actionSelectAll = register({
             ? new LinearElementEditor(elements[0], app.scene)
             : null,
       },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   contextItemLabel: "labels.selectAll",

src/actions/actionStyles.ts

@@ -20,11 +20,12 @@ import {
   hasBoundTextElement,
   canApplyRoundnessTypeToElement,
   getDefaultRoundnessTypeForElement,
-  isFrameElement,
+  isFrameLikeElement,
   isArrowElement,
 } from "../element/typeChecks";
 import { getSelectedElements } from "../scene";
 import { ExcalidrawTextElement } from "../element/types";
+import { StoreAction } from "./types";
 
 // `copiedStyles` is exported only for tests.
 export let copiedStyles: string = "{}";
@@ -48,7 +49,7 @@ export const actionCopyStyles = register({
         ...appState,
         toast: { message: t("toast.copyStyles") },
       },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   contextItemLabel: "labels.copyStyles",
@@ -64,7 +65,7 @@ export const actionPasteStyles = register({
     const pastedElement = elementsCopied[0];
     const boundTextElement = elementsCopied[1];
     if (!isExcalidrawElement(pastedElement)) {
-      return { elements, commitToHistory: false };
+      return { elements, storeAction: StoreAction.NONE };
     }
 
     const selectedElements = getSelectedElements(elements, appState, {
@@ -138,7 +139,7 @@ export const actionPasteStyles = register({
             });
           }
 
-          if (isFrameElement(element)) {
+          if (isFrameLikeElement(element)) {
             newElement = newElementWith(newElement, {
               roundness: null,
               backgroundColor: "transparent",
@@ -149,7 +150,7 @@ export const actionPasteStyles = register({
         }
         return element;
       }),
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   contextItemLabel: "labels.pasteStyles",

src/actions/actionToggleGridMode.tsx

@@ -2,6 +2,7 @@ import { CODES, KEYS } from "../keys";
 import { register } from "./register";
 import { GRID_SIZE } from "../constants";
 import { AppState } from "../types";
+import { StoreAction } from "./types";
 
 export const actionToggleGridMode = register({
   name: "gridMode",
@@ -17,7 +18,7 @@ export const actionToggleGridMode = register({
         gridSize: this.checked!(appState) ? null : GRID_SIZE,
         objectsSnapModeEnabled: false,
       },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   checked: (appState: AppState) => appState.gridSize !== null,

src/actions/actionToggleObjectsSnapMode.tsx

@@ -1,5 +1,6 @@
 import { CODES, KEYS } from "../keys";
 import { register } from "./register";
+import { StoreAction } from "./types";
 
 export const actionToggleObjectsSnapMode = register({
   name: "objectsSnapMode",
@@ -15,7 +16,7 @@ export const actionToggleObjectsSnapMode = register({
         objectsSnapModeEnabled: !this.checked!(appState),
         gridSize: null,
       },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   checked: (appState) => appState.objectsSnapModeEnabled,

src/actions/actionToggleStats.tsx

@@ -1,5 +1,6 @@
 import { register } from "./register";
 import { CODES, KEYS } from "../keys";
+import { StoreAction } from "./types";
 
 export const actionToggleStats = register({
   name: "stats",
@@ -11,7 +12,7 @@ export const actionToggleStats = register({
         ...appState,
         showStats: !this.checked!(appState),
       },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   checked: (appState) => appState.showStats,

src/actions/actionToggleViewMode.tsx

@@ -1,5 +1,6 @@
 import { CODES, KEYS } from "../keys";
 import { register } from "./register";
+import { StoreAction } from "./types";
 
 export const actionToggleViewMode = register({
   name: "viewMode",
@@ -14,7 +15,7 @@ export const actionToggleViewMode = register({
         ...appState,
         viewModeEnabled: !this.checked!(appState),
       },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   checked: (appState) => appState.viewModeEnabled,

src/actions/actionToggleZenMode.tsx

@@ -1,5 +1,6 @@
 import { CODES, KEYS } from "../keys";
 import { register } from "./register";
+import { StoreAction } from "./types";
 
 export const actionToggleZenMode = register({
   name: "zenMode",
@@ -14,7 +15,7 @@ export const actionToggleZenMode = register({
         ...appState,
         zenModeEnabled: !this.checked!(appState),
       },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
     };
   },
   checked: (appState) => appState.zenModeEnabled,

src/actions/actionZindex.tsx

@@ -1,4 +1,3 @@
-import React from "react";
 import {
   moveOneLeft,
   moveOneRight,
@@ -16,6 +15,7 @@ import {
   SendToBackIcon,
 } from "../components/icons";
 import { isDarwin } from "../constants";
+import { StoreAction } from "./types";
 
 export const actionSendBackward = register({
   name: "sendBackward",
@@ -24,7 +24,7 @@ export const actionSendBackward = register({
     return {
       elements: moveOneLeft(elements, appState),
       appState,
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   contextItemLabel: "labels.sendBackward",
@@ -52,7 +52,7 @@ export const actionBringForward = register({
     return {
       elements: moveOneRight(elements, appState),
       appState,
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   contextItemLabel: "labels.bringForward",
@@ -80,7 +80,7 @@ export const actionSendToBack = register({
     return {
       elements: moveAllLeft(elements, appState),
       appState,
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   contextItemLabel: "labels.sendToBack",
@@ -116,7 +116,7 @@ export const actionBringToFront = register({
     return {
       elements: moveAllRight(elements, appState),
       appState,
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   contextItemLabel: "labels.bringToFront",

src/actions/types.ts

@@ -10,6 +10,12 @@ import { MarkOptional } from "../utility-types";
 
 export type ActionSource = "ui" | "keyboard" | "contextMenu" | "api";
 
+export enum StoreAction {
+  NONE = "none",
+  UPDATE = "update", // TODO_UNDO: think about better naming as this one is confusing
+  CAPTURE = "capture",
+}
+
 /** if false, the action should be prevented */
 export type ActionResult =
   | {
@@ -19,8 +25,7 @@ export type ActionResult =
         "offsetTop" | "offsetLeft" | "width" | "height"
       > | null;
       files?: BinaryFiles | null;
-      commitToHistory: boolean;
-      syncHistory?: boolean;
+      storeAction: StoreAction;
       replaceFiles?: boolean;
     }
   | false;

src/change.ts

@@ -0,0 +1,567 @@
+import { newElementWith } from "./element/mutateElement";
+import { ExcalidrawElement } from "./element/types";
+import {
+  AppState,
+  ObservedAppState,
+  ObservedElementsAppState,
+  ObservedStandaloneAppState,
+} from "./types";
+import { SubtypeOf } from "./utility-types";
+import { isShallowEqual } from "./utils";
+
+/**
+ * Represents the difference between two `T` objects.
+ *
+ * Keeping it as pure object (without transient state, side-effects, etc.), so we don't have to instantiate it on load.
+ */
+class Delta<T> {
+  private constructor(
+    public readonly from: Partial<T>,
+    public readonly to: Partial<T>,
+  ) {}
+
+  public static create<T>(
+    from: Partial<T>,
+    to: Partial<T>,
+    modifier?: (delta: Partial<T>) => Partial<T>,
+    modifierOptions?: "from" | "to",
+  ) {
+    const modifiedFrom =
+      modifier && modifierOptions !== "to" ? modifier(from) : from;
+    const modifiedTo =
+      modifier && modifierOptions !== "from" ? modifier(to) : to;
+
+    return new Delta(modifiedFrom, modifiedTo);
+  }
+
+  /**
+   * Calculates the delta between two objects.
+   *
+   * @param prevObject - The previous state of the object.
+   * @param nextObject - The next state of the object.
+   *
+   * @returns new Delta instance.
+   */
+  public static calculate<T extends Object>(
+    prevObject: T,
+    nextObject: T,
+    modifier?: (delta: Partial<T>) => Partial<T>,
+  ): Delta<T> {
+    if (prevObject === nextObject) {
+      return Delta.empty();
+    }
+
+    const from = {} as Partial<T>;
+    const to = {} as Partial<T>;
+
+    const unionOfKeys = new Set([
+      ...Object.keys(prevObject),
+      ...Object.keys(nextObject),
+    ]);
+
+    for (const key of unionOfKeys) {
+      const prevValue = prevObject[key as keyof T];
+      const nextValue = nextObject[key as keyof T];
+
+      if (prevValue !== nextValue) {
+        from[key as keyof T] = prevValue;
+        to[key as keyof T] = nextValue;
+      }
+    }
+    return Delta.create(from, to, modifier);
+  }
+
+  public static empty() {
+    return new Delta({}, {});
+  }
+
+  public static isEmpty<T>(delta: Delta<T>): boolean {
+    return !Object.keys(delta.from).length && !Object.keys(delta.to).length;
+  }
+
+  /**
+   * Compares if the delta contains any different values compared to the object.
+   *
+   * WARN: it's based on shallow compare performed only on the first level, won't work for objects with deeper props.
+   */
+  public static containsDifference<T>(delta: Partial<T>, object: T): boolean {
+    const anyDistinctKey = this.distinctKeysIterator(delta, object).next()
+      .value;
+    return !!anyDistinctKey;
+  }
+
+  /**
+   * Returns all the keys that have distinct values.
+   *
+   * WARN: it's based on shallow compare performed only on the first level, won't work for objects with deeper props.
+   */
+  public static gatherDifferences<T>(delta: Partial<T>, object: T) {
+    const distinctKeys = new Set<string>();
+
+    for (const key of this.distinctKeysIterator(delta, object)) {
+      distinctKeys.add(key);
+    }
+
+    return Array.from(distinctKeys);
+  }
+
+  private static *distinctKeysIterator<T>(delta: Partial<T>, object: T) {
+    for (const [key, deltaValue] of Object.entries(delta)) {
+      const objectValue = object[key as keyof T];
+
+      if (deltaValue !== objectValue) {
+        // TODO_UNDO: staticly fail (typecheck) on deeper objects?
+        if (
+          typeof deltaValue === "object" &&
+          typeof objectValue === "object" &&
+          deltaValue !== null &&
+          objectValue !== null &&
+          isShallowEqual(
+            deltaValue as Record<string, any>,
+            objectValue as Record<string, any>,
+          )
+        ) {
+          continue;
+        }
+
+        yield key;
+      }
+    }
+  }
+}
+
+/**
+ * Encapsulates the modifications captured as `Delta`/s.
+ */
+interface Change<T> {
+  /**
+   * Inverses the `Delta`s inside while creating a new `Change`.
+   */
+  inverse(): Change<T>;
+
+  /**
+   * Applies the `Change` to the previous object.
+   *
+   * @returns new object instance and boolean, indicating if there was any visible change made.
+   */
+  applyTo(previous: Readonly<T>, ...options: unknown[]): [T, boolean];
+
+  /**
+   * Checks whether there are actually `Delta`s.
+   */
+  isEmpty(): boolean;
+}
+
+export class AppStateChange implements Change<AppState> {
+  private constructor(private readonly delta: Delta<ObservedAppState>) {}
+
+  public static calculate<T extends Partial<ObservedAppState>>(
+    prevAppState: T,
+    nextAppState: T,
+  ): AppStateChange {
+    const delta = Delta.calculate(prevAppState, nextAppState);
+    return new AppStateChange(delta);
+  }
+
+  public static empty() {
+    return new AppStateChange(Delta.create({}, {}));
+  }
+
+  public inverse(): AppStateChange {
+    const inversedDelta = Delta.create(this.delta.to, this.delta.from);
+    return new AppStateChange(inversedDelta);
+  }
+
+  public applyTo(
+    appState: Readonly<AppState>,
+    elements: Readonly<Map<string, ExcalidrawElement>>,
+  ): [AppState, boolean] {
+    const constainsVisibleChanges = this.checkForVisibleChanges(
+      appState,
+      elements,
+    );
+
+    const newAppState = {
+      ...appState,
+      ...this.delta.to, // TODO_UNDO: probably shouldn't apply element related changes
+    };
+
+    return [newAppState, constainsVisibleChanges];
+  }
+
+  public isEmpty(): boolean {
+    return Delta.isEmpty(this.delta);
+  }
+
+  private checkForVisibleChanges(
+    appState: ObservedAppState,
+    elements: Map<string, ExcalidrawElement>,
+  ): boolean {
+    const containsStandaloneDifference = Delta.containsDifference(
+      AppStateChange.stripElementsProps(this.delta.to),
+      appState,
+    );
+
+    if (containsStandaloneDifference) {
+      // We detected a a difference which is unrelated to the elements
+      return true;
+    }
+
+    const containsElementsDifference = Delta.containsDifference(
+      AppStateChange.stripStandaloneProps(this.delta.to),
+      appState,
+    );
+
+    if (!containsStandaloneDifference && !containsElementsDifference) {
+      // There is no difference detected at all
+      return false;
+    }
+
+    // We need to handle elements differences separately,
+    // as they could be related to deleted elements and/or they could on their own result in no visible action
+    const changedDeltaKeys = Delta.gatherDifferences(
+      AppStateChange.stripStandaloneProps(this.delta.to),
+      appState,
+    ) as Array<keyof ObservedElementsAppState>;
+
+    // Check whether delta properties are related to the existing non-deleted elements
+    for (const key of changedDeltaKeys) {
+      switch (key) {
+        case "selectedElementIds":
+          if (
+            AppStateChange.checkForSelectedElementsDifferences(
+              this.delta.to[key],
+              appState,
+              elements,
+            )
+          ) {
+            return true;
+          }
+          break;
+        case "selectedLinearElement":
+        case "editingLinearElement":
+          if (
+            AppStateChange.checkForLinearElementDifferences(
+              this.delta.to[key],
+              elements,
+            )
+          ) {
+            return true;
+          }
+          break;
+        case "editingGroupId":
+        case "selectedGroupIds":
+          return AppStateChange.checkForGroupsDifferences();
+        default: {
+          // WARN: this exhaustive check in the switch statement is here to catch unexpected future changes
+          // TODO_UNDO: use assertNever
+          const exhaustiveCheck: never = key;
+          throw new Error(
+            `Unknown ObservedElementsAppState key '${exhaustiveCheck}'.`,
+          );
+        }
+      }
+    }
+
+    return false;
+  }
+
+  private static checkForSelectedElementsDifferences(
+    deltaIds: ObservedElementsAppState["selectedElementIds"] | undefined,
+    appState: Pick<AppState, "selectedElementIds">,
+    elements: Map<string, ExcalidrawElement>,
+  ) {
+    if (!deltaIds) {
+      // There are no selectedElementIds in the delta
+      return;
+    }
+
+    // TODO_UNDO: it could have been visible before (and now it's not)
+    // TODO_UNDO: it could have been selected 
+    for (const id of Object.keys(deltaIds)) {
+      const element = elements.get(id);
+
+      if (element && !element.isDeleted) {
+        // // TODO_UNDO: breaks multi selection
+        // if (appState.selectedElementIds[id]) {
+        //   // Element is already selected
+        //   return;
+        // }
+
+        // Found related visible element!
+        return true;
+      }
+    }
+  }
+
+  private static checkForLinearElementDifferences(
+    linearElement:
+      | ObservedElementsAppState["editingLinearElement"]
+      | ObservedAppState["selectedLinearElement"]
+      | undefined,
+    elements: Map<string, ExcalidrawElement>,
+  ) {
+    if (!linearElement) {
+      return;
+    }
+
+    const element = elements.get(linearElement.elementId);
+
+    if (element && !element.isDeleted) {
+      // Found related visible element!
+      return true;
+    }
+  }
+
+  // Currently we don't have an index of elements by groupIds, which means
+  // the calculation for getting the visible elements based on the groupIds stored in delta
+  // is not worth performing - due to perf. and dev. complexity.
+  //
+  // Therefore we are accepting in these cases empty undos / redos, which should be pretty rare:
+  // - only when one of these (or both) are in delta and the are no non deleted elements containing these group ids
+  private static checkForGroupsDifferences() {
+    return true;
+  }
+
+  private static stripElementsProps(
+    delta: Partial<ObservedAppState>,
+  ): Partial<ObservedStandaloneAppState> {
+    // WARN: Do not remove the type-casts as they here for exhaustive type checks
+    const {
+      editingGroupId,
+      selectedGroupIds,
+      selectedElementIds,
+      editingLinearElement,
+      selectedLinearElement,
+      ...standaloneProps
+    } = delta as ObservedAppState;
+
+    return standaloneProps as SubtypeOf<
+      typeof standaloneProps,
+      ObservedStandaloneAppState
+    >;
+  }
+
+  private static stripStandaloneProps(
+    delta: Partial<ObservedAppState>,
+  ): Partial<ObservedElementsAppState> {
+    // WARN: Do not remove the type-casts as they here for exhaustive type checks
+    const { name, viewBackgroundColor, ...elementsProps } =
+      delta as ObservedAppState;
+
+    return elementsProps as SubtypeOf<
+      typeof elementsProps,
+      ObservedElementsAppState
+    >;
+  }
+}
+
+/**
+ * Elements change is a low level primitive to capture a change between two sets of elements.
+ * It does so by encapsulating forward and backward `Delta`s, which allow to travel in both directions.
+ *
+ * We could be smarter about the change in the future, ideas for improvements are:
+ * - for memory, share the same delta instances between different deltas (flyweight-like)
+ * - for serialization, compress the deltas into a tree-like structures with custom pointers or let one delta instance contain multiple element ids
+ * - for performance, emit the changes directly by the user actions, then apply them in from store into the state (no diffing!)
+ * - for performance, add operations in addition to deltas, which increment (decrement) properties by given value (could be used i.e. for presence-like move)
+ */
+export class ElementsChange implements Change<Map<string, ExcalidrawElement>> {
+  private constructor(
+    // TODO_UNDO: re-think the possible need for added/ remove/ updated deltas (possibly for handling edge cases with deletion, fixing bindings for deletion, showing changes added/modified/updated for version end etc.)
+    private readonly deltas: Map<string, Delta<ExcalidrawElement>>,
+  ) {}
+
+  public static create(deltas: Map<string, Delta<ExcalidrawElement>>) {
+    return new ElementsChange(deltas);
+  }
+
+  /**
+   * Calculates the `Delta`s between the previous and next set of elements.
+   *
+   * @param prevElements - Map representing the previous state of elements.
+   * @param nextElements - Map representing the next state of elements.
+   *
+   * @returns `ElementsChange` instance representing the `Delta` changes between the two sets of elements.
+   */
+  public static calculate<T extends ExcalidrawElement>(
+    prevElements: Map<string, ExcalidrawElement>,
+    nextElements: Map<string, ExcalidrawElement>,
+  ): ElementsChange {
+    if (prevElements === nextElements) {
+      return ElementsChange.empty();
+    }
+
+    const deltas = new Map<string, Delta<T>>();
+
+    // This might be needed only in same edge cases, like during collab, when `isDeleted` elements get removed
+    for (const prevElement of prevElements.values()) {
+      const nextElement = nextElements.get(prevElement.id);
+
+      // Element got removed
+      if (!nextElement) {
+        const from = { ...prevElement, isDeleted: false } as T;
+        const to = { isDeleted: true } as T;
+
+        const delta = Delta.create(
+          from,
+          to,
+          ElementsChange.stripIrrelevantProps,
+        );
+
+        deltas.set(prevElement.id, delta as Delta<T>);
+      }
+    }
+
+    for (const nextElement of nextElements.values()) {
+      const prevElement = prevElements.get(nextElement.id);
+
+      // Element got added
+      if (!prevElement) {
+        if (nextElement.isDeleted) {
+          // Special case when an element is added as deleted (i.e. through the API).
+          // Creating a delta for it wouldn't make sense, as it would go from isDeleted `true` into `true` again.
+          // We are going to skip it for now, later we could be have separate `added` & `removed` entries in the elements change,
+          // so that we would distinguish between actual addition, removal and "soft" (un)deletion.
+          continue;
+        }
+
+        const from = { isDeleted: true } as T;
+        const to = { ...nextElement, isDeleted: false } as T;
+
+        const delta = Delta.create(
+          from,
+          to,
+          ElementsChange.stripIrrelevantProps,
+        );
+
+        deltas.set(nextElement.id, delta as Delta<T>);
+
+        continue;
+      }
+
+      // Element got updated
+      if (prevElement.versionNonce !== nextElement.versionNonce) {
+        // O(n^2) here, but it's not as bad as it looks:
+        // - we do this only on history recordings, not on every frame
+        // - we do this only on changed elements
+        // - # of element's properties is reasonably small
+        // - otherwise we would have to emit deltas on user actions & apply them on every frame
+        const delta = Delta.calculate<ExcalidrawElement>(
+          prevElement,
+          nextElement,
+          ElementsChange.stripIrrelevantProps,
+        );
+
+        // Make sure there are at least some changes (except changes to irrelevant data)
+        if (!Delta.isEmpty(delta)) {
+          deltas.set(nextElement.id, delta as Delta<T>);
+        }
+      }
+    }
+
+    return new ElementsChange(deltas);
+  }
+
+  public static empty() {
+    return new ElementsChange(new Map());
+  }
+
+  public inverse(): ElementsChange {
+    const deltas = new Map<string, Delta<ExcalidrawElement>>();
+
+    for (const [id, delta] of this.deltas.entries()) {
+      deltas.set(id, Delta.create(delta.to, delta.from));
+    }
+
+    return new ElementsChange(deltas);
+  }
+
+  public applyTo(
+    elements: Readonly<Map<string, ExcalidrawElement>>,
+  ): [Map<string, ExcalidrawElement>, boolean] {
+    let containsVisibleDifference = false;
+
+    for (const [id, delta] of this.deltas.entries()) {
+      const existingElement = elements.get(id);
+
+      if (existingElement) {
+        // Check if there was actually any visible change before applying
+        if (!containsVisibleDifference) {
+          // Special case, when delta deletes element, it results in a visible change
+          if (existingElement.isDeleted && delta.to.isDeleted === false) {
+            containsVisibleDifference = true;
+          } else if (!existingElement.isDeleted) {
+            // Check for any difference on a visible element
+            containsVisibleDifference = Delta.containsDifference(
+              delta.to,
+              existingElement,
+            );
+          }
+        }
+
+        elements.set(id, newElementWith(existingElement, delta.to, true));
+      }
+    }
+
+    return [elements, containsVisibleDifference];
+  }
+
+  public isEmpty(): boolean {
+    // TODO_UNDO: might need to go through all deltas and check for emptiness
+    return this.deltas.size === 0;
+  }
+
+  /**
+   * Update the delta/s based on the existing elements.
+   *
+   * @param elements current elements
+   * @param modifierOptions defines which of the delta (`from` or `to`) will be updated
+   * @returns new instance with modified delta/s
+   */
+  public applyLatestChanges(
+    elements: Map<string, ExcalidrawElement>,
+    modifierOptions: "from" | "to",
+  ): ElementsChange {
+    const modifier =
+      (element: ExcalidrawElement) => (partial: Partial<ExcalidrawElement>) => {
+        const modifiedPartial: { [key: string]: unknown } = {};
+
+        for (const key of Object.keys(partial)) {
+          modifiedPartial[key] = element[key as keyof ExcalidrawElement];
+        }
+
+        return modifiedPartial;
+      };
+
+    const deltas = new Map<string, Delta<ExcalidrawElement>>();
+
+    for (const [id, delta] of this.deltas.entries()) {
+      const existingElement = elements.get(id);
+
+      if (existingElement) {
+        const modifiedDelta = Delta.create(
+          delta.from,
+          delta.to,
+          modifier(existingElement),
+          modifierOptions,
+        );
+
+        deltas.set(id, modifiedDelta);
+      } else {
+        // Keep whatever we had
+        deltas.set(id, delta);
+      }
+    }
+
+    return ElementsChange.create(deltas);
+  }
+
+  private static stripIrrelevantProps(delta: Partial<ExcalidrawElement>) {
+    // TODO_UNDO: is seed correctly stripped?
+    const { id, updated, version, versionNonce, seed, ...strippedDelta } =
+      delta;
+
+    return strippedDelta;
+  }
+}

src/clipboard.ts

@@ -9,7 +9,10 @@ import {
   EXPORT_DATA_TYPES,
   MIME_TYPES,
 } from "./constants";
-import { isInitializedImageElement } from "./element/typeChecks";
+import {
+  isFrameLikeElement,
+  isInitializedImageElement,
+} from "./element/typeChecks";
 import { deepCopyElement } from "./element/newElement";
 import { mutateElement } from "./element/mutateElement";
 import { getContainingFrame } from "./frame";
@@ -124,7 +127,7 @@ export const serializeAsClipboardJSON = ({
   files: BinaryFiles | null;
 }) => {
   const framesToCopy = new Set(
-    elements.filter((element) => element.type === "frame"),
+    elements.filter((element) => isFrameLikeElement(element)),
   );
   let foundFile = false;
 

src/components/Actions.scss

@@ -12,6 +12,7 @@
   font-size: 0.875rem !important;
   width: var(--lg-button-size);
   height: var(--lg-button-size);
+
   svg {
     width: var(--lg-icon-size) !important;
     height: var(--lg-icon-size) !important;

src/components/Actions.tsx

@@ -1,7 +1,7 @@
 import React, { useState } from "react";
 import { ActionManager } from "../actions/manager";
 import { getNonDeletedElements } from "../element";
-import { ExcalidrawElement } from "../element/types";
+import { ExcalidrawElement, ExcalidrawElementType } from "../element/types";
 import { t } from "../i18n";
 import { useDevice } from "../components/App";
 import {
@@ -36,6 +36,8 @@ import {
   frameToolIcon,
   mermaidLogoIcon,
   laserPointerToolIcon,
+  OpenAIIcon,
+  MagicIcon,
 } from "./icons";
 import { KEYS } from "../keys";
 
@@ -79,7 +81,8 @@ export const SelectedShapeActions = ({
   const showLinkIcon =
     targetElements.length === 1 || isSingleElementBoundContainer;
 
-  let commonSelectedType: string | null = targetElements[0]?.type || null;
+  let commonSelectedType: ExcalidrawElementType | null =
+    targetElements[0]?.type || null;
 
   for (const element of targetElements) {
     if (element.type !== commonSelectedType) {
@@ -94,7 +97,8 @@ export const SelectedShapeActions = ({
         {((hasStrokeColor(appState.activeTool.type) &&
           appState.activeTool.type !== "image" &&
           commonSelectedType !== "image" &&
-          commonSelectedType !== "frame") ||
+          commonSelectedType !== "frame" &&
+          commonSelectedType !== "magicframe") ||
           targetElements.some((element) => hasStrokeColor(element.type))) &&
           renderAction("changeStrokeColor")}
       </div>
@@ -331,6 +335,9 @@ export const ShapesSwitcher = ({
           >
             {t("toolBar.laser")}
           </DropdownMenu.Item>
+          <div style={{ margin: "6px 0", fontSize: 14, fontWeight: 600 }}>
+            Generate
+          </div>
           <DropdownMenu.Item
             onSelect={() => app.setOpenDialog("mermaid")}
             icon={mermaidLogoIcon}
@@ -338,6 +345,25 @@ export const ShapesSwitcher = ({
           >
             {t("toolBar.mermaidToExcalidraw")}
           </DropdownMenu.Item>
+
+          {app.props.aiEnabled !== false && (
+            <>
+              <DropdownMenu.Item
+                onSelect={() => app.onMagicButtonSelect()}
+                icon={MagicIcon}
+                data-testid="toolbar-magicframe"
+              >
+                {t("toolBar.magicframe")}
+              </DropdownMenu.Item>
+              <DropdownMenu.Item
+                onSelect={() => app.setOpenDialog("magicSettings")}
+                icon={OpenAIIcon}
+                data-testid="toolbar-magicSettings"
+              >
+                {t("toolBar.magicSettings")}
+              </DropdownMenu.Item>
+            </>
+          )}
         </DropdownMenu.Content>
       </DropdownMenu>
     </>

src/components/LayerUI.tsx

@@ -1,7 +1,12 @@
 import clsx from "clsx";
 import React from "react";
 import { ActionManager } from "../actions/manager";
-import { CLASSES, DEFAULT_SIDEBAR, LIBRARY_SIDEBAR_WIDTH } from "../constants";
+import {
+  CLASSES,
+  DEFAULT_SIDEBAR,
+  LIBRARY_SIDEBAR_WIDTH,
+  TOOL_TYPE,
+} from "../constants";
 import { showSelectedShapeActions } from "../element";
 import { NonDeletedExcalidrawElement } from "../element/types";
 import { Language, t } from "../i18n";
@@ -56,6 +61,7 @@ import { mutateElement } from "../element/mutateElement";
 import { ShapeCache } from "../scene/ShapeCache";
 import Scene from "../scene/Scene";
 import { LaserPointerButton } from "./LaserTool/LaserPointerButton";
+import { MagicSettings } from "./MagicSettings";
 
 interface LayerUIProps {
   actionManager: ActionManager;
@@ -77,6 +83,10 @@ interface LayerUIProps {
   children?: React.ReactNode;
   app: AppClassProperties;
   isCollaborating: boolean;
+  openAIKey: string | null;
+  isOpenAIKeyPersisted: boolean;
+  onOpenAIAPIKeyChange: (apiKey: string, shouldPersist: boolean) => void;
+  onMagicSettingsConfirm: (apiKey: string, shouldPersist: boolean) => void;
 }
 
 const DefaultMainMenu: React.FC<{
@@ -133,6 +143,10 @@ const LayerUI = ({
   children,
   app,
   isCollaborating,
+  openAIKey,
+  isOpenAIKeyPersisted,
+  onOpenAIAPIKeyChange,
+  onMagicSettingsConfirm,
 }: LayerUIProps) => {
   const device = useDevice();
   const tunnels = useInitializeTunnels();
@@ -295,9 +309,11 @@ const LayerUI = ({
                         >
                           <LaserPointerButton
                             title={t("toolBar.laser")}
-                            checked={appState.activeTool.type === "laser"}
+                            checked={
+                              appState.activeTool.type === TOOL_TYPE.laser
+                            }
                             onChange={() =>
-                              app.setActiveTool({ type: "laser" })
+                              app.setActiveTool({ type: TOOL_TYPE.laser })
                             }
                             isMobile
                           />
@@ -439,6 +455,20 @@ const LayerUI = ({
           }}
         />
       )}
+      {appState.openDialog === "magicSettings" && (
+        <MagicSettings
+          openAIKey={openAIKey}
+          isPersisted={isOpenAIKeyPersisted}
+          onChange={onOpenAIAPIKeyChange}
+          onConfirm={(apiKey, shouldPersist) => {
+            setAppState({ openDialog: null });
+            onMagicSettingsConfirm(apiKey, shouldPersist);
+          }}
+          onClose={() => {
+            setAppState({ openDialog: null });
+          }}
+        />
+      )}
       <ActiveConfirmDialog />
       <tunnels.OverwriteConfirmDialogTunnel.Out />
       {renderImageExportDialog()}

src/components/MagicButton.tsx

@@ -0,0 +1,38 @@
+import "./ToolIcon.scss";
+
+import clsx from "clsx";
+import { ToolButtonSize } from "./ToolButton";
+
+const DEFAULT_SIZE: ToolButtonSize = "small";
+
+export const ElementCanvasButton = (props: {
+  title?: string;
+  icon: JSX.Element;
+  name?: string;
+  checked: boolean;
+  onChange?(): void;
+  isMobile?: boolean;
+}) => {
+  return (
+    <label
+      className={clsx(
+        "ToolIcon ToolIcon__MagicButton",
+        `ToolIcon_size_${DEFAULT_SIZE}`,
+        {
+          "is-mobile": props.isMobile,
+        },
+      )}
+      title={`${props.title}`}
+    >
+      <input
+        className="ToolIcon_type_checkbox"
+        type="checkbox"
+        name={props.name}
+        onChange={props.onChange}
+        checked={props.checked}
+        aria-label={props.title}
+      />
+      <div className="ToolIcon__icon">{props.icon}</div>
+    </label>
+  );
+};

src/components/MagicSettings.scss

@@ -0,0 +1,9 @@
+.excalidraw {
+  .MagicSettings-confirm {
+    padding: 0.5rem 1rem;
+  }
+
+  .MagicSettings__confirm {
+    margin-top: 2rem;
+  }
+}

src/components/MagicSettings.tsx

@@ -0,0 +1,145 @@
+import { useState } from "react";
+import { Dialog } from "./Dialog";
+import { TextField } from "./TextField";
+import { MagicIcon, OpenAIIcon } from "./icons";
+
+import "./MagicSettings.scss";
+import { FilledButton } from "./FilledButton";
+import { CheckboxItem } from "./CheckboxItem";
+import { KEYS } from "../keys";
+import { useUIAppState } from "../context/ui-appState";
+
+const InlineButton = ({ icon }: { icon: JSX.Element }) => {
+  return (
+    <span
+      style={{
+        width: "1em",
+        margin: "0 0.5ex 0 0.5ex",
+        display: "inline-block",
+        lineHeight: 0,
+        verticalAlign: "middle",
+      }}
+    >
+      {icon}
+    </span>
+  );
+};
+
+export const MagicSettings = (props: {
+  openAIKey: string | null;
+  isPersisted: boolean;
+  onChange: (key: string, shouldPersist: boolean) => void;
+  onConfirm: (key: string, shouldPersist: boolean) => void;
+  onClose: () => void;
+}) => {
+  const { theme } = useUIAppState();
+  const [keyInputValue, setKeyInputValue] = useState(props.openAIKey || "");
+  const [shouldPersist, setShouldPersist] = useState<boolean>(
+    props.isPersisted,
+  );
+
+  const onConfirm = () => {
+    props.onConfirm(keyInputValue.trim(), shouldPersist);
+  };
+
+  return (
+    <Dialog
+      onCloseRequest={() => {
+        props.onClose();
+        props.onConfirm(keyInputValue.trim(), shouldPersist);
+      }}
+      title={
+        <div style={{ display: "flex" }}>
+          Diagram to Code (AI){" "}
+          <div
+            style={{
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              padding: "0.1rem 0.5rem",
+              marginLeft: "1rem",
+              fontSize: 14,
+              borderRadius: "12px",
+              background: theme === "light" ? "#FFCCCC" : "#703333",
+            }}
+          >
+            Experimental
+          </div>
+        </div>
+      }
+      className="MagicSettings"
+      autofocus={false}
+    >
+      <p
+        style={{
+          display: "inline-flex",
+          alignItems: "center",
+          marginBottom: 0,
+        }}
+      >
+        For the diagram-to-code feature we use{" "}
+        <InlineButton icon={OpenAIIcon} />
+        OpenAI.
+      </p>
+      <p>
+        While the OpenAI API is in beta, its use is strictly limited — as such
+        we require you use your own API key. You can create an{" "}
+        <a
+          href="https://platform.openai.com/login?launch"
+          rel="noopener noreferrer"
+          target="_blank"
+        >
+          OpenAI account
+        </a>
+        , add a small credit (5 USD minimum), and{" "}
+        <a
+          href="https://platform.openai.com/api-keys"
+          rel="noopener noreferrer"
+          target="_blank"
+        >
+          generate your own API key
+        </a>
+        .
+      </p>
+      <p>
+        Your OpenAI key does not leave the browser, and you can also set your
+        own limit in your OpenAI account dashboard if needed.
+      </p>
+      <TextField
+        isPassword
+        value={keyInputValue}
+        placeholder="Paste your API key here"
+        label="OpenAI API key"
+        onChange={(value) => {
+          setKeyInputValue(value);
+          props.onChange(value.trim(), shouldPersist);
+        }}
+        selectOnRender
+        onKeyDown={(event) => event.key === KEYS.ENTER && onConfirm()}
+      />
+      <p>
+        By default, your API token is not persisted anywhere so you'll need to
+        insert it again after reload. But, you can persist locally in your
+        browser below.
+      </p>
+
+      <CheckboxItem checked={shouldPersist} onChange={setShouldPersist}>
+        Persist API key in browser storage
+      </CheckboxItem>
+
+      <p>
+        Once API key is set, you can use the <InlineButton icon={MagicIcon} />{" "}
+        tool to wrap your elements in a frame that will then allow you to turn
+        it into code. This dialog can be accessed using the <b>AI Settings</b>{" "}
+        <InlineButton icon={OpenAIIcon} />.
+      </p>
+
+      <FilledButton
+        className="MagicSettings__confirm"
+        size="large"
+        label="Confirm"
+        onClick={onConfirm}
+      />
+    </Dialog>
+  );
+};

src/components/PasteChartDialog.tsx

@@ -94,7 +94,7 @@ export const PasteChartDialog = ({
 
   const handleChartClick = (chartType: ChartType, elements: ChartElements) => {
     onInsertElements(elements);
-    trackEvent("magic", "chart", chartType);
+    trackEvent("paste", "chart", chartType);
     setAppState({
       currentChartType: chartType,
       pasteDialog: {

src/components/PublishLibrary.tsx

@@ -8,6 +8,7 @@ import Trans from "./Trans";
 import { LibraryItems, LibraryItem, UIAppState } from "../types";
 import { exportToCanvas, exportToSvg } from "../packages/utils";
 import {
+  EDITOR_LS_KEYS,
   EXPORT_DATA_TYPES,
   EXPORT_SOURCE,
   MIME_TYPES,
@@ -19,6 +20,7 @@ import { chunk } from "../utils";
 import DialogActionButton from "./DialogActionButton";
 import { CloseIcon } from "./icons";
 import { ToolButton } from "./ToolButton";
+import { EditorLocalStorage } from "../data/EditorLocalStorage";
 
 import "./PublishLibrary.scss";
 
@@ -31,34 +33,6 @@ interface PublishLibraryDataParams {
   website: string;
 }
 
-const LOCAL_STORAGE_KEY_PUBLISH_LIBRARY = "publish-library-data";
-
-const savePublishLibDataToStorage = (data: PublishLibraryDataParams) => {
-  try {
-    localStorage.setItem(
-      LOCAL_STORAGE_KEY_PUBLISH_LIBRARY,
-      JSON.stringify(data),
-    );
-  } catch (error: any) {
-    // Unable to access window.localStorage
-    console.error(error);
-  }
-};
-
-const importPublishLibDataFromStorage = () => {
-  try {
-    const data = localStorage.getItem(LOCAL_STORAGE_KEY_PUBLISH_LIBRARY);
-    if (data) {
-      return JSON.parse(data);
-    }
-  } catch (error: any) {
-    // Unable to access localStorage
-    console.error(error);
-  }
-
-  return null;
-};
-
 const generatePreviewImage = async (libraryItems: LibraryItems) => {
   const MAX_ITEMS_PER_ROW = 6;
   const BOX_SIZE = 128;
@@ -255,7 +229,9 @@ const PublishLibrary = ({
   const [isSubmitting, setIsSubmitting] = useState(false);
 
   useEffect(() => {
-    const data = importPublishLibDataFromStorage();
+    const data = EditorLocalStorage.get<PublishLibraryDataParams>(
+      EDITOR_LS_KEYS.PUBLISH_LIBRARY,
+    );
     if (data) {
       setLibraryData(data);
     }
@@ -328,7 +304,7 @@ const PublishLibrary = ({
           if (response.ok) {
             return response.json().then(({ url }) => {
               // flush data from local storage
-              localStorage.removeItem(LOCAL_STORAGE_KEY_PUBLISH_LIBRARY);
+              EditorLocalStorage.delete(EDITOR_LS_KEYS.PUBLISH_LIBRARY);
               onSuccess({
                 url,
                 authorName: libraryData.authorName,
@@ -384,7 +360,7 @@ const PublishLibrary = ({
 
   const onDialogClose = useCallback(() => {
     updateItemsInStorage(clonedLibItems);
-    savePublishLibDataToStorage(libraryData);
+    EditorLocalStorage.set(EDITOR_LS_KEYS.PUBLISH_LIBRARY, libraryData);
     onClose();
   }, [clonedLibItems, onClose, updateItemsInStorage, libraryData]);
 

src/components/TextField.tsx

@@ -4,12 +4,15 @@ import {
   useImperativeHandle,
   KeyboardEvent,
   useLayoutEffect,
+  useState,
 } from "react";
 import clsx from "clsx";
 
 import "./TextField.scss";
+import { Button } from "./Button";
+import { eyeIcon, eyeClosedIcon } from "./icons";
 
-export type TextFieldProps = {
+type TextFieldProps = {
   value?: string;
 
   onChange?: (value: string) => void;
@@ -22,6 +25,7 @@ export type TextFieldProps = {
 
   label?: string;
   placeholder?: string;
+  isPassword?: boolean;
 };
 
 export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
@@ -35,6 +39,7 @@ export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
       readonly,
       selectOnRender,
       onKeyDown,
+      isPassword = false,
     },
     ref,
   ) => {
@@ -48,6 +53,8 @@ export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
       }
     }, [selectOnRender]);
 
+    const [isVisible, setIsVisible] = useState<boolean>(true);
+
     return (
       <div
         className={clsx("ExcTextField", {
@@ -64,14 +71,22 @@ export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
           })}
         >
           <input
+            type={isPassword && isVisible ? "password" : undefined}
             readOnly={readonly}
-            type="text"
             value={value}
             placeholder={placeholder}
             ref={innerRef}
             onChange={(event) => onChange?.(event.target.value)}
             onKeyDown={onKeyDown}
           />
+          {isPassword && (
+            <Button
+              onSelect={() => setIsVisible(!isVisible)}
+              style={{ border: 0 }}
+            >
+              {isVisible ? eyeIcon : eyeClosedIcon}
+            </Button>
+          )}
         </div>
       </div>
     );

src/components/ToolButton.tsx

@@ -24,6 +24,7 @@ type ToolButtonBaseProps = {
   hidden?: boolean;
   visible?: boolean;
   selected?: boolean;
+  disabled?: boolean;
   className?: string;
   style?: CSSProperties;
   isLoading?: boolean;
@@ -123,10 +124,14 @@ export const ToolButton = React.forwardRef((props: ToolButtonProps, ref) => {
         type={type}
         onClick={onClick}
         ref={innerRef}
-        disabled={isLoading || props.isLoading}
+        disabled={isLoading || props.isLoading || !!props.disabled}
       >
         {(props.icon || props.label) && (
-          <div className="ToolIcon__icon" aria-hidden="true">
+          <div
+            className="ToolIcon__icon"
+            aria-hidden="true"
+            aria-disabled={!!props.disabled}
+          >
             {props.icon || props.label}
             {props.keyBindingLabel && (
               <span className="ToolIcon__keybinding">

src/components/ToolIcon.scss

@@ -77,8 +77,8 @@
   }
 
   .ToolIcon_type_button,
-  .Modal .ToolIcon_type_button,
-  .ToolIcon_type_button {
+  .Modal .ToolIcon_type_button
+  {
     padding: 0;
     border: none;
     margin: 0;
@@ -101,6 +101,22 @@
       background-color: var(--button-gray-3);
     }
 
+    &:disabled {
+      cursor: default;
+  
+      &:active,
+      &:focus-visible,
+      &:hover {
+        background-color: initial;
+        border: none;
+        box-shadow: none;
+      }
+  
+      svg {
+        color: var(--color-disabled);
+      }
+    }
+
     &--show {
       visibility: visible;
     }
@@ -175,7 +191,8 @@
       }
     }
 
-    .ToolIcon__LaserPointer .ToolIcon__icon {
+    .ToolIcon__LaserPointer .ToolIcon__icon,
+    .ToolIcon__MagicButton .ToolIcon__icon {
       width: var(--default-button-size);
       height: var(--default-button-size);
     }

src/components/canvases/InteractiveCanvas.tsx

@@ -189,8 +189,6 @@ const getRelevantAppStateProps = (
   suggestedBindings: appState.suggestedBindings,
   isRotating: appState.isRotating,
   elementsToHighlight: appState.elementsToHighlight,
-  openSidebar: appState.openSidebar,
-  showHyperlinkPopup: appState.showHyperlinkPopup,
   collaborators: appState.collaborators, // Necessary for collab. sessions
   activeEmbeddable: appState.activeEmbeddable,
   snapLines: appState.snapLines,

src/components/icons.tsx

@@ -1688,3 +1688,57 @@ export const laserPointerToolIcon = createIcon(
 
   20,
 );
+
+export const MagicIcon = createIcon(
+  <g stroke="currentColor" fill="none">
+    <path stroke="none" d="M0 0h24v24H0z" />
+    <path d="M6 21l15 -15l-3 -3l-15 15l3 3" />
+    <path d="M15 6l3 3" />
+    <path d="M9 3a2 2 0 0 0 2 2a2 2 0 0 0 -2 2a2 2 0 0 0 -2 -2a2 2 0 0 0 2 -2" />
+    <path d="M19 13a2 2 0 0 0 2 2a2 2 0 0 0 -2 2a2 2 0 0 0 -2 -2a2 2 0 0 0 2 -2" />
+  </g>,
+  tablerIconProps,
+);
+
+export const OpenAIIcon = createIcon(
+  <g stroke="currentColor" fill="none">
+    <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+    <path d="M11.217 19.384a3.501 3.501 0 0 0 6.783 -1.217v-5.167l-6 -3.35" />
+    <path d="M5.214 15.014a3.501 3.501 0 0 0 4.446 5.266l4.34 -2.534v-6.946" />
+    <path d="M6 7.63c-1.391 -.236 -2.787 .395 -3.534 1.689a3.474 3.474 0 0 0 1.271 4.745l4.263 2.514l6 -3.348" />
+    <path d="M12.783 4.616a3.501 3.501 0 0 0 -6.783 1.217v5.067l6 3.45" />
+    <path d="M18.786 8.986a3.501 3.501 0 0 0 -4.446 -5.266l-4.34 2.534v6.946" />
+    <path d="M18 16.302c1.391 .236 2.787 -.395 3.534 -1.689a3.474 3.474 0 0 0 -1.271 -4.745l-4.308 -2.514l-5.955 3.42" />
+  </g>,
+  tablerIconProps,
+);
+
+export const fullscreenIcon = createIcon(
+  <g stroke="currentColor" fill="none">
+    <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+    <path d="M4 8v-2a2 2 0 0 1 2 -2h2" />
+    <path d="M4 16v2a2 2 0 0 0 2 2h2" />
+    <path d="M16 4h2a2 2 0 0 1 2 2v2" />
+    <path d="M16 20h2a2 2 0 0 0 2 -2v-2" />
+  </g>,
+  tablerIconProps,
+);
+
+export const eyeIcon = createIcon(
+  <g stroke="currentColor" fill="none">
+    <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+    <path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" />
+    <path d="M21 12c-2.4 4 -5.4 6 -9 6c-3.6 0 -6.6 -2 -9 -6c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6" />
+  </g>,
+  tablerIconProps,
+);
+
+export const eyeClosedIcon = createIcon(
+  <g stroke="currentColor" fill="none">
+    <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+    <path d="M10.585 10.587a2 2 0 0 0 2.829 2.828" />
+    <path d="M16.681 16.673a8.717 8.717 0 0 1 -4.681 1.327c-3.6 0 -6.6 -2 -9 -6c1.272 -2.12 2.712 -3.678 4.32 -4.674m2.86 -1.146a9.055 9.055 0 0 1 1.82 -.18c3.6 0 6.6 2 9 6c-.666 1.11 -1.379 2.067 -2.138 2.87" />
+    <path d="M3 3l18 18" />
+  </g>,
+  tablerIconProps,
+);

src/constants.ts

@@ -80,6 +80,7 @@ export enum EVENT {
   EXCALIDRAW_LINK = "excalidraw-link",
   MENU_ITEM_SELECT = "menu.itemSelect",
   MESSAGE = "message",
+  FULLSCREENCHANGE = "fullscreenchange",
 }
 
 export const YOUTUBE_STATES = {
@@ -195,6 +196,7 @@ export const VERSION_TIMEOUT = 30000;
 export const SCROLL_TIMEOUT = 100;
 export const ZOOM_STEP = 0.1;
 export const MIN_ZOOM = 0.1;
+export const MAX_ZOOM = 30.0;
 export const HYPERLINK_TOOLTIP_DELAY = 300;
 
 // Report a user inactive after IDLE_THRESHOLD milliseconds
@@ -301,10 +303,6 @@ export const ROUNDNESS = {
   ADAPTIVE_RADIUS: 3,
 } as const;
 
-/** key containt id of precedeing elemnt id we use in reconciliation during
- * collaboration */
-export const PRECEDING_ELEMENT_KEY = "__precedingElement__";
-
 export const ROUGHNESS = {
   architect: 0,
   artist: 1,
@@ -344,4 +342,33 @@ export const DEFAULT_SIDEBAR = {
   defaultTab: LIBRARY_SIDEBAR_TAB,
 } as const;
 
-export const LIBRARY_DISABLED_TYPES = new Set(["embeddable", "image"] as const);
+export const LIBRARY_DISABLED_TYPES = new Set([
+  "iframe",
+  "embeddable",
+  "image",
+] as const);
+
+// use these constants to easily identify reference sites
+export const TOOL_TYPE = {
+  selection: "selection",
+  rectangle: "rectangle",
+  diamond: "diamond",
+  ellipse: "ellipse",
+  arrow: "arrow",
+  line: "line",
+  freedraw: "freedraw",
+  text: "text",
+  image: "image",
+  eraser: "eraser",
+  hand: "hand",
+  frame: "frame",
+  magicframe: "magicframe",
+  embeddable: "embeddable",
+  laser: "laser",
+} as const;
+
+export const EDITOR_LS_KEYS = {
+  OAI_API_KEY: "excalidraw-oai-api-key",
+  // legacy naming (non)scheme
+  PUBLISH_LIBRARY: "publish-library-data",
+} as const;

src/css/styles.scss

@@ -5,9 +5,11 @@
   --zIndex-canvas: 1;
   --zIndex-interactiveCanvas: 2;
   --zIndex-wysiwyg: 3;
+  --zIndex-canvasButtons: 3;
   --zIndex-layerUI: 4;
   --zIndex-eyeDropperBackdrop: 5;
   --zIndex-eyeDropperPreview: 6;
+  --zIndex-hyperlinkContainer: 7;
 
   --zIndex-modal: 1000;
   --zIndex-popup: 1001;

src/css/theme.scss

@@ -97,6 +97,8 @@
   --color-gray-90: #1e1e1e;
   --color-gray-100: #121212;
 
+  --color-disabled: var(--color-gray-40);
+
   --color-warning: #fceeca;
   --color-warning-dark: #f5c354;
   --color-warning-darker: #f3ab2c;

src/css/variables.module.scss

@@ -50,6 +50,15 @@
         color: var(--color-on-primary-container);
       }
     }
+
+    &[aria-disabled="true"] {
+      background: initial;
+      border: none;
+
+      svg {
+        color: var(--color-disabled);
+      }
+    }
   }
 }
 

src/data/EditorLocalStorage.ts

@@ -0,0 +1,51 @@
+import { EDITOR_LS_KEYS } from "../constants";
+import { JSONValue } from "../types";
+
+export class EditorLocalStorage {
+  static has(key: typeof EDITOR_LS_KEYS[keyof typeof EDITOR_LS_KEYS]) {
+    try {
+      return !!window.localStorage.getItem(key);
+    } catch (error: any) {
+      console.warn(`localStorage.getItem error: ${error.message}`);
+      return false;
+    }
+  }
+
+  static get<T extends JSONValue>(
+    key: typeof EDITOR_LS_KEYS[keyof typeof EDITOR_LS_KEYS],
+  ) {
+    try {
+      const value = window.localStorage.getItem(key);
+      if (value) {
+        return JSON.parse(value) as T;
+      }
+      return null;
+    } catch (error: any) {
+      console.warn(`localStorage.getItem error: ${error.message}`);
+      return null;
+    }
+  }
+
+  static set = (
+    key: typeof EDITOR_LS_KEYS[keyof typeof EDITOR_LS_KEYS],
+    value: JSONValue,
+  ) => {
+    try {
+      window.localStorage.setItem(key, JSON.stringify(value));
+      return true;
+    } catch (error: any) {
+      console.warn(`localStorage.setItem error: ${error.message}`);
+      return false;
+    }
+  };
+
+  static delete = (
+    name: typeof EDITOR_LS_KEYS[keyof typeof EDITOR_LS_KEYS],
+  ) => {
+    try {
+      window.localStorage.removeItem(name);
+    } catch (error: any) {
+      console.warn(`localStorage.removeItem error: ${error.message}`);
+    }
+  };
+}

src/data/__snapshots__/transform.test.ts.snap

@@ -15,6 +15,7 @@ exports[`Test Transform > Test arrow bindings > should bind arrows to existing s
     },
   ],
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 300,
@@ -50,6 +51,7 @@ exports[`Test Transform > Test arrow bindings > should bind arrows to existing s
     },
   ],
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 100,
@@ -86,6 +88,7 @@ exports[`Test Transform > Test arrow bindings > should bind arrows to existing s
     "gap": 1,
   },
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 35,
@@ -139,6 +142,7 @@ exports[`Test Transform > Test arrow bindings > should bind arrows to existing s
     "gap": 3.834326468444573,
   },
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 0,
@@ -191,6 +195,7 @@ exports[`Test Transform > Test arrow bindings > should bind arrows to existing s
     },
   ],
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 300,
@@ -230,6 +235,7 @@ exports[`Test Transform > Test arrow bindings > should bind arrows to existing t
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 25,
@@ -274,6 +280,7 @@ exports[`Test Transform > Test arrow bindings > should bind arrows to existing t
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 25,
@@ -320,6 +327,7 @@ exports[`Test Transform > Test arrow bindings > should bind arrows to existing t
     "gap": 205,
   },
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 0,
@@ -371,6 +379,7 @@ exports[`Test Transform > Test arrow bindings > should bind arrows to existing t
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 25,
@@ -417,6 +426,7 @@ exports[`Test Transform > Test arrow bindings > should bind arrows to shapes whe
     "gap": 1,
   },
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 0,
@@ -468,6 +478,7 @@ exports[`Test Transform > Test arrow bindings > should bind arrows to shapes whe
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 25,
@@ -508,6 +519,7 @@ exports[`Test Transform > Test arrow bindings > should bind arrows to shapes whe
     },
   ],
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 100,
@@ -543,6 +555,7 @@ exports[`Test Transform > Test arrow bindings > should bind arrows to shapes whe
     },
   ],
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 100,
@@ -584,6 +597,7 @@ exports[`Test Transform > Test arrow bindings > should bind arrows to text when
     "gap": 1,
   },
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 0,
@@ -635,6 +649,7 @@ exports[`Test Transform > Test arrow bindings > should bind arrows to text when
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 25,
@@ -679,6 +694,7 @@ exports[`Test Transform > Test arrow bindings > should bind arrows to text when
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 25,
@@ -723,6 +739,7 @@ exports[`Test Transform > Test arrow bindings > should bind arrows to text when
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 25,
@@ -758,6 +775,7 @@ exports[`Test Transform > should not allow duplicate ids 1`] = `
   "backgroundColor": "transparent",
   "boundElements": null,
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 200,
@@ -790,6 +808,7 @@ exports[`Test Transform > should transform linear elements 1`] = `
   "endArrowhead": "arrow",
   "endBinding": null,
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 0,
@@ -835,6 +854,7 @@ exports[`Test Transform > should transform linear elements 2`] = `
   "endArrowhead": "triangle",
   "endBinding": null,
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 0,
@@ -880,6 +900,7 @@ exports[`Test Transform > should transform linear elements 3`] = `
   "endArrowhead": null,
   "endBinding": null,
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 0,
@@ -925,6 +946,7 @@ exports[`Test Transform > should transform linear elements 4`] = `
   "endArrowhead": null,
   "endBinding": null,
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 0,
@@ -968,6 +990,7 @@ exports[`Test Transform > should transform regular shapes 1`] = `
   "backgroundColor": "transparent",
   "boundElements": null,
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 100,
@@ -998,6 +1021,7 @@ exports[`Test Transform > should transform regular shapes 2`] = `
   "backgroundColor": "transparent",
   "boundElements": null,
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 100,
@@ -1028,6 +1052,7 @@ exports[`Test Transform > should transform regular shapes 3`] = `
   "backgroundColor": "transparent",
   "boundElements": null,
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 100,
@@ -1058,6 +1083,7 @@ exports[`Test Transform > should transform regular shapes 4`] = `
   "backgroundColor": "#c0eb75",
   "boundElements": null,
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 100,
@@ -1088,6 +1114,7 @@ exports[`Test Transform > should transform regular shapes 5`] = `
   "backgroundColor": "#ffc9c9",
   "boundElements": null,
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 100,
@@ -1118,6 +1145,7 @@ exports[`Test Transform > should transform regular shapes 6`] = `
   "backgroundColor": "#a5d8ff",
   "boundElements": null,
   "fillStyle": "cross-hatch",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 100,
@@ -1152,6 +1180,7 @@ exports[`Test Transform > should transform text element 1`] = `
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 25,
@@ -1191,6 +1220,7 @@ exports[`Test Transform > should transform text element 2`] = `
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 25,
@@ -1233,6 +1263,7 @@ exports[`Test Transform > should transform to labelled arrows when label provide
   "endArrowhead": "arrow",
   "endBinding": null,
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 0,
@@ -1283,6 +1314,7 @@ exports[`Test Transform > should transform to labelled arrows when label provide
   "endArrowhead": "arrow",
   "endBinding": null,
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 0,
@@ -1333,6 +1365,7 @@ exports[`Test Transform > should transform to labelled arrows when label provide
   "endArrowhead": "arrow",
   "endBinding": null,
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 0,
@@ -1383,6 +1416,7 @@ exports[`Test Transform > should transform to labelled arrows when label provide
   "endArrowhead": "arrow",
   "endBinding": null,
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 0,
@@ -1430,6 +1464,7 @@ exports[`Test Transform > should transform to labelled arrows when label provide
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 25,
@@ -1469,6 +1504,7 @@ exports[`Test Transform > should transform to labelled arrows when label provide
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 25,
@@ -1508,6 +1544,7 @@ exports[`Test Transform > should transform to labelled arrows when label provide
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 50,
@@ -1548,6 +1585,7 @@ exports[`Test Transform > should transform to labelled arrows when label provide
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 50,
@@ -1589,6 +1627,7 @@ exports[`Test Transform > should transform to text containers when label provide
     },
   ],
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 35,
@@ -1624,6 +1663,7 @@ exports[`Test Transform > should transform to text containers when label provide
     },
   ],
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 85,
@@ -1659,6 +1699,7 @@ exports[`Test Transform > should transform to text containers when label provide
     },
   ],
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 170,
@@ -1694,6 +1735,7 @@ exports[`Test Transform > should transform to text containers when label provide
     },
   ],
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 120,
@@ -1729,6 +1771,7 @@ exports[`Test Transform > should transform to text containers when label provide
     },
   ],
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 85,
@@ -1764,6 +1807,7 @@ exports[`Test Transform > should transform to text containers when label provide
     },
   ],
   "fillStyle": "solid",
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 120,
@@ -1798,6 +1842,7 @@ exports[`Test Transform > should transform to text containers when label provide
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 25,
@@ -1837,6 +1882,7 @@ exports[`Test Transform > should transform to text containers when label provide
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 50,
@@ -1877,6 +1923,7 @@ exports[`Test Transform > should transform to text containers when label provide
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 75,
@@ -1919,6 +1966,7 @@ exports[`Test Transform > should transform to text containers when label provide
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 50,
@@ -1959,6 +2007,7 @@ exports[`Test Transform > should transform to text containers when label provide
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 75,
@@ -2000,6 +2049,7 @@ exports[`Test Transform > should transform to text containers when label provide
   "fillStyle": "solid",
   "fontFamily": 1,
   "fontSize": 20,
+  "fractionalIndex": null,
   "frameId": null,
   "groupIds": [],
   "height": 75,

src/data/ai/types.ts

@@ -0,0 +1,300 @@
+export namespace OpenAIInput {
+  type ChatCompletionContentPart =
+    | ChatCompletionContentPartText
+    | ChatCompletionContentPartImage;
+
+  interface ChatCompletionContentPartImage {
+    image_url: ChatCompletionContentPartImage.ImageURL;
+
+    /**
+     * The type of the content part.
+     */
+    type: "image_url";
+  }
+
+  namespace ChatCompletionContentPartImage {
+    export interface ImageURL {
+      /**
+       * Either a URL of the image or the base64 encoded image data.
+       */
+      url: string;
+
+      /**
+       * Specifies the detail level of the image.
+       */
+      detail?: "auto" | "low" | "high";
+    }
+  }
+
+  interface ChatCompletionContentPartText {
+    /**
+     * The text content.
+     */
+    text: string;
+
+    /**
+     * The type of the content part.
+     */
+    type: "text";
+  }
+
+  interface ChatCompletionUserMessageParam {
+    /**
+     * The contents of the user message.
+     */
+    content: string | Array<ChatCompletionContentPart> | null;
+
+    /**
+     * The role of the messages author, in this case `user`.
+     */
+    role: "user";
+  }
+
+  interface ChatCompletionSystemMessageParam {
+    /**
+     * The contents of the system message.
+     */
+    content: string | null;
+
+    /**
+     * The role of the messages author, in this case `system`.
+     */
+    role: "system";
+  }
+
+  export interface ChatCompletionCreateParamsBase {
+    /**
+     * A list of messages comprising the conversation so far.
+     * [Example Python code](https://cookbook.openai.com/examples/how_to_format_inputs_to_chatgpt_models).
+     */
+    messages: Array<
+      ChatCompletionUserMessageParam | ChatCompletionSystemMessageParam
+    >;
+
+    /**
+     * ID of the model to use. See the
+     * [model endpoint compatibility](https://platform.openai.com/docs/models/model-endpoint-compatibility)
+     * table for details on which models work with the Chat API.
+     */
+    model:
+      | (string & {})
+      | "gpt-4-1106-preview"
+      | "gpt-4-vision-preview"
+      | "gpt-4"
+      | "gpt-4-0314"
+      | "gpt-4-0613"
+      | "gpt-4-32k"
+      | "gpt-4-32k-0314"
+      | "gpt-4-32k-0613"
+      | "gpt-3.5-turbo"
+      | "gpt-3.5-turbo-16k"
+      | "gpt-3.5-turbo-0301"
+      | "gpt-3.5-turbo-0613"
+      | "gpt-3.5-turbo-16k-0613";
+
+    /**
+     * Number between -2.0 and 2.0. Positive values penalize new tokens based on their
+     * existing frequency in the text so far, decreasing the model's likelihood to
+     * repeat the same line verbatim.
+     *
+     * [See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/gpt/parameter-details)
+     */
+    frequency_penalty?: number | null;
+
+    /**
+     * Modify the likelihood of specified tokens appearing in the completion.
+     *
+     * Accepts a JSON object that maps tokens (specified by their token ID in the
+     * tokenizer) to an associated bias value from -100 to 100. Mathematically, the
+     * bias is added to the logits generated by the model prior to sampling. The exact
+     * effect will vary per model, but values between -1 and 1 should decrease or
+     * increase likelihood of selection; values like -100 or 100 should result in a ban
+     * or exclusive selection of the relevant token.
+     */
+    logit_bias?: Record<string, number> | null;
+
+    /**
+     * The maximum number of [tokens](/tokenizer) to generate in the chat completion.
+     *
+     * The total length of input tokens and generated tokens is limited by the model's
+     * context length.
+     * [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken)
+     * for counting tokens.
+     */
+    max_tokens?: number | null;
+
+    /**
+     * How many chat completion choices to generate for each input message.
+     */
+    n?: number | null;
+
+    /**
+     * Number between -2.0 and 2.0. Positive values penalize new tokens based on
+     * whether they appear in the text so far, increasing the model's likelihood to
+     * talk about new topics.
+     *
+     * [See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/gpt/parameter-details)
+     */
+    presence_penalty?: number | null;
+
+    /**
+     * This feature is in Beta. If specified, our system will make a best effort to
+     * sample deterministically, such that repeated requests with the same `seed` and
+     * parameters should return the same result. Determinism is not guaranteed, and you
+     * should refer to the `system_fingerprint` response parameter to monitor changes
+     * in the backend.
+     */
+    seed?: number | null;
+
+    /**
+     * Up to 4 sequences where the API will stop generating further tokens.
+     */
+    stop?: string | null | Array<string>;
+
+    /**
+     * If set, partial message deltas will be sent, like in ChatGPT. Tokens will be
+     * sent as data-only
+     * [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format)
+     * as they become available, with the stream terminated by a `data: [DONE]`
+     * message.
+     * [Example Python code](https://cookbook.openai.com/examples/how_to_stream_completions).
+     */
+    stream?: boolean | null;
+
+    /**
+     * What sampling temperature to use, between 0 and 2. Higher values like 0.8 will
+     * make the output more random, while lower values like 0.2 will make it more
+     * focused and deterministic.
+     *
+     * We generally recommend altering this or `top_p` but not both.
+     */
+    temperature?: number | null;
+
+    /**
+     * An alternative to sampling with temperature, called nucleus sampling, where the
+     * model considers the results of the tokens with top_p probability mass. So 0.1
+     * means only the tokens comprising the top 10% probability mass are considered.
+     *
+     * We generally recommend altering this or `temperature` but not both.
+     */
+    top_p?: number | null;
+
+    /**
+     * A unique identifier representing your end-user, which can help OpenAI to monitor
+     * and detect abuse.
+     * [Learn more](https://platform.openai.com/docs/guides/safety-best-practices/end-user-ids).
+     */
+    user?: string;
+  }
+}
+
+export namespace OpenAIOutput {
+  export interface ChatCompletion {
+    /**
+     * A unique identifier for the chat completion.
+     */
+    id: string;
+
+    /**
+     * A list of chat completion choices. Can be more than one if `n` is greater
+     * than 1.
+     */
+    choices: Array<Choice>;
+
+    /**
+     * The Unix timestamp (in seconds) of when the chat completion was created.
+     */
+    created: number;
+
+    /**
+     * The model used for the chat completion.
+     */
+    model: string;
+
+    /**
+     * The object type, which is always `chat.completion`.
+     */
+    object: "chat.completion";
+
+    /**
+     * This fingerprint represents the backend configuration that the model runs with.
+     *
+     * Can be used in conjunction with the `seed` request parameter to understand when
+     * backend changes have been made that might impact determinism.
+     */
+    system_fingerprint?: string;
+
+    /**
+     * Usage statistics for the completion request.
+     */
+    usage?: CompletionUsage;
+  }
+  export interface Choice {
+    /**
+     * The reason the model stopped generating tokens. This will be `stop` if the model
+     * hit a natural stop point or a provided stop sequence, `length` if the maximum
+     * number of tokens specified in the request was reached, `content_filter` if
+     * content was omitted due to a flag from our content filters, `tool_calls` if the
+     * model called a tool, or `function_call` (deprecated) if the model called a
+     * function.
+     */
+    finish_reason:
+      | "stop"
+      | "length"
+      | "tool_calls"
+      | "content_filter"
+      | "function_call";
+
+    /**
+     * The index of the choice in the list of choices.
+     */
+    index: number;
+
+    /**
+     * A chat completion message generated by the model.
+     */
+    message: ChatCompletionMessage;
+  }
+
+  interface ChatCompletionMessage {
+    /**
+     * The contents of the message.
+     */
+    content: string | null;
+
+    /**
+     * The role of the author of this message.
+     */
+    role: "assistant";
+  }
+
+  /**
+   * Usage statistics for the completion request.
+   */
+  interface CompletionUsage {
+    /**
+     * Number of tokens in the generated completion.
+     */
+    completion_tokens: number;
+
+    /**
+     * Number of tokens in the prompt.
+     */
+    prompt_tokens: number;
+
+    /**
+     * Total number of tokens used in the request (prompt + completion).
+     */
+    total_tokens: number;
+  }
+
+  export interface APIError {
+    readonly status: 400 | 401 | 403 | 404 | 409 | 422 | 429 | 500 | undefined;
+    readonly headers: Headers | undefined;
+    readonly error: { message: string } | undefined;
+
+    readonly code: string | null | undefined;
+    readonly param: string | null | undefined;
+    readonly type: string | undefined;
+  }
+}

src/data/index.ts

@@ -3,10 +3,11 @@ import {
   copyTextToSystemClipboard,
 } from "../clipboard";
 import { DEFAULT_EXPORT_PADDING, isFirefox, MIME_TYPES } from "../constants";
-import { getNonDeletedElements, isFrameElement } from "../element";
+import { getNonDeletedElements } from "../element";
+import { isFrameLikeElement } from "../element/typeChecks";
 import {
   ExcalidrawElement,
-  ExcalidrawFrameElement,
+  ExcalidrawFrameLikeElement,
   NonDeletedExcalidrawElement,
 } from "../element/types";
 import { t } from "../i18n";
@@ -38,7 +39,7 @@ export const prepareElementsForExport = (
     exportSelectionOnly &&
     isSomeElementSelected(elements, { selectedElementIds });
 
-  let exportingFrame: ExcalidrawFrameElement | null = null;
+  let exportingFrame: ExcalidrawFrameLikeElement | null = null;
   let exportedElements = isExportingSelection
     ? getSelectedElements(
         elements,
@@ -50,7 +51,10 @@ export const prepareElementsForExport = (
     : elements;
 
   if (isExportingSelection) {
-    if (exportedElements.length === 1 && isFrameElement(exportedElements[0])) {
+    if (
+      exportedElements.length === 1 &&
+      isFrameLikeElement(exportedElements[0])
+    ) {
       exportingFrame = exportedElements[0];
       exportedElements = elementsOverlappingBBox({
         elements,
@@ -93,7 +97,7 @@ export const exportCanvas = async (
     viewBackgroundColor: string;
     name: string;
     fileHandle?: FileSystemHandle | null;
-    exportingFrame: ExcalidrawFrameElement | null;
+    exportingFrame: ExcalidrawFrameLikeElement | null;
   },
 ) => {
   if (elements.length === 0) {

src/data/magic.ts

@@ -0,0 +1,104 @@
+import { Theme } from "../element/types";
+import { DataURL } from "../types";
+import { OpenAIInput, OpenAIOutput } from "./ai/types";
+
+export type MagicCacheData =
+  | {
+      status: "pending";
+    }
+  | { status: "done"; html: string }
+  | {
+      status: "error";
+      message?: string;
+      code: "ERR_GENERATION_INTERRUPTED" | string;
+    };
+
+const SYSTEM_PROMPT = `You are a skilled front-end developer who builds interactive prototypes from wireframes, and is an expert at CSS Grid and Flex design.
+Your role is to transform low-fidelity wireframes into working front-end HTML code.
+
+YOU MUST FOLLOW FOLLOWING RULES:
+
+- Use HTML, CSS, JavaScript to build a responsive, accessible, polished prototype
+- Leverage Tailwind for styling and layout (import as script <script src="https://cdn.tailwindcss.com"></script>)
+- Inline JavaScript when needed
+- Fetch dependencies from CDNs when needed (using unpkg or skypack)
+- Source images from Unsplash or create applicable placeholders
+- Interpret annotations as intended vs literal UI
+- Fill gaps using your expertise in UX and business logic
+- generate primarily for desktop UI, but make it responsive.
+- Use grid and flexbox wherever applicable.
+- Convert the wireframe in its entirety, don't omit elements if possible.
+
+If the wireframes, diagrams, or text is unclear or unreadable, refer to provided text for clarification.
+
+Your goal is a production-ready prototype that brings the wireframes to life.
+
+Please output JUST THE HTML file containing your best attempt at implementing the provided wireframes.`;
+
+export async function diagramToHTML({
+  image,
+  apiKey,
+  text,
+  theme = "light",
+}: {
+  image: DataURL;
+  apiKey: string;
+  text: string;
+  theme?: Theme;
+}) {
+  const body: OpenAIInput.ChatCompletionCreateParamsBase = {
+    model: "gpt-4-vision-preview",
+    // 4096 are max output tokens allowed for `gpt-4-vision-preview` currently
+    max_tokens: 4096,
+    temperature: 0.1,
+    messages: [
+      {
+        role: "system",
+        content: SYSTEM_PROMPT,
+      },
+      {
+        role: "user",
+        content: [
+          {
+            type: "image_url",
+            image_url: {
+              url: image,
+              detail: "high",
+            },
+          },
+          {
+            type: "text",
+            text: `Above is the reference wireframe. Please make a new website based on these and return just the HTML file. Also, please make it for the ${theme} theme. What follows are the wireframe's text annotations (if any)...`,
+          },
+          {
+            type: "text",
+            text,
+          },
+        ],
+      },
+    ],
+  };
+
+  let result:
+    | ({ ok: true } & OpenAIOutput.ChatCompletion)
+    | ({ ok: false } & OpenAIOutput.APIError);
+
+  const resp = await fetch("https://api.openai.com/v1/chat/completions", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (resp.ok) {
+    const json: OpenAIOutput.ChatCompletion = await resp.json();
+    result = { ...json, ok: true };
+  } else {
+    const json: OpenAIOutput.APIError = await resp.json();
+    result = { ...json, ok: false };
+  }
+
+  return result;
+}

src/data/restore.ts

@@ -1,5 +1,6 @@
 import {
   ExcalidrawElement,
+  ExcalidrawElementType,
   ExcalidrawSelectionElement,
   ExcalidrawTextElement,
   FontFamilyValues,
@@ -25,7 +26,6 @@ import {
   DEFAULT_FONT_FAMILY,
   DEFAULT_TEXT_ALIGN,
   DEFAULT_VERTICAL_ALIGN,
-  PRECEDING_ELEMENT_KEY,
   FONT_FAMILY,
   ROUNDNESS,
   DEFAULT_SIDEBAR,
@@ -43,6 +43,7 @@ import {
   measureBaseline,
 } from "../element/textElement";
 import { normalizeLink } from "./url";
+import { restoreFractionalIndicies } from "../fractionalIndex";
 
 type RestoredAppState = Omit<
   AppState,
@@ -68,6 +69,7 @@ export const AllowedExcalidrawActiveTools: Record<
   embeddable: true,
   hand: true,
   laser: false,
+  magicframe: false,
 };
 
 export type RestoredDataState = {
@@ -99,8 +101,6 @@ const restoreElementWithProperties = <
     boundElementIds?: readonly ExcalidrawElement["id"][];
     /** @deprecated */
     strokeSharpness?: StrokeRoundness;
-    /** metadata that may be present in elements during collaboration */
-    [PRECEDING_ELEMENT_KEY]?: string;
   },
   K extends Pick<T, keyof Omit<Required<T>, keyof ExcalidrawElement>>,
 >(
@@ -111,16 +111,16 @@ const restoreElementWithProperties = <
     // @ts-ignore TS complains here but type checks the call sites fine.
     keyof K
   > &
-    Partial<Pick<ExcalidrawElement, "type" | "x" | "y">>,
+    Partial<Pick<ExcalidrawElement, "type" | "x" | "y" | "customData">>,
 ): T => {
-  const base: Pick<T, keyof ExcalidrawElement> & {
-    [PRECEDING_ELEMENT_KEY]?: string;
-  } = {
+  const base: Pick<T, keyof ExcalidrawElement> = {
     type: extra.type || element.type,
     // all elements must have version > 0 so getSceneVersion() will pick up
     // newly added elements
     version: element.version || 1,
     versionNonce: element.versionNonce ?? 0,
+    // TODO: think about this more
+    fractionalIndex: element.fractionalIndex ?? null,
     isDeleted: element.isDeleted ?? false,
     id: element.id || randomId(),
     fillStyle: element.fillStyle || DEFAULT_ELEMENT_PROPS.fillStyle,
@@ -159,12 +159,9 @@ const restoreElementWithProperties = <
     locked: element.locked ?? false,
   };
 
-  if ("customData" in element) {
-    base.customData = element.customData;
-  }
-
-  if (PRECEDING_ELEMENT_KEY in element) {
-    base[PRECEDING_ELEMENT_KEY] = element[PRECEDING_ELEMENT_KEY];
+  if ("customData" in element || "customData" in extra) {
+    base.customData =
+      "customData" in extra ? extra.customData : element.customData;
   }
 
   return {
@@ -273,7 +270,7 @@ const restoreElement = (
 
       return restoreElementWithProperties(element, {
         type:
-          (element.type as ExcalidrawElement["type"] | "draw") === "draw"
+          (element.type as ExcalidrawElementType | "draw") === "draw"
             ? "line"
             : element.type,
         startBinding: repairBinding(element.startBinding),
@@ -289,15 +286,15 @@ const restoreElement = (
 
     // generic elements
     case "ellipse":
-      return restoreElementWithProperties(element, {});
     case "rectangle":
-      return restoreElementWithProperties(element, {});
     case "diamond":
+    case "iframe":
       return restoreElementWithProperties(element, {});
     case "embeddable":
       return restoreElementWithProperties(element, {
         validated: null,
       });
+    case "magicframe":
     case "frame":
       return restoreElementWithProperties(element, {
         name: element.name ?? null,
@@ -464,7 +461,7 @@ export const restoreElements = (
     }
   }
 
-  return restoredElements;
+  return restoreFractionalIndicies(restoredElements) as ExcalidrawElement[];
 };
 
 const coalesceAppStateValue = <

src/data/transform.ts

@@ -15,6 +15,7 @@ import {
   ElementConstructorOpts,
   newFrameElement,
   newImageElement,
+  newMagicFrameElement,
   newTextElement,
 } from "../element/newElement";
 import {
@@ -26,12 +27,13 @@ import {
   ExcalidrawArrowElement,
   ExcalidrawBindableElement,
   ExcalidrawElement,
-  ExcalidrawEmbeddableElement,
   ExcalidrawFrameElement,
   ExcalidrawFreeDrawElement,
   ExcalidrawGenericElement,
+  ExcalidrawIframeLikeElement,
   ExcalidrawImageElement,
   ExcalidrawLinearElement,
+  ExcalidrawMagicFrameElement,
   ExcalidrawSelectionElement,
   ExcalidrawTextElement,
   FileId,
@@ -61,7 +63,12 @@ export type ValidLinearElement = {
             | {
                 type: Exclude<
                   ExcalidrawBindableElement["type"],
-                  "image" | "text" | "frame" | "embeddable"
+                  | "image"
+                  | "text"
+                  | "frame"
+                  | "magicframe"
+                  | "embeddable"
+                  | "iframe"
                 >;
                 id?: ExcalidrawGenericElement["id"];
               }
@@ -69,7 +76,12 @@ export type ValidLinearElement = {
                 id: ExcalidrawGenericElement["id"];
                 type?: Exclude<
                   ExcalidrawBindableElement["type"],
-                  "image" | "text" | "frame" | "embeddable"
+                  | "image"
+                  | "text"
+                  | "frame"
+                  | "magicframe"
+                  | "embeddable"
+                  | "iframe"
                 >;
               }
           )
@@ -93,7 +105,12 @@ export type ValidLinearElement = {
             | {
                 type: Exclude<
                   ExcalidrawBindableElement["type"],
-                  "image" | "text" | "frame" | "embeddable"
+                  | "image"
+                  | "text"
+                  | "frame"
+                  | "magicframe"
+                  | "embeddable"
+                  | "iframe"
                 >;
                 id?: ExcalidrawGenericElement["id"];
               }
@@ -101,7 +118,12 @@ export type ValidLinearElement = {
                 id: ExcalidrawGenericElement["id"];
                 type?: Exclude<
                   ExcalidrawBindableElement["type"],
-                  "image" | "text" | "frame" | "embeddable"
+                  | "image"
+                  | "text"
+                  | "frame"
+                  | "magicframe"
+                  | "embeddable"
+                  | "iframe"
                 >;
               }
           )
@@ -137,7 +159,7 @@ export type ValidContainer =
 export type ExcalidrawElementSkeleton =
   | Extract<
       Exclude<ExcalidrawElement, ExcalidrawSelectionElement>,
-      ExcalidrawEmbeddableElement | ExcalidrawFreeDrawElement
+      ExcalidrawIframeLikeElement | ExcalidrawFreeDrawElement
     >
   | ({
       type: Extract<ExcalidrawLinearElement["type"], "line">;
@@ -163,7 +185,12 @@ export type ExcalidrawElementSkeleton =
       type: "frame";
       children: readonly ExcalidrawElement["id"][];
       name?: string;
-    } & Partial<ExcalidrawFrameElement>);
+    } & Partial<ExcalidrawFrameElement>)
+  | ({
+      type: "magicframe";
+      children: readonly ExcalidrawElement["id"][];
+      name?: string;
+    } & Partial<ExcalidrawMagicFrameElement>);
 
 const DEFAULT_LINEAR_ELEMENT_PROPS = {
   width: 100,
@@ -547,7 +574,16 @@ export const convertToExcalidrawElements = (
         });
         break;
       }
+      case "magicframe": {
+        excalidrawElement = newMagicFrameElement({
+          x: 0,
+          y: 0,
+          ...element,
+        });
+        break;
+      }
       case "freedraw":
+      case "iframe":
       case "embeddable": {
         excalidrawElement = element;
         break;
@@ -656,7 +692,7 @@ export const convertToExcalidrawElements = (
   // need to calculate coordinates and dimensions of frame which is possibe after all
   // frame children are processed.
   for (const [id, element] of elementsWithIds) {
-    if (element.type !== "frame") {
+    if (element.type !== "frame" && element.type !== "magicframe") {
       continue;
     }
     const frame = elementStore.getElement(id);

src/element/ElementCanvasButtons.scss

@@ -0,0 +1,14 @@
+.excalidraw {
+  .excalidraw-canvas-buttons {
+    position: absolute;
+
+    box-shadow: 0px 2px 4px 0 rgb(0 0 0 / 30%);
+    z-index: var(--zIndex-canvasButtons);
+    background: var(--island-bg-color);
+    border-radius: var(--border-radius-lg);
+
+    display: flex;
+    flex-direction: column;
+    gap: 0.375rem;
+  }
+}

src/element/ElementCanvasButtons.tsx

@@ -0,0 +1,60 @@
+import { AppState } from "../types";
+import { sceneCoordsToViewportCoords } from "../utils";
+import { NonDeletedExcalidrawElement } from "./types";
+import { getElementAbsoluteCoords } from ".";
+import { useExcalidrawAppState } from "../components/App";
+
+import "./ElementCanvasButtons.scss";
+
+const CONTAINER_PADDING = 5;
+
+const getContainerCoords = (
+  element: NonDeletedExcalidrawElement,
+  appState: AppState,
+) => {
+  const [x1, y1] = getElementAbsoluteCoords(element);
+  const { x: viewportX, y: viewportY } = sceneCoordsToViewportCoords(
+    { sceneX: x1 + element.width, sceneY: y1 },
+    appState,
+  );
+  const x = viewportX - appState.offsetLeft + 10;
+  const y = viewportY - appState.offsetTop;
+  return { x, y };
+};
+
+export const ElementCanvasButtons = ({
+  children,
+  element,
+}: {
+  children: React.ReactNode;
+  element: NonDeletedExcalidrawElement;
+}) => {
+  const appState = useExcalidrawAppState();
+
+  if (
+    appState.contextMenu ||
+    appState.draggingElement ||
+    appState.resizingElement ||
+    appState.isRotating ||
+    appState.openMenu ||
+    appState.viewModeEnabled
+  ) {
+    return null;
+  }
+
+  const { x, y } = getContainerCoords(element, appState);
+
+  return (
+    <div
+      className="excalidraw-canvas-buttons"
+      style={{
+        top: `${y}px`,
+        left: `${x}px`,
+        // width: CONTAINER_WIDTH,
+        padding: CONTAINER_PADDING,
+      }}
+    >
+      {children}
+    </div>
+  );
+};

src/element/Hyperlink.scss

@@ -6,7 +6,7 @@
   justify-content: space-between;
   position: absolute;
   box-shadow: 0px 2px 4px 0 rgb(0 0 0 / 30%);
-  z-index: 100;
+  z-index: var(--zIndex-hyperlinkContainer);
   background: var(--island-bg-color);
   border-radius: var(--border-radius-md);
   box-sizing: border-box;

src/element/Hyperlink.tsx

@@ -40,6 +40,7 @@ import { trackEvent } from "../analytics";
 import { useAppProps, useExcalidrawAppState } from "../components/App";
 import { isEmbeddableElement } from "./typeChecks";
 import { ShapeCache } from "../scene/ShapeCache";
+import { StoreAction } from "../actions/types";
 
 const CONTAINER_WIDTH = 320;
 const SPACE_BOTTOM = 85;
@@ -121,7 +122,7 @@ export const Hyperlink = ({
           setToast({ message: embedLink.warning, closable: true });
         }
         const ar = embedLink
-          ? embedLink.aspectRatio.w / embedLink.aspectRatio.h
+          ? embedLink.intrinsicSize.w / embedLink.intrinsicSize.h
           : 1;
         const hasLinkChanged =
           embeddableLinkCache.get(element.id) !== element.link;
@@ -210,6 +211,7 @@ export const Hyperlink = ({
   };
   const { x, y } = getCoordsForPopover(element, appState);
   if (
+    appState.contextMenu ||
     appState.draggingElement ||
     appState.resizingElement ||
     appState.isRotating ||
@@ -342,7 +344,7 @@ export const actionLink = register({
         showHyperlinkPopup: "editor",
         openMenu: null,
       },
-      commitToHistory: true,
+      storeAction: StoreAction.CAPTURE,
     };
   },
   trackEvent: { category: "hyperlink", action: "click" },

src/element/collision.ts

@@ -18,7 +18,6 @@ import {
   ExcalidrawBindableElement,
   ExcalidrawElement,
   ExcalidrawRectangleElement,
-  ExcalidrawEmbeddableElement,
   ExcalidrawDiamondElement,
   ExcalidrawTextElement,
   ExcalidrawEllipseElement,
@@ -27,7 +26,8 @@ import {
   ExcalidrawImageElement,
   ExcalidrawLinearElement,
   StrokeRoundness,
-  ExcalidrawFrameElement,
+  ExcalidrawFrameLikeElement,
+  ExcalidrawIframeLikeElement,
 } from "./types";
 
 import {
@@ -41,7 +41,8 @@ import { Drawable } from "roughjs/bin/core";
 import { AppState } from "../types";
 import {
   hasBoundTextElement,
-  isEmbeddableElement,
+  isFrameLikeElement,
+  isIframeLikeElement,
   isImageElement,
 } from "./typeChecks";
 import { isTextElement } from ".";
@@ -64,7 +65,7 @@ const isElementDraggableFromInside = (
   const isDraggableFromInside =
     !isTransparent(element.backgroundColor) ||
     hasBoundTextElement(element) ||
-    isEmbeddableElement(element);
+    isIframeLikeElement(element);
   if (element.type === "line") {
     return isDraggableFromInside && isPathALoop(element.points);
   }
@@ -186,7 +187,7 @@ export const isPointHittingElementBoundingBox = (
   // by its frame, whether it has been selected or not
   // this logic here is not ideal
   // TODO: refactor it later...
-  if (element.type === "frame") {
+  if (isFrameLikeElement(element)) {
     return hitTestPointAgainstElement({
       element,
       point: [x, y],
@@ -255,6 +256,7 @@ type HitTestArgs = {
 const hitTestPointAgainstElement = (args: HitTestArgs): boolean => {
   switch (args.element.type) {
     case "rectangle":
+    case "iframe":
     case "embeddable":
     case "image":
     case "text":
@@ -282,7 +284,8 @@ const hitTestPointAgainstElement = (args: HitTestArgs): boolean => {
         "This should not happen, we need to investigate why it does.",
       );
       return false;
-    case "frame": {
+    case "frame":
+    case "magicframe": {
       // check distance to frame element first
       if (
         args.check(
@@ -314,8 +317,10 @@ export const distanceToBindableElement = (
     case "rectangle":
     case "image":
     case "text":
+    case "iframe":
     case "embeddable":
     case "frame":
+    case "magicframe":
       return distanceToRectangle(element, point);
     case "diamond":
       return distanceToDiamond(element, point);
@@ -346,8 +351,8 @@ const distanceToRectangle = (
     | ExcalidrawTextElement
     | ExcalidrawFreeDrawElement
     | ExcalidrawImageElement
-    | ExcalidrawEmbeddableElement
-    | ExcalidrawFrameElement,
+    | ExcalidrawIframeLikeElement
+    | ExcalidrawFrameLikeElement,
   point: Point,
 ): number => {
   const [, pointRel, hwidth, hheight] = pointRelativeToElement(element, point);
@@ -662,8 +667,10 @@ export const determineFocusDistance = (
     case "rectangle":
     case "image":
     case "text":
+    case "iframe":
     case "embeddable":
     case "frame":
+    case "magicframe":
       ret = c / (hwidth * (nabs + q * mabs));
       break;
     case "diamond":
@@ -700,8 +707,10 @@ export const determineFocusPoint = (
     case "image":
     case "text":
     case "diamond":
+    case "iframe":
     case "embeddable":
     case "frame":
+    case "magicframe":
       point = findFocusPointForRectangulars(element, focus, adjecentPointRel);
       break;
     case "ellipse":
@@ -752,8 +761,10 @@ const getSortedElementLineIntersections = (
     case "image":
     case "text":
     case "diamond":
+    case "iframe":
     case "embeddable":
     case "frame":
+    case "magicframe":
       const corners = getCorners(element);
       intersections = corners
         .flatMap((point, i) => {
@@ -788,8 +799,8 @@ const getCorners = (
     | ExcalidrawImageElement
     | ExcalidrawDiamondElement
     | ExcalidrawTextElement
-    | ExcalidrawEmbeddableElement
-    | ExcalidrawFrameElement,
+    | ExcalidrawIframeLikeElement
+    | ExcalidrawFrameLikeElement,
   scale: number = 1,
 ): GA.Point[] => {
   const hx = (scale * element.width) / 2;
@@ -798,8 +809,10 @@ const getCorners = (
     case "rectangle":
     case "image":
     case "text":
+    case "iframe":
     case "embeddable":
     case "frame":
+    case "magicframe":
       return [
         GA.point(hx, hy),
         GA.point(hx, -hy),
@@ -948,8 +961,8 @@ export const findFocusPointForRectangulars = (
     | ExcalidrawImageElement
     | ExcalidrawDiamondElement
     | ExcalidrawTextElement
-    | ExcalidrawEmbeddableElement
-    | ExcalidrawFrameElement,
+    | ExcalidrawIframeLikeElement
+    | ExcalidrawFrameLikeElement,
   // Between -1 and 1 for how far away should the focus point be relative
   // to the size of the element. Sign determines orientation.
   relativeDistance: number,

src/element/dragElements.ts

@@ -11,7 +11,7 @@ import Scene from "../scene/Scene";
 import {
   isArrowElement,
   isBoundToContainer,
-  isFrameElement,
+  isFrameLikeElement,
 } from "./typeChecks";
 
 export const dragSelectedElements = (
@@ -33,7 +33,7 @@ export const dragSelectedElements = (
     selectedElements,
   );
   const frames = selectedElements
-    .filter((e) => isFrameElement(e))
+    .filter((e) => isFrameLikeElement(e))
     .map((f) => f.id);
 
   if (frames.length > 0) {

src/element/embeddable.ts

@@ -6,25 +6,20 @@ import { getFontString, updateActiveTool } from "../utils";
 import { setCursorForShape } from "../cursor";
 import { newTextElement } from "./newElement";
 import { getContainerElement, wrapText } from "./textElement";
-import { isEmbeddableElement } from "./typeChecks";
+import {
+  isFrameLikeElement,
+  isIframeElement,
+  isIframeLikeElement,
+} from "./typeChecks";
 import {
   ExcalidrawElement,
-  ExcalidrawEmbeddableElement,
+  ExcalidrawIframeLikeElement,
+  IframeData,
   NonDeletedExcalidrawElement,
-  Theme,
 } from "./types";
+import { StoreAction } from "../actions/types";
 
-type EmbeddedLink =
-  | ({
-      aspectRatio: { w: number; h: number };
-      warning?: string;
-    } & (
-      | { type: "video" | "generic"; link: string }
-      | { type: "document"; srcdoc: (theme: Theme) => string }
-    ))
-  | null;
-
-const embeddedLinkCache = new Map<string, EmbeddedLink>();
+const embeddedLinkCache = new Map<string, IframeData>();
 
 const RE_YOUTUBE =
   /^(?:http(?:s)?:\/\/)?(?:www\.)?youtu(?:be\.com|\.be)\/(embed\/|watch\?v=|shorts\/|playlist\?list=|embed\/videoseries\?list=)?([a-zA-Z0-9_-]+)(?:\?t=|&t=|\?start=|&start=)?([a-zA-Z0-9_-]+)?[^\s]*$/;
@@ -67,11 +62,13 @@ const ALLOWED_DOMAINS = new Set([
   "dddice.com",
 ]);
 
-const createSrcDoc = (body: string) => {
+export const createSrcDoc = (body: string) => {
   return `<html><body>${body}</body></html>`;
 };
 
-export const getEmbedLink = (link: string | null | undefined): EmbeddedLink => {
+export const getEmbedLink = (
+  link: string | null | undefined,
+): IframeData | null => {
   if (!link) {
     return null;
   }
@@ -104,8 +101,12 @@ export const getEmbedLink = (link: string | null | undefined): EmbeddedLink => {
         break;
     }
     aspectRatio = isPortrait ? { w: 315, h: 560 } : { w: 560, h: 315 };
-    embeddedLinkCache.set(originalLink, { link, aspectRatio, type });
-    return { link, aspectRatio, type };
+    embeddedLinkCache.set(originalLink, {
+      link,
+      intrinsicSize: aspectRatio,
+      type,
+    });
+    return { link, intrinsicSize: aspectRatio, type };
   }
 
   const vimeoLink = link.match(RE_VIMEO);
@@ -119,8 +120,12 @@ export const getEmbedLink = (link: string | null | undefined): EmbeddedLink => {
     aspectRatio = { w: 560, h: 315 };
     //warning deliberately ommited so it is displayed only once per link
     //same link next time will be served from cache
-    embeddedLinkCache.set(originalLink, { link, aspectRatio, type });
-    return { link, aspectRatio, type, warning };
+    embeddedLinkCache.set(originalLink, {
+      link,
+      intrinsicSize: aspectRatio,
+      type,
+    });
+    return { link, intrinsicSize: aspectRatio, type, warning };
   }
 
   const figmaLink = link.match(RE_FIGMA);
@@ -130,27 +135,35 @@ export const getEmbedLink = (link: string | null | undefined): EmbeddedLink => {
       link,
     )}`;
     aspectRatio = { w: 550, h: 550 };
-    embeddedLinkCache.set(originalLink, { link, aspectRatio, type });
-    return { link, aspectRatio, type };
+    embeddedLinkCache.set(originalLink, {
+      link,
+      intrinsicSize: aspectRatio,
+      type,
+    });
+    return { link, intrinsicSize: aspectRatio, type };
   }
 
   const valLink = link.match(RE_VALTOWN);
   if (valLink) {
     link =
       valLink[1] === "embed" ? valLink[0] : valLink[0].replace("/v", "/embed");
-    embeddedLinkCache.set(originalLink, { link, aspectRatio, type });
-    return { link, aspectRatio, type };
+    embeddedLinkCache.set(originalLink, {
+      link,
+      intrinsicSize: aspectRatio,
+      type,
+    });
+    return { link, intrinsicSize: aspectRatio, type };
   }
 
   if (RE_TWITTER.test(link)) {
-    let ret: EmbeddedLink;
+    let ret: IframeData;
     // assume embed code
     if (/<blockquote/.test(link)) {
       const srcDoc = createSrcDoc(link);
       ret = {
         type: "document",
         srcdoc: () => srcDoc,
-        aspectRatio: { w: 480, h: 480 },
+        intrinsicSize: { w: 480, h: 480 },
       };
       // assume regular tweet url
     } else {
@@ -160,7 +173,7 @@ export const getEmbedLink = (link: string | null | undefined): EmbeddedLink => {
           createSrcDoc(
             `<blockquote class="twitter-tweet" data-dnt="true" data-theme="${theme}"><a href="${link}"></a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>`,
           ),
-        aspectRatio: { w: 480, h: 480 },
+        intrinsicSize: { w: 480, h: 480 },
       };
     }
     embeddedLinkCache.set(originalLink, ret);
@@ -168,14 +181,14 @@ export const getEmbedLink = (link: string | null | undefined): EmbeddedLink => {
   }
 
   if (RE_GH_GIST.test(link)) {
-    let ret: EmbeddedLink;
+    let ret: IframeData;
     // assume embed code
     if (/<script>/.test(link)) {
       const srcDoc = createSrcDoc(link);
       ret = {
         type: "document",
         srcdoc: () => srcDoc,
-        aspectRatio: { w: 550, h: 720 },
+        intrinsicSize: { w: 550, h: 720 },
       };
       // assume regular url
     } else {
@@ -190,26 +203,26 @@ export const getEmbedLink = (link: string | null | undefined): EmbeddedLink => {
             .gist .gist-file { height: calc(100vh - 2px); padding: 0px; display: grid; grid-template-rows: 1fr auto; }
           </style>
         `),
-        aspectRatio: { w: 550, h: 720 },
+        intrinsicSize: { w: 550, h: 720 },
       };
     }
     embeddedLinkCache.set(link, ret);
     return ret;
   }
 
-  embeddedLinkCache.set(link, { link, aspectRatio, type });
-  return { link, aspectRatio, type };
+  embeddedLinkCache.set(link, { link, intrinsicSize: aspectRatio, type });
+  return { link, intrinsicSize: aspectRatio, type };
 };
 
-export const isEmbeddableOrLabel = (
+export const isIframeLikeOrItsLabel = (
   element: NonDeletedExcalidrawElement,
 ): Boolean => {
-  if (isEmbeddableElement(element)) {
+  if (isIframeLikeElement(element)) {
     return true;
   }
   if (element.type === "text") {
     const container = getContainerElement(element);
-    if (container && isEmbeddableElement(container)) {
+    if (container && isFrameLikeElement(container)) {
       return true;
     }
   }
@@ -217,10 +230,16 @@ export const isEmbeddableOrLabel = (
 };
 
 export const createPlaceholderEmbeddableLabel = (
-  element: ExcalidrawEmbeddableElement,
+  element: ExcalidrawIframeLikeElement,
 ): ExcalidrawElement => {
-  const text =
-    !element.link || element?.link === "" ? "Empty Web-Embed" : element.link;
+  let text: string;
+  if (isIframeElement(element)) {
+    text = "IFrame element";
+  } else {
+    text =
+      !element.link || element?.link === "" ? "Empty Web-Embed" : element.link;
+  }
+
   const fontSize = Math.max(
     Math.min(element.width / 2, element.width / text.length),
     element.width / 30,
@@ -268,7 +287,8 @@ export const actionSetEmbeddableAsActiveTool = register({
           type: "embeddable",
         }),
       },
-      commitToHistory: false,
+      storeAction: StoreAction.NONE,
+
     };
   },
 });

src/element/index.ts

@@ -2,7 +2,6 @@ import {
   ExcalidrawElement,
   NonDeletedExcalidrawElement,
   NonDeleted,
-  ExcalidrawFrameElement,
 } from "./types";
 import { isInvisiblySmallElement } from "./sizeHelpers";
 import { isLinearElementType } from "./typeChecks";
@@ -50,11 +49,7 @@ export {
   getDragOffsetXY,
   dragNewElement,
 } from "./dragElements";
-export {
-  isTextElement,
-  isExcalidrawElement,
-  isFrameElement,
-} from "./typeChecks";
+export { isTextElement, isExcalidrawElement } from "./typeChecks";
 export { textWysiwyg } from "./textWysiwyg";
 export { redrawTextBoundingBox } from "./textElement";
 export {
@@ -74,17 +69,10 @@ export const getVisibleElements = (elements: readonly ExcalidrawElement[]) =>
     (el) => !el.isDeleted && !isInvisiblySmallElement(el),
   ) as readonly NonDeletedExcalidrawElement[];
 
-export const getNonDeletedElements = (elements: readonly ExcalidrawElement[]) =>
-  elements.filter(
-    (element) => !element.isDeleted,
-  ) as readonly NonDeletedExcalidrawElement[];
-
-export const getNonDeletedFrames = (
-  frames: readonly ExcalidrawFrameElement[],
+export const getNonDeletedElements = <T extends ExcalidrawElement>(
+  elements: readonly T[],
 ) =>
-  frames.filter(
-    (frame) => !frame.isDeleted,
-  ) as readonly NonDeleted<ExcalidrawFrameElement>[];
+  elements.filter((element) => !element.isDeleted) as readonly NonDeleted<T>[];
 
 export const isNonDeletedElement = <T extends ExcalidrawElement>(
   element: T,

src/element/linearElementEditor.ts

@@ -33,7 +33,6 @@ import {
   InteractiveCanvasAppState,
 } from "../types";
 import { mutateElement } from "./mutateElement";
-import History from "../history";
 
 import Scene from "../scene/Scene";
 import {
@@ -48,6 +47,7 @@ import { getBoundTextElement, handleBindTextResize } from "./textElement";
 import { DRAGGING_THRESHOLD } from "../constants";
 import { Mutable } from "../utility-types";
 import { ShapeCache } from "../scene/ShapeCache";
+import { Store } from "../store";
 
 const editorMidPointsCache: {
   version: number | null;
@@ -602,7 +602,7 @@ export class LinearElementEditor {
   static handlePointerDown(
     event: React.PointerEvent<HTMLElement>,
     appState: AppState,
-    history: History,
+    store: Store,
     scenePointer: { x: number; y: number },
     linearElementEditor: LinearElementEditor,
   ): {
@@ -654,7 +654,7 @@ export class LinearElementEditor {
         });
         ret.didAddPoint = true;
       }
-      history.resumeRecording();
+      store.resumeCapturing();
       ret.linearElementEditor = {
         ...linearElementEditor,
         pointerDownState: {

src/element/mutateElement.ts

@@ -106,24 +106,27 @@ export const mutateElement = <TElement extends Mutable<ExcalidrawElement>>(
 export const newElementWith = <TElement extends ExcalidrawElement>(
   element: TElement,
   updates: ElementUpdate<TElement>,
+  forceUpdate: boolean = false,
 ): TElement => {
-  let didChange = false;
-  for (const key in updates) {
-    const value = (updates as any)[key];
-    if (typeof value !== "undefined") {
-      if (
-        (element as any)[key] === value &&
-        // if object, always update because its attrs could have changed
-        (typeof value !== "object" || value === null)
-      ) {
-        continue;
+  if (!forceUpdate) {
+    let didChange = false;
+    for (const key in updates) {
+      const value = (updates as any)[key];
+      if (typeof value !== "undefined") {
+        if (
+          (element as any)[key] === value &&
+          // if object, always update because its attrs could have changed
+          (typeof value !== "object" || value === null)
+        ) {
+          continue;
+        }
+        didChange = true;
       }
-      didChange = true;
     }
-  }
 
-  if (!didChange) {
-    return element;
+    if (!didChange) {
+      return element;
+    }
   }
 
   return {

src/element/newElement.ts

@@ -14,6 +14,8 @@ import {
   ExcalidrawTextContainer,
   ExcalidrawFrameElement,
   ExcalidrawEmbeddableElement,
+  ExcalidrawMagicFrameElement,
+  ExcalidrawIframeElement,
 } from "../element/types";
 import {
   arrayToMap,
@@ -53,6 +55,7 @@ export type ElementConstructorOpts = MarkOptional<
   | "angle"
   | "groupIds"
   | "frameId"
+  | "fractionalIndex"
   | "boundElements"
   | "seed"
   | "version"
@@ -86,6 +89,8 @@ const _newElementBase = <T extends ExcalidrawElement>(
     angle = 0,
     groupIds = [],
     frameId = null,
+    // TODO: think about this more
+    fractionalIndex = null,
     roundness = null,
     boundElements = null,
     link = null,
@@ -111,6 +116,7 @@ const _newElementBase = <T extends ExcalidrawElement>(
     opacity,
     groupIds,
     frameId,
+    fractionalIndex,
     roundness,
     seed: rest.seed ?? randomInteger(),
     version: rest.version || 1,
@@ -143,6 +149,16 @@ export const newEmbeddableElement = (
   };
 };
 
+export const newIframeElement = (
+  opts: {
+    type: "iframe";
+  } & ElementConstructorOpts,
+): NonDeleted<ExcalidrawIframeElement> => {
+  return {
+    ..._newElementBase<ExcalidrawIframeElement>("iframe", opts),
+  };
+};
+
 export const newFrameElement = (
   opts: {
     name?: string;
@@ -160,6 +176,23 @@ export const newFrameElement = (
   return frameElement;
 };
 
+export const newMagicFrameElement = (
+  opts: {
+    name?: string;
+  } & ElementConstructorOpts,
+): NonDeleted<ExcalidrawMagicFrameElement> => {
+  const frameElement = newElementWith(
+    {
+      ..._newElementBase<ExcalidrawMagicFrameElement>("magicframe", opts),
+      type: "magicframe",
+      name: opts?.name || null,
+    },
+    {},
+  );
+
+  return frameElement;
+};
+
 /** computes element x/y offset based on textAlign/verticalAlign */
 const getTextElementPositionOffsets = (
   opts: {

src/element/resizeElements.ts

@@ -27,7 +27,7 @@ import {
 import {
   isArrowElement,
   isBoundToContainer,
-  isFrameElement,
+  isFrameLikeElement,
   isFreeDrawElement,
   isImageElement,
   isLinearElement,
@@ -163,7 +163,7 @@ const rotateSingleElement = (
   const cx = (x1 + x2) / 2;
   const cy = (y1 + y2) / 2;
   let angle: number;
-  if (isFrameElement(element)) {
+  if (isFrameLikeElement(element)) {
     angle = 0;
   } else {
     angle = (5 * Math.PI) / 2 + Math.atan2(pointerY - cy, pointerX - cx);
@@ -900,7 +900,7 @@ const rotateMultipleElements = (
   }
 
   elements
-    .filter((element) => element.type !== "frame")
+    .filter((element) => !isFrameLikeElement(element))
     .forEach((element) => {
       const [x1, y1, x2, y2] = getElementAbsoluteCoords(element);
       const cx = (x1 + x2) / 2;

src/element/textElement.ts

@@ -1,6 +1,7 @@
 import { getFontString, arrayToMap, isTestEnv } from "../utils";
 import {
   ExcalidrawElement,
+  ExcalidrawElementType,
   ExcalidrawTextContainer,
   ExcalidrawTextElement,
   ExcalidrawTextElementWithContainer,
@@ -867,7 +868,7 @@ const VALID_CONTAINER_TYPES = new Set([
 ]);
 
 export const isValidTextContainer = (element: {
-  type: ExcalidrawElement["type"];
+  type: ExcalidrawElementType;
 }) => VALID_CONTAINER_TYPES.has(element.type);
 
 export const computeContainerDimensionForBoundText = (

src/element/transformHandles.ts

@@ -8,7 +8,7 @@ import { Bounds, getElementAbsoluteCoords } from "./bounds";
 import { rotate } from "../math";
 import { InteractiveCanvasAppState, Zoom } from "../types";
 import { isTextElement } from ".";
-import { isFrameElement, isLinearElement } from "./typeChecks";
+import { isFrameLikeElement, isLinearElement } from "./typeChecks";
 import { DEFAULT_SPACING } from "../renderer/renderScene";
 
 export type TransformHandleDirection =
@@ -257,7 +257,7 @@ export const getTransformHandles = (
     }
   } else if (isTextElement(element)) {
     omitSides = OMIT_SIDES_FOR_TEXT_ELEMENT;
-  } else if (isFrameElement(element)) {
+  } else if (isFrameLikeElement(element)) {
     omitSides = {
       rotation: true,
     };

src/element/typeChecks.ts

@@ -1,5 +1,5 @@
 import { ROUNDNESS } from "../constants";
-import { AppState } from "../types";
+import { ElementOrToolType } from "../types";
 import { MarkNonNullable } from "../utility-types";
 import { assertNever } from "../utils";
 import {
@@ -8,7 +8,6 @@ import {
   ExcalidrawEmbeddableElement,
   ExcalidrawLinearElement,
   ExcalidrawBindableElement,
-  ExcalidrawGenericElement,
   ExcalidrawFreeDrawElement,
   InitializedExcalidrawImageElement,
   ExcalidrawImageElement,
@@ -16,21 +15,13 @@ import {
   ExcalidrawTextContainer,
   ExcalidrawFrameElement,
   RoundnessType,
+  ExcalidrawFrameLikeElement,
+  ExcalidrawElementType,
+  ExcalidrawIframeElement,
+  ExcalidrawIframeLikeElement,
+  ExcalidrawMagicFrameElement,
 } from "./types";
 
-export const isGenericElement = (
-  element: ExcalidrawElement | null,
-): element is ExcalidrawGenericElement => {
-  return (
-    element != null &&
-    (element.type === "selection" ||
-      element.type === "rectangle" ||
-      element.type === "diamond" ||
-      element.type === "ellipse" ||
-      element.type === "embeddable")
-  );
-};
-
 export const isInitializedImageElement = (
   element: ExcalidrawElement | null,
 ): element is InitializedExcalidrawImageElement => {
@@ -49,6 +40,20 @@ export const isEmbeddableElement = (
   return !!element && element.type === "embeddable";
 };
 
+export const isIframeElement = (
+  element: ExcalidrawElement | null,
+): element is ExcalidrawIframeElement => {
+  return !!element && element.type === "iframe";
+};
+
+export const isIframeLikeElement = (
+  element: ExcalidrawElement | null,
+): element is ExcalidrawIframeLikeElement => {
+  return (
+    !!element && (element.type === "iframe" || element.type === "embeddable")
+  );
+};
+
 export const isTextElement = (
   element: ExcalidrawElement | null,
 ): element is ExcalidrawTextElement => {
@@ -61,6 +66,21 @@ export const isFrameElement = (
   return element != null && element.type === "frame";
 };
 
+export const isMagicFrameElement = (
+  element: ExcalidrawElement | null,
+): element is ExcalidrawMagicFrameElement => {
+  return element != null && element.type === "magicframe";
+};
+
+export const isFrameLikeElement = (
+  element: ExcalidrawElement | null,
+): element is ExcalidrawFrameLikeElement => {
+  return (
+    element != null &&
+    (element.type === "frame" || element.type === "magicframe")
+  );
+};
+
 export const isFreeDrawElement = (
   element?: ExcalidrawElement | null,
 ): element is ExcalidrawFreeDrawElement => {
@@ -68,7 +88,7 @@ export const isFreeDrawElement = (
 };
 
 export const isFreeDrawElementType = (
-  elementType: ExcalidrawElement["type"],
+  elementType: ExcalidrawElementType,
 ): boolean => {
   return elementType === "freedraw";
 };
@@ -86,7 +106,7 @@ export const isArrowElement = (
 };
 
 export const isLinearElementType = (
-  elementType: AppState["activeTool"]["type"],
+  elementType: ElementOrToolType,
 ): boolean => {
   return (
     elementType === "arrow" || elementType === "line" // || elementType === "freedraw"
@@ -105,7 +125,7 @@ export const isBindingElement = (
 };
 
 export const isBindingElementType = (
-  elementType: AppState["activeTool"]["type"],
+  elementType: ElementOrToolType,
 ): boolean => {
   return elementType === "arrow";
 };
@@ -121,8 +141,10 @@ export const isBindableElement = (
       element.type === "diamond" ||
       element.type === "ellipse" ||
       element.type === "image" ||
+      element.type === "iframe" ||
       element.type === "embeddable" ||
       element.type === "frame" ||
+      element.type === "magicframe" ||
       (element.type === "text" && !element.containerId))
   );
 };
@@ -144,7 +166,7 @@ export const isTextBindableContainer = (
 export const isExcalidrawElement = (
   element: any,
 ): element is ExcalidrawElement => {
-  const type: ExcalidrawElement["type"] | undefined = element?.type;
+  const type: ExcalidrawElementType | undefined = element?.type;
   if (!type) {
     return false;
   }
@@ -152,12 +174,14 @@ export const isExcalidrawElement = (
     case "text":
     case "diamond":
     case "rectangle":
+    case "iframe":
     case "embeddable":
     case "ellipse":
     case "arrow":
     case "freedraw":
     case "line":
     case "frame":
+    case "magicframe":
     case "image":
     case "selection": {
       return true;
@@ -190,7 +214,7 @@ export const isBoundToContainer = (
 };
 
 export const isUsingAdaptiveRadius = (type: string) =>
-  type === "rectangle" || type === "embeddable";
+  type === "rectangle" || type === "embeddable" || type === "iframe";
 
 export const isUsingProportionalRadius = (type: string) =>
   type === "line" || type === "arrow" || type === "diamond";

src/element/types.ts

@@ -7,6 +7,7 @@ import {
   VERTICAL_ALIGN,
 } from "../constants";
 import { MarkNonNullable, ValueOf } from "../utility-types";
+import { MagicCacheData } from "../data/magic";
 
 export type ChartType = "bar" | "line";
 export type FillStyle = "hachure" | "cross-hatch" | "solid" | "zigzag";
@@ -49,6 +50,7 @@ type _ExcalidrawElementBase = Readonly<{
       Used for deterministic reconciliation of updates during collaboration,
       in case the versions (see above) are identical. */
   versionNonce: number;
+  fractionalIndex: string | null;
   isDeleted: boolean;
   /** List of groups the element belongs to.
       Ordered from deepest to shallowest. */
@@ -97,6 +99,26 @@ export type ExcalidrawEmbeddableElement = _ExcalidrawElementBase &
     validated: boolean | null;
   }>;
 
+export type ExcalidrawIframeElement = _ExcalidrawElementBase &
+  Readonly<{
+    type: "iframe";
+    // TODO move later to AI-specific frame
+    customData?: { generationData?: MagicCacheData };
+  }>;
+
+export type ExcalidrawIframeLikeElement =
+  | ExcalidrawIframeElement
+  | ExcalidrawEmbeddableElement;
+
+export type IframeData =
+  | {
+      intrinsicSize: { w: number; h: number };
+      warning?: string;
+    } & (
+      | { type: "video" | "generic"; link: string }
+      | { type: "document"; srcdoc: (theme: Theme) => string }
+    );
+
 export type ExcalidrawImageElement = _ExcalidrawElementBase &
   Readonly<{
     type: "image";
@@ -117,6 +139,15 @@ export type ExcalidrawFrameElement = _ExcalidrawElementBase & {
   name: string | null;
 };
 
+export type ExcalidrawMagicFrameElement = _ExcalidrawElementBase & {
+  type: "magicframe";
+  name: string | null;
+};
+
+export type ExcalidrawFrameLikeElement =
+  | ExcalidrawFrameElement
+  | ExcalidrawMagicFrameElement;
+
 /**
  * These are elements that don't have any additional properties.
  */
@@ -138,6 +169,8 @@ export type ExcalidrawElement =
   | ExcalidrawFreeDrawElement
   | ExcalidrawImageElement
   | ExcalidrawFrameElement
+  | ExcalidrawMagicFrameElement
+  | ExcalidrawIframeElement
   | ExcalidrawEmbeddableElement;
 
 export type NonDeleted<TElement extends ExcalidrawElement> = TElement & {
@@ -170,8 +203,10 @@ export type ExcalidrawBindableElement =
   | ExcalidrawEllipseElement
   | ExcalidrawTextElement
   | ExcalidrawImageElement
+  | ExcalidrawIframeElement
   | ExcalidrawEmbeddableElement
-  | ExcalidrawFrameElement;
+  | ExcalidrawFrameElement
+  | ExcalidrawMagicFrameElement;
 
 export type ExcalidrawTextContainer =
   | ExcalidrawRectangleElement
@@ -217,3 +252,5 @@ export type ExcalidrawFreeDrawElement = _ExcalidrawElementBase &
   }>;
 
 export type FileId = string & { _brand: "FileId" };
+
+export type ExcalidrawElementType = ExcalidrawElement["type"];

src/fractionalIndex.ts

@@ -0,0 +1,227 @@
+import { mutateElement } from "./element/mutateElement";
+import { ExcalidrawElement } from "./element/types";
+import {
+  generateKeyBetween,
+  generateJitteredKeyBetween,
+  generateNKeysBetween,
+  generateNJitteredKeysBetween,
+} from "fractional-indexing-jittered";
+import { ENV } from "./constants";
+
+type FractionalIndex = ExcalidrawElement["fractionalIndex"];
+
+const isValidFractionalIndex = (
+  index: FractionalIndex,
+  predecessor: FractionalIndex,
+  successor: FractionalIndex,
+) => {
+  if (index) {
+    if (predecessor && successor) {
+      return predecessor < index && index < successor;
+    }
+
+    if (successor && !predecessor) {
+      // first element
+      return index < successor;
+    }
+
+    if (predecessor && !successor) {
+      // last element
+      return predecessor < index;
+    }
+
+    if (!predecessor && !successor) {
+      return index.length > 0;
+    }
+  }
+
+  return false;
+};
+
+const getContiguousMovedIndices = (
+  elements: readonly ExcalidrawElement[],
+  movedElementsMap: Map<string, ExcalidrawElement>,
+) => {
+  const result: number[][] = [];
+  const contiguous: number[] = [];
+
+  for (let i = 0; i < elements.length; i++) {
+    const element = elements[i];
+    if (movedElementsMap.has(element.id)) {
+      if (contiguous.length) {
+        if (contiguous[contiguous.length - 1] + 1 === i) {
+          contiguous.push(i);
+        } else {
+          result.push(contiguous.slice());
+          contiguous.length = 0;
+          contiguous.push(i);
+        }
+      } else {
+        contiguous.push(i);
+      }
+    }
+  }
+
+  if (contiguous.length > 0) {
+    result.push(contiguous.slice());
+  }
+
+  return result;
+};
+
+export const fixFractionalIndices = (
+  elements: readonly ExcalidrawElement[],
+  movedElementsMap: Map<string, ExcalidrawElement>,
+) => {
+  const contiguousMovedIndices = getContiguousMovedIndices(
+    elements,
+    movedElementsMap,
+  );
+
+  const generateFn =
+    import.meta.env.MODE === ENV.TEST
+      ? generateNKeysBetween
+      : generateNJitteredKeysBetween;
+
+  for (const movedIndices of contiguousMovedIndices) {
+    try {
+      const predecessor =
+        elements[movedIndices[0] - 1]?.fractionalIndex || null;
+      const successor =
+        elements[movedIndices[movedIndices.length - 1] + 1]?.fractionalIndex ||
+        null;
+
+      const newKeys = generateFn(predecessor, successor, movedIndices.length);
+
+      for (let i = 0; i < movedIndices.length; i++) {
+        const element = elements[movedIndices[i]];
+
+        mutateElement(
+          element,
+          {
+            fractionalIndex: newKeys[i],
+          },
+          false,
+        );
+      }
+    } catch (e) {
+      console.error("error fixing fractional indices", e);
+    }
+  }
+
+  return elements as ExcalidrawElement[];
+};
+
+const compareStrings = (a: string, b: string) => {
+  return a < b ? -1 : 1;
+};
+
+export const orderByFractionalIndex = (allElements: ExcalidrawElement[]) => {
+  return allElements.sort((a, b) => {
+    if (a.fractionalIndex && b.fractionalIndex) {
+      if (a.fractionalIndex < b.fractionalIndex) {
+        return -1;
+      } else if (a.fractionalIndex > b.fractionalIndex) {
+        return 1;
+      }
+      return compareStrings(a.id, b.id);
+    }
+
+    return 0;
+  });
+};
+
+const restoreFractionalIndex = (
+  predecessor: FractionalIndex,
+  successor: FractionalIndex,
+) => {
+  const generateFn =
+    import.meta.env.MODE === ENV.TEST
+      ? generateKeyBetween
+      : generateJitteredKeyBetween;
+
+  if (successor && !predecessor) {
+    // first element in the array
+    // insert before successor
+    return generateFn(null, successor);
+  }
+
+  if (predecessor && !successor) {
+    // last element in the array
+    // insert after predecessor
+    return generateFn(predecessor, null);
+  }
+
+  // both predecessor and successor exist (or both do not)
+  // insert after predecessor
+  return generateFn(predecessor, null);
+};
+
+/**
+ * restore the fractional indicies of the elements in the given array such that
+ * every element in the array has a fractional index smaller than its successor's
+ *
+ * neighboring indices might be updated as well
+ *
+ * only use this function when restoring or as a fallback to guarantee fractional
+ * indices consistency
+ */
+export const restoreFractionalIndicies = (
+  allElements: readonly ExcalidrawElement[],
+) => {
+  let suc = 1;
+
+  const normalized: ExcalidrawElement[] = [];
+
+  for (const element of allElements) {
+    const predecessor =
+      normalized[normalized.length - 1]?.fractionalIndex || null;
+    const successor = allElements[suc]?.fractionalIndex || null;
+
+    if (
+      !isValidFractionalIndex(element.fractionalIndex, predecessor, successor)
+    ) {
+      try {
+        const nextFractionalIndex = restoreFractionalIndex(
+          predecessor,
+          successor,
+        );
+
+        normalized.push({
+          ...element,
+          fractionalIndex: nextFractionalIndex,
+        });
+      } catch (e) {
+        normalized.push(element);
+      }
+    } else {
+      normalized.push(element);
+    }
+    suc++;
+  }
+
+  return normalized;
+};
+
+export const validateFractionalIndicies = (
+  elements: readonly ExcalidrawElement[],
+) => {
+  for (let i = 0; i < elements.length; i++) {
+    const element = elements[i];
+    const successor = elements[i + 1];
+
+    if (element.fractionalIndex) {
+      if (
+        successor &&
+        successor.fractionalIndex &&
+        element.fractionalIndex >= successor.fractionalIndex
+      ) {
+        return false;
+      }
+    } else {
+      return false;
+    }
+  }
+
+  return true;
+};

src/frame.ts

@@ -5,7 +5,7 @@ import {
 } from "./element";
 import {
   ExcalidrawElement,
-  ExcalidrawFrameElement,
+  ExcalidrawFrameLikeElement,
   NonDeleted,
   NonDeletedExcalidrawElement,
 } from "./element/types";
@@ -18,11 +18,11 @@ import { arrayToMap } from "./utils";
 import { mutateElement } from "./element/mutateElement";
 import { AppClassProperties, AppState, StaticCanvasAppState } from "./types";
 import { getElementsWithinSelection, getSelectedElements } from "./scene";
-import { isFrameElement } from "./element";
 import { getElementsInGroup, selectGroupsFromGivenElements } from "./groups";
 import Scene, { ExcalidrawElementsIncludingDeleted } from "./scene/Scene";
 import { getElementLineSegments } from "./element/bounds";
 import { doLineSegmentsIntersect } from "./packages/utils";
+import { isFrameElement, isFrameLikeElement } from "./element/typeChecks";
 
 // --------------------------- Frame State ------------------------------------
 export const bindElementsToFramesAfterDuplication = (
@@ -58,7 +58,7 @@ export const bindElementsToFramesAfterDuplication = (
 
 export function isElementIntersectingFrame(
   element: ExcalidrawElement,
-  frame: ExcalidrawFrameElement,
+  frame: ExcalidrawFrameLikeElement,
 ) {
   const frameLineSegments = getElementLineSegments(frame);
 
@@ -75,20 +75,20 @@ export function isElementIntersectingFrame(
 
 export const getElementsCompletelyInFrame = (
   elements: readonly ExcalidrawElement[],
-  frame: ExcalidrawFrameElement,
+  frame: ExcalidrawFrameLikeElement,
 ) =>
-  omitGroupsContainingFrames(
+  omitGroupsContainingFrameLikes(
     getElementsWithinSelection(elements, frame, false),
   ).filter(
     (element) =>
-      (element.type !== "frame" && !element.frameId) ||
+      (!isFrameLikeElement(element) && !element.frameId) ||
       element.frameId === frame.id,
   );
 
 export const isElementContainingFrame = (
   elements: readonly ExcalidrawElement[],
   element: ExcalidrawElement,
-  frame: ExcalidrawFrameElement,
+  frame: ExcalidrawFrameLikeElement,
 ) => {
   return getElementsWithinSelection(elements, element).some(
     (e) => e.id === frame.id,
@@ -97,12 +97,12 @@ export const isElementContainingFrame = (
 
 export const getElementsIntersectingFrame = (
   elements: readonly ExcalidrawElement[],
-  frame: ExcalidrawFrameElement,
+  frame: ExcalidrawFrameLikeElement,
 ) => elements.filter((element) => isElementIntersectingFrame(element, frame));
 
 export const elementsAreInFrameBounds = (
   elements: readonly ExcalidrawElement[],
-  frame: ExcalidrawFrameElement,
+  frame: ExcalidrawFrameLikeElement,
 ) => {
   const [selectionX1, selectionY1, selectionX2, selectionY2] =
     getElementAbsoluteCoords(frame);
@@ -120,7 +120,7 @@ export const elementsAreInFrameBounds = (
 
 export const elementOverlapsWithFrame = (
   element: ExcalidrawElement,
-  frame: ExcalidrawFrameElement,
+  frame: ExcalidrawFrameLikeElement,
 ) => {
   return (
     elementsAreInFrameBounds([element], frame) ||
@@ -134,7 +134,7 @@ export const isCursorInFrame = (
     x: number;
     y: number;
   },
-  frame: NonDeleted<ExcalidrawFrameElement>,
+  frame: NonDeleted<ExcalidrawFrameLikeElement>,
 ) => {
   const [fx1, fy1, fx2, fy2] = getElementAbsoluteCoords(frame);
 
@@ -148,7 +148,7 @@ export const isCursorInFrame = (
 export const groupsAreAtLeastIntersectingTheFrame = (
   elements: readonly NonDeletedExcalidrawElement[],
   groupIds: readonly string[],
-  frame: ExcalidrawFrameElement,
+  frame: ExcalidrawFrameLikeElement,
 ) => {
   const elementsInGroup = groupIds.flatMap((groupId) =>
     getElementsInGroup(elements, groupId),
@@ -168,7 +168,7 @@ export const groupsAreAtLeastIntersectingTheFrame = (
 export const groupsAreCompletelyOutOfFrame = (
   elements: readonly NonDeletedExcalidrawElement[],
   groupIds: readonly string[],
-  frame: ExcalidrawFrameElement,
+  frame: ExcalidrawFrameLikeElement,
 ) => {
   const elementsInGroup = groupIds.flatMap((groupId) =>
     getElementsInGroup(elements, groupId),
@@ -192,14 +192,14 @@ export const groupsAreCompletelyOutOfFrame = (
 /**
  * Returns a map of frameId to frame elements. Includes empty frames.
  */
-export const groupByFrames = (elements: readonly ExcalidrawElement[]) => {
+export const groupByFrameLikes = (elements: readonly ExcalidrawElement[]) => {
   const frameElementsMap = new Map<
     ExcalidrawElement["id"],
     ExcalidrawElement[]
   >();
 
   for (const element of elements) {
-    const frameId = isFrameElement(element) ? element.id : element.frameId;
+    const frameId = isFrameLikeElement(element) ? element.id : element.frameId;
     if (frameId && !frameElementsMap.has(frameId)) {
       frameElementsMap.set(frameId, getFrameChildren(elements, frameId));
     }
@@ -213,12 +213,12 @@ export const getFrameChildren = (
   frameId: string,
 ) => allElements.filter((element) => element.frameId === frameId);
 
-export const getFrameElements = (
+export const getFrameLikeElements = (
   allElements: ExcalidrawElementsIncludingDeleted,
-): ExcalidrawFrameElement[] => {
-  return allElements.filter((element) =>
-    isFrameElement(element),
-  ) as ExcalidrawFrameElement[];
+): ExcalidrawFrameLikeElement[] => {
+  return allElements.filter((element): element is ExcalidrawFrameLikeElement =>
+    isFrameLikeElement(element),
+  );
 };
 
 /**
@@ -232,7 +232,7 @@ export const getFrameElements = (
 export const getRootElements = (
   allElements: ExcalidrawElementsIncludingDeleted,
 ) => {
-  const frameElements = arrayToMap(getFrameElements(allElements));
+  const frameElements = arrayToMap(getFrameLikeElements(allElements));
   return allElements.filter(
     (element) =>
       frameElements.has(element.id) ||
@@ -243,7 +243,7 @@ export const getRootElements = (
 
 export const getElementsInResizingFrame = (
   allElements: ExcalidrawElementsIncludingDeleted,
-  frame: ExcalidrawFrameElement,
+  frame: ExcalidrawFrameLikeElement,
   appState: AppState,
 ): ExcalidrawElement[] => {
   const prevElementsInFrame = getFrameChildren(allElements, frame.id);
@@ -336,9 +336,9 @@ export const getElementsInResizingFrame = (
 
 export const getElementsInNewFrame = (
   allElements: ExcalidrawElementsIncludingDeleted,
-  frame: ExcalidrawFrameElement,
+  frame: ExcalidrawFrameLikeElement,
 ) => {
-  return omitGroupsContainingFrames(
+  return omitGroupsContainingFrameLikes(
     allElements,
     getElementsCompletelyInFrame(allElements, frame),
   );
@@ -356,12 +356,12 @@ export const getContainingFrame = (
   if (element.frameId) {
     if (elementsMap) {
       return (elementsMap.get(element.frameId) ||
-        null) as null | ExcalidrawFrameElement;
+        null) as null | ExcalidrawFrameLikeElement;
     }
     return (
       (Scene.getScene(element)?.getElement(
         element.frameId,
-      ) as ExcalidrawFrameElement) || null
+      ) as ExcalidrawFrameLikeElement) || null
     );
   }
   return null;
@@ -377,7 +377,7 @@ export const getContainingFrame = (
 export const addElementsToFrame = (
   allElements: ExcalidrawElementsIncludingDeleted,
   elementsToAdd: NonDeletedExcalidrawElement[],
-  frame: ExcalidrawFrameElement,
+  frame: ExcalidrawFrameLikeElement,
 ) => {
   const { currTargetFrameChildrenMap } = allElements.reduce(
     (acc, element, index) => {
@@ -397,7 +397,7 @@ export const addElementsToFrame = (
 
   // - add bound text elements if not already in the array
   // - filter out elements that are already in the frame
-  for (const element of omitGroupsContainingFrames(
+  for (const element of omitGroupsContainingFrameLikes(
     allElements,
     elementsToAdd,
   )) {
@@ -438,7 +438,7 @@ export const removeElementsFromFrame = (
   >();
 
   const toRemoveElementsByFrame = new Map<
-    ExcalidrawFrameElement["id"],
+    ExcalidrawFrameLikeElement["id"],
     ExcalidrawElement[]
   >();
 
@@ -474,7 +474,7 @@ export const removeElementsFromFrame = (
 
 export const removeAllElementsFromFrame = (
   allElements: ExcalidrawElementsIncludingDeleted,
-  frame: ExcalidrawFrameElement,
+  frame: ExcalidrawFrameLikeElement,
   appState: AppState,
 ) => {
   const elementsInFrame = getFrameChildren(allElements, frame.id);
@@ -484,7 +484,7 @@ export const removeAllElementsFromFrame = (
 export const replaceAllElementsInFrame = (
   allElements: ExcalidrawElementsIncludingDeleted,
   nextElementsInFrame: ExcalidrawElement[],
-  frame: ExcalidrawFrameElement,
+  frame: ExcalidrawFrameLikeElement,
   appState: AppState,
 ) => {
   return addElementsToFrame(
@@ -524,7 +524,7 @@ export const updateFrameMembershipOfSelectedElements = (
   elementsToFilter.forEach((element) => {
     if (
       element.frameId &&
-      !isFrameElement(element) &&
+      !isFrameLikeElement(element) &&
       !isElementInFrame(element, allElements, appState)
     ) {
       elementsToRemove.add(element);
@@ -540,7 +540,7 @@ export const updateFrameMembershipOfSelectedElements = (
  * filters out elements that are inside groups that contain a frame element
  * anywhere in the group tree
  */
-export const omitGroupsContainingFrames = (
+export const omitGroupsContainingFrameLikes = (
   allElements: ExcalidrawElementsIncludingDeleted,
   /** subset of elements you want to filter. Optional perf optimization so we
    * don't have to filter all elements unnecessarily
@@ -558,7 +558,9 @@ export const omitGroupsContainingFrames = (
   const rejectedGroupIds = new Set<string>();
   for (const groupId of uniqueGroupIds) {
     if (
-      getElementsInGroup(allElements, groupId).some((el) => isFrameElement(el))
+      getElementsInGroup(allElements, groupId).some((el) =>
+        isFrameLikeElement(el),
+      )
     ) {
       rejectedGroupIds.add(groupId);
     }
@@ -636,7 +638,7 @@ export const isElementInFrame = (
     }
 
     for (const elementInGroup of allElementsInGroup) {
-      if (isFrameElement(elementInGroup)) {
+      if (isFrameLikeElement(elementInGroup)) {
         return false;
       }
     }
@@ -650,3 +652,15 @@ export const isElementInFrame = (
 
   return false;
 };
+
+export const getFrameLikeTitle = (
+  element: ExcalidrawFrameLikeElement,
+  frameIdx: number,
+) => {
+  const existingName = element.name?.trim();
+  if (existingName) {
+    return existingName;
+  }
+  // TODO name frames AI only is specific to AI frames
+  return isFrameElement(element) ? `Frame ${frameIdx}` : `AI Frame ${frameIdx}`;
+};

src/history.ts

@@ -1,265 +1,173 @@
-import { AppState } from "./types";
+import { AppStateChange, ElementsChange } from "./change";
 import { ExcalidrawElement } from "./element/types";
-import { isLinearElement } from "./element/typeChecks";
-import { deepCopyElement } from "./element/newElement";
-import { Mutable } from "./utility-types";
+import { AppState } from "./types";
 
-export interface HistoryEntry {
-  appState: ReturnType<typeof clearAppStatePropertiesForHistory>;
-  elements: ExcalidrawElement[];
-}
+// TODO_UNDO: think about limiting the depth of stack
+export class History {
+  private readonly undoStack: HistoryEntry[] = [];
+  private readonly redoStack: HistoryEntry[] = [];
 
-interface DehydratedExcalidrawElement {
-  id: string;
-  versionNonce: number;
-}
-
-interface DehydratedHistoryEntry {
-  appState: string;
-  elements: DehydratedExcalidrawElement[];
-}
-
-const clearAppStatePropertiesForHistory = (appState: AppState) => {
-  return {
-    selectedElementIds: appState.selectedElementIds,
-    selectedGroupIds: appState.selectedGroupIds,
-    viewBackgroundColor: appState.viewBackgroundColor,
-    editingLinearElement: appState.editingLinearElement,
-    editingGroupId: appState.editingGroupId,
-    name: appState.name,
-  };
-};
-
-class History {
-  private elementCache = new Map<string, Map<number, ExcalidrawElement>>();
-  private recording: boolean = true;
-  private stateHistory: DehydratedHistoryEntry[] = [];
-  private redoStack: DehydratedHistoryEntry[] = [];
-  private lastEntry: HistoryEntry | null = null;
-
-  private hydrateHistoryEntry({
-    appState,
-    elements,
-  }: DehydratedHistoryEntry): HistoryEntry {
-    return {
-      appState: JSON.parse(appState),
-      elements: elements.map((dehydratedExcalidrawElement) => {
-        const element = this.elementCache
-          .get(dehydratedExcalidrawElement.id)
-          ?.get(dehydratedExcalidrawElement.versionNonce);
-        if (!element) {
-          throw new Error(
-            `Element not found: ${dehydratedExcalidrawElement.id}:${dehydratedExcalidrawElement.versionNonce}`,
-          );
-        }
-        return element;
-      }),
-    };
+  public get isUndoStackEmpty() {
+    return this.undoStack.length === 0;
   }
 
-  private dehydrateHistoryEntry({
-    appState,
-    elements,
-  }: HistoryEntry): DehydratedHistoryEntry {
-    return {
-      appState: JSON.stringify(appState),
-      elements: elements.map((element: ExcalidrawElement) => {
-        if (!this.elementCache.has(element.id)) {
-          this.elementCache.set(element.id, new Map());
-        }
-        const versions = this.elementCache.get(element.id)!;
-        if (!versions.has(element.versionNonce)) {
-          versions.set(element.versionNonce, deepCopyElement(element));
-        }
-        return {
-          id: element.id,
-          versionNonce: element.versionNonce,
-        };
-      }),
-    };
+  public get isRedoStackEmpty() {
+    return this.redoStack.length === 0;
   }
 
-  getSnapshotForTest() {
-    return {
-      recording: this.recording,
-      stateHistory: this.stateHistory.map((dehydratedHistoryEntry) =>
-        this.hydrateHistoryEntry(dehydratedHistoryEntry),
-      ),
-      redoStack: this.redoStack.map((dehydratedHistoryEntry) =>
-        this.hydrateHistoryEntry(dehydratedHistoryEntry),
-      ),
-    };
-  }
-
-  clear() {
-    this.stateHistory.length = 0;
+  public clear() {
+    this.undoStack.length = 0;
     this.redoStack.length = 0;
-    this.lastEntry = null;
-    this.elementCache.clear();
-  }
-
-  private generateEntry = (
-    appState: AppState,
-    elements: readonly ExcalidrawElement[],
-  ): DehydratedHistoryEntry =>
-    this.dehydrateHistoryEntry({
-      appState: clearAppStatePropertiesForHistory(appState),
-      elements: elements.reduce((elements, element) => {
-        if (
-          isLinearElement(element) &&
-          appState.multiElement &&
-          appState.multiElement.id === element.id
-        ) {
-          // don't store multi-point arrow if still has only one point
-          if (
-            appState.multiElement &&
-            appState.multiElement.id === element.id &&
-            element.points.length < 2
-          ) {
-            return elements;
-          }
-
-          elements.push({
-            ...element,
-            // don't store last point if not committed
-            points:
-              element.lastCommittedPoint !==
-              element.points[element.points.length - 1]
-                ? element.points.slice(0, -1)
-                : element.points,
-          });
-        } else {
-          elements.push(element);
-        }
-        return elements;
-      }, [] as Mutable<typeof elements>),
-    });
-
-  shouldCreateEntry(nextEntry: HistoryEntry): boolean {
-    const { lastEntry } = this;
-
-    if (!lastEntry) {
-      return true;
-    }
-
-    if (nextEntry.elements.length !== lastEntry.elements.length) {
-      return true;
-    }
-
-    // loop from right to left as changes are likelier to happen on new elements
-    for (let i = nextEntry.elements.length - 1; i > -1; i--) {
-      const prev = nextEntry.elements[i];
-      const next = lastEntry.elements[i];
-      if (
-        !prev ||
-        !next ||
-        prev.id !== next.id ||
-        prev.versionNonce !== next.versionNonce
-      ) {
-        return true;
-      }
-    }
-
-    // note: this is safe because entry's appState is guaranteed no excess props
-    let key: keyof typeof nextEntry.appState;
-    for (key in nextEntry.appState) {
-      if (key === "editingLinearElement") {
-        if (
-          nextEntry.appState[key]?.elementId ===
-          lastEntry.appState[key]?.elementId
-        ) {
-          continue;
-        }
-      }
-      if (key === "selectedElementIds" || key === "selectedGroupIds") {
-        continue;
-      }
-      if (nextEntry.appState[key] !== lastEntry.appState[key]) {
-        return true;
-      }
-    }
-
-    return false;
-  }
-
-  pushEntry(appState: AppState, elements: readonly ExcalidrawElement[]) {
-    const newEntryDehydrated = this.generateEntry(appState, elements);
-    const newEntry: HistoryEntry = this.hydrateHistoryEntry(newEntryDehydrated);
-
-    if (newEntry) {
-      if (!this.shouldCreateEntry(newEntry)) {
-        return;
-      }
-
-      this.stateHistory.push(newEntryDehydrated);
-      this.lastEntry = newEntry;
-      // As a new entry was pushed, we invalidate the redo stack
-      this.clearRedoStack();
-    }
-  }
-
-  clearRedoStack() {
-    this.redoStack.splice(0, this.redoStack.length);
-  }
-
-  redoOnce(): HistoryEntry | null {
-    if (this.redoStack.length === 0) {
-      return null;
-    }
-
-    const entryToRestore = this.redoStack.pop();
-
-    if (entryToRestore !== undefined) {
-      this.stateHistory.push(entryToRestore);
-      return this.hydrateHistoryEntry(entryToRestore);
-    }
-
-    return null;
-  }
-
-  undoOnce(): HistoryEntry | null {
-    if (this.stateHistory.length === 1) {
-      return null;
-    }
-
-    const currentEntry = this.stateHistory.pop();
-
-    const entryToRestore = this.stateHistory[this.stateHistory.length - 1];
-
-    if (currentEntry !== undefined) {
-      this.redoStack.push(currentEntry);
-      return this.hydrateHistoryEntry(entryToRestore);
-    }
-
-    return null;
   }
 
   /**
-   * Updates history's `lastEntry` to latest app state. This is necessary
-   *  when doing undo/redo which itself doesn't commit to history, but updates
-   *  app state in a way that would break `shouldCreateEntry` which relies on
-   *  `lastEntry` to reflect last comittable history state.
-   * We can't update `lastEntry` from within history when calling undo/redo
-   *  because the action potentially mutates appState/elements before storing
-   *  it.
+   * Record a local change which will go into the history
    */
-  setCurrentState(appState: AppState, elements: readonly ExcalidrawElement[]) {
-    this.lastEntry = this.hydrateHistoryEntry(
-      this.generateEntry(appState, elements),
-    );
-  }
+  public record(
+    elementsChange: ElementsChange,
+    appStateChange: AppStateChange,
+  ) {
+    const entry = HistoryEntry.create(appStateChange, elementsChange);
 
-  // Suspicious that this is called so many places. Seems error-prone.
-  resumeRecording() {
-    this.recording = true;
-  }
+    if (!entry.isEmpty()) {
+      this.undoStack.push(entry);
 
-  record(state: AppState, elements: readonly ExcalidrawElement[]) {
-    if (this.recording) {
-      this.pushEntry(state, elements);
-      this.recording = false;
+      // As a new entry was pushed, we invalidate the redo stack
+      this.redoStack.length = 0;
     }
   }
+
+  public undo(elements: Map<string, ExcalidrawElement>, appState: AppState) {
+    return this.perform(this.undoOnce.bind(this), elements, appState);
+  }
+
+  public redo(elements: Map<string, ExcalidrawElement>, appState: AppState) {
+    return this.perform(this.redoOnce.bind(this), elements, appState);
+  }
+
+  private perform(
+    action: typeof this.undoOnce | typeof this.redoOnce,
+    elements: Map<string, ExcalidrawElement>,
+    appState: AppState,
+  ): [Map<string, ExcalidrawElement>, AppState] | void {
+    let historyEntry = action(elements);
+
+    // Nothing to undo / redo
+    if (historyEntry === null) {
+      return;
+    }
+
+    let nextElements = elements;
+    let nextAppState = appState;
+    let containsVisibleChange = false;
+
+    // Iterate through the history entries in case they result in no visible changes
+    while (historyEntry) {
+      [nextElements, nextAppState, containsVisibleChange] =
+        historyEntry.applyTo(nextElements, nextAppState);
+
+      // TODO_UNDO: Be very carefuly here, as we could accidentaly iterate through the whole stack
+      if (containsVisibleChange) {
+        break;
+      }
+
+      historyEntry = action(elements);
+    }
+
+    return [nextElements, nextAppState];
+  }
+
+  private undoOnce(
+    elements: Map<string, ExcalidrawElement>,
+  ): HistoryEntry | null {
+    if (!this.undoStack.length) {
+      return null;
+    }
+
+    const undoEntry = this.undoStack.pop();
+
+    if (undoEntry !== undefined) {
+      const redoEntry = undoEntry.applyLatestChanges(elements, "to");
+      this.redoStack.push(redoEntry);
+
+      return undoEntry.inverse();
+    }
+
+    return null;
+  }
+
+  private redoOnce(
+    elements: Map<string, ExcalidrawElement>,
+  ): HistoryEntry | null {
+    if (!this.redoStack.length) {
+      return null;
+    }
+
+    const redoEntry = this.redoStack.pop();
+
+    if (redoEntry !== undefined) {
+      const undoEntry = redoEntry.applyLatestChanges(elements, "from");
+      this.undoStack.push(undoEntry);
+
+      return redoEntry;
+    }
+
+    return null;
+  }
 }
 
-export default History;
+export class HistoryEntry {
+  private constructor(
+    private readonly appStateChange: AppStateChange,
+    private readonly elementsChange: ElementsChange,
+  ) {}
+
+  public static create(
+    appStateChange: AppStateChange,
+    elementsChange: ElementsChange,
+  ) {
+    return new HistoryEntry(appStateChange, elementsChange);
+  }
+
+  public inverse(): HistoryEntry {
+    return new HistoryEntry(
+      this.appStateChange.inverse(),
+      this.elementsChange.inverse(),
+    );
+  }
+
+  public applyTo(
+    elements: Map<string, ExcalidrawElement>,
+    appState: AppState,
+  ): [Map<string, ExcalidrawElement>, AppState, boolean] {
+    const [nextElements, elementsContainVisibleChange] =
+      this.elementsChange.applyTo(elements);
+
+    const [nextAppState, appStateContainsVisibleChange] =
+      this.appStateChange.applyTo(appState, nextElements);
+
+    const appliedVisibleChanges =
+      elementsContainVisibleChange || appStateContainsVisibleChange;
+
+    return [nextElements, nextAppState, appliedVisibleChanges];
+  }
+
+  /**
+   * Apply latest (remote) changes to the history entry, creates new instance of `HistoryEntry`.
+   */
+  public applyLatestChanges(
+    elements: Map<string, ExcalidrawElement>,
+    modifierOptions: "from" | "to",
+  ): HistoryEntry {
+    const updatedElementsChange = this.elementsChange.applyLatestChanges(
+      elements,
+      modifierOptions,
+    );
+
+    return HistoryEntry.create(this.appStateChange, updatedElementsChange);
+  }
+
+  public isEmpty(): boolean {
+    return this.appStateChange.isEmpty() && this.elementsChange.isEmpty();
+  }
+}

src/locales/en.json

@@ -11,6 +11,8 @@
     "copyAsPng": "Copy to clipboard as PNG",
     "copyAsSvg": "Copy to clipboard as SVG",
     "copyText": "Copy to clipboard as text",
+    "copySource": "Copy source to clipboard",
+    "convertToCode": "Convert to code",
     "bringForward": "Bring forward",
     "sendToBack": "Send to back",
     "bringToFront": "Bring to front",
@@ -218,6 +220,7 @@
     },
     "libraryElementTypeError": {
       "embeddable": "Embeddable elements cannot be added to the library.",
+      "iframe": "IFrame elements cannot be added to the library.",
       "image": "Support for adding images to the library coming soon!"
     },
     "asyncPasteFailedOnRead": "Couldn't paste (couldn't read from system clipboard).",
@@ -240,11 +243,13 @@
     "link": "Add/ Update link for a selected shape",
     "eraser": "Eraser",
     "frame": "Frame tool",
+    "magicframe": "Wireframe to code",
     "embeddable": "Web Embed",
     "laser": "Laser pointer",
     "hand": "Hand (panning tool)",
     "extraTools": "More tools",
-    "mermaidToExcalidraw": "Mermaid to Excalidraw"
+    "mermaidToExcalidraw": "Mermaid to Excalidraw",
+    "magicSettings": "AI settings"
   },
   "headings": {
     "canvasActions": "Canvas actions",

src/packages/excalidraw/CHANGELOG.md

@@ -15,20 +15,33 @@ Please add the latest change on the top under the correct section.
 
 ### Features
 
+- Support for multiplayer undo / redo [#7348](https://github.com/excalidraw/excalidraw/pull/7348).
+
+### Breaking Changes
+
+- Renamed required `updatedScene` parameter from `commitToHistory` into `commitToStore` [#7348](https://github.com/excalidraw/excalidraw/pull/7348).
+- Updates of `elements` or `appState` performed through [`updateScene`](https://github.com/excalidraw/excalidraw/blob/master/src/components/App.tsx#L282) without `commitToStore` set to `true` require a new parameter `skipSnapshotUpdate` to be set to `true`, if the given update should be locally undo-able with the next user action. In other cases such a parameter shouldn't be needed, i.e. as in during multiplayer collab updates, which shouldn't should not be locally undoable.
+
+## 0.17.0 (2023-11-14)
+
+### Features
+
 - Added support for disabling `image` tool (also disabling image insertion in general, though keeps support for importing from `.excalidraw` files) [#6320](https://github.com/excalidraw/excalidraw/pull/6320).
 
-For disabling `image` you need to set 👇
+  For disabling `image` you need to set 👇
 
-```
-UIOptions.tools = {
-  image: false
-}
-```
+  ```
+  UIOptions.tools = {
+    image: false
+  }
+  ```
 
 - Support `excalidrawAPI` prop for accessing the Excalidraw API [#7251](https://github.com/excalidraw/excalidraw/pull/7251).
 
 - Export [`getCommonBounds`](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api/utils#getcommonbounds) helper from the package [#7247](https://github.com/excalidraw/excalidraw/pull/7247).
 
+- Support frames via programmatic API [#7205](https://github.com/excalidraw/excalidraw/pull/7205).
+
 - Export `elementsOverlappingBBox`, `isElementInsideBBox`, `elementPartiallyOverlapsWithOrContainsBBox` helpers for filtering/checking if elements within bounds. [#6727](https://github.com/excalidraw/excalidraw/pull/6727)
 
 - Regenerate ids by default when using transform api and also update bindings by 0.5px to avoid possible overlapping [#7195](https://github.com/excalidraw/excalidraw/pull/7195)
@@ -55,13 +68,133 @@ UIOptions.tools = {
 
 - Support Preact [#7255](https://github.com/excalidraw/excalidraw/pull/7255). The host needs to set `process.env.IS_PREACT` to `true`
 
-When using vite, you will have to make sure the variable process.env.IS_PREACT is available at runtime since Vite removes it by default, so you can update the vite config to ensure its available
+  When using `vite` or any build tools, you will have to make sure the `process` is accessible as we are accessing `process.env.IS_PREACT` to decide whether to use the `preact` build.
 
-```js
-define: {
-  "process.env.IS_PREACT": process.env.IS_PREACT,
-}
-```
+  Since `Vite` removes env variables by default, you can update the Vite config to ensure its available :point_down:
+
+  ```
+  define: {
+    "process.env.IS_PREACT": process.env.IS_PREACT,
+  },
+  ```
+
+## Excalidraw Library
+
+**_This section lists the updates made to the excalidraw library and will not affect the integration._**
+
+### Features
+
+- Allow D&D dice app domain for embeds [#7263](https://github.com/excalidraw/excalidraw/pull/7263)
+
+- Remove full screen shortcut [#7222](https://github.com/excalidraw/excalidraw/pull/7222)
+
+- Make adaptive-roughness less aggressive [#7250](https://github.com/excalidraw/excalidraw/pull/7250)
+
+- Render frames on export [#7210](https://github.com/excalidraw/excalidraw/pull/7210)
+
+- Support mermaid flowchart and sequence diagrams to excalidraw diagrams 🥳 [#6920](https://github.com/excalidraw/excalidraw/pull/6920)
+
+- Support frames via programmatic API [#7205](https://github.com/excalidraw/excalidraw/pull/7205)
+
+- Make clipboard more robust and reintroduce contextmenu actions [#7198](https://github.com/excalidraw/excalidraw/pull/7198)
+
+- Support giphy.com embed domain [#7192](https://github.com/excalidraw/excalidraw/pull/7192)
+
+- Renderer tweaks [#6698](https://github.com/excalidraw/excalidraw/pull/6698)
+
+- Closing of "Save to.." Dialog on Save To Disk [#7168](https://github.com/excalidraw/excalidraw/pull/7168)
+
+- Added Copy/Paste from Google Docs [#7136](https://github.com/excalidraw/excalidraw/pull/7136)
+
+- Remove bound-arrows from frames [#7157](https://github.com/excalidraw/excalidraw/pull/7157)
+
+- New dark mode theme & light theme tweaks [#7104](https://github.com/excalidraw/excalidraw/pull/7104)
+
+- Better laser cursor for dark mode [#7132](https://github.com/excalidraw/excalidraw/pull/7132)
+
+- Laser pointer improvements [#7128](https://github.com/excalidraw/excalidraw/pull/7128)
+
+- Initial Laser Pointer MVP [#6739](https://github.com/excalidraw/excalidraw/pull/6739)
+
+- Export `iconFillColor()` [#6996](https://github.com/excalidraw/excalidraw/pull/6996)
+
+- Element alignments - snapping [#6256](https://github.com/excalidraw/excalidraw/pull/6256)
+
+### Fixes
+
+- Image insertion bugs [#7278](https://github.com/excalidraw/excalidraw/pull/7278)
+
+- ExportToSvg to honor frameRendering also for name not only for frame itself [#7270](https://github.com/excalidraw/excalidraw/pull/7270)
+
+- Can't toggle penMode off due to missing typecheck in togglePenMode [#7273](https://github.com/excalidraw/excalidraw/pull/7273)
+
+- Replace hard coded font family with const value in addFrameLabelsAsTextElements [#7269](https://github.com/excalidraw/excalidraw/pull/7269)
+
+- Perf issue when ungrouping elements within frame [#7265](https://github.com/excalidraw/excalidraw/pull/7265)
+
+- Fixes the shortcut collision between "toggleHandTool" and "distributeHorizontally" [#7189](https://github.com/excalidraw/excalidraw/pull/7189)
+
+- Allow pointer events when editing a linear element [#7238](https://github.com/excalidraw/excalidraw/pull/7238)
+
+- Make modal use viewport breakpoints [#7246](https://github.com/excalidraw/excalidraw/pull/7246)
+
+- Align input `:hover`/`:focus` with spec [#7225](https://github.com/excalidraw/excalidraw/pull/7225)
+
+- Dialog remounting on className updates [#7224](https://github.com/excalidraw/excalidraw/pull/7224)
+
+- Don't update label position when dragging labelled arrows [#6891](https://github.com/excalidraw/excalidraw/pull/6891)
+
+- Frame add/remove/z-index ordering changes [#7194](https://github.com/excalidraw/excalidraw/pull/7194)
+
+- Element relative position when dragging multiple elements on grid [#7107](https://github.com/excalidraw/excalidraw/pull/7107)
+
+- Freedraw non-solid bg hitbox not working [#7193](https://github.com/excalidraw/excalidraw/pull/7193)
+
+- Actions panel ux improvement [#6850](https://github.com/excalidraw/excalidraw/pull/6850)
+
+- Better fill rendering with latest RoughJS [#7031](https://github.com/excalidraw/excalidraw/pull/7031)
+
+- Fix for Strange Symbol Appearing on Canvas after Deleting Grouped Graphics (Issue #7116) [#7170](https://github.com/excalidraw/excalidraw/pull/7170)
+
+- Attempt to fix flake in wysiwyg tests [#7173](https://github.com/excalidraw/excalidraw/pull/7173)
+
+- Ensure `ClipboardItem` created in the same tick to fix safari [#7066](https://github.com/excalidraw/excalidraw/pull/7066)
+
+- Wysiwyg left in undefined state on reload [#7123](https://github.com/excalidraw/excalidraw/pull/7123)
+
+- Ensure relative z-index of elements added to frame is retained [#7134](https://github.com/excalidraw/excalidraw/pull/7134)
+
+- Memoize static canvas on `props.renderConfig` [#7131](https://github.com/excalidraw/excalidraw/pull/7131)
+
+- Regression from #6739 preventing redirect link in view mode [#7120](https://github.com/excalidraw/excalidraw/pull/7120)
+
+- Update links to excalidraw-app [#7072](https://github.com/excalidraw/excalidraw/pull/7072)
+
+- Ensure we do not stop laser update prematurely [#7100](https://github.com/excalidraw/excalidraw/pull/7100)
+
+- Remove invisible elements safely [#7083](https://github.com/excalidraw/excalidraw/pull/7083)
+
+- Icon size in manifest [#7073](https://github.com/excalidraw/excalidraw/pull/7073)
+
+- Elements being dropped/duplicated when added to frame [#7057](https://github.com/excalidraw/excalidraw/pull/7057)
+
+- Frame name not editable on dbl-click [#7037](https://github.com/excalidraw/excalidraw/pull/7037)
+
+- Polyfill `Element.replaceChildren` [#7034](https://github.com/excalidraw/excalidraw/pull/7034)
+
+### Refactor
+
+- DRY out tool typing [#7086](https://github.com/excalidraw/excalidraw/pull/7086)
+
+- Refactor event globals to differentiate from `lastPointerUp` [#7084](https://github.com/excalidraw/excalidraw/pull/7084)
+
+- DRY out and simplify setting active tool from toolbar [#7079](https://github.com/excalidraw/excalidraw/pull/7079)
+
+### Performance
+
+- Improve element in frame check [#7124](https://github.com/excalidraw/excalidraw/pull/7124)
+
+---
 
 ## 0.16.1 (2023-09-21)
 
@@ -84,7 +217,7 @@ define: {
 - Support creating containers, linear elements, text containers, labelled arrows and arrow bindings programatically [#6546](https://github.com/excalidraw/excalidraw/pull/6546)
 - Introducing Web-Embeds (alias iframe element)[#6691](https://github.com/excalidraw/excalidraw/pull/6691)
 - Added [`props.validateEmbeddable`](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api/props#validateEmbeddable) to customize embeddable src url validation. [#6691](https://github.com/excalidraw/excalidraw/pull/6691)
-- Add support for `opts.fitToViewport` and `opts.viewportZoomFactor` in the [`ExcalidrawAPI.scrollToContent`](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api/props/ref#scrolltocontent) API. [#6581](https://github.com/excalidraw/excalidraw/pull/6581).
+- Add support for `opts.fitToViewport` and `opts.viewportZoomFactor` in the [`ExcalidrawAPI.scrollToContent`](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api/props/excalidraw-api#scrolltocontent) API. [#6581](https://github.com/excalidraw/excalidraw/pull/6581).
 - Properly sanitize element `link` urls. [#6728](https://github.com/excalidraw/excalidraw/pull/6728).
 - Sidebar component now supports tabs — for more detailed description of new behavior and breaking changes, see the linked PR. [#6213](https://github.com/excalidraw/excalidraw/pull/6213)
 - Exposed `DefaultSidebar` component to allow modifying the default sidebar, such as adding custom tabs to it. [#6213](https://github.com/excalidraw/excalidraw/pull/6213)
@@ -363,7 +496,7 @@ define: {
 
 ### Features
 
-- [`ExcalidrawAPI.scrollToContent`](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api/props/ref#scrolltocontent) has new opts object allowing you to fit viewport to content, and animate the scrolling. [#6319](https://github.com/excalidraw/excalidraw/pull/6319)
+- [`ExcalidrawAPI.scrollToContent`](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api/props/excalidraw-api#scrolltocontent) has new opts object allowing you to fit viewport to content, and animate the scrolling. [#6319](https://github.com/excalidraw/excalidraw/pull/6319)
 
 - Expose `useI18n()` hook return an object containing `t()` i18n helper and current `langCode`. You can use this in components you render as `<Excalidraw>` children to render any of our i18n locale strings. [#6224](https://github.com/excalidraw/excalidraw/pull/6224)
 

src/packages/excalidraw/index.tsx

@@ -44,6 +44,7 @@ const ExcalidrawBase = (props: ExcalidrawProps) => {
     children,
     validateEmbeddable,
     renderEmbeddable,
+    aiEnabled,
   } = props;
 
   const canvasActions = props.UIOptions?.canvasActions;
@@ -122,6 +123,7 @@ const ExcalidrawBase = (props: ExcalidrawProps) => {
           onScrollChange={onScrollChange}
           validateEmbeddable={validateEmbeddable}
           renderEmbeddable={renderEmbeddable}
+          aiEnabled={aiEnabled !== false}
         >
           {children}
         </App>

src/packages/excalidraw/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@excalidraw/excalidraw",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "main": "main.js",
   "types": "types/packages/excalidraw/index.d.ts",
   "files": [

src/packages/utils.ts

@@ -6,7 +6,7 @@ import { getDefaultAppState } from "../appState";
 import { AppState, BinaryFiles } from "../types";
 import {
   ExcalidrawElement,
-  ExcalidrawFrameElement,
+  ExcalidrawFrameLikeElement,
   NonDeleted,
 } from "../element/types";
 import { restore } from "../data/restore";
@@ -26,7 +26,7 @@ type ExportOpts = {
   appState?: Partial<Omit<AppState, "offsetTop" | "offsetLeft">>;
   files: BinaryFiles | null;
   maxWidthOrHeight?: number;
-  exportingFrame?: ExcalidrawFrameElement | null;
+  exportingFrame?: ExcalidrawFrameLikeElement | null;
   getDimensions?: (
     width: number,
     height: number,