snapshot of https://github.com/excalidraw/excalidraw.git (master, 2026-09-16; blobs > 131072B omitted)

packages/element/tests/__snapshots__/linearElementEditor.test.tsx.snap

@@ -0,0 +1,57 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Test Linear Elements > Test bound text element > should bind text to arrow when clicked on arrow and enter pressed 1`] = `
+"Online whiteboard
+collaboration made
+easy"
+`;
+
+exports[`Test Linear Elements > Test bound text element > should bind text to arrow when double clicked 1`] = `
+"Online whiteboard
+collaboration made
+easy"
+`;
+
+exports[`Test Linear Elements > Test bound text element > should match styles for text editor 1`] = `
+<textarea
+  class="excalidraw-wysiwyg"
+  data-type="wysiwyg"
+  dir="auto"
+  style="position: absolute; display: inline-block; min-height: 1em; backface-visibility: hidden; margin: 0px; padding: 0px; border: 0px; outline: 0; resize: none; background: transparent; overflow: hidden; z-index: var(--zIndex-wysiwyg); word-break: break-word; white-space: pre-wrap; overflow-wrap: break-word; box-sizing: content-box; width: 10.5px; height: 26.25px; left: 35px; top: 7.5px; transform: translate(0px, 0px) scale(1) rotate(0deg); text-align: center; vertical-align: middle; color: rgb(30, 30, 30); opacity: 1; max-height: 992.5px; font: Emoji 20px 20px; line-height: 1.25; font-family: Excalifont, Xiaolai, sans-serif, Segoe UI Emoji;"
+  tabindex="0"
+  wrap="off"
+/>
+`;
+
+exports[`Test Linear Elements > Test bound text element > should resize and position the bound text and bounding box correctly when 3 pointer arrow element resized 2`] = `
+"Online whiteboard
+collaboration made
+easy"
+`;
+
+exports[`Test Linear Elements > Test bound text element > should resize and position the bound text and bounding box correctly when 3 pointer arrow element resized 6`] = `
+"Online whiteboard
+collaboration made easy"
+`;
+
+exports[`Test Linear Elements > Test bound text element > should resize and position the bound text correctly when 2 pointer linear element resized 2`] = `
+"Online whiteboard
+collaboration made
+easy"
+`;
+
+exports[`Test Linear Elements > Test bound text element > should resize and position the bound text correctly when 2 pointer linear element resized 5`] = `
+"Online whiteboard
+collaboration made easy"
+`;
+
+exports[`Test Linear Elements > Test bound text element > should wrap the bound text when arrow bound container moves 1`] = `
+"Online whiteboard
+collaboration made easy"
+`;
+
+exports[`Test Linear Elements > Test bound text element > should wrap the bound text when arrow bound container moves 2`] = `
+"Online whiteboard
+collaboration made
+easy"
+`;

packages/element/tests/binding.test.tsx

@@ -0,0 +1,817 @@
+import { KEYS, arrayToMap } from "@excalidraw/common";
+
+import { pointFrom } from "@excalidraw/math";
+
+import { actionWrapTextInContainer } from "@excalidraw/excalidraw/actions/actionBoundText";
+
+import { Excalidraw, isLinearElement } from "@excalidraw/excalidraw";
+
+import { API } from "@excalidraw/excalidraw/tests/helpers/api";
+import { UI, Pointer, Keyboard } from "@excalidraw/excalidraw/tests/helpers/ui";
+import {
+  act,
+  fireEvent,
+  render,
+} from "@excalidraw/excalidraw/tests/test-utils";
+
+import { defaultLang, setLanguage } from "@excalidraw/excalidraw/i18n";
+
+import { bindBindingElement, updateBoundElements } from "../src/binding";
+import { getTransformHandles } from "../src/transformHandles";
+import {
+  getTextEditor,
+  TEXT_EDITOR_SELECTOR,
+} from "../../excalidraw/tests/queries/dom";
+
+import type {
+  ExcalidrawArrowElement,
+  ExcalidrawBindableElement,
+  ExcalidrawLinearElement,
+  FixedPointBinding,
+  NonDeleted,
+} from "../src/types";
+
+const { h } = window;
+
+const mouse = new Pointer("mouse");
+
+describe("binding for simple arrows", () => {
+  describe("when both endpoints are bound inside the same element", () => {
+    beforeEach(async () => {
+      mouse.reset();
+
+      await act(() => {
+        return setLanguage(defaultLang);
+      });
+      await render(<Excalidraw handleKeyboardGlobally={true} />);
+    });
+
+    it("should create an `inside` binding", () => {
+      // Create a rectangle
+      UI.clickTool("rectangle");
+      mouse.reset();
+      mouse.downAt(100, 100);
+      mouse.moveTo(200, 200);
+      mouse.up();
+
+      const rect = API.getSelectedElement();
+
+      // Draw arrow with endpoint inside the filled rectangle
+      UI.clickTool("arrow");
+      mouse.downAt(110, 110);
+      mouse.moveTo(160, 160);
+      mouse.up();
+
+      const arrow = API.getSelectedElement() as ExcalidrawLinearElement;
+      expect(arrow.x).toBe(110);
+      expect(arrow.y).toBe(110);
+
+      // Should bind to the rectangle since endpoint is inside
+      expect(arrow.startBinding?.elementId).toBe(rect.id);
+      expect(arrow.endBinding?.elementId).toBe(rect.id);
+
+      const startBinding = arrow.startBinding as FixedPointBinding;
+      expect(startBinding.fixedPoint[0]).toBeGreaterThanOrEqual(0);
+      expect(startBinding.fixedPoint[0]).toBeLessThanOrEqual(1);
+      expect(startBinding.fixedPoint[1]).toBeGreaterThanOrEqual(0);
+      expect(startBinding.fixedPoint[1]).toBeLessThanOrEqual(1);
+      expect(startBinding.mode).toBe("inside");
+
+      const endBinding = arrow.endBinding as FixedPointBinding;
+      expect(endBinding.fixedPoint[0]).toBeGreaterThanOrEqual(0);
+      expect(endBinding.fixedPoint[0]).toBeLessThanOrEqual(1);
+      expect(endBinding.fixedPoint[1]).toBeGreaterThanOrEqual(0);
+      expect(endBinding.fixedPoint[1]).toBeLessThanOrEqual(1);
+      expect(endBinding.mode).toBe("inside");
+
+      // Move the bindable
+      mouse.downAt(100, 150);
+      mouse.moveTo(280, 110);
+      mouse.up();
+
+      // Check if the arrow moved
+      expect(arrow.x).toBe(290);
+      expect(arrow.y).toBe(70);
+
+      // Restore bindable
+      mouse.reset();
+      mouse.downAt(280, 110);
+      mouse.moveTo(130, 110);
+      mouse.up();
+
+      // Move the start point of the arrow to check if
+      // the behavior remains the same for old arrows
+      mouse.reset();
+      mouse.downAt(110, 110);
+      mouse.moveTo(120, 120);
+      mouse.up();
+
+      // Move the bindable again
+      mouse.reset();
+      mouse.downAt(130, 110);
+      mouse.moveTo(280, 110);
+      mouse.up();
+
+      // Check if the arrow moved
+      expect(arrow.x).toBe(290);
+      expect(arrow.y).toBe(70);
+    });
+
+    it("3+ point arrow should be dragged along with the bindable", () => {
+      // Create two rectangles as binding targets
+      const rectLeft = API.createElement({
+        type: "rectangle",
+        x: 0,
+        y: 0,
+        width: 100,
+        height: 100,
+      });
+
+      const rectRight = API.createElement({
+        type: "rectangle",
+        x: 300,
+        y: 0,
+        width: 100,
+        height: 100,
+      });
+
+      // Create a non-elbowed arrow with inner points bound to different elements
+      const arrow = API.createElement({
+        type: "arrow",
+        x: 100,
+        y: 50,
+        width: 200,
+        height: 0,
+        points: [
+          pointFrom(0, 0), // start point
+          pointFrom(50, -20), // first inner point
+          pointFrom(150, 20), // second inner point
+          pointFrom(200, 0), // end point
+        ],
+        startBinding: {
+          elementId: rectLeft.id,
+          fixedPoint: [0.5, 0.5],
+          mode: "orbit",
+        },
+        endBinding: {
+          elementId: rectRight.id,
+          fixedPoint: [0.5, 0.5],
+          mode: "orbit",
+        },
+      });
+
+      API.setElements([rectLeft, rectRight, arrow]);
+
+      // Store original inner point positions
+      const originalInnerPoint1 = [...arrow.points[1]];
+      const originalInnerPoint2 = [...arrow.points[2]];
+
+      // Move the right rectangle down by 50 pixels
+      mouse.reset();
+      mouse.downAt(350, 50); // Click on the right rectangle
+      mouse.moveTo(350, 100); // Move it down
+      mouse.up();
+
+      // Verify that inner points did NOT move when bound to different elements
+      // The arrow should NOT translate inner points proportionally when only one end moves
+      expect(arrow.points[1][0]).toBe(originalInnerPoint1[0]);
+      expect(arrow.points[1][1]).toBe(originalInnerPoint1[1]);
+      expect(arrow.points[2][0]).toBe(originalInnerPoint2[0]);
+      expect(arrow.points[2][1]).toBe(originalInnerPoint2[1]);
+    });
+  });
+
+  describe("self-binding (both ends to the same element) single-click finalize", () => {
+    // rect spans x:200..400, y:200..400; orbit ring is ~15px outside the outline
+    const INSIDE: [number, number] = [250, 250];
+    const ORBIT_LEFT: [number, number] = [187, 300];
+    const ORBIT_RIGHT: [number, number] = [413, 300];
+    const MIDDLE: [number, number] = [550, 100];
+
+    beforeEach(async () => {
+      mouse.reset();
+      await act(() => setLanguage(defaultLang));
+      await render(<Excalidraw handleKeyboardGlobally={true} />);
+      UI.createElement("rectangle", {
+        x: 200,
+        y: 200,
+        width: 200,
+        height: 200,
+      });
+    });
+
+    const drawSelfArrow = (start: [number, number], end: [number, number]) => {
+      UI.clickTool("arrow");
+      mouse.reset();
+      mouse.clickAt(...start);
+      mouse.moveTo(...MIDDLE);
+      mouse.clickAt(...MIDDLE); // commit a middle point so it's a multi-point arrow
+      mouse.moveTo(...end);
+      mouse.clickAt(...end); // single click at the end
+    };
+
+    it("orbit -> orbit finalizes on a single click", () => {
+      drawSelfArrow(ORBIT_LEFT, ORBIT_RIGHT);
+
+      const arrow = h.elements[h.elements.length - 1] as ExcalidrawArrowElement;
+      expect(h.state.multiElement).toBe(null);
+      expect(h.state.activeTool.type).toBe("selection");
+      expect(arrow.startBinding?.elementId).toBe(arrow.endBinding?.elementId);
+      expect(arrow.endBinding?.elementId).not.toBe(undefined);
+    });
+
+    it("inside -> orbit finalizes on a single click", () => {
+      drawSelfArrow(INSIDE, ORBIT_RIGHT);
+
+      const arrow = h.elements[h.elements.length - 1] as ExcalidrawArrowElement;
+      expect(h.state.multiElement).toBe(null);
+      expect(h.state.activeTool.type).toBe("selection");
+      expect(arrow.startBinding?.elementId).toBe(arrow.endBinding?.elementId);
+      expect(arrow.endBinding?.elementId).not.toBe(undefined);
+    });
+
+    it("inside -> inside keep in multi-point mode (no single-click finalize)", () => {
+      drawSelfArrow(INSIDE, [INSIDE[0] + 50, INSIDE[1] + 50]); // end dropped inside the rect
+
+      // ambiguous → must be confirmed with a second click, so still in progress
+      expect(h.state.multiElement).not.toBe(null);
+      expect(h.state.activeTool.type).toBe("arrow");
+    });
+  });
+
+  describe("when arrow is outside of shape", () => {
+    beforeEach(async () => {
+      mouse.reset();
+
+      await act(() => {
+        return setLanguage(defaultLang);
+      });
+      await render(<Excalidraw handleKeyboardGlobally={true} />);
+    });
+
+    it("should handle new arrow start point binding", () => {
+      // Create a rectangle
+      UI.clickTool("rectangle");
+      mouse.downAt(100, 100);
+      mouse.moveTo(200, 200);
+      mouse.up();
+
+      const rectangle = API.getSelectedElement();
+
+      // Create arrow with arrow tool
+      UI.clickTool("arrow");
+      mouse.downAt(205, 150); // Start close to rectangle
+      mouse.moveTo(250, 150); // End outside
+      mouse.up();
+
+      const arrow = API.getSelectedElement() as ExcalidrawLinearElement;
+
+      // Arrow should have start binding to rectangle
+      expect(arrow.startBinding?.elementId).toBe(rectangle.id);
+      expect(arrow.startBinding?.mode).toBe("orbit"); // Default is orbit, not inside
+      expect(arrow.endBinding).toBeNull();
+    });
+
+    it("should handle new arrow end point binding", () => {
+      // Create a rectangle
+      UI.clickTool("rectangle");
+      mouse.downAt(100, 100);
+      mouse.moveTo(200, 200);
+      mouse.up();
+
+      const rectangle = API.getSelectedElement();
+
+      // Create arrow with end point in binding zone
+      UI.clickTool("arrow");
+      mouse.downAt(50, 150); // Start outside
+      mouse.moveTo(95, 95); // End near rectangle edge (should bind as orbit)
+      mouse.up();
+
+      const arrow = API.getSelectedElement() as ExcalidrawLinearElement;
+
+      // Arrow should have end binding to rectangle
+      expect(arrow.endBinding?.elementId).toBe(rectangle.id);
+      expect(arrow.endBinding?.mode).toBe("orbit");
+      expect(arrow.startBinding).toBeNull();
+    });
+
+    it.skip("should create orbit binding when one of the cursor is inside rectangle", () => {
+      // Create a filled solid rectangle
+      UI.clickTool("rectangle");
+      mouse.downAt(100, 100);
+      mouse.moveTo(200, 200);
+      mouse.up();
+
+      const rect = API.getSelectedElement();
+      API.updateElement(rect, {
+        fillStyle: "solid",
+        backgroundColor: "#a5d8ff",
+      });
+
+      // Draw arrow with endpoint inside the filled rectangle, since only
+      // filled bindables bind inside the shape
+      UI.clickTool("arrow");
+      mouse.downAt(10, 10);
+      mouse.moveTo(160, 160);
+      mouse.up();
+
+      const arrow = API.getSelectedElement() as ExcalidrawLinearElement;
+      expect(arrow.x).toBe(10);
+      expect(arrow.y).toBe(10);
+      expect(arrow.width).toBeCloseTo(85.75985931287957);
+      expect(arrow.height).toBeCloseTo(85.75985931288186);
+
+      // Should bind to the rectangle since endpoint is inside
+      expect(arrow.startBinding).toBe(null);
+      expect(arrow.endBinding?.elementId).toBe(rect.id);
+
+      const endBinding = arrow.endBinding as FixedPointBinding;
+      expect(endBinding.fixedPoint[0]).toBeGreaterThanOrEqual(0);
+      expect(endBinding.fixedPoint[0]).toBeLessThanOrEqual(1);
+      expect(endBinding.fixedPoint[1]).toBeGreaterThanOrEqual(0);
+      expect(endBinding.fixedPoint[1]).toBeLessThanOrEqual(1);
+
+      mouse.reset();
+
+      // Move the bindable
+      mouse.downAt(130, 110);
+      mouse.moveTo(280, 110);
+      mouse.up();
+
+      // Check if the arrow moved
+      expect(arrow.x).toBe(10);
+      expect(arrow.y).toBe(10);
+      expect(arrow.width).toBeCloseTo(234);
+      expect(arrow.height).toBeCloseTo(117);
+
+      // Restore bindable
+      mouse.reset();
+      mouse.downAt(280, 110);
+      mouse.moveTo(130, 110);
+      mouse.up();
+
+      // Move the arrow out
+      mouse.reset();
+      mouse.click(10, 10);
+      mouse.downAt(96.466, 96.466);
+      mouse.moveTo(50, 50);
+      mouse.up();
+
+      expect(arrow.startBinding).toBe(null);
+      expect(arrow.endBinding).toBe(null);
+
+      // Re-bind the arrow by moving the cursor inside the rectangle
+      mouse.reset();
+      mouse.downAt(50, 50);
+      mouse.moveTo(150, 150);
+      mouse.up();
+
+      // Check if the arrow is still on the outside
+      expect(arrow.width).toBeCloseTo(86, 0);
+      expect(arrow.height).toBeCloseTo(86, 0);
+    });
+  });
+
+  describe("additional binding behavior", () => {
+    beforeEach(async () => {
+      mouse.reset();
+
+      await act(() => {
+        return setLanguage(defaultLang);
+      });
+      await render(<Excalidraw handleKeyboardGlobally={true} />);
+    });
+
+    it(
+      "editing arrow and moving its head to bind it to element A, finalizing the" +
+        "editing by clicking on element A should end up selecting A",
+      async () => {
+        UI.createElement("rectangle", {
+          y: 0,
+          size: 100,
+        });
+        // Create arrow bound to rectangle
+        UI.clickTool("arrow");
+        mouse.down(50, -100);
+        mouse.up(0, 80);
+
+        // Edit arrow
+        Keyboard.withModifierKeys({ ctrl: true }, () => {
+          Keyboard.keyPress(KEYS.ENTER);
+        });
+
+        // move arrow head
+        mouse.down();
+        mouse.up(0, 10);
+        expect(API.getSelectedElement().type).toBe("arrow");
+
+        expect(h.state.selectedLinearElement?.isEditing).toBe(true);
+        mouse.reset();
+        mouse.clickAt(-50, -50);
+        expect(h.state.selectedLinearElement?.isEditing).toBe(false);
+        expect(API.getSelectedElement().type).toBe("arrow");
+
+        // Edit arrow
+        Keyboard.withModifierKeys({ ctrl: true }, () => {
+          Keyboard.keyPress(KEYS.ENTER);
+        });
+        expect(h.state.selectedLinearElement?.isEditing).toBe(true);
+        mouse.reset();
+        mouse.clickAt(0, 0);
+        expect(h.state.selectedLinearElement).toBeNull();
+        expect(API.getSelectedElement().type).toBe("rectangle");
+      },
+    );
+
+    it("should unbind on bound element deletion", () => {
+      const rectangle = UI.createElement("rectangle", {
+        x: 60,
+        y: 0,
+        size: 100,
+      });
+
+      const arrow = UI.createElement("arrow", {
+        x: 0,
+        y: 5,
+        size: 70,
+      });
+
+      expect(arrow.endBinding?.elementId).toBe(rectangle.id);
+
+      mouse.select(rectangle);
+      expect(API.getSelectedElement().type).toBe("rectangle");
+      Keyboard.keyDown(KEYS.DELETE);
+      expect(arrow.endBinding).toBe(null);
+    });
+
+    it("should unbind arrow when arrow is resized", () => {
+      const rectLeft = UI.createElement("rectangle", {
+        x: 0,
+        width: 200,
+        height: 500,
+      });
+      const rectRight = UI.createElement("rectangle", {
+        x: 400,
+        width: 200,
+        height: 500,
+      });
+      UI.clickTool("arrow");
+      mouse.reset();
+      mouse.clickAt(190, 250);
+      mouse.moveTo(220, 200);
+      mouse.moveTo(300, 200);
+      mouse.clickAt(300, 200);
+      mouse.moveTo(340, 251);
+      mouse.moveTo(410, 251);
+      mouse.clickAt(410, 251);
+      mouse.clickAt(410, 251);
+      const arrow = h.elements[h.elements.length - 1] as any;
+
+      expect(arrow.startBinding?.elementId).toBe(rectLeft.id);
+      expect(arrow.endBinding?.elementId).toBe(rectRight.id);
+
+      // Drag arrow off of bound rectangle range
+      const handles = getTransformHandles(
+        arrow,
+        h.state.zoom,
+        arrayToMap(h.elements),
+        "mouse",
+      ).se!;
+
+      const elX = handles[0] + handles[2] / 2;
+      const elY = handles[1] + handles[3] / 2;
+      // move first, as a real pointer would — the hover state from the spot
+      // where arrow creation finished must clear before the pointerdown
+      mouse.moveTo(elX, elY);
+      mouse.downAt(elX, elY);
+      mouse.moveTo(300, 400);
+      mouse.up();
+
+      expect(arrow.startBinding).toBe(null);
+      expect(arrow.endBinding).toBe(null);
+    });
+
+    it("should unbind arrow when arrow is rotated", () => {
+      const rectLeft = UI.createElement("rectangle", {
+        x: 0,
+        width: 200,
+        height: 500,
+      });
+      const rectRight = UI.createElement("rectangle", {
+        x: 400,
+        width: 200,
+        height: 500,
+      });
+
+      UI.clickTool("arrow");
+      mouse.reset();
+      mouse.clickAt(190, 250);
+      mouse.moveTo(220, 200);
+      mouse.moveTo(300, 200);
+      mouse.clickAt(300, 200);
+      mouse.moveTo(350, 251);
+      mouse.moveTo(410, 251);
+      mouse.clickAt(410, 251);
+      mouse.clickAt(410, 251);
+
+      const arrow = API.getSelectedElement() as ExcalidrawArrowElement;
+
+      expect(arrow.startBinding?.elementId).toBe(rectLeft.id);
+      expect(arrow.endBinding?.elementId).toBe(rectRight.id);
+
+      const rotation = getTransformHandles(
+        arrow,
+        h.state.zoom,
+        arrayToMap(h.elements),
+        "mouse",
+      ).rotation!;
+      const rotationHandleX = rotation[0] + rotation[2] / 2;
+      const rotationHandleY = rotation[1] + rotation[3] / 2;
+      mouse.reset();
+      mouse.down(rotationHandleX, rotationHandleY);
+      mouse.move(300, 400);
+      mouse.up();
+      expect(arrow.angle).toBeGreaterThan(0.7 * Math.PI);
+      expect(arrow.angle).toBeLessThan(1.3 * Math.PI);
+      expect(arrow.startBinding).toBeNull();
+      expect(arrow.endBinding).toBeNull();
+    });
+
+    it("should not unbind when duplicating via selection group", () => {
+      const rectLeft = UI.createElement("rectangle", {
+        x: 0,
+        width: 200,
+        height: 500,
+      });
+      const rectRight = UI.createElement("rectangle", {
+        x: 400,
+        y: 200,
+        width: 200,
+        height: 500,
+      });
+      const arrow = UI.createElement("arrow", {
+        x: 190,
+        y: 250,
+        width: 217,
+        height: 1,
+      });
+      expect(arrow.startBinding?.elementId).toBe(rectLeft.id);
+      expect(arrow.endBinding?.elementId).toBe(rectRight.id);
+
+      mouse.downAt(-100, -100);
+      mouse.moveTo(0, 0);
+      mouse.moveTo(650, 750);
+      mouse.up(0, 0);
+
+      expect(API.getSelectedElements().length).toBe(3);
+
+      mouse.moveTo(5, 5);
+      Keyboard.withModifierKeys({ alt: true }, () => {
+        mouse.downAt(5, 5);
+        mouse.moveTo(1000, 1000);
+        mouse.up(0, 0);
+
+        expect(window.h.elements.length).toBe(6);
+        window.h.elements.forEach((element) => {
+          if (isLinearElement(element)) {
+            expect(element.startBinding).not.toBe(null);
+            expect(element.endBinding).not.toBe(null);
+          } else {
+            expect(element.boundElements).not.toBe(null);
+          }
+        });
+      });
+    });
+  });
+
+  describe("to text elements", () => {
+    beforeEach(async () => {
+      mouse.reset();
+
+      await act(() => {
+        return setLanguage(defaultLang);
+      });
+      await render(<Excalidraw handleKeyboardGlobally={true} />);
+    });
+
+    it("should update binding when text containerized", async () => {
+      const rectangle1 = API.createElement({
+        type: "rectangle",
+        id: "rectangle1",
+        width: 100,
+        height: 100,
+        boundElements: [
+          { id: "arrow1", type: "arrow" },
+          { id: "arrow2", type: "arrow" },
+        ],
+      });
+
+      const arrow1 = API.createElement({
+        type: "arrow",
+        id: "arrow1",
+        points: [pointFrom(0, 0), pointFrom(0, -87.45777932247563)],
+        startBinding: {
+          elementId: "rectangle1",
+          fixedPoint: [0.5, 1],
+          mode: "orbit",
+        },
+        endBinding: {
+          elementId: "text1",
+          fixedPoint: [1, 0.5],
+          mode: "orbit",
+        },
+      });
+
+      const arrow2 = API.createElement({
+        type: "arrow",
+        id: "arrow2",
+        points: [pointFrom(0, 0), pointFrom(0, -87.45777932247563)],
+        startBinding: {
+          elementId: "text1",
+          fixedPoint: [0.5, 1],
+          mode: "orbit",
+        },
+        endBinding: {
+          elementId: "rectangle1",
+          fixedPoint: [1, 0.5],
+          mode: "orbit",
+        },
+      });
+
+      const text1 = API.createElement({
+        type: "text",
+        id: "text1",
+        text: "ola",
+        boundElements: [
+          { id: "arrow1", type: "arrow" },
+          { id: "arrow2", type: "arrow" },
+        ],
+      });
+
+      API.setElements([rectangle1, arrow1, arrow2, text1]);
+
+      API.setSelectedElements([text1]);
+
+      expect(h.state.selectedElementIds[text1.id]).toBe(true);
+
+      API.executeAction(actionWrapTextInContainer);
+
+      // new text container will be placed before the text element
+      const container = h.elements.at(-2)!;
+
+      expect(container.type).toBe("rectangle");
+      expect(container.id).not.toBe(rectangle1.id);
+
+      expect(container).toEqual(
+        expect.objectContaining({
+          boundElements: expect.arrayContaining([
+            {
+              type: "text",
+              id: text1.id,
+            },
+            {
+              type: "arrow",
+              id: arrow1.id,
+            },
+            {
+              type: "arrow",
+              id: arrow2.id,
+            },
+          ]),
+        }),
+      );
+
+      expect(arrow1.startBinding?.elementId).toBe(rectangle1.id);
+      expect(arrow1.endBinding?.elementId).toBe(container.id);
+      expect(arrow2.startBinding?.elementId).toBe(container.id);
+      expect(arrow2.endBinding?.elementId).toBe(rectangle1.id);
+    });
+
+    it("should keep binding on text update", async () => {
+      const text = API.createElement({
+        type: "text",
+        text: "ola",
+        x: 60,
+        y: 0,
+        width: 100,
+        height: 100,
+      });
+
+      API.setElements([text]);
+
+      const arrow = UI.createElement("arrow", {
+        x: 0,
+        y: 0,
+        size: 65,
+      });
+
+      expect(arrow.endBinding?.elementId).toBe(text.id);
+
+      // delete text element by submitting empty text
+      // -------------------------------------------------------------------------
+
+      UI.clickTool("text");
+
+      mouse.clickAt(text.x + 50, text.y + 50);
+      const editor = await getTextEditor();
+
+      expect(editor).not.toBe(null);
+
+      fireEvent.change(editor, { target: { value: "asdasdasdasdas" } });
+      fireEvent.keyDown(editor, { key: KEYS.ESCAPE });
+
+      expect(document.querySelector(TEXT_EDITOR_SELECTOR)).toBe(null);
+      expect(arrow.endBinding?.elementId).toBe(text.id);
+    });
+
+    it("should unbind on text element deletion by submitting empty text", async () => {
+      const text = API.createElement({
+        type: "text",
+        text: "¡olá!",
+        x: 60,
+        y: 0,
+        width: 100,
+        height: 100,
+      });
+
+      API.setElements([text]);
+
+      const arrow = UI.createElement("arrow", {
+        x: 0,
+        y: 0,
+        size: 65,
+      });
+
+      expect(arrow.endBinding?.elementId).toBe(text.id);
+
+      // edit text element and submit
+      // -------------------------------------------------------------------------
+
+      UI.clickTool("text");
+
+      mouse.clickAt(text.x + 50, text.y + 50);
+
+      const editor = await getTextEditor();
+
+      fireEvent.change(editor, { target: { value: "" } });
+      fireEvent.keyDown(editor, { key: KEYS.ESCAPE });
+
+      expect(document.querySelector(TEXT_EDITOR_SELECTOR)).toBe(null);
+      expect(arrow.endBinding).toBe(null);
+    });
+  });
+});
+
+describe("binding to a point-like (sub-pixel) element", () => {
+  beforeEach(async () => {
+    mouse.reset();
+    await act(() => setLanguage(defaultLang));
+    await render(<Excalidraw handleKeyboardGlobally={true} />);
+  });
+
+  // Regression: binding to a zero/near-zero-size element used to yield an
+  // enormous fixedPoint ratio (offset / ~0), which exploded into an arrow
+  // hundreds of thousands of px wide once the element was resized to a normal
+  // size
+  it.each([
+    ["simple", false],
+    ["elbow", true],
+  ])(
+    "%s arrow binds to the center and stays put when the element grows",
+    (_label, elbowed) => {
+      const rect = API.createElement({
+        type: "rectangle",
+        x: 200,
+        y: 50,
+        width: 0.00005,
+        height: 0.00005,
+      }) as NonDeleted<ExcalidrawBindableElement>;
+      const arrow = API.createElement({
+        type: "arrow",
+        elbowed,
+        x: 0,
+        y: 50,
+        width: 195,
+        height: 0,
+        points: [pointFrom(0, 0), pointFrom(195, 0)],
+      }) as NonDeleted<ExcalidrawArrowElement>;
+      API.setElements([rect, arrow]);
+
+      bindBindingElement(arrow, rect, "orbit", "end", h.scene);
+
+      const endBinding = arrow.endBinding as FixedPointBinding;
+      expect(endBinding.elementId).toBe(rect.id);
+      // Point-like element => bind to center (0.5 is normalized to 0.5001)
+      expect(endBinding.fixedPoint[0]).toBeCloseTo(0.5001);
+      expect(endBinding.fixedPoint[1]).toBeCloseTo(0.5001);
+
+      // Grow the element to a normal size and let bound arrows follow
+      h.scene.mutateElement(rect, { width: 300, height: 200 });
+      updateBoundElements(rect, h.scene);
+
+      // The arrow endpoint must track the element (its center), not fly off
+      expect(Math.abs(arrow.width)).toBeLessThan(1000);
+      expect(Math.abs(arrow.height)).toBeLessThan(1000);
+    },
+  );
+});

packages/element/tests/bounds.test.ts

@@ -0,0 +1,209 @@
+import { pointFrom } from "@excalidraw/math";
+import { arrayToMap, type Bounds, ROUNDNESS } from "@excalidraw/common";
+import { API } from "@excalidraw/excalidraw/tests/helpers/api";
+
+import type { LocalPoint } from "@excalidraw/math";
+
+import {
+  elementsOverlappingBBox,
+  getElementAbsoluteCoords,
+  getElementBounds,
+} from "../src/bounds";
+
+import type { ExcalidrawElement, ExcalidrawLinearElement } from "../src/types";
+
+const _ce = ({
+  x,
+  y,
+  w,
+  h,
+  a,
+  t,
+}: {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  a?: number;
+  t?: string;
+}) =>
+  ({
+    type: t || "rectangle",
+    strokeColor: "#000",
+    backgroundColor: "#000",
+    fillStyle: "solid",
+    strokeWidth: 1,
+    roundness: { type: ROUNDNESS.PROPORTIONAL_RADIUS },
+    roughness: 0,
+    opacity: 1,
+    x,
+    y,
+    width: w,
+    height: h,
+    angle: a,
+  } as ExcalidrawElement);
+
+describe("getElementAbsoluteCoords", () => {
+  it("test x1 coordinate", () => {
+    const element = _ce({ x: 10, y: 20, w: 10, h: 0 });
+    const [x1] = getElementAbsoluteCoords(element, arrayToMap([element]));
+    expect(x1).toEqual(10);
+  });
+
+  it("test x2 coordinate", () => {
+    const element = _ce({ x: 10, y: 20, w: 10, h: 0 });
+    const [, , x2] = getElementAbsoluteCoords(element, arrayToMap([element]));
+    expect(x2).toEqual(20);
+  });
+
+  it("test y1 coordinate", () => {
+    const element = _ce({ x: 0, y: 10, w: 0, h: 10 });
+    const [, y1] = getElementAbsoluteCoords(element, arrayToMap([element]));
+    expect(y1).toEqual(10);
+  });
+
+  it("test y2 coordinate", () => {
+    const element = _ce({ x: 0, y: 10, w: 0, h: 10 });
+    const [, , , y2] = getElementAbsoluteCoords(element, arrayToMap([element]));
+    expect(y2).toEqual(20);
+  });
+});
+
+describe("getElementBounds", () => {
+  it("rectangle", () => {
+    const element = _ce({
+      x: 40,
+      y: 30,
+      w: 20,
+      h: 10,
+      a: Math.PI / 4,
+      t: "rectangle",
+    });
+    const [x1, y1, x2, y2] = getElementBounds(element, arrayToMap([element]));
+    expect(x1).toEqual(39.39339828220179);
+    expect(y1).toEqual(24.393398282201787);
+    expect(x2).toEqual(60.60660171779821);
+    expect(y2).toEqual(45.60660171779821);
+  });
+
+  it("diamond", () => {
+    const element = _ce({
+      x: 40,
+      y: 30,
+      w: 20,
+      h: 10,
+      a: Math.PI / 4,
+      t: "diamond",
+    });
+
+    const [x1, y1, x2, y2] = getElementBounds(element, arrayToMap([element]));
+
+    expect(x1).toEqual(42.928932188134524);
+    expect(y1).toEqual(27.928932188134524);
+    expect(x2).toEqual(57.071067811865476);
+    expect(y2).toEqual(42.071067811865476);
+  });
+
+  it("ellipse", () => {
+    const element = _ce({
+      x: 40,
+      y: 30,
+      w: 20,
+      h: 10,
+      a: Math.PI / 4,
+      t: "ellipse",
+    });
+
+    const [x1, y1, x2, y2] = getElementBounds(element, arrayToMap([element]));
+    expect(x1).toEqual(42.09430584957905);
+    expect(y1).toEqual(27.09430584957905);
+    expect(x2).toEqual(57.90569415042095);
+    expect(y2).toEqual(42.90569415042095);
+  });
+
+  it("curved line", () => {
+    const element = {
+      ..._ce({
+        t: "line",
+        x: 449.58203125,
+        y: 186.0625,
+        w: 170.12890625,
+        h: 92.48828125,
+        a: 0.6447741904932416,
+      }),
+      points: [
+        pointFrom<LocalPoint>(0, 0),
+        pointFrom<LocalPoint>(67.33984375, 92.48828125),
+        pointFrom<LocalPoint>(-102.7890625, 52.15625),
+      ],
+    } as ExcalidrawLinearElement;
+
+    const [x1, y1, x2, y2] = getElementBounds(element, arrayToMap([element]));
+    expect(x1).toEqual(360.9291017525165);
+    expect(y1).toEqual(185.24770129343722);
+    expect(x2).toEqual(481.4815539037601);
+    expect(y2).toEqual(319.8162855827246);
+  });
+});
+
+const makeElement = (x: number, y: number, width: number, height: number) =>
+  API.createElement({
+    type: "rectangle",
+    x,
+    y,
+    width,
+    height,
+  });
+
+const makeBBox = (
+  minX: number,
+  minY: number,
+  maxX: number,
+  maxY: number,
+): Bounds => [minX, minY, maxX, maxY];
+
+describe("elementsOverlappingBBox()", () => {
+  it("should return elements that overlap bbox", () => {
+    const bbox = makeBBox(0, 0, 100, 100);
+
+    const rectOutside = makeElement(110, 110, 100, 100);
+    const rectInside = makeElement(10, 10, 85, 85);
+    const rectContainingBBox = makeElement(-10, -10, 110, 110);
+    const rectOverlappingTopLeft = makeElement(-10, -10, 50, 50);
+
+    expect(
+      elementsOverlappingBBox({
+        bounds: bbox,
+        type: "overlap",
+        elements: [
+          rectOutside,
+          rectInside,
+          rectContainingBBox,
+          rectOverlappingTopLeft,
+        ],
+      }),
+    ).toEqual([rectInside, rectOverlappingTopLeft]);
+  });
+
+  it("should return elements inside/containing bbox", () => {
+    const bbox = makeBBox(0, 0, 100, 100);
+
+    const rectOutside = makeElement(110, 110, 100, 100);
+    const rectInside = makeElement(10, 10, 85, 85);
+    const rectContainingBBox = makeElement(-10, -10, 110, 110);
+    const rectOverlappingTopLeft = makeElement(-10, -10, 50, 50);
+
+    expect(
+      elementsOverlappingBBox({
+        bounds: bbox,
+        type: "contain",
+        elements: [
+          rectOutside,
+          rectInside,
+          rectContainingBBox,
+          rectOverlappingTopLeft,
+        ],
+      }),
+    ).toEqual([rectInside]);
+  });
+});

packages/element/tests/collision.test.tsx

@@ -0,0 +1,220 @@
+import { arrayToMap, reseed } from "@excalidraw/common";
+import { type GlobalPoint, type LocalPoint, pointFrom } from "@excalidraw/math";
+import { Excalidraw } from "@excalidraw/excalidraw";
+import { API } from "@excalidraw/excalidraw/tests/helpers/api";
+import { UI } from "@excalidraw/excalidraw/tests/helpers/ui";
+import "@excalidraw/utils/test-utils";
+import { render } from "@excalidraw/excalidraw/tests/test-utils";
+
+import * as distance from "../src/distance";
+import { hitElementItself } from "../src/collision";
+
+describe("check rotated elements can be hit:", () => {
+  beforeEach(async () => {
+    localStorage.clear();
+    reseed(7);
+    await render(<Excalidraw handleKeyboardGlobally={true} />);
+  });
+
+  it("arrow", () => {
+    UI.createElement("arrow", {
+      x: 0,
+      y: 0,
+      width: 124,
+      height: 302,
+      angle: 1.8700426423973724,
+      points: [
+        [0, 0],
+        [120, -198],
+        [-4, -302],
+      ] as LocalPoint[],
+    });
+    const hit = hitElementItself({
+      point: pointFrom<GlobalPoint>(88, -68),
+      element: window.h.elements[0],
+      threshold: 10,
+      elementsMap: window.h.scene.getNonDeletedElementsMap(),
+    });
+    expect(hit).toBe(true);
+  });
+});
+
+describe("hitElementItself cache", () => {
+  beforeEach(async () => {
+    // reset cache
+    hitElementItself({
+      point: pointFrom<GlobalPoint>(50, 50),
+      element: API.createElement({
+        type: "rectangle",
+        x: 0,
+        y: 0,
+        width: 100,
+        height: 100,
+        backgroundColor: "#ffffff",
+      }),
+      threshold: Infinity,
+      elementsMap: new Map([]),
+    });
+
+    localStorage.clear();
+    reseed(7);
+    await render(<Excalidraw handleKeyboardGlobally={true} />);
+  });
+
+  it("reuses cached result when threshold increases", () => {
+    const element = API.createElement({
+      type: "rectangle",
+      x: 0,
+      y: 0,
+      width: 100,
+      height: 100,
+      backgroundColor: "#ffffff",
+    });
+    const elementsMap = arrayToMap([element]);
+    const point = pointFrom<GlobalPoint>(100.5, 50);
+
+    const distanceSpy = jest.spyOn(distance, "distanceToElement");
+
+    expect(
+      hitElementItself({
+        point,
+        element,
+        threshold: 1,
+        elementsMap,
+      }),
+    ).toBe(true);
+
+    expect(distanceSpy).toHaveBeenCalledTimes(1);
+
+    expect(
+      hitElementItself({
+        point,
+        element,
+        threshold: 10,
+        elementsMap,
+      }),
+    ).toBe(true);
+
+    expect(distanceSpy).toHaveBeenCalledTimes(1);
+
+    distanceSpy.mockRestore();
+  });
+
+  it("does not reuse cache when threshold decreases", () => {
+    const element = API.createElement({
+      type: "rectangle",
+      x: 0,
+      y: 0,
+      width: 100,
+      height: 100,
+      backgroundColor: "transparent",
+    });
+    const elementsMap = arrayToMap([element]);
+    const point = pointFrom<GlobalPoint>(105, 50);
+
+    const distanceSpy = jest.spyOn(distance, "distanceToElement");
+
+    expect(
+      hitElementItself({
+        point,
+        element,
+        threshold: 10,
+        elementsMap,
+      }),
+    ).toBe(true);
+
+    expect(distanceSpy).toHaveBeenCalledTimes(1);
+
+    expect(
+      hitElementItself({
+        point,
+        element,
+        threshold: 6,
+        elementsMap,
+      }),
+    ).toBe(true);
+
+    expect(distanceSpy).toHaveBeenCalledTimes(2);
+    distanceSpy.mockRestore();
+  });
+
+  it("invalidates cache when element version changes", () => {
+    const element = API.createElement({
+      type: "rectangle",
+      x: 0,
+      y: 0,
+      width: 100,
+      height: 100,
+      backgroundColor: "#ffffff",
+    });
+    const elementsMap = arrayToMap([element]);
+    const point = pointFrom<GlobalPoint>(100.5, 50);
+
+    const distanceSpy = jest.spyOn(distance, "distanceToElement");
+
+    expect(
+      hitElementItself({
+        point,
+        element,
+        threshold: 1,
+        elementsMap,
+      }),
+    ).toBe(true);
+
+    expect(distanceSpy).toHaveBeenCalledTimes(1);
+
+    const movedElement = {
+      ...element,
+      version: element.version + 1,
+      versionNonce: element.versionNonce + 1,
+    };
+
+    expect(
+      hitElementItself({
+        point,
+        element: movedElement,
+        threshold: 1,
+        elementsMap,
+      }),
+    ).toBe(true);
+
+    expect(distanceSpy).toHaveBeenCalledTimes(2);
+    distanceSpy.mockRestore();
+  });
+
+  it("override does not affect caching", () => {
+    const element = API.createElement({
+      type: "rectangle",
+      x: 0,
+      y: 0,
+      width: 100,
+      height: 100,
+      backgroundColor: "transparent",
+    });
+    const elementsMap = arrayToMap([element]);
+    const point = pointFrom<GlobalPoint>(50, 50);
+
+    const distanceSpy = jest.spyOn(distance, "distanceToElement");
+
+    expect(
+      hitElementItself({
+        point,
+        element,
+        threshold: 10,
+        elementsMap,
+      }),
+    ).toBe(false);
+
+    expect(distanceSpy).toHaveBeenCalledTimes(1);
+
+    expect(
+      hitElementItself({
+        point,
+        element,
+        threshold: 10,
+        elementsMap,
+        overrideShouldTestInside: true,
+      }),
+    ).toBe(true);
+  });
+});

packages/element/tests/cropElement.test.tsx

@@ -0,0 +1,363 @@
+import React from "react";
+import { vi } from "vitest";
+
+import { KEYS, cloneJSON } from "@excalidraw/common";
+
+import {
+  Excalidraw,
+  exportToCanvas,
+  exportToSvg,
+} from "@excalidraw/excalidraw";
+import {
+  actionFlipHorizontal,
+  actionFlipVertical,
+} from "@excalidraw/excalidraw/actions";
+
+import { API } from "@excalidraw/excalidraw/tests/helpers/api";
+import { Keyboard, Pointer, UI } from "@excalidraw/excalidraw/tests/helpers/ui";
+import {
+  act,
+  GlobalTestState,
+  render,
+  unmountComponent,
+} from "@excalidraw/excalidraw/tests/test-utils";
+
+import type { NormalizedZoomValue } from "@excalidraw/excalidraw/types";
+
+import { duplicateElement } from "../src/duplicate";
+
+import type {
+  ExcalidrawImageElement,
+  ImageCrop,
+  NonDeleted,
+} from "../src/types";
+
+const { h } = window;
+const mouse = new Pointer("mouse");
+
+beforeEach(async () => {
+  unmountComponent();
+
+  mouse.reset();
+  localStorage.clear();
+  sessionStorage.clear();
+  vi.clearAllMocks();
+
+  Object.assign(document, {
+    elementFromPoint: () => GlobalTestState.canvas,
+  });
+  await render(<Excalidraw autoFocus={true} handleKeyboardGlobally={true} />);
+  API.setAppState({
+    zoom: {
+      value: 1 as NormalizedZoomValue,
+    },
+  });
+
+  const image = API.createElement({ type: "image", width: 200, height: 100 });
+  API.setElements([image]);
+  API.setAppState({
+    selectedElementIds: {
+      [image.id]: true,
+    },
+  });
+});
+
+const generateRandomNaturalWidthAndHeight = (image: ExcalidrawImageElement) => {
+  const initialWidth = image.width;
+  const initialHeight = image.height;
+
+  const scale = 1 + Math.random() * 5;
+
+  return {
+    naturalWidth: initialWidth * scale,
+    naturalHeight: initialHeight * scale,
+  };
+};
+
+const compareCrops = (cropA: ImageCrop, cropB: ImageCrop) => {
+  (Object.keys(cropA) as [keyof ImageCrop]).forEach((key) => {
+    const propA = cropA[key];
+    const propB = cropB[key];
+
+    expect(propA as number).toBeCloseTo(propB as number);
+  });
+};
+
+describe("Enter and leave the crop editor", () => {
+  it("enter the editor by double clicking", () => {
+    const image = h.elements[0];
+    expect(h.state.croppingElementId).toBe(null);
+    mouse.doubleClickOn(image);
+    expect(h.state.croppingElementId).not.toBe(null);
+    expect(h.state.croppingElementId).toBe(image.id);
+  });
+
+  it("enter the editor by pressing enter", () => {
+    const image = h.elements[0];
+    expect(h.state.croppingElementId).toBe(null);
+    Keyboard.keyDown(KEYS.ENTER);
+    expect(h.state.croppingElementId).not.toBe(null);
+    expect(h.state.croppingElementId).toBe(image.id);
+  });
+
+  it("leave the editor by clicking outside", () => {
+    const image = h.elements[0];
+    Keyboard.keyDown(KEYS.ENTER);
+    expect(h.state.croppingElementId).not.toBe(null);
+
+    mouse.click(image.x - 20, image.y - 20);
+    expect(h.state.croppingElementId).toBe(null);
+  });
+
+  it("leave the editor by pressing escape", () => {
+    const image = h.elements[0];
+    mouse.doubleClickOn(image);
+    expect(h.state.croppingElementId).not.toBe(null);
+
+    Keyboard.keyDown(KEYS.ESCAPE);
+    expect(h.state.croppingElementId).toBe(null);
+  });
+});
+
+describe("Crop an image", () => {
+  it("Cropping changes the dimension", async () => {
+    const image = h.elements[0] as ExcalidrawImageElement;
+
+    const initialWidth = image.width;
+    const initialHeight = image.height;
+
+    const { naturalWidth, naturalHeight } =
+      generateRandomNaturalWidthAndHeight(image);
+
+    UI.crop(image, "w", naturalWidth, naturalHeight, [initialWidth / 2, 0]);
+
+    expect(image.width).toBeLessThan(initialWidth);
+    UI.crop(image, "n", naturalWidth, naturalHeight, [0, initialHeight / 2]);
+    expect(image.height).toBeLessThan(initialHeight);
+  });
+
+  it("Cropping has minimal sizes", async () => {
+    const image = h.elements[0] as ExcalidrawImageElement;
+    const initialWidth = image.width;
+    const initialHeight = image.height;
+
+    const { naturalWidth, naturalHeight } =
+      generateRandomNaturalWidthAndHeight(image);
+
+    UI.crop(image, "w", naturalWidth, naturalHeight, [initialWidth, 0]);
+    expect(image.width).toBeLessThan(initialWidth);
+    expect(image.width).toBeGreaterThan(0);
+    UI.crop(image, "w", naturalWidth, naturalHeight, [-initialWidth, 0]);
+    UI.crop(image, "n", naturalWidth, naturalHeight, [0, initialHeight]);
+    expect(image.height).toBeLessThan(initialHeight);
+    expect(image.height).toBeGreaterThan(0);
+  });
+
+  it("Preserve aspect ratio", async () => {
+    let image = h.elements[0] as ExcalidrawImageElement;
+    const initialWidth = image.width;
+    const initialHeight = image.height;
+
+    const { naturalWidth, naturalHeight } =
+      generateRandomNaturalWidthAndHeight(image);
+
+    UI.crop(image, "w", naturalWidth, naturalHeight, [initialWidth / 3, 0]);
+
+    let resizedWidth = image.width;
+    let resizedHeight = image.height;
+
+    // max height, cropping should not change anything
+    UI.crop(
+      image,
+      "w",
+      naturalWidth,
+      naturalHeight,
+      [-initialWidth / 3, 0],
+      true,
+    );
+    expect(image.width).toBeCloseTo(resizedWidth, 10);
+    expect(image.height).toBeCloseTo(resizedHeight, 10);
+
+    // re-crop to initial state
+    UI.crop(image, "w", naturalWidth, naturalHeight, [-initialWidth / 3, 0]);
+    // change crop height and width
+    UI.crop(image, "s", naturalWidth, naturalHeight, [0, -initialHeight / 2]);
+    UI.crop(image, "e", naturalWidth, naturalHeight, [-initialWidth / 3, 0]);
+
+    resizedWidth = image.width;
+    resizedHeight = image.height;
+
+    // test corner handle aspect ratio preserving
+    UI.crop(image, "se", naturalWidth, naturalHeight, [initialWidth, 0], true);
+    expect(image.width / image.height).toBe(resizedWidth / resizedHeight);
+    expect(image.width).toBeLessThanOrEqual(initialWidth + 0.0001);
+    expect(image.height).toBeLessThanOrEqual(initialHeight + 0.0001);
+
+    // reset
+    image = API.createElement({ type: "image", width: 200, height: 100 });
+    API.setElements([image]);
+    API.setAppState({
+      selectedElementIds: {
+        [image.id]: true,
+      },
+    });
+
+    // 50 x 50 square
+    UI.crop(image, "nw", naturalWidth, naturalHeight, [150, 50]);
+    UI.crop(image, "n", naturalWidth, naturalHeight, [0, -100], true);
+    expect(image.width).toBeCloseTo(image.height);
+    // image is at the corner, not space to its right to expand, should not be able to resize
+    expect(image.height).toBeCloseTo(50);
+
+    UI.crop(image, "nw", naturalWidth, naturalHeight, [-150, -100], true);
+    expect(image.width).toBeCloseTo(image.height);
+    // max height should be reached
+    expect(image.height).toBeCloseTo(initialHeight);
+    expect(image.width).toBeCloseTo(initialHeight);
+  });
+});
+
+describe("Cropping and other features", async () => {
+  it("Cropping works independently of duplication", async () => {
+    const image = h.elements[0] as ExcalidrawImageElement;
+    const initialWidth = image.width;
+    const initialHeight = image.height;
+
+    const { naturalWidth, naturalHeight } =
+      generateRandomNaturalWidthAndHeight(image);
+
+    UI.crop(image, "nw", naturalWidth, naturalHeight, [
+      initialWidth / 2,
+      initialHeight / 2,
+    ]);
+    Keyboard.keyDown(KEYS.ESCAPE);
+    const duplicatedImage = duplicateElement(null, new Map(), image);
+    act(() => {
+      h.app.scene.insertElement(duplicatedImage);
+    });
+
+    expect(duplicatedImage.width).toBe(image.width);
+    expect(duplicatedImage.height).toBe(image.height);
+
+    UI.crop(duplicatedImage, "nw", naturalWidth, naturalHeight, [
+      -initialWidth / 2,
+      -initialHeight / 2,
+    ]);
+    expect(duplicatedImage.width).toBe(initialWidth);
+    expect(duplicatedImage.height).toBe(initialHeight);
+    const resizedWidth = image.width;
+    const resizedHeight = image.height;
+
+    expect(image.width).not.toBe(duplicatedImage.width);
+    expect(image.height).not.toBe(duplicatedImage.height);
+    UI.crop(duplicatedImage, "se", naturalWidth, naturalHeight, [
+      -initialWidth / 1.5,
+      -initialHeight / 1.5,
+    ]);
+    expect(duplicatedImage.width).not.toBe(initialWidth);
+    expect(image.width).toBe(resizedWidth);
+    expect(duplicatedImage.height).not.toBe(initialHeight);
+    expect(image.height).toBe(resizedHeight);
+  });
+
+  it("Resizing should not affect crop", async () => {
+    const image = h.elements[0] as ExcalidrawImageElement;
+    const initialWidth = image.width;
+    const initialHeight = image.height;
+
+    const { naturalWidth, naturalHeight } =
+      generateRandomNaturalWidthAndHeight(image);
+
+    UI.crop(image, "nw", naturalWidth, naturalHeight, [
+      initialWidth / 2,
+      initialHeight / 2,
+    ]);
+    const cropBeforeResizing = image.crop;
+    const cropBeforeResizingCloned = cloneJSON(image.crop) as ImageCrop;
+    expect(cropBeforeResizing).not.toBe(null);
+
+    UI.crop(image, "e", naturalWidth, naturalHeight, [200, 0]);
+    expect(cropBeforeResizing).toBe(image.crop);
+    compareCrops(cropBeforeResizingCloned, image.crop!);
+
+    UI.resize(image, "s", [0, -100]);
+    expect(cropBeforeResizing).toBe(image.crop);
+    compareCrops(cropBeforeResizingCloned, image.crop!);
+
+    UI.resize(image, "ne", [-50, -50]);
+    expect(cropBeforeResizing).toBe(image.crop);
+    compareCrops(cropBeforeResizingCloned, image.crop!);
+  });
+
+  it("Flipping does not change crop", async () => {
+    const image = h.elements[0] as ExcalidrawImageElement;
+    const initialWidth = image.width;
+    const initialHeight = image.height;
+
+    const { naturalWidth, naturalHeight } =
+      generateRandomNaturalWidthAndHeight(image);
+
+    mouse.doubleClickOn(image);
+    expect(h.state.croppingElementId).not.toBe(null);
+    UI.crop(image, "nw", naturalWidth, naturalHeight, [
+      initialWidth / 2,
+      initialHeight / 2,
+    ]);
+    Keyboard.keyDown(KEYS.ESCAPE);
+    const cropBeforeResizing = image.crop;
+    const cropBeforeResizingCloned = cloneJSON(image.crop) as ImageCrop;
+
+    API.executeAction(actionFlipHorizontal);
+    expect(image.crop).toBe(cropBeforeResizing);
+    compareCrops(cropBeforeResizingCloned, image.crop!);
+
+    API.executeAction(actionFlipVertical);
+    expect(image.crop).toBe(cropBeforeResizing);
+    compareCrops(cropBeforeResizingCloned, image.crop!);
+  });
+
+  it("Exports should preserve crops", async () => {
+    const image = h.elements[0] as NonDeleted<ExcalidrawImageElement>;
+    const initialWidth = image.width;
+    const initialHeight = image.height;
+
+    const { naturalWidth, naturalHeight } =
+      generateRandomNaturalWidthAndHeight(image);
+
+    mouse.doubleClickOn(image);
+    expect(h.state.croppingElementId).not.toBe(null);
+    UI.crop(image, "nw", naturalWidth, naturalHeight, [
+      initialWidth / 2,
+      initialHeight / 4,
+    ]);
+    Keyboard.keyDown(KEYS.ESCAPE);
+    const widthToHeightRatio = image.width / image.height;
+
+    const canvas = await exportToCanvas({
+      elements: [image],
+      // @ts-ignore
+      appState: h.state,
+      files: h.app.files,
+      exportPadding: 0,
+    });
+    const exportedCanvasRatio = canvas.width / canvas.height;
+
+    expect(widthToHeightRatio).toBeCloseTo(exportedCanvasRatio);
+
+    const svg = await exportToSvg({
+      elements: [image],
+      // @ts-ignore
+      appState: h.state,
+      files: h.app.files,
+      exportPadding: 0,
+    });
+    const svgWidth = svg.getAttribute("width");
+    const svgHeight = svg.getAttribute("height");
+
+    expect(svgWidth).toBeDefined();
+    expect(svgHeight).toBeDefined();
+
+    const exportedSvgRatio = Number(svgWidth) / Number(svgHeight);
+    expect(widthToHeightRatio).toBeCloseTo(exportedSvgRatio);
+  });
+});

packages/element/tests/delta.test.tsx

@@ -0,0 +1,853 @@
+import { API } from "@excalidraw/excalidraw/tests/helpers/api";
+import { arrayToMap } from "@excalidraw/common";
+import { pointFrom } from "@excalidraw/math";
+
+import type { ObservedAppState } from "@excalidraw/excalidraw/types";
+import type { LinearElementEditor } from "@excalidraw/element";
+import type {
+  ExcalidrawTextElement,
+  FractionalIndex,
+  SceneElementsMap,
+} from "@excalidraw/element/types";
+
+import { AppStateDelta, Delta, ElementsDelta } from "../src/delta";
+import { mutateElement, newElementWith } from "../src/mutateElement";
+
+describe("ElementsDelta", () => {
+  describe("visible changes", () => {
+    const apply = (before: SceneElementsMap, after: SceneElementsMap) =>
+      ElementsDelta.calculate(before, after).applyTo(before, before, {
+        excludedProperties: new Set(["version", "versionNonce"]),
+      });
+
+    const boundText = (
+      type: "rectangle" | "stickynote" | "arrow",
+      text = "",
+    ) => {
+      const container = API.createElement({
+        type,
+        id: "container",
+        index: "a0" as FractionalIndex,
+        width: 250,
+        height: type === "arrow" ? 0 : 250,
+        baseHeight: type === "stickynote" ? 250 : undefined,
+        points:
+          type === "arrow" ? [pointFrom(0, 0), pointFrom(250, 0)] : undefined,
+        boundElements: [{ id: "label", type: "text" }],
+      });
+      const label: ExcalidrawTextElement = {
+        ...API.createElement({
+          type: "text",
+          id: "label",
+          index: "a1" as FractionalIndex,
+          containerId: container.id,
+          fontSize: 20,
+          textAlign: "center",
+          verticalAlign: "middle",
+        }),
+        // API.createElement substitutes "test" for an empty string.
+        text,
+        originalText: text,
+      };
+      const before = arrayToMap([container, label]) as SceneElementsMap;
+      const after = arrayToMap([
+        newElementWith(container, { boundElements: [] }),
+        newElementWith(label, { isDeleted: true }),
+      ]) as SceneElementsMap;
+      return { container, label, before, after };
+    };
+
+    it.each(["rectangle", "stickynote"] as const)(
+      "ignores empty-label deletion and restoration on a %s",
+      (type) => {
+        const { before, after, container, label } = boundText(type);
+        const [deleted, deletionIsVisible] = apply(before, after);
+        expect(deletionIsVisible).toBe(false);
+        expect(deleted.get(label.id)?.isDeleted).toBe(true);
+        expect(deleted.get(container.id)?.boundElements).toEqual([]);
+
+        const [restored, restorationIsVisible] = apply(after, before);
+        expect(restorationIsVisible).toBe(false);
+        expect(restored.get(label.id)?.isDeleted).toBe(false);
+        expect(restored.get(container.id)?.boundElements).toEqual([
+          { id: label.id, type: "text" },
+        ]);
+      },
+    );
+
+    it("keeps deletion and restoration of nonempty labels visible", () => {
+      const { before, after } = boundText("stickynote", "hello");
+      expect(apply(before, after)[1]).toBe(true);
+      expect(apply(after, before)[1]).toBe(true);
+    });
+
+    it.each(["excluded", "already applied"])(
+      "ignores %s properties when deciding visibility",
+      (mode) => {
+        const element = API.createElement({
+          type: "rectangle",
+          index: "a0" as FractionalIndex,
+        });
+        const before = arrayToMap([element]) as SceneElementsMap;
+        const after = arrayToMap([
+          newElementWith(element, { strokeColor: "red" }),
+        ]) as SceneElementsMap;
+        const delta = ElementsDelta.calculate(before, after);
+        const current = mode === "excluded" ? before : after;
+        const [elements, isVisible] = delta.applyTo(current, current, {
+          excludedProperties: new Set([
+            "version",
+            "versionNonce",
+            ...(mode === "excluded" ? ["strokeColor" as const] : []),
+          ]),
+        });
+
+        expect(elements.get(element.id)?.strokeColor).toBe(
+          current.get(element.id)?.strokeColor,
+        );
+        expect(isVisible).toBe(false);
+      },
+    );
+
+    it("keeps snapshot restoration visible for a metadata-only update", () => {
+      const element = API.createElement({
+        type: "rectangle",
+        index: "a0" as FractionalIndex,
+      });
+      const before = arrayToMap([element]) as SceneElementsMap;
+      const after = arrayToMap([
+        newElementWith(element, { version: element.version + 1 }),
+      ]) as SceneElementsMap;
+      const delta = ElementsDelta.calculate(before, after);
+      const [elements, isVisible] = delta.applyTo(
+        new Map() as SceneElementsMap,
+        before,
+      );
+
+      expect(elements.get(element.id)?.isDeleted).toBe(false);
+      expect(isVisible).toBe(true);
+    });
+
+    it("keeps an arrow's empty-label gap visible", () => {
+      const { before, after } = boundText("arrow");
+      expect(apply(before, after)[1]).toBe(true);
+      expect(apply(after, before)[1]).toBe(true);
+    });
+
+    it("detects a container resized by restoring an empty label", () => {
+      const { container, label } = boundText("rectangle");
+      const smallContainer = newElementWith(container, {
+        width: 20,
+        height: 10,
+        boundElements: [],
+      });
+      const before = arrayToMap([
+        smallContainer,
+        newElementWith(label, { isDeleted: true }),
+      ]) as SceneElementsMap;
+      const after = arrayToMap([
+        newElementWith(smallContainer, {
+          boundElements: [{ id: label.id, type: "text" }],
+        }),
+        newElementWith(label, { isDeleted: false }),
+      ]) as SceneElementsMap;
+
+      const [elements, isVisible] = apply(before, after);
+      expect(elements.get(container.id)?.height).toBeGreaterThan(10);
+      expect(isVisible).toBe(true);
+    });
+
+    it("detects a bound label repositioned by a container's redraw", () => {
+      const { container, label } = boundText("rectangle", "hello");
+      const misplacedLabel = newElementWith(label, { x: -100, y: -100 });
+      const before = arrayToMap([
+        container,
+        misplacedLabel,
+      ]) as SceneElementsMap;
+      const after = arrayToMap([
+        newElementWith(container, { version: container.version + 1 }),
+        misplacedLabel,
+      ]) as SceneElementsMap;
+
+      const [elements, isVisible] = apply(before, after);
+      expect(elements.get(container.id)?.height).toBe(container.height);
+      expect(elements.get(label.id)?.x).not.toBe(-100);
+      expect(isVisible).toBe(true);
+    });
+
+    it("detects a bound arrow repositioned by a container's redraw", () => {
+      const container = API.createElement({
+        type: "rectangle",
+        id: "container",
+        index: "a0" as FractionalIndex,
+        boundElements: [{ id: "arrow", type: "arrow" }],
+      });
+      const arrow = API.createElement({
+        type: "arrow",
+        id: "arrow",
+        index: "a1" as FractionalIndex,
+        x: 200,
+        y: 50,
+        points: [pointFrom(0, 0), pointFrom(100, 0)],
+        startBinding: {
+          elementId: container.id,
+          mode: "orbit",
+          fixedPoint: [1, 0.5],
+        },
+      });
+      const before = arrayToMap([container, arrow]) as SceneElementsMap;
+      const after = arrayToMap([
+        newElementWith(container, { version: container.version + 1 }),
+        arrow,
+      ]) as SceneElementsMap;
+
+      const [elements, isVisible] = apply(before, after);
+      expect(elements.get(container.id)?.width).toBe(container.width);
+      expect(elements.get(arrow.id)?.x).not.toBe(200);
+      expect(isVisible).toBe(true);
+    });
+
+    it.each(["test", "development", "production"])(
+      "guards against untracked layout mutations in %s mode",
+      (mode) => {
+        const element = API.createElement({
+          type: "rectangle",
+          id: "changed",
+          index: "a0" as FractionalIndex,
+        });
+        const unrelated = API.createElement({
+          type: "rectangle",
+          id: "unrelated",
+          index: "a1" as FractionalIndex,
+        });
+        const before = arrayToMap([element, unrelated]) as SceneElementsMap;
+        const after = arrayToMap([
+          newElementWith(element, { strokeColor: "red" }),
+          unrelated,
+        ]) as SceneElementsMap;
+        // Simulate a future layout dependency missing from idsToCheck.
+        // Mutate the shared instance so the guard must snapshot version values.
+        const redraw = vi
+          .spyOn(ElementsDelta, "redrawElements")
+          .mockImplementationOnce((elements) => {
+            mutateElement(elements.get(unrelated.id)!, elements, {
+              x: unrelated.x + 1,
+            });
+            return elements;
+          });
+        const consoleError = vi
+          .spyOn(console, "error")
+          .mockImplementation(() => {});
+        vi.stubEnv("MODE", mode);
+
+        try {
+          if (mode === "production") {
+            expect(apply(before, after)[1]).toBe(true);
+            expect(consoleError).not.toHaveBeenCalled();
+          } else {
+            expect(() => apply(before, after)).toThrow(
+              'Redrawn element "unrelated" is missing from idsToCheck',
+            );
+          }
+        } finally {
+          redraw.mockRestore();
+          consoleError.mockRestore();
+          vi.unstubAllEnvs();
+        }
+      },
+    );
+
+    it("keeps an empty text element's arrow bindings visible", () => {
+      const label: ExcalidrawTextElement = {
+        ...API.createElement({
+          type: "text",
+          id: "label",
+          index: "a0" as FractionalIndex,
+          boundElements: [{ id: "arrow", type: "arrow" }],
+        }),
+        text: "",
+        originalText: "",
+      };
+      const arrow = API.createElement({
+        type: "arrow",
+        id: "arrow",
+        index: "a1" as FractionalIndex,
+        startBinding: {
+          elementId: label.id,
+          mode: "orbit",
+          fixedPoint: [1, 0.5],
+        },
+      });
+      const before = arrayToMap([label, arrow]) as SceneElementsMap;
+      const after = arrayToMap([
+        newElementWith(label, { isDeleted: true, boundElements: [] }),
+        newElementWith(arrow, { startBinding: null }),
+      ]) as SceneElementsMap;
+      expect(apply(before, after)[1]).toBe(true);
+    });
+  });
+
+  describe("elements delta calculation", () => {
+    it("should not throw when element gets removed but was already deleted", () => {
+      const element = API.createElement({
+        type: "rectangle",
+        x: 100,
+        y: 100,
+        isDeleted: true,
+      });
+
+      const prevElements = new Map([[element.id, element]]);
+      const nextElements = new Map();
+
+      expect(() =>
+        ElementsDelta.calculate(prevElements, nextElements),
+      ).not.toThrow();
+    });
+
+    it("should not throw when adding element as already deleted", () => {
+      const element = API.createElement({
+        type: "rectangle",
+        x: 100,
+        y: 100,
+        isDeleted: true,
+      });
+
+      const prevElements = new Map();
+      const nextElements = new Map([[element.id, element]]);
+
+      expect(() =>
+        ElementsDelta.calculate(prevElements, nextElements),
+      ).not.toThrow();
+    });
+
+    it("should create updated delta even when there is only version and versionNonce change", () => {
+      const baseElement = API.createElement({
+        type: "rectangle",
+        x: 100,
+        y: 100,
+        strokeColor: "#000000",
+        backgroundColor: "#ffffff",
+      });
+
+      const modifiedElement = {
+        ...baseElement,
+        version: baseElement.version + 1,
+        versionNonce: baseElement.versionNonce + 1,
+      };
+
+      // Create maps for the delta calculation
+      const prevElements = new Map([[baseElement.id, baseElement]]);
+      const nextElements = new Map([[modifiedElement.id, modifiedElement]]);
+
+      // Calculate the delta
+      const delta = ElementsDelta.calculate(
+        prevElements as SceneElementsMap,
+        nextElements as SceneElementsMap,
+      );
+
+      expect(delta).toEqual(
+        ElementsDelta.create(
+          {},
+          {},
+          {
+            [baseElement.id]: Delta.create(
+              {
+                version: baseElement.version,
+                versionNonce: baseElement.versionNonce,
+              },
+              {
+                version: baseElement.version + 1,
+                versionNonce: baseElement.versionNonce + 1,
+              },
+            ),
+          },
+        ),
+      );
+    });
+  });
+
+  describe("squash", () => {
+    it("should not squash when second delta is empty", () => {
+      const updatedDelta = Delta.create(
+        { x: 100, version: 1, versionNonce: 1 },
+        { x: 200, version: 2, versionNonce: 2 },
+      );
+
+      const elementsDelta1 = ElementsDelta.create(
+        {},
+        {},
+        { id1: updatedDelta },
+      );
+      const elementsDelta2 = ElementsDelta.empty();
+      const elementsDelta = elementsDelta1.squash(elementsDelta2);
+
+      expect(elementsDelta.isEmpty()).toBeFalsy();
+      expect(elementsDelta).toBe(elementsDelta1);
+      expect(elementsDelta.updated.id1).toBe(updatedDelta);
+    });
+
+    it("should squash mutually exclusive delta types", () => {
+      const addedDelta = Delta.create(
+        { x: 100, version: 1, versionNonce: 1, isDeleted: true },
+        { x: 200, version: 2, versionNonce: 2, isDeleted: false },
+      );
+
+      const removedDelta = Delta.create(
+        { x: 100, version: 1, versionNonce: 1, isDeleted: false },
+        { x: 200, version: 2, versionNonce: 2, isDeleted: true },
+      );
+
+      const updatedDelta = Delta.create(
+        { x: 100, version: 1, versionNonce: 1 },
+        { x: 200, version: 2, versionNonce: 2 },
+      );
+
+      const elementsDelta1 = ElementsDelta.create(
+        { id1: addedDelta },
+        { id2: removedDelta },
+        {},
+      );
+
+      const elementsDelta2 = ElementsDelta.create(
+        {},
+        {},
+        { id3: updatedDelta },
+      );
+
+      const elementsDelta = elementsDelta1.squash(elementsDelta2);
+
+      expect(elementsDelta.isEmpty()).toBeFalsy();
+      expect(elementsDelta).toBe(elementsDelta1);
+      expect(elementsDelta.added.id1).toBe(addedDelta);
+      expect(elementsDelta.removed.id2).toBe(removedDelta);
+      expect(elementsDelta.updated.id3).toBe(updatedDelta);
+    });
+
+    it("should squash the same delta types", () => {
+      const elementsDelta1 = ElementsDelta.create(
+        {
+          id1: Delta.create(
+            { x: 100, version: 1, versionNonce: 1, isDeleted: true },
+            { x: 200, version: 2, versionNonce: 2, isDeleted: false },
+          ),
+        },
+        {
+          id2: Delta.create(
+            { x: 100, version: 1, versionNonce: 1, isDeleted: false },
+            { x: 200, version: 2, versionNonce: 2, isDeleted: true },
+          ),
+        },
+        {
+          id3: Delta.create(
+            { x: 100, version: 1, versionNonce: 1 },
+            { x: 200, version: 2, versionNonce: 2 },
+          ),
+        },
+      );
+
+      const elementsDelta2 = ElementsDelta.create(
+        {
+          id1: Delta.create(
+            { y: 100, version: 2, versionNonce: 2, isDeleted: true },
+            { y: 200, version: 3, versionNonce: 3, isDeleted: false },
+          ),
+        },
+        {
+          id2: Delta.create(
+            { y: 100, version: 2, versionNonce: 2, isDeleted: false },
+            { y: 200, version: 3, versionNonce: 3, isDeleted: true },
+          ),
+        },
+        {
+          id3: Delta.create(
+            { y: 100, version: 2, versionNonce: 2 },
+            { y: 200, version: 3, versionNonce: 3 },
+          ),
+        },
+      );
+
+      const elementsDelta = elementsDelta1.squash(elementsDelta2);
+
+      expect(elementsDelta.isEmpty()).toBeFalsy();
+      expect(elementsDelta).toBe(elementsDelta1);
+      expect(elementsDelta.added.id1).toEqual(
+        Delta.create(
+          { x: 100, y: 100, version: 2, versionNonce: 2, isDeleted: true },
+          { x: 200, y: 200, version: 3, versionNonce: 3, isDeleted: false },
+        ),
+      );
+      expect(elementsDelta.removed.id2).toEqual(
+        Delta.create(
+          { x: 100, y: 100, version: 2, versionNonce: 2, isDeleted: false },
+          { x: 200, y: 200, version: 3, versionNonce: 3, isDeleted: true },
+        ),
+      );
+      expect(elementsDelta.updated.id3).toEqual(
+        Delta.create(
+          { x: 100, y: 100, version: 2, versionNonce: 2 },
+          { x: 200, y: 200, version: 3, versionNonce: 3 },
+        ),
+      );
+    });
+
+    it("should squash different delta types ", () => {
+      // id1: added   -> updated => added
+      // id2: removed -> added   => added
+      // id3: updated -> removed => removed
+      const elementsDelta1 = ElementsDelta.create(
+        {
+          id1: Delta.create(
+            { x: 100, version: 1, versionNonce: 1, isDeleted: true },
+            { x: 101, version: 2, versionNonce: 2, isDeleted: false },
+          ),
+        },
+        {
+          id2: Delta.create(
+            { x: 200, version: 1, versionNonce: 1, isDeleted: false },
+            { x: 201, version: 2, versionNonce: 2, isDeleted: true },
+          ),
+        },
+        {
+          id3: Delta.create(
+            { x: 300, version: 1, versionNonce: 1 },
+            { x: 301, version: 2, versionNonce: 2 },
+          ),
+        },
+      );
+
+      const elementsDelta2 = ElementsDelta.create(
+        {
+          id2: Delta.create(
+            { y: 200, version: 2, versionNonce: 2, isDeleted: true },
+            { y: 201, version: 3, versionNonce: 3, isDeleted: false },
+          ),
+        },
+        {
+          id3: Delta.create(
+            { y: 300, version: 2, versionNonce: 2, isDeleted: false },
+            { y: 301, version: 3, versionNonce: 3, isDeleted: true },
+          ),
+        },
+        {
+          id1: Delta.create(
+            { y: 100, version: 2, versionNonce: 2 },
+            { y: 101, version: 3, versionNonce: 3 },
+          ),
+        },
+      );
+
+      const elementsDelta = elementsDelta1.squash(elementsDelta2);
+
+      expect(elementsDelta.isEmpty()).toBeFalsy();
+      expect(elementsDelta).toBe(elementsDelta1);
+      expect(elementsDelta.added).toEqual({
+        id1: Delta.create(
+          { x: 100, y: 100, version: 2, versionNonce: 2, isDeleted: true },
+          { x: 101, y: 101, version: 3, versionNonce: 3, isDeleted: false },
+        ),
+        id2: Delta.create(
+          { x: 200, y: 200, version: 2, versionNonce: 2, isDeleted: true },
+          { x: 201, y: 201, version: 3, versionNonce: 3, isDeleted: false },
+        ),
+      });
+      expect(elementsDelta.removed).toEqual({
+        id3: Delta.create(
+          { x: 300, y: 300, version: 2, versionNonce: 2, isDeleted: false },
+          { x: 301, y: 301, version: 3, versionNonce: 3, isDeleted: true },
+        ),
+      });
+      expect(elementsDelta.updated).toEqual({});
+    });
+
+    it("should squash bound elements", () => {
+      const elementsDelta1 = ElementsDelta.create(
+        {},
+        {},
+        {
+          id1: Delta.create(
+            {
+              version: 1,
+              versionNonce: 1,
+              boundElements: [{ id: "t1", type: "text" }],
+            },
+            {
+              version: 2,
+              versionNonce: 2,
+              boundElements: [{ id: "t2", type: "text" }],
+            },
+          ),
+        },
+      );
+
+      const elementsDelta2 = ElementsDelta.create(
+        {},
+        {},
+        {
+          id1: Delta.create(
+            {
+              version: 2,
+              versionNonce: 2,
+              boundElements: [{ id: "a1", type: "arrow" }],
+            },
+            {
+              version: 3,
+              versionNonce: 3,
+              boundElements: [{ id: "a2", type: "arrow" }],
+            },
+          ),
+        },
+      );
+
+      const elementsDelta = elementsDelta1.squash(elementsDelta2);
+
+      expect(elementsDelta.updated.id1.deleted.boundElements).toEqual([
+        { id: "t1", type: "text" },
+        { id: "a1", type: "arrow" },
+      ]);
+      expect(elementsDelta.updated.id1.inserted.boundElements).toEqual([
+        { id: "t2", type: "text" },
+        { id: "a2", type: "arrow" },
+      ]);
+    });
+  });
+});
+
+describe("AppStateDelta", () => {
+  describe("ensure stable delta properties order", () => {
+    it("should maintain stable order for root properties", () => {
+      const name = "untitled scene";
+      const selectedLinearElement = {
+        elementId: "id1" as LinearElementEditor["elementId"],
+        isEditing: false,
+      };
+
+      const commonAppState = {
+        viewBackgroundColor: "#ffffff",
+        selectedElementIds: {},
+        selectedGroupIds: {},
+        editingGroupId: null,
+        croppingElementId: null,
+        editingLinearElementId: null,
+        selectedLinearElementIsEditing: null,
+        lockedMultiSelections: {},
+        activeLockedId: null,
+      };
+
+      const prevAppState1: ObservedAppState = {
+        ...commonAppState,
+        name: "",
+        selectedLinearElement: null,
+      };
+
+      const nextAppState1: ObservedAppState = {
+        ...commonAppState,
+        name,
+        selectedLinearElement,
+      };
+
+      const prevAppState2: ObservedAppState = {
+        selectedLinearElement: null,
+        name: "",
+        ...commonAppState,
+      };
+
+      const nextAppState2: ObservedAppState = {
+        selectedLinearElement,
+        name,
+        ...commonAppState,
+      };
+
+      const delta1 = AppStateDelta.calculate(prevAppState1, nextAppState1);
+      const delta2 = AppStateDelta.calculate(prevAppState2, nextAppState2);
+
+      expect(JSON.stringify(delta1)).toBe(JSON.stringify(delta2));
+    });
+
+    it("should maintain stable order for selectedElementIds", () => {
+      const commonAppState = {
+        name: "",
+        viewBackgroundColor: "#ffffff",
+        selectedGroupIds: {},
+        editingGroupId: null,
+        croppingElementId: null,
+        selectedLinearElement: null,
+        activeLockedId: null,
+        lockedMultiSelections: {},
+      };
+
+      const prevAppState1: ObservedAppState = {
+        ...commonAppState,
+        selectedElementIds: { id5: true, id2: true, id4: true },
+      };
+
+      const nextAppState1: ObservedAppState = {
+        ...commonAppState,
+        selectedElementIds: {
+          id1: true,
+          id2: true,
+          id3: true,
+        },
+      };
+
+      const prevAppState2: ObservedAppState = {
+        ...commonAppState,
+        selectedElementIds: { id4: true, id2: true, id5: true },
+      };
+
+      const nextAppState2: ObservedAppState = {
+        ...commonAppState,
+        selectedElementIds: {
+          id3: true,
+          id2: true,
+          id1: true,
+        },
+      };
+
+      const delta1 = AppStateDelta.calculate(prevAppState1, nextAppState1);
+      const delta2 = AppStateDelta.calculate(prevAppState2, nextAppState2);
+
+      expect(JSON.stringify(delta1)).toBe(JSON.stringify(delta2));
+    });
+
+    it("should maintain stable order for selectedGroupIds", () => {
+      const commonAppState = {
+        name: "",
+        viewBackgroundColor: "#ffffff",
+        selectedElementIds: {},
+        editingGroupId: null,
+        croppingElementId: null,
+        selectedLinearElement: null,
+        activeLockedId: null,
+        lockedMultiSelections: {},
+      };
+
+      const prevAppState1: ObservedAppState = {
+        ...commonAppState,
+        selectedGroupIds: { id5: false, id2: true, id4: true, id0: true },
+      };
+
+      const nextAppState1: ObservedAppState = {
+        ...commonAppState,
+        selectedGroupIds: {
+          id0: true,
+          id1: true,
+          id2: false,
+          id3: true,
+        },
+      };
+
+      const prevAppState2: ObservedAppState = {
+        ...commonAppState,
+        selectedGroupIds: { id0: true, id4: true, id2: true, id5: false },
+      };
+
+      const nextAppState2: ObservedAppState = {
+        ...commonAppState,
+        selectedGroupIds: {
+          id3: true,
+          id2: false,
+          id1: true,
+          id0: true,
+        },
+      };
+
+      const delta1 = AppStateDelta.calculate(prevAppState1, nextAppState1);
+      const delta2 = AppStateDelta.calculate(prevAppState2, nextAppState2);
+
+      expect(JSON.stringify(delta1)).toBe(JSON.stringify(delta2));
+    });
+  });
+
+  describe("squash", () => {
+    it("should not squash when second delta is empty", () => {
+      const delta = Delta.create(
+        { name: "untitled scene" },
+        { name: "titled scene" },
+      );
+
+      const appStateDelta1 = AppStateDelta.create(delta);
+      const appStateDelta2 = AppStateDelta.empty();
+      const appStateDelta = appStateDelta1.squash(appStateDelta2);
+
+      expect(appStateDelta.isEmpty()).toBeFalsy();
+      expect(appStateDelta).toBe(appStateDelta1);
+      expect(appStateDelta.delta).toBe(delta);
+    });
+
+    it("should squash exclusive properties", () => {
+      const delta1 = Delta.create(
+        { name: "untitled scene" },
+        { name: "titled scene" },
+      );
+      const delta2 = Delta.create(
+        { viewBackgroundColor: "#ffffff" },
+        { viewBackgroundColor: "#000000" },
+      );
+
+      const appStateDelta1 = AppStateDelta.create(delta1);
+      const appStateDelta2 = AppStateDelta.create(delta2);
+      const appStateDelta = appStateDelta1.squash(appStateDelta2);
+
+      expect(appStateDelta.isEmpty()).toBeFalsy();
+      expect(appStateDelta).toBe(appStateDelta1);
+      expect(appStateDelta.delta).toEqual(
+        Delta.create(
+          { name: "untitled scene", viewBackgroundColor: "#ffffff" },
+          { name: "titled scene", viewBackgroundColor: "#000000" },
+        ),
+      );
+    });
+
+    it("should squash selectedElementIds, selectedGroupIds and lockedMultiSelections", () => {
+      const delta1 = Delta.create<Partial<ObservedAppState>>(
+        {
+          name: "untitled scene",
+          selectedElementIds: { id1: true },
+          selectedGroupIds: {},
+          lockedMultiSelections: { g1: true },
+        },
+        {
+          name: "titled scene",
+          selectedElementIds: { id2: true },
+          selectedGroupIds: { g1: true },
+          lockedMultiSelections: {},
+        },
+      );
+      const delta2 = Delta.create<Partial<ObservedAppState>>(
+        {
+          selectedElementIds: { id3: true },
+          selectedGroupIds: { g1: true },
+          lockedMultiSelections: {},
+        },
+        {
+          selectedElementIds: { id2: true },
+          selectedGroupIds: { g2: true, g3: true },
+          lockedMultiSelections: { g3: true },
+        },
+      );
+
+      const appStateDelta1 = AppStateDelta.create(delta1);
+      const appStateDelta2 = AppStateDelta.create(delta2);
+      const appStateDelta = appStateDelta1.squash(appStateDelta2);
+
+      expect(appStateDelta.isEmpty()).toBeFalsy();
+      expect(appStateDelta).toBe(appStateDelta1);
+      expect(appStateDelta.delta).toEqual(
+        Delta.create<Partial<ObservedAppState>>(
+          {
+            name: "untitled scene",
+            selectedElementIds: { id1: true, id3: true },
+            selectedGroupIds: { g1: true },
+            lockedMultiSelections: { g1: true },
+          },
+          {
+            name: "titled scene",
+            selectedElementIds: { id2: true },
+            selectedGroupIds: { g1: true, g2: true, g3: true },
+            lockedMultiSelections: { g3: true },
+          },
+        ),
+      );
+    });
+  });
+});

packages/element/tests/distribute.test.tsx

@@ -0,0 +1,128 @@
+import {
+  distributeHorizontally,
+  distributeVertically,
+} from "@excalidraw/excalidraw/actions";
+import { defaultLang, setLanguage } from "@excalidraw/excalidraw/i18n";
+import { Excalidraw } from "@excalidraw/excalidraw";
+
+import { API } from "@excalidraw/excalidraw/tests/helpers/api";
+import { UI, Pointer, Keyboard } from "@excalidraw/excalidraw/tests/helpers/ui";
+import {
+  act,
+  unmountComponent,
+  render,
+} from "@excalidraw/excalidraw/tests/test-utils";
+
+const mouse = new Pointer("mouse");
+
+// Scenario: three rectangles that will be distributed with gaps
+const createAndSelectThreeRectanglesWithGap = () => {
+  UI.clickTool("rectangle");
+  mouse.down();
+  mouse.up(100, 100);
+  mouse.reset();
+
+  UI.clickTool("rectangle");
+  mouse.down(10, 10);
+  mouse.up(100, 100);
+  mouse.reset();
+
+  UI.clickTool("rectangle");
+  mouse.down(300, 300);
+  mouse.up(100, 100);
+  mouse.reset();
+
+  // Last rectangle is selected by default
+  Keyboard.withModifierKeys({ shift: true }, () => {
+    mouse.click(0, 10);
+    mouse.click(10, 0);
+  });
+};
+
+// Scenario: three rectangles that will be distributed by their centers
+const createAndSelectThreeRectanglesWithoutGap = () => {
+  UI.clickTool("rectangle");
+  mouse.down();
+  mouse.up(100, 100);
+  mouse.reset();
+
+  UI.clickTool("rectangle");
+  mouse.down(10, 10);
+  mouse.up(200, 200);
+  mouse.reset();
+
+  UI.clickTool("rectangle");
+  mouse.down(200, 200);
+  mouse.up(100, 100);
+  mouse.reset();
+
+  // Last rectangle is selected by default
+  Keyboard.withModifierKeys({ shift: true }, () => {
+    mouse.click(0, 10);
+    mouse.click(10, 0);
+  });
+};
+
+describe("distributing", () => {
+  beforeEach(async () => {
+    unmountComponent();
+    mouse.reset();
+
+    await act(() => {
+      return setLanguage(defaultLang);
+    });
+    await render(<Excalidraw handleKeyboardGlobally={true} />);
+  });
+
+  it("should distribute selected elements horizontally", async () => {
+    createAndSelectThreeRectanglesWithGap();
+    expect(API.getSelectedElements()[0].x).toEqual(0);
+    expect(API.getSelectedElements()[1].x).toEqual(10);
+    expect(API.getSelectedElements()[2].x).toEqual(300);
+
+    API.executeAction(distributeHorizontally);
+
+    expect(API.getSelectedElements()[0].x).toEqual(0);
+    expect(API.getSelectedElements()[1].x).toEqual(150);
+    expect(API.getSelectedElements()[2].x).toEqual(300);
+  });
+
+  it("should distribute selected elements vertically", async () => {
+    createAndSelectThreeRectanglesWithGap();
+    expect(API.getSelectedElements()[0].y).toEqual(0);
+    expect(API.getSelectedElements()[1].y).toEqual(10);
+    expect(API.getSelectedElements()[2].y).toEqual(300);
+
+    API.executeAction(distributeVertically);
+
+    expect(API.getSelectedElements()[0].y).toEqual(0);
+    expect(API.getSelectedElements()[1].y).toEqual(150);
+    expect(API.getSelectedElements()[2].y).toEqual(300);
+  });
+
+  it("should distribute selected elements horizontally based on their centers", async () => {
+    createAndSelectThreeRectanglesWithoutGap();
+    expect(API.getSelectedElements()[0].x).toEqual(0);
+    expect(API.getSelectedElements()[1].x).toEqual(10);
+    expect(API.getSelectedElements()[2].x).toEqual(200);
+
+    API.executeAction(distributeHorizontally);
+
+    expect(API.getSelectedElements()[0].x).toEqual(0);
+    expect(API.getSelectedElements()[1].x).toEqual(50);
+    expect(API.getSelectedElements()[2].x).toEqual(200);
+  });
+
+  it("should distribute selected elements vertically with based on their centers", async () => {
+    createAndSelectThreeRectanglesWithoutGap();
+    expect(API.getSelectedElements()[0].y).toEqual(0);
+    expect(API.getSelectedElements()[1].y).toEqual(10);
+    expect(API.getSelectedElements()[2].y).toEqual(200);
+
+    API.executeAction(distributeVertically);
+
+    expect(API.getSelectedElements()[0].y).toEqual(0);
+    expect(API.getSelectedElements()[1].y).toEqual(50);
+    expect(API.getSelectedElements()[2].y).toEqual(200);
+  });
+});

packages/element/tests/duplicate.test.tsx

@@ -0,0 +1,865 @@
+import { pointFrom } from "@excalidraw/math";
+
+import {
+  FONT_FAMILY,
+  ORIG_ID,
+  ROUNDNESS,
+  isPrimitive,
+  getUpdatedTimestamp,
+} from "@excalidraw/common";
+
+import { Excalidraw, mutateElement } from "@excalidraw/excalidraw";
+
+import { actionDuplicateSelection } from "@excalidraw/excalidraw/actions";
+
+import { API } from "@excalidraw/excalidraw/tests/helpers/api";
+
+import { UI, Keyboard, Pointer } from "@excalidraw/excalidraw/tests/helpers/ui";
+
+import {
+  act,
+  assertElements,
+  getCloneByOrigId,
+  render,
+} from "@excalidraw/excalidraw/tests/test-utils";
+
+import type { LocalPoint } from "@excalidraw/math";
+
+import {
+  deepCopyElement,
+  duplicateElement,
+  duplicateElements,
+} from "../src/duplicate";
+
+import type { ExcalidrawLinearElement } from "../src/types";
+
+const { h } = window;
+const mouse = new Pointer("mouse");
+
+const assertCloneObjects = (source: any, clone: any) => {
+  for (const key in clone) {
+    if (clone.hasOwnProperty(key) && !isPrimitive(clone[key])) {
+      expect(clone[key]).not.toBe(source[key]);
+      if (source[key]) {
+        assertCloneObjects(source[key], clone[key]);
+      }
+    }
+  }
+};
+
+describe("duplicating single elements", () => {
+  it.each([123, 0, null])(
+    "preserves created=%s on a deep copy and resets it for a new instance",
+    (created) => {
+      const element = API.createElement({ type: "rectangle", created });
+      const cloned = deepCopyElement(element);
+      const duplicate = duplicateElement(null, new Map(), element);
+
+      expect(cloned).toEqual(element);
+      expect(duplicate).toMatchObject({
+        created: getUpdatedTimestamp(),
+        version: element.version,
+        versionNonce: element.versionNonce,
+      });
+      expect(duplicate.id).not.toBe(element.id);
+      expect(element.created).toBe(created);
+    },
+  );
+
+  it("clones arrow element", () => {
+    const element = API.createElement({
+      type: "arrow",
+      x: 0,
+      y: 0,
+      strokeColor: "#000000",
+      backgroundColor: "transparent",
+      fillStyle: "hachure",
+      strokeWidth: 1,
+      strokeStyle: "solid",
+      roundness: { type: ROUNDNESS.PROPORTIONAL_RADIUS },
+      roughness: 1,
+      opacity: 100,
+    });
+
+    // @ts-ignore
+    element.__proto__ = { hello: "world" };
+
+    mutateElement(element, new Map(), {
+      points: [pointFrom<LocalPoint>(1, 2), pointFrom<LocalPoint>(3, 4)],
+    });
+
+    const copy = duplicateElement(null, new Map(), element, true);
+
+    assertCloneObjects(element, copy);
+
+    // assert we clone the object's prototype
+    // @ts-ignore
+    expect(copy.__proto__).toEqual({ hello: "world" });
+    expect(copy.hasOwnProperty("hello")).toBe(false);
+
+    expect(copy.points).not.toBe(element.points);
+    expect(copy).not.toHaveProperty("shape");
+    expect(copy.id).not.toBe(element.id);
+    expect(typeof copy.id).toBe("string");
+    expect(copy.seed).not.toBe(element.seed);
+    expect(typeof copy.seed).toBe("number");
+    expect(copy).toEqual({
+      ...element,
+      id: copy.id,
+      seed: copy.seed,
+      version: copy.version,
+      versionNonce: copy.versionNonce,
+    });
+  });
+
+  it("clones text element", () => {
+    const element = API.createElement({
+      type: "text",
+      x: 0,
+      y: 0,
+      strokeColor: "#000000",
+      backgroundColor: "transparent",
+      fillStyle: "hachure",
+      strokeWidth: 1,
+      strokeStyle: "solid",
+      roundness: null,
+      roughness: 1,
+      opacity: 100,
+      text: "hello",
+      fontSize: 20,
+      fontFamily: FONT_FAMILY.Virgil,
+      textAlign: "left",
+      verticalAlign: "top",
+    });
+
+    const copy = duplicateElement(null, new Map(), element);
+
+    assertCloneObjects(element, copy);
+
+    expect(copy).not.toHaveProperty("points");
+    expect(copy).not.toHaveProperty("shape");
+    expect(copy.id).not.toBe(element.id);
+    expect(typeof copy.id).toBe("string");
+    expect(typeof copy.seed).toBe("number");
+  });
+});
+
+describe("duplicating multiple elements", () => {
+  it("duplicateElements should clone bindings", () => {
+    const rectangle1 = API.createElement({
+      type: "rectangle",
+      id: "rectangle1",
+      boundElements: [
+        { id: "arrow1", type: "arrow" },
+        { id: "arrow2", type: "arrow" },
+        { id: "text1", type: "text" },
+      ],
+    });
+
+    const text1 = API.createElement({
+      type: "text",
+      id: "text1",
+      containerId: "rectangle1",
+    });
+
+    const arrow1 = API.createElement({
+      type: "arrow",
+      id: "arrow1",
+      startBinding: {
+        elementId: "rectangle1",
+        fixedPoint: [0.5, 1],
+        mode: "orbit",
+      },
+    });
+
+    const arrow2 = API.createElement({
+      type: "arrow",
+      id: "arrow2",
+      endBinding: {
+        elementId: "rectangle1",
+        fixedPoint: [0.5, 1],
+        mode: "orbit",
+      },
+      boundElements: [{ id: "text2", type: "text" }],
+    });
+
+    const text2 = API.createElement({
+      type: "text",
+      id: "text2",
+      containerId: "arrow2",
+    });
+
+    // -------------------------------------------------------------------------
+
+    const origElements = [rectangle1, text1, arrow1, arrow2, text2] as const;
+    const { duplicatedElements } = duplicateElements({
+      type: "everything",
+      elements: origElements,
+    });
+
+    // generic id in-equality checks
+    // --------------------------------------------------------------------------
+    expect(origElements.map((e) => e.type)).toEqual(
+      duplicatedElements.map((e) => e.type),
+    );
+    origElements.forEach((origElement, idx) => {
+      const clonedElement = duplicatedElements[idx];
+      expect(origElement).toEqual(
+        expect.objectContaining({
+          id: expect.not.stringMatching(clonedElement.id),
+          type: clonedElement.type,
+        }),
+      );
+      if ("containerId" in origElement) {
+        expect(origElement.containerId).not.toBe(
+          (clonedElement as any).containerId,
+        );
+      }
+      if ("endBinding" in origElement) {
+        if (origElement.endBinding) {
+          expect(origElement.endBinding.elementId).not.toBe(
+            (clonedElement as any).endBinding?.elementId,
+          );
+        } else {
+          expect((clonedElement as any).endBinding).toBeNull();
+        }
+      }
+      if ("startBinding" in origElement) {
+        if (origElement.startBinding) {
+          expect(origElement.startBinding.elementId).not.toBe(
+            (clonedElement as any).startBinding?.elementId,
+          );
+        } else {
+          expect((clonedElement as any).startBinding).toBeNull();
+        }
+      }
+    });
+    // --------------------------------------------------------------------------
+
+    const clonedArrows = duplicatedElements.filter(
+      (e) => e.type === "arrow",
+    ) as ExcalidrawLinearElement[];
+
+    const [clonedRectangle, clonedText1, , clonedArrow2, clonedArrowLabel] =
+      duplicatedElements as any as typeof origElements;
+
+    expect(clonedText1.containerId).toBe(clonedRectangle.id);
+    expect(
+      clonedRectangle.boundElements!.find((e) => e.id === clonedText1.id),
+    ).toEqual(
+      expect.objectContaining({
+        id: clonedText1.id,
+        type: clonedText1.type,
+      }),
+    );
+    expect(clonedRectangle.type).toBe("rectangle");
+
+    clonedArrows.forEach((arrow) => {
+      expect(
+        clonedRectangle.boundElements!.find((e) => e.id === arrow.id),
+      ).toEqual(
+        expect.objectContaining({
+          id: arrow.id,
+          type: arrow.type,
+        }),
+      );
+
+      if (arrow.endBinding) {
+        expect(arrow.endBinding.elementId).toBe(clonedRectangle.id);
+      }
+      if (arrow.startBinding) {
+        expect(arrow.startBinding.elementId).toBe(clonedRectangle.id);
+      }
+    });
+
+    expect(clonedArrow2.boundElements).toEqual([
+      { type: "text", id: clonedArrowLabel.id },
+    ]);
+    expect(clonedArrowLabel.containerId).toBe(clonedArrow2.id);
+  });
+
+  it("should remove id references of elements that aren't found", () => {
+    const rectangle1 = API.createElement({
+      type: "rectangle",
+      id: "rectangle1",
+      boundElements: [
+        // should keep
+        { id: "arrow1", type: "arrow" },
+        // should drop
+        { id: "arrow-not-exists", type: "arrow" },
+        // should drop
+        { id: "text-not-exists", type: "text" },
+      ],
+    });
+
+    const arrow1 = API.createElement({
+      type: "arrow",
+      id: "arrow1",
+      startBinding: {
+        elementId: "rectangle1",
+        fixedPoint: [0.5, 1],
+        mode: "orbit",
+      },
+    });
+
+    const text1 = API.createElement({
+      type: "text",
+      id: "text1",
+      containerId: "rectangle-not-exists",
+    });
+
+    const arrow2 = API.createElement({
+      type: "arrow",
+      id: "arrow2",
+      startBinding: {
+        elementId: "rectangle1",
+        fixedPoint: [0.5, 1],
+        mode: "orbit",
+      },
+      endBinding: {
+        elementId: "rectangle-not-exists",
+        fixedPoint: [0.5, 1],
+        mode: "orbit",
+      },
+    });
+
+    const arrow3 = API.createElement({
+      type: "arrow",
+      id: "arrow3",
+      startBinding: {
+        elementId: "rectangle-not-exists",
+        fixedPoint: [0.5, 1],
+        mode: "orbit",
+      },
+      endBinding: {
+        elementId: "rectangle1",
+        fixedPoint: [0.5, 1],
+        mode: "orbit",
+      },
+    });
+
+    // -------------------------------------------------------------------------
+
+    const origElements = [rectangle1, text1, arrow1, arrow2, arrow3] as const;
+    const duplicatedElements = duplicateElements({
+      type: "everything",
+      elements: origElements,
+    }).duplicatedElements as any as typeof origElements;
+
+    const [
+      clonedRectangle,
+      clonedText1,
+      clonedArrow1,
+      clonedArrow2,
+      clonedArrow3,
+    ] = duplicatedElements;
+
+    expect(clonedRectangle.boundElements).toEqual([
+      { id: clonedArrow1.id, type: "arrow" },
+    ]);
+
+    expect(clonedText1.containerId).toBe(null);
+
+    expect(clonedArrow2.startBinding).toEqual({
+      ...arrow2.startBinding,
+      elementId: clonedRectangle.id,
+    });
+    expect(clonedArrow2.endBinding).toBe(null);
+    expect(clonedArrow3.startBinding).toBe(null);
+    expect(clonedArrow3.endBinding).toEqual({
+      ...arrow3.endBinding,
+      elementId: clonedRectangle.id,
+    });
+  });
+
+  describe("should duplicate all group ids", () => {
+    it("should regenerate all group ids and keep them consistent across elements", () => {
+      const rectangle1 = API.createElement({
+        type: "rectangle",
+        groupIds: ["g1"],
+      });
+      const rectangle2 = API.createElement({
+        type: "rectangle",
+        groupIds: ["g2", "g1"],
+      });
+      const rectangle3 = API.createElement({
+        type: "rectangle",
+        groupIds: ["g2", "g1"],
+      });
+
+      const origElements = [rectangle1, rectangle2, rectangle3] as const;
+      const { duplicatedElements } = duplicateElements({
+        type: "everything",
+        elements: origElements,
+      });
+      const [clonedRectangle1, clonedRectangle2, clonedRectangle3] =
+        duplicatedElements;
+
+      expect(rectangle1.groupIds[0]).not.toBe(clonedRectangle1.groupIds[0]);
+      expect(rectangle2.groupIds[0]).not.toBe(clonedRectangle2.groupIds[0]);
+      expect(rectangle2.groupIds[1]).not.toBe(clonedRectangle2.groupIds[1]);
+
+      expect(clonedRectangle1.groupIds[0]).toBe(clonedRectangle2.groupIds[1]);
+      expect(clonedRectangle2.groupIds[0]).toBe(clonedRectangle3.groupIds[0]);
+      expect(clonedRectangle2.groupIds[1]).toBe(clonedRectangle3.groupIds[1]);
+    });
+
+    it("should keep and regenerate ids of groups even if invalid", () => {
+      // lone element shouldn't be able to be grouped with itself,
+      // but hard to check against in a performant way so we ignore it
+      const rectangle1 = API.createElement({
+        type: "rectangle",
+        groupIds: ["g1"],
+      });
+
+      const {
+        duplicatedElements: [clonedRectangle1],
+      } = duplicateElements({ type: "everything", elements: [rectangle1] });
+
+      expect(typeof clonedRectangle1.groupIds[0]).toBe("string");
+      expect(rectangle1.groupIds[0]).not.toBe(clonedRectangle1.groupIds[0]);
+    });
+  });
+});
+
+describe("group-related duplication", () => {
+  beforeEach(async () => {
+    await render(<Excalidraw />);
+  });
+
+  it("action-duplicating within group", async () => {
+    const rectangle1 = API.createElement({
+      type: "rectangle",
+      x: 0,
+      y: 0,
+      groupIds: ["group1"],
+    });
+    const rectangle2 = API.createElement({
+      type: "rectangle",
+      x: 10,
+      y: 10,
+      groupIds: ["group1"],
+    });
+
+    API.setElements([rectangle1, rectangle2]);
+    API.setSelectedElements([rectangle2], "group1");
+
+    act(() => {
+      h.app.actionManager.executeAction(actionDuplicateSelection);
+    });
+
+    assertElements(h.elements, [
+      { id: rectangle1.id },
+      { id: rectangle2.id },
+      { [ORIG_ID]: rectangle2.id, selected: true, groupIds: ["group1"] },
+    ]);
+    expect(h.state.editingGroupId).toBe("group1");
+  });
+
+  it("alt-duplicating within group", async () => {
+    const rectangle1 = API.createElement({
+      type: "rectangle",
+      x: 0,
+      y: 0,
+      groupIds: ["group1"],
+    });
+    const rectangle2 = API.createElement({
+      type: "rectangle",
+      x: 10,
+      y: 10,
+      groupIds: ["group1"],
+    });
+
+    API.setElements([rectangle1, rectangle2]);
+    API.setSelectedElements([rectangle2], "group1");
+
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      mouse.down(rectangle2.x + 5, rectangle2.y + 5);
+      mouse.up(rectangle2.x + 50, rectangle2.y + 50);
+    });
+
+    assertElements(h.elements, [
+      { id: rectangle1.id },
+      { id: rectangle2.id },
+      { [ORIG_ID]: rectangle2.id, selected: true, groupIds: ["group1"] },
+    ]);
+    expect(h.state.editingGroupId).toBe("group1");
+  });
+
+  it("alt-duplicating within group away outside frame", () => {
+    const frame = API.createElement({
+      type: "frame",
+      x: 0,
+      y: 0,
+      width: 100,
+      height: 100,
+    });
+    const rectangle1 = API.createElement({
+      type: "rectangle",
+      x: 0,
+      y: 0,
+      width: 50,
+      height: 50,
+      groupIds: ["group1"],
+      frameId: frame.id,
+    });
+    const rectangle2 = API.createElement({
+      type: "rectangle",
+      x: 10,
+      y: 10,
+      width: 50,
+      height: 50,
+      groupIds: ["group1"],
+      frameId: frame.id,
+    });
+
+    API.setElements([frame, rectangle1, rectangle2]);
+    API.setSelectedElements([rectangle2], "group1");
+
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      mouse.down(rectangle2.x + 5, rectangle2.y + 5);
+      mouse.up(frame.x + frame.width + 50, frame.y + frame.height + 50);
+    });
+
+    assertElements(h.elements, [
+      { id: frame.id },
+      { id: rectangle1.id, frameId: frame.id },
+      { id: rectangle2.id, frameId: frame.id },
+      { [ORIG_ID]: rectangle2.id, selected: true, groupIds: [], frameId: null },
+    ]);
+    expect(h.state.editingGroupId).toBe(null);
+  });
+});
+
+describe("duplication z-order", () => {
+  beforeEach(async () => {
+    await render(<Excalidraw />);
+  });
+
+  it("duplication z order with Cmd+D for the lowest z-ordered element should be +1 for the clone", () => {
+    const rectangle1 = API.createElement({
+      type: "rectangle",
+      x: 0,
+      y: 0,
+    });
+    const rectangle2 = API.createElement({
+      type: "rectangle",
+      x: 10,
+      y: 10,
+    });
+    const rectangle3 = API.createElement({
+      type: "rectangle",
+      x: 20,
+      y: 20,
+    });
+
+    API.setElements([rectangle1, rectangle2, rectangle3]);
+    API.setSelectedElements([rectangle1]);
+
+    act(() => {
+      h.app.actionManager.executeAction(actionDuplicateSelection);
+    });
+
+    assertElements(h.elements, [
+      { id: rectangle1.id },
+      { [ORIG_ID]: rectangle1.id, selected: true },
+      { id: rectangle2.id },
+      { id: rectangle3.id },
+    ]);
+  });
+
+  it("duplication z order with Cmd+D  for the highest z-ordered element should be +1 for the clone", () => {
+    const rectangle1 = API.createElement({
+      type: "rectangle",
+      x: 0,
+      y: 0,
+    });
+    const rectangle2 = API.createElement({
+      type: "rectangle",
+      x: 10,
+      y: 10,
+    });
+    const rectangle3 = API.createElement({
+      type: "rectangle",
+      x: 20,
+      y: 20,
+    });
+
+    API.setElements([rectangle1, rectangle2, rectangle3]);
+    API.setSelectedElements([rectangle3]);
+
+    act(() => {
+      h.app.actionManager.executeAction(actionDuplicateSelection);
+    });
+
+    assertElements(h.elements, [
+      { id: rectangle1.id },
+      { id: rectangle2.id },
+      { id: rectangle3.id },
+      { [ORIG_ID]: rectangle3.id, selected: true },
+    ]);
+  });
+
+  it("duplication z order with alt+drag for the lowest z-ordered element should be +1 for the clone", () => {
+    const rectangle1 = API.createElement({
+      type: "rectangle",
+      x: 0,
+      y: 0,
+    });
+    const rectangle2 = API.createElement({
+      type: "rectangle",
+      x: 10,
+      y: 10,
+    });
+    const rectangle3 = API.createElement({
+      type: "rectangle",
+      x: 20,
+      y: 20,
+    });
+
+    API.setElements([rectangle1, rectangle2, rectangle3]);
+
+    mouse.select(rectangle1);
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      mouse.down(rectangle1.x + 5, rectangle1.y + 5);
+      mouse.up(rectangle1.x + 5, rectangle1.y + 5);
+    });
+
+    assertElements(h.elements, [
+      { id: rectangle1.id },
+      { [ORIG_ID]: rectangle1.id, selected: true },
+      { id: rectangle2.id },
+      { id: rectangle3.id },
+    ]);
+  });
+
+  it("duplication z order with alt+drag for the highest z-ordered element should be +1 for the clone", () => {
+    const rectangle1 = API.createElement({
+      type: "rectangle",
+      x: 0,
+      y: 0,
+    });
+    const rectangle2 = API.createElement({
+      type: "rectangle",
+      x: 10,
+      y: 10,
+    });
+    const rectangle3 = API.createElement({
+      type: "rectangle",
+      x: 20,
+      y: 20,
+    });
+
+    API.setElements([rectangle1, rectangle2, rectangle3]);
+
+    mouse.select(rectangle3);
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      mouse.down(rectangle3.x + 5, rectangle3.y + 5);
+      mouse.up(rectangle3.x + 5, rectangle3.y + 5);
+    });
+
+    assertElements(h.elements, [
+      { id: rectangle1.id },
+      { id: rectangle2.id },
+      { id: rectangle3.id },
+      { [ORIG_ID]: rectangle3.id, selected: true },
+    ]);
+  });
+
+  it("duplication z order with alt+drag for the lowest z-ordered element should be +1 for the clone", () => {
+    const rectangle1 = API.createElement({
+      type: "rectangle",
+      x: 0,
+      y: 0,
+    });
+    const rectangle2 = API.createElement({
+      type: "rectangle",
+      x: 10,
+      y: 10,
+    });
+    const rectangle3 = API.createElement({
+      type: "rectangle",
+      x: 20,
+      y: 20,
+    });
+
+    API.setElements([rectangle1, rectangle2, rectangle3]);
+
+    mouse.select(rectangle1);
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      mouse.down(rectangle1.x + 5, rectangle1.y + 5);
+      mouse.up(rectangle1.x + 5, rectangle1.y + 5);
+    });
+
+    assertElements(h.elements, [
+      { id: rectangle1.id },
+      { [ORIG_ID]: rectangle1.id, selected: true },
+      { id: rectangle2.id },
+      { id: rectangle3.id },
+    ]);
+  });
+
+  it("duplication z order with alt+drag with grouped elements should consider the group together when determining z-index", () => {
+    const rectangle1 = API.createElement({
+      type: "rectangle",
+      x: 0,
+      y: 0,
+      groupIds: ["group1"],
+    });
+    const rectangle2 = API.createElement({
+      type: "rectangle",
+      x: 10,
+      y: 10,
+      groupIds: ["group1"],
+    });
+    const rectangle3 = API.createElement({
+      type: "rectangle",
+      x: 20,
+      y: 20,
+      groupIds: ["group1"],
+    });
+
+    API.setElements([rectangle1, rectangle2, rectangle3]);
+
+    mouse.select(rectangle1);
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      mouse.down(rectangle1.x + 5, rectangle1.y + 5);
+      mouse.up(rectangle1.x + 15, rectangle1.y + 15);
+    });
+
+    assertElements(h.elements, [
+      { id: rectangle1.id },
+      { id: rectangle2.id },
+      { id: rectangle3.id },
+      { [ORIG_ID]: rectangle1.id, selected: true },
+      { [ORIG_ID]: rectangle2.id, selected: true },
+      { [ORIG_ID]: rectangle3.id, selected: true },
+    ]);
+  });
+
+  it("alt-duplicating text container (in-order)", async () => {
+    const [rectangle, text] = API.createTextContainer();
+    API.setElements([rectangle, text]);
+    API.setSelectedElements([rectangle]);
+
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      mouse.down(rectangle.x + 5, rectangle.y + 5);
+      mouse.up(rectangle.x + 15, rectangle.y + 15);
+    });
+
+    assertElements(h.elements, [
+      { id: rectangle.id },
+      { id: text.id, containerId: rectangle.id },
+      { [ORIG_ID]: rectangle.id, selected: true },
+      {
+        [ORIG_ID]: text.id,
+        containerId: getCloneByOrigId(rectangle.id)?.id,
+      },
+    ]);
+  });
+
+  it("alt-duplicating text container (out-of-order)", async () => {
+    const [rectangle, text] = API.createTextContainer();
+    API.setElements([text, rectangle]);
+    API.setSelectedElements([rectangle]);
+
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      mouse.down(rectangle.x + 5, rectangle.y + 5);
+      mouse.up(rectangle.x + 15, rectangle.y + 15);
+    });
+
+    assertElements(h.elements, [
+      { id: rectangle.id },
+      { id: text.id, containerId: rectangle.id },
+      { [ORIG_ID]: rectangle.id, selected: true },
+      {
+        [ORIG_ID]: text.id,
+        containerId: getCloneByOrigId(rectangle.id)?.id,
+      },
+    ]);
+  });
+
+  it("alt-duplicating labeled arrows (in-order)", async () => {
+    const [arrow, text] = API.createLabeledArrow();
+
+    API.setElements([arrow, text]);
+    API.setSelectedElements([arrow]);
+
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      mouse.down(arrow.x + 5, arrow.y + 5);
+      mouse.up(arrow.x + 15, arrow.y + 15);
+    });
+
+    assertElements(h.elements, [
+      { id: arrow.id },
+      { id: text.id, containerId: arrow.id },
+      { [ORIG_ID]: arrow.id, selected: true },
+      {
+        [ORIG_ID]: text.id,
+        containerId: getCloneByOrigId(arrow.id)?.id,
+      },
+    ]);
+    expect(h.state.selectedLinearElement).toEqual(
+      expect.objectContaining({ elementId: getCloneByOrigId(arrow.id)?.id }),
+    );
+  });
+
+  it("alt-duplicating labeled arrows (out-of-order)", async () => {
+    const [arrow, text] = API.createLabeledArrow();
+
+    API.setElements([text, arrow]);
+    API.setSelectedElements([arrow]);
+
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      mouse.down(arrow.x + 5, arrow.y + 5);
+      mouse.up(arrow.x + 15, arrow.y + 15);
+    });
+
+    assertElements(h.elements, [
+      { id: arrow.id },
+      { id: text.id, containerId: arrow.id },
+      { [ORIG_ID]: arrow.id, selected: true },
+      {
+        [ORIG_ID]: text.id,
+        containerId: getCloneByOrigId(arrow.id)?.id,
+      },
+    ]);
+  });
+
+  it("alt-duplicating bindable element with bound arrow should keep the arrow on the duplicate", async () => {
+    const rect = UI.createElement("rectangle", {
+      x: 0,
+      y: 0,
+      width: 100,
+      height: 100,
+    });
+
+    const arrow = UI.createElement("arrow", {
+      x: -100,
+      y: 50,
+      width: 115,
+      height: 0,
+    });
+
+    expect(arrow.endBinding?.elementId).toBe(rect.id);
+
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      mouse.down(5, 5);
+      mouse.up(15, 15);
+    });
+
+    assertElements(h.elements, [
+      {
+        id: rect.id,
+        boundElements: expect.arrayContaining([
+          expect.objectContaining({ id: arrow.id }),
+        ]),
+      },
+      { [ORIG_ID]: rect.id, boundElements: [], selected: true },
+      {
+        id: arrow.id,
+        endBinding: expect.objectContaining({ elementId: rect.id }),
+      },
+    ]);
+  });
+});

packages/element/tests/elbowArrow.test.tsx

@@ -0,0 +1,416 @@
+import { ARROW_TYPE } from "@excalidraw/common";
+import { pointFrom } from "@excalidraw/math";
+import { Excalidraw } from "@excalidraw/excalidraw";
+import { actionSelectAll } from "@excalidraw/excalidraw/actions";
+import { actionDuplicateSelection } from "@excalidraw/excalidraw/actions/actionDuplicateSelection";
+import { API } from "@excalidraw/excalidraw/tests/helpers/api";
+import { Pointer, UI } from "@excalidraw/excalidraw/tests/helpers/ui";
+import {
+  act,
+  fireEvent,
+  GlobalTestState,
+  queryByTestId,
+  render,
+} from "@excalidraw/excalidraw/tests/test-utils";
+import "@excalidraw/utils/test-utils";
+import { bindBindingElement } from "@excalidraw/element";
+
+import type { LocalPoint } from "@excalidraw/math";
+
+import { Scene } from "../src/Scene";
+
+import type {
+  ExcalidrawArrowElement,
+  ExcalidrawBindableElement,
+  ExcalidrawElbowArrowElement,
+  NonDeleted,
+} from "../src/types";
+
+const { h } = window;
+
+const mouse = new Pointer("mouse");
+
+describe("elbow arrow segment move", () => {
+  beforeEach(async () => {
+    localStorage.clear();
+    await render(<Excalidraw handleKeyboardGlobally={true} />);
+  });
+
+  it("can move the second segment of a fully connected elbow arrow", () => {
+    UI.createElement("rectangle", {
+      x: -100,
+      y: -50,
+      width: 100,
+      height: 100,
+    });
+    UI.createElement("rectangle", {
+      x: 200,
+      y: 150,
+      width: 100,
+      height: 100,
+    });
+
+    UI.clickTool("arrow");
+    UI.clickOnTestId("elbow-arrow");
+
+    mouse.reset();
+    mouse.moveTo(0, 0);
+    mouse.click();
+    mouse.moveTo(200, 200);
+    mouse.click();
+
+    mouse.reset();
+    mouse.moveTo(100, 100);
+    mouse.down();
+    mouse.moveTo(115, 100);
+    mouse.up();
+
+    const arrow = h.scene.getSelectedElements(
+      h.state,
+    )[0] as ExcalidrawElbowArrowElement;
+
+    expect(h.state.selectedElementIds).toEqual({ [arrow.id]: true });
+    expect(arrow.fixedSegments?.length).toBe(1);
+
+    expect(arrow.points).toCloselyEqualPoints([
+      [0, 0],
+      [110, 0],
+      [110, 200],
+      [190, 200],
+    ]);
+
+    mouse.reset();
+    mouse.moveTo(105, 74.275);
+    mouse.doubleClick();
+
+    expect(arrow.points).toCloselyEqualPoints([
+      [0, 0],
+      [110, 0],
+      [110, 200],
+      [190, 200],
+    ]);
+  });
+
+  it("can move the second segment of an unconnected elbow arrow", () => {
+    UI.clickTool("arrow");
+    UI.clickOnTestId("elbow-arrow");
+
+    mouse.reset();
+    mouse.moveTo(0, 0);
+    mouse.click();
+    mouse.moveTo(250, 200);
+    mouse.click();
+
+    mouse.reset();
+    mouse.moveTo(125, 100);
+    mouse.down();
+    mouse.moveTo(130, 100);
+    mouse.up();
+
+    const arrow = h.scene.getSelectedElements(
+      h.state,
+    )[0] as ExcalidrawArrowElement;
+
+    expect(arrow.points).toCloselyEqualPoints([
+      [0, 0],
+      [130, 0],
+      [130, 200],
+      [250, 200],
+    ]);
+
+    mouse.reset();
+    mouse.moveTo(130, 100);
+    mouse.doubleClick();
+
+    expect(arrow.points).toCloselyEqualPoints([
+      [0, 0],
+      [125, 0],
+      [125, 200],
+      [250, 200],
+    ]);
+  });
+});
+
+describe("elbow arrow routing", () => {
+  beforeEach(async () => {
+    localStorage.clear();
+    await render(<Excalidraw handleKeyboardGlobally={true} />);
+  });
+
+  it("can properly generate orthogonal arrow points", () => {
+    const scene = new Scene();
+    const arrow = API.createElement({
+      type: "arrow",
+      elbowed: true,
+    }) as NonDeleted<ExcalidrawElbowArrowElement>;
+    scene.insertElement(arrow);
+    h.app.scene.mutateElement(arrow, {
+      points: [
+        pointFrom<LocalPoint>(-45 - arrow.x, -100.1 - arrow.y),
+        pointFrom<LocalPoint>(45 - arrow.x, 99.9 - arrow.y),
+      ],
+    });
+    expect(arrow.points).toEqual([
+      [0, 0],
+      [0, 100],
+      [90, 100],
+      [90, 200],
+    ]);
+    expect(arrow.x).toEqual(-45);
+    expect(arrow.y).toEqual(-100.1);
+    expect(arrow.width).toEqual(90);
+    expect(arrow.height).toEqual(200);
+  });
+
+  it("can generate proper points for bound elbow arrow", () => {
+    const rectangle1 = API.createElement({
+      type: "rectangle",
+      x: -150,
+      y: -150,
+      width: 100,
+      height: 100,
+    }) as NonDeleted<ExcalidrawBindableElement>;
+    const rectangle2 = API.createElement({
+      type: "rectangle",
+      x: 50,
+      y: 50,
+      width: 100,
+      height: 100,
+    }) as NonDeleted<ExcalidrawBindableElement>;
+    const arrow = API.createElement({
+      type: "arrow",
+      elbowed: true,
+      x: -45,
+      y: -100.1,
+      width: 90,
+      height: 200,
+      points: [pointFrom(0, 0), pointFrom(90, 200)],
+    }) as NonDeleted<ExcalidrawElbowArrowElement>;
+    API.setElements([rectangle1, rectangle2, arrow]);
+
+    bindBindingElement(arrow, rectangle1, "orbit", "start", h.scene);
+    bindBindingElement(arrow, rectangle2, "orbit", "end", h.scene);
+
+    expect(arrow.startBinding).not.toBe(null);
+    expect(arrow.endBinding).not.toBe(null);
+
+    h.scene.mutateElement(arrow, {
+      points: [pointFrom<LocalPoint>(0, 0), pointFrom<LocalPoint>(90, 200)],
+    });
+
+    expect(arrow.points).toCloselyEqualPoints([
+      [0, 0],
+      [39, 0],
+      [39, 200],
+      [78, 200],
+    ]);
+  });
+});
+
+describe("elbow arrow ui", () => {
+  beforeEach(async () => {
+    localStorage.clear();
+    await render(<Excalidraw handleKeyboardGlobally={true} />);
+
+    fireEvent.contextMenu(GlobalTestState.interactiveCanvas, {
+      button: 2,
+      clientX: 1,
+      clientY: 1,
+    });
+    const contextMenu = UI.queryContextMenu();
+    fireEvent.click(queryByTestId(contextMenu!, "stats")!);
+  });
+
+  it("can follow bound shapes", async () => {
+    UI.createElement("rectangle", {
+      x: -150,
+      y: -150,
+      width: 100,
+      height: 100,
+    });
+    UI.createElement("rectangle", {
+      x: 50,
+      y: 50,
+      width: 100,
+      height: 100,
+    });
+
+    UI.clickTool("arrow");
+    UI.clickOnTestId("elbow-arrow");
+
+    expect(h.state.currentItemArrowType).toBe(ARROW_TYPE.elbow);
+
+    mouse.reset();
+    mouse.moveTo(-53, -99);
+    mouse.click();
+    mouse.moveTo(53, 99);
+    mouse.click();
+
+    const arrow = h.scene.getSelectedElements(
+      h.state,
+    )[0] as ExcalidrawArrowElement;
+
+    expect(arrow.type).toBe("arrow");
+    expect(arrow.elbowed).toBe(true);
+    expect(arrow.points).toCloselyEqualPoints([
+      [0, 0],
+      [39, 0],
+      [39, 200],
+      [78, 200],
+    ]);
+  });
+
+  it("can follow bound rotated shapes", async () => {
+    UI.createElement("rectangle", {
+      x: -150,
+      y: -150,
+      width: 100,
+      height: 100,
+    });
+    UI.createElement("rectangle", {
+      x: 50,
+      y: 50,
+      width: 100,
+      height: 100,
+    });
+
+    UI.clickTool("arrow");
+    UI.clickOnTestId("elbow-arrow");
+
+    mouse.reset();
+    mouse.moveTo(-53, -99);
+    mouse.click();
+    mouse.moveTo(53, 99);
+    mouse.click();
+
+    const arrow = h.scene.getSelectedElements(
+      h.state,
+    )[0] as ExcalidrawArrowElement;
+
+    mouse.click(51, 51);
+
+    const inputAngle = UI.queryStatsProperty("A")?.querySelector(
+      ".drag-input",
+    ) as HTMLInputElement;
+    UI.updateInput(inputAngle, String("40"));
+
+    expect(arrow.points.map((point) => point.map(Math.round))).toEqual([
+      [0, 0],
+      [36, 0],
+      [36, 90],
+      [28, 90],
+      [28, 164],
+      [101, 164],
+    ]);
+  });
+
+  it("keeps arrow shape when the whole set of arrow and bindables are duplicated", async () => {
+    UI.createElement("rectangle", {
+      x: -150,
+      y: -150,
+      width: 100,
+      height: 100,
+    });
+    UI.createElement("rectangle", {
+      x: 50,
+      y: 50,
+      width: 100,
+      height: 100,
+    });
+
+    UI.clickTool("arrow");
+    UI.clickOnTestId("elbow-arrow");
+
+    mouse.reset();
+    mouse.moveTo(-53, -99);
+    mouse.click();
+    mouse.moveTo(53, 99);
+    mouse.click();
+
+    const arrow = h.scene.getSelectedElements(
+      h.state,
+    )[0] as ExcalidrawArrowElement;
+    const originalArrowId = arrow.id;
+
+    expect(arrow.startBinding).not.toBe(null);
+    expect(arrow.endBinding).not.toBe(null);
+
+    act(() => {
+      h.app.actionManager.executeAction(actionSelectAll);
+    });
+
+    act(() => {
+      h.app.actionManager.executeAction(actionDuplicateSelection);
+    });
+
+    expect(h.elements.length).toEqual(6);
+
+    const duplicatedArrow = h.scene.getSelectedElements(
+      h.state,
+    )[2] as ExcalidrawArrowElement;
+
+    expect(duplicatedArrow.id).not.toBe(originalArrowId);
+    expect(duplicatedArrow.type).toBe("arrow");
+    expect(duplicatedArrow.elbowed).toBe(true);
+    expect(duplicatedArrow.points).toCloselyEqualPoints([
+      [0, 0],
+      [39, 0],
+      [39, 200],
+      [78, 200],
+    ]);
+    expect(arrow.startBinding).not.toBe(null);
+    expect(arrow.endBinding).not.toBe(null);
+  });
+
+  it("changes arrow shape to unbind variant if only the connected elbow arrow is duplicated", async () => {
+    UI.createElement("rectangle", {
+      x: -150,
+      y: -150,
+      width: 100,
+      height: 100,
+    });
+    UI.createElement("rectangle", {
+      x: 50,
+      y: 50,
+      width: 100,
+      height: 100,
+    });
+
+    UI.clickTool("arrow");
+    UI.clickOnTestId("elbow-arrow");
+
+    mouse.reset();
+    mouse.moveTo(-53, -99);
+    mouse.click();
+    mouse.moveTo(53, 99);
+    mouse.click();
+
+    const arrow = h.scene.getSelectedElements(
+      h.state,
+    )[0] as ExcalidrawArrowElement;
+    const originalArrowId = arrow.id;
+
+    expect(arrow.startBinding).not.toBe(null);
+    expect(arrow.endBinding).not.toBe(null);
+
+    act(() => {
+      h.app.actionManager.executeAction(actionDuplicateSelection);
+    });
+
+    expect(h.elements.length).toEqual(4);
+
+    const duplicatedArrow = h.scene.getSelectedElements(
+      h.state,
+    )[0] as ExcalidrawArrowElement;
+
+    expect(duplicatedArrow.id).not.toBe(originalArrowId);
+    expect(duplicatedArrow.type).toBe("arrow");
+    expect(duplicatedArrow.elbowed).toBe(true);
+    expect(duplicatedArrow.points).toCloselyEqualPoints([
+      [0, 0],
+      [0, 100],
+      [78, 100],
+      [78, 200],
+    ]);
+  });
+});

packages/element/tests/embeddable.test.ts

@@ -0,0 +1,233 @@
+import { embeddableURLValidator, getEmbedLink } from "../src/embeddable";
+
+describe("YouTube timestamp parsing", () => {
+  it("should parse YouTube URLs with timestamp in seconds", () => {
+    const testCases = [
+      {
+        url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=90",
+        expectedStart: 90,
+      },
+      {
+        url: "https://youtu.be/dQw4w9WgXcQ?t=120",
+        expectedStart: 120,
+      },
+      {
+        url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ&start=150",
+        expectedStart: 150,
+      },
+    ];
+
+    testCases.forEach(({ url, expectedStart }) => {
+      const result = getEmbedLink(url);
+      expect(result).toBeTruthy();
+      expect(result?.type).toBe("video");
+      if (result?.type === "video" || result?.type === "generic") {
+        expect(result.link).toContain(`start=${expectedStart}`);
+      }
+    });
+  });
+
+  it("should parse YouTube URLs with timestamp in time format", () => {
+    const testCases = [
+      {
+        url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=1m30s",
+        expectedStart: 90, // 1*60 + 30
+      },
+      {
+        url: "https://youtu.be/dQw4w9WgXcQ?t=2m45s",
+        expectedStart: 165, // 2*60 + 45
+      },
+      {
+        url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=1h2m3s",
+        expectedStart: 3723, // 1*3600 + 2*60 + 3
+      },
+      {
+        url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=45s",
+        expectedStart: 45,
+      },
+      {
+        url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=5m",
+        expectedStart: 300, // 5*60
+      },
+      {
+        url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=2h",
+        expectedStart: 7200, // 2*3600
+      },
+    ];
+
+    testCases.forEach(({ url, expectedStart }) => {
+      const result = getEmbedLink(url);
+      expect(result).toBeTruthy();
+      expect(result?.type).toBe("video");
+      if (result?.type === "video" || result?.type === "generic") {
+        expect(result.link).toContain(`start=${expectedStart}`);
+      }
+    });
+  });
+
+  it("should handle YouTube URLs without timestamps", () => {
+    const testCases = [
+      "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+      "https://youtu.be/dQw4w9WgXcQ",
+      "https://www.youtube.com/embed/dQw4w9WgXcQ",
+    ];
+
+    testCases.forEach((url) => {
+      const result = getEmbedLink(url);
+      expect(result).toBeTruthy();
+      expect(result?.type).toBe("video");
+      if (result?.type === "video" || result?.type === "generic") {
+        expect(result.link).not.toContain("start=");
+      }
+    });
+  });
+
+  it("should handle YouTube shorts URLs with timestamps", () => {
+    const url = "https://www.youtube.com/shorts/dQw4w9WgXcQ?t=30";
+    const result = getEmbedLink(url);
+
+    expect(result).toBeTruthy();
+    expect(result?.type).toBe("video");
+    if (result?.type === "video" || result?.type === "generic") {
+      expect(result.link).toContain("start=30");
+    }
+    // Shorts should have portrait aspect ratio
+    expect(result?.intrinsicSize).toEqual({ w: 315, h: 560 });
+  });
+
+  it("should handle playlist URLs with timestamps", () => {
+    const url =
+      "https://www.youtube.com/playlist?list=PLrAXtmRdnEQy1KbG5lbfgQ0-PKQY6FKYZ&t=60";
+    const result = getEmbedLink(url);
+
+    expect(result).toBeTruthy();
+    expect(result?.type).toBe("video");
+    if (result?.type === "video" || result?.type === "generic") {
+      expect(result.link).toContain("start=60");
+      expect(result.link).toContain("list=PLrAXtmRdnEQy1KbG5lbfgQ0-PKQY6FKYZ");
+    }
+  });
+
+  it("should handle malformed or edge case timestamps", () => {
+    const testCases = [
+      {
+        url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=abc",
+        expectedStart: 0, // Invalid timestamp should default to 0
+      },
+      {
+        url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=",
+        expectedStart: 0, // Empty timestamp should default to 0
+      },
+      {
+        url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=0",
+        expectedStart: 0, // Zero timestamp should be handled
+      },
+    ];
+
+    testCases.forEach(({ url, expectedStart }) => {
+      const result = getEmbedLink(url);
+      expect(result).toBeTruthy();
+      expect(result?.type).toBe("video");
+      if (result?.type === "video" || result?.type === "generic") {
+        if (expectedStart === 0) {
+          expect(result.link).not.toContain("start=");
+        } else {
+          expect(result.link).toContain(`start=${expectedStart}`);
+        }
+      }
+    });
+  });
+
+  it("should preserve other URL parameters", () => {
+    const url =
+      "https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=90&feature=youtu.be&list=PLtest";
+    const result = getEmbedLink(url);
+
+    expect(result).toBeTruthy();
+    expect(result?.type).toBe("video");
+    if (result?.type === "video" || result?.type === "generic") {
+      expect(result.link).toContain("start=90");
+      expect(result.link).toContain("enablejsapi=1");
+    }
+  });
+});
+
+describe("Google Drive video embedding", () => {
+  it.each([
+    {
+      url: "https://drive.google.com/file/d/1AbCdEfGhIjKlMnOpQrStUvWxYz123456/view?usp=sharing",
+      expectedLink:
+        "https://drive.google.com/file/d/1AbCdEfGhIjKlMnOpQrStUvWxYz123456/preview",
+    },
+    {
+      url: "https://drive.google.com/open?id=1AbCdEfGhIjKlMnOpQrStUvWxYz123456",
+      expectedLink:
+        "https://drive.google.com/file/d/1AbCdEfGhIjKlMnOpQrStUvWxYz123456/preview",
+    },
+    {
+      url: "https://drive.google.com/uc?export=download&id=1AbCdEfGhIjKlMnOpQrStUvWxYz123456",
+      expectedLink:
+        "https://drive.google.com/file/d/1AbCdEfGhIjKlMnOpQrStUvWxYz123456/preview",
+    },
+  ])("should normalize Google Drive link: $url", ({ url, expectedLink }) => {
+    const result = getEmbedLink(url);
+
+    expect(result).toBeTruthy();
+    expect(result?.type).toBe("video");
+    if (result?.type === "video" || result?.type === "generic") {
+      expect(result.link).toBe(expectedLink);
+    }
+    expect(result?.intrinsicSize).toEqual({ w: 560, h: 315 });
+  });
+
+  it("should preserve resourcekey when available", () => {
+    const url =
+      "https://drive.google.com/file/d/1AbCdEfGhIjKlMnOpQrStUvWxYz123456/view?resourcekey=0-abcdef123456";
+    const result = getEmbedLink(url);
+
+    expect(result).toBeTruthy();
+    expect(result?.type).toBe("video");
+    if (result?.type === "video" || result?.type === "generic") {
+      expect(result.link).toBe(
+        "https://drive.google.com/file/d/1AbCdEfGhIjKlMnOpQrStUvWxYz123456/preview?resourcekey=0-abcdef123456",
+      );
+    }
+  });
+
+  it("should preserve timestamp when available", () => {
+    const url =
+      "https://drive.google.com/file/d/1AbCdEfGhIjKlMnOpQrStUvWxYz123456/view?t=9";
+    const result = getEmbedLink(url);
+
+    expect(result).toBeTruthy();
+    expect(result?.type).toBe("video");
+    if (result?.type === "video" || result?.type === "generic") {
+      expect(result.link).toBe(
+        "https://drive.google.com/file/d/1AbCdEfGhIjKlMnOpQrStUvWxYz123456/preview?t=9",
+      );
+    }
+  });
+
+  it("should preserve resourcekey and timestamp together", () => {
+    const url =
+      "https://drive.google.com/file/d/1AbCdEfGhIjKlMnOpQrStUvWxYz123456/view?resourcekey=0-abcdef123456&t=9";
+    const result = getEmbedLink(url);
+
+    expect(result).toBeTruthy();
+    expect(result?.type).toBe("video");
+    if (result?.type === "video" || result?.type === "generic") {
+      expect(result.link).toBe(
+        "https://drive.google.com/file/d/1AbCdEfGhIjKlMnOpQrStUvWxYz123456/preview?resourcekey=0-abcdef123456&t=9",
+      );
+    }
+  });
+
+  it("should validate Google Drive domain by default", () => {
+    expect(
+      embeddableURLValidator(
+        "https://drive.google.com/file/d/1AbCdEfGhIjKlMnOpQrStUvWxYz123456/view",
+        undefined,
+      ),
+    ).toBe(true);
+  });
+});

packages/element/tests/flowchart.test.tsx

@@ -0,0 +1,683 @@
+import { KEYS, reseed } from "@excalidraw/common";
+
+import { Excalidraw } from "@excalidraw/excalidraw";
+
+import { API } from "@excalidraw/excalidraw/tests/helpers/api";
+import { UI, Keyboard, Pointer } from "@excalidraw/excalidraw/tests/helpers/ui";
+import {
+  render,
+  unmountComponent,
+} from "@excalidraw/excalidraw/tests/test-utils";
+
+import type { NonDeletedExcalidrawElement } from "@excalidraw/element/types";
+
+unmountComponent();
+
+const { h } = window;
+const mouse = new Pointer("mouse");
+
+beforeEach(async () => {
+  localStorage.clear();
+  reseed(7);
+  mouse.reset();
+
+  await render(<Excalidraw handleKeyboardGlobally={true} />);
+  h.state.width = 1000;
+  h.state.height = 1000;
+
+  // The bounds of hand-drawn linear elements may change after flipping, so
+  // removing this style for testing
+  UI.clickTool("arrow");
+  UI.clickByTitle("Architect");
+  UI.clickTool("selection");
+});
+
+describe("flow chart creation", () => {
+  beforeEach(() => {
+    API.clearSelection();
+    const rectangle = API.createElement({
+      type: "rectangle",
+      width: 200,
+      height: 100,
+    });
+
+    API.setElements([rectangle]);
+    API.setSelectedElements([rectangle]);
+  });
+
+  // multiple at once
+  it("create multiple successor nodes at once", () => {
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    expect(h.elements.length).toBe(5);
+    expect(h.elements.filter((el) => el.type === "rectangle").length).toBe(3);
+    expect(h.elements.filter((el) => el.type === "arrow").length).toBe(2);
+  });
+
+  it("when directions are changed, only the last same directions will apply", () => {
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+
+      Keyboard.keyPress(KEYS.ARROW_LEFT);
+
+      Keyboard.keyPress(KEYS.ARROW_UP);
+      Keyboard.keyPress(KEYS.ARROW_UP);
+      Keyboard.keyPress(KEYS.ARROW_UP);
+    });
+
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    expect(h.elements.length).toBe(7);
+    expect(h.elements.filter((el) => el.type === "rectangle").length).toBe(4);
+    expect(h.elements.filter((el) => el.type === "arrow").length).toBe(3);
+  });
+
+  it("when escaped, no nodes will be created", () => {
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      Keyboard.keyPress(KEYS.ARROW_LEFT);
+      Keyboard.keyPress(KEYS.ARROW_UP);
+      Keyboard.keyPress(KEYS.ARROW_DOWN);
+    });
+
+    Keyboard.keyPress(KEYS.ESCAPE);
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    expect(h.elements.length).toBe(1);
+  });
+
+  it("create nodes one at a time", () => {
+    const initialNode = h.elements[0];
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    expect(h.elements.length).toBe(3);
+    expect(h.elements.filter((el) => el.type === "rectangle").length).toBe(2);
+    expect(h.elements.filter((el) => el.type === "arrow").length).toBe(1);
+
+    const firstChildNode = h.elements.filter(
+      (el) => el.type === "rectangle" && el.id !== initialNode.id,
+    )[0];
+    expect(firstChildNode).not.toBe(null);
+    expect(firstChildNode.id).toBe(Object.keys(h.state.selectedElementIds)[0]);
+
+    API.setSelectedElements([initialNode] as NonDeletedExcalidrawElement[]);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    expect(h.elements.length).toBe(5);
+    expect(h.elements.filter((el) => el.type === "rectangle").length).toBe(3);
+    expect(h.elements.filter((el) => el.type === "arrow").length).toBe(2);
+
+    const secondChildNode = h.elements.filter(
+      (el) =>
+        el.type === "rectangle" &&
+        el.id !== initialNode.id &&
+        el.id !== firstChildNode.id,
+    )[0];
+    expect(secondChildNode).not.toBe(null);
+    expect(secondChildNode.id).toBe(Object.keys(h.state.selectedElementIds)[0]);
+
+    API.setSelectedElements([initialNode] as NonDeletedExcalidrawElement[]);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    expect(h.elements.length).toBe(7);
+    expect(h.elements.filter((el) => el.type === "rectangle").length).toBe(4);
+    expect(h.elements.filter((el) => el.type === "arrow").length).toBe(3);
+
+    const thirdChildNode = h.elements.filter(
+      (el) =>
+        el.type === "rectangle" &&
+        el.id !== initialNode.id &&
+        el.id !== firstChildNode.id &&
+        el.id !== secondChildNode.id,
+    )[0];
+
+    expect(thirdChildNode).not.toBe(null);
+    expect(thirdChildNode.id).toBe(Object.keys(h.state.selectedElementIds)[0]);
+
+    expect(firstChildNode.x).toBe(secondChildNode.x);
+    expect(secondChildNode.x).toBe(thirdChildNode.x);
+  });
+
+  // regression for #8518: additional siblings must not overlap existing ones
+  it("does not overlap existing siblings when adding more children (down)", () => {
+    API.clearSelection();
+    const parent = API.createElement({
+      type: "rectangle",
+      width: 400,
+      height: 300,
+    });
+    API.setElements([parent]);
+    API.setSelectedElements([parent]);
+
+    for (let i = 0; i < 4; i++) {
+      API.setSelectedElements([parent]);
+      Keyboard.withModifierKeys({ ctrl: true }, () => {
+        Keyboard.keyPress(KEYS.ARROW_DOWN);
+      });
+      Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+    }
+
+    const children = h.elements.filter(
+      (el) => el.type === "rectangle" && el.id !== parent.id,
+    );
+    expect(children.length).toBe(4);
+
+    // all siblings should sit on the same row (no vertical misalignment)
+    const ys = new Set(children.map((c) => c.y));
+    expect(ys.size).toBe(1);
+
+    // no two siblings should overlap horizontally
+    const sorted = [...children].sort((a, b) => a.x - b.x);
+    for (let i = 1; i < sorted.length; i++) {
+      expect(sorted[i].x).toBeGreaterThanOrEqual(
+        sorted[i - 1].x + sorted[i - 1].width,
+      );
+    }
+  });
+
+  // regression for #8518: a second batch of children (added by holding the
+  // modifier and pressing the arrow several times) must clear the first batch
+  it("does not overlap a previous batch of children (down)", () => {
+    API.clearSelection();
+    const parent = API.createElement({
+      type: "rectangle",
+      width: 400,
+      height: 300,
+    });
+    API.setElements([parent]);
+
+    // hold the modifier and press down N times to create a batch at once
+    const addBatch = (count: number) => {
+      API.setSelectedElements([parent]);
+      Keyboard.withModifierKeys({ ctrl: true }, () => {
+        for (let i = 0; i < count; i++) {
+          Keyboard.keyPress(KEYS.ARROW_DOWN);
+        }
+      });
+      Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+    };
+
+    addBatch(3);
+    addBatch(2);
+
+    const children = h.elements.filter(
+      (el) => el.type === "rectangle" && el.id !== parent.id,
+    );
+    expect(children.length).toBe(5);
+
+    const overlaps = (a: typeof children[0], b: typeof children[0]) =>
+      a.x < b.x + b.width &&
+      a.x + a.width > b.x &&
+      a.y < b.y + b.height &&
+      a.y + a.height > b.y;
+
+    for (let i = 0; i < children.length; i++) {
+      for (let j = i + 1; j < children.length; j++) {
+        expect(overlaps(children[i], children[j])).toBe(false);
+      }
+    }
+  });
+
+  // regression for #8518: a new child must also clear nodes that aren't the
+  // start node's direct siblings but sit where it would land — e.g. a sibling
+  // reached through a shared parent
+  it("does not overlap a sibling reached through a shared parent", () => {
+    API.clearSelection();
+    const parent = API.createElement({
+      type: "rectangle",
+      width: 200,
+      height: 100,
+    });
+    API.setElements([parent]);
+
+    // two right-children stack into a column to the right of the parent
+    API.setSelectedElements([parent]);
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    const rightChildren = h.elements
+      .filter((el) => el.type === "rectangle" && el.id !== parent.id)
+      .sort((a, b) => a.y - b.y);
+    expect(rightChildren.length).toBe(2);
+    const [upper, lower] = rightChildren;
+
+    // add a child below the upper sibling; it must not land on the lower one
+    // that sits directly beneath it
+    API.setSelectedElements([upper] as NonDeletedExcalidrawElement[]);
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_DOWN);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    const newChild = h.elements.filter(
+      (el) =>
+        el.type === "rectangle" &&
+        el.id !== parent.id &&
+        el.id !== upper.id &&
+        el.id !== lower.id,
+    )[0];
+    expect(newChild).toBeTruthy();
+
+    const overlaps = (a: typeof newChild, b: typeof lower) =>
+      a.x < b.x + b.width &&
+      a.x + a.width > b.x &&
+      a.y < b.y + b.height &&
+      a.y + a.height > b.y;
+
+    expect(overlaps(newChild, lower)).toBe(false);
+  });
+});
+
+describe("flow chart band-search placement", () => {
+  const addChild = (parent: NonDeletedExcalidrawElement, key: string) => {
+    API.setSelectedElements([parent]);
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(key);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+  };
+
+  const children = (parent: NonDeletedExcalidrawElement) =>
+    h.elements.filter((el) => el.type === "rectangle" && el.id !== parent.id);
+
+  const pendingRects = () =>
+    (h.app.flowchart.pendingNodes ?? [])
+      .filter((el) => el.type === "rectangle")
+      .map((el) => ({ x: el.x, y: el.y }));
+
+  it("places the first child exactly one offset away in every direction", () => {
+    const cases = [
+      { key: KEYS.ARROW_RIGHT, x: 300, y: 0 },
+      { key: KEYS.ARROW_LEFT, x: -300, y: 0 },
+      { key: KEYS.ARROW_DOWN, x: 0, y: 200 },
+      { key: KEYS.ARROW_UP, x: 0, y: -200 },
+    ];
+
+    for (const { key, x, y } of cases) {
+      API.clearSelection();
+      const parent = API.createElement({
+        type: "rectangle",
+        width: 200,
+        height: 100,
+      });
+      API.setElements([parent]);
+
+      addChild(parent, key);
+
+      const [child] = children(parent);
+      expect(child).toBeTruthy();
+      expect(child.x).toBe(x);
+      expect(child.y).toBe(y);
+    }
+  });
+
+  it("slides into the nearest free gap between obstacles without moving them", () => {
+    API.clearSelection();
+    const parent = API.createElement({
+      type: "rectangle",
+      width: 200,
+      height: 100,
+    });
+    API.setElements([parent]);
+
+    addChild(parent, KEYS.ARROW_DOWN);
+    addChild(parent, KEYS.ARROW_DOWN);
+
+    const [c1, c2] = children(parent).sort((a, b) => a.x - b.x);
+    expect([c1.x, c2.x]).toEqual([0, 300]);
+
+    // widen the gap between the siblings so a third child fits in between
+    API.updateElement(c2, { x: 600 });
+
+    addChild(parent, KEYS.ARROW_DOWN);
+
+    const c3 = children(parent).find(
+      (el) => el.id !== c1.id && el.id !== c2.id,
+    )!;
+    expect({ x: c3.x, y: c3.y }).toEqual({ x: 300, y: 200 });
+
+    // the obstacles were not moved
+    expect({ x: c1.x, y: c1.y }).toEqual({ x: 0, y: 200 });
+    expect({ x: c2.x, y: c2.y }).toEqual({ x: 600, y: 200 });
+  });
+
+  it("keeps pending nodes in place while the cluster grows", () => {
+    API.clearSelection();
+    const parent = API.createElement({
+      type: "rectangle",
+      width: 200,
+      height: 100,
+    });
+    API.setElements([parent]);
+    API.setSelectedElements([parent]);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      expect(pendingRects()).toEqual([{ x: 300, y: 0 }]);
+
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      expect(pendingRects()).toEqual([
+        { x: 300, y: 0 },
+        { x: 300, y: 200 },
+      ]);
+
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      expect(pendingRects()).toEqual([
+        { x: 300, y: -200 },
+        { x: 300, y: 0 },
+        { x: 300, y: 200 },
+      ]);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+  });
+
+  it("repositions the whole pending cluster when it no longer fits", () => {
+    API.clearSelection();
+    const parent = API.createElement({
+      type: "rectangle",
+      width: 200,
+      height: 100,
+    });
+    API.setElements([parent]);
+
+    // box in the space right of the parent, leaving room for a single node
+    addChild(parent, KEYS.ARROW_RIGHT);
+    const [c1] = children(parent);
+    API.updateElement(c1, { y: -300 });
+
+    addChild(parent, KEYS.ARROW_RIGHT);
+    const c2 = children(parent).find((el) => el.id !== c1.id)!;
+    expect({ x: c2.x, y: c2.y }).toEqual({ x: 300, y: 0 });
+    API.updateElement(c2, { y: 300 });
+
+    API.setSelectedElements([parent]);
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      expect(pendingRects()).toEqual([{ x: 300, y: 0 }]);
+
+      // growing cannot extend at either end, so the cluster moves as a whole
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      expect(pendingRects()).toEqual([
+        { x: 300, y: -100 },
+        { x: 300, y: 100 },
+      ]);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    // the obstacles were not moved
+    expect({ x: c1.x, y: c1.y }).toEqual({ x: 300, y: -300 });
+    expect({ x: c2.x, y: c2.y }).toEqual({ x: 300, y: 300 });
+  });
+});
+
+describe("flow chart navigation", () => {
+  it("single node at each level", () => {
+    /**
+     * ▨ -> ▨ -> ▨ -> ▨ -> ▨
+     */
+
+    API.clearSelection();
+    const rectangle = API.createElement({
+      type: "rectangle",
+      width: 200,
+      height: 100,
+    });
+
+    API.setElements([rectangle]);
+    API.setSelectedElements([rectangle]);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    expect(h.elements.filter((el) => el.type === "rectangle").length).toBe(5);
+    expect(h.elements.filter((el) => el.type === "arrow").length).toBe(4);
+
+    // all the way to the left, gets us to the first node
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_LEFT);
+      Keyboard.keyPress(KEYS.ARROW_LEFT);
+      Keyboard.keyPress(KEYS.ARROW_LEFT);
+      Keyboard.keyPress(KEYS.ARROW_LEFT);
+    });
+    Keyboard.keyUp(KEYS.ALT);
+    expect(h.state.selectedElementIds[rectangle.id]).toBe(true);
+
+    // all the way to the right, gets us to the last node
+    const rightMostNode = h.elements[h.elements.length - 2];
+    expect(rightMostNode);
+    expect(rightMostNode.type).toBe("rectangle");
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.ALT);
+    expect(h.state.selectedElementIds[rightMostNode.id]).toBe(true);
+  });
+
+  it("multiple nodes at each level", () => {
+    /**
+     * from the perspective of the first node, there're four layers, and
+     * there are four nodes at the second layer
+     *
+     *   -> ▨
+     * ▨ -> ▨ -> ▨ -> ▨ -> ▨
+     *   -> ▨
+     *   -> ▨
+     */
+
+    API.clearSelection();
+    const rectangle = API.createElement({
+      type: "rectangle",
+      width: 200,
+      height: 100,
+    });
+
+    API.setElements([rectangle]);
+    API.setSelectedElements([rectangle]);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    const secondNode = h.elements[1];
+    const rightMostNode = h.elements[h.elements.length - 2];
+
+    API.setSelectedElements([rectangle]);
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    API.setSelectedElements([rectangle]);
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    API.setSelectedElements([rectangle]);
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    API.setSelectedElements([rectangle]);
+
+    // because of same level cycling,
+    // going right five times should take us back to the second node again
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.ALT);
+    expect(h.state.selectedElementIds[secondNode.id]).toBe(true);
+
+    // from the second node, going right three times should take us to the rightmost node
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.ALT);
+    expect(h.state.selectedElementIds[rightMostNode.id]).toBe(true);
+
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_LEFT);
+      Keyboard.keyPress(KEYS.ARROW_LEFT);
+      Keyboard.keyPress(KEYS.ARROW_LEFT);
+      Keyboard.keyPress(KEYS.ARROW_LEFT);
+    });
+    Keyboard.keyUp(KEYS.ALT);
+    expect(h.state.selectedElementIds[rectangle.id]).toBe(true);
+  });
+
+  it("take the most obvious link when possible", () => {
+    /**
+     * ▨ → ▨   ▨ → ▨
+     *     ↓   ↑
+     *     ▨ → ▨
+     */
+
+    API.clearSelection();
+    const rectangle = API.createElement({
+      type: "rectangle",
+      width: 200,
+      height: 100,
+    });
+
+    API.setElements([rectangle]);
+    API.setSelectedElements([rectangle]);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_DOWN);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_UP);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.CTRL_OR_CMD);
+
+    // last node should be the one that's selected
+    const rightMostNode = h.elements[h.elements.length - 2];
+    expect(rightMostNode.type).toBe("rectangle");
+    expect(h.state.selectedElementIds[rightMostNode.id]).toBe(true);
+
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_LEFT);
+      Keyboard.keyPress(KEYS.ARROW_LEFT);
+      Keyboard.keyPress(KEYS.ARROW_LEFT);
+      Keyboard.keyPress(KEYS.ARROW_LEFT);
+      Keyboard.keyPress(KEYS.ARROW_LEFT);
+    });
+    Keyboard.keyUp(KEYS.ALT);
+
+    expect(h.state.selectedElementIds[rectangle.id]).toBe(true);
+
+    // going any direction takes us to the predecessor as well
+    const predecessorToRightMostNode = h.elements[h.elements.length - 4];
+    expect(predecessorToRightMostNode.type).toBe("rectangle");
+
+    API.setSelectedElements([rightMostNode] as NonDeletedExcalidrawElement[]);
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_RIGHT);
+    });
+    Keyboard.keyUp(KEYS.ALT);
+    expect(h.state.selectedElementIds[rightMostNode.id]).not.toBe(true);
+    expect(h.state.selectedElementIds[predecessorToRightMostNode.id]).toBe(
+      true,
+    );
+    API.setSelectedElements([rightMostNode] as NonDeletedExcalidrawElement[]);
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_UP);
+    });
+    Keyboard.keyUp(KEYS.ALT);
+    expect(h.state.selectedElementIds[rightMostNode.id]).not.toBe(true);
+    expect(h.state.selectedElementIds[predecessorToRightMostNode.id]).toBe(
+      true,
+    );
+    API.setSelectedElements([rightMostNode] as NonDeletedExcalidrawElement[]);
+    Keyboard.withModifierKeys({ alt: true }, () => {
+      Keyboard.keyPress(KEYS.ARROW_DOWN);
+    });
+    Keyboard.keyUp(KEYS.ALT);
+    expect(h.state.selectedElementIds[rightMostNode.id]).not.toBe(true);
+    expect(h.state.selectedElementIds[predecessorToRightMostNode.id]).toBe(
+      true,
+    );
+  });
+});

packages/element/tests/fractionalIndex.test.ts

@@ -0,0 +1,877 @@
+/* eslint-disable no-lone-blocks */
+import { arrayToMap } from "@excalidraw/common";
+
+import {
+  InvalidFractionalIndexError,
+  syncInvalidIndices,
+  syncMovedIndices,
+  validateFractionalIndices,
+} from "@excalidraw/element";
+
+import { deepCopyElement } from "@excalidraw/element";
+
+import { API } from "@excalidraw/excalidraw/tests/helpers/api";
+
+import {
+  generateKeyBetween,
+  validateOrderKey,
+} from "@excalidraw/fractional-indexing";
+
+import type {
+  ElementsMap,
+  ExcalidrawElement,
+  FractionalIndex,
+} from "@excalidraw/element/types";
+
+describe("fractional index format validation", () => {
+  it("should reject malformed base62 order keys", () => {
+    expect(() => validateOrderKey("a!")).toThrow();
+    expect(() => validateOrderKey("a_")).toThrow();
+    expect(() => validateOrderKey("a1!")).toThrow();
+    expect(() => validateOrderKey("a1_")).toThrow();
+    expect(() => validateOrderKey("zd0032")).toThrow();
+  });
+
+  it("should accept valid base62 order keys", () => {
+    expect(() => validateOrderKey("Zz")).not.toThrow();
+    expect(() => validateOrderKey("a0")).not.toThrow();
+    expect(() => validateOrderKey("a1")).not.toThrow();
+    expect(() => validateOrderKey("a1V")).not.toThrow();
+    expect(() => validateOrderKey("z".padEnd(28, "z"))).not.toThrow();
+  });
+});
+
+describe("sync invalid indices with array order", () => {
+  describe("should NOT sync empty array", () => {
+    testMovedIndicesSync({
+      elements: [],
+      movedElements: [],
+      expect: {
+        unchangedElements: [],
+        validInput: true,
+      },
+    });
+
+    testInvalidIndicesSync({
+      elements: [],
+      expect: {
+        unchangedElements: [],
+        validInput: true,
+      },
+    });
+  });
+
+  describe("should NOT sync when index is well defined", () => {
+    testMovedIndicesSync({
+      elements: [{ id: "A", index: "a1" }],
+      movedElements: [],
+      expect: {
+        unchangedElements: ["A"],
+        validInput: true,
+      },
+    });
+
+    testInvalidIndicesSync({
+      elements: [{ id: "A", index: "a1" }],
+      expect: {
+        unchangedElements: ["A"],
+        validInput: true,
+      },
+    });
+  });
+
+  describe("should NOT sync when indices are well defined", () => {
+    testMovedIndicesSync({
+      elements: [
+        { id: "A", index: "a1" },
+        { id: "B", index: "a2" },
+        { id: "C", index: "a3" },
+      ],
+      movedElements: [],
+      expect: {
+        unchangedElements: ["A", "B", "C"],
+        validInput: true,
+      },
+    });
+
+    testInvalidIndicesSync({
+      elements: [
+        { id: "A", index: "a1" },
+        { id: "B", index: "a2" },
+        { id: "C", index: "a3" },
+      ],
+      expect: {
+        unchangedElements: ["A", "B", "C"],
+        validInput: true,
+      },
+    });
+  });
+
+  describe("should sync when fractional index is not defined", () => {
+    testMovedIndicesSync({
+      elements: [{ id: "A" }],
+      movedElements: ["A"],
+      expect: {
+        unchangedElements: [],
+      },
+    });
+
+    testInvalidIndicesSync({
+      elements: [{ id: "A" }],
+      expect: {
+        unchangedElements: [],
+      },
+    });
+  });
+
+  describe("should sync when fractional index is malformed", () => {
+    // "zd0032" has head "z" which requires length 28 per getIntegerLength,
+    // but the string is far too short, so validateOrderKey throws for it
+    testInvalidIndicesSync({
+      elements: [{ id: "A", index: "zd0032" }],
+      expect: {
+        unchangedElements: [],
+      },
+    });
+
+    testInvalidIndicesSync({
+      elements: [
+        { id: "A", index: "a1" },
+        { id: "B", index: "zd0032" },
+        { id: "C", index: "a3" },
+      ],
+      expect: {
+        unchangedElements: ["A", "C"],
+      },
+    });
+
+    testInvalidIndicesSync({
+      elements: [{ id: "A", index: "a!" }],
+      expect: {
+        unchangedElements: [],
+      },
+    });
+
+    testInvalidIndicesSync({
+      elements: [
+        { id: "A", index: "a1" },
+        { id: "B", index: "a!" },
+        { id: "C", index: "a2" },
+      ],
+      expect: {
+        unchangedElements: ["A", "C"],
+      },
+    });
+  });
+
+  describe("should sync when fractional indices are duplicated", () => {
+    testInvalidIndicesSync({
+      elements: [
+        { id: "A", index: "a1" },
+        { id: "B", index: "a1" },
+      ],
+      expect: {
+        unchangedElements: ["A"],
+      },
+    });
+
+    testInvalidIndicesSync({
+      elements: [
+        { id: "A", index: "a1" },
+        { id: "B", index: "a1" },
+      ],
+      expect: {
+        unchangedElements: ["A"],
+      },
+    });
+  });
+
+  describe("should sync when a fractional index is out of order", () => {
+    testMovedIndicesSync({
+      elements: [
+        { id: "A", index: "a2" },
+        { id: "B", index: "a1" },
+      ],
+      movedElements: ["B"],
+      expect: {
+        unchangedElements: ["A"],
+      },
+    });
+
+    testMovedIndicesSync({
+      elements: [
+        { id: "A", index: "a2" },
+        { id: "B", index: "a1" },
+      ],
+      movedElements: ["A"],
+      expect: {
+        unchangedElements: ["B"],
+      },
+    });
+
+    testInvalidIndicesSync({
+      elements: [
+        { id: "A", index: "a2" },
+        { id: "B", index: "a1" },
+      ],
+      expect: {
+        unchangedElements: ["A"],
+      },
+    });
+  });
+
+  describe("should sync when fractional indices are out of order", () => {
+    testMovedIndicesSync({
+      elements: [
+        { id: "A", index: "a3" },
+        { id: "B", index: "a2" },
+        { id: "C", index: "a1" },
+      ],
+      movedElements: ["B", "C"],
+      expect: {
+        unchangedElements: ["A"],
+      },
+    });
+
+    testInvalidIndicesSync({
+      elements: [
+        { id: "A", index: "a3" },
+        { id: "B", index: "a2" },
+        { id: "C", index: "a1" },
+      ],
+      expect: {
+        unchangedElements: ["A"],
+      },
+    });
+  });
+
+  describe("should sync when incorrect fractional index is in between correct ones ", () => {
+    testMovedIndicesSync({
+      elements: [
+        { id: "A", index: "a1" },
+        { id: "B", index: "a0" },
+        { id: "C", index: "a2" },
+      ],
+      movedElements: ["B"],
+      expect: {
+        unchangedElements: ["A", "C"],
+      },
+    });
+
+    testInvalidIndicesSync({
+      elements: [
+        { id: "A", index: "a1" },
+        { id: "B", index: "a0" },
+        { id: "C", index: "a2" },
+      ],
+      expect: {
+        unchangedElements: ["A", "C"],
+      },
+    });
+  });
+
+  describe("should sync when incorrect fractional index is on top and duplicated below", () => {
+    testMovedIndicesSync({
+      elements: [
+        { id: "A", index: "a1" },
+        { id: "B", index: "a2" },
+        { id: "C", index: "a1" },
+      ],
+      movedElements: ["C"],
+      expect: {
+        unchangedElements: ["A", "B"],
+      },
+    });
+
+    testInvalidIndicesSync({
+      elements: [
+        { id: "A", index: "a1" },
+        { id: "B", index: "a2" },
+        { id: "C", index: "a1" },
+      ],
+      expect: {
+        unchangedElements: ["A", "B"],
+      },
+    });
+  });
+
+  describe("should sync when given a mix of duplicate / invalid indices", () => {
+    testMovedIndicesSync({
+      elements: [
+        { id: "A", index: "a0" },
+        { id: "B", index: "a2" },
+        { id: "C", index: "a1" },
+        { id: "D", index: "a1" },
+        { id: "E", index: "a2" },
+      ],
+      movedElements: ["C", "D", "E"],
+      expect: {
+        unchangedElements: ["A", "B"],
+      },
+    });
+
+    testInvalidIndicesSync({
+      elements: [
+        { id: "A", index: "a0" },
+        { id: "B", index: "a2" },
+        { id: "C", index: "a1" },
+        { id: "D", index: "a1" },
+        { id: "E", index: "a2" },
+      ],
+      expect: {
+        unchangedElements: ["A", "B"],
+      },
+    });
+  });
+
+  describe("should sync when given a mix of undefined / invalid indices", () => {
+    testMovedIndicesSync({
+      elements: [
+        { id: "A" },
+        { id: "B" },
+        { id: "C", index: "a0" },
+        { id: "D", index: "a2" },
+        { id: "E" },
+        { id: "F", index: "a3" },
+        { id: "G" },
+        { id: "H", index: "a1" },
+        { id: "I", index: "a2" },
+        { id: "J" },
+      ],
+      movedElements: ["A", "B", "E", "G", "H", "I", "J"],
+      expect: {
+        unchangedElements: ["C", "D", "F"],
+      },
+    });
+
+    testInvalidIndicesSync({
+      elements: [
+        { id: "A" },
+        { id: "B" },
+        { id: "C", index: "a0" },
+        { id: "D", index: "a2" },
+        { id: "E" },
+        { id: "F", index: "a3" },
+        { id: "G" },
+        { id: "H", index: "a1" },
+        { id: "I", index: "a2" },
+        { id: "J" },
+      ],
+      expect: {
+        unchangedElements: ["C", "D", "F"],
+      },
+    });
+  });
+
+  describe("should sync all moved elements regardless of their validity", () => {
+    testMovedIndicesSync({
+      elements: [
+        { id: "A", index: "a2" },
+        { id: "B", index: "a4" },
+      ],
+      movedElements: ["A"],
+      expect: {
+        validInput: true,
+        unchangedElements: ["B"],
+      },
+    });
+
+    testMovedIndicesSync({
+      elements: [
+        { id: "A", index: "a2" },
+        { id: "B", index: "a4" },
+      ],
+      movedElements: ["B"],
+      expect: {
+        validInput: true,
+        unchangedElements: ["A"],
+      },
+    });
+
+    testMovedIndicesSync({
+      elements: [
+        { id: "C", index: "a2" },
+        { id: "D", index: "a3" },
+        { id: "A", index: "a0" },
+        { id: "B", index: "a1" },
+      ],
+      movedElements: ["C", "D"],
+      expect: {
+        unchangedElements: ["A", "B"],
+      },
+    });
+
+    testMovedIndicesSync({
+      elements: [
+        { id: "A", index: "a1" },
+        { id: "B", index: "a2" },
+        { id: "D", index: "a4" },
+        { id: "C", index: "a3" },
+        { id: "F", index: "a6" },
+        { id: "E", index: "a5" },
+        { id: "H", index: "a8" },
+        { id: "G", index: "a7" },
+        { id: "I", index: "a9" },
+      ],
+      movedElements: ["D", "F", "H"],
+      expect: {
+        unchangedElements: ["A", "B", "C", "E", "G", "I"],
+      },
+    });
+
+    {
+      testMovedIndicesSync({
+        elements: [
+          { id: "A", index: "a1" },
+          { id: "B", index: "a0" },
+          { id: "C", index: "a2" },
+        ],
+        movedElements: ["B", "C"],
+        expect: {
+          unchangedElements: ["A"],
+        },
+      });
+
+      testMovedIndicesSync({
+        elements: [
+          { id: "A", index: "a1" },
+          { id: "B", index: "a0" },
+          { id: "C", index: "a2" },
+        ],
+        movedElements: ["A", "B"],
+        expect: {
+          unchangedElements: ["C"],
+        },
+      });
+    }
+
+    testMovedIndicesSync({
+      elements: [
+        { id: "A", index: "a0" },
+        { id: "B", index: "a2" },
+        { id: "C", index: "a1" },
+        { id: "D", index: "a1" },
+        { id: "E", index: "a2" },
+      ],
+      movedElements: ["B", "D", "E"],
+      expect: {
+        unchangedElements: ["A", "C"],
+      },
+    });
+
+    testMovedIndicesSync({
+      elements: [
+        { id: "A" },
+        { id: "B" },
+        { id: "C", index: "a0" },
+        { id: "D", index: "a2" },
+        { id: "E" },
+        { id: "F", index: "a3" },
+        { id: "G" },
+        { id: "H", index: "a1" },
+        { id: "I", index: "a2" },
+        { id: "J" },
+      ],
+      movedElements: ["A", "B", "D", "E", "F", "G", "J"],
+      expect: {
+        unchangedElements: ["C", "H", "I"],
+      },
+    });
+  });
+
+  describe("should generate fractions for explicitly moved elements", () => {
+    describe("should generate a fraction between 'A' and 'C'", () => {
+      testMovedIndicesSync({
+        elements: [
+          { id: "A", index: "a1" },
+          // doing actual fractions, without jitter 'a1' becomes 'a1V'
+          // as V is taken as the charset's middle-right value
+          { id: "B", index: "a1" },
+          { id: "C", index: "a2" },
+        ],
+        movedElements: ["B"],
+        expect: {
+          unchangedElements: ["A", "C"],
+        },
+      });
+
+      testInvalidIndicesSync({
+        elements: [
+          { id: "A", index: "a1" },
+          { id: "B", index: "a1" },
+          { id: "C", index: "a2" },
+        ],
+        expect: {
+          // as above, B will become fractional
+          unchangedElements: ["A", "C"],
+        },
+      });
+    });
+
+    describe("should generate fractions given duplicated indices", () => {
+      testMovedIndicesSync({
+        elements: [
+          { id: "A", index: "a01" },
+          { id: "B", index: "a01" },
+          { id: "C", index: "a01" },
+          { id: "D", index: "a01" },
+          { id: "E", index: "a02" },
+          { id: "F", index: "a02" },
+          { id: "G", index: "a02" },
+        ],
+        movedElements: ["B", "C", "D", "E", "F"],
+        expect: {
+          unchangedElements: ["A", "G"],
+        },
+      });
+
+      testMovedIndicesSync({
+        elements: [
+          { id: "A", index: "a01" },
+          { id: "B", index: "a01" },
+          { id: "C", index: "a01" },
+          { id: "D", index: "a01" },
+          { id: "E", index: "a02" },
+          { id: "F", index: "a02" },
+          { id: "G", index: "a02" },
+        ],
+        movedElements: ["A", "C", "D", "E", "G"],
+        expect: {
+          unchangedElements: ["B", "F"],
+        },
+      });
+
+      testMovedIndicesSync({
+        elements: [
+          { id: "A", index: "a01" },
+          { id: "B", index: "a01" },
+          { id: "C", index: "a01" },
+          { id: "D", index: "a01" },
+          { id: "E", index: "a02" },
+          { id: "F", index: "a02" },
+          { id: "G", index: "a02" },
+        ],
+        movedElements: ["B", "C", "D", "F", "G"],
+        expect: {
+          unchangedElements: ["A", "E"],
+        },
+      });
+
+      testInvalidIndicesSync({
+        elements: [
+          { id: "A", index: "a01" },
+          { id: "B", index: "a01" },
+          { id: "C", index: "a01" },
+          { id: "D", index: "a01" },
+          { id: "E", index: "a02" },
+          { id: "F", index: "a02" },
+          { id: "G", index: "a02" },
+        ],
+        expect: {
+          // notice fallback considers first item (E) as a valid one
+          unchangedElements: ["A", "E"],
+        },
+      });
+    });
+  });
+
+  describe("should be able to sync 20K invalid indices", () => {
+    const length = 20_000;
+
+    describe("should sync all empty indices", () => {
+      const elements = Array.from({ length }).map((_, index) => ({
+        id: `A_${index}`,
+      }));
+
+      testMovedIndicesSync({
+        // elements without fractional index
+        elements,
+        movedElements: Array.from({ length }).map((_, index) => `A_${index}`),
+        expect: {
+          unchangedElements: [],
+        },
+      });
+
+      testInvalidIndicesSync({
+        // elements without fractional index
+        elements,
+        expect: {
+          unchangedElements: [],
+        },
+      });
+    });
+
+    describe("should sync all but last index given a growing array of indices", () => {
+      let lastIndex: string | null = null;
+
+      const elements = Array.from({ length }).map((_, index) => {
+        // going up from 'a0'
+        lastIndex = generateKeyBetween(lastIndex, null);
+
+        return {
+          id: `A_${index}`,
+          // assigning the last generated index, so sync can go down from there
+          // without jitter lastIndex is 'c4BZ' for 20000th element
+          index: index === length - 1 ? lastIndex : undefined,
+        };
+      });
+      const movedElements = Array.from({ length }).map(
+        (_, index) => `A_${index}`,
+      );
+      // remove last element
+      movedElements.pop();
+
+      testMovedIndicesSync({
+        elements,
+        movedElements,
+        expect: {
+          unchangedElements: [`A_${length - 1}`],
+        },
+      });
+
+      testInvalidIndicesSync({
+        elements,
+        expect: {
+          unchangedElements: [`A_${length - 1}`],
+        },
+      });
+    });
+
+    describe("should sync all but first index given a declining array of indices", () => {
+      let lastIndex: string | null = null;
+
+      const elements = Array.from({ length }).map((_, index) => {
+        // going down from 'a0'
+        lastIndex = generateKeyBetween(null, lastIndex);
+
+        return {
+          id: `A_${index}`,
+          // without jitter lastIndex is 'XvoR' for 20000th element
+          index: lastIndex,
+        };
+      });
+      const movedElements = Array.from({ length }).map(
+        (_, index) => `A_${index}`,
+      );
+      // remove first element
+      movedElements.shift();
+
+      testMovedIndicesSync({
+        elements,
+        movedElements,
+        expect: {
+          unchangedElements: [`A_0`],
+        },
+      });
+
+      testInvalidIndicesSync({
+        elements,
+        expect: {
+          unchangedElements: [`A_0`],
+        },
+      });
+    });
+  });
+
+  describe("should automatically fallback to fixing all invalid indices", () => {
+    describe("should fallback to syncing duplicated indices when moved elements are empty", () => {
+      testMovedIndicesSync({
+        elements: [
+          { id: "A", index: "a1" },
+          { id: "B", index: "a1" },
+          { id: "C", index: "a1" },
+        ],
+        // the validation will throw as nothing was synced
+        // therefore it will lead to triggering the fallback and fixing all invalid indices
+        movedElements: [],
+        expect: {
+          unchangedElements: ["A"],
+        },
+      });
+    });
+
+    describe("should fallback to syncing undefined / invalid indices when moved elements are empty", () => {
+      testMovedIndicesSync({
+        elements: [
+          { id: "A", index: "a1" },
+          { id: "B" },
+          { id: "C", index: "a0" },
+        ],
+        // since elements are invalid, this will fail the validation
+        // leading to fallback fixing "B" and "C"
+        movedElements: [],
+        expect: {
+          unchangedElements: ["A"],
+        },
+      });
+    });
+
+    describe("should fallback to syncing unordered indices when moved element is invalid", () => {
+      testMovedIndicesSync({
+        elements: [
+          { id: "A", index: "a1" },
+          { id: "B", index: "a2" },
+          { id: "C", index: "a1" },
+        ],
+        movedElements: ["A"],
+        expect: {
+          unchangedElements: ["A", "B"],
+        },
+      });
+    });
+
+    describe("should fallback when trying to generate an index in between unordered elements", () => {
+      testMovedIndicesSync({
+        elements: [
+          { id: "A", index: "a2" },
+          { id: "B" },
+          { id: "C", index: "a1" },
+        ],
+        // 'B' is invalid, but so is 'C', which was not marked as moved
+        // therefore it will try to generate a key between 'a2' and 'a1'
+        // which it cannot do, thus will throw during generation and automatically fallback
+        movedElements: ["B"],
+        expect: {
+          unchangedElements: ["A"],
+        },
+      });
+    });
+
+    describe("should fallback when trying to generate an index in between duplicate indices", () => {
+      testMovedIndicesSync({
+        elements: [
+          { id: "A", index: "a01" },
+          { id: "B" },
+          { id: "C" },
+          { id: "D", index: "a01" },
+          { id: "E", index: "a01" },
+          { id: "F", index: "a01" },
+          { id: "G" },
+          { id: "I", index: "a03" },
+          { id: "H" },
+        ],
+        // missed "E" therefore upper bound for 'B' is a01, while lower bound is 'a02'
+        // therefore, similarly to above, it will fail during key generation and lead to fallback
+        movedElements: ["B", "C", "D", "F", "G", "H"],
+        expect: {
+          unchangedElements: ["A", "I"],
+        },
+      });
+    });
+  });
+});
+
+function testMovedIndicesSync(args: {
+  elements: { id: string; index?: string }[];
+  movedElements: string[];
+  expect: {
+    unchangedElements: string[];
+    validInput?: true;
+  };
+}) {
+  const [elements, movedElements] = prepareArguments(
+    args.elements,
+    args.movedElements,
+  );
+  const expectUnchangedElements = arrayToMap(
+    args.expect.unchangedElements.map((x) => ({ id: x })),
+  );
+
+  test(
+    "should sync invalid indices of moved elements or fallback",
+    elements,
+    movedElements,
+    expectUnchangedElements,
+    args.expect.validInput,
+  );
+}
+
+function testInvalidIndicesSync(args: {
+  elements: { id: string; index?: string }[];
+  expect: {
+    unchangedElements: string[];
+    validInput?: true;
+  };
+}) {
+  const [elements] = prepareArguments(args.elements);
+  const expectUnchangedElements = arrayToMap(
+    args.expect.unchangedElements.map((x) => ({ id: x })),
+  );
+
+  test(
+    "should sync invalid indices of all elements",
+    elements,
+    undefined,
+    expectUnchangedElements,
+    args.expect.validInput,
+  );
+}
+
+function prepareArguments(
+  elementsLike: { id: string; index?: string }[],
+  movedElementsIds?: string[],
+): [ExcalidrawElement[], ElementsMap | undefined] {
+  const elements = elementsLike.map((x) =>
+    API.createElement({ id: x.id, index: x.index as FractionalIndex }),
+  );
+  const movedMap = arrayToMap(movedElementsIds || []);
+  const movedElements = movedElementsIds
+    ? arrayToMap(elements.filter((x) => movedMap.has(x.id)))
+    : undefined;
+
+  return [elements, movedElements];
+}
+
+function test(
+  name: string,
+  elements: ExcalidrawElement[],
+  movedElements: ElementsMap | undefined,
+  expectUnchangedElements: Map<string, { id: string }>,
+  expectValidInput?: boolean,
+) {
+  it(name, () => {
+    // ensure the input is invalid (unless the flag is on)
+    if (!expectValidInput) {
+      expect(() =>
+        validateFractionalIndices(elements, {
+          shouldThrow: true,
+          includeBoundTextValidation: true,
+          ignoreLogs: true,
+        }),
+      ).toThrowError(InvalidFractionalIndexError);
+    }
+
+    // clone due to mutation
+    const clonedElements = elements.map((x) => deepCopyElement(x));
+
+    // act
+    const syncedElements = movedElements
+      ? syncMovedIndices(clonedElements, movedElements)
+      : syncInvalidIndices(clonedElements);
+
+    expect(syncedElements.length).toBe(elements.length);
+    expect(() =>
+      validateFractionalIndices(syncedElements, {
+        shouldThrow: true,
+        includeBoundTextValidation: true,
+        ignoreLogs: true,
+      }),
+    ).not.toThrowError(InvalidFractionalIndexError);
+
+    syncedElements.forEach((synced, index) => {
+      const element = elements[index];
+      // ensure the order hasn't changed
+      expect(synced.id).toBe(element.id);
+
+      if (expectUnchangedElements.has(synced.id)) {
+        // ensure we didn't mutate where we didn't want to mutate
+        expect(synced.index).toBe(elements[index].index);
+        expect(synced.version).toBe(elements[index].version);
+      } else {
+        expect(synced.index).not.toBe(elements[index].index);
+        // ensure we mutated just once, even with fallback triggered
+        expect(synced.version).toBe(elements[index].version + 1);
+      }
+    });
+  });
+}

packages/element/tests/newElement.test.ts

@@ -0,0 +1,52 @@
+import * as common from "@excalidraw/common";
+
+import { API } from "@excalidraw/excalidraw/tests/helpers/api";
+
+import { newElement, newLinearElement } from "../src/newElement";
+import { mutateElement, newElementWith } from "../src/mutateElement";
+
+describe("element creation time", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it.each([
+    "rectangle",
+    "diamond",
+    "ellipse",
+    "text",
+    "line",
+    "arrow",
+    "freedraw",
+    "image",
+    "frame",
+    "magicframe",
+    "embeddable",
+    "iframe",
+  ] as const)("initializes a new %s before any capture", (type) => {
+    vi.spyOn(common, "getUpdatedTimestamp").mockReturnValue(123);
+    const element = API.createElement({ type });
+    expect(element.created).toBe(123);
+
+    vi.mocked(common.getUpdatedTimestamp).mockReturnValue(456);
+    const edited = newElementWith(element, { x: 50 });
+    mutateElement(edited, new Map(), { y: 50 });
+
+    expect(edited).toMatchObject({ created: 123, updated: 456 });
+  });
+
+  it.each([123, 0, null])(
+    "preserves explicit created=%s when reconstructing the same element",
+    (created) => {
+      const original = newElement({
+        type: "rectangle",
+        x: 0,
+        y: 0,
+        created,
+      });
+      const converted = newLinearElement({ ...original, type: "line" });
+
+      expect(converted).toMatchObject({ id: original.id, created });
+    },
+  );
+});

packages/element/tests/recognizeShape.test.ts

@@ -0,0 +1,327 @@
+import type { GlobalPoint } from "@excalidraw/math";
+
+import { recognizeShape } from "../src/convertToShape";
+
+// Deterministic jitter, so a run that passes keeps passing.
+let seed = 1;
+const random = () => {
+  seed = (seed * 1103515245 + 12345) % 2147483648;
+  return seed / 2147483648 - 0.5;
+};
+
+// Draw the shape somewhere else, at another size, turned by `angle`, with a
+// wobbly hand.
+const sketch = (
+  points: readonly [number, number][],
+  { angle = 0, scale = 1, noise = 0 } = {},
+): GlobalPoint[] =>
+  points.map(([x, y]) => {
+    const nx = x * scale + random() * noise;
+    const ny = y * scale + random() * noise;
+    return [
+      nx * Math.cos(angle) - ny * Math.sin(angle) + 600,
+      nx * Math.sin(angle) + ny * Math.cos(angle) + 600,
+    ] as GlobalPoint;
+  });
+
+const edge = (
+  from: readonly [number, number],
+  to: readonly [number, number],
+  steps: number,
+): [number, number][] =>
+  Array.from({ length: steps }, (_, i) => [
+    from[0] + ((to[0] - from[0]) * i) / steps,
+    from[1] + ((to[1] - from[1]) * i) / steps,
+  ]);
+
+const outline = (corners: readonly [number, number][]): [number, number][] => [
+  ...corners.flatMap((corner, i) => edge(corner, corners[(i + 1) % 4], 18)),
+  corners[0],
+];
+
+const rectangle = (w: number, h: number) =>
+  outline([
+    [-w / 2, -h / 2],
+    [w / 2, -h / 2],
+    [w / 2, h / 2],
+    [-w / 2, h / 2],
+  ]);
+
+const diamond = (w: number, h: number) =>
+  outline([
+    [0, -h / 2],
+    [w / 2, 0],
+    [0, h / 2],
+    [-w / 2, 0],
+  ]);
+
+const ellipse = (rx: number, ry: number): [number, number][] => {
+  const points: [number, number][] = [];
+  for (let a = 0; a <= Math.PI * 2 + 0.05; a += 0.1) {
+    points.push([Math.cos(a) * rx, Math.sin(a) * ry]);
+  }
+  return points;
+};
+
+// Moving-average smoothing: rounds every corner the way a relaxed pen does.
+const smooth = (
+  pts: readonly [number, number][],
+  window: number,
+): [number, number][] =>
+  pts.map((_, i) => {
+    let sx = 0;
+    let sy = 0;
+    for (let k = -window; k <= window; k++) {
+      const [x, y] = pts[(i + k + pts.length) % pts.length];
+      sx += x;
+      sy += y;
+    }
+    return [sx / (2 * window + 1), sy / (2 * window + 1)];
+  });
+
+// A sloppy hand-drawn "rectangle" that tapers, bucket-like: wider at the top
+// than the bottom. Its hull fill ratio, (topW + bottomW) / (2 * topW), lands
+// right at an ellipse's PI/4 — only its sharp corners tell the two apart.
+const taperedRectangle = (
+  topW: number,
+  bottomW: number,
+  h: number,
+): [number, number][] =>
+  outline([
+    [-topW / 2, -h / 2],
+    [topW / 2, -h / 2],
+    [bottomW / 2, h / 2],
+    [-bottomW / 2, h / 2],
+  ]);
+
+// A rectangle drawn with broad, pen-like rounded corners. Its outline is a
+// superellipse midway between an ellipse (exponent 2) and a sharp rectangle.
+const roundedRectangle = (rx: number, ry: number): [number, number][] => {
+  const points: [number, number][] = [];
+  for (let a = 0; a <= Math.PI * 2 + 0.05; a += 0.1) {
+    const cos = Math.cos(a);
+    const sin = Math.sin(a);
+    points.push([
+      Math.sign(cos) * Math.sqrt(Math.abs(cos)) * rx,
+      Math.sign(sin) * Math.sqrt(Math.abs(sin)) * ry,
+    ]);
+  }
+  return points;
+};
+
+const line = (length: number) => edge([-length / 2, 0], [length / 2, 0], 40);
+
+/** A shaft, then a V head traced back from the tip and over itself. */
+const arrow = (length: number, headRatio: number): [number, number][] => {
+  const tip: [number, number] = [length / 2, 0];
+  const headLength = length * headRatio;
+  const arm = (side: number): [number, number] => [
+    tip[0] - headLength * Math.cos(Math.PI / 6),
+    tip[1] - side * headLength * Math.sin(Math.PI / 6),
+  ];
+  return [
+    ...edge([-length / 2, 0], tip, 24),
+    ...edge(tip, arm(1), 8),
+    ...edge(arm(1), tip, 8),
+    ...edge(tip, arm(-1), 8),
+  ];
+};
+
+const SCALES = [0.5, 1, 2, 4];
+
+describe("recognizeShape", () => {
+  describe("is invariant to where, how big and how rotated a shape is drawn", () => {
+    // A rectangle turned 45° *is* a diamond, so these two are only swept over
+    // the right angles that map them onto themselves. Every other class is
+    // swept over arbitrary angles.
+    const RIGHT_ANGLES = [0, Math.PI / 2, Math.PI, (3 * Math.PI) / 2];
+    // 4.7 rad is within a degree of vertical — the size gate compares the
+    // larger bounding-box dimension, so thin (near-)axis-aligned strokes are
+    // recognized like any other.
+    const ANY_ANGLES = [0, 0.3, Math.PI / 4, 1.2, Math.PI / 2, 2.5, 4.7];
+
+    const cases: [string, [number, number][], number[], string][] = [
+      ["a square", rectangle(200, 200), RIGHT_ANGLES, "rectangle"],
+      ["a wide rectangle", rectangle(300, 150), RIGHT_ANGLES, "rectangle"],
+      ["a thin rectangle", rectangle(500, 100), RIGHT_ANGLES, "rectangle"],
+      [
+        "a tapered rectangle",
+        taperedRectangle(170, 100, 200),
+        RIGHT_ANGLES,
+        "rectangle",
+      ],
+      ["a diamond", diamond(200, 200), RIGHT_ANGLES, "diamond"],
+      ["a wide diamond", diamond(300, 150), RIGHT_ANGLES, "diamond"],
+      ["a circle", ellipse(100, 100), ANY_ANGLES, "ellipse"],
+      ["an ellipse", ellipse(150, 75), ANY_ANGLES, "ellipse"],
+      ["a line", line(300), ANY_ANGLES, "line"],
+      ["an arrow with a small head", arrow(300, 0.15), ANY_ANGLES, "arrow"],
+      ["an arrow with a large head", arrow(300, 0.45), ANY_ANGLES, "arrow"],
+    ];
+
+    it.each(cases)("recognizes %s", (_name, points, angles, expected) => {
+      for (const angle of angles) {
+        for (const scale of SCALES) {
+          for (const noise of [0, 3]) {
+            expect({
+              angle,
+              scale,
+              noise,
+              type: recognizeShape(
+                sketch(points, { angle, scale, noise }),
+                null,
+              ).type,
+            }).toEqual({ angle, scale, noise, type: expected });
+          }
+        }
+      }
+    });
+  });
+
+  it("tells an arrow from a line by the points its head piles up", () => {
+    const options = { angle: 0.3 };
+    expect(recognizeShape(sketch(line(300), options), null).type).toBe("line");
+    expect(recognizeShape(sketch(arrow(300, 0.3), options), null).type).toBe(
+      "arrow",
+    );
+  });
+
+  it("recognizes an outline the user didn't quite close", () => {
+    const gapped = rectangle(200, 200).slice(0, -6);
+
+    expect(recognizeShape(sketch(gapped), null).type).toBe("rectangle");
+  });
+
+  it("recognizes a pen-drawn outline with rounded corners as a rectangle", () => {
+    expect(recognizeShape(sketch(roundedRectangle(100, 70)), null).type).toBe(
+      "rectangle",
+    );
+
+    // ...while a true ellipse of the same proportions remains an ellipse
+    expect(recognizeShape(sketch(ellipse(100, 70)), null).type).toBe("ellipse");
+  });
+
+  it("tells a tapered, bucket-like rectangle from an ellipse by its corners", () => {
+    // proportions traced from real sketches that used to recognize as
+    // ellipses: hull fill ≈ 0.8 ≈ PI/4, so corner sharpness must decide
+    const buckets: [number, number, number][] = [
+      [110, 65, 220],
+      [110, 65, 130],
+      [75, 50, 115],
+      [120, 60, 250],
+    ];
+
+    for (const [topW, bottomW, h] of buckets) {
+      // lightly rounded corners + wobble, like the real strokes
+      const points = sketch(smooth(taperedRectangle(topW, bottomW, h), 2), {
+        noise: 2,
+      });
+
+      expect({
+        bucket: [topW, bottomW, h],
+        type: recognizeShape(points, null).type,
+      }).toEqual({ bucket: [topW, bottomW, h], type: "rectangle" });
+    }
+  });
+
+  it("does not read sharply bent open strokes as lines or arrows", () => {
+    const semicircle: [number, number][] = Array.from(
+      { length: 40 },
+      (_, i) => {
+        const a = (Math.PI * i) / 39;
+        return [Math.cos(a) * 150, Math.sin(a) * 150];
+      },
+    );
+    const sawtooth: [number, number][] = Array.from({ length: 31 }, (_, i) => [
+      i * 10,
+      (i % 2) * 60,
+    ]);
+
+    const bent: [string, [number, number][]][] = [
+      [
+        "a right-angle elbow",
+        [...edge([0, 0], [110, 110], 20), ...edge([110, 110], [220, 0], 20)],
+      ],
+      [
+        "an L shape",
+        [...edge([0, 0], [0, 150], 20), ...edge([0, 150], [150, 150], 20)],
+      ],
+      [
+        "a checkmark",
+        [...edge([0, 60], [60, 120], 12), ...edge([60, 120], [200, 0], 24)],
+      ],
+      ["a semicircular arc", semicircle],
+      ["a sawtooth", sawtooth],
+    ];
+
+    for (const [name, points] of bent) {
+      expect({
+        name,
+        type: recognizeShape(sketch(points, { noise: 2 }), null).type,
+      }).toEqual({ name, type: "freedraw" });
+    }
+  });
+
+  it("still reads a lazily bowed or squiggly stroke as a line", () => {
+    const bowed: [number, number][] = Array.from({ length: 40 }, (_, i) => {
+      const t = i / 39;
+      return [t * 300, Math.sin(t * Math.PI) * 24];
+    });
+    const squiggly: [number, number][] = Array.from({ length: 40 }, (_, i) => {
+      const t = i / 39;
+      return [t * 300, Math.sin(t * Math.PI * 4) * 12];
+    });
+
+    expect(recognizeShape(sketch(bowed, { noise: 2 }), null).type).toBe("line");
+    expect(recognizeShape(sketch(squiggly, { noise: 2 }), null).type).toBe(
+      "line",
+    );
+  });
+
+  it("leaves a stroke that resembles no known shape as freedraw", () => {
+    const squiggle: [number, number][] = Array.from({ length: 60 }, (_, i) => [
+      i * 4 - 120,
+      Math.sin(i / 2) * 70 + random() * 20,
+    ]);
+
+    expect(recognizeShape(sketch(squiggle), null).type).toBe("freedraw");
+  });
+
+  it("only extends an arrow with another arrow", () => {
+    const previous = { type: "arrow" } as Parameters<typeof recognizeShape>[1];
+
+    expect(
+      recognizeShape(sketch(arrow(300, 0.3), { angle: 0.3 }), previous).type,
+    ).toBe("arrow");
+    expect(recognizeShape(sketch(rectangle(200, 200)), previous).type).toBe(
+      "freedraw",
+    );
+  });
+
+  it("ignores a stroke too small to be a shape", () => {
+    const tiny: [number, number][] = [
+      [0, 0],
+      [1, 1],
+      [2, 0],
+      [1, -1],
+    ];
+
+    expect(recognizeShape(sketch(tiny), null).type).toBe("freedraw");
+  });
+
+  it("gates on apparent (screen) size, so zoom decides what is too small", () => {
+    const smallCircle = ellipse(8, 8); // 16 scene units across
+
+    expect(recognizeShape(sketch(smallCircle), null).type).toBe("freedraw");
+    expect(recognizeShape(sketch(smallCircle), null, 10).type).toBe("ellipse");
+
+    // 300 apparent px at 0.1 zoom
+    expect(
+      recognizeShape(sketch(line(3000), { angle: 0.3 }), null, 0.1).type,
+    ).toBe("line");
+    // 10 apparent px at 0.1 zoom
+    expect(
+      recognizeShape(sketch(line(100), { angle: 0.3 }), null, 0.1).type,
+    ).toBe("freedraw");
+  });
+});

packages/element/tests/selection.test.ts

@@ -0,0 +1,35 @@
+import { makeNextSelectedElementIds } from "../src/selection";
+
+describe("makeNextSelectedElementIds", () => {
+  const _makeNextSelectedElementIds = (
+    selectedElementIds: { [id: string]: true },
+    prevSelectedElementIds: { [id: string]: true },
+    expectUpdated: boolean,
+  ) => {
+    const ret = makeNextSelectedElementIds(selectedElementIds, {
+      selectedElementIds: prevSelectedElementIds,
+    });
+    expect(ret === selectedElementIds).toBe(expectUpdated);
+  };
+  it("should return prevState selectedElementIds if no change", () => {
+    _makeNextSelectedElementIds({}, {}, false);
+    _makeNextSelectedElementIds({ 1: true }, { 1: true }, false);
+    _makeNextSelectedElementIds(
+      { 1: true, 2: true },
+      { 1: true, 2: true },
+      false,
+    );
+  });
+  it("should return new selectedElementIds if changed", () => {
+    // _makeNextSelectedElementIds({ 1: true }, { 1: false }, true);
+    _makeNextSelectedElementIds({ 1: true }, {}, true);
+    _makeNextSelectedElementIds({}, { 1: true }, true);
+    _makeNextSelectedElementIds({ 1: true }, { 2: true }, true);
+    _makeNextSelectedElementIds({ 1: true }, { 1: true, 2: true }, true);
+    _makeNextSelectedElementIds(
+      { 1: true, 2: true },
+      { 1: true, 3: true },
+      true,
+    );
+  });
+});

packages/element/tests/sizeHelpers.test.ts

@@ -0,0 +1,58 @@
+import { vi } from "vitest";
+
+import { getPerfectElementSize } from "../src/sizeHelpers";
+
+const EPSILON_DIGITS = 3;
+// Needed so that we can mock the value of constants which is done in
+// below tests. In Jest this wasn't needed as global override was possible
+// but vite doesn't allow that hence we need to mock
+vi.mock(
+  "@excalidraw/common",
+  //@ts-ignore
+  async (importOriginal) => {
+    const module: any = await importOriginal();
+    return { ...module };
+  },
+);
+describe("getPerfectElementSize", () => {
+  it("should return height:0 if `elementType` is line and locked angle is 0", () => {
+    const { height, width } = getPerfectElementSize("line", 149, 10);
+    expect(width).toBeCloseTo(149, EPSILON_DIGITS);
+    expect(height).toBeCloseTo(0, EPSILON_DIGITS);
+  });
+
+  it("should return width:0 if `elementType` is line and locked angle is 90 deg (Math.PI/2)", () => {
+    const { height, width } = getPerfectElementSize("line", 10, 140);
+    expect(width).toBeCloseTo(0, EPSILON_DIGITS);
+    expect(height).toBeCloseTo(140, EPSILON_DIGITS);
+  });
+
+  it("should return height:0 if `elementType` is arrow and locked angle is 0", () => {
+    const { height, width } = getPerfectElementSize("arrow", 200, 20);
+    expect(width).toBeCloseTo(200, EPSILON_DIGITS);
+    expect(height).toBeCloseTo(0, EPSILON_DIGITS);
+  });
+  it("should return width:0 if `elementType` is arrow and locked angle is 90 deg (Math.PI/2)", () => {
+    const { height, width } = getPerfectElementSize("arrow", 10, 100);
+    expect(width).toBeCloseTo(0, EPSILON_DIGITS);
+    expect(height).toBeCloseTo(100, EPSILON_DIGITS);
+  });
+
+  it("should return adjust height to be width * tan(locked angle)", () => {
+    const { height, width } = getPerfectElementSize("arrow", 120, 185);
+    expect(width).toBeCloseTo(120, EPSILON_DIGITS);
+    expect(height).toBeCloseTo(207.846, EPSILON_DIGITS);
+  });
+
+  it("should return height equals to width if locked angle is 45 deg", () => {
+    const { height, width } = getPerfectElementSize("arrow", 135, 145);
+    expect(width).toBeCloseTo(135, EPSILON_DIGITS);
+    expect(height).toBeCloseTo(135, EPSILON_DIGITS);
+  });
+
+  it("should return height:0 and width:0 when width and height are 0", () => {
+    const { height, width } = getPerfectElementSize("arrow", 0, 0);
+    expect(width).toBeCloseTo(0, EPSILON_DIGITS);
+    expect(height).toBeCloseTo(0, EPSILON_DIGITS);
+  });
+});

packages/element/tests/sortElements.test.ts

@@ -0,0 +1,446 @@
+import { API } from "@excalidraw/excalidraw/tests/helpers/api";
+
+import { mutateElement } from "@excalidraw/element";
+
+import { normalizeElementOrder } from "../src/sortElements";
+
+import type { ExcalidrawElement } from "../src/types";
+
+const { h } = window;
+const assertOrder = (
+  elements: readonly ExcalidrawElement[],
+  expectedOrder: string[],
+) => {
+  const actualOrder = elements.map((element) => element.id);
+  expect(actualOrder).toEqual(expectedOrder);
+};
+
+describe("normalizeElementsOrder", () => {
+  it("sort bound-text elements", () => {
+    const container = API.createElement({
+      id: "container",
+      type: "rectangle",
+    });
+    const boundText = API.createElement({
+      id: "boundText",
+      type: "text",
+      containerId: container.id,
+    });
+    const otherElement = API.createElement({
+      id: "otherElement",
+      type: "rectangle",
+      boundElements: [],
+    });
+    const otherElement2 = API.createElement({
+      id: "otherElement2",
+      type: "rectangle",
+      boundElements: [],
+    });
+
+    mutateElement(container, new Map(), {
+      boundElements: [{ type: "text", id: boundText.id }],
+    });
+
+    assertOrder(normalizeElementOrder([container, boundText]), [
+      "container",
+      "boundText",
+    ]);
+    assertOrder(normalizeElementOrder([boundText, container]), [
+      "container",
+      "boundText",
+    ]);
+    assertOrder(
+      normalizeElementOrder([
+        boundText,
+        container,
+        otherElement,
+        otherElement2,
+      ]),
+      ["container", "boundText", "otherElement", "otherElement2"],
+    );
+    assertOrder(normalizeElementOrder([container, otherElement, boundText]), [
+      "container",
+      "boundText",
+      "otherElement",
+    ]);
+    assertOrder(
+      normalizeElementOrder([
+        container,
+        otherElement,
+        otherElement2,
+        boundText,
+      ]),
+      ["container", "boundText", "otherElement", "otherElement2"],
+    );
+
+    assertOrder(
+      normalizeElementOrder([
+        boundText,
+        otherElement,
+        container,
+        otherElement2,
+      ]),
+      ["otherElement", "container", "boundText", "otherElement2"],
+    );
+
+    // noop
+    assertOrder(
+      normalizeElementOrder([
+        otherElement,
+        container,
+        boundText,
+        otherElement2,
+      ]),
+      ["otherElement", "container", "boundText", "otherElement2"],
+    );
+
+    // text has existing containerId, but container doesn't list is
+    // as a boundElement
+    assertOrder(
+      normalizeElementOrder([
+        API.createElement({
+          id: "boundText",
+          type: "text",
+          containerId: "container",
+        }),
+        API.createElement({
+          id: "container",
+          type: "rectangle",
+        }),
+      ]),
+      ["boundText", "container"],
+    );
+    assertOrder(
+      normalizeElementOrder([
+        API.createElement({
+          id: "boundText",
+          type: "text",
+          containerId: "container",
+        }),
+      ]),
+      ["boundText"],
+    );
+    assertOrder(
+      normalizeElementOrder([
+        API.createElement({
+          id: "container",
+          type: "rectangle",
+          boundElements: [],
+        }),
+      ]),
+      ["container"],
+    );
+    assertOrder(
+      normalizeElementOrder([
+        API.createElement({
+          id: "container",
+          type: "rectangle",
+          boundElements: [{ id: "x", type: "text" }],
+        }),
+      ]),
+      ["container"],
+    );
+    assertOrder(
+      normalizeElementOrder([
+        API.createElement({
+          id: "arrow",
+          type: "arrow",
+        }),
+        API.createElement({
+          id: "container",
+          type: "rectangle",
+          boundElements: [{ id: "arrow", type: "arrow" }],
+        }),
+      ]),
+      ["arrow", "container"],
+    );
+  });
+
+  it("normalize group order", () => {
+    assertOrder(
+      normalizeElementOrder([
+        API.createElement({
+          id: "A_rect1",
+          type: "rectangle",
+          groupIds: ["A"],
+        }),
+        API.createElement({
+          id: "rect2",
+          type: "rectangle",
+        }),
+        API.createElement({
+          id: "rect3",
+          type: "rectangle",
+        }),
+        API.createElement({
+          id: "A_rect4",
+          type: "rectangle",
+          groupIds: ["A"],
+        }),
+        API.createElement({
+          id: "A_rect5",
+          type: "rectangle",
+          groupIds: ["A"],
+        }),
+        API.createElement({
+          id: "rect6",
+          type: "rectangle",
+        }),
+        API.createElement({
+          id: "A_rect7",
+          type: "rectangle",
+          groupIds: ["A"],
+        }),
+      ]),
+      ["A_rect1", "A_rect4", "A_rect5", "A_rect7", "rect2", "rect3", "rect6"],
+    );
+    assertOrder(
+      normalizeElementOrder([
+        API.createElement({
+          id: "A_rect1",
+          type: "rectangle",
+          groupIds: ["A"],
+        }),
+        API.createElement({
+          id: "rect2",
+          type: "rectangle",
+        }),
+        API.createElement({
+          id: "B_rect3",
+          type: "rectangle",
+          groupIds: ["B"],
+        }),
+        API.createElement({
+          id: "A_rect4",
+          type: "rectangle",
+          groupIds: ["A"],
+        }),
+        API.createElement({
+          id: "B_rect5",
+          type: "rectangle",
+          groupIds: ["B"],
+        }),
+        API.createElement({
+          id: "rect6",
+          type: "rectangle",
+        }),
+        API.createElement({
+          id: "A_rect7",
+          type: "rectangle",
+          groupIds: ["A"],
+        }),
+      ]),
+      ["A_rect1", "A_rect4", "A_rect7", "rect2", "B_rect3", "B_rect5", "rect6"],
+    );
+    // nested groups
+    assertOrder(
+      normalizeElementOrder([
+        API.createElement({
+          id: "A_rect1",
+          type: "rectangle",
+          groupIds: ["A"],
+        }),
+        API.createElement({
+          id: "BA_rect2",
+          type: "rectangle",
+          groupIds: ["B", "A"],
+        }),
+      ]),
+      ["A_rect1", "BA_rect2"],
+    );
+    assertOrder(
+      normalizeElementOrder([
+        API.createElement({
+          id: "BA_rect1",
+          type: "rectangle",
+          groupIds: ["B", "A"],
+        }),
+        API.createElement({
+          id: "A_rect2",
+          type: "rectangle",
+          groupIds: ["A"],
+        }),
+      ]),
+      ["BA_rect1", "A_rect2"],
+    );
+    assertOrder(
+      normalizeElementOrder([
+        API.createElement({
+          id: "BA_rect1",
+          type: "rectangle",
+          groupIds: ["B", "A"],
+        }),
+        API.createElement({
+          id: "A_rect2",
+          type: "rectangle",
+          groupIds: ["A"],
+        }),
+        API.createElement({
+          id: "CBA_rect3",
+          type: "rectangle",
+          groupIds: ["C", "B", "A"],
+        }),
+        API.createElement({
+          id: "rect4",
+          type: "rectangle",
+        }),
+        API.createElement({
+          id: "A_rect5",
+          type: "rectangle",
+          groupIds: ["A"],
+        }),
+        API.createElement({
+          id: "BA_rect5",
+          type: "rectangle",
+          groupIds: ["B", "A"],
+        }),
+        API.createElement({
+          id: "BA_rect6",
+          type: "rectangle",
+          groupIds: ["B", "A"],
+        }),
+        API.createElement({
+          id: "CBA_rect7",
+          type: "rectangle",
+          groupIds: ["C", "B", "A"],
+        }),
+        API.createElement({
+          id: "X_rect8",
+          type: "rectangle",
+          groupIds: ["X"],
+        }),
+        API.createElement({
+          id: "rect9",
+          type: "rectangle",
+        }),
+        API.createElement({
+          id: "YX_rect10",
+          type: "rectangle",
+          groupIds: ["Y", "X"],
+        }),
+        API.createElement({
+          id: "X_rect11",
+          type: "rectangle",
+          groupIds: ["X"],
+        }),
+      ]),
+      [
+        "BA_rect1",
+        "CBA_rect3",
+        "CBA_rect7",
+        "BA_rect5",
+        "BA_rect6",
+        "A_rect2",
+        "A_rect5",
+        "rect4",
+        "X_rect8",
+        "YX_rect10",
+        "X_rect11",
+        "rect9",
+      ],
+    );
+    assertOrder(
+      normalizeElementOrder([
+        API.createElement({
+          id: "A_rect1",
+          type: "rectangle",
+          groupIds: ["A"],
+        }),
+        API.createElement({
+          id: "CBA_rect2",
+          type: "rectangle",
+          groupIds: ["C", "B", "A"],
+        }),
+        API.createElement({
+          id: "A_rect3",
+          type: "rectangle",
+          groupIds: ["A"],
+        }),
+      ]),
+      ["A_rect1", "CBA_rect2", "A_rect3"],
+    );
+    assertOrder(
+      normalizeElementOrder([
+        API.createElement({
+          id: "abcT_rect1",
+          type: "rectangle",
+          groupIds: ["ab", "c", "T"],
+        }),
+        API.createElement({
+          id: "abcT_rect2",
+          type: "rectangle",
+          groupIds: ["a", "bc", "T"],
+        }),
+        API.createElement({
+          id: "abcT_rect3",
+          type: "rectangle",
+          groupIds: ["ab", "c", "T"],
+        }),
+      ]),
+      ["abcT_rect1", "abcT_rect3", "abcT_rect2"],
+    );
+  });
+
+  // TODO
+  it.skip("normalize boundElements array", () => {
+    const container = API.createElement({
+      id: "container",
+      type: "rectangle",
+      boundElements: [],
+    });
+    const boundText = API.createElement({
+      id: "boundText",
+      type: "text",
+      containerId: container.id,
+    });
+
+    h.app.scene.mutateElement(container, {
+      boundElements: [
+        { type: "text", id: boundText.id },
+        { type: "text", id: "xxx" },
+      ],
+    });
+
+    expect(normalizeElementOrder([container, boundText])).toEqual([
+      expect.objectContaining({
+        id: container.id,
+      }),
+      expect.objectContaining({ id: boundText.id }),
+    ]);
+  });
+
+  // should take around <100ms for 10K iterations (@dwelle's PC 22-05-25)
+  it.skip("normalizeElementsOrder() perf", () => {
+    const makeElements = (iterations: number) => {
+      const elements: ExcalidrawElement[] = [];
+      while (iterations--) {
+        const container = API.createElement({
+          type: "rectangle",
+          boundElements: [],
+          groupIds: ["B", "A"],
+        });
+        const boundText = API.createElement({
+          type: "text",
+          containerId: container.id,
+          groupIds: ["A"],
+        });
+        const otherElement = API.createElement({
+          type: "rectangle",
+          boundElements: [],
+          groupIds: ["C", "A"],
+        });
+        h.app.scene.mutateElement(container, {
+          boundElements: [{ type: "text", id: boundText.id }],
+        });
+
+        elements.push(boundText, otherElement, container);
+      }
+      return elements;
+    };
+
+    const elements = makeElements(10000);
+    const t0 = Date.now();
+    normalizeElementOrder(elements);
+    console.info(`${Date.now() - t0}ms`);
+  });
+});

packages/element/tests/textElement.test.ts

@@ -0,0 +1,379 @@
+import { getLineHeight } from "@excalidraw/common";
+import { API } from "@excalidraw/excalidraw/tests/helpers/api";
+
+import { FONT_FAMILY, TEXT_ALIGN, VERTICAL_ALIGN } from "@excalidraw/common";
+
+import {
+  computeContainerDimensionForBoundText,
+  getContainerCoords,
+  getBoundTextMaxWidth,
+  getBoundTextMaxHeight,
+  computeBoundTextPosition,
+} from "../src/textElement";
+import { detectLineHeight, getLineHeightInPx } from "../src/textMeasurements";
+
+import type { ExcalidrawTextElementWithContainer } from "../src/types";
+
+describe("Test measureText", () => {
+  describe("Test getContainerCoords", () => {
+    const params = { width: 200, height: 100, x: 10, y: 20 };
+
+    it("should compute coords correctly when ellipse", () => {
+      const element = API.createElement({
+        type: "ellipse",
+        ...params,
+      });
+      expect(getContainerCoords(element)).toEqual({
+        x: 44.2893218813452455,
+        y: 39.64466094067262,
+      });
+    });
+
+    it("should compute coords correctly when rectangle", () => {
+      const element = API.createElement({
+        type: "rectangle",
+        ...params,
+      });
+      expect(getContainerCoords(element)).toEqual({
+        x: 15,
+        y: 25,
+      });
+    });
+
+    it("should compute coords correctly when diamond", () => {
+      const element = API.createElement({
+        type: "diamond",
+        ...params,
+      });
+      expect(getContainerCoords(element)).toEqual({
+        x: 65,
+        y: 50,
+      });
+    });
+  });
+
+  describe("Test computeContainerDimensionForBoundText", () => {
+    const params = {
+      width: 178,
+      height: 194,
+    };
+
+    it("should compute container height correctly for rectangle", () => {
+      const element = API.createElement({
+        type: "rectangle",
+        ...params,
+      });
+      expect(computeContainerDimensionForBoundText(150, element.type)).toEqual(
+        160,
+      );
+    });
+
+    it("should compute container height correctly for ellipse", () => {
+      const element = API.createElement({
+        type: "ellipse",
+        ...params,
+      });
+      expect(computeContainerDimensionForBoundText(150, element.type)).toEqual(
+        226,
+      );
+    });
+
+    it("should compute container height correctly for diamond", () => {
+      const element = API.createElement({
+        type: "diamond",
+        ...params,
+      });
+      expect(computeContainerDimensionForBoundText(150, element.type)).toEqual(
+        320,
+      );
+    });
+  });
+
+  describe("Test getBoundTextMaxWidth", () => {
+    const params = {
+      width: 178,
+      height: 194,
+    };
+
+    it("should return max width when container is rectangle", () => {
+      const container = API.createElement({ type: "rectangle", ...params });
+      expect(getBoundTextMaxWidth(container, null)).toBe(168);
+    });
+
+    it("should return max width when container is ellipse", () => {
+      const container = API.createElement({ type: "ellipse", ...params });
+      expect(getBoundTextMaxWidth(container, null)).toBe(116);
+    });
+
+    it("should return max width when container is diamond", () => {
+      const container = API.createElement({ type: "diamond", ...params });
+      expect(getBoundTextMaxWidth(container, null)).toBe(79);
+    });
+  });
+
+  describe("Test getBoundTextMaxHeight", () => {
+    const params = {
+      width: 178,
+      height: 194,
+      id: '"container-id',
+    };
+
+    const boundTextElement = API.createElement({
+      type: "text",
+      id: "text-id",
+      x: 560.51171875,
+      y: 202.033203125,
+      width: 154,
+      height: 175,
+      fontSize: 20,
+      fontFamily: 1,
+      text: "Excalidraw is a\nvirtual \nopensource \nwhiteboard for \nsketching \nhand-drawn like\ndiagrams",
+      textAlign: "center",
+      verticalAlign: "middle",
+      containerId: params.id,
+    }) as ExcalidrawTextElementWithContainer;
+
+    it("should return max height when container is rectangle", () => {
+      const container = API.createElement({ type: "rectangle", ...params });
+      expect(getBoundTextMaxHeight(container, boundTextElement)).toBe(184);
+    });
+
+    it("should return max height when container is ellipse", () => {
+      const container = API.createElement({ type: "ellipse", ...params });
+      expect(getBoundTextMaxHeight(container, boundTextElement)).toBe(127);
+    });
+
+    it("should return max height when container is diamond", () => {
+      const container = API.createElement({ type: "diamond", ...params });
+      expect(getBoundTextMaxHeight(container, boundTextElement)).toBe(87);
+    });
+
+    it("should return max height when container is arrow", () => {
+      const container = API.createElement({
+        type: "arrow",
+        ...params,
+      });
+      expect(getBoundTextMaxHeight(container, boundTextElement)).toBe(194);
+    });
+
+    it("should return max height when container is arrow and height is less than threshold", () => {
+      const container = API.createElement({
+        type: "arrow",
+        ...params,
+        height: 70,
+        boundElements: [{ type: "text", id: "text-id" }],
+      });
+
+      expect(getBoundTextMaxHeight(container, boundTextElement)).toBe(
+        boundTextElement.height,
+      );
+    });
+  });
+});
+
+const textElement = API.createElement({
+  type: "text",
+  text: "Excalidraw is a\nvirtual \nopensource \nwhiteboard for \nsketching \nhand-drawn like\ndiagrams",
+  fontSize: 20,
+  fontFamily: 1,
+  height: 175,
+});
+
+describe("Test detectLineHeight", () => {
+  it("should return correct line height", () => {
+    expect(detectLineHeight(textElement)).toBe(1.25);
+  });
+});
+
+describe("Test getLineHeightInPx", () => {
+  it("should return correct line height", () => {
+    expect(
+      getLineHeightInPx(textElement.fontSize, textElement.lineHeight),
+    ).toBe(25);
+  });
+});
+
+describe("Test getDefaultLineHeight", () => {
+  it("should return line height using default font family when not passed", () => {
+    //@ts-ignore
+    expect(getLineHeight()).toBe(1.25);
+  });
+
+  it("should return line height using default font family for unknown font", () => {
+    const UNKNOWN_FONT = 5;
+    expect(getLineHeight(UNKNOWN_FONT)).toBe(1.25);
+  });
+
+  it("should return correct line height", () => {
+    expect(getLineHeight(FONT_FAMILY.Cascadia)).toBe(1.2);
+  });
+});
+
+describe("Test computeBoundTextPosition", () => {
+  const createMockElementsMap = () => new Map();
+
+  // Helper function to create rectangle test case with 90-degree rotation
+  const createRotatedRectangleTestCase = (
+    textAlign: string,
+    verticalAlign: string,
+  ) => {
+    const container = API.createElement({
+      type: "rectangle",
+      x: 100,
+      y: 100,
+      width: 200,
+      height: 100,
+      angle: (Math.PI / 2) as any, // 90 degrees
+    });
+
+    const boundTextElement = API.createElement({
+      type: "text",
+      width: 80,
+      height: 40,
+      text: "hello darkness my old friend",
+      textAlign: textAlign as any,
+      verticalAlign: verticalAlign as any,
+      containerId: container.id,
+    }) as ExcalidrawTextElementWithContainer;
+
+    const elementsMap = createMockElementsMap();
+
+    return { container, boundTextElement, elementsMap };
+  };
+
+  describe("90-degree rotation with all alignment combinations", () => {
+    // Test all 9 combinations of horizontal (left, center, right) and vertical (top, middle, bottom) alignment
+
+    it("should position text with LEFT + TOP alignment at 90-degree rotation", () => {
+      const { container, boundTextElement, elementsMap } =
+        createRotatedRectangleTestCase(TEXT_ALIGN.LEFT, VERTICAL_ALIGN.TOP);
+
+      const result = computeBoundTextPosition(
+        container,
+        boundTextElement,
+        elementsMap,
+      );
+
+      expect(result.x).toBeCloseTo(185, 1);
+      expect(result.y).toBeCloseTo(75, 1);
+    });
+
+    it("should position text with LEFT + MIDDLE alignment at 90-degree rotation", () => {
+      const { container, boundTextElement, elementsMap } =
+        createRotatedRectangleTestCase(TEXT_ALIGN.LEFT, VERTICAL_ALIGN.MIDDLE);
+
+      const result = computeBoundTextPosition(
+        container,
+        boundTextElement,
+        elementsMap,
+      );
+
+      expect(result.x).toBeCloseTo(160, 1);
+      expect(result.y).toBeCloseTo(75, 1);
+    });
+
+    it("should position text with LEFT + BOTTOM alignment at 90-degree rotation", () => {
+      const { container, boundTextElement, elementsMap } =
+        createRotatedRectangleTestCase(TEXT_ALIGN.LEFT, VERTICAL_ALIGN.BOTTOM);
+
+      const result = computeBoundTextPosition(
+        container,
+        boundTextElement,
+        elementsMap,
+      );
+
+      expect(result.x).toBeCloseTo(135, 1);
+      expect(result.y).toBeCloseTo(75, 1);
+    });
+
+    it("should position text with CENTER + TOP alignment at 90-degree rotation", () => {
+      const { container, boundTextElement, elementsMap } =
+        createRotatedRectangleTestCase(TEXT_ALIGN.CENTER, VERTICAL_ALIGN.TOP);
+
+      const result = computeBoundTextPosition(
+        container,
+        boundTextElement,
+        elementsMap,
+      );
+
+      expect(result.x).toBeCloseTo(185, 1);
+      expect(result.y).toBeCloseTo(130, 1);
+    });
+
+    it("should position text with CENTER + MIDDLE alignment at 90-degree rotation", () => {
+      const { container, boundTextElement, elementsMap } =
+        createRotatedRectangleTestCase(
+          TEXT_ALIGN.CENTER,
+          VERTICAL_ALIGN.MIDDLE,
+        );
+
+      const result = computeBoundTextPosition(
+        container,
+        boundTextElement,
+        elementsMap,
+      );
+
+      expect(result.x).toBeCloseTo(160, 1);
+      expect(result.y).toBeCloseTo(130, 1);
+    });
+
+    it("should position text with CENTER + BOTTOM alignment at 90-degree rotation", () => {
+      const { container, boundTextElement, elementsMap } =
+        createRotatedRectangleTestCase(
+          TEXT_ALIGN.CENTER,
+          VERTICAL_ALIGN.BOTTOM,
+        );
+
+      const result = computeBoundTextPosition(
+        container,
+        boundTextElement,
+        elementsMap,
+      );
+
+      expect(result.x).toBeCloseTo(135, 1);
+      expect(result.y).toBeCloseTo(130, 1);
+    });
+
+    it("should position text with RIGHT + TOP alignment at 90-degree rotation", () => {
+      const { container, boundTextElement, elementsMap } =
+        createRotatedRectangleTestCase(TEXT_ALIGN.RIGHT, VERTICAL_ALIGN.TOP);
+
+      const result = computeBoundTextPosition(
+        container,
+        boundTextElement,
+        elementsMap,
+      );
+
+      expect(result.x).toBeCloseTo(185, 1);
+      expect(result.y).toBeCloseTo(185, 1);
+    });
+
+    it("should position text with RIGHT + MIDDLE alignment at 90-degree rotation", () => {
+      const { container, boundTextElement, elementsMap } =
+        createRotatedRectangleTestCase(TEXT_ALIGN.RIGHT, VERTICAL_ALIGN.MIDDLE);
+
+      const result = computeBoundTextPosition(
+        container,
+        boundTextElement,
+        elementsMap,
+      );
+
+      expect(result.x).toBeCloseTo(160, 1);
+      expect(result.y).toBeCloseTo(185, 1);
+    });
+
+    it("should position text with RIGHT + BOTTOM alignment at 90-degree rotation", () => {
+      const { container, boundTextElement, elementsMap } =
+        createRotatedRectangleTestCase(TEXT_ALIGN.RIGHT, VERTICAL_ALIGN.BOTTOM);
+
+      const result = computeBoundTextPosition(
+        container,
+        boundTextElement,
+        elementsMap,
+      );
+
+      expect(result.x).toBeCloseTo(135, 1);
+      expect(result.y).toBeCloseTo(185, 1);
+    });
+  });
+});

packages/element/tests/textWrapping.test.ts

@@ -0,0 +1,703 @@
+import {
+  getWrappedTextLines,
+  parseTokens,
+  wrapText,
+} from "../src/textWrapping";
+
+import type { FontString } from "../src/types";
+
+describe("Test wrapText", () => {
+  // font is irrelevant as jsdom does not support FontFace API
+  // `measureText` width is mocked to return `text.length` by `jest-canvas-mock`
+  // https://github.com/hustcc/jest-canvas-mock/blob/master/src/classes/TextMetrics.js
+  const font = "10px Cascadia, Segoe UI Emoji" as FontString;
+
+  it("should wrap the text correctly when word length is exactly equal to max width", () => {
+    const text = "Hello Excalidraw";
+    // Length of "Excalidraw" is 100 and exacty equal to max width
+    const res = wrapText(text, font, 100);
+    expect(res).toEqual(`Hello\nExcalidraw`);
+  });
+
+  it("should return the text as is if max width is invalid", () => {
+    const text = "Hello Excalidraw";
+    expect(wrapText(text, font, NaN)).toEqual(text);
+    expect(wrapText(text, font, -1)).toEqual(text);
+    expect(wrapText(text, font, Infinity)).toEqual(text);
+  });
+
+  it("should show the text correctly when max width reached", () => {
+    const text = "Hello😀";
+    const maxWidth = 10;
+    const res = wrapText(text, font, maxWidth);
+    expect(res).toBe("H\ne\nl\nl\no\n😀");
+  });
+
+  it("should not wrap number when wrapping line", () => {
+    const text = "don't wrap this number 99,100.99";
+    const maxWidth = 300;
+    const res = wrapText(text, font, maxWidth);
+    expect(res).toBe("don't wrap this number\n99,100.99");
+  });
+
+  it("should trim all trailing whitespaces", () => {
+    const text = "Hello     ";
+    const maxWidth = 50;
+    const res = wrapText(text, font, maxWidth);
+    expect(res).toBe("Hello");
+  });
+
+  it("should trim all but one trailing whitespaces", () => {
+    const text = "Hello     ";
+    const maxWidth = 60;
+    const res = wrapText(text, font, maxWidth);
+    expect(res).toBe("Hello ");
+  });
+
+  it("should keep preceding whitespaces and trim all trailing whitespaces", () => {
+    const text = "  Hello  World";
+    const maxWidth = 90;
+    const res = wrapText(text, font, maxWidth);
+    expect(res).toBe("  Hello\nWorld");
+  });
+
+  it("should keep some preceding whitespaces, trim trailing whitespaces, but kep those that fit in the trailing line", () => {
+    const text = "   Hello  World            ";
+    const maxWidth = 90;
+    const res = wrapText(text, font, maxWidth);
+    expect(res).toBe("   Hello\nWorld    ");
+  });
+
+  it("should trim keep those whitespace that fit in the trailing line", () => {
+    const text = "Hello   Wo rl  d                     ";
+    const maxWidth = 100;
+    const res = wrapText(text, font, maxWidth);
+    expect(res).toBe("Hello   Wo\nrl  d     ");
+  });
+
+  it("should support multiple (multi-codepoint) emojis", () => {
+    const text = "😀🗺🔥👩🏽‍🦰👨‍👩‍👧‍👦🇨🇿";
+    const maxWidth = 1;
+    const res = wrapText(text, font, maxWidth);
+    expect(res).toBe("😀\n🗺\n🔥\n👩🏽‍🦰\n👨‍👩‍👧‍👦\n🇨🇿");
+  });
+
+  it("should wrap the text correctly when text contains hyphen", () => {
+    let text =
+      "Wikipedia is hosted by Wikimedia- Foundation, a non-profit organization that also hosts a range-of other projects";
+    const res = wrapText(text, font, 110);
+    expect(res).toBe(
+      `Wikipedia\nis hosted\nby\nWikimedia-\nFoundation,\na non-\nprofit\norganizatio\nn that also\nhosts a\nrange-of\nother\nprojects`,
+    );
+
+    text = "Hello thereusing-now";
+    expect(wrapText(text, font, 100)).toEqual("Hello\nthereusing\n-now");
+  });
+
+  it("should support wrapping nested lists", () => {
+    const text = `\tA) one tab\t\t- two tabs        - 8 spaces`;
+
+    const maxWidth = 100;
+    const res = wrapText(text, font, maxWidth);
+    expect(res).toBe(`\tA) one\ntab\t\t- two\ntabs\n- 8 spaces`);
+
+    const maxWidth2 = 50;
+    const res2 = wrapText(text, font, maxWidth2);
+    expect(res2).toBe(`\tA)\none\ntab\n- two\ntabs\n- 8\nspace\ns`);
+  });
+
+  it("should retain original text offsets for wrapped lines", () => {
+    expect(getWrappedTextLines("Hello World!", font, 60)).toEqual([
+      {
+        text: "Hello",
+        start: 0,
+        end: 5,
+      },
+      {
+        text: "World!",
+        start: 6,
+        end: 12,
+      },
+    ]);
+  });
+
+  it("should exclude whitespace trimmed away at soft-wrap boundaries from line offsets", () => {
+    expect(getWrappedTextLines("  Hello  World", font, 90)).toEqual([
+      {
+        text: "  Hello",
+        start: 0,
+        end: 7,
+      },
+      {
+        text: "World",
+        start: 9,
+        end: 14,
+      },
+    ]);
+  });
+
+  it("should retain offsets when wrapping a single long token", () => {
+    expect(getWrappedTextLines("Excalidraw", font, 50)).toEqual([
+      {
+        text: "Excal",
+        start: 0,
+        end: 5,
+      },
+      {
+        text: "idraw",
+        start: 5,
+        end: 10,
+      },
+    ]);
+  });
+
+  it("should preserve empty hard lines in metadata", () => {
+    expect(getWrappedTextLines("A\n\nB", font, 100)).toEqual([
+      {
+        text: "A",
+        start: 0,
+        end: 1,
+      },
+      {
+        text: "",
+        start: 2,
+        end: 2,
+      },
+      {
+        text: "B",
+        start: 3,
+        end: 4,
+      },
+    ]);
+  });
+
+  describe("When text is CJK", () => {
+    it("should break each CJK character when width is very small", () => {
+      // "안녕하세요" (Hangul) + "こんにちは世界" (Hiragana, Kanji) + "ｺﾝﾆﾁハ" (Katakana) + "你好" (Han) = "Hello Hello World Hello Hi"
+      const text = "안녕하세요こんにちは世界ｺﾝﾆﾁハ你好";
+      const maxWidth = 10;
+      const res = wrapText(text, font, maxWidth);
+      expect(res).toBe(
+        "안\n녕\n하\n세\n요\nこ\nん\nに\nち\nは\n世\n界\nｺ\nﾝ\nﾆ\nﾁ\nハ\n你\n好",
+      );
+    });
+
+    it("should break CJK text into longer segments when width is larger", () => {
+      // "안녕하세요" (Hangul) + "こんにちは世界" (Hiragana, Kanji) + "ｺﾝﾆﾁハ" (Katakana) + "你好" (Han) = "Hello Hello World Hello Hi"
+      const text = "안녕하세요こんにちは世界ｺﾝﾆﾁハ你好";
+      const maxWidth = 30;
+      const res = wrapText(text, font, maxWidth);
+
+      // measureText is mocked, so it's not precisely what would happen in prod
+      expect(res).toBe("안녕하\n세요こ\nんにち\nは世界\nｺﾝﾆ\nﾁハ你\n好");
+    });
+
+    it("should handle a combination of CJK, latin, emojis and whitespaces", () => {
+      const text = `a醫 醫      bb  你好  world-i-😀🗺🔥`;
+
+      const maxWidth = 150;
+      const res = wrapText(text, font, maxWidth);
+      expect(res).toBe(`a醫 醫      bb  你\n好  world-i-😀🗺\n🔥`);
+
+      const maxWidth2 = 50;
+      const res2 = wrapText(text, font, maxWidth2);
+      expect(res2).toBe(`a醫 醫\nbb  你\n好\nworld\n-i-😀\n🗺🔥`);
+
+      const maxWidth3 = 30;
+      const res3 = wrapText(text, font, maxWidth3);
+      expect(res3).toBe(`a醫\n醫\nbb\n你好\nwor\nld-\ni-\n😀\n🗺\n🔥`);
+    });
+
+    it("should break before and after a regular CJK character", () => {
+      const text = "HelloたWorld";
+      const maxWidth1 = 50;
+      const res1 = wrapText(text, font, maxWidth1);
+      expect(res1).toBe("Hello\nた\nWorld");
+
+      const maxWidth2 = 60;
+      const res2 = wrapText(text, font, maxWidth2);
+      expect(res2).toBe("Helloた\nWorld");
+    });
+
+    it("should break before and after certain CJK symbols", () => {
+      const text = "こんにちは〃世界";
+      const maxWidth1 = 50;
+      const res1 = wrapText(text, font, maxWidth1);
+      expect(res1).toBe("こんにちは\n〃世界");
+
+      const maxWidth2 = 60;
+      const res2 = wrapText(text, font, maxWidth2);
+      expect(res2).toBe("こんにちは〃\n世界");
+    });
+
+    it("should break after, not before for certain CJK pairs", () => {
+      const text = "Hello た。";
+      const maxWidth = 70;
+      const res = wrapText(text, font, maxWidth);
+      expect(res).toBe("Hello\nた。");
+    });
+
+    it("should break before, not after for certain CJK pairs", () => {
+      const text = "Hello「たWorld」";
+      const maxWidth = 60;
+      const res = wrapText(text, font, maxWidth);
+      expect(res).toBe("Hello\n「た\nWorld」");
+    });
+
+    it("should break after, not before for certain CJK character pairs", () => {
+      const text = "「Helloた」World";
+      const maxWidth = 70;
+      const res = wrapText(text, font, maxWidth);
+      expect(res).toBe("「Hello\nた」World");
+    });
+
+    it("should break Chinese sentences", () => {
+      const text = `中国你好！这是一个测试。
+我们来看看：人民币¥1234「很贵」
+（括号）、逗号，句号。空格 换行　全角符号…—`;
+
+      const maxWidth1 = 80;
+      const res1 = wrapText(text, font, maxWidth1);
+      expect(res1).toBe(`中国你好！这是一\n个测试。
+我们来看看：人民\n币¥1234「很\n贵」
+（括号）、逗号，\n句号。空格 换行\n全角符号…—`);
+
+      const maxWidth2 = 50;
+      const res2 = wrapText(text, font, maxWidth2);
+      expect(res2).toBe(`中国你好！\n这是一个测\n试。
+我们来看\n看：人民币\n¥1234\n「很贵」
+（括号）、\n逗号，句\n号。空格\n换行　全角\n符号…—`);
+    });
+
+    it("should break Japanese sentences", () => {
+      const text = `日本こんにちは！これはテストです。
+  見てみましょう：円￥1234「高い」
+  （括弧）、読点、句点。
+  空白 改行　全角記号…ー`;
+
+      const maxWidth1 = 80;
+      const res1 = wrapText(text, font, maxWidth1);
+      expect(res1).toBe(`日本こんにちは！\nこれはテストで\nす。
+  見てみましょ\nう：円￥1234\n「高い」
+  （括弧）、読\n点、句点。
+  空白 改行\n全角記号…ー`);
+
+      const maxWidth2 = 50;
+      const res2 = wrapText(text, font, maxWidth2);
+      expect(res2).toBe(`日本こんに\nちは！これ\nはテストで\nす。
+  見てみ\nましょう：\n円\n￥1234\n「高い」
+  （括\n弧）、読\n点、句点。
+  空白\n改行　全角\n記号…ー`);
+    });
+
+    it("should break Korean sentences", () => {
+      const text = `한국 안녕하세요! 이것은 테스트입니다.
+우리 보자: 원화₩1234「비싸다」
+(괄호), 쉼표, 마침표.
+공백 줄바꿈　전각기호…—`;
+
+      const maxWidth1 = 80;
+      const res1 = wrapText(text, font, maxWidth1);
+      expect(res1).toBe(`한국 안녕하세\n요! 이것은 테\n스트입니다.
+우리 보자: 원\n화₩1234「비\n싸다」
+(괄호), 쉼\n표, 마침표.
+공백 줄바꿈　전\n각기호…—`);
+
+      const maxWidth2 = 60;
+      const res2 = wrapText(text, font, maxWidth2);
+      expect(res2).toBe(`한국 안녕하\n세요! 이것\n은 테스트입\n니다.
+우리 보자:\n원화\n₩1234\n「비싸다」
+(괄호),\n쉼표, 마침\n표.
+공백 줄바꿈\n전각기호…—`);
+    });
+  });
+
+  describe("When text contains leading whitespaces", () => {
+    const text = "  \t   Hello world";
+
+    it("should preserve leading whitespaces", () => {
+      const maxWidth = 120;
+      const res = wrapText(text, font, maxWidth);
+      expect(res).toBe("  \t   Hello\nworld");
+    });
+
+    it("should break and collapse leading whitespaces when line breaks", () => {
+      const maxWidth = 60;
+      const res = wrapText(text, font, maxWidth);
+      expect(res).toBe("\nHello\nworld");
+    });
+
+    it("should break and collapse leading whitespaces whe words break", () => {
+      const maxWidth = 30;
+      const res = wrapText(text, font, maxWidth);
+      expect(res).toBe("\nHel\nlo\nwor\nld");
+    });
+  });
+
+  describe("When text contains trailing whitespaces", () => {
+    it("shouldn't add new lines for trailing spaces", () => {
+      const text = "Hello whats up     ";
+      const maxWidth = 190;
+      const res = wrapText(text, font, maxWidth);
+      expect(res).toBe(text);
+    });
+
+    it("should ignore trailing whitespaces when line breaks", () => {
+      const text = "Hippopotomonstrosesquippedaliophobia        ??????";
+      const maxWidth = 400;
+      const res = wrapText(text, font, maxWidth);
+      expect(res).toBe("Hippopotomonstrosesquippedaliophobia\n??????");
+    });
+
+    it("should not ignore trailing whitespaces when word breaks", () => {
+      const text = "Hippopotomonstrosesquippedaliophobia        ??????";
+      const maxWidth = 300;
+      const res = wrapText(text, font, maxWidth);
+      expect(res).toBe("Hippopotomonstrosesquippedalio\nphobia        ??????");
+    });
+
+    it("should ignore trailing whitespaces when word breaks and line breaks", () => {
+      const text = "Hippopotomonstrosesquippedaliophobia        ??????";
+      const maxWidth = 180;
+      const res = wrapText(text, font, maxWidth);
+      expect(res).toBe("Hippopotomonstrose\nsquippedaliophobia\n??????");
+    });
+  });
+
+  describe("When text doesn't contain new lines", () => {
+    const text = "Hello whats up";
+
+    [
+      {
+        desc: "break all words when width of each word is less than container width",
+        width: 70,
+        res: `Hello\nwhats\nup`,
+      },
+      {
+        desc: "break all characters when width of each character is less than container width",
+        width: 15,
+        res: `H\ne\nl\nl\no\nw\nh\na\nt\ns\nu\np`,
+      },
+      {
+        desc: "break words as per the width",
+
+        width: 130,
+        res: `Hello whats\nup`,
+      },
+      {
+        desc: "fit the container",
+
+        width: 240,
+        res: "Hello whats up",
+      },
+      {
+        desc: "push the word if its equal to max width",
+        width: 50,
+        res: `Hello\nwhats\nup`,
+      },
+    ].forEach((data) => {
+      it(`should ${data.desc}`, () => {
+        const res = wrapText(text, font, data.width);
+        expect(res).toEqual(data.res);
+      });
+    });
+  });
+
+  describe("When text contain new lines", () => {
+    const text = `Hello\n  whats up`;
+    [
+      {
+        desc: "break all words when width of each word is less than container width",
+        width: 70,
+        res: `Hello\n  whats\nup`,
+      },
+      {
+        desc: "break all characters when width of each character is less than container width",
+        width: 15,
+        res: `H\ne\nl\nl\no\n\nw\nh\na\nt\ns\nu\np`,
+      },
+      {
+        desc: "break words as per the width",
+        width: 140,
+        res: `Hello\n  whats up`,
+      },
+    ].forEach((data) => {
+      it(`should respect new lines and ${data.desc}`, () => {
+        const res = wrapText(text, font, data.width);
+        expect(res).toEqual(data.res);
+      });
+    });
+  });
+
+  describe("When text is long", () => {
+    const text = `hellolongtextthisiswhatsupwithyouIamtypingggggandtypinggg break it now`;
+    [
+      {
+        desc: "fit characters of long string as per container width",
+        width: 160,
+        res: `hellolongtextthi\nsiswhatsupwithyo\nuIamtypingggggan\ndtypinggg break\nit now`,
+      },
+      {
+        desc: "fit characters of long string as per container width and break words as per the width",
+
+        width: 120,
+        res: `hellolongtex\ntthisiswhats\nupwithyouIam\ntypingggggan\ndtypinggg\nbreak it now`,
+      },
+      {
+        desc: "fit the long text when container width is greater than text length and move the rest to next line",
+
+        width: 590,
+        res: `hellolongtextthisiswhatsupwithyouIamtypingggggandtypinggg\nbreak it now`,
+      },
+    ].forEach((data) => {
+      it(`should ${data.desc}`, () => {
+        const res = wrapText(text, font, data.width);
+        expect(res).toEqual(data.res);
+      });
+    });
+  });
+
+  describe("Test parseTokens", () => {
+    it("should tokenize latin", () => {
+      let text = "Excalidraw is a virtual collaborative whiteboard";
+
+      expect(parseTokens(text)).toEqual([
+        "Excalidraw",
+        " ",
+        "is",
+        " ",
+        "a",
+        " ",
+        "virtual",
+        " ",
+        "collaborative",
+        " ",
+        "whiteboard",
+      ]);
+
+      text =
+        "Wikipedia is hosted by Wikimedia- Foundation, a non-profit organization that also hosts a range-of other projects";
+      expect(parseTokens(text)).toEqual([
+        "Wikipedia",
+        " ",
+        "is",
+        " ",
+        "hosted",
+        " ",
+        "by",
+        " ",
+        "Wikimedia-",
+        " ",
+        "Foundation,",
+        " ",
+        "a",
+        " ",
+        "non-",
+        "profit",
+        " ",
+        "organization",
+        " ",
+        "that",
+        " ",
+        "also",
+        " ",
+        "hosts",
+        " ",
+        "a",
+        " ",
+        "range-",
+        "of",
+        " ",
+        "other",
+        " ",
+        "projects",
+      ]);
+    });
+
+    it("should not tokenize number", () => {
+      const text = "99,100.99";
+      const tokens = parseTokens(text);
+      expect(tokens).toEqual(["99,100.99"]);
+    });
+
+    it("should tokenize joined emojis", () => {
+      const text = `😬🌍🗺🔥☂️👩🏽‍🦰👨‍👩‍👧‍👦👩🏾‍🔬🏳️‍🌈🧔‍♀️🧑‍🤝‍🧑🙅🏽‍♂️✅0️⃣🇨🇿🦅`;
+      const tokens = parseTokens(text);
+
+      expect(tokens).toEqual([
+        "😬",
+        "🌍",
+        "🗺",
+        "🔥",
+        "☂️",
+        "👩🏽‍🦰",
+        "👨‍👩‍👧‍👦",
+        "👩🏾‍🔬",
+        "🏳️‍🌈",
+        "🧔‍♀️",
+        "🧑‍🤝‍🧑",
+        "🙅🏽‍♂️",
+        "✅",
+        "0️⃣",
+        "🇨🇿",
+        "🦅",
+      ]);
+    });
+
+    it("should tokenize emojis mixed with mixed text", () => {
+      const text = `😬a🌍b🗺c🔥d☂️《👩🏽‍🦰》👨‍👩‍👧‍👦德👩🏾‍🔬こ🏳️‍🌈안🧔‍♀️g🧑‍🤝‍🧑h🙅🏽‍♂️e✅f0️⃣g🇨🇿10🦅#hash`;
+      const tokens = parseTokens(text);
+
+      expect(tokens).toEqual([
+        "😬",
+        "a",
+        "🌍",
+        "b",
+        "🗺",
+        "c",
+        "🔥",
+        "d",
+        "☂️",
+        "《",
+        "👩🏽‍🦰",
+        "》",
+        "👨‍👩‍👧‍👦",
+        "德",
+        "👩🏾‍🔬",
+        "こ",
+        "🏳️‍🌈",
+        "안",
+        "🧔‍♀️",
+        "g",
+        "🧑‍🤝‍🧑",
+        "h",
+        "🙅🏽‍♂️",
+        "e",
+        "✅",
+        "f0️⃣g", // bummer, but ok, as we traded kecaps not breaking (less common) for hash and numbers not breaking (more common)
+        "🇨🇿",
+        "10", // nice! do not break the number, as it's by default matched by \p{Emoji}
+        "🦅",
+        "#hash", // nice! do not break the hash, as it's by default matched by \p{Emoji}
+      ]);
+    });
+
+    it("should tokenize decomposed chars into their composed variants", () => {
+      // each input character is in a decomposed form
+      const text = "čでäぴέ다й한";
+      expect(text.normalize("NFC").length).toEqual(8);
+      expect(text).toEqual(text.normalize("NFD"));
+
+      const tokens = parseTokens(text);
+      expect(tokens.length).toEqual(8);
+      expect(tokens).toEqual(["č", "で", "ä", "ぴ", "έ", "다", "й", "한"]);
+    });
+
+    it("should tokenize artificial CJK", () => {
+      const text = `《道德經》醫-醫こんにちは世界！안녕하세요세계；요』,다.다...원/달(((다)))[[1]]〚({((한))>)〛(「た」)た…[Hello] \t　World？ニューヨーク・￥3700.55す。090-1234-5678￥1,000〜＄5,000「素晴らしい！」〔重要〕＃１：Taro君30％は、（たなばた）〰￥110±￥570で20℃〜9:30〜10:00【一番】`;
+      // [
+      //   '《道',      '德',        '經》',           '醫-',
+      //   '醫',        'こ',        'ん',             'に',
+      //   'ち',        'は',        '世',             '界！',
+      //   '안',        '녕',        '하',             '세',
+      //   '요',        '세',        '계；',           '요』,',
+      //   '다.',       '다...',     '원/',            '달',
+      //   '(((다)))',  '[[1]]',     '〚({((한))>)〛', '(「た」)',
+      //   'た…',       '[Hello]',   ' ',              '\t',
+      //   '　',        'World？',   'ニ',             'ュ',
+      //   'ー',        'ヨ',        'ー',             'ク・',
+      //   '￥3700.55', 'す。',      '090-',           '1234-',
+      //   '5678',      '￥1,000〜', '＄5,000',        '「素',
+      //   '晴',        'ら',        'し',             'い！」',
+      //   '〔重',      '要〕',      '＃',             '１：',
+      //   'Taro',      '君',        '30％',           'は、',
+      //   '（た',      'な',        'ば',             'た）',
+      //   '〰',        '￥110±',    '￥570',          'で',
+      //   '20℃〜',     '9:30〜',    '10:00',          '【一',
+      //   '番】'
+      // ]
+      const tokens = parseTokens(text);
+
+      // Latin
+      expect(tokens).toContain("[[1]]");
+      expect(tokens).toContain("[Hello]");
+      expect(tokens).toContain("World？");
+      expect(tokens).toContain("Taro");
+
+      // Chinese
+      expect(tokens).toContain("《道");
+      expect(tokens).toContain("德");
+      expect(tokens).toContain("經》");
+      expect(tokens).toContain("醫-");
+      expect(tokens).toContain("醫");
+
+      // Japanese
+      expect(tokens).toContain("こ");
+      expect(tokens).toContain("ん");
+      expect(tokens).toContain("に");
+      expect(tokens).toContain("ち");
+      expect(tokens).toContain("は");
+      expect(tokens).toContain("世");
+      expect(tokens).toContain("ク・");
+      expect(tokens).toContain("界！");
+      expect(tokens).toContain("た…");
+      expect(tokens).toContain("す。");
+      expect(tokens).toContain("ュ");
+      expect(tokens).toContain("「素");
+      expect(tokens).toContain("晴");
+      expect(tokens).toContain("ら");
+      expect(tokens).toContain("し");
+      expect(tokens).toContain("い！」");
+      expect(tokens).toContain("君");
+      expect(tokens).toContain("は、");
+      expect(tokens).toContain("（た");
+      expect(tokens).toContain("な");
+      expect(tokens).toContain("ば");
+      expect(tokens).toContain("た）");
+      expect(tokens).toContain("で");
+      expect(tokens).toContain("【一");
+      expect(tokens).toContain("番】");
+
+      // Check for Korean
+      expect(tokens).toContain("안");
+      expect(tokens).toContain("녕");
+      expect(tokens).toContain("하");
+      expect(tokens).toContain("세");
+      expect(tokens).toContain("요");
+      expect(tokens).toContain("세");
+      expect(tokens).toContain("계；");
+      expect(tokens).toContain("요』,");
+      expect(tokens).toContain("다.");
+      expect(tokens).toContain("다...");
+      expect(tokens).toContain("원/");
+      expect(tokens).toContain("달");
+      expect(tokens).toContain("(((다)))");
+      expect(tokens).toContain("〚({((한))>)〛");
+      expect(tokens).toContain("(「た」)");
+
+      // Numbers and units
+      expect(tokens).toContain("￥3700.55");
+      expect(tokens).toContain("090-");
+      expect(tokens).toContain("1234-");
+      expect(tokens).toContain("5678");
+      expect(tokens).toContain("￥1,000〜");
+      expect(tokens).toContain("＄5,000");
+      expect(tokens).toContain("１：");
+      expect(tokens).toContain("30％");
+      expect(tokens).toContain("￥110±");
+      expect(tokens).toContain("20℃〜");
+      expect(tokens).toContain("9:30〜");
+      expect(tokens).toContain("10:00");
+
+      // Punctuation and symbols
+      expect(tokens).toContain(" ");
+      expect(tokens).toContain("\t");
+      expect(tokens).toContain("　");
+      expect(tokens).toContain("ニ");
+      expect(tokens).toContain("ー");
+      expect(tokens).toContain("ヨ");
+      expect(tokens).toContain("〰");
+      expect(tokens).toContain("＃");
+    });
+  });
+});

packages/element/tests/typeChecks.test.ts

@@ -0,0 +1,115 @@
+import { API } from "@excalidraw/excalidraw/tests/helpers/api";
+
+import { newElementWith } from "../src/mutateElement";
+import {
+  hasBoundTextElement,
+  isLinearElement,
+  isTextElement,
+} from "../src/typeChecks";
+
+import type {
+  ExcalidrawElement,
+  ExcalidrawLinearElement,
+  ExcalidrawTextElement,
+  NonDeleted,
+  NonDeletedExcalidrawElement,
+} from "../src/types";
+
+describe("Test TypeChecks", () => {
+  describe("Test hasBoundTextElement", () => {
+    it("should return true for text bindable containers with bound text", () => {
+      expect(
+        hasBoundTextElement(
+          API.createElement({
+            type: "rectangle",
+            boundElements: [{ type: "text", id: "text-id" }],
+          }),
+        ),
+      ).toBeTruthy();
+
+      expect(
+        hasBoundTextElement(
+          API.createElement({
+            type: "ellipse",
+            boundElements: [{ type: "text", id: "text-id" }],
+          }),
+        ),
+      ).toBeTruthy();
+
+      expect(
+        hasBoundTextElement(
+          API.createElement({
+            type: "arrow",
+            boundElements: [{ type: "text", id: "text-id" }],
+          }),
+        ),
+      ).toBeTruthy();
+    });
+
+    it("should return false for text bindable containers without bound text", () => {
+      expect(
+        hasBoundTextElement(
+          API.createElement({
+            type: "freedraw",
+            boundElements: [{ type: "arrow", id: "arrow-id" }],
+          }),
+        ),
+      ).toBeFalsy();
+    });
+
+    it("should return false for non text bindable containers", () => {
+      expect(
+        hasBoundTextElement(
+          API.createElement({
+            type: "freedraw",
+            boundElements: [{ type: "text", id: "text-id" }],
+          }),
+        ),
+      ).toBeFalsy();
+    });
+
+    expect(
+      hasBoundTextElement(
+        API.createElement({
+          type: "image",
+          boundElements: [{ type: "text", id: "text-id" }],
+        }),
+      ),
+    ).toBeFalsy();
+  });
+});
+
+describe("Test NonDeleted type", () => {
+  it("should only allow `isDeleted: false` elements", () => {
+    const element = API.createElement({ type: "rectangle" });
+    const deletedElement = newElementWith(element as ExcalidrawElement, {
+      isDeleted: true,
+    });
+
+    // @ts-expect-error deleted elements are not assignable to NonDeleted
+    const nonDeleted: NonDeletedExcalidrawElement = deletedElement;
+
+    // runtime narrowing is still required to treat an element as non-deleted
+    // @ts-expect-error generic elements are not assignable to NonDeleted
+    const nonDeletedGeneric: NonDeletedExcalidrawElement =
+      deletedElement as ExcalidrawElement;
+
+    expect(nonDeleted.isDeleted).toBe(true);
+    expect(nonDeletedGeneric.isDeleted).toBe(true);
+  });
+
+  it("should be preserved by type guards", () => {
+    const elements: NonDeletedExcalidrawElement[] = [
+      API.createElement({ type: "text", text: "text" }),
+      API.createElement({ type: "arrow" }),
+    ];
+
+    const textElements: NonDeleted<ExcalidrawTextElement>[] =
+      elements.filter(isTextElement);
+    const linearElements: NonDeleted<ExcalidrawLinearElement>[] =
+      elements.filter(isLinearElement);
+
+    expect(textElements.length).toBe(1);
+    expect(linearElements.length).toBe(1);
+  });
+});