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

packages/common/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["../eslintrc.base.json"]
+}

packages/common/README.md

@@ -0,0 +1,19 @@
+# @excalidraw/common
+
+## Install
+
+```bash
+npm install @excalidraw/common
+```
+
+If you prefer Yarn over npm, use this command to install the Excalidraw utils package:
+
+```bash
+yarn add @excalidraw/common
+```
+
+With PNPM, similarly install the package with this command:
+
+```bash
+pnpm add @excalidraw/common
+```

packages/common/debug.ts

@@ -0,0 +1,220 @@
+const lessPrecise = (num: number, precision = 5) =>
+  parseFloat(num.toPrecision(precision));
+
+const getAvgFrameTime = (times: number[]) =>
+  lessPrecise(times.reduce((a, b) => a + b) / times.length);
+
+export class Debug {
+  public static DEBUG_LOG_TIMES = true;
+
+  private static TIMES_AGGR: Record<string, { t: number; times: number[] }> =
+    {};
+  private static TIMES_AVG: Record<
+    string,
+    { t: number; times: number[]; avg: number | null }
+  > = {};
+  private static LAST_DEBUG_LOG_CALL = 0;
+  private static DEBUG_LOG_INTERVAL_ID: null | number = null;
+
+  private static LAST_FRAME_TIMESTAMP = 0;
+  private static FRAME_COUNT = 0;
+  private static ANIMATION_FRAME_ID: null | number = null;
+
+  private static scheduleAnimationFrame = () => {
+    if (Debug.DEBUG_LOG_INTERVAL_ID !== null) {
+      Debug.ANIMATION_FRAME_ID = requestAnimationFrame((timestamp) => {
+        if (Debug.LAST_FRAME_TIMESTAMP !== timestamp) {
+          Debug.LAST_FRAME_TIMESTAMP = timestamp;
+          Debug.FRAME_COUNT++;
+        }
+
+        if (Debug.DEBUG_LOG_INTERVAL_ID !== null) {
+          Debug.scheduleAnimationFrame();
+        }
+      });
+    }
+  };
+
+  private static setupInterval = () => {
+    if (Debug.DEBUG_LOG_INTERVAL_ID === null) {
+      console.info("%c(starting perf recording)", "color: lime");
+      Debug.DEBUG_LOG_INTERVAL_ID = window.setInterval(Debug.debugLogger, 1000);
+      Debug.scheduleAnimationFrame();
+    }
+    Debug.LAST_DEBUG_LOG_CALL = Date.now();
+  };
+
+  private static debugLogger = () => {
+    if (Debug.DEBUG_LOG_TIMES) {
+      for (const [name, { t, times }] of Object.entries(Debug.TIMES_AGGR)) {
+        if (times.length) {
+          console.info(
+            name,
+            lessPrecise(times.reduce((a, b) => a + b)),
+            times.sort((a, b) => a - b).map((x) => lessPrecise(x)),
+          );
+          Debug.TIMES_AGGR[name] = { t, times: [] };
+        }
+      }
+      for (const [name, { t, times, avg }] of Object.entries(Debug.TIMES_AVG)) {
+        if (times.length) {
+          // const avgFrameTime = getAvgFrameTime(times);
+          const totalTime = times.reduce((a, b) => a + b);
+          const avgFrameTime = lessPrecise(totalTime / Debug.FRAME_COUNT);
+          console.info(
+            name,
+            `- ${times.length} calls - ${avgFrameTime}ms/frame across ${
+              Debug.FRAME_COUNT
+            } frames (${lessPrecise(
+              (avgFrameTime / 16.67) * 100,
+              1,
+            )}% of frame budget)`,
+          );
+          Debug.TIMES_AVG[name] = {
+            t,
+            times: [],
+            avg:
+              avg != null ? getAvgFrameTime([avg, avgFrameTime]) : avgFrameTime,
+          };
+        }
+      }
+    }
+    Debug.FRAME_COUNT = 0;
+
+    // Check for stop condition after logging
+    if (
+      Date.now() - Debug.LAST_DEBUG_LOG_CALL > 600 &&
+      Debug.DEBUG_LOG_INTERVAL_ID !== null
+    ) {
+      console.info("%c(stopping perf recording)", "color: red");
+      window.clearInterval(Debug.DEBUG_LOG_INTERVAL_ID);
+      window.cancelAnimationFrame(Debug.ANIMATION_FRAME_ID!);
+      Debug.ANIMATION_FRAME_ID = null;
+      Debug.FRAME_COUNT = 0;
+      Debug.LAST_FRAME_TIMESTAMP = 0;
+
+      Debug.DEBUG_LOG_INTERVAL_ID = null;
+      Debug.TIMES_AGGR = {};
+      Debug.TIMES_AVG = {};
+    }
+  };
+
+  public static logTime = (time?: number, name = "default") => {
+    Debug.setupInterval();
+    const now = performance.now();
+    const { t, times } = (Debug.TIMES_AGGR[name] = Debug.TIMES_AGGR[name] || {
+      t: 0,
+      times: [],
+    });
+    if (t) {
+      times.push(time != null ? time : now - t);
+    }
+    Debug.TIMES_AGGR[name].t = now;
+  };
+  public static logTimeAverage = (time?: number, name = "default") => {
+    Debug.setupInterval();
+    const now = performance.now();
+    const { t, times } = (Debug.TIMES_AVG[name] = Debug.TIMES_AVG[name] || {
+      t: 0,
+      times: [],
+    });
+    if (t) {
+      times.push(time != null ? time : now - t);
+    }
+    Debug.TIMES_AVG[name].t = now;
+  };
+
+  private static logWrapper =
+    (type: "logTime" | "logTimeAverage") =>
+    <T extends any[], R>(fn: (...args: T) => R, name = "default") => {
+      return (...args: T) => {
+        const t0 = performance.now();
+        const ret = fn(...args);
+        Debug[type](performance.now() - t0, name);
+        return ret;
+      };
+    };
+
+  public static logTimeWrap = Debug.logWrapper("logTime");
+  public static logTimeAverageWrap = Debug.logWrapper("logTimeAverage");
+
+  public static perfWrap = <T extends any[], R>(
+    fn: (...args: T) => R,
+    name = "default",
+  ) => {
+    return (...args: T) => {
+      // eslint-disable-next-line no-console
+      console.time(name);
+      const ret = fn(...args);
+      // eslint-disable-next-line no-console
+      console.timeEnd(name);
+      return ret;
+    };
+  };
+
+  private static CHANGED_CACHE: Record<string, Record<string, unknown>> = {};
+
+  public static logChanged(name: string, obj: Record<string, unknown>) {
+    const prev = Debug.CHANGED_CACHE[name];
+
+    Debug.CHANGED_CACHE[name] = obj;
+
+    if (!prev) {
+      return;
+    }
+
+    const allKeys = new Set([...Object.keys(prev), ...Object.keys(obj)]);
+    const changed: Record<string, { prev: unknown; next: unknown }> = {};
+
+    for (const key of allKeys) {
+      const prevVal = prev[key];
+      const nextVal = obj[key];
+      if (!deepEqual(prevVal, nextVal)) {
+        changed[key] = { prev: prevVal, next: nextVal };
+      }
+    }
+
+    if (Object.keys(changed).length > 0) {
+      console.info(`[${name}] changed:`, changed);
+    }
+  }
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) {
+    return true;
+  }
+
+  if (
+    a === null ||
+    b === null ||
+    typeof a !== "object" ||
+    typeof b !== "object"
+  ) {
+    return false;
+  }
+
+  if (Array.isArray(a) !== Array.isArray(b)) {
+    return false;
+  }
+
+  const keysA = Object.keys(a as Record<string, unknown>);
+  const keysB = Object.keys(b as Record<string, unknown>);
+
+  if (keysA.length !== keysB.length) {
+    return false;
+  }
+
+  for (const key of keysA) {
+    if (
+      !deepEqual(
+        (a as Record<string, unknown>)[key],
+        (b as Record<string, unknown>)[key],
+      )
+    ) {
+      return false;
+    }
+  }
+
+  return true;
+}

packages/common/global.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="vite/client" />
+import "@excalidraw/excalidraw/global";
+import "@excalidraw/excalidraw/css";

packages/common/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@excalidraw/common",
+  "version": "0.18.0",
+  "type": "module",
+  "types": "./dist/types/common/src/index.d.ts",
+  "main": "./dist/prod/index.js",
+  "module": "./dist/prod/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/types/common/src/index.d.ts",
+      "development": "./dist/dev/index.js",
+      "production": "./dist/prod/index.js",
+      "default": "./dist/prod/index.js"
+    },
+    "./*": {
+      "types": "./dist/types/common/src/*.d.ts",
+      "development": "./dist/dev/index.js",
+      "production": "./dist/prod/index.js",
+      "default": "./dist/prod/index.js"
+    }
+  },
+  "files": [
+    "dist/*"
+  ],
+  "description": "Excalidraw common functions, constants, etc.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "keywords": [
+    "excalidraw",
+    "excalidraw-utils"
+  ],
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not ie <= 11",
+      "not op_mini all",
+      "not safari < 12",
+      "not kaios <= 2.5",
+      "not edge < 79",
+      "not chrome < 70",
+      "not and_uc < 13",
+      "not samsung < 10"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  },
+  "bugs": "https://github.com/excalidraw/excalidraw/issues",
+  "repository": "https://github.com/excalidraw/excalidraw",
+  "scripts": {
+    "gen:types": "rimraf types && tsc",
+    "build:esm": "rimraf dist && node ../../scripts/buildBase.js && yarn gen:types"
+  },
+  "dependencies": {
+    "tinycolor2": "1.6.0"
+  },
+  "devDependencies": {
+    "@types/tinycolor2": "1.4.6"
+  }
+}

packages/common/src/__snapshots__/colors.test.ts.snap

@@ -0,0 +1,185 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`COLOR_PALETTE > color palette doesn't regress 1`] = `
+{
+  "black": "#1e1e1e",
+  "blue": [
+    "#e7f5ff",
+    "#a5d8ff",
+    "#4dabf7",
+    "#228be6",
+    "#1971c2",
+  ],
+  "bronze": [
+    "#f8f1ee",
+    "#eaddd7",
+    "#d2bab0",
+    "#a18072",
+    "#846358",
+  ],
+  "cyan": [
+    "#e3fafc",
+    "#99e9f2",
+    "#3bc9db",
+    "#15aabf",
+    "#0c8599",
+  ],
+  "grape": [
+    "#f8f0fc",
+    "#eebefa",
+    "#da77f2",
+    "#be4bdb",
+    "#9c36b5",
+  ],
+  "gray": [
+    "#f8f9fa",
+    "#e9ecef",
+    "#ced4da",
+    "#868e96",
+    "#343a40",
+  ],
+  "green": [
+    "#ebfbee",
+    "#b2f2bb",
+    "#69db7c",
+    "#40c057",
+    "#2f9e44",
+  ],
+  "orange": [
+    "#fff4e6",
+    "#ffd8a8",
+    "#ffa94d",
+    "#fd7e14",
+    "#e8590c",
+  ],
+  "pink": [
+    "#fff0f6",
+    "#fcc2d7",
+    "#f783ac",
+    "#e64980",
+    "#c2255c",
+  ],
+  "red": [
+    "#fff5f5",
+    "#ffc9c9",
+    "#ff8787",
+    "#fa5252",
+    "#e03131",
+  ],
+  "teal": [
+    "#e6fcf5",
+    "#96f2d7",
+    "#38d9a9",
+    "#12b886",
+    "#099268",
+  ],
+  "transparent": "transparent",
+  "violet": [
+    "#f3f0ff",
+    "#d0bfff",
+    "#9775fa",
+    "#7950f2",
+    "#6741d9",
+  ],
+  "white": "#ffffff",
+  "yellow": [
+    "#fff9db",
+    "#ffec99",
+    "#ffd43b",
+    "#fab005",
+    "#f08c00",
+  ],
+}
+`;
+
+exports[`applyDarkModeFilter > COLOR_PALETTE regression tests > matches snapshot for all palette colors 1`] = `
+{
+  "black": "#d3d3d3",
+  "blue": [
+    "#121e26",
+    "#154162",
+    "#2273b4",
+    "#3791e0",
+    "#56a2e8",
+  ],
+  "bronze": [
+    "#221c1a",
+    "#362b26",
+    "#5a463d",
+    "#917569",
+    "#a98d84",
+  ],
+  "cyan": [
+    "#0a1e20",
+    "#004149",
+    "#007281",
+    "#0f8fa1",
+    "#3da5b6",
+  ],
+  "grape": [
+    "#211a25",
+    "#5b3165",
+    "#a954be",
+    "#d471ed",
+    "#e28af8",
+  ],
+  "gray": [
+    "#161718",
+    "#202325",
+    "#33383d",
+    "#6e757c",
+    "#b7bcc1",
+  ],
+  "green": [
+    "#0f1d12",
+    "#043b0c",
+    "#056715",
+    "#16842a",
+    "#39994b",
+  ],
+  "orange": [
+    "#22190d",
+    "#4c2b01",
+    "#924800",
+    "#cd6005",
+    "#f17634",
+  ],
+  "pink": [
+    "#26191e",
+    "#602e40",
+    "#b04d70",
+    "#f56e9d",
+    "#ff8dbc",
+  ],
+  "red": [
+    "#1f1717",
+    "#5a2c2c",
+    "#b44d4d",
+    "#fa6969",
+    "#ff8383",
+  ],
+  "teal": [
+    "#0a1d17",
+    "#00422b",
+    "#00744b",
+    "#039267",
+    "#32a783",
+  ],
+  "transparent": "#ededed00",
+  "violet": [
+    "#1f1c29",
+    "#4a3b72",
+    "#8a6cdf",
+    "#a885ff",
+    "#b595ff",
+  ],
+  "white": "#121212",
+  "yellow": [
+    "#1e1900",
+    "#362600",
+    "#5f3a00",
+    "#905000",
+    "#b86200",
+  ],
+}
+`;

packages/common/src/appEventBus.test.ts

@@ -0,0 +1,74 @@
+import { AppEventBus } from "./appEventBus";
+
+type TestEvents = {
+  initialize: [api: number];
+  pointerUp: [pointerId: string];
+  viewState: [zoom: number];
+};
+
+const behavior = {
+  initialize: { cardinality: "once", replay: "last" },
+  pointerUp: { cardinality: "many", replay: "none" },
+  viewState: { cardinality: "many", replay: "last" },
+} as const;
+
+const flushMicrotasks = async () => Promise.resolve();
+
+describe("AppEventBus", () => {
+  it("replays once events to late callback and Promise subscribers", async () => {
+    const bus = new AppEventBus<TestEvents, typeof behavior>(behavior);
+    bus.emit("initialize", 42);
+
+    const calls: number[] = [];
+    bus.on("initialize", (value) => {
+      calls.push(value);
+    });
+
+    expect(calls).toEqual([]);
+    await flushMicrotasks();
+    expect(calls).toEqual([42]);
+
+    await expect(bus.on("initialize")).resolves.toBe(42);
+  });
+
+  it("does not replay stream events to late subscribers", async () => {
+    const bus = new AppEventBus<TestEvents, typeof behavior>(behavior);
+    bus.emit("pointerUp", "first");
+
+    const calls: string[] = [];
+    bus.on("pointerUp", (pointerId) => {
+      calls.push(pointerId);
+    });
+
+    await flushMicrotasks();
+    expect(calls).toEqual([]);
+
+    bus.emit("pointerUp", "second");
+    expect(calls).toEqual(["second"]);
+  });
+
+  it("replays replay-last stream events and stays subscribed", async () => {
+    const bus = new AppEventBus<TestEvents, typeof behavior>(behavior);
+    bus.emit("viewState", 1);
+
+    const calls: number[] = [];
+    bus.on("viewState", (zoom) => {
+      calls.push(zoom);
+    });
+
+    await flushMicrotasks();
+    expect(calls).toEqual([1]);
+
+    bus.emit("viewState", 2);
+    expect(calls).toEqual([1, 2]);
+  });
+
+  it("throws when emitting a once event twice", () => {
+    const bus = new AppEventBus<TestEvents, typeof behavior>(behavior);
+    bus.emit("initialize", 1);
+
+    expect(() => {
+      bus.emit("initialize", 2);
+    }).toThrow('Event "initialize" can only be emitted once');
+  });
+});

packages/common/src/appEventBus.ts

@@ -0,0 +1,136 @@
+import type { UnsubscribeCallback } from "@excalidraw/excalidraw/types";
+
+import { Emitter } from "./emitter";
+import { isProdEnv } from "./utils";
+
+export type AppEventPayloadMap = Record<string, unknown[]>;
+
+export type AppEventBehavior = {
+  cardinality: "once" | "many";
+  replay: "none" | "last";
+};
+
+export type AppEventBehaviorMap<Events extends AppEventPayloadMap> = {
+  [K in keyof Events]: AppEventBehavior;
+};
+
+type AwaitableAppEventKeys<
+  Events extends AppEventPayloadMap,
+  Behavior extends AppEventBehaviorMap<Events>,
+> = {
+  [K in keyof Events]: Behavior[K]["cardinality"] extends "once"
+    ? Behavior[K]["replay"] extends "last"
+      ? K
+      : never
+    : never;
+}[keyof Events];
+
+type AppEventPromiseValue<Args extends any[]> = Args extends [infer Only]
+  ? Only
+  : Args;
+
+export class AppEventBus<
+  Events extends AppEventPayloadMap,
+  Behavior extends AppEventBehaviorMap<Events>,
+> {
+  private readonly emitters = new Map<keyof Events, Emitter<any>>();
+  private readonly lastPayload = new Map<keyof Events, any[]>();
+  private readonly emittedOnce = new Set<keyof Events>();
+
+  constructor(private readonly behavior: Behavior) {}
+
+  private getEmitter<K extends keyof Events>(name: K): Emitter<Events[K]> {
+    let emitter = this.emitters.get(name);
+    if (!emitter) {
+      emitter = new Emitter<any>();
+      this.emitters.set(name, emitter);
+    }
+    return emitter as Emitter<Events[K]>;
+  }
+
+  private toPromiseValue<Args extends any[]>(
+    args: Args,
+  ): AppEventPromiseValue<Args> {
+    return (args.length === 1 ? args[0] : args) as AppEventPromiseValue<Args>;
+  }
+
+  public on<K extends keyof Events>(
+    name: K,
+    callback: (...args: Events[K]) => void,
+  ): UnsubscribeCallback;
+  public on<K extends AwaitableAppEventKeys<Events, Behavior>>(
+    name: K,
+  ): Promise<AppEventPromiseValue<Events[K]>>;
+  public on<K extends keyof Events>(
+    name: K,
+    callback?: (...args: Events[K]) => void,
+  ): UnsubscribeCallback | Promise<AppEventPromiseValue<Events[K]>> {
+    const eventBehavior = this.behavior[name];
+    const cachedPayload = this.lastPayload.get(name) as Events[K] | undefined;
+
+    if (callback) {
+      if (eventBehavior.replay === "last" && cachedPayload) {
+        queueMicrotask(() => callback(...cachedPayload));
+
+        if (eventBehavior.cardinality === "once") {
+          return () => {};
+        }
+      }
+
+      return this.getEmitter(name).on(callback);
+    }
+
+    if (
+      eventBehavior.cardinality !== "once" ||
+      eventBehavior.replay !== "last"
+    ) {
+      throw new Error(`Event "${String(name)}" requires a callback`);
+    }
+
+    if (cachedPayload) {
+      return Promise.resolve(this.toPromiseValue(cachedPayload));
+    }
+
+    return new Promise<AppEventPromiseValue<Events[K]>>((resolve) => {
+      this.getEmitter(name).once((...args: Events[K]) => {
+        resolve(this.toPromiseValue(args));
+      });
+    });
+  }
+
+  public emit<K extends keyof Events>(name: K, ...args: Events[K]) {
+    const eventBehavior = this.behavior[name];
+
+    if (!isProdEnv()) {
+      if (eventBehavior.cardinality === "once") {
+        if (this.emittedOnce.has(name)) {
+          throw new Error(`Event "${String(name)}" can only be emitted once`);
+        }
+        this.emittedOnce.add(name);
+      }
+    }
+
+    if (eventBehavior.replay === "last") {
+      this.lastPayload.set(name, args);
+    }
+
+    try {
+      this.getEmitter(name).trigger(...args);
+    } finally {
+      if (eventBehavior.cardinality === "once") {
+        this.getEmitter(name).clear();
+      }
+    }
+  }
+
+  public clear() {
+    this.lastPayload.clear();
+    this.emittedOnce.clear();
+
+    for (const emitter of this.emitters.values()) {
+      emitter.clear();
+    }
+
+    this.emitters.clear();
+  }
+}

packages/common/src/binary-heap.ts

@@ -0,0 +1,110 @@
+export class BinaryHeap<T> {
+  private content: T[] = [];
+
+  constructor(private scoreFunction: (node: T) => number) {}
+
+  sinkDown(idx: number) {
+    const node = this.content[idx];
+    const nodeScore = this.scoreFunction(node);
+    while (idx > 0) {
+      const parentN = ((idx + 1) >> 1) - 1;
+      const parent = this.content[parentN];
+      if (nodeScore < this.scoreFunction(parent)) {
+        this.content[idx] = parent;
+        idx = parentN; // TODO: Optimize
+      } else {
+        break;
+      }
+    }
+    this.content[idx] = node;
+  }
+
+  bubbleUp(idx: number) {
+    const length = this.content.length;
+    const node = this.content[idx];
+    const score = this.scoreFunction(node);
+
+    while (true) {
+      const child1N = ((idx + 1) << 1) - 1;
+      const child2N = child1N + 1;
+      let smallestIdx = idx;
+      let smallestScore = score;
+
+      // Check left child
+      if (child1N < length) {
+        const child1Score = this.scoreFunction(this.content[child1N]);
+        if (child1Score < smallestScore) {
+          smallestIdx = child1N;
+          smallestScore = child1Score;
+        }
+      }
+
+      // Check right child
+      if (child2N < length) {
+        const child2Score = this.scoreFunction(this.content[child2N]);
+        if (child2Score < smallestScore) {
+          smallestIdx = child2N;
+        }
+      }
+
+      if (smallestIdx === idx) {
+        break;
+      }
+
+      // Move the smaller child up, continue finding position for node
+      this.content[idx] = this.content[smallestIdx];
+      idx = smallestIdx;
+    }
+
+    // Place node in its final position
+    this.content[idx] = node;
+  }
+
+  push(node: T) {
+    this.content.push(node);
+    this.sinkDown(this.content.length - 1);
+  }
+
+  pop(): T | null {
+    if (this.content.length === 0) {
+      return null;
+    }
+
+    const result = this.content[0];
+    const end = this.content.pop()!;
+
+    if (this.content.length > 0) {
+      this.content[0] = end;
+      this.bubbleUp(0);
+    }
+
+    return result;
+  }
+
+  remove(node: T) {
+    if (this.content.length === 0) {
+      return;
+    }
+
+    const i = this.content.indexOf(node);
+    const end = this.content.pop()!;
+
+    if (i < this.content.length) {
+      this.content[i] = end;
+
+      if (this.scoreFunction(end) < this.scoreFunction(node)) {
+        this.sinkDown(i);
+      } else {
+        this.bubbleUp(i);
+      }
+    }
+  }
+
+  size(): number {
+    return this.content.length;
+  }
+
+  rescoreElement(node: T) {
+    this.sinkDown(this.content.indexOf(node));
+  }
+}

packages/common/src/bounds.ts

@@ -0,0 +1,17 @@
+/**
+ * x and y position of top left corner, x and y position of bottom right corner
+ */
+export type Bounds = readonly [
+  minX: number,
+  minY: number,
+  maxX: number,
+  maxY: number,
+];
+
+export const isBounds = (box: unknown): box is Bounds =>
+  Array.isArray(box) &&
+  box.length === 4 &&
+  typeof box[0] === "number" &&
+  typeof box[1] === "number" &&
+  typeof box[2] === "number" &&
+  typeof box[3] === "number";

packages/common/src/colors.test.ts

@@ -0,0 +1,305 @@
+import {
+  applyDarkModeFilter,
+  COLOR_PALETTE,
+  removeDarkModeFilter,
+  rgbToHex,
+} from "@excalidraw/common";
+
+describe("COLOR_PALETTE", () => {
+  it("color palette doesn't regress", () => {
+    expect(COLOR_PALETTE).toMatchSnapshot();
+  });
+});
+
+describe("applyDarkModeFilter", () => {
+  describe("basic transformations", () => {
+    it("transforms black to near-white", () => {
+      const result = applyDarkModeFilter("#000000");
+      // Black inverted 93% + hue rotate should be near white/light gray
+      expect(result).toBe("#ededed");
+    });
+
+    it("transforms white to near-black", () => {
+      const result = applyDarkModeFilter("#ffffff");
+      // White inverted 93% should be near black/dark gray
+      expect(result).toBe("#121212");
+    });
+
+    it("transforms pure red", () => {
+      const result = applyDarkModeFilter("#ff0000");
+      // Invert 93% + hue rotate 180deg produces a cyan-ish tint
+      expect(result).toBe("#ff9090");
+    });
+
+    it("transforms pure green", () => {
+      const result = applyDarkModeFilter("#00ff00");
+      // Invert 93% + hue rotate 180deg
+      expect(result).toBe("#008f00");
+    });
+
+    it("transforms pure blue", () => {
+      const result = applyDarkModeFilter("#0000ff");
+      // Invert 93% + hue rotate 180deg produces a light purple
+      expect(result).toBe("#cdcdff");
+    });
+  });
+
+  describe("color formats", () => {
+    it("handles hex with hash", () => {
+      const result = applyDarkModeFilter("#ff0000");
+      // Fully opaque colors return 6-char hex
+      expect(result).toMatch(/^#[0-9a-f]{6}$/);
+    });
+
+    it("handles named colors", () => {
+      const result = applyDarkModeFilter("red");
+      // "red" = #ff0000, fully opaque
+      expect(result).toBe("#ff9090");
+    });
+
+    it("handles rgb format", () => {
+      const result = applyDarkModeFilter("rgb(255, 0, 0)");
+      expect(result).toBe("#ff9090");
+    });
+
+    it("handles rgba format and preserves alpha", () => {
+      const result = applyDarkModeFilter("rgba(255, 0, 0, 0.5)");
+      expect(result).toMatch(/^#[0-9a-f]{8}$/);
+      // Alpha 0.5 = 128 in hex = 80
+      expect(result).toBe("#ff909080");
+    });
+
+    it("handles transparent", () => {
+      const result = applyDarkModeFilter("transparent");
+      // transparent = rgba(0,0,0,0), inverted should still have 0 alpha
+      expect(result).toBe("#ededed00");
+    });
+
+    it("handles shorthand hex", () => {
+      const result = applyDarkModeFilter("#f00");
+      expect(result).toBe("#ff9090");
+    });
+  });
+
+  describe("alpha preservation", () => {
+    it("omits alpha for full opacity", () => {
+      const result = applyDarkModeFilter("#ff0000ff");
+      // Full opacity returns 6-char hex (no alpha suffix)
+      expect(result).toBe("#ff9090");
+    });
+
+    it("preserves 50% opacity", () => {
+      const result = applyDarkModeFilter("#ff000080");
+      expect(result.slice(-2)).toBe("80");
+    });
+
+    it("preserves 0% opacity", () => {
+      const result = applyDarkModeFilter("#ff000000");
+      expect(result.slice(-2)).toBe("00");
+    });
+  });
+
+  describe("COLOR_PALETTE regression tests", () => {
+    it("transforms black from palette", () => {
+      // COLOR_PALETTE.black is #1e1e1e (not pure black)
+      const result = applyDarkModeFilter(COLOR_PALETTE.black);
+      expect(result).toBe("#d3d3d3");
+    });
+
+    it("transforms white from palette", () => {
+      const result = applyDarkModeFilter(COLOR_PALETTE.white);
+      expect(result).toBe("#121212");
+    });
+
+    it("transforms transparent from palette", () => {
+      const result = applyDarkModeFilter(COLOR_PALETTE.transparent);
+      expect(result).toBe("#ededed00");
+    });
+
+    // Test each color family from the palette (all opaque, so 6-char hex)
+    describe("red shades", () => {
+      const redShades = COLOR_PALETTE.red;
+      it.each(redShades.map((color, i) => [color, i]))(
+        "transforms red shade %s (index %d)",
+        (color) => {
+          const result = applyDarkModeFilter(color as string);
+          expect(result).toMatch(/^#[0-9a-f]{6}$/);
+        },
+      );
+    });
+
+    describe("blue shades", () => {
+      const blueShades = COLOR_PALETTE.blue;
+      it.each(blueShades.map((color, i) => [color, i]))(
+        "transforms blue shade %s (index %d)",
+        (color) => {
+          const result = applyDarkModeFilter(color as string);
+          expect(result).toMatch(/^#[0-9a-f]{6}$/);
+        },
+      );
+    });
+
+    describe("green shades", () => {
+      const greenShades = COLOR_PALETTE.green;
+      it.each(greenShades.map((color, i) => [color, i]))(
+        "transforms green shade %s (index %d)",
+        (color) => {
+          const result = applyDarkModeFilter(color as string);
+          expect(result).toMatch(/^#[0-9a-f]{6}$/);
+        },
+      );
+    });
+
+    describe("gray shades", () => {
+      const grayShades = COLOR_PALETTE.gray;
+      it.each(grayShades.map((color, i) => [color, i]))(
+        "transforms gray shade %s (index %d)",
+        (color) => {
+          const result = applyDarkModeFilter(color as string);
+          expect(result).toMatch(/^#[0-9a-f]{6}$/);
+        },
+      );
+    });
+
+    describe("bronze shades", () => {
+      const bronzeShades = COLOR_PALETTE.bronze;
+      it.each(bronzeShades.map((color, i) => [color, i]))(
+        "transforms bronze shade %s (index %d)",
+        (color) => {
+          const result = applyDarkModeFilter(color as string);
+          expect(result).toMatch(/^#[0-9a-f]{6}$/);
+        },
+      );
+    });
+
+    // Snapshot test for full palette to catch any regressions
+    it("matches snapshot for all palette colors", () => {
+      const transformedPalette: Record<string, string | string[]> = {};
+
+      transformedPalette.black = applyDarkModeFilter(COLOR_PALETTE.black);
+      transformedPalette.white = applyDarkModeFilter(COLOR_PALETTE.white);
+      transformedPalette.transparent = applyDarkModeFilter(
+        COLOR_PALETTE.transparent,
+      );
+
+      // Transform color arrays
+      for (const colorName of [
+        "gray",
+        "red",
+        "pink",
+        "grape",
+        "violet",
+        "blue",
+        "cyan",
+        "teal",
+        "green",
+        "yellow",
+        "orange",
+        "bronze",
+      ] as const) {
+        const shades = COLOR_PALETTE[colorName];
+        transformedPalette[colorName] = shades.map((shade) =>
+          applyDarkModeFilter(shade),
+        );
+      }
+
+      expect(transformedPalette).toMatchSnapshot();
+    });
+  });
+
+  describe("caching", () => {
+    it("returns same result for same input (cached)", () => {
+      const result1 = applyDarkModeFilter("#ff0000");
+      const result2 = applyDarkModeFilter("#ff0000");
+      expect(result1).toBe(result2);
+    });
+  });
+});
+
+describe("removeDarkModeFilter", () => {
+  it("restores black and white", () => {
+    expect(removeDarkModeFilter("#ededed")).toBe("#000000");
+    expect(removeDarkModeFilter("#121212")).toBe("#ffffff");
+  });
+
+  it.each([
+    COLOR_PALETTE.black,
+    COLOR_PALETTE.white,
+    COLOR_PALETTE.red[4],
+    COLOR_PALETTE.green[4],
+    COLOR_PALETTE.blue[4],
+  ])("preserves the rendered dark-mode color for %s", (color) => {
+    const filtered = applyDarkModeFilter(color);
+    expect(applyDarkModeFilter(removeDarkModeFilter(filtered))).toBe(filtered);
+  });
+});
+
+describe("rgbToHex", () => {
+  describe("basic RGB conversion", () => {
+    it("converts black (0,0,0)", () => {
+      expect(rgbToHex(0, 0, 0)).toBe("#000000");
+    });
+
+    it("converts white (255,255,255)", () => {
+      expect(rgbToHex(255, 255, 255)).toBe("#ffffff");
+    });
+
+    it("converts red (255,0,0)", () => {
+      expect(rgbToHex(255, 0, 0)).toBe("#ff0000");
+    });
+
+    it("converts green (0,255,0)", () => {
+      expect(rgbToHex(0, 255, 0)).toBe("#00ff00");
+    });
+
+    it("converts blue (0,0,255)", () => {
+      expect(rgbToHex(0, 0, 255)).toBe("#0000ff");
+    });
+
+    it("converts arbitrary color", () => {
+      expect(rgbToHex(30, 30, 30)).toBe("#1e1e1e");
+    });
+  });
+
+  describe("leading zeros preservation", () => {
+    it("preserves leading zeros for low values", () => {
+      expect(rgbToHex(0, 0, 1)).toBe("#000001");
+      expect(rgbToHex(0, 1, 0)).toBe("#000100");
+      expect(rgbToHex(1, 0, 0)).toBe("#010000");
+    });
+
+    it("preserves zeros for single-digit hex values", () => {
+      expect(rgbToHex(15, 15, 15)).toBe("#0f0f0f");
+    });
+  });
+
+  describe("alpha handling", () => {
+    it("omits alpha when undefined", () => {
+      expect(rgbToHex(255, 0, 0)).toBe("#ff0000");
+      expect(rgbToHex(255, 0, 0, undefined)).toBe("#ff0000");
+    });
+
+    it("omits alpha when fully opaque (1)", () => {
+      expect(rgbToHex(255, 0, 0, 1)).toBe("#ff0000");
+    });
+
+    it("includes alpha for semi-transparent (0.5)", () => {
+      // 0.5 * 255 = 127.5 -> rounds to 128 = 0x80
+      expect(rgbToHex(255, 0, 0, 0.5)).toBe("#ff000080");
+    });
+
+    it("includes alpha for fully transparent (0)", () => {
+      expect(rgbToHex(255, 0, 0, 0)).toBe("#ff000000");
+    });
+
+    it("includes alpha for near-opaque (0.99)", () => {
+      // 0.99 * 255 = 252.45 -> rounds to 252 = 0xfc
+      expect(rgbToHex(255, 0, 0, 0.99)).toBe("#ff0000fc");
+    });
+
+    it("pads alpha with leading zero when needed", () => {
+      // 0.05 * 255 = 12.75 -> rounds to 13 = 0x0d
+      expect(rgbToHex(255, 0, 0, 0.05)).toBe("#ff00000d");
+    });
+  });
+});

packages/common/src/colors.ts

@@ -0,0 +1,461 @@
+import tinycolor from "tinycolor2";
+
+import { clamp } from "@excalidraw/math";
+import { degreesToRadians } from "@excalidraw/math";
+
+import type { Degrees } from "@excalidraw/math";
+
+// ---------------------------------------------------------------------------
+// Dark mode color transformation
+// ---------------------------------------------------------------------------
+
+// Browser-only cache to avoid memory leaks on server
+const DARK_MODE_COLORS_CACHE: Map<string, string> | null =
+  typeof window !== "undefined" ? new Map() : null;
+
+const DARK_MODE_FILTER_INVERT_PERCENT = 93;
+const DARK_MODE_FILTER_HUE_ROTATE_DEGREES = 180 as Degrees;
+
+function cssHueRotate(
+  red: number,
+  green: number,
+  blue: number,
+  degrees: Degrees,
+): { r: number; g: number; b: number } {
+  // normalize
+  const r = red / 255;
+  const g = green / 255;
+  const b = blue / 255;
+
+  // Convert degrees to radians
+  const a = degreesToRadians(degrees);
+
+  const c = Math.cos(a);
+  const s = Math.sin(a);
+
+  // rotation matrix
+  const matrix = [
+    0.213 + c * 0.787 - s * 0.213,
+    0.715 - c * 0.715 - s * 0.715,
+    0.072 - c * 0.072 + s * 0.928,
+    0.213 - c * 0.213 + s * 0.143,
+    0.715 + c * 0.285 + s * 0.14,
+    0.072 - c * 0.072 - s * 0.283,
+    0.213 - c * 0.213 - s * 0.787,
+    0.715 - c * 0.715 + s * 0.715,
+    0.072 + c * 0.928 + s * 0.072,
+  ];
+
+  // transform
+  const newR = r * matrix[0] + g * matrix[1] + b * matrix[2];
+  const newG = r * matrix[3] + g * matrix[4] + b * matrix[5];
+  const newB = r * matrix[6] + g * matrix[7] + b * matrix[8];
+
+  // clamp the values to [0, 1] range and convert back to [0, 255]
+  return {
+    r: Math.round(Math.max(0, Math.min(1, newR)) * 255),
+    g: Math.round(Math.max(0, Math.min(1, newG)) * 255),
+    b: Math.round(Math.max(0, Math.min(1, newB)) * 255),
+  };
+}
+
+const cssInvert = (
+  r: number,
+  g: number,
+  b: number,
+  percent: number,
+): { r: number; g: number; b: number } => {
+  const p = clamp(percent, 0, 100) / 100;
+
+  // Function to invert a single color component
+  const invertComponent = (color: number): number => {
+    // Apply the invert formula
+    const inverted = color * (1 - p) + (255 - color) * p;
+    // Round to the nearest integer and clamp to [0, 255]
+    return Math.round(clamp(inverted, 0, 255));
+  };
+
+  // Calculate the inverted RGB components
+  const invertedR = invertComponent(r);
+  const invertedG = invertComponent(g);
+  const invertedB = invertComponent(b);
+
+  return { r: invertedR, g: invertedG, b: invertedB };
+};
+
+export const applyDarkModeFilter = (color: string, enable = true): string => {
+  if (!enable) {
+    return color;
+  }
+
+  const cached = DARK_MODE_COLORS_CACHE?.get(color);
+  if (cached) {
+    return cached;
+  }
+
+  const tc = tinycolor(color);
+  const alpha = tc.getAlpha();
+
+  // order of operations matters
+  // (corresponds to "filter: invert(invertPercent) hue-rotate(hueDegrees)" in css)
+  const rgb = tc.toRgb();
+  const inverted = cssInvert(
+    rgb.r,
+    rgb.g,
+    rgb.b,
+    DARK_MODE_FILTER_INVERT_PERCENT,
+  );
+  const rotated = cssHueRotate(
+    inverted.r,
+    inverted.g,
+    inverted.b,
+    DARK_MODE_FILTER_HUE_ROTATE_DEGREES,
+  );
+
+  const result = rgbToHex(rotated.r, rotated.g, rotated.b, alpha);
+
+  if (DARK_MODE_COLORS_CACHE) {
+    DARK_MODE_COLORS_CACHE.set(color, result);
+  }
+
+  return result;
+};
+
+const _reverseDarkModeInvert = (
+  r: number,
+  g: number,
+  b: number,
+): { r: number; g: number; b: number } => {
+  const p = DARK_MODE_FILTER_INVERT_PERCENT / 100;
+  const denominator = 1 - 2 * p;
+  const restore = (color: number) =>
+    Math.round(clamp((color - 255 * p) / denominator, 0, 255));
+
+  return {
+    r: restore(r),
+    g: restore(g),
+    b: restore(b),
+  };
+};
+
+export const removeDarkModeFilter = (color: string): string => {
+  const tc = tinycolor(color);
+  const alpha = tc.getAlpha();
+  const rgb = tc.toRgb();
+
+  // 180deg hue rotation is its own inverse, so undo it before the inversion.
+  const rotatedBack = cssHueRotate(
+    rgb.r,
+    rgb.g,
+    rgb.b,
+    DARK_MODE_FILTER_HUE_ROTATE_DEGREES,
+  );
+  const restored = _reverseDarkModeInvert(
+    rotatedBack.r,
+    rotatedBack.g,
+    rotatedBack.b,
+  );
+
+  return rgbToHex(restored.r, restored.g, restored.b, alpha);
+};
+
+// ---------------------------------------------------------------------------
+// Color palette
+// ---------------------------------------------------------------------------
+
+// FIXME can't put to utils.ts rn because of circular dependency
+const pick = <R extends Record<string, any>, K extends readonly (keyof R)[]>(
+  source: R,
+  keys: K,
+) => {
+  return keys.reduce((acc, key: K[number]) => {
+    if (key in source) {
+      acc[key] = source[key];
+    }
+    return acc;
+  }, {} as Pick<R, K[number]>) as Pick<R, K[number]>;
+};
+
+export type ColorTuple = readonly [string, string, string, string, string];
+
+// used general type instead of specific type (ColorPalette) to support custom colors
+export type ColorPaletteCustom = { [key: string]: ColorTuple | string };
+export type ColorShadesIndexes = [number, number, number, number, number];
+
+export const MAX_CUSTOM_COLORS_USED_IN_CANVAS = 5;
+export const COLORS_PER_ROW = 5;
+
+export const DEFAULT_CHART_COLOR_INDEX = 4;
+
+export const DEFAULT_ELEMENT_STROKE_COLOR_INDEX = 4;
+export const DEFAULT_ELEMENT_BACKGROUND_COLOR_INDEX = 1;
+
+export const COLOR_PALETTE = {
+  transparent: "transparent",
+  black: "#1e1e1e",
+  white: "#ffffff",
+  // open-color from https://github.com/yeun/open-color/blob/master/open-color.js
+  // corresponds to indexes [0,2,4,6,8] (weights: 50, 200, 400, 600, 800)
+  gray: ["#f8f9fa", "#e9ecef", "#ced4da", "#868e96", "#343a40"],
+  red: ["#fff5f5", "#ffc9c9", "#ff8787", "#fa5252", "#e03131"],
+  pink: ["#fff0f6", "#fcc2d7", "#f783ac", "#e64980", "#c2255c"],
+  grape: ["#f8f0fc", "#eebefa", "#da77f2", "#be4bdb", "#9c36b5"],
+  violet: ["#f3f0ff", "#d0bfff", "#9775fa", "#7950f2", "#6741d9"],
+  blue: ["#e7f5ff", "#a5d8ff", "#4dabf7", "#228be6", "#1971c2"],
+  cyan: ["#e3fafc", "#99e9f2", "#3bc9db", "#15aabf", "#0c8599"],
+  teal: ["#e6fcf5", "#96f2d7", "#38d9a9", "#12b886", "#099268"],
+  green: ["#ebfbee", "#b2f2bb", "#69db7c", "#40c057", "#2f9e44"],
+  yellow: ["#fff9db", "#ffec99", "#ffd43b", "#fab005", "#f08c00"],
+  orange: ["#fff4e6", "#ffd8a8", "#ffa94d", "#fd7e14", "#e8590c"],
+  // radix bronze shades [3,5,7,9,11]
+  bronze: ["#f8f1ee", "#eaddd7", "#d2bab0", "#a18072", "#846358"],
+} as const;
+
+export type ColorPalette = typeof COLOR_PALETTE;
+export type ColorPickerColor = keyof typeof COLOR_PALETTE;
+
+const COMMON_ELEMENT_SHADES = pick(COLOR_PALETTE, [
+  "cyan",
+  "blue",
+  "violet",
+  "grape",
+  "pink",
+  "green",
+  "teal",
+  "yellow",
+  "orange",
+  "red",
+]);
+
+// quick picks defaults
+// -----------------------------------------------------------------------------
+
+/** number of slots in the color-picker top-picks strip — the strip layout is
+ * sized for exactly this many swatches, and pick customization (replace /
+ * reorder) preserves it */
+export const COLOR_TOP_PICKS_SLOTS = 5;
+
+// ORDER matters for positioning in quick picker
+export const DEFAULT_ELEMENT_STROKE_PICKS = [
+  COLOR_PALETTE.black,
+  COLOR_PALETTE.red[DEFAULT_ELEMENT_STROKE_COLOR_INDEX],
+  COLOR_PALETTE.green[DEFAULT_ELEMENT_STROKE_COLOR_INDEX],
+  COLOR_PALETTE.blue[DEFAULT_ELEMENT_STROKE_COLOR_INDEX],
+  COLOR_PALETTE.yellow[DEFAULT_ELEMENT_STROKE_COLOR_INDEX],
+] as ColorTuple;
+
+// ORDER matters for positioning in quick picker
+export const DEFAULT_ELEMENT_BACKGROUND_PICKS = [
+  COLOR_PALETTE.transparent,
+  COLOR_PALETTE.red[DEFAULT_ELEMENT_BACKGROUND_COLOR_INDEX],
+  COLOR_PALETTE.green[DEFAULT_ELEMENT_BACKGROUND_COLOR_INDEX],
+  COLOR_PALETTE.blue[DEFAULT_ELEMENT_BACKGROUND_COLOR_INDEX],
+  COLOR_PALETTE.yellow[DEFAULT_ELEMENT_BACKGROUND_COLOR_INDEX],
+] as ColorTuple;
+
+// ORDER matters for positioning in quick picker.
+// Same as element background picks, with `transparent` (a no-op fill for the
+// bucket tool) swapped for white.
+export const BUCKET_FILL_BACKGROUND_PICKS = [
+  COLOR_PALETTE.white,
+  COLOR_PALETTE.red[DEFAULT_ELEMENT_BACKGROUND_COLOR_INDEX],
+  COLOR_PALETTE.green[DEFAULT_ELEMENT_BACKGROUND_COLOR_INDEX],
+  COLOR_PALETTE.blue[DEFAULT_ELEMENT_BACKGROUND_COLOR_INDEX],
+  COLOR_PALETTE.yellow[DEFAULT_ELEMENT_BACKGROUND_COLOR_INDEX],
+] as ColorTuple;
+
+// sticky notes are their own color domain (own defaults, own picks)
+export const DEFAULT_STICKY_NOTE_BG = "#ffdf6b";
+
+export const STICKY_NOTE_STROKE_PICKS: ColorTuple =
+  DEFAULT_ELEMENT_STROKE_PICKS;
+
+// ORDER matters for positioning in quick picker. Classic note colors; the
+// first one is `DEFAULT_STICKY_NOTE_BG`. Never transparent.
+export const STICKY_NOTE_BACKGROUND_PICKS = [
+  DEFAULT_STICKY_NOTE_BG,
+  COLOR_PALETTE.pink[1],
+  COLOR_PALETTE.green[1],
+  COLOR_PALETTE.blue[1],
+  COLOR_PALETTE.orange[1],
+] as ColorTuple;
+
+// ORDER matters for positioning in quick picker
+export const DEFAULT_CANVAS_BACKGROUND_PICKS = [
+  COLOR_PALETTE.white,
+  // radix slate2
+  "#f8f9fa",
+  // radix blue2
+  "#f5faff",
+  // radix yellow2
+  "#fffce8",
+  // radix bronze2
+  "#fdf8f6",
+] as ColorTuple;
+
+// palette defaults
+// -----------------------------------------------------------------------------
+
+export const DEFAULT_ELEMENT_STROKE_COLOR_PALETTE = {
+  // 1st row
+  transparent: COLOR_PALETTE.transparent,
+  white: COLOR_PALETTE.white,
+  gray: COLOR_PALETTE.gray,
+  black: COLOR_PALETTE.black,
+  bronze: COLOR_PALETTE.bronze,
+  // rest
+  ...COMMON_ELEMENT_SHADES,
+} as const;
+
+// ORDER matters for positioning in pallete (5x3 grid)s
+export const DEFAULT_ELEMENT_BACKGROUND_COLOR_PALETTE = {
+  transparent: COLOR_PALETTE.transparent,
+  white: COLOR_PALETTE.white,
+  gray: COLOR_PALETTE.gray,
+  black: COLOR_PALETTE.black,
+  bronze: COLOR_PALETTE.bronze,
+
+  ...COMMON_ELEMENT_SHADES,
+} as const;
+
+// color palette helpers
+// -----------------------------------------------------------------------------
+
+// !!!MUST BE WITHOUT GRAY, TRANSPARENT AND BLACK!!!
+export const getAllColorsSpecificShade = (index: 0 | 1 | 2 | 3 | 4) => [
+  // 2nd row
+  COLOR_PALETTE.cyan[index],
+  COLOR_PALETTE.blue[index],
+  COLOR_PALETTE.violet[index],
+  COLOR_PALETTE.grape[index],
+  COLOR_PALETTE.pink[index],
+
+  // 3rd row
+  COLOR_PALETTE.green[index],
+  COLOR_PALETTE.teal[index],
+  COLOR_PALETTE.yellow[index],
+  COLOR_PALETTE.orange[index],
+  COLOR_PALETTE.red[index],
+];
+
+// -----------------------------------------------------------------------------
+// other helpers
+// -----------------------------------------------------------------------------
+
+export const rgbToHex = (r: number, g: number, b: number, a?: number) => {
+  // (1 << 24) adds 0x1000000 to ensure the hex string is always 7 chars,
+  // then slice(1) removes the leading "1" to get exactly 6 hex digits
+  // e.g. rgb(0,0,0) -> 0x1000000 -> "1000000" -> "000000"
+  const hex6 = `#${((1 << 24) + (r << 16) + (g << 8) + b)
+    .toString(16)
+    .slice(1)}`;
+  if (a !== undefined && a < 1) {
+    // convert alpha from 0-1 float to 0-255 int, then to 2-digit hex
+    // e.g. 0.5 -> 128 -> "80"
+    const alphaHex = Math.round(a * 255)
+      .toString(16)
+      .padStart(2, "0");
+    return `${hex6}${alphaHex}`;
+  }
+  return hex6;
+};
+
+/**
+ * @returns the color with its alpha replaced by `alpha` (as #RRGGBBAA), or the
+ *  input unchanged if it's not a valid color
+ */
+export const setColorAlpha = (color: string, alpha: number): string => {
+  const tc = tinycolor(color);
+  if (!tc.isValid()) {
+    return color;
+  }
+  const { r, g, b } = tc.toRgb();
+  return rgbToHex(r, g, b, alpha);
+};
+
+/**
+ * @returns #RRGGBB or #RRGGBBAA based on color containing non-opaque alpha,
+ *  null if not valid color
+ */
+export const colorToHex = (color: string): string | null => {
+  const tc = tinycolor(color);
+  if (!tc.isValid()) {
+    return null;
+  }
+  const { r, g, b, a } = tc.toRgb();
+  return rgbToHex(r, g, b, a);
+};
+
+export const isTransparent = (color: string) => {
+  return tinycolor(color).getAlpha() === 0;
+};
+
+/**
+ * Whether the color is fully opaque (alpha exactly 1).
+ *
+ * NOT the negation of `isTransparent`, which is true only at alpha 0 — a
+ * partial-alpha color (`#RRGGBBAA`, `rgba(…, 0.5)`) is neither transparent
+ * (it renders) nor opaque (what's beneath shows through it).
+ */
+export const isOpaqueColor = (color: string) => {
+  return tinycolor(color).getAlpha() === 1;
+};
+
+// -----------------------------------------------------------------------------
+// color contract helpers
+// -----------------------------------------------------------------------------
+
+export const COLOR_OUTLINE_CONTRAST_THRESHOLD = 240;
+
+const calculateContrast = (r: number, g: number, b: number): number => {
+  const yiq = (r * 299 + g * 587 + b * 114) / 1000;
+  return yiq;
+};
+
+// YIQ algo, inspiration from https://stackoverflow.com/a/11868398
+export const isColorDark = (color: string, threshold = 160): boolean => {
+  // no color ("") -> assume it default to black
+  if (!color) {
+    return true;
+  }
+
+  if (isTransparent(color)) {
+    return false;
+  }
+
+  const tc = tinycolor(color);
+  if (!tc.isValid()) {
+    // invalid color -> assume it defaults to black
+    return true;
+  }
+
+  const { r, g, b } = tc.toRgb();
+  return calculateContrast(r, g, b) < threshold;
+};
+
+// -----------------------------------------------------------------------------
+// normalization
+// -----------------------------------------------------------------------------
+
+/**
+ * tries to keep the input color as-is if it's valid, making minimal adjustments
+ * (trimming whitespace or adding `#` to hex colors)
+ */
+export const normalizeInputColor = (color: string): string | null => {
+  color = color.trim();
+  if (isTransparent(color)) {
+    return color;
+  }
+
+  const tc = tinycolor(color);
+  if (tc.isValid()) {
+    // testing for `#` first fixes a bug on Electron (more specfically, an
+    // Obsidian popout window), where a hex color without `#` is considered valid
+    if (["hex", "hex8"].includes(tc.getFormat()) && !color.startsWith("#")) {
+      return `#${color}`;
+    }
+    return color;
+  }
+
+  return null;
+};

packages/common/src/constants.ts

@@ -0,0 +1,606 @@
+import type {
+  ExcalidrawElement,
+  FontFamilyValues,
+} from "@excalidraw/element/types";
+import type { AppProps, AppState } from "@excalidraw/excalidraw/types";
+
+import { COLOR_PALETTE } from "./colors";
+
+export { DEFAULT_STICKY_NOTE_BG } from "./colors";
+
+export const supportsResizeObserver =
+  typeof window !== "undefined" && "ResizeObserver" in window;
+
+export const APP_NAME = "Excalidraw";
+
+// distance when creating text before it's considered `autoResize: false`
+// we're using higher threshold so that clicks that end up being drags
+// don't unintentionally create text elements that are wrapped to a few chars
+// (happens a lot with fast clicks with the text tool)
+export const TEXT_AUTOWRAP_THRESHOLD = 36; // px
+export const DRAGGING_THRESHOLD = 10; // px
+export const MINIMUM_ARROW_SIZE = 20; // px
+export const LINE_CONFIRM_THRESHOLD = 8; // px
+export const ELEMENT_SHIFT_TRANSLATE_AMOUNT = 5;
+export const ELEMENT_TRANSLATE_AMOUNT = 1;
+export const TEXT_TO_CENTER_SNAP_THRESHOLD = 30;
+export const SHIFT_LOCKING_ANGLE = Math.PI / 12;
+export const DEFAULT_LASER_COLOR = "red";
+export const CURSOR_TYPE = {
+  TEXT: "text",
+  CROSSHAIR: "crosshair",
+  GRABBING: "grabbing",
+  GRAB: "grab",
+  POINTER: "pointer",
+  MOVE: "move",
+  AUTO: "",
+};
+export const POINTER_BUTTON = {
+  MAIN: 0,
+  WHEEL: 1,
+  SECONDARY: 2,
+  TOUCH: -1,
+  ERASER: 5,
+} as const;
+
+export const POINTER_EVENTS = {
+  enabled: "all",
+  disabled: "none",
+  // asserted as any so it can be freely assigned to React Element
+  // "pointerEnvets" CSS prop
+  inheritFromUI: "var(--ui-pointerEvents)" as any,
+} as const;
+
+export enum EVENT {
+  COPY = "copy",
+  PASTE = "paste",
+  CUT = "cut",
+  KEYDOWN = "keydown",
+  KEYUP = "keyup",
+  MOUSE_MOVE = "mousemove",
+  RESIZE = "resize",
+  UNLOAD = "unload",
+  FOCUS = "focus",
+  BLUR = "blur",
+  DRAG_OVER = "dragover",
+  DROP = "drop",
+  GESTURE_END = "gestureend",
+  BEFORE_UNLOAD = "beforeunload",
+  GESTURE_START = "gesturestart",
+  GESTURE_CHANGE = "gesturechange",
+  POINTER_MOVE = "pointermove",
+  POINTER_DOWN = "pointerdown",
+  POINTER_UP = "pointerup",
+  POINTER_CANCEL = "pointercancel",
+  STATE_CHANGE = "statechange",
+  WHEEL = "wheel",
+  TOUCH_START = "touchstart",
+  TOUCH_END = "touchend",
+  HASHCHANGE = "hashchange",
+  VISIBILITY_CHANGE = "visibilitychange",
+  SCROLL = "scroll",
+  // custom events
+  EXCALIDRAW_LINK = "excalidraw-link",
+  MENU_ITEM_SELECT = "menu.itemSelect",
+  MESSAGE = "message",
+  FULLSCREENCHANGE = "fullscreenchange",
+}
+
+export const YOUTUBE_STATES = {
+  UNSTARTED: -1,
+  ENDED: 0,
+  PLAYING: 1,
+  PAUSED: 2,
+  BUFFERING: 3,
+  CUED: 5,
+} as const;
+
+export const ENV = {
+  TEST: "test",
+  DEVELOPMENT: "development",
+  PRODUCTION: "production",
+};
+
+export const CLASSES = {
+  SIDEBAR: "sidebar",
+  SHAPE_ACTIONS_MENU: "App-menu__left",
+  ZOOM_ACTIONS: "zoom-actions",
+  SEARCH_MENU_INPUT_WRAPPER: "layer-ui__search-inputWrapper",
+  CONVERT_ELEMENT_TYPE_POPUP: "ConvertElementTypePopup",
+  SHAPE_ACTIONS_THEME_SCOPE: "shape-actions-theme-scope",
+  FRAME_NAME: "frame-name",
+  DROPDOWN_MENU_EVENT_WRAPPER: "dropdown-menu-event-wrapper",
+};
+
+export const FONT_SIZES = {
+  sm: 16,
+  md: 20,
+  lg: 28,
+  xl: 36,
+} as const;
+
+export const CJK_HAND_DRAWN_FALLBACK_FONT = "Xiaolai";
+export const WINDOWS_EMOJI_FALLBACK_FONT = "Segoe UI Emoji";
+
+/**
+ * // TODO: shouldn't be really `const`, likely neither have integers as values, due to value for the custom fonts, which should likely be some hash.
+ *
+ * Let's think this through and consider:
+ * - https://developer.mozilla.org/en-US/docs/Web/CSS/generic-family
+ * - https://drafts.csswg.org/css-fonts-4/#font-family-prop
+ * - https://learn.microsoft.com/en-us/typography/opentype/spec/ibmfc
+ */
+export const FONT_FAMILY = {
+  Virgil: 1,
+  Helvetica: 2,
+  Cascadia: 3,
+  // leave 4 unused as it was historically used for Assistant (which we don't use anymore) or custom font (Obsidian)
+  Excalifont: 5,
+  Nunito: 6,
+  "Lilita One": 7,
+  "Comic Shanns": 8,
+  "Liberation Sans": 9,
+  Assistant: 10,
+};
+
+// Segoe UI Emoji fails to properly fallback for some glyphs: ∞, ∫, ≠
+// so we need to have generic font fallback before it
+export const SANS_SERIF_GENERIC_FONT = "sans-serif";
+export const MONOSPACE_GENERIC_FONT = "monospace";
+
+export const FONT_FAMILY_GENERIC_FALLBACKS = {
+  [SANS_SERIF_GENERIC_FONT]: 998,
+  [MONOSPACE_GENERIC_FONT]: 999,
+};
+
+export const FONT_FAMILY_FALLBACKS = {
+  [CJK_HAND_DRAWN_FALLBACK_FONT]: 100,
+  ...FONT_FAMILY_GENERIC_FALLBACKS,
+  [WINDOWS_EMOJI_FALLBACK_FONT]: 1000,
+};
+
+export function getGenericFontFamilyFallback(
+  fontFamily: number,
+): keyof typeof FONT_FAMILY_GENERIC_FALLBACKS {
+  switch (fontFamily) {
+    case FONT_FAMILY.Cascadia:
+    case FONT_FAMILY["Comic Shanns"]:
+      return MONOSPACE_GENERIC_FONT;
+
+    default:
+      return SANS_SERIF_GENERIC_FONT;
+  }
+}
+
+export const getFontFamilyFallbacks = (
+  fontFamily: number,
+): Array<keyof typeof FONT_FAMILY_FALLBACKS> => {
+  const genericFallbackFont = getGenericFontFamilyFallback(fontFamily);
+
+  switch (fontFamily) {
+    case FONT_FAMILY.Excalifont:
+      return [
+        CJK_HAND_DRAWN_FALLBACK_FONT,
+        genericFallbackFont,
+        WINDOWS_EMOJI_FALLBACK_FONT,
+      ];
+    default:
+      return [genericFallbackFont, WINDOWS_EMOJI_FALLBACK_FONT];
+  }
+};
+
+export const THEME = {
+  LIGHT: "light",
+  DARK: "dark",
+} as const;
+
+export const DARK_THEME_FILTER = "invert(93%) hue-rotate(180deg)";
+
+export const FRAME_STYLE = {
+  strokeColor: "#bbb" as ExcalidrawElement["strokeColor"],
+  strokeWidth: 2 as ExcalidrawElement["strokeWidth"],
+  strokeStyle: "solid" as ExcalidrawElement["strokeStyle"],
+  fillStyle: "solid" as ExcalidrawElement["fillStyle"],
+  roughness: 0 as ExcalidrawElement["roughness"],
+  roundness: null as ExcalidrawElement["roundness"],
+  backgroundColor: "transparent" as ExcalidrawElement["backgroundColor"],
+  radius: 8,
+  nameOffsetY: 3,
+  nameColorLightTheme: "#999999",
+  nameColorDarkTheme: "#7a7a7a",
+  nameFontSize: 14,
+  nameLineHeight: 1.25,
+};
+
+export const MIN_FONT_SIZE = 1;
+export const DEFAULT_FONT_SIZE = 20;
+export const STICKY_NOTE_MIN_FONT_SIZE = 16;
+export const STICKY_NOTE_MAX_FONT_SIZE = 512;
+export const STICKY_NOTE_FALLBACK_FONT_SIZE = 28;
+export const STICKY_NOTE_FONT_STEP = 2;
+export const STICKY_NOTE_PADDING = 16;
+/**
+ * The creation-date footer: a 20px text row under the label body plus a 12px
+ * gap above it, inside the note's bottom padding. Reserved for every note —
+ * also when `created` is unknown — so geometry never depends on data
+ * availability. The label is chosen by width bucket, never measured, so
+ * painting stays measurement-free (the server has no text measurer):
+ * `minBodyWidthForYear` is the worst case ("30 May 2026") in the system sans
+ * stack at 12px, with margin for wider fallbacks such as DejaVu Sans.
+ */
+/**
+ * The creation-date footer of a sticky note. The label body ends `height`
+ * above the note's bottom padding, and the date's baseline sits
+ * `baselineFromBottom` above the note's bottom edge — so the 12px glyphs
+ * (~9px above the baseline, ~3px below) end up roughly 11px from the edge
+ * with a ~13px gap to the label body above them.
+ */
+export const STICKY_NOTE_FOOTER = {
+  height: 20,
+  fontSize: 12,
+  fontFamily: "Helvetica, Arial, sans-serif",
+  baselineFromBottom: 14,
+  opacity: 1,
+  minBodyWidthForYear: 80,
+} as const;
+/**
+ * outer height → label body height: top + bottom padding + footer. The body
+ * is what the label is fitted into; a middle-aligned label is still centered
+ * in the whole padded note when it fits (see `computeBoundTextPosition`).
+ */
+export const STICKY_NOTE_BODY_INSET_Y =
+  STICKY_NOTE_PADDING * 2 + STICKY_NOTE_FOOTER.height;
+export const DEFAULT_STICKY_NOTE_SIZE = 250;
+// floor for a finalized note's width and base height; the UI floor is font-aware
+// on top of it (see `getStickyNoteMinSize`)
+export const STICKY_NOTE_MIN_SIZE = 75;
+export const STICKY_NOTE_SHADOW_OFFSET = 3;
+export const STICKY_NOTE_SHADOW_OPACITY = 0.16;
+export const STICKY_NOTE_EDGE_SHADOW_WIDTH = 0.5;
+export const STICKY_NOTE_EDGE_SHADOW_OPACITY = 0.08;
+export const DEFAULT_FONT_FAMILY: FontFamilyValues = FONT_FAMILY.Excalifont;
+export const DEFAULT_TEXT_ALIGN = "left";
+export const DEFAULT_VERTICAL_ALIGN = "top";
+export const DEFAULT_VERSION = "{version}";
+export const DEFAULT_TRANSFORM_HANDLE_SPACING = 2;
+
+export const SIDE_RESIZING_THRESHOLD = 2 * DEFAULT_TRANSFORM_HANDLE_SPACING;
+// a small epsilon to make side resizing always take precedence
+// (avoids an increase in renders and changes to tests)
+export const EPSILON = 0.00001;
+export const DEFAULT_COLLISION_THRESHOLD =
+  2 * SIDE_RESIZING_THRESHOLD - EPSILON;
+
+export const COLOR_WHITE = "#ffffff";
+export const COLOR_CHARCOAL_BLACK = "#1e1e1e";
+// keep this in sync with CSS
+export const COLOR_VOICE_CALL = "#a2f1a6";
+
+export const CANVAS_ONLY_ACTIONS = ["selectAll"];
+
+export const DEFAULT_GRID_SIZE = 20;
+export const DEFAULT_GRID_STEP = 5;
+
+export const IMAGE_MIME_TYPES = {
+  svg: "image/svg+xml",
+  png: "image/png",
+  jpg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  bmp: "image/bmp",
+  ico: "image/x-icon",
+  avif: "image/avif",
+  jfif: "image/jfif",
+} as const;
+
+export const STRING_MIME_TYPES = {
+  text: "text/plain",
+  html: "text/html",
+  json: "application/json",
+  // excalidraw data
+  excalidraw: "application/vnd.excalidraw+json",
+  excalidrawClipboard: "application/vnd.excalidraw.clipboard+json",
+  // LEGACY: fully-qualified library JSON data
+  excalidrawlib: "application/vnd.excalidrawlib+json",
+  // list of excalidraw library item ids
+  excalidrawlibIds: "application/vnd.excalidrawlib.ids+json",
+} as const;
+
+export const MIME_TYPES = {
+  ...STRING_MIME_TYPES,
+  // image-encoded excalidraw data
+  "excalidraw.svg": "image/svg+xml",
+  "excalidraw.png": "image/png",
+  // binary
+  binary: "application/octet-stream",
+  // image
+  ...IMAGE_MIME_TYPES,
+} as const;
+
+export const ALLOWED_PASTE_MIME_TYPES = [
+  MIME_TYPES.text,
+  MIME_TYPES.html,
+  ...Object.values(IMAGE_MIME_TYPES),
+] as const;
+
+export const EXPORT_IMAGE_TYPES = {
+  png: "png",
+  svg: "svg",
+  clipboard: "clipboard",
+} as const;
+
+export const EXPORT_DATA_TYPES = {
+  excalidraw: "excalidraw",
+  excalidrawClipboard: "excalidraw/clipboard",
+  excalidrawLibrary: "excalidrawlib",
+  excalidrawClipboardWithAPI: "excalidraw-api/clipboard",
+} as const;
+
+export const getExportSource = () =>
+  window.EXCALIDRAW_EXPORT_SOURCE || window.location.origin;
+
+// time in milliseconds
+export const IMAGE_RENDER_TIMEOUT = 500;
+export const TAP_TWICE_TIMEOUT = 300;
+export const TOUCH_CTX_MENU_TIMEOUT = 500;
+export const TITLE_TIMEOUT = 10000;
+export const VERSION_TIMEOUT = 30000;
+export const SCROLL_TIMEOUT = 100;
+export const ZOOM_STEP = 0.1;
+export const MIN_ZOOM = 0.1;
+export const MAX_ZOOM = 30;
+export const HYPERLINK_TOOLTIP_DELAY = 300;
+
+// Report a user inactive after IDLE_THRESHOLD milliseconds
+export const IDLE_THRESHOLD = 60_000;
+// Report a user active each ACTIVE_THRESHOLD milliseconds
+export const ACTIVE_THRESHOLD = 3_000;
+
+export const URL_QUERY_KEYS = {
+  addLibrary: "addLibrary",
+} as const;
+
+export const URL_HASH_KEYS = {
+  addLibrary: "addLibrary",
+} as const;
+
+export const DEFAULT_UI_OPTIONS: AppProps["UIOptions"] = {
+  canvasActions: {
+    changeViewBackgroundColor: true,
+    clearCanvas: true,
+    export: { saveFileToDisk: true },
+    loadScene: true,
+    saveToActiveFile: true,
+    toggleTheme: null,
+    saveAsImage: true,
+  },
+  tools: {
+    image: true,
+  },
+};
+
+export const MAX_DECIMALS_FOR_SVG_EXPORT = 2;
+
+export const EXPORT_SCALES = [1, 2, 3];
+export const DEFAULT_EXPORT_PADDING = 10; // px
+
+export const DEFAULT_IMAGE_OPTIONS: AppProps["imageOptions"] = {
+  maxWidthOrHeight: 1440,
+  maxFileSizeBytes: 4 * 1024 * 1024,
+};
+
+export const SVG_NS = "http://www.w3.org/2000/svg";
+export const SVG_DOCUMENT_PREAMBLE = `<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+`;
+
+export const ENCRYPTION_KEY_BITS = 128;
+
+export const VERSIONS = {
+  excalidraw: 2,
+  excalidrawLibrary: 2,
+} as const;
+
+export const BOUND_TEXT_PADDING = 5;
+export const ARROW_LABEL_WIDTH_FRACTION = 0.7;
+export const ARROW_LABEL_FONT_SIZE_TO_MIN_WIDTH_RATIO = 11;
+
+export const VERTICAL_ALIGN = {
+  TOP: "top",
+  MIDDLE: "middle",
+  BOTTOM: "bottom",
+};
+
+export const TEXT_ALIGN = {
+  LEFT: "left",
+  CENTER: "center",
+  RIGHT: "right",
+};
+
+export const ELEMENT_READY_TO_ERASE_OPACITY = 20;
+export const ELEMENT_PENDING_DRAW_SHAPE_OPACITY = 70;
+
+// Radius represented as 25% of element's largest side (width/height).
+// Used for LEGACY and PROPORTIONAL_RADIUS algorithms, or when the element is
+// below the cutoff size.
+export const DEFAULT_PROPORTIONAL_RADIUS = 0.25;
+// Fixed radius for the ADAPTIVE_RADIUS algorithm. In pixels.
+export const DEFAULT_ADAPTIVE_RADIUS = 32;
+// roundness type (algorithm)
+export const ROUNDNESS = {
+  // Used for legacy rounding (rectangles), which currently works the same
+  // as PROPORTIONAL_RADIUS, but we need to differentiate for UI purposes and
+  // forwards-compat.
+  LEGACY: 1,
+
+  // Used for linear elements & diamonds
+  PROPORTIONAL_RADIUS: 2,
+
+  // Current default algorithm for rectangles, using fixed pixel radius.
+  // It's working similarly to a regular border-radius, but attemps to make
+  // radius visually similar across differnt element sizes, especially
+  // very large and very small elements.
+  //
+  // NOTE right now we don't allow configuration and use a constant radius
+  // (see DEFAULT_ADAPTIVE_RADIUS constant)
+  ADAPTIVE_RADIUS: 3,
+} as const;
+
+export const ROUGHNESS = {
+  architect: 0,
+  artist: 1,
+  cartoonist: 2,
+} as const;
+
+export type StrokeWidthKey = "thin" | "medium" | "bold";
+
+export const STROKE_WIDTH_KEYS: readonly StrokeWidthKey[] = [
+  "thin",
+  "medium",
+  "bold",
+];
+
+export const STROKE_WIDTH: Readonly<
+  Record<StrokeWidthKey | "extraBold", ExcalidrawElement["strokeWidth"]>
+> = {
+  thin: 1,
+  medium: 2,
+  bold: 4,
+  extraBold: 8, // unused (may be introduced in the future)
+};
+
+// freedraw schema 2.0 uses thinner stroke, but to maintain backwards and
+// forwards compatibility, instead of changing the shape renderer, we scale
+// the stroke width by 1/2 (previous, thin was 1, medium 2 etc.)
+//
+// note that in the UI, STROKE_WIDTH.thin == FREEDRAW_STROKE_WIDTH.thin still
+export const FREEDRAW_STROKE_WIDTH: Readonly<
+  Record<StrokeWidthKey | "extraBold", ExcalidrawElement["strokeWidth"]>
+> = {
+  thin: 0.5,
+  medium: 1,
+  bold: 2,
+  extraBold: 4, // legacy (may be used again in the future)
+};
+
+export const getStrokeWidthByKey = (
+  elementType: ExcalidrawElement["type"],
+  strokeWidthKey: StrokeWidthKey,
+): ExcalidrawElement["strokeWidth"] => {
+  return elementType === "freedraw"
+    ? FREEDRAW_STROKE_WIDTH[strokeWidthKey]
+    : STROKE_WIDTH[strokeWidthKey];
+};
+
+export const DEFAULT_ELEMENT_STROKE_WIDTH_KEY: StrokeWidthKey = "medium";
+
+export const DEFAULT_ELEMENT_PROPS: {
+  strokeColor: ExcalidrawElement["strokeColor"];
+  backgroundColor: ExcalidrawElement["backgroundColor"];
+  fillStyle: ExcalidrawElement["fillStyle"];
+  strokeWidth: ExcalidrawElement["strokeWidth"];
+  strokeStyle: ExcalidrawElement["strokeStyle"];
+  roughness: ExcalidrawElement["roughness"];
+  opacity: ExcalidrawElement["opacity"];
+  locked: ExcalidrawElement["locked"];
+} = {
+  strokeColor: COLOR_PALETTE.black,
+  backgroundColor: COLOR_PALETTE.transparent,
+  fillStyle: "solid",
+  strokeWidth: STROKE_WIDTH[DEFAULT_ELEMENT_STROKE_WIDTH_KEY],
+  strokeStyle: "solid",
+  roughness: ROUGHNESS.artist,
+  opacity: 100,
+  locked: false,
+};
+
+export const LIBRARY_SIDEBAR_TAB = "library";
+export const CANVAS_SEARCH_TAB = "search";
+
+export const DEFAULT_SIDEBAR = {
+  name: "default",
+  defaultTab: LIBRARY_SIDEBAR_TAB,
+} as const;
+
+export const LIBRARY_DISABLED_TYPES = new Set([
+  "iframe",
+  "embeddable",
+  "image",
+] as const);
+
+// use these constants to easily identify reference sites
+export const TOOL_TYPE = {
+  selection: "selection",
+  lasso: "lasso",
+  rectangle: "rectangle",
+  diamond: "diamond",
+  ellipse: "ellipse",
+  arrow: "arrow",
+  line: "line",
+  freedraw: "freedraw",
+  text: "text",
+  image: "image",
+  eraser: "eraser",
+  hand: "hand",
+  frame: "frame",
+  magicframe: "magicframe",
+  stickynote: "stickynote",
+  embeddable: "embeddable",
+  laser: "laser",
+  autoshape: "autoshape",
+  bucketfill: "bucketfill",
+} as const;
+
+export const EDITOR_LS_KEYS = {
+  OAI_API_KEY: "excalidraw-oai-api-key",
+  // legacy naming (non)scheme
+  MERMAID_TO_EXCALIDRAW: "mermaid-to-excalidraw",
+  PUBLISH_LIBRARY: "publish-library-data",
+} as const;
+
+/**
+ * not translated as this is used only in public, stateless API as default value
+ * where filename is optional and we can't retrieve name from app state
+ */
+export const DEFAULT_FILENAME = "Untitled";
+
+export const STATS_PANELS = { generalStats: 1, elementProperties: 2 } as const;
+
+export const MIN_WIDTH_OR_HEIGHT = 1;
+
+export const ARROW_TYPE: { [T in AppState["currentItemArrowType"]]: T } = {
+  sharp: "sharp",
+  round: "round",
+  elbow: "elbow",
+};
+
+export const DEFAULT_REDUCED_GLOBAL_ALPHA = 0.3;
+export const ELEMENT_LINK_KEY = "element";
+
+/** used in tests */
+export const ORIG_ID = Symbol.for("__test__originalId__");
+
+export enum UserIdleState {
+  ACTIVE = "active",
+  AWAY = "away",
+  IDLE = "idle",
+}
+
+/**
+ * distance at which we merge points instead of adding a new merge-point
+ * when converting a line to a polygon (merge currently means overlaping
+ * the start and end points)
+ */
+export const LINE_POLYGON_POINT_MERGE_DISTANCE = 20;
+
+export const DOUBLE_TAP_POSITION_THRESHOLD = 35;
+
+export const BIND_MODE_TIMEOUT = 700; // ms
+
+// glass background for mobile action buttons
+export const MOBILE_ACTION_BUTTON_BG = {
+  background: "var(--mobile-action-button-bg)",
+} as const;
+
+export const DEFAULT_STROKE_STREAMLINE = 0.5;
+export const DEFAULT_STROKE_STREAMLINE_PRECISE = 0.2;

packages/common/src/editorInterface.ts

@@ -0,0 +1,222 @@
+export type StylesPanelMode = "compact" | "full" | "mobile";
+
+export type EditorInterface = Readonly<{
+  formFactor: "phone" | "tablet" | "desktop";
+  desktopUIMode: "compact" | "full";
+  userAgent: Readonly<{
+    isMobileDevice: boolean;
+    platform: "ios" | "android" | "other" | "unknown";
+  }>;
+  isTouchScreen: boolean;
+  canFitSidebar: boolean;
+  isLandscape: boolean;
+}>;
+
+// storage key
+const DESKTOP_UI_MODE_STORAGE_KEY = "excalidraw.desktopUIMode";
+
+// breakpoints
+export const MQ_MAX_MOBILE = 599;
+
+export const MQ_MAX_WIDTH_LANDSCAPE = 1000;
+export const MQ_MAX_HEIGHT_LANDSCAPE = 500;
+
+// tablets
+export const MQ_MIN_TABLET = MQ_MAX_MOBILE + 1; // lower bound (excludes phones)
+export const MQ_MAX_TABLET = 1180; // ipad air
+
+// desktop/laptop (NOTE: not used for form factor detection)
+export const MQ_MIN_WIDTH_DESKTOP = 1440;
+
+// sidebar
+export const MQ_RIGHT_SIDEBAR_MIN_WIDTH = 1229;
+
+// -----------------------------------------------------------------------------
+
+// user agent detections
+export const isDarwin = /Mac|iPod|iPhone|iPad/.test(navigator.platform);
+export const isWindows = /^Win/.test(navigator.platform);
+export const isAndroid = /\b(android)\b/i.test(navigator.userAgent);
+export const isFirefox =
+  typeof window !== "undefined" &&
+  "netscape" in window &&
+  navigator.userAgent.indexOf("rv:") > 1 &&
+  navigator.userAgent.indexOf("Gecko") > 1;
+export const isChrome = navigator.userAgent.indexOf("Chrome") !== -1;
+export const isSafari =
+  !isChrome && navigator.userAgent.indexOf("Safari") !== -1;
+export const isIOS =
+  /iPad|iPhone/i.test(navigator.platform) ||
+  // iPadOS 13+
+  (navigator.userAgent.includes("Mac") && "ontouchend" in document);
+// keeping function so it can be mocked in test
+export const isBrave = () =>
+  (navigator as any).brave?.isBrave?.name === "isBrave";
+
+// export const isMobile =
+//   isIOS ||
+//   /android|webos|ipod|blackberry|iemobile|opera mini/i.test(
+//     navigator.userAgent,
+//   ) ||
+//   /android|ios|ipod|blackberry|windows phone/i.test(navigator.platform);
+
+// utilities
+export const isMobileBreakpoint = (width: number, height: number) => {
+  return (
+    width <= MQ_MAX_MOBILE ||
+    (height < MQ_MAX_HEIGHT_LANDSCAPE && width < MQ_MAX_WIDTH_LANDSCAPE)
+  );
+};
+
+export const isTabletBreakpoint = (
+  editorWidth: number,
+  editorHeight: number,
+) => {
+  const minSide = Math.min(editorWidth, editorHeight);
+  const maxSide = Math.max(editorWidth, editorHeight);
+
+  return minSide >= MQ_MIN_TABLET && maxSide <= MQ_MAX_TABLET;
+};
+
+const isMobileOrTablet = (): boolean => {
+  const ua = navigator.userAgent || "";
+  const platform = navigator.platform || "";
+  const uaData = (navigator as any).userAgentData as
+    | { mobile?: boolean; platform?: string }
+    | undefined;
+
+  // --- 1) chromium: prefer ua client hints -------------------------------
+  if (uaData) {
+    const plat = (uaData.platform || "").toLowerCase();
+    const isDesktopOS =
+      plat === "windows" ||
+      plat === "macos" ||
+      plat === "linux" ||
+      plat === "chrome os";
+    if (uaData.mobile === true) {
+      return true;
+    }
+    if (uaData.mobile === false && plat === "android") {
+      const looksTouchTablet =
+        matchMedia?.("(hover: none)").matches &&
+        matchMedia?.("(pointer: coarse)").matches;
+      return looksTouchTablet;
+    }
+    if (isDesktopOS) {
+      return false;
+    }
+  }
+
+  // --- 2) ios (includes ipad) --------------------------------------------
+  if (isIOS) {
+    return true;
+  }
+
+  // --- 3) android legacy ua fallback -------------------------------------
+  if (isAndroid) {
+    const isAndroidPhone = /Mobile/i.test(ua);
+    const isAndroidTablet = !isAndroidPhone;
+    if (isAndroidPhone || isAndroidTablet) {
+      const looksTouchTablet =
+        matchMedia?.("(hover: none)").matches &&
+        matchMedia?.("(pointer: coarse)").matches;
+      return looksTouchTablet;
+    }
+  }
+
+  // --- 4) last resort desktop exclusion ----------------------------------
+  const looksDesktopPlatform =
+    /Win|Linux|CrOS|Mac/.test(platform) ||
+    /Windows NT|X11|CrOS|Macintosh/.test(ua);
+  if (looksDesktopPlatform) {
+    return false;
+  }
+  return false;
+};
+
+export const getFormFactor = (
+  editorWidth: number,
+  editorHeight: number,
+): EditorInterface["formFactor"] => {
+  if (isMobileBreakpoint(editorWidth, editorHeight)) {
+    return "phone";
+  }
+
+  if (isTabletBreakpoint(editorWidth, editorHeight)) {
+    return "tablet";
+  }
+
+  return "desktop";
+};
+
+export const deriveStylesPanelMode = (
+  editorInterface: EditorInterface,
+): StylesPanelMode => {
+  if (editorInterface.formFactor === "phone") {
+    return "mobile";
+  }
+
+  if (editorInterface.formFactor === "tablet") {
+    return "compact";
+  }
+
+  return editorInterface.desktopUIMode;
+};
+
+export const createUserAgentDescriptor = (
+  userAgentString: string,
+): EditorInterface["userAgent"] => {
+  const normalizedUA = userAgentString ?? "";
+  let platform: EditorInterface["userAgent"]["platform"] = "unknown";
+
+  if (isIOS) {
+    platform = "ios";
+  } else if (isAndroid) {
+    platform = "android";
+  } else if (normalizedUA) {
+    platform = "other";
+  }
+
+  return {
+    isMobileDevice: isMobileOrTablet(),
+    platform,
+  } as const;
+};
+
+export const loadDesktopUIModePreference = () => {
+  if (typeof window === "undefined") {
+    return null;
+  }
+
+  try {
+    const stored = window.localStorage.getItem(DESKTOP_UI_MODE_STORAGE_KEY);
+    if (stored === "compact" || stored === "full") {
+      return stored as EditorInterface["desktopUIMode"];
+    }
+  } catch (error) {
+    // ignore storage access issues (e.g., Safari private mode)
+  }
+
+  return null;
+};
+
+const persistDesktopUIMode = (mode: EditorInterface["desktopUIMode"]) => {
+  if (typeof window === "undefined") {
+    return;
+  }
+  try {
+    window.localStorage.setItem(DESKTOP_UI_MODE_STORAGE_KEY, mode);
+  } catch (error) {
+    // ignore storage access issues (e.g., Safari private mode)
+  }
+};
+
+export const setDesktopUIMode = (mode: EditorInterface["desktopUIMode"]) => {
+  if (mode !== "compact" && mode !== "full") {
+    return;
+  }
+
+  persistDesktopUIMode(mode);
+
+  return mode;
+};

packages/common/src/emitter.ts

@@ -0,0 +1,51 @@
+import type { UnsubscribeCallback } from "@excalidraw/excalidraw/types";
+
+type Subscriber<T extends any[]> = (...payload: T) => void;
+
+export class Emitter<T extends any[] = []> {
+  public subscribers: Subscriber<T>[] = [];
+
+  /**
+   * Attaches subscriber
+   *
+   * @returns unsubscribe function
+   */
+  on(...handlers: Subscriber<T>[] | Subscriber<T>[][]): UnsubscribeCallback {
+    const _handlers = handlers
+      .flat()
+      .filter((item) => typeof item === "function");
+
+    this.subscribers.push(..._handlers);
+
+    return () => this.off(_handlers);
+  }
+
+  once(...handlers: Subscriber<T>[] | Subscriber<T>[][]): UnsubscribeCallback {
+    const _handlers = handlers
+      .flat()
+      .filter((item) => typeof item === "function");
+
+    _handlers.push(() => detach());
+
+    const detach = this.on(..._handlers);
+    return detach;
+  }
+
+  off(...handlers: Subscriber<T>[] | Subscriber<T>[][]) {
+    const _handlers = handlers.flat();
+    this.subscribers = this.subscribers.filter(
+      (handler) => !_handlers.includes(handler),
+    );
+  }
+
+  trigger(...payload: T) {
+    for (const handler of this.subscribers) {
+      handler(...payload);
+    }
+    return this;
+  }
+
+  clear() {
+    this.subscribers = [];
+  }
+}

packages/common/src/font-metadata.ts

@@ -0,0 +1,181 @@
+import type {
+  ExcalidrawTextElement,
+  FontFamilyValues,
+} from "@excalidraw/element/types";
+
+import { FONT_FAMILY, FONT_FAMILY_FALLBACKS } from "./constants";
+
+/**
+ * Encapsulates font metrics with additional font metadata.
+ * */
+export interface FontMetadata {
+  /** for head & hhea metrics read the woff2 with https://fontdrop.info/ */
+  metrics: {
+    /** head.unitsPerEm metric */
+    unitsPerEm: 1000 | 1024 | 2048;
+    /** hhea.ascender metric */
+    ascender: number;
+    /** hhea.descender metric */
+    descender: number;
+    /** harcoded unitless line-height, https://github.com/excalidraw/excalidraw/pull/6360#issuecomment-1477635971 */
+    lineHeight: number;
+  };
+  /** flag to indicate a deprecated font */
+  deprecated?: true;
+  /**
+   * whether this is a font that users can use (= shown in font picker)
+   */
+  private?: true;
+  /** flag to indiccate a local-only font */
+  local?: true;
+  /** flag to indicate a fallback font */
+  fallback?: true;
+}
+
+export const FONT_METADATA: Record<number, FontMetadata> = {
+  [FONT_FAMILY.Excalifont]: {
+    metrics: {
+      unitsPerEm: 1000,
+      ascender: 886,
+      descender: -374,
+      lineHeight: 1.25,
+    },
+  },
+  [FONT_FAMILY.Nunito]: {
+    metrics: {
+      unitsPerEm: 1000,
+      ascender: 1011,
+      descender: -353,
+      lineHeight: 1.25,
+    },
+  },
+  [FONT_FAMILY["Lilita One"]]: {
+    metrics: {
+      unitsPerEm: 1000,
+      ascender: 923,
+      descender: -220,
+      lineHeight: 1.15,
+    },
+  },
+  [FONT_FAMILY["Comic Shanns"]]: {
+    metrics: {
+      unitsPerEm: 1000,
+      ascender: 750,
+      descender: -250,
+      lineHeight: 1.25,
+    },
+  },
+  [FONT_FAMILY.Virgil]: {
+    metrics: {
+      unitsPerEm: 1000,
+      ascender: 886,
+      descender: -374,
+      lineHeight: 1.25,
+    },
+    deprecated: true,
+  },
+  [FONT_FAMILY.Helvetica]: {
+    metrics: {
+      unitsPerEm: 2048,
+      ascender: 1577,
+      descender: -471,
+      lineHeight: 1.15,
+    },
+    deprecated: true,
+    local: true,
+  },
+  [FONT_FAMILY.Cascadia]: {
+    metrics: {
+      unitsPerEm: 2048,
+      ascender: 1900,
+      descender: -480,
+      lineHeight: 1.2,
+    },
+    deprecated: true,
+  },
+  [FONT_FAMILY["Liberation Sans"]]: {
+    metrics: {
+      unitsPerEm: 2048,
+      ascender: 1854,
+      descender: -434,
+      lineHeight: 1.15,
+    },
+    private: true,
+  },
+  [FONT_FAMILY.Assistant]: {
+    metrics: {
+      unitsPerEm: 2048,
+      ascender: 1021,
+      descender: -287,
+      lineHeight: 1.25,
+    },
+    private: true,
+  },
+  [FONT_FAMILY_FALLBACKS.Xiaolai]: {
+    metrics: {
+      unitsPerEm: 1000,
+      ascender: 880,
+      descender: -144,
+      lineHeight: 1.25,
+    },
+    fallback: true,
+  },
+  [FONT_FAMILY_FALLBACKS["Segoe UI Emoji"]]: {
+    metrics: {
+      // reusing Excalifont metrics
+      unitsPerEm: 1000,
+      ascender: 886,
+      descender: -374,
+      lineHeight: 1.25,
+    },
+    local: true,
+    fallback: true,
+  },
+};
+
+/** Unicode ranges defined by google fonts */
+export const GOOGLE_FONTS_RANGES = {
+  LATIN:
+    "U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD",
+  LATIN_EXT:
+    "U+0100-02AF, U+0304, U+0308, U+0329, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF",
+  CYRILIC_EXT:
+    "U+0460-052F, U+1C80-1C88, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F",
+  CYRILIC: "U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116",
+  VIETNAMESE:
+    "U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB",
+};
+
+/** local protocol to skip the local font from registering or inlining */
+export const LOCAL_FONT_PROTOCOL = "local:";
+
+/**
+ * Calculates vertical offset for a text with alphabetic baseline.
+ */
+export const getVerticalOffset = (
+  fontFamily: ExcalidrawTextElement["fontFamily"],
+  fontSize: ExcalidrawTextElement["fontSize"],
+  lineHeightPx: number,
+) => {
+  const { unitsPerEm, ascender, descender } =
+    FONT_METADATA[fontFamily]?.metrics ||
+    FONT_METADATA[FONT_FAMILY.Excalifont].metrics;
+
+  const fontSizeEm = fontSize / unitsPerEm;
+  const lineGap =
+    (lineHeightPx - fontSizeEm * ascender + fontSizeEm * descender) / 2;
+
+  const verticalOffset = fontSizeEm * ascender + lineGap;
+  return verticalOffset;
+};
+
+/**
+ * Gets line height for a selected family.
+ */
+export const getLineHeight = (fontFamily: FontFamilyValues) => {
+  const { lineHeight } =
+    FONT_METADATA[fontFamily]?.metrics ||
+    FONT_METADATA[FONT_FAMILY.Excalifont].metrics;
+
+  return lineHeight as ExcalidrawTextElement["lineHeight"];
+};

packages/common/src/index.ts

@@ -0,0 +1,17 @@
+export * from "./binary-heap";
+export * from "./bounds";
+export * from "./colors";
+export * from "./constants";
+export * from "./font-metadata";
+export * from "./queue";
+export * from "./keys";
+export * from "./points";
+export * from "./promise-pool";
+export * from "./random";
+export * from "./url";
+export * from "./utils";
+export * from "./emitter";
+export * from "./appEventBus";
+export * from "./editorInterface";
+export * from "./versionedSnapshotStore";
+export { Debug } from "../debug";

packages/common/src/keys.ts

@@ -0,0 +1,153 @@
+import { isDarwin } from "./editorInterface";
+
+import type { ValueOf } from "./utility-types";
+
+export const CODES = {
+  EQUAL: "Equal",
+  MINUS: "Minus",
+  NUM_ADD: "NumpadAdd",
+  NUM_SUBTRACT: "NumpadSubtract",
+  NUM_ZERO: "Numpad0",
+  BRACKET_RIGHT: "BracketRight",
+  BRACKET_LEFT: "BracketLeft",
+  ONE: "Digit1",
+  TWO: "Digit2",
+  THREE: "Digit3",
+  NINE: "Digit9",
+  QUOTE: "Quote",
+  ZERO: "Digit0",
+  SLASH: "Slash",
+  C: "KeyC",
+  D: "KeyD",
+  H: "KeyH",
+  V: "KeyV",
+  Z: "KeyZ",
+  Y: "KeyY",
+  R: "KeyR",
+  S: "KeyS",
+} as const;
+
+export const KEYS = {
+  ARROW_DOWN: "ArrowDown",
+  ARROW_LEFT: "ArrowLeft",
+  ARROW_RIGHT: "ArrowRight",
+  ARROW_UP: "ArrowUp",
+  PAGE_UP: "PageUp",
+  PAGE_DOWN: "PageDown",
+  BACKSPACE: "Backspace",
+  ALT: "Alt",
+  CTRL_OR_CMD: isDarwin ? "metaKey" : "ctrlKey",
+  DELETE: "Delete",
+  ENTER: "Enter",
+  ESCAPE: "Escape",
+  QUESTION_MARK: "?",
+  SPACE: " ",
+  TAB: "Tab",
+  CHEVRON_LEFT: "<",
+  CHEVRON_RIGHT: ">",
+  PERIOD: ".",
+  COMMA: ",",
+  SUBTRACT: "-",
+  SLASH: "/",
+
+  A: "a",
+  B: "b",
+  C: "c",
+  D: "d",
+  E: "e",
+  F: "f",
+  G: "g",
+  H: "h",
+  I: "i",
+  L: "l",
+  N: "n",
+  O: "o",
+  P: "p",
+  Q: "q",
+  R: "r",
+  S: "s",
+  T: "t",
+  V: "v",
+  X: "x",
+  Y: "y",
+  Z: "z",
+  K: "k",
+  W: "w",
+
+  0: "0",
+  1: "1",
+  2: "2",
+  3: "3",
+  4: "4",
+  5: "5",
+  6: "6",
+  7: "7",
+  8: "8",
+  9: "9",
+} as const;
+
+export type Key = keyof typeof KEYS;
+
+// defines key code mapping for matching codes as fallback to respective keys on non-latin keyboard layouts
+export const KeyCodeMap = new Map<ValueOf<typeof KEYS>, ValueOf<typeof CODES>>([
+  [KEYS.Z, CODES.Z],
+  [KEYS.Y, CODES.Y],
+]);
+
+export const isLatinChar = (key: string) => /^[a-z]$/.test(key.toLowerCase());
+
+/**
+ * Used to match key events for any keyboard layout, especially on Windows and Linux,
+ * where non-latin character with modified (CMD) is not substituted with latin-based alternative.
+ *
+ * Uses `event.key` when it's latin, otherwise fallbacks to `event.code` (if mapping exists).
+ *
+ * Example of pressing "z" on different layouts, with the chosen key or code highlighted in []:
+ *
+ * Layout                | Code  | Key | Comment
+ * --------------------- | ----- | --- | -------
+ * U.S.                  |  KeyZ  | [z] |
+ * Czech                 |  KeyY  | [z] |
+ * Turkish               |  KeyN  | [z] |
+ * French                |  KeyW  | [z] |
+ * Macedonian            | [KeyZ] |  з  | z with cmd; з is Cyrillic equivalent of z
+ * Russian               | [KeyZ] |  я  | z with cmd
+ * Serbian               | [KeyZ] |  ѕ  | z with cmd
+ * Greek                 | [KeyZ] |  ζ  | z with cmd; also ζ is Greek equivalent of z
+ * Hebrew                | [KeyZ] |  ז  | z with cmd; also ז is Hebrew equivalent of z
+ * Pinyin - Simplified   |  KeyZ  | [z] | due to IME
+ * Cangije - Traditional | [KeyZ] |  重 | z with cmd
+ * Japanese              | [KeyZ] |  つ | z with cmd
+ * 2-Set Korean          | [KeyZ] |  ㅋ | z with cmd
+ *
+ * More details in https://github.com/excalidraw/excalidraw/pull/5944
+ */
+export const matchKey = (
+  event: KeyboardEvent | React.KeyboardEvent<Element>,
+  key: ValueOf<typeof KEYS>,
+): boolean => {
+  // for latin layouts use key
+  if (key === event.key.toLowerCase()) {
+    return true;
+  }
+
+  // non-latin layouts fallback to code
+  const code = KeyCodeMap.get(key);
+  return Boolean(code && !isLatinChar(event.key) && event.code === code);
+};
+
+export const isArrowKey = (key: string) =>
+  key === KEYS.ARROW_LEFT ||
+  key === KEYS.ARROW_RIGHT ||
+  key === KEYS.ARROW_DOWN ||
+  key === KEYS.ARROW_UP;
+
+export const shouldResizeFromCenter = (event: MouseEvent | KeyboardEvent) =>
+  event.altKey;
+
+export const shouldMaintainAspectRatio = (event: MouseEvent | KeyboardEvent) =>
+  event.shiftKey;
+
+export const shouldRotateWithDiscreteAngle = (
+  event: MouseEvent | KeyboardEvent | React.PointerEvent<HTMLCanvasElement>,
+) => event.shiftKey;

packages/common/src/points.ts

@@ -0,0 +1,81 @@
+import {
+  pointFrom,
+  pointFromPair,
+  type GlobalPoint,
+  type LocalPoint,
+} from "@excalidraw/math";
+
+import type { NullableGridSize } from "@excalidraw/excalidraw/types";
+
+export const getSizeFromPoints = (
+  points: readonly (GlobalPoint | LocalPoint)[],
+) => {
+  const xs = points.map((point) => point[0]);
+  const ys = points.map((point) => point[1]);
+  return {
+    width: Math.max(...xs) - Math.min(...xs),
+    height: Math.max(...ys) - Math.min(...ys),
+  };
+};
+
+/** @arg dimension, 0 for rescaling only x, 1 for y */
+export const rescalePoints = <Point extends GlobalPoint | LocalPoint>(
+  dimension: 0 | 1,
+  newSize: number,
+  points: readonly Point[],
+  normalize: boolean,
+): Point[] => {
+  const coordinates = points.map((point) => point[dimension]);
+  const maxCoordinate = Math.max(...coordinates);
+  const minCoordinate = Math.min(...coordinates);
+  const size = maxCoordinate - minCoordinate;
+  const scale = size === 0 ? 1 : newSize / size;
+
+  let nextMinCoordinate = Infinity;
+
+  const scaledPoints = points.map((point): Point => {
+    const newCoordinate = point[dimension] * scale;
+    const newPoint = [...point];
+    newPoint[dimension] = newCoordinate;
+    if (newCoordinate < nextMinCoordinate) {
+      nextMinCoordinate = newCoordinate;
+    }
+    return newPoint as Point;
+  });
+
+  if (!normalize) {
+    return scaledPoints;
+  }
+
+  if (scaledPoints.length === 2) {
+    // we don't translate two-point lines
+    return scaledPoints;
+  }
+
+  const translation = minCoordinate - nextMinCoordinate;
+
+  const nextPoints = scaledPoints.map((scaledPoint) =>
+    pointFromPair<Point>(
+      scaledPoint.map((value, currentDimension) => {
+        return currentDimension === dimension ? value + translation : value;
+      }) as [number, number],
+    ),
+  );
+
+  return nextPoints;
+};
+
+// TODO: Rounding this point causes some shake when free drawing
+export const getGridPoint = (
+  x: number,
+  y: number,
+  gridSize: NullableGridSize,
+): GlobalPoint => {
+  if (gridSize) {
+    return pointFrom<GlobalPoint>(
+      Math.round(x / gridSize) * gridSize,
+      Math.round(y / gridSize) * gridSize,
+    );
+  }
+  return pointFrom<GlobalPoint>(x, y);
+};

packages/common/src/promise-pool.ts

@@ -0,0 +1,50 @@
+import Pool from "es6-promise-pool";
+
+// extending the missing types
+// relying on the [Index, T] to keep a correct order
+type TPromisePool<T, Index = number> = Pool<[Index, T][]> & {
+  addEventListener: (
+    type: "fulfilled",
+    listener: (event: { data: { result: [Index, T] } }) => void,
+  ) => (event: { data: { result: [Index, T] } }) => void;
+  removeEventListener: (
+    type: "fulfilled",
+    listener: (event: { data: { result: [Index, T] } }) => void,
+  ) => void;
+};
+
+export class PromisePool<T> {
+  private readonly pool: TPromisePool<T>;
+  private readonly entries: Record<number, T> = {};
+
+  constructor(
+    source: IterableIterator<Promise<void | readonly [number, T]>>,
+    concurrency: number,
+  ) {
+    this.pool = new Pool(
+      source as unknown as () => void | PromiseLike<[number, T][]>,
+      concurrency,
+    ) as TPromisePool<T>;
+  }
+
+  public all() {
+    const listener = (event: { data: { result: void | [number, T] } }) => {
+      if (event.data.result) {
+        // by default pool does not return the results, so we are gathering them manually
+        // with the correct call order (represented by the index in the tuple)
+        const [index, value] = event.data.result;
+        this.entries[index] = value;
+      }
+    };
+
+    this.pool.addEventListener("fulfilled", listener);
+
+    return this.pool.start().then(() => {
+      setTimeout(() => {
+        this.pool.removeEventListener("fulfilled", listener);
+      });
+
+      return Object.values(this.entries);
+    });
+  }
+}

packages/common/src/queue.ts

@@ -0,0 +1,48 @@
+import { promiseTry, resolvablePromise } from ".";
+
+import type { ResolvablePromise } from ".";
+
+import type { MaybePromise } from "./utility-types";
+
+type Job<T, TArgs extends unknown[]> = (...args: TArgs) => MaybePromise<T>;
+
+type QueueJob<T, TArgs extends unknown[]> = {
+  jobFactory: Job<T, TArgs>;
+  promise: ResolvablePromise<T>;
+  args: TArgs;
+};
+
+export class Queue {
+  private jobs: QueueJob<any, any[]>[] = [];
+  private running = false;
+
+  private tick() {
+    if (this.running) {
+      return;
+    }
+    const job = this.jobs.shift();
+    if (job) {
+      this.running = true;
+      job.promise.resolve(
+        promiseTry(job.jobFactory, ...job.args).finally(() => {
+          this.running = false;
+          this.tick();
+        }),
+      );
+    } else {
+      this.running = false;
+    }
+  }
+
+  push<TValue, TArgs extends unknown[]>(
+    jobFactory: Job<TValue, TArgs>,
+    ...args: TArgs
+  ): Promise<TValue> {
+    const promise = resolvablePromise<TValue>();
+    this.jobs.push({ jobFactory, promise, args });
+
+    this.tick();
+
+    return promise;
+  }
+}

packages/common/src/random.ts

@@ -0,0 +1,33 @@
+import { nanoid } from "nanoid";
+import { Random } from "roughjs/bin/math";
+
+import { isTestEnv } from "./utils";
+
+let random = new Random(Date.now());
+let testIdBase = 0;
+
+export const randomInteger = () => Math.floor(random.next() * 2 ** 31);
+
+export const reseed = (seed: number) => {
+  random = new Random(seed);
+  testIdBase = 0;
+};
+
+export const randomId = () => (isTestEnv() ? `id${testIdBase++}` : nanoid());
+
+/**
+ * Deterministic PRNG (mulberry32) for a given seed: same seed, same
+ * sequence — used where a render must be stable across frames and clients
+ * (e.g. the sticky note's corner jitter) and roughjs's `Random` is
+ * unsuitable (it degenerates for seed 0). Returns numbers in [0, 1).
+ */
+export const seededRandom = (seed: number) => {
+  let value = seed >>> 0;
+  return () => {
+    value += 0x6d2b79f5;
+    let next = value;
+    next = Math.imul(next ^ (next >>> 15), next | 1);
+    next ^= next + Math.imul(next ^ (next >>> 7), next | 61);
+    return ((next ^ (next >>> 14)) >>> 0) / 4294967296;
+  };
+};

packages/common/src/url.ts

@@ -0,0 +1,37 @@
+import { sanitizeUrl } from "@braintree/sanitize-url";
+
+import { escapeDoubleQuotes } from "./utils";
+
+export const normalizeLink = (link: string) => {
+  link = link.trim();
+  if (!link) {
+    return link;
+  }
+  return sanitizeUrl(escapeDoubleQuotes(link));
+};
+
+export const isLocalLink = (link: string | null) => {
+  return !!(link?.includes(location.origin) || link?.startsWith("/"));
+};
+
+/**
+ * Returns URL sanitized and safe for usage in places such as
+ * iframe's src attribute or <a> href attributes.
+ */
+export const toValidURL = (link: string) => {
+  link = normalizeLink(link);
+
+  // make relative links into fully-qualified urls
+  if (link.startsWith("/")) {
+    return `${location.origin}${link}`;
+  }
+
+  try {
+    new URL(link);
+  } catch {
+    // if link does not parse as URL, assume invalid and return blank page
+    return "about:blank";
+  }
+
+  return link;
+};

packages/common/src/utility-types.ts

@@ -0,0 +1,79 @@
+export type Mutable<T> = {
+  -readonly [P in keyof T]: T[P];
+};
+
+export type ValueOf<T> = T[keyof T];
+
+export type Merge<M, N> = Omit<M, keyof N> & N;
+
+/** utility type to assert that the second type is a subtype of the first type.
+ * Returns the subtype. */
+export type SubtypeOf<Supertype, Subtype extends Supertype> = Subtype;
+
+export type ResolutionType<T extends (...args: any) => any> = T extends (
+  ...args: any
+) => Promise<infer R>
+  ? R
+  : any;
+
+// https://github.com/krzkaczor/ts-essentials
+export type MarkOptional<T, K extends keyof T> = Omit<T, K> &
+  Partial<Pick<T, K>>;
+
+export type MarkRequired<T, RK extends keyof T> = Exclude<T, RK> &
+  Required<Pick<T, RK>>;
+
+export type MarkNonNullable<T, K extends keyof T> = {
+  [P in K]-?: P extends K ? NonNullable<T[P]> : T[P];
+} & { [P in keyof T]: T[P] };
+
+export type NonOptional<T> = Exclude<T, undefined>;
+
+// -----------------------------------------------------------------------------
+// type getter for interface's callable type
+// src: https://stackoverflow.com/a/58658851/927631
+// -----------------------------------------------------------------------------
+export type SignatureType<T> = T extends (...args: infer R) => any ? R : never;
+export type CallableType<T extends (...args: any[]) => any> = (
+  ...args: SignatureType<T>
+) => ReturnType<T>;
+// --------------------------------------------------------------------------—
+
+// Type for React.forwardRef --- supply only the first generic argument T
+export type ForwardRef<T, P = any> = Parameters<
+  CallableType<React.ForwardRefRenderFunction<T, P>>
+>[1];
+
+export type ExtractSetType<T extends Set<any>> = T extends Set<infer U>
+  ? U
+  : never;
+
+export type SameType<T, U> = T extends U ? (U extends T ? true : false) : false;
+export type Assert<T extends true> = T;
+
+export type NestedKeyOf<T, K = keyof T> = K extends keyof T & (string | number)
+  ? `${K}` | (T[K] extends object ? `${K}.${NestedKeyOf<T[K]>}` : never)
+  : never;
+
+export type SetLike<T> = Set<T> | T[];
+export type ReadonlySetLike<T> = ReadonlySet<T> | readonly T[];
+
+export type MakeBrand<T extends string> = {
+  /** @private using ~ to sort last in intellisense */
+  [K in `~brand~${T}`]: T;
+};
+
+/** Maybe just promise or already fulfilled one! */
+export type MaybePromise<T> = T | Promise<T>;
+
+// get union of all keys from the union of types
+export type AllPossibleKeys<T> = T extends any ? keyof T : never;
+
+/** Strip all the methods or functions from a type */
+export type DTO<T> = {
+  [K in keyof T as T[K] extends Function ? never : K]: T[K];
+};
+
+export type MapEntry<M extends Map<any, any>> = M extends Map<infer K, infer V>
+  ? [K, V]
+  : never;

packages/common/src/utils.test.ts

@@ -0,0 +1,204 @@
+import {
+  getNearestScrollableContainer,
+  isInputLike,
+  isInteractive,
+  isToolIcon,
+  isTransparent,
+  isWritableElement,
+  mapFind,
+  reduceToCommonValue,
+} from "@excalidraw/common";
+import { vi } from "vitest";
+
+// Import directly to avoid the @excalidraw/common throttleRAF mock from setupTests.ts.
+import { throttleRAF } from "./utils";
+
+type RafCallback = FrameRequestCallback;
+
+describe("@excalidraw/common/utils", () => {
+  describe("cross-document element guards", () => {
+    it("uses constructors from the target element's window", () => {
+      const iframe = document.createElement("iframe");
+      document.body.append(iframe);
+
+      const iframeDocument = iframe.contentDocument!;
+      const iframeWindow = iframe.contentWindow!;
+      const textarea = iframeDocument.createElement("textarea");
+      const button = iframeDocument.createElement("button");
+      const toolIcon = iframeDocument.createElement("div");
+      toolIcon.className = "ToolIcon__icon";
+
+      expect(textarea).not.toBeInstanceOf(HTMLTextAreaElement);
+      expect(textarea).toBeInstanceOf(
+        (iframeWindow as Window & typeof globalThis).HTMLTextAreaElement,
+      );
+      expect(isInputLike(textarea)).toBe(true);
+      expect(isWritableElement(textarea)).toBe(true);
+      expect(isInteractive(button)).toBe(true);
+      expect(isToolIcon(toolIcon)).toBe(true);
+
+      iframeDocument.body.append(textarea);
+      expect(getNearestScrollableContainer(textarea)).toBe(iframeDocument);
+
+      iframe.remove();
+    });
+  });
+
+  describe("isTransparent()", () => {
+    it("should return true when color is rgb transparent", () => {
+      expect(isTransparent("#ff00")).toEqual(true);
+      expect(isTransparent("#fff00000")).toEqual(true);
+      expect(isTransparent("transparent")).toEqual(true);
+    });
+
+    it("should return false when color is not transparent", () => {
+      expect(isTransparent("#ced4da")).toEqual(false);
+    });
+  });
+
+  describe("reduceToCommonValue()", () => {
+    it("should return the common value when all values are the same", () => {
+      expect(reduceToCommonValue([1, 1])).toEqual(1);
+      expect(reduceToCommonValue([0, 0])).toEqual(0);
+      expect(reduceToCommonValue(["a", "a"])).toEqual("a");
+      expect(reduceToCommonValue(new Set([1]))).toEqual(1);
+      expect(reduceToCommonValue([""])).toEqual("");
+      expect(reduceToCommonValue([0])).toEqual(0);
+
+      const o = {};
+      expect(reduceToCommonValue([o, o])).toEqual(o);
+
+      expect(
+        reduceToCommonValue([{ a: 1 }, { a: 1, b: 2 }], (o) => o.a),
+      ).toEqual(1);
+      expect(
+        reduceToCommonValue(new Set([{ a: 1 }, { a: 1, b: 2 }]), (o) => o.a),
+      ).toEqual(1);
+    });
+
+    it("should return `null` when values are different", () => {
+      expect(reduceToCommonValue([1, 2, 3])).toEqual(null);
+      expect(reduceToCommonValue(new Set([1, 2]))).toEqual(null);
+      expect(reduceToCommonValue([{ a: 1 }, { a: 2 }], (o) => o.a)).toEqual(
+        null,
+      );
+    });
+
+    it("should return `null` when some values are nullable", () => {
+      expect(reduceToCommonValue([1, null, 1])).toEqual(null);
+      expect(reduceToCommonValue([null, 1])).toEqual(null);
+      expect(reduceToCommonValue([1, undefined])).toEqual(null);
+      expect(reduceToCommonValue([undefined, 1])).toEqual(null);
+      expect(reduceToCommonValue([null])).toEqual(null);
+      expect(reduceToCommonValue([undefined])).toEqual(null);
+      expect(reduceToCommonValue([])).toEqual(null);
+    });
+  });
+
+  describe("mapFind()", () => {
+    it("should return the first mapped non-null element", () => {
+      {
+        let counter = 0;
+
+        const result = mapFind(["a", "b", "c"], (value) => {
+          counter++;
+          return value === "b" ? 42 : null;
+        });
+        expect(result).toEqual(42);
+        expect(counter).toBe(2);
+      }
+
+      expect(mapFind([1, 2], (value) => value * 0)).toBe(0);
+      expect(mapFind([1, 2], () => false)).toBe(false);
+      expect(mapFind([1, 2], () => "")).toBe("");
+    });
+
+    it("should return undefined if no mapped element is found", () => {
+      expect(mapFind([1, 2], () => undefined)).toBe(undefined);
+      expect(mapFind([1, 2], () => null)).toBe(undefined);
+    });
+  });
+
+  describe("throttleRAF()", () => {
+    let frameCallbacks: Map<number, RafCallback>;
+    let nextFrameId: number;
+
+    const runScheduledFrame = (timestamp = 16) => {
+      const callbacks = [...frameCallbacks.values()];
+      frameCallbacks.clear();
+      callbacks.forEach((callback) => callback(timestamp));
+    };
+
+    beforeEach(() => {
+      frameCallbacks = new Map();
+      nextFrameId = 0;
+
+      vi.spyOn(window, "requestAnimationFrame").mockImplementation(
+        (callback) => {
+          const frameId = ++nextFrameId;
+          frameCallbacks.set(frameId, callback);
+          return frameId;
+        },
+      );
+
+      vi.spyOn(window, "cancelAnimationFrame").mockImplementation((frameId) => {
+        frameCallbacks.delete(frameId);
+      });
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it("should invoke the callback with the last args from the same frame", () => {
+      const fn = vi.fn();
+      const throttled = throttleRAF(fn);
+
+      throttled("first", 1);
+      throttled("second", 2);
+      throttled("last", 3);
+
+      expect(fn).not.toHaveBeenCalled();
+      expect(window.requestAnimationFrame).toHaveBeenCalledTimes(1);
+
+      runScheduledFrame();
+
+      expect(fn).toHaveBeenCalledTimes(1);
+      expect(fn).toHaveBeenCalledWith("last", 3);
+    });
+
+    it("should flush the pending callback immediately", () => {
+      const fn = vi.fn();
+      const throttled = throttleRAF(fn);
+
+      throttled("first");
+      throttled("last");
+
+      throttled.flush();
+
+      expect(window.cancelAnimationFrame).toHaveBeenCalledTimes(1);
+      expect(fn).toHaveBeenCalledTimes(1);
+      expect(fn).toHaveBeenCalledWith("last");
+
+      runScheduledFrame();
+
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it("should cancel the pending callback", () => {
+      const fn = vi.fn();
+      const throttled = throttleRAF(fn);
+
+      throttled("first");
+      throttled("last");
+
+      throttled.cancel();
+
+      expect(window.cancelAnimationFrame).toHaveBeenCalledTimes(1);
+
+      runScheduledFrame();
+
+      expect(fn).not.toHaveBeenCalled();
+    });
+  });
+});

packages/common/src/versionedSnapshotStore.ts

@@ -0,0 +1,70 @@
+export type VersionedSnapshot<T> = Readonly<{
+  version: number;
+  value: T;
+}>;
+
+export class VersionedSnapshotStore<T> {
+  private version = 0;
+  private value: T;
+  private readonly waiters = new Set<
+    (snapshot: VersionedSnapshot<T>) => void
+  >();
+  private readonly subscribers = new Set<
+    (snapshot: VersionedSnapshot<T>) => void
+  >();
+
+  constructor(
+    initialValue: T,
+    private readonly isEqual: (prev: T, next: T) => boolean = Object.is,
+  ) {
+    this.value = initialValue;
+  }
+
+  public getSnapshot(): VersionedSnapshot<T> {
+    return { version: this.version, value: this.value };
+  }
+
+  public set(nextValue: T): boolean {
+    if (this.isEqual(this.value, nextValue)) {
+      return false;
+    }
+
+    this.value = nextValue;
+    this.version += 1;
+
+    const snapshot = this.getSnapshot();
+
+    for (const subscriber of this.subscribers) {
+      subscriber(snapshot);
+    }
+    for (const waiter of this.waiters) {
+      waiter(snapshot);
+    }
+    this.waiters.clear();
+
+    return true;
+  }
+
+  public update(updater: (prev: T) => T): boolean {
+    return this.set(updater(this.value));
+  }
+
+  public subscribe(
+    subscriber: (snapshot: VersionedSnapshot<T>) => void,
+  ): () => void {
+    this.subscribers.add(subscriber);
+    return () => {
+      this.subscribers.delete(subscriber);
+    };
+  }
+
+  public pull(sinceVersion = -1): Promise<VersionedSnapshot<T>> {
+    if (this.version !== sinceVersion) {
+      return Promise.resolve(this.getSnapshot());
+    }
+
+    return new Promise((resolve) => {
+      this.waiters.add(resolve);
+    });
+  }
+}

packages/common/tests/binary-heap.test.ts

@@ -0,0 +1,109 @@
+import { BinaryHeap } from "../src/binary-heap";
+
+describe("BinaryHeap", () => {
+  const numberHeap = () => new BinaryHeap<number>((n) => n);
+
+  const drain = (heap: BinaryHeap<number>) => {
+    const out: number[] = [];
+    while (heap.size() > 0) {
+      out.push(heap.pop()!);
+    }
+    return out;
+  };
+
+  describe("empty heap", () => {
+    it("has size 0", () => {
+      expect(numberHeap().size()).toBe(0);
+    });
+
+    it("pop() returns null", () => {
+      expect(numberHeap().pop()).toBe(null);
+    });
+
+    it("remove() is a no-op and does not throw", () => {
+      const heap = numberHeap();
+      expect(() => heap.remove(1)).not.toThrow();
+      expect(heap.size()).toBe(0);
+    });
+  });
+
+  describe("push / pop", () => {
+    it("tracks size as items are added and removed", () => {
+      const heap = numberHeap();
+      [3, 1, 2].forEach((n) => heap.push(n));
+      expect(heap.size()).toBe(3);
+
+      heap.pop();
+      expect(heap.size()).toBe(2);
+    });
+
+    it("pops a single pushed element back out", () => {
+      const heap = numberHeap();
+      heap.push(42);
+      expect(heap.pop()).toBe(42);
+      expect(heap.pop()).toBe(null);
+    });
+
+    it("always pops the smallest score first", () => {
+      const heap = numberHeap();
+      [5, 3, 8, 1, 9, 2, 7].forEach((n) => heap.push(n));
+      expect(drain(heap)).toEqual([1, 2, 3, 5, 7, 8, 9]);
+    });
+
+    it("handles duplicate scores", () => {
+      const heap = numberHeap();
+      [4, 1, 4, 1, 2].forEach((n) => heap.push(n));
+      expect(drain(heap)).toEqual([1, 1, 2, 4, 4]);
+    });
+
+    it("maintains the heap invariant for a large adversarial (reverse-sorted) input", () => {
+      const heap = numberHeap();
+      // pushing in descending order forces a sift-up on every insert
+      const input = Array.from({ length: 1000 }, (_, i) => 1000 - i);
+      input.forEach((n) => heap.push(n));
+      expect(drain(heap)).toEqual([...input].sort((a, b) => a - b));
+    });
+  });
+
+  describe("remove", () => {
+    it("removes an interior element and keeps the rest ordered", () => {
+      const heap = numberHeap();
+      [5, 3, 8, 1, 9].forEach((n) => heap.push(n));
+
+      heap.remove(8);
+
+      expect(heap.size()).toBe(4);
+      expect(drain(heap)).toEqual([1, 3, 5, 9]);
+    });
+
+    it("can remove the current minimum", () => {
+      const heap = numberHeap();
+      [5, 3, 8, 1, 9].forEach((n) => heap.push(n));
+
+      heap.remove(1);
+
+      expect(heap.size()).toBe(4);
+      expect(heap.pop()).toBe(3);
+    });
+  });
+
+  describe("rescoreElement", () => {
+    type Node = { id: string; f: number };
+
+    it("re-sorts a node after its score is lowered", () => {
+      const heap = new BinaryHeap<Node>((node) => node.f);
+
+      const a = { id: "a", f: 10 };
+      const b = { id: "b", f: 20 };
+      const c = { id: "c", f: 30 };
+      [a, b, c].forEach((node) => heap.push(node));
+
+      c.f = 5;
+      heap.rescoreElement(c);
+
+      expect(heap.pop()).toBe(c);
+      expect(heap.pop()).toBe(a);
+      expect(heap.pop()).toBe(b);
+    });
+  });
+});

packages/common/tests/keys.test.ts

@@ -0,0 +1,271 @@
+import { KEYS, matchKey } from "../src/keys";
+
+describe("key matcher", async () => {
+  it("should not match unexpected key", async () => {
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "N" }), KEYS.Y),
+    ).toBeFalsy();
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "Unidentified" }), KEYS.Z),
+    ).toBeFalsy();
+
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "z" }), KEYS.Y),
+    ).toBeFalsy();
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "y" }), KEYS.Z),
+    ).toBeFalsy();
+
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "Z" }), KEYS.Y),
+    ).toBeFalsy();
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "Y" }), KEYS.Z),
+    ).toBeFalsy();
+  });
+
+  it("should match key (case insensitive) when key is latin", async () => {
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "z" }), KEYS.Z),
+    ).toBeTruthy();
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "y" }), KEYS.Y),
+    ).toBeTruthy();
+
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "Z" }), KEYS.Z),
+    ).toBeTruthy();
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "Y" }), KEYS.Y),
+    ).toBeTruthy();
+  });
+
+  it("should match key on QWERTY, QWERTZ, AZERTY", async () => {
+    // QWERTY
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "z", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "y", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // QWERTZ
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "z", code: "KeyY" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "y", code: "KeyZ" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // AZERTY
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "z", code: "KeyW" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "y", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+  });
+
+  it("should match key on DVORAK, COLEMAK", async () => {
+    // DVORAK
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "z", code: "KeySemicolon" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "y", code: "KeyF" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // COLEMAK
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "z", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "y", code: "KeyJ" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+  });
+
+  it("should match key on Turkish-Q", async () => {
+    // Turkish-Q
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "z", code: "KeyN" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "Y", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+  });
+
+  it("should not fallback when code is not defined", async () => {
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "я" }), KEYS.Z),
+    ).toBeFalsy();
+
+    expect(
+      matchKey(new KeyboardEvent("keydown", { key: "卜" }), KEYS.Y),
+    ).toBeFalsy();
+  });
+
+  it("should not fallback when code is incorrect", async () => {
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "z", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeFalsy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "Y", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeFalsy();
+  });
+
+  it("should fallback to code when key is non-latin", async () => {
+    // Macedonian
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "з", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "ѕ", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // Russian
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "я", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "н", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // Serbian
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "ѕ", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "з", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // Greek
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "ζ", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "υ", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // Hebrew
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "ז", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "ט", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // Cangjie - Traditional
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "重", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "卜", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // Japanese
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "つ", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "ん", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+
+    // 2-Set Korean
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "ㅋ", code: "KeyZ" }),
+        KEYS.Z,
+      ),
+    ).toBeTruthy();
+    expect(
+      matchKey(
+        new KeyboardEvent("keydown", { key: "ㅛ", code: "KeyY" }),
+        KEYS.Y,
+      ),
+    ).toBeTruthy();
+  });
+});

packages/common/tests/queue.test.ts

@@ -0,0 +1,62 @@
+import { Queue } from "../src/queue";
+
+describe("Queue", () => {
+  const calls: any[] = [];
+
+  const createJobFactory =
+    <T>(
+      // for purpose of this test, Error object will become a rejection value
+      resolutionOrRejectionValue: T,
+      ms = 1,
+    ) =>
+    () => {
+      return new Promise<T>((resolve, reject) => {
+        setTimeout(() => {
+          if (resolutionOrRejectionValue instanceof Error) {
+            reject(resolutionOrRejectionValue);
+          } else {
+            resolve(resolutionOrRejectionValue);
+          }
+        }, ms);
+      }).then((x) => {
+        calls.push(x);
+        return x;
+      });
+    };
+
+  beforeEach(() => {
+    calls.length = 0;
+  });
+
+  it("should await and resolve values in order of enqueueing", async () => {
+    const queue = new Queue();
+
+    const p1 = queue.push(createJobFactory("A", 50));
+    const p2 = queue.push(createJobFactory("B"));
+    const p3 = queue.push(createJobFactory("C"));
+
+    expect(await p3).toBe("C");
+    expect(await p2).toBe("B");
+    expect(await p1).toBe("A");
+
+    expect(calls).toEqual(["A", "B", "C"]);
+  });
+
+  it("should reject a job if it throws, and not affect other jobs", async () => {
+    const queue = new Queue();
+
+    const err = new Error("B");
+
+    queue.push(createJobFactory("A", 50));
+    const p2 = queue.push(createJobFactory(err));
+    const p3 = queue.push(createJobFactory("C"));
+
+    const p2err = p2.catch((err) => err);
+
+    await p3;
+
+    expect(await p2err).toBe(err);
+
+    expect(calls).toEqual(["A", "C"]);
+  });
+});

packages/common/tests/url.test.tsx

@@ -0,0 +1,31 @@
+import { normalizeLink } from "../src/url";
+
+describe("normalizeLink", () => {
+  // NOTE not an extensive XSS test suite, just to check if we're not
+  // regressing in sanitization
+  it("should sanitize links", () => {
+    expect(
+      // eslint-disable-next-line no-script-url
+      normalizeLink(`javascript://%0aalert(document.domain)`).startsWith(
+        // eslint-disable-next-line no-script-url
+        `javascript:`,
+      ),
+    ).toBe(false);
+    expect(normalizeLink("ola")).toBe("ola");
+    expect(normalizeLink(" ola")).toBe("ola");
+
+    expect(normalizeLink("https://www.excalidraw.com")).toBe(
+      "https://www.excalidraw.com",
+    );
+    expect(normalizeLink("www.excalidraw.com")).toBe("www.excalidraw.com");
+    expect(normalizeLink("/ola")).toBe("/ola");
+    expect(normalizeLink("http://test")).toBe("http://test");
+    expect(normalizeLink("ftp://test")).toBe("ftp://test");
+    expect(normalizeLink("file://")).toBe("file://");
+    expect(normalizeLink("file://")).toBe("file://");
+    expect(normalizeLink("[test](https://test)")).toBe("[test](https://test)");
+    expect(normalizeLink("[[test]]")).toBe("[[test]]");
+    expect(normalizeLink("<test>")).toBe("<test>");
+    expect(normalizeLink("test&")).toBe("test&");
+  });
+});

packages/common/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist/types",
+    "rootDir": "../"
+  },
+  "include": ["src/**/*", "global.d.ts"],
+  "exclude": ["**/*.test.*", "tests", "types", "examples", "dist"]
+}

packages/element/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["../eslintrc.base.json"]
+}

packages/element/README.md

@@ -0,0 +1,19 @@
+# @excalidraw/element
+
+## Install
+
+```bash
+npm install @excalidraw/element
+```
+
+If you prefer Yarn over npm, use this command to install the Excalidraw utils package:
+
+```bash
+yarn add @excalidraw/element
+```
+
+With PNPM, similarly install the package with this command:
+
+```bash
+pnpm add @excalidraw/element
+```

packages/element/global.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="vite/client" />
+import "@excalidraw/excalidraw/global";
+import "@excalidraw/excalidraw/css";

packages/element/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@excalidraw/element",
+  "version": "0.18.0",
+  "type": "module",
+  "types": "./dist/types/element/src/index.d.ts",
+  "main": "./dist/prod/index.js",
+  "module": "./dist/prod/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/types/element/src/index.d.ts",
+      "development": "./dist/dev/index.js",
+      "production": "./dist/prod/index.js",
+      "default": "./dist/prod/index.js"
+    },
+    "./*": {
+      "types": "./dist/types/element/src/*.d.ts",
+      "development": "./dist/dev/index.js",
+      "production": "./dist/prod/index.js",
+      "default": "./dist/prod/index.js"
+    },
+    "./visualdebug": {
+      "types": "./dist/types/element/src/visualdebug.d.ts",
+      "development": "./dist/dev/visualdebug.js",
+      "production": "./dist/prod/visualdebug.js",
+      "default": "./dist/prod/visualdebug.js"
+    }
+  },
+  "files": [
+    "dist/*"
+  ],
+  "description": "Excalidraw elements-related logic",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "keywords": [
+    "excalidraw",
+    "excalidraw-utils"
+  ],
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not ie <= 11",
+      "not op_mini all",
+      "not safari < 12",
+      "not kaios <= 2.5",
+      "not edge < 79",
+      "not chrome < 70",
+      "not and_uc < 13",
+      "not samsung < 10"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  },
+  "bugs": "https://github.com/excalidraw/excalidraw/issues",
+  "repository": "https://github.com/excalidraw/excalidraw",
+  "scripts": {
+    "gen:types": "rimraf types && tsc",
+    "build:esm": "rimraf dist && node ../../scripts/buildBase.js && yarn gen:types"
+  },
+  "dependencies": {
+    "@excalidraw/common": "0.18.0",
+    "@excalidraw/math": "0.18.0",
+    "@excalidraw/fractional-indexing": "3.3.0"
+  }
+}

packages/element/src/Scene.ts

@@ -0,0 +1,446 @@
+import throttle from "lodash.throttle";
+
+import {
+  randomInteger,
+  arrayToMap,
+  toBrandedType,
+  isDevEnv,
+  isTestEnv,
+  toArray,
+} from "@excalidraw/common";
+import { isNonDeletedElement } from "@excalidraw/element";
+import { isFrameLikeElement } from "@excalidraw/element";
+import { getElementsInGroup } from "@excalidraw/element";
+
+import {
+  syncInvalidIndices,
+  syncMovedIndices,
+  validateFractionalIndices,
+} from "@excalidraw/element";
+
+import { getSelectedElements } from "@excalidraw/element";
+
+import { mutateElement, type ElementUpdate } from "@excalidraw/element";
+
+import type {
+  ExcalidrawElement,
+  NonDeletedExcalidrawElement,
+  NonDeleted,
+  ExcalidrawFrameLikeElement,
+  ElementsMapOrArray,
+  SceneElementsMap,
+  NonDeletedSceneElementsMap,
+  OrderedExcalidrawElement,
+  Ordered,
+} from "@excalidraw/element/types";
+
+import type {
+  Assert,
+  Mutable,
+  SameType,
+} from "@excalidraw/common/utility-types";
+
+import type { AppState } from "../../excalidraw/types";
+
+type SceneStateCallback = () => void;
+type SceneStateCallbackRemover = () => void;
+
+type SelectionHash = string & { __brand: "selectionHash" };
+
+const getNonDeletedElements = <T extends ExcalidrawElement>(
+  allElements: readonly T[],
+) => {
+  const elementsMap = new Map() as NonDeletedSceneElementsMap;
+  const elements: NonDeleted<T>[] = [];
+  for (const element of allElements) {
+    if (!element.isDeleted) {
+      elements.push(element as NonDeleted<T>);
+      elementsMap.set(
+        element.id,
+        element as Ordered<NonDeletedExcalidrawElement>,
+      );
+    }
+  }
+  return { elementsMap, elements };
+};
+
+const validateIndicesThrottled = throttle(
+  (elements: readonly ExcalidrawElement[]) => {
+    if (isDevEnv() || isTestEnv() || window?.DEBUG_FRACTIONAL_INDICES) {
+      validateFractionalIndices(elements, {
+        // throw only in dev & test, to remain functional on `DEBUG_FRACTIONAL_INDICES`
+        shouldThrow: isDevEnv() || isTestEnv(),
+        includeBoundTextValidation: true,
+      });
+    }
+  },
+  1000 * 60,
+  { leading: true, trailing: false },
+);
+
+const hashSelectionOpts = (
+  opts: Parameters<InstanceType<typeof Scene>["getSelectedElements"]>[0],
+) => {
+  const keys = ["includeBoundTextElement", "includeElementsInFrames"] as const;
+
+  type HashableKeys = Omit<typeof opts, "selectedElementIds" | "elements">;
+
+  // just to ensure we're hashing all expected keys
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  type _ = Assert<
+    SameType<
+      Required<HashableKeys>,
+      Pick<Required<HashableKeys>, typeof keys[number]>
+    >
+  >;
+
+  let hash = "";
+  for (const key of keys) {
+    hash += `${key}:${opts[key] ? "1" : "0"}`;
+  }
+  return hash as SelectionHash;
+};
+
+// ideally this would be a branded type but it'd be insanely hard to work with
+// in our codebase
+export type ExcalidrawElementsIncludingDeleted = readonly ExcalidrawElement[];
+
+export class Scene {
+  // ---------------------------------------------------------------------------
+  // instance methods/props
+  // ---------------------------------------------------------------------------
+
+  private callbacks: Set<SceneStateCallback> = new Set();
+
+  private nonDeletedElements: readonly Ordered<NonDeletedExcalidrawElement>[] =
+    [];
+  private nonDeletedElementsMap = toBrandedType<NonDeletedSceneElementsMap>(
+    new Map(),
+  );
+  // ideally all elements within the scene should be wrapped around with `Ordered` type, but right now there is no real benefit doing so
+  private elements: readonly OrderedExcalidrawElement[] = [];
+  private nonDeletedFramesLikes: readonly NonDeleted<ExcalidrawFrameLikeElement>[] =
+    [];
+  private frames: readonly ExcalidrawFrameLikeElement[] = [];
+  private elementsMap = toBrandedType<SceneElementsMap>(new Map());
+  private selectedElementsCache: {
+    selectedElementIds: AppState["selectedElementIds"] | null;
+    elements: readonly NonDeletedExcalidrawElement[] | null;
+    cache: Map<SelectionHash, NonDeletedExcalidrawElement[]>;
+  } = {
+    selectedElementIds: null,
+    elements: null,
+    cache: new Map(),
+  };
+  /**
+   * Random integer regenerated each scene update.
+   *
+   * Does not relate to elements versions, it's only a renderer
+   * cache-invalidation nonce at the moment.
+   */
+  private sceneNonce: number | undefined;
+
+  getSceneNonce() {
+    return this.sceneNonce;
+  }
+
+  getNonDeletedElementsMap() {
+    return this.nonDeletedElementsMap;
+  }
+
+  getElementsIncludingDeleted() {
+    return this.elements;
+  }
+
+  getElementsMapIncludingDeleted() {
+    return this.elementsMap;
+  }
+
+  getNonDeletedElements() {
+    return this.nonDeletedElements;
+  }
+
+  getFramesIncludingDeleted() {
+    return this.frames;
+  }
+
+  constructor(
+    elements: ElementsMapOrArray | null = null,
+    options?: {
+      skipValidation?: true;
+    },
+  ) {
+    if (elements) {
+      this.replaceAllElements(elements, options);
+    }
+  }
+
+  getSelectedElements(opts: {
+    // NOTE can be ommitted by making Scene constructor require App instance
+    selectedElementIds: AppState["selectedElementIds"];
+    /**
+     * for specific cases where you need to use elements not from current
+     * scene state. This in effect will likely result in cache-miss, and
+     * the cache won't be updated in this case.
+     */
+    elements?: ElementsMapOrArray;
+    // selection-related options
+    includeBoundTextElement?: boolean;
+    includeElementsInFrames?: boolean;
+  }): NonDeletedExcalidrawElement[] {
+    const hash = hashSelectionOpts(opts);
+
+    const elements = opts?.elements || this.nonDeletedElements;
+    if (
+      this.selectedElementsCache.elements === elements &&
+      this.selectedElementsCache.selectedElementIds === opts.selectedElementIds
+    ) {
+      const cached = this.selectedElementsCache.cache.get(hash);
+      if (cached) {
+        return cached;
+      }
+    } else if (opts?.elements == null) {
+      // if we're operating on latest scene elements and the cache is not
+      //  storing the latest elements, clear the cache
+      this.selectedElementsCache.cache.clear();
+    }
+
+    const selectedElements = getSelectedElements(
+      elements,
+      { selectedElementIds: opts.selectedElementIds },
+      opts,
+    );
+
+    // cache only if we're not using custom elements
+    if (opts?.elements == null) {
+      this.selectedElementsCache.selectedElementIds = opts.selectedElementIds;
+      this.selectedElementsCache.elements = this.nonDeletedElements;
+      this.selectedElementsCache.cache.set(hash, selectedElements);
+    }
+
+    return selectedElements;
+  }
+
+  getNonDeletedFramesLikes(): readonly NonDeleted<ExcalidrawFrameLikeElement>[] {
+    return this.nonDeletedFramesLikes;
+  }
+
+  getElement<T extends ExcalidrawElement>(id: T["id"]): T | null {
+    return (this.elementsMap.get(id) as T | undefined) || null;
+  }
+
+  getNonDeletedElement(
+    id: ExcalidrawElement["id"],
+  ): NonDeleted<ExcalidrawElement> | null {
+    const element = this.getElement(id);
+    if (element && isNonDeletedElement(element)) {
+      return element;
+    }
+    return null;
+  }
+
+  /**
+   * A utility method to help with updating all scene elements, with the added
+   * performance optimization of not renewing the array if no change is made.
+   *
+   * Maps all current excalidraw elements, invoking the callback for each
+   * element. The callback should either return a new mapped element, or the
+   * original element if no changes are made. If no changes are made to any
+   * element, this results in a no-op. Otherwise, the newly mapped elements
+   * are set as the next scene's elements.
+   *
+   * @returns whether a change was made
+   */
+  mapElements(
+    iteratee: (element: ExcalidrawElement) => ExcalidrawElement,
+  ): boolean {
+    let didChange = false;
+    const newElements = this.elements.map((element) => {
+      const nextElement = iteratee(element);
+      if (nextElement !== element) {
+        didChange = true;
+      }
+      return nextElement;
+    });
+    if (didChange) {
+      this.replaceAllElements(newElements);
+    }
+    return didChange;
+  }
+
+  replaceAllElements(
+    nextElements: ElementsMapOrArray,
+    options?: {
+      skipValidation?: true;
+    },
+  ) {
+    // we do trust the insertion order on the map, though maybe we shouldn't and should prefer order defined by fractional indices
+    const _nextElements = toArray(nextElements);
+    const nextFrameLikes: ExcalidrawFrameLikeElement[] = [];
+
+    if (!options?.skipValidation) {
+      validateIndicesThrottled(_nextElements);
+    }
+
+    this.elements = syncInvalidIndices(_nextElements);
+    this.elementsMap.clear();
+    this.elements.forEach((element) => {
+      if (isFrameLikeElement(element)) {
+        nextFrameLikes.push(element);
+      }
+      this.elementsMap.set(element.id, element);
+    });
+    const nonDeletedElements = getNonDeletedElements(this.elements);
+    this.nonDeletedElements = nonDeletedElements.elements;
+    this.nonDeletedElementsMap = nonDeletedElements.elementsMap;
+
+    this.frames = nextFrameLikes;
+    this.nonDeletedFramesLikes = getNonDeletedElements(this.frames).elements;
+
+    this.triggerUpdate();
+  }
+
+  triggerUpdate() {
+    this.sceneNonce = randomInteger();
+
+    for (const callback of Array.from(this.callbacks)) {
+      callback();
+    }
+  }
+
+  onUpdate(cb: SceneStateCallback): SceneStateCallbackRemover {
+    if (this.callbacks.has(cb)) {
+      throw new Error();
+    }
+
+    this.callbacks.add(cb);
+
+    return () => {
+      if (!this.callbacks.has(cb)) {
+        throw new Error();
+      }
+      this.callbacks.delete(cb);
+    };
+  }
+
+  destroy() {
+    this.elements = [];
+    this.nonDeletedElements = [];
+    this.nonDeletedFramesLikes = [];
+    this.frames = [];
+    this.elementsMap.clear();
+    this.selectedElementsCache.selectedElementIds = null;
+    this.selectedElementsCache.elements = null;
+    this.selectedElementsCache.cache.clear();
+
+    // done not for memory leaks, but to guard against possible late fires
+    // (I guess?)
+    this.callbacks.clear();
+  }
+
+  /** low-level - generally use app.insertNewElements() */
+  insertElementsAtIndex(
+    elements: ExcalidrawElement[],
+    /** null indicates end of the array */
+    index: number | null,
+  ) {
+    if (!elements.length) {
+      return;
+    }
+
+    if (index === null) {
+      index = this.elements.length;
+    }
+
+    if (!Number.isFinite(index) || index < 0) {
+      throw new Error(
+        "insertElementAtIndex can only be called with index >= 0",
+      );
+    }
+
+    const nextElements = [
+      ...this.elements.slice(0, index),
+      ...elements,
+      ...this.elements.slice(index),
+    ];
+
+    syncMovedIndices(nextElements, arrayToMap(elements));
+
+    this.replaceAllElements(nextElements);
+  }
+
+  /** low-level - generally use app.insertNewElement() */
+  insertElement = (element: ExcalidrawElement) => {
+    this.insertElementsAtIndex([element], null);
+  };
+
+  getElementIndex(elementId: string) {
+    return this.elements.findIndex((element) => element.id === elementId);
+  }
+
+  getContainerElement = (
+    element:
+      | (ExcalidrawElement & {
+          containerId: ExcalidrawElement["id"] | null;
+        })
+      | null,
+  ) => {
+    if (!element) {
+      return null;
+    }
+    if (element.containerId) {
+      return this.getElement(element.containerId) || null;
+    }
+    return null;
+  };
+
+  getElementsFromId = (id: string): ExcalidrawElement[] => {
+    const elementsMap = this.getNonDeletedElementsMap();
+    // first check if the id is an element
+    const el = elementsMap.get(id);
+    if (el) {
+      return [el];
+    }
+
+    // then, check if the id is a group
+    return getElementsInGroup(elementsMap, id);
+  };
+
+  // Mutate an element with passed updates and trigger the component to update. Make sure you
+  // are calling it either from a React event handler or within unstable_batchedUpdates().
+  mutateElement<TElement extends Mutable<ExcalidrawElement>>(
+    element: TElement,
+    updates: ElementUpdate<TElement>,
+    options: {
+      informMutation: boolean;
+      isDragging: boolean;
+      isBindingEnabled?: boolean;
+      isMidpointSnappingEnabled?: boolean;
+    } = {
+      informMutation: true,
+      isDragging: false,
+    },
+  ) {
+    const elementsMap = this.getNonDeletedElementsMap();
+
+    const { version: prevVersion } = element;
+    const { version: nextVersion } = mutateElement(
+      element,
+      elementsMap,
+      updates,
+      options,
+    );
+
+    if (
+      // skip if the element is not in the scene (i.e. selection)
+      this.elementsMap.has(element.id) &&
+      // skip if the element's version hasn't changed, as mutateElement returned the same element
+      prevVersion !== nextVersion &&
+      options.informMutation
+    ) {
+      this.triggerUpdate();
+    }
+
+    return element;
+  }
+}

packages/element/src/__tests__/flowchart.test.ts

@@ -0,0 +1,60 @@
+import { ROUNDNESS } from "@excalidraw/common";
+
+import type { AppState } from "@excalidraw/excalidraw/types";
+
+import { Scene } from "../Scene";
+import { addNewNodes } from "../flowchart";
+import { newStickyNoteElement } from "../newElement";
+import { isFlowchartNodeElement, isStickyNoteElement } from "../typeChecks";
+
+describe("flowchart", () => {
+  it("creates connected sticky notes", () => {
+    const sticky = newStickyNoteElement({
+      type: "stickynote",
+      x: 100,
+      y: 100,
+      width: 240,
+      height: 260,
+      baseHeight: 220,
+      roundness: { type: ROUNDNESS.PROPORTIONAL_RADIUS },
+      roughness: 2,
+      backgroundColor: "#ffec99",
+      strokeColor: "#1e1e1e",
+      strokeWidth: 2,
+    });
+    const scene = new Scene([sticky], { skipValidation: true });
+    const {
+      nodes: [nextNode, bindingArrow],
+    } = addNewNodes(
+      sticky,
+      {
+        currentItemEndArrowhead: "arrow",
+      } as AppState,
+      "right",
+      scene,
+      1,
+    );
+
+    expect(isFlowchartNodeElement(sticky)).toBe(true);
+    expect(isFlowchartNodeElement(nextNode)).toBe(true);
+    expect(isStickyNoteElement(nextNode)).toBe(true);
+    expect(nextNode).toMatchObject({
+      type: "stickynote",
+      x: sticky.x + sticky.width + 100,
+      y: sticky.y,
+      width: sticky.width,
+      height: sticky.height,
+      baseHeight: sticky.baseHeight,
+      roundness: sticky.roundness,
+      roughness: sticky.roughness,
+      backgroundColor: sticky.backgroundColor,
+      strokeColor: sticky.strokeColor,
+      strokeWidth: sticky.strokeWidth,
+    });
+    expect(bindingArrow).toMatchObject({
+      type: "arrow",
+      startBinding: { elementId: sticky.id },
+      endBinding: { elementId: nextNode.id },
+    });
+  });
+});

packages/element/src/align.ts

@@ -0,0 +1,82 @@
+import type { AppState } from "@excalidraw/excalidraw/types";
+
+import { updateBoundElements } from "./binding";
+import { getCommonBoundingBox } from "./bounds";
+import { getSelectedElementsByGroup } from "./groups";
+
+import { getNonDeletedElements } from ".";
+
+import type { Scene } from "./Scene";
+
+import type { BoundingBox } from "./bounds";
+import type { ExcalidrawElement, NonDeletedExcalidrawElement } from "./types";
+
+export interface Alignment {
+  position: "start" | "center" | "end";
+  axis: "x" | "y";
+}
+
+export const alignElements = (
+  selectedElements: NonDeletedExcalidrawElement[],
+  alignment: Alignment,
+  scene: Scene,
+  appState: Readonly<AppState>,
+): NonDeletedExcalidrawElement[] => {
+  const groups = getSelectedElementsByGroup(
+    selectedElements,
+    scene.getNonDeletedElementsMap(),
+    appState,
+  ).map(getNonDeletedElements); // Nothing to align on deleted elements
+  const selectionBoundingBox = getCommonBoundingBox(selectedElements);
+
+  return groups.flatMap((group) => {
+    const translation = calculateTranslation(
+      group,
+      selectionBoundingBox,
+      alignment,
+    );
+    return group.map((element) => {
+      // update element
+      const updatedEle = scene.mutateElement(element, {
+        x: element.x + translation.x,
+        y: element.y + translation.y,
+      });
+
+      // update bound elements
+      updateBoundElements(element, scene, {
+        simultaneouslyUpdated: group,
+      });
+      return updatedEle;
+    });
+  });
+};
+
+const calculateTranslation = (
+  group: readonly ExcalidrawElement[],
+  selectionBoundingBox: BoundingBox,
+  { axis, position }: Alignment,
+): { x: number; y: number } => {
+  const groupBoundingBox = getCommonBoundingBox(group);
+
+  const [min, max]: ["minX" | "minY", "maxX" | "maxY"] =
+    axis === "x" ? ["minX", "maxX"] : ["minY", "maxY"];
+
+  const noTranslation = { x: 0, y: 0 };
+  if (position === "start") {
+    return {
+      ...noTranslation,
+      [axis]: selectionBoundingBox[min] - groupBoundingBox[min],
+    };
+  } else if (position === "end") {
+    return {
+      ...noTranslation,
+      [axis]: selectionBoundingBox[max] - groupBoundingBox[max],
+    };
+  } // else if (position === "center") {
+  return {
+    ...noTranslation,
+    [axis]:
+      (selectionBoundingBox[min] + selectionBoundingBox[max]) / 2 -
+      (groupBoundingBox[min] + groupBoundingBox[max]) / 2,
+  };
+};

packages/element/src/arrowEndpointText.ts

@@ -0,0 +1,288 @@
+/**
+ * Text bound to an arrow endpoint — creating a text element that reads as a
+ * label for the tip of an arrow, placed and anchored so the arrow itself never
+ * moves.
+ *
+ * The App-side interaction (hover affordance, hit gating, creation/drag entry
+ * points) lives in `App.arrowText.ts`; the generic binding bookkeeping these
+ * helpers rely on stays in `binding.ts`.
+ */
+import { TEXT_ALIGN, VERTICAL_ALIGN } from "@excalidraw/common";
+
+import {
+  pointDistance,
+  pointFromVector,
+  pointsEqual,
+  vector,
+  vectorDot,
+  vectorFromPoint,
+  vectorNormalize,
+  vectorScale,
+} from "@excalidraw/math";
+
+import type { GlobalPoint } from "@excalidraw/math";
+
+import type { AppState } from "@excalidraw/excalidraw/types";
+
+import { getBindingGap, normalizeFixedPoint } from "./binding";
+import {
+  HEADING_DOWN,
+  HEADING_LEFT,
+  HEADING_RIGHT,
+  HEADING_UP,
+  compareHeading,
+} from "./heading";
+import { LinearElementEditor } from "./linearElementEditor";
+import { getTextAnchorRatios } from "./newElement";
+import { isArrowElement, isElbowArrow } from "./typeChecks";
+
+import type { Heading } from "./heading";
+import type {
+  ElementsMap,
+  ExcalidrawArrowElement,
+  ExcalidrawTextElement,
+  FixedPoint,
+  NonDeleted,
+  NonDeletedExcalidrawElement,
+  TextAlign,
+  VerticalAlign,
+} from "./types";
+
+export type ArrowEndpoint = {
+  arrow: NonDeleted<ExcalidrawArrowElement>;
+  startOrEnd: "start" | "end";
+};
+
+/**
+ * Finds a free (unbound) arrow endpoint under the cursor, front-most first.
+ * Used by the text tool to offer creating a text label anchored to the tip of
+ * an arrow.
+ */
+export const getUnboundArrowEndpointAtPoint = (
+  scenePointer: GlobalPoint,
+  elements: readonly NonDeletedExcalidrawElement[],
+  elementsMap: ElementsMap,
+  zoom: AppState["zoom"],
+): ArrowEndpoint | null => {
+  // front to back, so the top-most arrow wins when endpoints overlap
+  for (let index = elements.length - 1; index >= 0; index--) {
+    const element = elements[index];
+
+    if (
+      !isArrowElement(element) ||
+      element.locked ||
+      element.points.length < 2
+    ) {
+      continue;
+    }
+
+    // prefer the end (arrowhead) over the start when both are within range
+    for (const startOrEnd of ["end", "start"] as const) {
+      if (element[startOrEnd === "start" ? "startBinding" : "endBinding"]) {
+        continue;
+      }
+
+      // a zero-length tail has no direction to place a text along, so
+      // `getTextBindingForArrowEndpoint` would refuse the endpoint — don't
+      // offer it at all rather than highlight something a click won't honor
+      if (
+        pointsEqual(
+          element.points[
+            startOrEnd === "start" ? 0 : element.points.length - 1
+          ],
+          element.points[
+            startOrEnd === "start" ? 1 : element.points.length - 2
+          ],
+        )
+      ) {
+        continue;
+      }
+
+      const point = LinearElementEditor.getPointAtIndexGlobalCoordinates(
+        element,
+        startOrEnd === "start" ? 0 : -1,
+        elementsMap,
+      );
+
+      // same reach as grabbing a point handle in the linear editor
+      // (`LinearElementEditor.getPointIndexUnderCursor`), which can't be
+      // reused here: it reports whichever point is nearest, with no way to
+      // skip an endpoint that is already bound and fall through to the other
+      if (
+        pointDistance(scenePointer, point) * zoom.value <
+        LinearElementEditor.POINT_HANDLE_SIZE + 1
+      ) {
+        return { arrow: element, startOrEnd };
+      }
+    }
+  }
+
+  return null;
+};
+
+/**
+ * Describes how a text element should be created so that it reads as a label
+ * for the given arrow endpoint.
+ *
+ * The arrow is treated as fixed: rather than routing the arrow to the text, we
+ * pick the side of the text the arrow should attach to (the one it already
+ * points at), and place the text so that side's midpoint lands on the existing
+ * endpoint. The alignment returned pins that same midpoint while the text is
+ * typed, so the arrow doesn't swing around during editing.
+ */
+export const getTextBindingForArrowEndpoint = (
+  arrow: NonDeleted<ExcalidrawArrowElement>,
+  startOrEnd: "start" | "end",
+  elementsMap: ElementsMap,
+  /**
+   * stroke width the text will be created with — the binding gap is derived
+   * from the *bind target*, so using the arrow's would offset the anchor by
+   * half the difference between the two
+   */
+  targetStrokeWidth: number,
+): {
+  /** the text-local ratio the arrow binds to (a side midpoint) */
+  fixedPoint: FixedPoint;
+  textAlign: TextAlign;
+  verticalAlign: VerticalAlign;
+  /** scene position the text's bound side midpoint should sit at */
+  anchor: GlobalPoint;
+} | null => {
+  const endpoint = LinearElementEditor.getPointAtIndexGlobalCoordinates(
+    arrow,
+    startOrEnd === "start" ? 0 : -1,
+    elementsMap,
+  );
+  const neighbor = LinearElementEditor.getPointAtIndexGlobalCoordinates(
+    arrow,
+    startOrEnd === "start" ? 1 : -2,
+    elementsMap,
+  );
+
+  if (pointsEqual(endpoint, neighbor)) {
+    return null;
+  }
+
+  // The direction the arrow travels as it reaches this endpoint, snapped to
+  // the dominant axis — i.e. the direction the text should extend away from
+  // the tip.
+  //
+  // Deliberately not `vectorToHeading`: its tie-break resolves an exact 45°
+  // vector to a direction the arrow isn't travelling in at all (a perfectly
+  // down-right vector yields UP), which would put the text on the wrong side.
+  // Here a tie picks the horizontal axis, always with the correct sign.
+  const direction = vectorFromPoint(endpoint, neighbor);
+  const heading: Heading =
+    Math.abs(direction[0]) >= Math.abs(direction[1])
+      ? direction[0] >= 0
+        ? HEADING_RIGHT
+        : HEADING_LEFT
+      : direction[1] >= 0
+      ? HEADING_DOWN
+      : HEADING_UP;
+
+  // Keep the tip off the text's bounding box by the usual binding gap so the
+  // arrowhead doesn't collide with the glyphs. Must match the gap
+  // `updateBoundPoint` will resolve the binding with, or the first text update
+  // shifts the arrow. Elbow arrows terminate on the fixed point itself rather
+  // than gap-outside the outline, so offsetting there would just shift them.
+  const gap = isElbowArrow(arrow)
+    ? 0
+    : getBindingGap({ strokeWidth: targetStrokeWidth }, arrow);
+
+  // How far back along the arrow the bound side has to sit for the tip to
+  // stay exactly where it is.
+  //
+  // `updateBoundPoint` resolves an orbit binding by intersecting the arrow's
+  // own line with the target's outline grown by `gap`; it does not step along
+  // the bound side's normal. Offsetting the anchor perpendicular to the side
+  // would therefore leave the tip `gap * tan(angle)` off to one side on a
+  // diagonal arrow. Walking back along the arrow instead keeps the anchor both
+  // `gap` clear of the tip and collinear with the arrow, so the intersection
+  // lands back on the tip itself.
+  //
+  // `heading` is the dominant axis of the arrow direction, so it is never more
+  // than 45° away from it and the divisor stays >= cos(45°).
+  const awayFromTip = vectorNormalize(vectorFromPoint(neighbor, endpoint));
+  const alongHeading = Math.abs(
+    vectorDot(awayFromTip, vector(heading[0], heading[1])),
+  );
+  const anchor = pointFromVector(
+    vectorScale(awayFromTip, -gap / alongHeading),
+    endpoint,
+  );
+
+  if (compareHeading(heading, HEADING_RIGHT)) {
+    // text sits to the right of the tip -> bind its left side
+    return {
+      fixedPoint: normalizeFixedPoint([0, 0.5]),
+      anchor,
+      textAlign: TEXT_ALIGN.LEFT as TextAlign,
+      verticalAlign: VERTICAL_ALIGN.MIDDLE as VerticalAlign,
+    };
+  }
+
+  if (compareHeading(heading, HEADING_LEFT)) {
+    // text sits to the left of the tip -> bind its right side
+    return {
+      fixedPoint: normalizeFixedPoint([1, 0.5]),
+      anchor,
+      textAlign: TEXT_ALIGN.RIGHT as TextAlign,
+      verticalAlign: VERTICAL_ALIGN.MIDDLE as VerticalAlign,
+    };
+  }
+
+  if (compareHeading(heading, HEADING_DOWN)) {
+    // text sits below the tip -> bind its top side
+    return {
+      fixedPoint: normalizeFixedPoint([0.5, 0]),
+      anchor,
+      textAlign: TEXT_ALIGN.CENTER as TextAlign,
+      verticalAlign: VERTICAL_ALIGN.TOP as VerticalAlign,
+    };
+  }
+
+  // text sits above the tip -> bind its bottom side
+  return {
+    fixedPoint: normalizeFixedPoint([0.5, 1]),
+    anchor,
+    textAlign: TEXT_ALIGN.CENTER as TextAlign,
+    verticalAlign: VERTICAL_ALIGN.BOTTOM as VerticalAlign,
+  };
+};
+
+/**
+ * Whether an arrow endpoint is bound to this text — i.e. the text serves as an
+ * arrow-endpoint label. Checked on the arrows' own bindings: the text's
+ * `boundElements` only says an arrow relates to it, while the binding on the
+ * arrow is the authoritative side of the relationship.
+ */
+export const isEndpointBoundText = (
+  text: ExcalidrawTextElement,
+  elementsMap: ElementsMap,
+): boolean =>
+  !!text.boundElements?.some(({ id, type }) => {
+    if (type !== "arrow") {
+      return false;
+    }
+
+    const arrow = elementsMap.get(id);
+
+    return (
+      isArrowElement(arrow) &&
+      (arrow.startBinding?.elementId === text.id ||
+        arrow.endBinding?.elementId === text.id)
+    );
+  });
+
+/** the anchor a text bound to an arrow endpoint grows away from */
+export const getEndpointBoundTextDragAnchor = (
+  newElement: ExcalidrawTextElement,
+) => {
+  const anchorRatio = getTextAnchorRatios(newElement).x;
+
+  return {
+    anchorRatio,
+    anchorX: newElement.x + newElement.width * anchorRatio,
+  };
+};

packages/element/src/arrowheads.ts

@@ -0,0 +1,32 @@
+import type { Arrowhead, AnyArrowhead } from "./types";
+
+export const normalizeArrowhead = (
+  arrowhead: AnyArrowhead | null | undefined,
+): Arrowhead | null => {
+  switch (arrowhead) {
+    case undefined:
+    case null:
+      return null;
+    case "dot":
+      return "circle";
+    case "crowfoot_one":
+      return "cardinality_one";
+    case "crowfoot_many":
+      return "cardinality_many";
+    case "crowfoot_one_or_many":
+      return "cardinality_one_or_many";
+    default:
+      return arrowhead;
+  }
+};
+
+export const getArrowheadForPicker = (
+  arrowhead: AnyArrowhead | null | undefined,
+): Arrowhead | null => {
+  const normalizedArrowhead = normalizeArrowhead(arrowhead);
+  if (normalizedArrowhead === null) {
+    return null;
+  }
+
+  return normalizedArrowhead;
+};

packages/element/src/arrows/focus.ts

@@ -0,0 +1,575 @@
+import { pointDistance, pointFrom, type GlobalPoint } from "@excalidraw/math";
+import { invariant } from "@excalidraw/common";
+
+import type { AppState, NullableGridSize } from "@excalidraw/excalidraw/types";
+
+import {
+  bindBindingElement,
+  calculateFixedPointForNonElbowArrowBinding,
+  FOCUS_POINT_SIZE,
+  getBindingGap,
+  getGlobalFixedPointForBindableElement,
+  isBindingEnabled,
+  maxBindingDistance_simple,
+  unbindBindingElement,
+  updateBoundPoint,
+} from "../binding";
+import {
+  isBindableElement,
+  isBindingElement,
+  isElbowArrow,
+} from "../typeChecks";
+import { LinearElementEditor } from "../linearElementEditor";
+import { getHoveredElementForFocusPoint, hitElementItself } from "../collision";
+import { moveArrowAboveBindable } from "../zindex";
+
+import type {
+  ElementsMap,
+  ExcalidrawArrowElement,
+  ExcalidrawBindableElement,
+  NonDeleted,
+  FixedPointBinding,
+  NonDeletedSceneElementsMap,
+  PointsPositionUpdates,
+} from "../types";
+
+import type { Scene } from "../Scene";
+
+export const isFocusPointVisible = (
+  focusPoint: GlobalPoint,
+  arrow: ExcalidrawArrowElement,
+  bindableElement: ExcalidrawBindableElement,
+  elementsMap: ElementsMap,
+  appState: {
+    isBindingEnabled: AppState["isBindingEnabled"];
+    zoom: AppState["zoom"];
+  },
+  startOrEnd: "start" | "end",
+  ignoreOverlap = false,
+): boolean => {
+  // No focus point management for elbow arrows, because elbow arrows
+  // always have their focus point at the arrow point itself
+  if (
+    isElbowArrow(arrow) ||
+    !isBindingEnabled(appState) ||
+    arrow.points.length !== 2
+  ) {
+    return false;
+  }
+
+  // Avoid showing the focus point indicator if the focus point is essentially
+  // on top of the arrow point it belongs to itself, if not ignoring specifically
+  if (!ignoreOverlap) {
+    const associatedPointIdx =
+      arrow.startBinding?.elementId === bindableElement.id
+        ? 0
+        : arrow.points.length - 1;
+    const associatedArrowPoint =
+      LinearElementEditor.getPointAtIndexGlobalCoordinates(
+        arrow,
+        associatedPointIdx,
+        elementsMap,
+      );
+
+    if (
+      pointDistance(focusPoint, associatedArrowPoint) <
+      (FOCUS_POINT_SIZE * 1.5) / appState.zoom.value
+    ) {
+      return false;
+    }
+  }
+
+  const arrowPoint = LinearElementEditor.getPointAtIndexGlobalCoordinates(
+    arrow,
+    startOrEnd === "end" ? arrow.points.length - 1 : 0,
+    elementsMap,
+  );
+
+  // Check if the focus point is within the element's shape bounds
+  // Endpoint dragging takes precedence
+  return (
+    pointDistance(focusPoint, arrowPoint) >=
+      (FOCUS_POINT_SIZE * 1.5) / appState.zoom.value &&
+    hitElementItself({
+      element: bindableElement,
+      elementsMap,
+      point: focusPoint,
+      threshold: getBindingGap(bindableElement, arrow),
+      overrideShouldTestInside: true,
+    })
+  );
+};
+
+// Updates the arrow endpoints in "orbit" configuration
+const focusPointUpdate = (
+  arrow: NonDeleted<ExcalidrawArrowElement>,
+  bindableElement: ExcalidrawBindableElement | null,
+  isStartBinding: boolean,
+  elementsMap: NonDeletedSceneElementsMap,
+  scene: Scene,
+  appState: AppState,
+  switchToInsideBinding: boolean,
+) => {
+  const pointUpdates = new Map();
+
+  const originalAdjacentBinding =
+    appState.selectedLinearElement?.initialState
+      .arrowOtherEndpointInitialBinding;
+  const bindingField = isStartBinding ? "startBinding" : "endBinding";
+  const adjacentBindingField = isStartBinding ? "endBinding" : "startBinding";
+  let currentBinding = arrow[bindingField];
+  let adjacentBinding =
+    originalAdjacentBinding?.mode === "orbit" &&
+    arrow[adjacentBindingField]?.mode === "inside"
+      ? originalAdjacentBinding
+      : arrow[adjacentBindingField];
+
+  // Update the dragged focus point related end
+  if (currentBinding && bindableElement) {
+    // Update the targeted bindings
+    const boundToSameElement =
+      bindableElement &&
+      adjacentBinding &&
+      currentBinding.elementId === adjacentBinding.elementId;
+    if (switchToInsideBinding || boundToSameElement) {
+      currentBinding = {
+        ...currentBinding,
+        mode: "inside",
+      };
+    } else {
+      currentBinding = {
+        ...currentBinding,
+        mode: "orbit",
+      };
+    }
+
+    const pointIndex = isStartBinding ? 0 : arrow.points.length - 1;
+    const newPoint = updateBoundPoint(
+      arrow,
+      bindingField as "startBinding" | "endBinding",
+      currentBinding,
+      bindableElement,
+      elementsMap,
+      true,
+    );
+
+    if (newPoint) {
+      pointUpdates.set(pointIndex, { point: newPoint });
+    }
+  }
+
+  // Also update the adjacent end if it has a binding
+  if (adjacentBinding && adjacentBinding.mode === "orbit") {
+    const adjacentBindableElement = elementsMap.get(
+      adjacentBinding.elementId,
+    ) as ExcalidrawBindableElement;
+
+    if (
+      adjacentBindableElement &&
+      isBindableElement(adjacentBindableElement) &&
+      isBindingEnabled(appState)
+    ) {
+      // Same shape bound on both ends
+      const boundToSameElementAfterUpdate =
+        bindableElement && adjacentBinding.elementId === bindableElement.id;
+      if (boundToSameElementAfterUpdate) {
+        adjacentBinding = {
+          ...adjacentBinding,
+          mode: "inside",
+        };
+      } else {
+        adjacentBinding = {
+          ...adjacentBinding,
+          mode: "orbit",
+        };
+      }
+
+      const adjacentPointIndex = isStartBinding ? arrow.points.length - 1 : 0;
+      const adjacentNewPoint = updateBoundPoint(
+        arrow,
+        adjacentBindingField,
+        adjacentBinding,
+        adjacentBindableElement,
+        elementsMap,
+      );
+
+      if (adjacentNewPoint) {
+        pointUpdates.set(adjacentPointIndex, {
+          point: adjacentNewPoint,
+        });
+      }
+    }
+  }
+
+  if (pointUpdates.size > 0) {
+    LinearElementEditor.movePoints(arrow, scene, pointUpdates, {
+      [bindingField]: currentBinding,
+      [adjacentBindingField]: adjacentBinding,
+    });
+  }
+};
+
+export const handleFocusPointDrag = (
+  linearElementEditor: LinearElementEditor,
+  elementsMap: NonDeletedSceneElementsMap,
+  pointerCoords: { x: number; y: number },
+  scene: Scene,
+  appState: AppState,
+  gridSize: NullableGridSize,
+  switchToInsideBinding: boolean,
+) => {
+  const arrow = LinearElementEditor.getElement(
+    linearElementEditor.elementId,
+    elementsMap,
+  );
+
+  // Sanity checks
+  if (
+    !arrow ||
+    !isBindingElement(arrow) ||
+    isElbowArrow(arrow) ||
+    !linearElementEditor.hoveredFocusPointBinding ||
+    !linearElementEditor.draggedFocusPointBinding
+  ) {
+    return;
+  }
+
+  const isStartBinding =
+    linearElementEditor.draggedFocusPointBinding === "start";
+  const binding = isStartBinding ? arrow.startBinding : arrow.endBinding;
+  const { x: offsetX, y: offsetY } = linearElementEditor.pointerOffset;
+  const point = pointFrom<GlobalPoint>(
+    pointerCoords.x - offsetX,
+    pointerCoords.y - offsetY,
+  );
+  const bindingField = isStartBinding ? "startBinding" : "endBinding";
+  const hit = getHoveredElementForFocusPoint(
+    point,
+    arrow,
+    scene.getNonDeletedElements(),
+    elementsMap,
+    maxBindingDistance_simple(appState.zoom),
+  );
+
+  // Hovering a bindable element
+  if (hit && isBindingEnabled(appState)) {
+    // Break existing binding if bound to another shape or if binding is disabled
+    if (arrow[bindingField] && hit.id !== binding?.elementId) {
+      unbindBindingElement(
+        arrow,
+        linearElementEditor.draggedFocusPointBinding,
+        scene,
+      );
+    }
+
+    // Handle binding mode switch
+    const newMode =
+      switchToInsideBinding && arrow[bindingField]?.mode === "orbit"
+        ? "inside"
+        : !switchToInsideBinding && arrow[bindingField]?.mode === "inside"
+        ? "orbit"
+        : null;
+
+    // If no existing binding, create it
+    if (!arrow[bindingField] || newMode) {
+      // Create a new binding if none exists
+      bindBindingElement(
+        arrow,
+        hit,
+        newMode || "orbit",
+        linearElementEditor.draggedFocusPointBinding,
+        scene,
+        point,
+      );
+    }
+
+    // Update the binding's fixed point
+    scene.mutateElement(arrow, {
+      [bindingField]: {
+        ...arrow[bindingField],
+        elementId: hit.id,
+        mode: newMode || arrow[bindingField]?.mode || "orbit",
+        ...calculateFixedPointForNonElbowArrowBinding(
+          arrow,
+          hit,
+          linearElementEditor.draggedFocusPointBinding,
+          elementsMap,
+          point,
+        ),
+      },
+    });
+  } else {
+    // Not hovering any bindable element, move the arrow endpoint
+    const pointUpdates: PointsPositionUpdates = new Map();
+    const pointIndex = isStartBinding ? 0 : arrow.points.length - 1;
+    pointUpdates.set(pointIndex, {
+      point: LinearElementEditor.createPointAt(
+        arrow,
+        elementsMap,
+        point[0],
+        point[1],
+        gridSize,
+      ),
+    });
+    LinearElementEditor.movePoints(arrow, scene, pointUpdates);
+    if (arrow[bindingField]) {
+      unbindBindingElement(arrow, isStartBinding ? "start" : "end", scene);
+    }
+  }
+
+  // Update the arrow endpoints
+  focusPointUpdate(
+    arrow,
+    hit,
+    isStartBinding,
+    elementsMap,
+    scene,
+    appState,
+    switchToInsideBinding,
+  );
+
+  if (hit && isBindingEnabled(appState)) {
+    moveArrowAboveBindable(
+      point,
+      arrow,
+      scene.getElementsIncludingDeleted(),
+      elementsMap,
+      scene,
+      hit,
+    );
+  }
+};
+
+export const handleFocusPointPointerDown = (
+  arrow: ExcalidrawArrowElement,
+  pointerDownState: { origin: { x: number; y: number } },
+  elementsMap: NonDeletedSceneElementsMap,
+  appState: AppState,
+): {
+  hitFocusPoint: "start" | "end" | null;
+  pointerOffset: { x: number; y: number };
+  arrowOtherEndpointInitialBinding: FixedPointBinding | null;
+} => {
+  const pointerPos = pointFrom(
+    pointerDownState.origin.x,
+    pointerDownState.origin.y,
+  );
+  const hitThreshold = (FOCUS_POINT_SIZE * 1.5) / appState.zoom.value;
+
+  // Check start binding focus point
+  if (arrow.startBinding?.elementId) {
+    const bindableElement = elementsMap.get(arrow.startBinding.elementId);
+    if (
+      bindableElement &&
+      isBindableElement(bindableElement) &&
+      !bindableElement.isDeleted
+    ) {
+      const focusPoint = getGlobalFixedPointForBindableElement(
+        arrow.startBinding.fixedPoint,
+        bindableElement,
+        elementsMap,
+      );
+      if (
+        isFocusPointVisible(
+          focusPoint,
+          arrow,
+          bindableElement,
+          elementsMap,
+          appState,
+          "start",
+        ) &&
+        pointDistance(pointerPos, focusPoint) <= hitThreshold
+      ) {
+        return {
+          hitFocusPoint: "start",
+          pointerOffset: {
+            x: pointerPos[0] - focusPoint[0],
+            y: pointerPos[1] - focusPoint[1],
+          },
+          arrowOtherEndpointInitialBinding: arrow.endBinding,
+        };
+      }
+    }
+  }
+
+  // Check end binding focus point (only if start not already hit)
+  if (arrow.endBinding?.elementId) {
+    const bindableElement = elementsMap.get(arrow.endBinding.elementId);
+    if (
+      bindableElement &&
+      isBindableElement(bindableElement) &&
+      !bindableElement.isDeleted
+    ) {
+      const focusPoint = getGlobalFixedPointForBindableElement(
+        arrow.endBinding.fixedPoint,
+        bindableElement,
+        elementsMap,
+      );
+      if (
+        isFocusPointVisible(
+          focusPoint,
+          arrow,
+          bindableElement,
+          elementsMap,
+          appState,
+          "end",
+        ) &&
+        pointDistance(pointerPos, focusPoint) <= hitThreshold
+      ) {
+        return {
+          hitFocusPoint: "end",
+          pointerOffset: {
+            x: pointerPos[0] - focusPoint[0],
+            y: pointerPos[1] - focusPoint[1],
+          },
+          arrowOtherEndpointInitialBinding: arrow.startBinding,
+        };
+      }
+    }
+  }
+
+  return {
+    hitFocusPoint: null,
+    pointerOffset: { x: 0, y: 0 },
+    arrowOtherEndpointInitialBinding: null,
+  };
+};
+
+export const handleFocusPointPointerUp = (
+  linearElementEditor: LinearElementEditor,
+  scene: Scene,
+) => {
+  invariant(
+    linearElementEditor.draggedFocusPointBinding,
+    "Must have a dragged focus point at pointer release",
+  );
+
+  const arrow = LinearElementEditor.getElement<ExcalidrawArrowElement>(
+    linearElementEditor.elementId,
+    scene.getNonDeletedElementsMap(),
+  );
+  invariant(arrow, "Arrow must be in the scene");
+
+  // Clean up
+  const bindingKey =
+    linearElementEditor.draggedFocusPointBinding === "start"
+      ? "startBinding"
+      : "endBinding";
+  const otherBindingKey =
+    linearElementEditor.draggedFocusPointBinding === "start"
+      ? "endBinding"
+      : "startBinding";
+  const boundElementId = arrow[bindingKey]?.elementId;
+  const otherBoundElementId = arrow[otherBindingKey]?.elementId;
+  const oldBoundElement =
+    boundElementId &&
+    scene
+      .getNonDeletedElements()
+      .find(
+        (element) =>
+          element.id !== boundElementId &&
+          element.id !== otherBoundElementId &&
+          isBindableElement(element) &&
+          element.boundElements?.find(({ id }) => id === arrow.id),
+      );
+  if (oldBoundElement) {
+    scene.mutateElement(oldBoundElement, {
+      boundElements: oldBoundElement.boundElements?.filter(
+        ({ id }) => id !== arrow.id,
+      ),
+    });
+  }
+
+  // Record the new bound element
+  const boundElement =
+    boundElementId && scene.getNonDeletedElementsMap().get(boundElementId);
+  if (boundElement) {
+    scene.mutateElement(boundElement, {
+      boundElements: [
+        ...(boundElement.boundElements || [])?.filter(
+          ({ id }) => id !== arrow.id,
+        ),
+        {
+          id: arrow.id,
+          type: "arrow",
+        },
+      ],
+    });
+  }
+
+  return {
+    arrowOtherEndpointInitialBinding: null,
+  };
+};
+
+export const handleFocusPointHover = (
+  arrow: ExcalidrawArrowElement,
+  scenePointerX: number,
+  scenePointerY: number,
+  scene: Scene,
+  appState: AppState,
+): "start" | "end" | null => {
+  const elementsMap = scene.getNonDeletedElementsMap();
+  const pointerPos = pointFrom(scenePointerX, scenePointerY);
+  const hitThreshold = (FOCUS_POINT_SIZE * 1.5) / appState.zoom.value;
+
+  // Check start binding focus point
+  if (arrow.startBinding?.elementId) {
+    const bindableElement = elementsMap.get(arrow.startBinding.elementId);
+    if (
+      bindableElement &&
+      isBindableElement(bindableElement) &&
+      !bindableElement.isDeleted
+    ) {
+      const focusPoint = getGlobalFixedPointForBindableElement(
+        arrow.startBinding.fixedPoint,
+        bindableElement,
+        elementsMap,
+      );
+      if (
+        isFocusPointVisible(
+          focusPoint,
+          arrow,
+          bindableElement,
+          elementsMap,
+          appState,
+          "start",
+        ) &&
+        pointDistance(pointerPos, focusPoint) <= hitThreshold
+      ) {
+        return "start";
+      }
+    }
+  }
+
+  // Check end binding focus point (only if start not already hovered)
+  if (arrow.endBinding?.elementId) {
+    const bindableElement = elementsMap.get(arrow.endBinding.elementId);
+    if (
+      bindableElement &&
+      isBindableElement(bindableElement) &&
+      !bindableElement.isDeleted
+    ) {
+      const focusPoint = getGlobalFixedPointForBindableElement(
+        arrow.endBinding.fixedPoint,
+        bindableElement,
+        elementsMap,
+      );
+      if (
+        isFocusPointVisible(
+          focusPoint,
+          arrow,
+          bindableElement,
+          elementsMap,
+          appState,
+          "end",
+        ) &&
+        pointDistance(pointerPos, focusPoint) <= hitThreshold
+      ) {
+        return "end";
+      }
+    }
+  }
+
+  return null;
+};

packages/element/src/arrows/helpers.ts

@@ -0,0 +1,45 @@
+import type { App } from "@excalidraw/excalidraw/types";
+
+import { LinearElementEditor } from "../linearElementEditor";
+
+import { handleFocusPointDrag } from "./focus";
+
+export const maybeHandleArrowPointlikeDrag = ({
+  app,
+  event,
+}: {
+  app: App;
+  event: KeyboardEvent | React.KeyboardEvent<Element> | PointerEvent;
+}): boolean => {
+  const appState = app.state;
+  if (appState.selectedLinearElement && app.lastPointerMoveCoords) {
+    // Update focus point status if the binding mode is changing
+    if (appState.selectedLinearElement.draggedFocusPointBinding) {
+      handleFocusPointDrag(
+        appState.selectedLinearElement,
+        app.scene.getNonDeletedElementsMap(),
+        app.lastPointerMoveCoords,
+        app.scene,
+        appState,
+        app.getEffectiveGridSize(),
+        event.altKey,
+      );
+      return true;
+    } else if (
+      appState.selectedLinearElement.hoverPointIndex !== null &&
+      app.lastPointerMoveEvent &&
+      appState.selectedLinearElement.initialState.lastClickedPoint >= 0 &&
+      appState.selectedLinearElement.isDragging
+    ) {
+      LinearElementEditor.handlePointDragging(
+        app.lastPointerMoveEvent,
+        app,
+        app.lastPointerMoveCoords.x,
+        app.lastPointerMoveCoords.y,
+        appState.selectedLinearElement,
+      );
+      return true;
+    }
+  }
+  return false;
+};

packages/element/src/collision.ts

@@ -0,0 +1,868 @@
+import { invariant, isTransparent, type Bounds } from "@excalidraw/common";
+import {
+  curveIntersectLineSegment,
+  isPointWithinBounds,
+  lineSegment,
+  lineSegmentIntersectionPoints,
+  pointFrom,
+  pointFromVector,
+  pointRotateRads,
+  pointsEqual,
+  vectorFromPoint,
+  vectorNormalize,
+  vectorScale,
+} from "@excalidraw/math";
+
+import {
+  ellipse,
+  ellipseSegmentInterceptPoints,
+} from "@excalidraw/math/ellipse";
+
+import type {
+  Curve,
+  GlobalPoint,
+  LineSegment,
+  Radians,
+} from "@excalidraw/math";
+
+import type { FrameNameBounds } from "@excalidraw/excalidraw/types";
+
+import { isPathALoop } from "./utils";
+import {
+  doBoundsIntersect,
+  elementCenterPoint,
+  getCenterForBounds,
+  getCubicBezierCurveBound,
+  getDiamondPoints,
+  getElementBounds,
+  pointInsideBounds,
+} from "./bounds";
+import {
+  hasBoundTextElement,
+  isBindableElement,
+  isFrameLikeElement,
+  isFreeDrawElement,
+  isIframeLikeElement,
+  isImageElement,
+  isLinearElement,
+  isTextElement,
+} from "./typeChecks";
+import {
+  deconstructDiamondElement,
+  deconstructLinearOrFreeDrawElement,
+  deconstructRectanguloidElement,
+} from "./utils";
+
+import { getBoundTextElement } from "./textElement";
+
+import { LinearElementEditor } from "./linearElementEditor";
+
+import { distanceToElement } from "./distance";
+
+import { getBindingGap } from "./binding";
+
+import { hasBackground } from "./comparisons";
+
+import type {
+  ElementsMap,
+  ExcalidrawArrowElement,
+  ExcalidrawBindableElement,
+  ExcalidrawDiamondElement,
+  ExcalidrawElement,
+  ExcalidrawEllipseElement,
+  ExcalidrawFreeDrawElement,
+  ExcalidrawLinearElement,
+  ExcalidrawRectanguloidElement,
+  NonDeleted,
+  NonDeletedExcalidrawElement,
+  NonDeletedSceneElementsMap,
+  Ordered,
+} from "./types";
+
+export const shouldTestInside = (element: ExcalidrawElement) => {
+  if (element.type === "arrow") {
+    return false;
+  }
+
+  const isDraggableFromInside =
+    (hasBackground(element.type) && !isTransparent(element.backgroundColor)) ||
+    hasBoundTextElement(element) ||
+    isIframeLikeElement(element) ||
+    isTextElement(element);
+
+  if (element.type === "line") {
+    return isDraggableFromInside && isPathALoop(element.points);
+  }
+
+  if (element.type === "freedraw") {
+    return isDraggableFromInside && isPathALoop(element.points);
+  }
+
+  return isDraggableFromInside || isImageElement(element);
+};
+
+export type HitTestArgs = {
+  point: GlobalPoint;
+  element: ExcalidrawElement;
+  threshold: number;
+  elementsMap: ElementsMap;
+  frameNameBound?: FrameNameBounds | null;
+  overrideShouldTestInside?: boolean;
+};
+
+let cachedPoint: GlobalPoint | null = null;
+let cachedElement: WeakRef<ExcalidrawElement> | null = null;
+let cachedThreshold: number = Infinity;
+let cachedHit: boolean = false;
+let cachedOverrideShouldTestInside = false;
+let cachedFrameNameBound: FrameNameBounds | null = null;
+
+const frameNameBoundsEqual = (
+  a: FrameNameBounds | null,
+  b: FrameNameBounds | null,
+) =>
+  a === b ||
+  (!!a &&
+    !!b &&
+    a.x === b.x &&
+    a.y === b.y &&
+    a.width === b.width &&
+    a.height === b.height);
+
+export const hitElementItself = ({
+  point,
+  element,
+  threshold,
+  elementsMap,
+  frameNameBound = null,
+  overrideShouldTestInside = false,
+}: HitTestArgs) => {
+  // Return cached result if the same point and element version is tested again.
+  // A cached hit stays valid for any larger threshold, while a cached miss
+  // stays valid only for a threshold no larger than the cached one (a larger
+  // threshold could turn a miss into a hit).
+  if (
+    cachedPoint &&
+    pointsEqual(point, cachedPoint) &&
+    (cachedHit ? cachedThreshold <= threshold : cachedThreshold >= threshold) &&
+    overrideShouldTestInside === cachedOverrideShouldTestInside &&
+    frameNameBoundsEqual(frameNameBound, cachedFrameNameBound)
+  ) {
+    const derefElement = cachedElement?.deref();
+    if (
+      derefElement &&
+      derefElement.id === element.id &&
+      derefElement.version === element.version &&
+      derefElement.versionNonce === element.versionNonce
+    ) {
+      return cachedHit;
+    }
+  }
+
+  // Hit test against a frame's name
+  const hitFrameName = frameNameBound
+    ? isPointWithinBounds(
+        pointFrom(frameNameBound.x - threshold, frameNameBound.y - threshold),
+        point,
+        pointFrom(
+          frameNameBound.x + frameNameBound.width + threshold,
+          frameNameBound.y + frameNameBound.height + threshold,
+        ),
+      )
+    : false;
+
+  // Hit test against the extended, rotated bounding box of the element first
+  const bounds = getElementBounds(element, elementsMap, true);
+  const hitBounds = isPointInRotatedBounds(
+    point,
+    bounds,
+    element.angle,
+    threshold,
+  );
+
+  // PERF: Bail out early if the point is not even in the
+  // rotated bounding box or not hitting the frame name (saves 99%)
+  if (!hitBounds && !hitFrameName) {
+    return false;
+  }
+
+  // Do the precise (and relatively costly) hit test
+  const hitElement = (
+    overrideShouldTestInside ? true : shouldTestInside(element)
+  )
+    ? // Since `inShape` tests STRICTLY againt the insides of a shape
+      // we would need `onShape` as well to include the "borders"
+      isPointInElement(point, element, elementsMap) ||
+      isPointOnElementOutline(point, element, elementsMap, threshold)
+    : isPointOnElementOutline(point, element, elementsMap, threshold);
+
+  const result = hitElement || hitFrameName;
+
+  // Cache end result
+  cachedPoint = point;
+  cachedElement = new WeakRef(element);
+  cachedThreshold = threshold;
+  cachedOverrideShouldTestInside = overrideShouldTestInside;
+  cachedFrameNameBound = frameNameBound;
+  cachedHit = result;
+
+  return result;
+};
+
+const isPointInRotatedBounds = (
+  point: GlobalPoint,
+  bounds: Bounds,
+  angle: Radians,
+  tolerance = 0,
+) => {
+  const adjustedPoint =
+    angle === 0
+      ? point
+      : pointRotateRads(point, getCenterForBounds(bounds), -angle as Radians);
+
+  return isPointWithinBounds(
+    pointFrom(bounds[0] - tolerance, bounds[1] - tolerance),
+    adjustedPoint,
+    pointFrom(bounds[2] + tolerance, bounds[3] + tolerance),
+  );
+};
+
+export const hitElementBoundingBox = (
+  point: GlobalPoint,
+  element: ExcalidrawElement,
+  elementsMap: ElementsMap,
+  tolerance = 0,
+) => {
+  const bounds = getElementBounds(element, elementsMap, true);
+  return isPointInRotatedBounds(point, bounds, element.angle, tolerance);
+};
+
+export const hitElementBoundingBoxOnly = (
+  hitArgs: HitTestArgs,
+  elementsMap: ElementsMap,
+) =>
+  !hitElementItself(hitArgs) &&
+  // bound text is considered part of the element (even if it's outside the bounding box)
+  !hitElementBoundText(hitArgs.point, hitArgs.element, elementsMap) &&
+  hitElementBoundingBox(hitArgs.point, hitArgs.element, elementsMap);
+
+export const hitElementBoundText = (
+  point: GlobalPoint,
+  element: ExcalidrawElement,
+  elementsMap: ElementsMap,
+): boolean => {
+  const boundTextElementCandidate = getBoundTextElement(element, elementsMap);
+
+  if (!boundTextElementCandidate) {
+    return false;
+  }
+  const boundTextElement = isLinearElement(element)
+    ? {
+        ...boundTextElementCandidate,
+        // arrow's bound text accurate position is not stored in the element's property
+        // but rather calculated and returned from the following static method
+        ...LinearElementEditor.getBoundTextElementPosition(
+          element,
+          boundTextElementCandidate,
+          elementsMap,
+        ),
+      }
+    : boundTextElementCandidate;
+
+  return isPointInElement(point, boundTextElement, elementsMap);
+};
+
+const bindingBorderTest = (
+  element: NonDeleted<ExcalidrawBindableElement>,
+  [x, y]: Readonly<GlobalPoint>,
+  elementsMap: NonDeletedSceneElementsMap,
+  tolerance: number = 0,
+): boolean => {
+  const p = pointFrom<GlobalPoint>(x, y);
+  const shouldTestInside =
+    // disable fullshape snapping for frame elements so we
+    // can bind to frame children
+    !isFrameLikeElement(element);
+
+  // PERF: Run a cheap test to see if the binding element
+  // is even close to the element
+  const t = Math.max(1, tolerance);
+  const bounds = [x - t, y - t, x + t, y + t] as Bounds;
+  const elementBounds = getElementBounds(element, elementsMap);
+  if (!doBoundsIntersect(bounds, elementBounds)) {
+    return false;
+  }
+
+  // If the element is inside a frame, we should clip the element
+  if (element.frameId) {
+    const enclosingFrame = elementsMap.get(element.frameId);
+    if (enclosingFrame && isFrameLikeElement(enclosingFrame)) {
+      const enclosingFrameBounds = getElementBounds(
+        enclosingFrame,
+        elementsMap,
+      );
+      if (!pointInsideBounds(p, enclosingFrameBounds)) {
+        return false;
+      }
+    }
+  }
+
+  // Do the intersection test against the element since it's close enough
+  const intersections = intersectElementWithLineSegment(
+    element,
+    elementsMap,
+    lineSegment(elementCenterPoint(element, elementsMap), p),
+  );
+  const distance = distanceToElement(element, elementsMap, p);
+
+  return shouldTestInside
+    ? intersections.length === 0 || distance <= tolerance
+    : intersections.length > 0 && distance <= t;
+};
+
+export const getAllHoveredElementAtPoint = (
+  point: Readonly<GlobalPoint>,
+  elements: readonly Ordered<NonDeletedExcalidrawElement>[],
+  elementsMap: NonDeletedSceneElementsMap,
+  tolerance?: number,
+): NonDeleted<ExcalidrawBindableElement>[] => {
+  const candidateElements: NonDeleted<ExcalidrawBindableElement>[] = [];
+  // We need to to hit testing from front (end of the array) to back (beginning of the array)
+  // because array is ordered from lower z-index to highest and we want element z-index
+  // with higher z-index
+  for (let index = elements.length - 1; index >= 0; --index) {
+    const element = elements[index];
+
+    invariant(
+      !element.isDeleted,
+      "Elements in the function parameter for getAllElementsAtPositionForBinding() should not contain deleted elements",
+    );
+
+    if (
+      isBindableElement(element, false) &&
+      bindingBorderTest(element, point, elementsMap, tolerance)
+    ) {
+      candidateElements.push(element);
+
+      if (
+        hasBackground(element.type) &&
+        !isTransparent(element.backgroundColor)
+      ) {
+        break;
+      }
+    }
+  }
+
+  return candidateElements;
+};
+
+export const getHoveredElementForBinding = (
+  point: Readonly<GlobalPoint>,
+  elements: readonly Ordered<NonDeletedExcalidrawElement>[],
+  elementsMap: NonDeletedSceneElementsMap,
+  tolerance?: number,
+): NonDeleted<ExcalidrawBindableElement> | null => {
+  const candidateElements = getAllHoveredElementAtPoint(
+    point,
+    elements,
+    elementsMap,
+    tolerance,
+  );
+
+  if (!candidateElements || candidateElements.length === 0) {
+    return null;
+  }
+
+  if (candidateElements.length === 1) {
+    return candidateElements[0];
+  }
+
+  // Prefer smaller shapes
+  return candidateElements
+    .sort(
+      (a, b) => b.width ** 2 + b.height ** 2 - (a.width ** 2 + a.height ** 2),
+    )
+    .pop() as NonDeleted<ExcalidrawBindableElement>;
+};
+
+export const getHoveredElementForFocusPoint = (
+  point: GlobalPoint,
+  arrow: ExcalidrawArrowElement,
+  elements: readonly Ordered<NonDeletedExcalidrawElement>[],
+  elementsMap: NonDeletedSceneElementsMap,
+  tolerance?: number,
+): NonDeleted<ExcalidrawBindableElement> | null => {
+  const candidateElements: NonDeleted<ExcalidrawBindableElement>[] = [];
+  // We need to to hit testing from front (end of the array) to back (beginning of the array)
+  // because array is ordered from lower z-index to highest and we want element z-index
+  // with higher z-index
+  for (let index = elements.length - 1; index >= 0; --index) {
+    const element = elements[index];
+
+    invariant(
+      !element.isDeleted,
+      "Elements in the function parameter for getAllElementsAtPositionForBinding() should not contain deleted elements",
+    );
+
+    if (
+      isBindableElement(element, false) &&
+      bindingBorderTest(element, point, elementsMap, tolerance)
+    ) {
+      candidateElements.push(element);
+    }
+  }
+
+  if (!candidateElements || candidateElements.length === 0) {
+    return null;
+  }
+
+  if (candidateElements.length === 1) {
+    return candidateElements[0];
+  }
+
+  const distanceFilteredCandidateElements = candidateElements
+    // Resolve by distance
+    .filter(
+      (el) =>
+        distanceToElement(el, elementsMap, point) <= getBindingGap(el, arrow) ||
+        isPointInElement(point, el, elementsMap),
+    );
+
+  if (distanceFilteredCandidateElements.length === 0) {
+    return null;
+  }
+
+  return distanceFilteredCandidateElements[0] as NonDeleted<ExcalidrawBindableElement>;
+};
+
+/**
+ * Intersect a line with an element for binding test
+ *
+ * @param element
+ * @param line
+ * @param offset
+ * @returns
+ */
+export const intersectElementWithLineSegment = (
+  element: ExcalidrawElement,
+  elementsMap: ElementsMap,
+  line: LineSegment<GlobalPoint>,
+  offset: number = 0,
+  onlyFirst = false,
+): GlobalPoint[] => {
+  // First check if the line intersects the element's axis-aligned bounding box
+  // as it is much faster than checking intersection against the element's shape
+  const intersectorBounds = [
+    Math.min(line[0][0] - offset, line[1][0] - offset),
+    Math.min(line[0][1] - offset, line[1][1] - offset),
+    Math.max(line[0][0] + offset, line[1][0] + offset),
+    Math.max(line[0][1] + offset, line[1][1] + offset),
+  ] as Bounds;
+  const elementBounds = getElementBounds(element, elementsMap);
+
+  if (!doBoundsIntersect(intersectorBounds, elementBounds)) {
+    return [];
+  }
+
+  // Do the actual intersection test against the element's shape
+  switch (element.type) {
+    case "rectangle":
+    case "stickynote":
+    case "image":
+    case "text":
+    case "iframe":
+    case "embeddable":
+    case "frame":
+    case "selection":
+    case "magicframe":
+      return intersectRectanguloidWithLineSegment(
+        element,
+        elementsMap,
+        line,
+        offset,
+        onlyFirst,
+      );
+    case "diamond":
+      return intersectDiamondWithLineSegment(
+        element,
+        elementsMap,
+        line,
+        offset,
+        onlyFirst,
+      );
+    case "ellipse":
+      return intersectEllipseWithLineSegment(
+        element,
+        elementsMap,
+        line,
+        offset,
+      );
+    case "line":
+    case "freedraw":
+    case "arrow":
+      return intersectLinearOrFreeDrawWithLineSegment(
+        element,
+        line,
+        elementsMap,
+        onlyFirst,
+      );
+  }
+};
+
+const curveIntersections = (
+  curves: Curve<GlobalPoint>[],
+  segment: LineSegment<GlobalPoint>,
+  intersections: GlobalPoint[],
+  center: GlobalPoint,
+  angle: Radians,
+  onlyFirst = false,
+) => {
+  for (const c of curves) {
+    // Optimize by doing a cheap bounding box check first
+    const b1 = getCubicBezierCurveBound(c[0], c[1], c[2], c[3]);
+    const b2 = [
+      Math.min(segment[0][0], segment[1][0]),
+      Math.min(segment[0][1], segment[1][1]),
+      Math.max(segment[0][0], segment[1][0]),
+      Math.max(segment[0][1], segment[1][1]),
+    ] as Bounds;
+
+    if (!doBoundsIntersect(b1, b2)) {
+      continue;
+    }
+
+    const hits = curveIntersectLineSegment(c, segment);
+
+    if (hits.length > 0) {
+      for (const j of hits) {
+        intersections.push(pointRotateRads(j, center, angle));
+      }
+
+      if (onlyFirst) {
+        return intersections;
+      }
+    }
+  }
+
+  return intersections;
+};
+
+const lineIntersections = (
+  lines: LineSegment<GlobalPoint>[],
+  segment: LineSegment<GlobalPoint>,
+  intersections: GlobalPoint[],
+  center: GlobalPoint,
+  angle: Radians,
+  onlyFirst = false,
+) => {
+  for (const l of lines) {
+    const intersection = lineSegmentIntersectionPoints(l, segment);
+    if (intersection) {
+      intersections.push(pointRotateRads(intersection, center, angle));
+
+      if (onlyFirst) {
+        return intersections;
+      }
+    }
+  }
+
+  return intersections;
+};
+
+const intersectLinearOrFreeDrawWithLineSegment = (
+  element: ExcalidrawLinearElement | ExcalidrawFreeDrawElement,
+  segment: LineSegment<GlobalPoint>,
+  elementsMap: ElementsMap,
+  onlyFirst = false,
+): GlobalPoint[] => {
+  // NOTE: This is the only one which return the decomposed elements
+  // rotated! This is due to taking advantage of roughjs definitions.
+  const [lines, curves] = deconstructLinearOrFreeDrawElement(
+    element,
+    elementsMap,
+  );
+  const intersections: GlobalPoint[] = [];
+
+  for (const l of lines) {
+    const intersection = lineSegmentIntersectionPoints(l, segment);
+    if (intersection) {
+      intersections.push(intersection);
+
+      if (onlyFirst) {
+        return intersections;
+      }
+    }
+  }
+
+  for (const c of curves) {
+    // Optimize by doing a cheap bounding box check first
+    const b1 = getCubicBezierCurveBound(c[0], c[1], c[2], c[3]);
+    const b2 = [
+      Math.min(segment[0][0], segment[1][0]),
+      Math.min(segment[0][1], segment[1][1]),
+      Math.max(segment[0][0], segment[1][0]),
+      Math.max(segment[0][1], segment[1][1]),
+    ] as Bounds;
+
+    if (!doBoundsIntersect(b1, b2)) {
+      continue;
+    }
+
+    const hits = curveIntersectLineSegment(c, segment, {
+      iterLimit: 10,
+    });
+
+    if (hits.length > 0) {
+      intersections.push(...hits);
+
+      if (onlyFirst) {
+        return intersections;
+      }
+    }
+  }
+
+  return intersections;
+};
+
+const intersectRectanguloidWithLineSegment = (
+  element: ExcalidrawRectanguloidElement,
+  elementsMap: ElementsMap,
+  segment: LineSegment<GlobalPoint>,
+  offset: number = 0,
+  onlyFirst = false,
+): GlobalPoint[] => {
+  const center = elementCenterPoint(element, elementsMap);
+  // To emulate a rotated rectangle we rotate the point in the inverse angle
+  // instead. It's all the same distance-wise.
+  const rotatedA = pointRotateRads<GlobalPoint>(
+    segment[0],
+    center,
+    -element.angle as Radians,
+  );
+  const rotatedB = pointRotateRads<GlobalPoint>(
+    segment[1],
+    center,
+    -element.angle as Radians,
+  );
+  const rotatedIntersector = lineSegment(rotatedA, rotatedB);
+
+  // Get the element's building components we can test against
+  const [sides, corners] = deconstructRectanguloidElement(element, offset);
+
+  const intersections: GlobalPoint[] = [];
+
+  lineIntersections(
+    sides,
+    rotatedIntersector,
+    intersections,
+    center,
+    element.angle,
+    onlyFirst,
+  );
+
+  if (onlyFirst && intersections.length > 0) {
+    return intersections;
+  }
+
+  curveIntersections(
+    corners,
+    rotatedIntersector,
+    intersections,
+    center,
+    element.angle,
+    onlyFirst,
+  );
+
+  return intersections;
+};
+
+/**
+ *
+ * @param element
+ * @param a
+ * @param b
+ * @returns
+ */
+const intersectDiamondWithLineSegment = (
+  element: ExcalidrawDiamondElement,
+  elementsMap: ElementsMap,
+  l: LineSegment<GlobalPoint>,
+  offset: number = 0,
+  onlyFirst = false,
+): GlobalPoint[] => {
+  const center = elementCenterPoint(element, elementsMap);
+
+  // Rotate the point to the inverse direction to simulate the rotated diamond
+  // points. It's all the same distance-wise.
+  const rotatedA = pointRotateRads(l[0], center, -element.angle as Radians);
+  const rotatedB = pointRotateRads(l[1], center, -element.angle as Radians);
+  const rotatedIntersector = lineSegment(rotatedA, rotatedB);
+
+  const [sides, corners] = deconstructDiamondElement(element, offset);
+  const intersections: GlobalPoint[] = [];
+
+  lineIntersections(
+    sides,
+    rotatedIntersector,
+    intersections,
+    center,
+    element.angle,
+    onlyFirst,
+  );
+
+  if (onlyFirst && intersections.length > 0) {
+    return intersections;
+  }
+
+  curveIntersections(
+    corners,
+    rotatedIntersector,
+    intersections,
+    center,
+    element.angle,
+    onlyFirst,
+  );
+
+  return intersections;
+};
+
+/**
+ *
+ * @param element
+ * @param a
+ * @param b
+ * @returns
+ */
+const intersectEllipseWithLineSegment = (
+  element: ExcalidrawEllipseElement,
+  elementsMap: ElementsMap,
+  l: LineSegment<GlobalPoint>,
+  offset: number = 0,
+): GlobalPoint[] => {
+  const center = elementCenterPoint(element, elementsMap);
+
+  const rotatedA = pointRotateRads(l[0], center, -element.angle as Radians);
+  const rotatedB = pointRotateRads(l[1], center, -element.angle as Radians);
+
+  return ellipseSegmentInterceptPoints(
+    ellipse(center, element.width / 2 + offset, element.height / 2 + offset),
+    lineSegment(rotatedA, rotatedB),
+  ).map((p) => pointRotateRads(p, center, element.angle));
+};
+
+/**
+ * Check if the given point is considered on the given shape's border
+ *
+ * @param point
+ * @param element
+ * @param tolerance
+ * @returns
+ */
+const isPointOnElementOutline = (
+  point: GlobalPoint,
+  element: ExcalidrawElement,
+  elementsMap: ElementsMap,
+  tolerance = 1,
+) => distanceToElement(element, elementsMap, point) <= tolerance;
+
+/**
+ * Check if the given point is considered inside the element's border
+ *
+ * @param point
+ * @param element
+ * @returns
+ */
+export const isPointInElement = (
+  point: GlobalPoint,
+  element: ExcalidrawElement,
+  elementsMap: ElementsMap,
+) => {
+  if (
+    (isLinearElement(element) || isFreeDrawElement(element)) &&
+    !isPathALoop(element.points)
+  ) {
+    // There isn't any "inside" for a non-looping path
+    return false;
+  }
+
+  const [x1, y1, x2, y2] = getElementBounds(element, elementsMap);
+
+  if (!isPointWithinBounds(pointFrom(x1, y1), point, pointFrom(x2, y2))) {
+    return false;
+  }
+
+  const center = pointFrom<GlobalPoint>((x1 + x2) / 2, (y1 + y2) / 2);
+  const otherPoint = pointFromVector(
+    vectorScale(
+      vectorNormalize(vectorFromPoint(point, center, 0.1)),
+      Math.max(element.width, element.height) * 2,
+    ),
+    center,
+  );
+  const intersector = lineSegment(point, otherPoint);
+  const intersections = intersectElementWithLineSegment(
+    element,
+    elementsMap,
+    intersector,
+  ).filter((p, pos, arr) => arr.findIndex((q) => pointsEqual(q, p)) === pos);
+
+  return intersections.length % 2 === 1;
+};
+
+export const isBindableElementInsideOtherBindable = (
+  innerElement: ExcalidrawBindableElement,
+  outerElement: ExcalidrawBindableElement,
+  elementsMap: ElementsMap,
+): boolean => {
+  // Get corner points of the inner element based on its type
+  const getCornerPoints = (
+    element: ExcalidrawElement,
+    offset: number,
+  ): GlobalPoint[] => {
+    const { x, y, width, height, angle } = element;
+    const center = elementCenterPoint(element, elementsMap);
+
+    if (element.type === "diamond") {
+      // Diamond has 4 corner points at the middle of each side
+      const [topX, topY, rightX, rightY, bottomX, bottomY, leftX, leftY] =
+        getDiamondPoints(element);
+      const corners: GlobalPoint[] = [
+        pointFrom(x + topX, y + topY - offset), // top
+        pointFrom(x + rightX + offset, y + rightY), // right
+        pointFrom(x + bottomX, y + bottomY + offset), // bottom
+        pointFrom(x + leftX - offset, y + leftY), // left
+      ];
+      return corners.map((corner) => pointRotateRads(corner, center, angle));
+    }
+    if (element.type === "ellipse") {
+      // For ellipse, test points at the extremes (top, right, bottom, left)
+      const cx = x + width / 2;
+      const cy = y + height / 2;
+      const rx = width / 2;
+      const ry = height / 2;
+      const corners: GlobalPoint[] = [
+        pointFrom(cx, cy - ry - offset), // top
+        pointFrom(cx + rx + offset, cy), // right
+        pointFrom(cx, cy + ry + offset), // bottom
+        pointFrom(cx - rx - offset, cy), // left
+      ];
+      return corners.map((corner) => pointRotateRads(corner, center, angle));
+    }
+    // Rectangle and other rectangular shapes (image, text, etc.)
+    const corners: GlobalPoint[] = [
+      pointFrom(x - offset, y - offset), // top-left
+      pointFrom(x + width + offset, y - offset), // top-right
+      pointFrom(x + width + offset, y + height + offset), // bottom-right
+      pointFrom(x - offset, y + height + offset), // bottom-left
+    ];
+    return corners.map((corner) => pointRotateRads(corner, center, angle));
+  };
+
+  const offset = (-1 * Math.max(innerElement.width, innerElement.height)) / 20; // 5% offset
+  const innerCorners = getCornerPoints(innerElement, offset);
+
+  // Check if all corner points of the inner element are inside the outer element
+  return innerCorners.every((corner) =>
+    isPointInElement(corner, outerElement, elementsMap),
+  );
+};

packages/element/src/comparisons.ts

@@ -0,0 +1,68 @@
+import type { ElementOrToolType } from "@excalidraw/excalidraw/types";
+
+export const hasBackground = (type: ElementOrToolType) =>
+  type === "rectangle" ||
+  type === "stickynote" ||
+  type === "iframe" ||
+  type === "embeddable" ||
+  type === "ellipse" ||
+  type === "diamond" ||
+  type === "line" ||
+  type === "freedraw" ||
+  type === "autoshape" ||
+  // tool-only type; makes the `G` background shortcut work for bucket fill
+  type === "bucketfill";
+
+export const hasFillStyle = (type: ElementOrToolType) =>
+  hasBackground(type) && type !== "stickynote";
+
+export const hasStrokeColor = (type: ElementOrToolType) =>
+  type === "rectangle" ||
+  type === "stickynote" ||
+  type === "ellipse" ||
+  type === "diamond" ||
+  type === "freedraw" ||
+  type === "arrow" ||
+  type === "line" ||
+  type === "text" ||
+  type === "embeddable" ||
+  type === "autoshape";
+
+export const hasStrokeWidth = (type: ElementOrToolType) =>
+  type === "rectangle" ||
+  type === "iframe" ||
+  type === "embeddable" ||
+  type === "ellipse" ||
+  type === "diamond" ||
+  type === "freedraw" ||
+  type === "arrow" ||
+  type === "line" ||
+  type === "autoshape";
+
+export const hasStrokeStyle = (type: ElementOrToolType) =>
+  type === "rectangle" ||
+  type === "iframe" ||
+  type === "embeddable" ||
+  type === "ellipse" ||
+  type === "diamond" ||
+  type === "arrow" ||
+  type === "line" ||
+  type === "autoshape";
+
+export const hasRoughness = (type: ElementOrToolType) =>
+  hasStrokeStyle(type) || type === "stickynote";
+
+export const hasFreedrawMode = (type: ElementOrToolType) => type === "freedraw";
+
+export const canChangeRoundness = (type: ElementOrToolType) =>
+  type === "rectangle" ||
+  type === "iframe" ||
+  type === "embeddable" ||
+  type === "line" ||
+  type === "diamond" ||
+  type === "stickynote" ||
+  type === "image";
+
+export const toolIsArrow = (type: ElementOrToolType) => type === "arrow";
+
+export const canHaveArrowheads = (type: ElementOrToolType) => type === "arrow";

packages/element/src/containerCache.ts

@@ -0,0 +1,33 @@
+import type { ExcalidrawTextContainer } from "./types";
+
+export const originalContainerCache: {
+  [id: ExcalidrawTextContainer["id"]]:
+    | {
+        height: ExcalidrawTextContainer["height"];
+      }
+    | undefined;
+} = {};
+
+export const updateOriginalContainerCache = (
+  id: ExcalidrawTextContainer["id"],
+  height: ExcalidrawTextContainer["height"],
+) => {
+  const data =
+    originalContainerCache[id] || (originalContainerCache[id] = { height });
+  data.height = height;
+  return data;
+};
+
+export const resetOriginalContainerCache = (
+  id: ExcalidrawTextContainer["id"],
+) => {
+  if (originalContainerCache[id]) {
+    delete originalContainerCache[id];
+  }
+};
+
+export const getOriginalContainerHeightFromCache = (
+  id: ExcalidrawTextContainer["id"],
+) => {
+  return originalContainerCache[id]?.height ?? null;
+};

packages/element/src/convertToShape.ts

@@ -0,0 +1,821 @@
+import {
+  getBoundsFromPoints,
+  getElementAbsoluteCoords,
+} from "@excalidraw/element/bounds";
+import {
+  newArrowElement,
+  newElement,
+  newLinearElement,
+} from "@excalidraw/element/newElement";
+import {
+  ELEMENT_PENDING_DRAW_SHAPE_OPACITY,
+  getStrokeWidthByKey,
+  ROUNDNESS,
+} from "@excalidraw/common";
+import {
+  convexHull,
+  distanceToLineSegment,
+  elongation,
+  kurtosis,
+  lineSegment,
+  orientPrincipalAxes,
+  pointFrom,
+  polygonArea,
+  principalAxes,
+  principalCoords,
+  skewness,
+} from "@excalidraw/math";
+
+import type { App, AppState } from "@excalidraw/excalidraw/types";
+
+import type { LocalPoint, GlobalPoint, Radians } from "@excalidraw/math";
+import type { Bounds } from "@excalidraw/common";
+import type {
+  ExcalidrawArrowElement,
+  ExcalidrawDiamondElement,
+  ExcalidrawElement,
+  ExcalidrawEllipseElement,
+  ExcalidrawFreeDrawElement,
+  ExcalidrawFrameLikeElement,
+  ExcalidrawRectangleElement,
+  ElementsMap,
+  ExcalidrawNonSelectionElement,
+  NonDeletedExcalidrawElement,
+  NonDeleted,
+  ExcalidrawLineElement,
+} from "@excalidraw/element/types";
+
+import { getFrameLikeElements } from "./frame";
+import {
+  isLinearElement,
+  isLineElement,
+  isUsingAdaptiveRadius,
+} from "./typeChecks";
+import { LinearElementEditor } from "./linearElementEditor";
+
+declare global {
+  interface Window {
+    LAST_POINTS?: readonly GlobalPoint[];
+  }
+}
+
+// A moment-based shape recognizer.
+//
+// NOTE: Rectangle vs. diamond is deliberately *not* rotation invariant. A 45
+// rectangle = diamond.
+
+type NonDeletedRecognizedShapeElement = NonDeleted<
+  | ExcalidrawRectangleElement
+  | ExcalidrawEllipseElement
+  | ExcalidrawDiamondElement
+  | ExcalidrawArrowElement
+  | ExcalidrawLineElement
+  | ExcalidrawFreeDrawElement
+>;
+
+type Shape = NonDeletedRecognizedShapeElement["type"];
+
+interface ShapeRecognitionResult<P extends LocalPoint | GlobalPoint> {
+  // The type of the recognized shape, or "freedraw" if no good match was found
+  type: Shape;
+
+  // The original input points (not simplified)
+  points: readonly P[];
+
+  // Bounding box of the original input points, used for positioning the
+  // converted shape
+  boundingBox: Bounds;
+}
+
+// Number of points every stroke is resampled to before feature extraction.
+const RESAMPLE_N = 64;
+
+// Minimum apparent (on-screen) size of a stroke's larger bounding-box
+// dimension, in pixels, for recognition to run — below this the stroke reads
+// as an accidental scribble. Compared against `sceneSize * zoom` so the same
+// physical gesture behaves the same at every zoom level.
+//
+// Maximum not required. Runtime is O(point count), points come in at roughly
+// one per frame.
+const RECOGNITION_MIN_SCREEN_SIZE = 25;
+
+// A stroke whose endpoints are farther apart than this fraction of its own
+// path length is treated as open (a line or an arrow) rather than closed (a
+// rectangle, diamond or ellipse).
+const CLOSED_GAP_MAX_RATIO = 0.15;
+
+// Maximum elongation for an open stroke to count as straight.
+const LINEAR_MAX_ELONGATION = 0.25;
+
+// Fraction of the start→tip distance around the tip inside which an arrowhead
+// may live: points there are exempt from the shaft straightness check.
+const ARROWHEAD_ZONE_RATIO = 0.5;
+
+// Maximum distance any point outside the arrowhead zone may stray from the
+// start→tip chord, as a fraction of the chord length. Loose enough for a lazy
+// bow or a small squiggle, tight enough to reject elbows, arcs and sawtooths
+// that only *statistically* look straight (their point-cloud elongation
+// passes, their geometry doesn't).
+const LINEAR_MAX_SHAFT_DEVIATION = 0.15;
+
+// Minimum |skew| along the major axis for an open, straight stroke to be an
+// arrow rather than a plain line. Arrowhead add "mass" -> skews that way.
+const ARROW_MIN_SKEW = 0.3;
+
+// Maximum feature-space distance to a shape prototype, in units of the
+// per-feature tolerances in CLOSED_SHAPE_PROTOTYPES. Beyond this the stroke is
+// not enough like any known shape and stays freedraw.
+const CLOSED_SHAPE_MAX_DISTANCE = 1.5;
+
+// Half-width, in resampled points, of the chord window used to measure local
+// turning along the stroke. Wide enough to smooth pen wobble, narrow enough
+// that adjacent corners of a small quadrilateral stay separate peaks.
+const TURN_WINDOW = 3;
+
+// =============================================================================
+// Feature extraction
+// =============================================================================
+
+// Resample `pts` to exactly `n` evenly-spaced points along the stroke path.
+function resample<P extends LocalPoint | GlobalPoint>(
+  pts: readonly P[],
+  n: number,
+): P[] {
+  let totalLen = 0;
+  for (let i = 1; i < pts.length; i++) {
+    totalLen += Math.hypot(
+      pts[i][0] - pts[i - 1][0],
+      pts[i][1] - pts[i - 1][1],
+    );
+  }
+
+  const interval = totalLen / (n - 1);
+  let accumulated = 0;
+  const result: P[] = [pts[0]];
+  let prev = pts[0];
+
+  for (let i = 1; i < pts.length; i++) {
+    const curr = pts[i];
+    const segLen = Math.hypot(curr[0] - prev[0], curr[1] - prev[1]);
+    if (accumulated + segLen >= interval) {
+      // Insert interpolated points within this segment
+      let remaining = interval - accumulated;
+      while (remaining <= segLen + 1e-10) {
+        const t = remaining / segLen;
+        const newPt: P = [
+          prev[0] + t * (curr[0] - prev[0]),
+          prev[1] + t * (curr[1] - prev[1]),
+        ] as P;
+        result.push(newPt);
+        if (result.length === n) {
+          return result;
+        }
+        prev = newPt;
+        accumulated = 0;
+        remaining += interval;
+      }
+      accumulated = segLen - (remaining - interval);
+    } else {
+      accumulated += segLen;
+    }
+    prev = curr;
+  }
+
+  // Fill any remaining slots with the last point (rounding errors)
+  while (result.length < n) {
+    result.push(pts[pts.length - 1]);
+  }
+  return result;
+}
+
+// Statistical description of a stroke, in terms that don't depend on where,
+// how big, or (except where noted) how rotated it was drawn.
+interface StrokeFeatures {
+  // Straight-line distance between the endpoints over the stroke's own path
+  // length. ~0 when the stroke returns to its start.
+  gapRatio: number;
+
+  // Point cloud elongation along the major axis.
+  elongation: number;
+
+  // Skew of the points projected onto the major axis. Signed so that it is
+  // <= 0 by construction.
+  majorSkew: number;
+
+  // Convex hull area over axis-aligned bounding box area, in the screen
+  // frame: ~1 for a rectangle, ~PI/4 for an ellipse, ~1/2 for a diamond.
+  hullFillRatio: number;
+
+  // Share of the stroke's total turning concentrated in its 4 strongest
+  // corner loci: ~1 for any quadrilateral — however tapered or slanted, all
+  // turning happens at the corners — vs. ~0.5 for an ellipse, whose turning
+  // is spread along the whole outline. This is what tells a sloppy,
+  // trapezoid-ish rectangle (hull fill ≈ PI/4, same as an ellipse's) from an
+  // actual ellipse: sharp corners.
+  cornerTurnShare: number;
+
+  // kurtosis along x times kurtosis along y, in the screen frame. The two
+  // factors each vary with the aspect ratio, but their product barely does:
+  // ~1.83 for any rectangle, 2.25 for any ellipse, 3.24 for any diamond.
+  kurtosisProduct: number;
+
+  // How far the stroke strays from the straight chord between its start and
+  // its farthest point ("tip"), as a fraction of that chord's length — points
+  // within ARROWHEAD_ZONE_RATIO of the tip are exempt, so an arrowhead
+  // doesn't count as straying. ~0 for a line or arrow however wobbly, large
+  // for elbows, arcs and sawtooths, whose point-cloud statistics alone can
+  // still look line-like.
+  shaftDeviationRatio: number;
+}
+
+// See StrokeFeatures.shaftDeviationRatio.
+function shaftDeviationRatio<P extends LocalPoint | GlobalPoint>(
+  pts: readonly P[],
+): number {
+  const start = pts[0];
+  let tip = start;
+  let tipDistance = 0;
+  for (const point of pts) {
+    const distance = Math.hypot(point[0] - start[0], point[1] - start[1]);
+    if (distance > tipDistance) {
+      tipDistance = distance;
+      tip = point;
+    }
+  }
+  if (tipDistance === 0) {
+    return 0;
+  }
+
+  const chord = lineSegment(start, tip);
+  let maxDeviation = 0;
+  for (const point of pts) {
+    const tipDist = Math.hypot(point[0] - tip[0], point[1] - tip[1]);
+    if (tipDist <= ARROWHEAD_ZONE_RATIO * tipDistance) {
+      continue;
+    }
+    maxDeviation = Math.max(maxDeviation, distanceToLineSegment(point, chord));
+  }
+  return maxDeviation / tipDistance;
+}
+
+// The turn angle at every resampled point, measured between the incoming and
+// outgoing chords `TURN_WINDOW` points away. The stroke is deliberately NOT
+// treated as a closed loop: wrapping around would let the closure artifacts of
+// a hand-drawn outline (overshooting or undershooting the starting point)
+// fabricate a sharp corner that was never drawn.
+function windowedTurns<P extends LocalPoint | GlobalPoint>(
+  pts: readonly P[],
+): number[] {
+  const turns: number[] = [];
+  for (let i = TURN_WINDOW; i < pts.length - TURN_WINDOW; i++) {
+    const [ax, ay] = pts[i - TURN_WINDOW];
+    const [bx, by] = pts[i];
+    const [cx, cy] = pts[i + TURN_WINDOW];
+    const v1x = bx - ax;
+    const v1y = by - ay;
+    const v2x = cx - bx;
+    const v2y = cy - by;
+    turns.push(
+      Math.abs(Math.atan2(v1x * v2y - v1y * v2x, v1x * v2x + v1y * v2y)),
+    );
+  }
+  return turns;
+}
+
+// See StrokeFeatures.cornerTurnShare. Greedily picks the 4 strongest turn
+// peaks, each absorbing its ±TURN_WINDOW neighborhood so one physical corner
+// (whose turn smears across the window) counts once.
+function cornerTurnShare<P extends LocalPoint | GlobalPoint>(
+  pts: readonly P[],
+): number {
+  const turns = windowedTurns(pts);
+  const total = turns.reduce((sum, turn) => sum + turn, 0);
+  if (total === 0) {
+    return 0;
+  }
+
+  const taken = new Array<boolean>(turns.length).fill(false);
+  let top4 = 0;
+  for (let corner = 0; corner < 4; corner++) {
+    let peak = -1;
+    let peakTurn = 0;
+    for (let i = 0; i < turns.length; i++) {
+      if (!taken[i] && turns[i] > peakTurn) {
+        peakTurn = turns[i];
+        peak = i;
+      }
+    }
+    if (peak < 0) {
+      break;
+    }
+    for (let i = peak - TURN_WINDOW; i <= peak + TURN_WINDOW; i++) {
+      if (i >= 0 && i < turns.length && !taken[i]) {
+        top4 += turns[i];
+        taken[i] = true;
+      }
+    }
+  }
+  return top4 / total;
+}
+
+function extractFeatures<P extends LocalPoint | GlobalPoint>(
+  points: readonly P[],
+): StrokeFeatures {
+  // Resample first: features are moments of the point set, so they would
+  // otherwise be biased by pointer speed, which crowds samples wherever the
+  // user drew slowly.
+  const pts = resample(points, RESAMPLE_N);
+
+  let pathLength = 0;
+  for (let i = 1; i < pts.length; i++) {
+    pathLength += Math.hypot(
+      pts[i][0] - pts[i - 1][0],
+      pts[i][1] - pts[i - 1][1],
+    );
+  }
+  const gap = Math.hypot(
+    pts[pts.length - 1][0] - pts[0][0],
+    pts[pts.length - 1][1] - pts[0][1],
+  );
+
+  const axes = orientPrincipalAxes(pts, principalAxes(pts));
+  const majorProjection = principalCoords(pts, axes).map(([u]) => u);
+
+  const hull = convexHull(pts);
+  const [minX, minY, maxX, maxY] = getBoundsFromPoints(pts);
+  const boxArea = (maxX - minX) * (maxY - minY);
+
+  return {
+    gapRatio: pathLength > 0 ? gap / pathLength : 0,
+    elongation: elongation(axes),
+    majorSkew: skewness(majorProjection),
+    hullFillRatio: boxArea > 0 ? polygonArea(hull) / boxArea : 0,
+    cornerTurnShare: cornerTurnShare(pts),
+    kurtosisProduct:
+      kurtosis(pts.map(([x]) => x)) * kurtosis(pts.map(([, y]) => y)),
+    shaftDeviationRatio: shaftDeviationRatio(pts),
+  };
+}
+
+// =============================================================================
+// Classification
+// =============================================================================
+
+const CLOSED_SHAPE_PROTOTYPES: readonly {
+  type: Shape;
+  hullFillRatio: number;
+  cornerTurnShare: number;
+  kurtosisProduct: number;
+}[] = [
+  {
+    type: "rectangle",
+    hullFillRatio: 1,
+    cornerTurnShare: 0.95,
+    kurtosisProduct: 1.83,
+  },
+  {
+    type: "diamond",
+    hullFillRatio: 0.5,
+    cornerTurnShare: 0.95,
+    kurtosisProduct: 3.24,
+  },
+  {
+    type: "ellipse",
+    hullFillRatio: Math.PI / 4,
+    cornerTurnShare: 0.55,
+    kurtosisProduct: 2.25,
+  },
+];
+
+// Hull fill no longer has to separate rectangles from ellipses on its own
+// (cornerTurnShare carries that), so it can afford the slack that lets a
+// tapered, hand-drawn quadrilateral (fill ≈ 0.8) still read as a rectangle.
+const HULL_FILL_RATIO_TOLERANCE = 0.2;
+const CORNER_TURN_SHARE_TOLERANCE = 0.2;
+const KURTOSIS_PRODUCT_TOLERANCE = 0.7;
+
+// Pick the closed shape whose prototype the stroke's features sit closest to,
+// or freedraw when even the nearest one is too far away.
+function classifyClosedStroke(features: StrokeFeatures): Shape {
+  let best: Shape = "freedraw";
+  let bestDistance = CLOSED_SHAPE_MAX_DISTANCE;
+
+  for (const prototype of CLOSED_SHAPE_PROTOTYPES) {
+    const distance = Math.hypot(
+      (features.hullFillRatio - prototype.hullFillRatio) /
+        HULL_FILL_RATIO_TOLERANCE,
+      (features.cornerTurnShare - prototype.cornerTurnShare) /
+        CORNER_TURN_SHARE_TOLERANCE,
+      (features.kurtosisProduct - prototype.kurtosisProduct) /
+        KURTOSIS_PRODUCT_TOLERANCE,
+    );
+
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = prototype.type;
+    }
+  }
+
+  return best;
+}
+
+// An open stroke is a line or an arrow, provided it is straight enough; the
+// arrowhead is what makes the point distribution lopsided.
+function classifyOpenStroke(features: StrokeFeatures): Shape {
+  if (
+    features.elongation > LINEAR_MAX_ELONGATION ||
+    features.shaftDeviationRatio > LINEAR_MAX_SHAFT_DEVIATION
+  ) {
+    return "freedraw";
+  }
+  return Math.abs(features.majorSkew) >= ARROW_MIN_SKEW ? "arrow" : "line";
+}
+
+function classify(features: StrokeFeatures): Shape {
+  return features.gapRatio > CLOSED_GAP_MAX_RATIO
+    ? classifyOpenStroke(features)
+    : classifyClosedStroke(features);
+}
+
+// Arrow endpoint selection
+
+// When an arrow is recognized, the original input's last point may not
+// correspond to the actual arrow tip. The tip must lie on the bounding-box
+// perimeter and is the perimeter point farthest from the start (first input
+// point). We find the closest original input point to that ideal tip.
+function getArrowEndpoint<P extends LocalPoint | GlobalPoint>(
+  points: readonly P[],
+  boundingBox: Bounds,
+  startPoint: P,
+): P {
+  const [minX, minY, maxX, maxY] = boundingBox;
+  const w = maxX - minX;
+  const h = maxY - minY;
+
+  // Degenerate bounding box – fall back to last point
+  if (w === 0 && h === 0) {
+    return points[points.length - 1];
+  }
+
+  // Perimeter corners / edge points to check (4 corners + 4 edge midpoints
+  // give good coverage of the perimeter).
+  const perimeterPoints: LocalPoint[] = [
+    pointFrom(minX, minY),
+    pointFrom((minX + maxX) / 2, minY),
+    pointFrom(maxX, minY),
+    pointFrom(maxX, (minY + maxY) / 2),
+    pointFrom(maxX, maxY),
+    pointFrom((minX + maxX) / 2, maxY),
+    pointFrom(minX, maxY),
+    pointFrom(minX, (minY + maxY) / 2),
+  ];
+
+  // Ideal endpoint = perimeter point farthest from start.
+  let idealDist = -1;
+  let idealEndpoint: LocalPoint = pointFrom(maxX, maxY);
+  for (const pp of perimeterPoints) {
+    const d = Math.hypot(pp[0] - startPoint[0], pp[1] - startPoint[1]);
+    if (d > idealDist) {
+      idealDist = d;
+      idealEndpoint = pp;
+    }
+  }
+
+  // Find the original input point closest to the ideal endpoint.
+  let bestDist = Infinity;
+  let bestPoint: P = points[points.length - 1];
+  for (const pt of points) {
+    const d = Math.hypot(pt[0] - idealEndpoint[0], pt[1] - idealEndpoint[1]);
+    if (d < bestDist) {
+      bestDist = d;
+      bestPoint = pt;
+    }
+  }
+  return bestPoint;
+}
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+// Recognizes common shapes from free-draw input points
+export const recognizeShape = <P extends LocalPoint | GlobalPoint>(
+  points: P[],
+  previousElement: ExcalidrawElement | null,
+  zoom: number = 1,
+): ShapeRecognitionResult<P> => {
+  // DEBUG (will be removed lated)
+  if (typeof window !== "undefined") {
+    window.LAST_POINTS = points.map(([x, y]) => pointFrom<GlobalPoint>(x, y));
+  }
+
+  const boundingBox = getBoundsFromPoints(points);
+
+  const [minX, minY, maxX, maxY] = boundingBox;
+  const maxDim = Math.max(maxX - minX, maxY - minY);
+  if (points.length < 3 || maxDim * zoom < RECOGNITION_MIN_SCREEN_SIZE) {
+    return { type: "freedraw", points, boundingBox };
+  }
+
+  const recognized = classify(extractFeatures(points));
+  const type =
+    previousElement?.type === "arrow" && recognized !== "arrow"
+      ? "freedraw"
+      : recognized;
+
+  return { type, points, boundingBox };
+};
+
+// Converts a freedraw element to the detected shape.
+//
+// `frames` lets callers pass the scene's cached frame-like elements (e.g.
+// scene.getNonDeletedFramesLikes()) to avoid spreading and re-filtering the
+// whole element map on every invocation; when omitted it is derived from
+// `elementsMap`.
+export const convertToShape = (
+  points: GlobalPoint[],
+  appState: AppState,
+  elementsMap: ElementsMap,
+  previousElement: ExcalidrawElement | null,
+  frames?: readonly ExcalidrawFrameLikeElement[],
+): NonDeletedRecognizedShapeElement | undefined => {
+  const recognizedShape = recognizeShape(
+    points,
+    previousElement,
+    appState.zoom.value,
+  );
+
+  const boundingBox = recognizedShape.boundingBox;
+  const [minX, minY, maxX, maxY] = boundingBox;
+
+  const frameLikeElements =
+    frames ?? getFrameLikeElements([...elementsMap.values()]);
+  const frameId =
+    frameLikeElements.find((frame) => {
+      const [fx1, fy1, fx2, fy2] = getElementAbsoluteCoords(frame, elementsMap);
+      return fx1 <= minX && fy1 <= minY && fx2 >= maxX && fy2 >= maxY;
+    })?.id ?? null;
+
+  const roundness =
+    appState.currentItemRoundness === "round"
+      ? {
+          type: isUsingAdaptiveRadius(recognizedShape.type)
+            ? ROUNDNESS.ADAPTIVE_RADIUS
+            : ROUNDNESS.PROPORTIONAL_RADIUS,
+        }
+      : null;
+
+  switch (recognizedShape.type) {
+    case "rectangle":
+    case "diamond":
+    case "ellipse": {
+      return newElement({
+        type: recognizedShape.type,
+        x: recognizedShape.boundingBox[0],
+        y: recognizedShape.boundingBox[1],
+        width: recognizedShape.boundingBox[2] - recognizedShape.boundingBox[0],
+        height: recognizedShape.boundingBox[3] - recognizedShape.boundingBox[1],
+        groupIds: [],
+        angle: 0 as Radians,
+        frameId,
+        roundness,
+        roughness: appState.currentItemRoughness,
+        backgroundColor: appState.currentItemBackgroundColor,
+        strokeColor: appState.currentItemStrokeColor,
+        fillStyle: appState.currentItemFillStyle,
+        opacity: appState.currentItemOpacity,
+        strokeStyle: appState.currentItemStrokeStyle,
+        strokeWidth: getStrokeWidthByKey(
+          recognizedShape.type,
+          appState.currentItemStrokeWidthKey,
+        ),
+      }) as NonDeletedRecognizedShapeElement;
+    }
+    case "arrow": {
+      const [arrowX, arrowY] = recognizedShape.points[0];
+
+      const [globalEndX, globalEndY] = getArrowEndpoint(
+        recognizedShape.points,
+        recognizedShape.boundingBox,
+        recognizedShape.points[0],
+      );
+      const endPoint: LocalPoint = pointFrom<LocalPoint>(
+        globalEndX - arrowX,
+        globalEndY - arrowY,
+      );
+      const arrowLen = Math.hypot(
+        globalEndX - recognizedShape.points[0][0],
+        globalEndY - recognizedShape.points[0][1],
+      );
+      if (arrowLen < 60) {
+        const tempElement = newLinearElement({
+          type: "line",
+          x: arrowX,
+          y: arrowY,
+          points: [
+            pointFrom<LocalPoint>(
+              recognizedShape.points[0][0] - arrowX,
+              recognizedShape.points[0][1] - arrowY,
+            ),
+            endPoint,
+          ],
+          groupIds: [],
+          frameId,
+          locked: false,
+          angle: 0 as Radians,
+          roundness,
+          roughness: appState.currentItemRoughness,
+          backgroundColor: appState.currentItemBackgroundColor,
+          strokeColor: appState.currentItemStrokeColor,
+          fillStyle: appState.currentItemFillStyle,
+          opacity: appState.currentItemOpacity,
+          strokeStyle: appState.currentItemStrokeStyle,
+          strokeWidth: getStrokeWidthByKey(
+            recognizedShape.type,
+            appState.currentItemStrokeWidthKey,
+          ),
+        });
+
+        const normalized =
+          LinearElementEditor.getNormalizeElementPointsAndCoords(tempElement);
+
+        return newLinearElement({
+          ...tempElement,
+          ...normalized,
+        }) as NonDeletedRecognizedShapeElement;
+      }
+      const tempElement = newArrowElement({
+        type: "arrow",
+        x: arrowX,
+        y: arrowY,
+        startArrowhead: appState.currentItemStartArrowhead,
+        endArrowhead: appState.currentItemEndArrowhead,
+        points: [
+          pointFrom<LocalPoint>(
+            recognizedShape.points[0][0] - arrowX,
+            recognizedShape.points[0][1] - arrowY,
+          ),
+          endPoint,
+        ],
+        groupIds: [],
+        frameId,
+        locked: false,
+        angle: 0 as Radians,
+        roundness,
+        roughness: appState.currentItemRoughness,
+        backgroundColor: appState.currentItemBackgroundColor,
+        strokeColor: appState.currentItemStrokeColor,
+        fillStyle: appState.currentItemFillStyle,
+        opacity: appState.currentItemOpacity,
+        strokeStyle: appState.currentItemStrokeStyle,
+        strokeWidth: getStrokeWidthByKey(
+          recognizedShape.type,
+          appState.currentItemStrokeWidthKey,
+        ),
+      });
+
+      const normalized =
+        LinearElementEditor.getNormalizeElementPointsAndCoords(tempElement);
+
+      return newArrowElement({
+        ...tempElement,
+        ...normalized,
+      });
+    }
+    case "line": {
+      const [lineX, lineY] = recognizedShape.points[0];
+      const endPoint =
+        recognizedShape.points[recognizedShape.points.length - 1];
+      const tempElement = newLinearElement({
+        type: recognizedShape.type,
+        x: lineX,
+        y: lineY,
+        points: [
+          pointFrom<LocalPoint>(
+            recognizedShape.points[0][0] - lineX,
+            recognizedShape.points[0][1] - lineY,
+          ),
+          pointFrom<LocalPoint>(endPoint[0] - lineX, endPoint[1] - lineY),
+        ],
+        groupIds: [],
+        frameId,
+        locked: false,
+        angle: 0 as Radians,
+        roundness,
+        roughness: appState.currentItemRoughness,
+        backgroundColor: appState.currentItemBackgroundColor,
+        strokeColor: appState.currentItemStrokeColor,
+        fillStyle: appState.currentItemFillStyle,
+        opacity: appState.currentItemOpacity,
+        strokeStyle: appState.currentItemStrokeStyle,
+        strokeWidth: getStrokeWidthByKey(
+          recognizedShape.type,
+          appState.currentItemStrokeWidthKey,
+        ),
+      });
+
+      const normalized =
+        LinearElementEditor.getNormalizeElementPointsAndCoords(tempElement);
+
+      return newLinearElement({
+        ...tempElement,
+        ...normalized,
+      }) as NonDeletedRecognizedShapeElement;
+    }
+  }
+
+  return undefined;
+};
+
+// Whether two drawShape preview elements are visually identical, so a redundant
+// preview recompute on pointermove can skip setState (avoiding a no-op React
+// re-render and roughjs shape regeneration).
+const isDrawShapePreviewEqual = (
+  a: NonDeletedExcalidrawElement | null,
+  b: NonDeletedExcalidrawElement,
+): boolean => {
+  if (
+    !a ||
+    a.type !== b.type ||
+    a.x !== b.x ||
+    a.y !== b.y ||
+    a.width !== b.width ||
+    a.height !== b.height ||
+    a.angle !== b.angle
+  ) {
+    return false;
+  }
+  if (isLinearElement(a) && isLinearElement(b)) {
+    if (a.points.length !== b.points.length) {
+      return false;
+    }
+    for (let i = 0; i < a.points.length; i++) {
+      if (
+        a.points[i][0] !== b.points[i][0] ||
+        a.points[i][1] !== b.points[i][1]
+      ) {
+        return false;
+      }
+    }
+  }
+  return true;
+};
+
+// Append to the trail and recompute the shape preview. This runs inside
+// withBatchedUpdatesThrottled (throttleRAF), so it fires at most once per
+// animation frame regardless of raw pointermove rate.
+export const convertToShapeHandlePointerMoveFromPointerDown = (
+  app: App,
+  pointerCoords: { x: number; y: number },
+) => {
+  if (app.state.activeTool.type === "autoshape") {
+    app.drawShape.trail.addPointToPath(pointerCoords.x, pointerCoords.y);
+
+    const drawShapeTrailPoints = app.drawShape.trail.getCurrentPoints();
+    // note: size gate inside recognizeShape
+    if (drawShapeTrailPoints.length >= 3) {
+      const shapePreview = convertToShape(
+        drawShapeTrailPoints,
+        app.state,
+        app.scene.getNonDeletedElementsMap(),
+        app.state.newElement,
+        app.scene.getNonDeletedFramesLikes(),
+      ) as ExcalidrawNonSelectionElement | undefined;
+
+      // Lines get no live preview — nearly every stroke reads as a line at
+      // some early point, so previewing them is mostly flicker. Releasing
+      // still commits the line: finalize() re-recognizes from the trail when
+      // no preview exists.
+      if (shapePreview && !isLineElement(shapePreview)) {
+        const prevPreview = app.state.newElement;
+        const nextPreview = {
+          ...shapePreview,
+          // Keep a stable id across the gesture while the recognized type
+          // is unchanged, so the preview element's identity doesn't churn
+          // frame to frame.
+          id:
+            prevPreview?.type === shapePreview.type
+              ? prevPreview.id
+              : shapePreview.id,
+          created:
+            prevPreview?.type === shapePreview.type
+              ? prevPreview.created
+              : shapePreview.created,
+          seed: 1,
+          opacity: ELEMENT_PENDING_DRAW_SHAPE_OPACITY,
+          isDeleted: false as const,
+        } as NonDeletedRecognizedShapeElement;
+
+        if (!isDrawShapePreviewEqual(prevPreview, nextPreview)) {
+          app.setState({ newElement: nextPreview });
+        }
+      } else if (app.state.newElement !== null) {
+        app.setState({ newElement: null });
+      }
+    }
+
+    return true;
+  }
+
+  return false;
+};

packages/element/src/cropElement.ts

@@ -0,0 +1,628 @@
+import {
+  type Radians,
+  pointFrom,
+  pointCenter,
+  pointRotateRads,
+  vectorFromPoint,
+  vectorNormalize,
+  vectorSubtract,
+  vectorAdd,
+  vectorScale,
+  pointFromVector,
+  clamp,
+  isCloseTo,
+} from "@excalidraw/math";
+import { type Point } from "points-on-curve";
+
+import {
+  elementCenterPoint,
+  getElementAbsoluteCoords,
+  getResizedElementAbsoluteCoords,
+} from "./bounds";
+
+import type { TransformHandleType } from "./transformHandles";
+import type {
+  ElementsMap,
+  ExcalidrawElement,
+  ExcalidrawImageElement,
+  ImageCrop,
+} from "./types";
+
+export const MINIMAL_CROP_SIZE = 10;
+
+export const cropElement = (
+  element: ExcalidrawImageElement,
+  elementsMap: ElementsMap,
+  transformHandle: TransformHandleType,
+  naturalWidth: number,
+  naturalHeight: number,
+  pointerX: number,
+  pointerY: number,
+  widthAspectRatio?: number,
+) => {
+  const { width: uncroppedWidth, height: uncroppedHeight } =
+    getUncroppedWidthAndHeight(element);
+
+  const naturalWidthToUncropped = naturalWidth / uncroppedWidth;
+  const naturalHeightToUncropped = naturalHeight / uncroppedHeight;
+
+  const croppedLeft = (element.crop?.x ?? 0) / naturalWidthToUncropped;
+  const croppedTop = (element.crop?.y ?? 0) / naturalHeightToUncropped;
+
+  /**
+   *      uncropped width
+   * *––––––––––––––––––––––––*
+   * |     (x,y) (natural)    |
+   * |       *–––––––*        |
+   * |       |///////| height | uncropped height
+   * |       *–––––––*        |
+   * |    width (natural)     |
+   * *––––––––––––––––––––––––*
+   */
+
+  const rotatedPointer = pointRotateRads(
+    pointFrom(pointerX, pointerY),
+    elementCenterPoint(element, elementsMap),
+    -element.angle as Radians,
+  );
+
+  pointerX = rotatedPointer[0];
+  pointerY = rotatedPointer[1];
+
+  let nextWidth = element.width;
+  let nextHeight = element.height;
+
+  let crop: ImageCrop | null = element.crop ?? {
+    x: 0,
+    y: 0,
+    width: naturalWidth,
+    height: naturalHeight,
+    naturalWidth,
+    naturalHeight,
+  };
+
+  const previousCropHeight = crop.height;
+  const previousCropWidth = crop.width;
+
+  const isFlippedByX = element.scale[0] === -1;
+  const isFlippedByY = element.scale[1] === -1;
+
+  let changeInHeight = pointerY - element.y;
+  let changeInWidth = pointerX - element.x;
+
+  if (transformHandle.includes("n")) {
+    nextHeight = clamp(
+      element.height - changeInHeight,
+      MINIMAL_CROP_SIZE,
+      isFlippedByY ? uncroppedHeight - croppedTop : element.height + croppedTop,
+    );
+  }
+
+  if (transformHandle.includes("s")) {
+    changeInHeight = pointerY - element.y - element.height;
+    nextHeight = clamp(
+      element.height + changeInHeight,
+      MINIMAL_CROP_SIZE,
+      isFlippedByY ? element.height + croppedTop : uncroppedHeight - croppedTop,
+    );
+  }
+
+  if (transformHandle.includes("e")) {
+    changeInWidth = pointerX - element.x - element.width;
+
+    nextWidth = clamp(
+      element.width + changeInWidth,
+      MINIMAL_CROP_SIZE,
+      isFlippedByX ? element.width + croppedLeft : uncroppedWidth - croppedLeft,
+    );
+  }
+
+  if (transformHandle.includes("w")) {
+    nextWidth = clamp(
+      element.width - changeInWidth,
+      MINIMAL_CROP_SIZE,
+      isFlippedByX ? uncroppedWidth - croppedLeft : element.width + croppedLeft,
+    );
+  }
+
+  const updateCropWidthAndHeight = (crop: ImageCrop) => {
+    crop.height = nextHeight * naturalHeightToUncropped;
+    crop.width = nextWidth * naturalWidthToUncropped;
+  };
+
+  updateCropWidthAndHeight(crop);
+
+  const adjustFlipForHandle = (
+    handle: TransformHandleType,
+    crop: ImageCrop,
+  ) => {
+    updateCropWidthAndHeight(crop);
+    if (handle.includes("n")) {
+      if (!isFlippedByY) {
+        crop.y += previousCropHeight - crop.height;
+      }
+    }
+    if (handle.includes("s")) {
+      if (isFlippedByY) {
+        crop.y += previousCropHeight - crop.height;
+      }
+    }
+    if (handle.includes("e")) {
+      if (isFlippedByX) {
+        crop.x += previousCropWidth - crop.width;
+      }
+    }
+    if (handle.includes("w")) {
+      if (!isFlippedByX) {
+        crop.x += previousCropWidth - crop.width;
+      }
+    }
+  };
+
+  switch (transformHandle) {
+    case "n": {
+      if (widthAspectRatio) {
+        const distanceToLeft = croppedLeft + element.width / 2;
+        const distanceToRight =
+          uncroppedWidth - croppedLeft - element.width / 2;
+
+        const MAX_WIDTH = Math.min(distanceToLeft, distanceToRight) * 2;
+
+        nextWidth = clamp(
+          nextHeight * widthAspectRatio,
+          MINIMAL_CROP_SIZE,
+          MAX_WIDTH,
+        );
+        nextHeight = nextWidth / widthAspectRatio;
+      }
+
+      adjustFlipForHandle(transformHandle, crop);
+
+      if (widthAspectRatio) {
+        crop.x += (previousCropWidth - crop.width) / 2;
+      }
+
+      break;
+    }
+    case "s": {
+      if (widthAspectRatio) {
+        const distanceToLeft = croppedLeft + element.width / 2;
+        const distanceToRight =
+          uncroppedWidth - croppedLeft - element.width / 2;
+
+        const MAX_WIDTH = Math.min(distanceToLeft, distanceToRight) * 2;
+
+        nextWidth = clamp(
+          nextHeight * widthAspectRatio,
+          MINIMAL_CROP_SIZE,
+          MAX_WIDTH,
+        );
+        nextHeight = nextWidth / widthAspectRatio;
+      }
+
+      adjustFlipForHandle(transformHandle, crop);
+
+      if (widthAspectRatio) {
+        crop.x += (previousCropWidth - crop.width) / 2;
+      }
+
+      break;
+    }
+    case "w": {
+      if (widthAspectRatio) {
+        const distanceToTop = croppedTop + element.height / 2;
+        const distanceToBottom =
+          uncroppedHeight - croppedTop - element.height / 2;
+
+        const MAX_HEIGHT = Math.min(distanceToTop, distanceToBottom) * 2;
+
+        nextHeight = clamp(
+          nextWidth / widthAspectRatio,
+          MINIMAL_CROP_SIZE,
+          MAX_HEIGHT,
+        );
+        nextWidth = nextHeight * widthAspectRatio;
+      }
+
+      adjustFlipForHandle(transformHandle, crop);
+
+      if (widthAspectRatio) {
+        crop.y += (previousCropHeight - crop.height) / 2;
+      }
+
+      break;
+    }
+    case "e": {
+      if (widthAspectRatio) {
+        const distanceToTop = croppedTop + element.height / 2;
+        const distanceToBottom =
+          uncroppedHeight - croppedTop - element.height / 2;
+
+        const MAX_HEIGHT = Math.min(distanceToTop, distanceToBottom) * 2;
+
+        nextHeight = clamp(
+          nextWidth / widthAspectRatio,
+          MINIMAL_CROP_SIZE,
+          MAX_HEIGHT,
+        );
+        nextWidth = nextHeight * widthAspectRatio;
+      }
+
+      adjustFlipForHandle(transformHandle, crop);
+
+      if (widthAspectRatio) {
+        crop.y += (previousCropHeight - crop.height) / 2;
+      }
+
+      break;
+    }
+    case "ne": {
+      if (widthAspectRatio) {
+        if (changeInWidth > -changeInHeight) {
+          const MAX_HEIGHT = isFlippedByY
+            ? uncroppedHeight - croppedTop
+            : croppedTop + element.height;
+
+          nextHeight = clamp(
+            nextWidth / widthAspectRatio,
+            MINIMAL_CROP_SIZE,
+            MAX_HEIGHT,
+          );
+          nextWidth = nextHeight * widthAspectRatio;
+        } else {
+          const MAX_WIDTH = isFlippedByX
+            ? croppedLeft + element.width
+            : uncroppedWidth - croppedLeft;
+
+          nextWidth = clamp(
+            nextHeight * widthAspectRatio,
+            MINIMAL_CROP_SIZE,
+            MAX_WIDTH,
+          );
+          nextHeight = nextWidth / widthAspectRatio;
+        }
+      }
+
+      adjustFlipForHandle(transformHandle, crop);
+      break;
+    }
+    case "nw": {
+      if (widthAspectRatio) {
+        if (changeInWidth < changeInHeight) {
+          const MAX_HEIGHT = isFlippedByY
+            ? uncroppedHeight - croppedTop
+            : croppedTop + element.height;
+          nextHeight = clamp(
+            nextWidth / widthAspectRatio,
+            MINIMAL_CROP_SIZE,
+            MAX_HEIGHT,
+          );
+          nextWidth = nextHeight * widthAspectRatio;
+        } else {
+          const MAX_WIDTH = isFlippedByX
+            ? uncroppedWidth - croppedLeft
+            : croppedLeft + element.width;
+
+          nextWidth = clamp(
+            nextHeight * widthAspectRatio,
+            MINIMAL_CROP_SIZE,
+            MAX_WIDTH,
+          );
+          nextHeight = nextWidth / widthAspectRatio;
+        }
+      }
+
+      adjustFlipForHandle(transformHandle, crop);
+      break;
+    }
+    case "se": {
+      if (widthAspectRatio) {
+        if (changeInWidth > changeInHeight) {
+          const MAX_HEIGHT = isFlippedByY
+            ? croppedTop + element.height
+            : uncroppedHeight - croppedTop;
+
+          nextHeight = clamp(
+            nextWidth / widthAspectRatio,
+            MINIMAL_CROP_SIZE,
+            MAX_HEIGHT,
+          );
+          nextWidth = nextHeight * widthAspectRatio;
+        } else {
+          const MAX_WIDTH = isFlippedByX
+            ? croppedLeft + element.width
+            : uncroppedWidth - croppedLeft;
+
+          nextWidth = clamp(
+            nextHeight * widthAspectRatio,
+            MINIMAL_CROP_SIZE,
+            MAX_WIDTH,
+          );
+          nextHeight = nextWidth / widthAspectRatio;
+        }
+      }
+
+      adjustFlipForHandle(transformHandle, crop);
+      break;
+    }
+    case "sw": {
+      if (widthAspectRatio) {
+        if (-changeInWidth > changeInHeight) {
+          const MAX_HEIGHT = isFlippedByY
+            ? croppedTop + element.height
+            : uncroppedHeight - croppedTop;
+
+          nextHeight = clamp(
+            nextWidth / widthAspectRatio,
+            MINIMAL_CROP_SIZE,
+            MAX_HEIGHT,
+          );
+          nextWidth = nextHeight * widthAspectRatio;
+        } else {
+          const MAX_WIDTH = isFlippedByX
+            ? uncroppedWidth - croppedLeft
+            : croppedLeft + element.width;
+
+          nextWidth = clamp(
+            nextHeight * widthAspectRatio,
+            MINIMAL_CROP_SIZE,
+            MAX_WIDTH,
+          );
+          nextHeight = nextWidth / widthAspectRatio;
+        }
+      }
+
+      adjustFlipForHandle(transformHandle, crop);
+      break;
+    }
+    default:
+      break;
+  }
+
+  const newOrigin = recomputeOrigin(
+    element,
+    transformHandle,
+    nextWidth,
+    nextHeight,
+    !!widthAspectRatio,
+  );
+
+  // reset crop to null if we're back to orig size
+  if (
+    isCloseTo(crop.width, crop.naturalWidth) &&
+    isCloseTo(crop.height, crop.naturalHeight)
+  ) {
+    crop = null;
+  }
+
+  return {
+    x: newOrigin[0],
+    y: newOrigin[1],
+    width: nextWidth,
+    height: nextHeight,
+    crop,
+  };
+};
+
+const recomputeOrigin = (
+  stateAtCropStart: ExcalidrawElement,
+  transformHandle: TransformHandleType,
+  width: number,
+  height: number,
+  shouldMaintainAspectRatio?: boolean,
+) => {
+  const [x1, y1, x2, y2] = getResizedElementAbsoluteCoords(
+    stateAtCropStart,
+    stateAtCropStart.width,
+    stateAtCropStart.height,
+    true,
+  );
+  const startTopLeft = pointFrom(x1, y1);
+  const startBottomRight = pointFrom(x2, y2);
+  const startCenter: any = pointCenter(startTopLeft, startBottomRight);
+
+  const [newBoundsX1, newBoundsY1, newBoundsX2, newBoundsY2] =
+    getResizedElementAbsoluteCoords(stateAtCropStart, width, height, true);
+  const newBoundsWidth = newBoundsX2 - newBoundsX1;
+  const newBoundsHeight = newBoundsY2 - newBoundsY1;
+
+  // Calculate new topLeft based on fixed corner during resize
+  let newTopLeft = [...startTopLeft] as [number, number];
+
+  if (["n", "w", "nw"].includes(transformHandle)) {
+    newTopLeft = [
+      startBottomRight[0] - Math.abs(newBoundsWidth),
+      startBottomRight[1] - Math.abs(newBoundsHeight),
+    ];
+  }
+  if (transformHandle === "ne") {
+    const bottomLeft = [startTopLeft[0], startBottomRight[1]];
+    newTopLeft = [bottomLeft[0], bottomLeft[1] - Math.abs(newBoundsHeight)];
+  }
+  if (transformHandle === "sw") {
+    const topRight = [startBottomRight[0], startTopLeft[1]];
+    newTopLeft = [topRight[0] - Math.abs(newBoundsWidth), topRight[1]];
+  }
+
+  if (shouldMaintainAspectRatio) {
+    if (["s", "n"].includes(transformHandle)) {
+      newTopLeft[0] = startCenter[0] - newBoundsWidth / 2;
+    }
+    if (["e", "w"].includes(transformHandle)) {
+      newTopLeft[1] = startCenter[1] - newBoundsHeight / 2;
+    }
+  }
+
+  // adjust topLeft to new rotation point
+  const angle = stateAtCropStart.angle;
+  const rotatedTopLeft = pointRotateRads(newTopLeft, startCenter, angle);
+  const newCenter: Point = [
+    newTopLeft[0] + Math.abs(newBoundsWidth) / 2,
+    newTopLeft[1] + Math.abs(newBoundsHeight) / 2,
+  ];
+  const rotatedNewCenter = pointRotateRads(newCenter, startCenter, angle);
+  newTopLeft = pointRotateRads(
+    rotatedTopLeft,
+    rotatedNewCenter,
+    -angle as Radians,
+  );
+
+  const newOrigin = [...newTopLeft];
+  newOrigin[0] += stateAtCropStart.x - newBoundsX1;
+  newOrigin[1] += stateAtCropStart.y - newBoundsY1;
+
+  return newOrigin;
+};
+
+// refer to https://link.excalidraw.com/l/6rfy1007QOo/6stx5PmRn0k
+export const getUncroppedImageElement = (
+  element: ExcalidrawImageElement,
+  elementsMap: ElementsMap,
+) => {
+  if (element.crop) {
+    const { width, height } = getUncroppedWidthAndHeight(element);
+
+    const [x1, y1, x2, y2, cx, cy] = getElementAbsoluteCoords(
+      element,
+      elementsMap,
+    );
+
+    const topLeftVector = vectorFromPoint(
+      pointRotateRads(pointFrom(x1, y1), pointFrom(cx, cy), element.angle),
+    );
+    const topRightVector = vectorFromPoint(
+      pointRotateRads(pointFrom(x2, y1), pointFrom(cx, cy), element.angle),
+    );
+    const topEdgeNormalized = vectorNormalize(
+      vectorSubtract(topRightVector, topLeftVector),
+    );
+    const bottomLeftVector = vectorFromPoint(
+      pointRotateRads(pointFrom(x1, y2), pointFrom(cx, cy), element.angle),
+    );
+    const leftEdgeVector = vectorSubtract(bottomLeftVector, topLeftVector);
+    const leftEdgeNormalized = vectorNormalize(leftEdgeVector);
+
+    const { cropX, cropY } = adjustCropPosition(element.crop, element.scale);
+
+    const rotatedTopLeft = vectorAdd(
+      vectorAdd(
+        topLeftVector,
+        vectorScale(
+          topEdgeNormalized,
+          (-cropX * width) / element.crop.naturalWidth,
+        ),
+      ),
+      vectorScale(
+        leftEdgeNormalized,
+        (-cropY * height) / element.crop.naturalHeight,
+      ),
+    );
+
+    const center = pointFromVector(
+      vectorAdd(
+        vectorAdd(rotatedTopLeft, vectorScale(topEdgeNormalized, width / 2)),
+        vectorScale(leftEdgeNormalized, height / 2),
+      ),
+    );
+
+    const unrotatedTopLeft = pointRotateRads(
+      pointFromVector(rotatedTopLeft),
+      center,
+      -element.angle as Radians,
+    );
+
+    const uncroppedElement: ExcalidrawImageElement = {
+      ...element,
+      x: unrotatedTopLeft[0],
+      y: unrotatedTopLeft[1],
+      width,
+      height,
+      crop: null,
+    };
+
+    return uncroppedElement;
+  }
+
+  return element;
+};
+
+export const getUncroppedWidthAndHeight = (element: ExcalidrawImageElement) => {
+  if (element.crop) {
+    const width =
+      element.width / (element.crop.width / element.crop.naturalWidth);
+    const height =
+      element.height / (element.crop.height / element.crop.naturalHeight);
+
+    return {
+      width,
+      height,
+    };
+  }
+
+  return {
+    width: element.width,
+    height: element.height,
+  };
+};
+
+const adjustCropPosition = (
+  crop: ImageCrop,
+  scale: ExcalidrawImageElement["scale"],
+) => {
+  let cropX = crop.x;
+  let cropY = crop.y;
+
+  const flipX = scale[0] === -1;
+  const flipY = scale[1] === -1;
+
+  if (flipX) {
+    cropX = crop.naturalWidth - Math.abs(cropX) - crop.width;
+  }
+
+  if (flipY) {
+    cropY = crop.naturalHeight - Math.abs(cropY) - crop.height;
+  }
+
+  return {
+    cropX,
+    cropY,
+  };
+};
+
+export const getFlipAdjustedCropPosition = (
+  element: ExcalidrawImageElement,
+  natural = false,
+) => {
+  const crop = element.crop;
+  if (!crop) {
+    return null;
+  }
+
+  const isFlippedByX = element.scale[0] === -1;
+  const isFlippedByY = element.scale[1] === -1;
+
+  let cropX = crop.x;
+  let cropY = crop.y;
+
+  if (isFlippedByX) {
+    cropX = crop.naturalWidth - crop.width - crop.x;
+  }
+
+  if (isFlippedByY) {
+    cropY = crop.naturalHeight - crop.height - crop.y;
+  }
+
+  if (natural) {
+    return {
+      x: cropX,
+      y: cropY,
+    };
+  }
+
+  const { width, height } = getUncroppedWidthAndHeight(element);
+
+  return {
+    x: cropX / (crop.naturalWidth / width),
+    y: cropY / (crop.naturalHeight / height),
+  };
+};

packages/element/src/distance.ts

@@ -0,0 +1,144 @@
+import {
+  curvePointDistance,
+  distanceToLineSegment,
+  pointRotateRads,
+} from "@excalidraw/math";
+
+import { ellipse, ellipseDistanceFromPoint } from "@excalidraw/math/ellipse";
+
+import type { GlobalPoint, Radians } from "@excalidraw/math";
+
+import {
+  deconstructDiamondElement,
+  deconstructLinearOrFreeDrawElement,
+  deconstructRectanguloidElement,
+} from "./utils";
+
+import { elementCenterPoint } from "./bounds";
+
+import type {
+  ElementsMap,
+  ExcalidrawDiamondElement,
+  ExcalidrawElement,
+  ExcalidrawEllipseElement,
+  ExcalidrawFreeDrawElement,
+  ExcalidrawLinearElement,
+  ExcalidrawRectanguloidElement,
+} from "./types";
+
+export const distanceToElement = (
+  element: ExcalidrawElement,
+  elementsMap: ElementsMap,
+  p: GlobalPoint,
+): number => {
+  switch (element.type) {
+    case "selection":
+    case "rectangle":
+    case "stickynote":
+    case "image":
+    case "text":
+    case "iframe":
+    case "embeddable":
+    case "frame":
+    case "magicframe":
+      return distanceToRectanguloidElement(element, elementsMap, p);
+    case "diamond":
+      return distanceToDiamondElement(element, elementsMap, p);
+    case "ellipse":
+      return distanceToEllipseElement(element, elementsMap, p);
+    case "line":
+    case "arrow":
+    case "freedraw":
+      return distanceToLinearOrFreeDraElement(element, elementsMap, p);
+  }
+};
+
+/**
+ * Returns the distance of a point and the provided rectangular-shaped element,
+ * accounting for roundness and rotation
+ *
+ * @param element The rectanguloid element
+ * @param p The point to consider
+ * @returns The eucledian distance to the outline of the rectanguloid element
+ */
+const distanceToRectanguloidElement = (
+  element: ExcalidrawRectanguloidElement,
+  elementsMap: ElementsMap,
+  p: GlobalPoint,
+) => {
+  const center = elementCenterPoint(element, elementsMap);
+  // To emulate a rotated rectangle we rotate the point in the inverse angle
+  // instead. It's all the same distance-wise.
+  const rotatedPoint = pointRotateRads(p, center, -element.angle as Radians);
+
+  // Get the element's building components we can test against
+  const [sides, corners] = deconstructRectanguloidElement(element);
+
+  return Math.min(
+    ...sides.map((s) => distanceToLineSegment(rotatedPoint, s)),
+    ...corners.map((a) => curvePointDistance(a, rotatedPoint)),
+  );
+};
+
+/**
+ * Returns the distance of a point and the provided diamond element, accounting
+ * for roundness and rotation
+ *
+ * @param element The diamond element
+ * @param p The point to consider
+ * @returns The eucledian distance to the outline of the diamond
+ */
+const distanceToDiamondElement = (
+  element: ExcalidrawDiamondElement,
+  elementsMap: ElementsMap,
+  p: GlobalPoint,
+): number => {
+  const center = elementCenterPoint(element, elementsMap);
+
+  // Rotate the point to the inverse direction to simulate the rotated diamond
+  // points. It's all the same distance-wise.
+  const rotatedPoint = pointRotateRads(p, center, -element.angle as Radians);
+
+  const [sides, curves] = deconstructDiamondElement(element);
+
+  return Math.min(
+    ...sides.map((s) => distanceToLineSegment(rotatedPoint, s)),
+    ...curves.map((a) => curvePointDistance(a, rotatedPoint)),
+  );
+};
+
+/**
+ * Returns the distance of a point and the provided ellipse element, accounting
+ * for roundness and rotation
+ *
+ * @param element The ellipse element
+ * @param p The point to consider
+ * @returns The eucledian distance to the outline of the ellipse
+ */
+const distanceToEllipseElement = (
+  element: ExcalidrawEllipseElement,
+  elementsMap: ElementsMap,
+  p: GlobalPoint,
+): number => {
+  const center = elementCenterPoint(element, elementsMap);
+  return ellipseDistanceFromPoint(
+    // Instead of rotating the ellipse, rotate the point to the inverse angle
+    pointRotateRads(p, center, -element.angle as Radians),
+    ellipse(center, element.width / 2, element.height / 2),
+  );
+};
+
+const distanceToLinearOrFreeDraElement = (
+  element: ExcalidrawLinearElement | ExcalidrawFreeDrawElement,
+  elementsMap: ElementsMap,
+  p: GlobalPoint,
+) => {
+  const [lines, curves] = deconstructLinearOrFreeDrawElement(
+    element,
+    elementsMap,
+  );
+  return Math.min(
+    ...lines.map((s) => distanceToLineSegment(p, s)),
+    ...curves.map((a) => curvePointDistance(a, p)),
+  );
+};

packages/element/src/distribute.ts

@@ -0,0 +1,114 @@
+import type { AppState } from "@excalidraw/excalidraw/types";
+
+import { updateBoundElements } from "./binding";
+import { getCommonBoundingBox } from "./bounds";
+
+import { getSelectedElementsByGroup } from "./groups";
+
+import { getNonDeletedElements } from ".";
+
+import type { Scene } from "./Scene";
+
+import type { ElementsMap, NonDeletedExcalidrawElement } from "./types";
+
+export interface Distribution {
+  space: "between";
+  axis: "x" | "y";
+}
+
+export const distributeElements = (
+  selectedElements: NonDeletedExcalidrawElement[],
+  elementsMap: ElementsMap,
+  distribution: Distribution,
+  appState: Readonly<AppState>,
+  scene: Scene,
+): NonDeletedExcalidrawElement[] => {
+  const [start, mid, end, extent] =
+    distribution.axis === "x"
+      ? (["minX", "midX", "maxX", "width"] as const)
+      : (["minY", "midY", "maxY", "height"] as const);
+
+  const bounds = getCommonBoundingBox(selectedElements);
+  const groups = getSelectedElementsByGroup(
+    selectedElements,
+    elementsMap,
+    appState,
+  )
+    .map(getNonDeletedElements) // Nothing to distribute on deleted elements
+    .map((group) => [group, getCommonBoundingBox(group)] as const)
+    .sort((a, b) => a[1][mid] - b[1][mid]);
+
+  let span = 0;
+  for (const group of groups) {
+    span += group[1][extent];
+  }
+
+  const step = (bounds[extent] - span) / (groups.length - 1);
+
+  if (step < 0) {
+    // If we have a negative step, we'll need to distribute from centers
+    // rather than from gaps. Buckle up, this is a weird one.
+
+    // Get indices of boxes that define start and end of our bounding box
+    const index0 = groups.findIndex((g) => g[1][start] === bounds[start]);
+    const index1 = groups.findIndex((g) => g[1][end] === bounds[end]);
+
+    // Get our step, based on the distance between the center points of our
+    // start and end boxes
+    const step =
+      (groups[index1][1][mid] - groups[index0][1][mid]) / (groups.length - 1);
+
+    let pos = groups[index0][1][mid];
+
+    return groups.flatMap(([group, box], index) => {
+      const translation = {
+        x: 0,
+        y: 0,
+      };
+
+      // Don't move our start and end boxes
+      if (index !== index0 && index !== index1) {
+        pos += step;
+        translation[distribution.axis] = pos - box[mid];
+      }
+
+      return group.map((element) => {
+        const updatedElement = scene.mutateElement(element, {
+          x: element.x + translation.x,
+          y: element.y + translation.y,
+        });
+        updateBoundElements(element, scene, {
+          simultaneouslyUpdated: group,
+        });
+        return updatedElement;
+      });
+    });
+  }
+
+  // Distribute from gaps
+
+  let pos = bounds[start];
+
+  return groups.flatMap(([group, box]) => {
+    const translation = {
+      x: 0,
+      y: 0,
+    };
+
+    translation[distribution.axis] = pos - box[start];
+
+    pos += step;
+    pos += box[extent];
+
+    return group.map((element) => {
+      const updatedElement = scene.mutateElement(element, {
+        x: element.x + translation.x,
+        y: element.y + translation.y,
+      });
+      updateBoundElements(element, scene, {
+        simultaneouslyUpdated: group,
+      });
+      return updatedElement;
+    });
+  });
+};

packages/element/src/dragElements.ts

@@ -0,0 +1,409 @@
+import {
+  type Bounds,
+  TEXT_AUTOWRAP_THRESHOLD,
+  getGridPoint,
+  getFontString,
+  DRAGGING_THRESHOLD,
+} from "@excalidraw/common";
+
+import type {
+  AppState,
+  NormalizedZoomValue,
+  NullableGridSize,
+  PointerDownState,
+} from "@excalidraw/excalidraw/types";
+
+import type { NonDeletedExcalidrawElement } from "@excalidraw/element/types";
+
+import { unbindBindingElement, updateBoundElements } from "./binding";
+import { getCommonBounds } from "./bounds";
+import { getPerfectElementSize } from "./sizeHelpers";
+import { getBoundTextElement } from "./textElement";
+import { getMinTextElementWidth } from "./textMeasurements";
+import {
+  isArrowElement,
+  isElbowArrow,
+  isFrameLikeElement,
+  isImageElement,
+  isTextElement,
+} from "./typeChecks";
+
+import type { Scene } from "./Scene";
+
+import type { ExcalidrawElement, ExcalidrawTextElement } from "./types";
+
+export const dragSelectedElements = (
+  pointerDownState: PointerDownState,
+  _selectedElements: NonDeletedExcalidrawElement[],
+  offset: { x: number; y: number },
+  scene: Scene,
+  snapOffset: {
+    x: number;
+    y: number;
+  },
+  gridSize: NullableGridSize,
+) => {
+  if (
+    _selectedElements.length === 1 &&
+    isElbowArrow(_selectedElements[0]) &&
+    (_selectedElements[0].startBinding || _selectedElements[0].endBinding)
+  ) {
+    return;
+  }
+
+  const selectedElements = _selectedElements.filter((element) => {
+    if (isElbowArrow(element) && element.startBinding && element.endBinding) {
+      const startElement = _selectedElements.find(
+        (el) => el.id === element.startBinding?.elementId,
+      );
+      const endElement = _selectedElements.find(
+        (el) => el.id === element.endBinding?.elementId,
+      );
+
+      return startElement && endElement;
+    }
+
+    return true;
+  });
+
+  // we do not want a frame and its elements to be selected at the same time
+  // but when it happens (due to some bug), we want to avoid updating element
+  // in the frame twice, hence the use of set
+  const elementsToUpdate = new Set<NonDeletedExcalidrawElement>(
+    selectedElements,
+  );
+  const frames = selectedElements
+    .filter((e) => isFrameLikeElement(e))
+    .map((f) => f.id);
+
+  if (frames.length > 0) {
+    for (const element of scene.getNonDeletedElements()) {
+      if (element.frameId !== null && frames.includes(element.frameId)) {
+        elementsToUpdate.add(element);
+      }
+    }
+  }
+
+  const origElements: ExcalidrawElement[] = [];
+
+  for (const element of elementsToUpdate) {
+    const origElement = pointerDownState.originalElements.get(element.id);
+    // if original element is not set (e.g. when you duplicate during a drag
+    // operation), exit to avoid undefined behavior
+    if (!origElement) {
+      return;
+    }
+    origElements.push(origElement);
+  }
+
+  const adjustedOffset = calculateOffset(
+    getCommonBounds(origElements),
+    offset,
+    snapOffset,
+    gridSize,
+  );
+
+  const elementsToUpdateIds = new Set(
+    Array.from(elementsToUpdate, (el) => el.id),
+  );
+
+  elementsToUpdate.forEach((element) => {
+    const isArrow = !isArrowElement(element);
+    const isStartBoundElementSelected =
+      isArrow ||
+      (element.startBinding
+        ? elementsToUpdateIds.has(element.startBinding.elementId)
+        : false);
+    const isEndBoundElementSelected =
+      isArrow ||
+      (element.endBinding
+        ? elementsToUpdateIds.has(element.endBinding.elementId)
+        : false);
+
+    if (!isArrowElement(element)) {
+      updateElementCoords(pointerDownState, element, scene, adjustedOffset);
+
+      // skip arrow labels since we calculate its position during render
+      const textElement = getBoundTextElement(
+        element,
+        scene.getNonDeletedElementsMap(),
+      );
+      if (textElement) {
+        updateElementCoords(
+          pointerDownState,
+          textElement,
+          scene,
+          adjustedOffset,
+        );
+      }
+      updateBoundElements(element, scene, {
+        simultaneouslyUpdated: Array.from(elementsToUpdate),
+      });
+    } else if (
+      // NOTE: Add a little initial drag to the arrow dragging when the arrow
+      // is the single element being dragged to avoid accidentally unbinding
+      // the arrow when the user just wants to select it.
+
+      elementsToUpdate.size > 1 ||
+      Math.max(Math.abs(adjustedOffset.x), Math.abs(adjustedOffset.y)) >
+        DRAGGING_THRESHOLD ||
+      (!element.startBinding && !element.endBinding)
+    ) {
+      updateElementCoords(pointerDownState, element, scene, adjustedOffset);
+
+      const shouldUnbindStart =
+        element.startBinding && !isStartBoundElementSelected;
+      const shouldUnbindEnd = element.endBinding && !isEndBoundElementSelected;
+      if (shouldUnbindStart || shouldUnbindEnd) {
+        // NOTE: Moving the bound arrow should unbind it, otherwise we would
+        // have weird situations, like 0 lenght arrow when the user moves
+        // the arrow outside a filled shape suddenly forcing the arrow start
+        // and end point to jump "outside" the shape.
+        if (shouldUnbindStart) {
+          unbindBindingElement(element, "start", scene);
+        }
+        if (shouldUnbindEnd) {
+          unbindBindingElement(element, "end", scene);
+        }
+      }
+    }
+  });
+};
+
+const calculateOffset = (
+  commonBounds: Bounds,
+  dragOffset: { x: number; y: number },
+  snapOffset: { x: number; y: number },
+  gridSize: NullableGridSize,
+): { x: number; y: number } => {
+  const [x, y] = commonBounds;
+  let nextX = x + dragOffset.x + snapOffset.x;
+  let nextY = y + dragOffset.y + snapOffset.y;
+
+  if (snapOffset.x === 0 || snapOffset.y === 0) {
+    const [nextGridX, nextGridY] = getGridPoint(
+      x + dragOffset.x,
+      y + dragOffset.y,
+      gridSize,
+    );
+
+    if (snapOffset.x === 0) {
+      nextX = nextGridX;
+    }
+
+    if (snapOffset.y === 0) {
+      nextY = nextGridY;
+    }
+  }
+  return {
+    x: nextX - x,
+    y: nextY - y,
+  };
+};
+
+const updateElementCoords = (
+  pointerDownState: PointerDownState,
+  element: ExcalidrawElement,
+  scene: Scene,
+  dragOffset: { x: number; y: number },
+) => {
+  const originalElement =
+    pointerDownState.originalElements.get(element.id) ?? element;
+
+  const nextX = originalElement.x + dragOffset.x;
+  const nextY = originalElement.y + dragOffset.y;
+
+  scene.mutateElement(element, {
+    x: nextX,
+    y: nextY,
+  });
+};
+
+export const getDragOffsetXY = (
+  selectedElements: NonDeletedExcalidrawElement[],
+  x: number,
+  y: number,
+): [number, number] => {
+  const [x1, y1] = getCommonBounds(selectedElements);
+  return [x - x1, y - y1];
+};
+
+/**
+ * Sizes a text element as it is dragged out.
+ *
+ * A dragged text pins one point and grows away from it; `anchorRatio` says
+ * where along the box that point sits — 0 for its left edge, 1 for its right,
+ * 0.5 for its centre.
+ *
+ * A free text pins the point the drag started from and takes the ratio from
+ * the drag direction, so it can be pulled either way. A text bound to an arrow
+ * endpoint instead pins whatever the binding placed it against and takes the
+ * ratio from its alignment — which is also what keeps it from growing back
+ * over the arrow, since dragging that way makes no progress rather than
+ * flipping the box around.
+ */
+export const dragNewTextElement = ({
+  newElement,
+  anchorX,
+  anchorRatio,
+  pointerX,
+  nextY,
+  zoom,
+  scene,
+  informMutation = true,
+}: {
+  newElement: ExcalidrawTextElement;
+  anchorX: number;
+  /** 0 = anchored by its left edge, 1 = by its right, 0.5 = by its centre */
+  anchorRatio: number;
+  pointerX: number;
+  /** free text re-tops itself to the drag origin; a bound one must not move */
+  nextY?: number;
+  zoom: NormalizedZoomValue;
+  scene: Scene;
+  informMutation?: boolean;
+}) => {
+  const offset = pointerX - anchorX;
+
+  // how far the pointer has travelled away from the anchor along the direction
+  // the box may grow — negative once it heads back the other way
+  const reach =
+    anchorRatio === 0 ? offset : anchorRatio === 1 ? -offset : Math.abs(offset);
+
+  const width = Math.max(
+    // a centred box grows on both sides, so it widens at twice the reach
+    anchorRatio === 0.5 ? reach * 2 : reach,
+    getMinTextElementWidth(
+      getFontString({
+        fontSize: newElement.fontSize,
+        fontFamily: newElement.fontFamily,
+      }),
+      newElement.lineHeight,
+    ),
+  );
+
+  scene.mutateElement(
+    newElement,
+    {
+      x: anchorX - width * anchorRatio,
+      ...(nextY === undefined ? {} : { y: nextY }),
+      width,
+      ...(reach > TEXT_AUTOWRAP_THRESHOLD / zoom ? { autoResize: false } : {}),
+    },
+    { informMutation, isDragging: false },
+  );
+};
+
+export const dragNewElement = ({
+  newElement,
+  elementType,
+  originX,
+  originY,
+  x,
+  y,
+  width,
+  height,
+  shouldMaintainAspectRatio,
+  shouldResizeFromCenter,
+  zoom,
+  scene,
+  widthAspectRatio = null,
+  originOffset = null,
+  informMutation = true,
+}: {
+  newElement: NonDeletedExcalidrawElement;
+  elementType: AppState["activeTool"]["type"];
+  originX: number;
+  originY: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  shouldMaintainAspectRatio: boolean;
+  shouldResizeFromCenter: boolean;
+  zoom: NormalizedZoomValue;
+  scene: Scene;
+  /** whether to keep given aspect ratio when `isResizeWithSidesSameLength` is
+      true */
+  widthAspectRatio?: number | null;
+  originOffset?: {
+    x: number;
+    y: number;
+  } | null;
+  informMutation?: boolean;
+}) => {
+  if (shouldMaintainAspectRatio && newElement.type !== "selection") {
+    if (widthAspectRatio) {
+      height = width / widthAspectRatio;
+    } else {
+      // Depending on where the cursor is at (x, y) relative to where the starting point is
+      // (originX, originY), we use ONLY width or height to control size increase.
+      // This allows the cursor to always "stick" to one of the sides of the bounding box.
+      if (Math.abs(y - originY) > Math.abs(x - originX)) {
+        ({ width, height } = getPerfectElementSize(
+          elementType,
+          height,
+          x < originX ? -width : width,
+        ));
+      } else {
+        ({ width, height } = getPerfectElementSize(
+          elementType,
+          width,
+          y < originY ? -height : height,
+        ));
+      }
+
+      if (height < 0) {
+        height = -height;
+      }
+    }
+  }
+
+  if (isTextElement(newElement)) {
+    // a text is only ever sized horizontally — its height follows the wrapped
+    // content — so it grows away from the point the drag started at
+    dragNewTextElement({
+      newElement,
+      anchorX: originX + (originOffset?.x ?? 0),
+      anchorRatio: shouldResizeFromCenter ? 0.5 : x < originX ? 1 : 0,
+      pointerX: x,
+      nextY: originY + (originOffset?.y ?? 0),
+      zoom,
+      scene,
+      informMutation,
+    });
+    return;
+  }
+
+  let newX = x < originX ? originX - width : originX;
+  let newY = y < originY ? originY - height : originY;
+
+  if (shouldResizeFromCenter) {
+    width += width;
+    height += height;
+    newX = originX - width / 2;
+    newY = originY - height / 2;
+  }
+
+  if (width !== 0 && height !== 0) {
+    let imageInitialDimension = null;
+    if (isImageElement(newElement)) {
+      imageInitialDimension = {
+        initialWidth: width,
+        initialHeight: height,
+      };
+    }
+
+    scene.mutateElement(
+      newElement,
+      {
+        x: newX + (originOffset?.x ?? 0),
+        y: newY + (originOffset?.y ?? 0),
+        width,
+        height,
+        ...imageInitialDimension,
+      },
+      { informMutation, isDragging: false },
+    );
+  }
+};

packages/element/src/duplicate.ts

@@ -0,0 +1,519 @@
+import {
+  ORIG_ID,
+  randomId,
+  randomInteger,
+  arrayToMap,
+  castArray,
+  findLastIndex,
+  getUpdatedTimestamp,
+  isTestEnv,
+} from "@excalidraw/common";
+
+import type { Mutable } from "@excalidraw/common/utility-types";
+
+import type { AppState } from "@excalidraw/excalidraw/types";
+
+import {
+  getElementsInGroup,
+  getNewGroupIdsForDuplication,
+  getSelectedGroupForElement,
+} from "./groups";
+
+import {
+  bindElementsToFramesAfterDuplication,
+  getFrameChildren,
+} from "./frame";
+
+import { normalizeElementOrder } from "./sortElements";
+
+import { bumpVersion } from "./mutateElement";
+
+import {
+  hasBoundTextElement,
+  isBoundToContainer,
+  isFrameLikeElement,
+} from "./typeChecks";
+
+import { getBoundTextElement, getContainerElement } from "./textElement";
+
+import { fixDuplicatedBindingsAfterDuplication } from "./binding";
+
+import { isNonDeletedElement } from ".";
+
+import type {
+  ElementsMap,
+  ExcalidrawElement,
+  GroupId,
+  NonDeletedExcalidrawElement,
+  NonDeletedSceneElementsMap,
+} from "./types";
+
+/**
+ * Duplicate an element, often used in the alt-drag operation.
+ * Note that this method has gotten a bit complicated since the
+ * introduction of gruoping/ungrouping elements.
+ * @param editingGroupId The current group being edited. The new
+ *                       element will inherit this group and its
+ *                       parents.
+ * @param groupIdMapForOperation A Map that maps old group IDs to
+ *                               duplicated ones. If you are duplicating
+ *                               multiple elements at once, share this map
+ *                               amongst all of them
+ * @param element Element to duplicate
+ */
+export const duplicateElement = <TElement extends ExcalidrawElement>(
+  editingGroupId: AppState["editingGroupId"],
+  groupIdMapForOperation: Map<GroupId, GroupId>,
+  element: TElement,
+  randomizeSeed?: boolean,
+): Readonly<TElement> => {
+  const copy = deepCopyElement(element);
+
+  if (isTestEnv()) {
+    __test__defineOrigId(copy, element.id);
+  }
+
+  copy.id = randomId();
+  copy.updated = getUpdatedTimestamp();
+  copy.created = copy.updated;
+  if (randomizeSeed) {
+    copy.seed = randomInteger();
+    bumpVersion(copy);
+  }
+
+  copy.groupIds = getNewGroupIdsForDuplication(
+    copy.groupIds,
+    editingGroupId,
+    (groupId) => {
+      if (!groupIdMapForOperation.has(groupId)) {
+        groupIdMapForOperation.set(groupId, randomId());
+      }
+      return groupIdMapForOperation.get(groupId)!;
+    },
+  );
+  return copy;
+};
+
+export const duplicateElements = (
+  opts: {
+    elements: readonly ExcalidrawElement[];
+    randomizeSeed?: boolean;
+    overrides?: (data: {
+      duplicateElement: ExcalidrawElement;
+      origElement: ExcalidrawElement;
+      origIdToDuplicateId: Map<
+        ExcalidrawElement["id"],
+        ExcalidrawElement["id"]
+      >;
+    }) => Partial<ExcalidrawElement>;
+  } & (
+    | {
+        /**
+         * Duplicates all elements in array.
+         *
+         * Use this when programmaticaly duplicating elements, without direct
+         * user interaction.
+         */
+        type: "everything";
+        // TODO remove/review this once we add frame children order migration
+        // and invariant checks
+        preserveFrameChildrenOrder?: boolean;
+      }
+    | {
+        /**
+         * Duplicates specified elements and inserts them back into the array
+         * in specified order.
+         *
+         * Use this when duplicating Scene elements, during user interaction
+         * such as alt-drag or on duplicate action.
+         */
+        type: "in-place";
+        idsOfElementsToDuplicate: Map<
+          ExcalidrawElement["id"],
+          ExcalidrawElement
+        >;
+        appState: {
+          editingGroupId: AppState["editingGroupId"];
+          selectedGroupIds: AppState["selectedGroupIds"];
+        };
+      }
+  ),
+) => {
+  let { elements } = opts;
+
+  const appState =
+    "appState" in opts
+      ? opts.appState
+      : ({
+          editingGroupId: null,
+          selectedGroupIds: {},
+        } as const);
+
+  // Ids of elements that have already been processed so we don't push them
+  // into the array twice if we end up backtracking when retrieving
+  // discontiguous group of elements (can happen due to a bug, or in edge
+  // cases such as a group containing deleted elements which were not selected).
+  //
+  // This is not enough to prevent duplicates, so we do a second loop afterwards
+  // to remove them.
+  //
+  // For convenience we mark even the newly created ones even though we don't
+  // loop over them.
+  const processedIds = new Map<ExcalidrawElement["id"], true>();
+  const groupIdMap = new Map();
+  const duplicatedElements: NonDeletedExcalidrawElement[] = [];
+  const origElements: ExcalidrawElement[] = [];
+  const origIdToDuplicateId = new Map<
+    ExcalidrawElement["id"],
+    ExcalidrawElement["id"]
+  >();
+  const duplicateIdToOrigElement = new Map<
+    ExcalidrawElement["id"],
+    ExcalidrawElement
+  >();
+  const duplicateElementsMap = new Map<string, NonDeletedExcalidrawElement>();
+  const elementsMap = arrayToMap(elements) as ElementsMap;
+  const _idsOfElementsToDuplicate =
+    opts.type === "in-place"
+      ? opts.idsOfElementsToDuplicate
+      : new Map(elements.map((el) => [el.id, el]));
+  const preserveFrameChildrenOrder =
+    opts.type === "everything" && opts.preserveFrameChildrenOrder;
+
+  // For sanity
+  if (opts.type === "in-place") {
+    for (const groupId of Object.keys(opts.appState.selectedGroupIds)) {
+      elements
+        .filter((el) => el.groupIds?.includes(groupId))
+        .forEach((el) => _idsOfElementsToDuplicate.set(el.id, el));
+    }
+  }
+
+  elements = normalizeElementOrder(elements);
+
+  const elementsWithDuplicates: ExcalidrawElement[] = elements.slice();
+
+  // helper functions
+  // -------------------------------------------------------------------------
+
+  // Used for the heavy lifing of copying a single element, a group of elements
+  // an element with bound text etc.
+  const copyElements = <T extends ExcalidrawElement | ExcalidrawElement[]>(
+    element: T,
+  ): T extends ExcalidrawElement[]
+    ? ExcalidrawElement[]
+    : ExcalidrawElement | null => {
+    const elements = castArray(element);
+
+    const _newElements = elements.reduce(
+      (acc: ExcalidrawElement[], element) => {
+        if (processedIds.has(element.id)) {
+          return acc;
+        }
+
+        processedIds.set(element.id, true);
+
+        // SAFETY: this should never happen, but we
+        // want to make sure we log it if it does
+        if (!isNonDeletedElement(element)) {
+          console.error(
+            "[NONDELETED][INVARIANT] Element to duplicate should be non-deleted",
+          );
+        }
+
+        const newElement = duplicateElement(
+          appState.editingGroupId,
+          groupIdMap,
+          element,
+          opts.randomizeSeed,
+        ) as NonDeletedExcalidrawElement;
+
+        processedIds.set(newElement.id, true);
+
+        duplicateElementsMap.set(newElement.id, newElement);
+        origIdToDuplicateId.set(element.id, newElement.id);
+        duplicateIdToOrigElement.set(newElement.id, element);
+
+        origElements.push(element);
+        duplicatedElements.push(newElement);
+
+        acc.push(newElement);
+        return acc;
+      },
+      [],
+    );
+
+    return (
+      Array.isArray(element) ? _newElements : _newElements[0] || null
+    ) as T extends ExcalidrawElement[]
+      ? ExcalidrawElement[]
+      : ExcalidrawElement | null;
+  };
+
+  // Helper to position cloned elements in the Z-order the product needs it
+  const insertBeforeOrAfterIndex = (
+    index: number,
+    elements: ExcalidrawElement | null | ExcalidrawElement[],
+  ) => {
+    if (!elements) {
+      return;
+    }
+
+    if (index > elementsWithDuplicates.length - 1) {
+      elementsWithDuplicates.push(...castArray(elements));
+      return;
+    }
+
+    elementsWithDuplicates.splice(index + 1, 0, ...castArray(elements));
+  };
+
+  // main
+  // ---------------------------------------------------------------------------
+
+  const frameIdsToDuplicate = new Set(
+    elements
+      .filter(
+        (el) => _idsOfElementsToDuplicate.has(el.id) && isFrameLikeElement(el),
+      )
+      .map((el) => el.id),
+  );
+
+  for (const element of elements) {
+    if (processedIds.has(element.id)) {
+      continue;
+    }
+
+    if (!_idsOfElementsToDuplicate.has(element.id)) {
+      continue;
+    }
+
+    // groups
+    // -------------------------------------------------------------------------
+
+    const groupId = getSelectedGroupForElement(appState, element);
+    if (groupId) {
+      const groupElements = getElementsInGroup(elements, groupId).flatMap(
+        (element) =>
+          isFrameLikeElement(element) && !preserveFrameChildrenOrder
+            ? [...getFrameChildren(elements, element.id), element]
+            : [element],
+      );
+
+      const targetIndex = findLastIndex(elementsWithDuplicates, (el) => {
+        return el.groupIds?.includes(groupId);
+      });
+
+      insertBeforeOrAfterIndex(targetIndex, copyElements(groupElements));
+      continue;
+    }
+
+    // frame duplication
+    // -------------------------------------------------------------------------
+
+    if (
+      !preserveFrameChildrenOrder &&
+      element.frameId &&
+      frameIdsToDuplicate.has(element.frameId)
+    ) {
+      continue;
+    }
+
+    if (isFrameLikeElement(element)) {
+      const frameId = element.id;
+
+      if (preserveFrameChildrenOrder) {
+        insertBeforeOrAfterIndex(
+          findLastIndex(elementsWithDuplicates, (el) => el.id === frameId),
+          copyElements(element),
+        );
+        continue;
+      }
+
+      const frameChildren = getFrameChildren(elements, frameId);
+
+      const targetIndex = findLastIndex(elementsWithDuplicates, (el) => {
+        return el.frameId === frameId || el.id === frameId;
+      });
+
+      insertBeforeOrAfterIndex(
+        targetIndex,
+        copyElements([...frameChildren, element]),
+      );
+      continue;
+    }
+
+    // text container
+    // -------------------------------------------------------------------------
+
+    if (hasBoundTextElement(element)) {
+      const boundTextElement = getBoundTextElement(element, elementsMap);
+
+      const targetIndex = findLastIndex(elementsWithDuplicates, (el) => {
+        return (
+          el.id === element.id ||
+          ("containerId" in el && el.containerId === element.id)
+        );
+      });
+
+      if (boundTextElement) {
+        insertBeforeOrAfterIndex(
+          targetIndex,
+          copyElements([element, boundTextElement]),
+        );
+      } else {
+        insertBeforeOrAfterIndex(targetIndex, copyElements(element));
+      }
+
+      continue;
+    }
+
+    if (isBoundToContainer(element)) {
+      const container = getContainerElement(element, elementsMap);
+
+      const targetIndex = findLastIndex(elementsWithDuplicates, (el) => {
+        return el.id === element.id || el.id === container?.id;
+      });
+
+      if (container) {
+        insertBeforeOrAfterIndex(
+          targetIndex,
+          copyElements([container, element]),
+        );
+      } else {
+        insertBeforeOrAfterIndex(targetIndex, copyElements(element));
+      }
+
+      continue;
+    }
+
+    // default duplication (regular elements)
+    // -------------------------------------------------------------------------
+
+    insertBeforeOrAfterIndex(
+      findLastIndex(elementsWithDuplicates, (el) => el.id === element.id),
+      copyElements(element),
+    );
+  }
+
+  // ---------------------------------------------------------------------------
+
+  fixDuplicatedBindingsAfterDuplication(
+    duplicatedElements,
+    origIdToDuplicateId,
+    duplicateElementsMap as NonDeletedSceneElementsMap,
+  );
+
+  bindElementsToFramesAfterDuplication(
+    elementsWithDuplicates,
+    origElements,
+    origIdToDuplicateId,
+  );
+
+  if (opts.overrides) {
+    for (const duplicateElement of duplicatedElements) {
+      const origElement = duplicateIdToOrigElement.get(duplicateElement.id);
+      if (origElement) {
+        Object.assign(
+          duplicateElement,
+          opts.overrides({
+            duplicateElement,
+            origElement,
+            origIdToDuplicateId,
+          }),
+        );
+      }
+    }
+  }
+
+  return {
+    duplicatedElements,
+    duplicateElementsMap,
+    elementsWithDuplicates,
+    origIdToDuplicateId,
+  };
+};
+
+// Simplified deep clone for the purpose of cloning ExcalidrawElement.
+//
+// Only clones plain objects and arrays. Doesn't clone Date, RegExp, Map, Set,
+// Typed arrays and other non-null objects.
+//
+// Adapted from https://github.com/lukeed/klona
+//
+// The reason for `deepCopyElement()` wrapper is type safety (only allow
+// passing ExcalidrawElement as the top-level argument).
+const _deepCopyElement = (val: any, depth: number = 0) => {
+  // only clone non-primitives
+  if (val == null || typeof val !== "object") {
+    return val;
+  }
+
+  const objectType = Object.prototype.toString.call(val);
+
+  if (objectType === "[object Object]") {
+    const tmp =
+      typeof val.constructor === "function"
+        ? Object.create(Object.getPrototypeOf(val))
+        : {};
+    for (const key in val) {
+      if (val.hasOwnProperty(key)) {
+        // don't copy non-serializable objects like these caches. They'll be
+        // populated when the element is rendered.
+        if (depth === 0 && (key === "shape" || key === "canvas")) {
+          continue;
+        }
+        tmp[key] = _deepCopyElement(val[key], depth + 1);
+      }
+    }
+    return tmp;
+  }
+
+  if (Array.isArray(val)) {
+    let k = val.length;
+    const arr = new Array(k);
+    while (k--) {
+      arr[k] = _deepCopyElement(val[k], depth + 1);
+    }
+    return arr;
+  }
+
+  // we're not cloning non-array & non-plain-object objects because we
+  // don't support them on excalidraw elements yet. If we do, we need to make
+  // sure we start cloning them, so let's warn about it.
+  if (import.meta.env.DEV) {
+    if (
+      objectType !== "[object Object]" &&
+      objectType !== "[object Array]" &&
+      objectType.startsWith("[object ")
+    ) {
+      console.warn(
+        `_deepCloneElement: unexpected object type ${objectType}. This value will not be cloned!`,
+      );
+    }
+  }
+
+  return val;
+};
+
+/**
+ * Clones ExcalidrawElement data structure. Does not regenerate id, nonce, or
+ * any value. The purpose is to to break object references for immutability
+ * reasons, whenever we want to keep the original element, but ensure it's not
+ * mutated.
+ *
+ * Only clones plain objects and arrays. Doesn't clone Date, RegExp, Map, Set,
+ * Typed arrays and other non-null objects.
+ */
+export const deepCopyElement = <T extends ExcalidrawElement>(
+  val: T,
+): Mutable<T> => {
+  return _deepCopyElement(val);
+};
+
+const __test__defineOrigId = (clonedObj: object, origId: string) => {
+  Object.defineProperty(clonedObj, ORIG_ID, {
+    value: origId,
+    writable: false,
+    enumerable: false,
+  });
+};

packages/element/src/elementLink.ts

@@ -0,0 +1,104 @@
+/**
+ * Create and link between shapes.
+ */
+
+import { ELEMENT_LINK_KEY, normalizeLink } from "@excalidraw/common";
+
+import type { AppProps, AppState } from "@excalidraw/excalidraw/types";
+
+import { elementsAreInSameGroup } from "./groups";
+
+import type { ExcalidrawElement } from "./types";
+
+export const defaultGetElementLinkFromSelection: Exclude<
+  AppProps["generateLinkForSelection"],
+  undefined
+> = (id, type) => {
+  const url = window.location.href;
+
+  try {
+    const link = new URL(url);
+    link.searchParams.set(ELEMENT_LINK_KEY, id);
+
+    return normalizeLink(link.toString());
+  } catch (error) {
+    console.error(error);
+  }
+
+  return normalizeLink(url);
+};
+
+export const getLinkIdAndTypeFromSelection = (
+  selectedElements: ExcalidrawElement[],
+  appState: AppState,
+): {
+  id: string;
+  type: "element" | "group";
+} | null => {
+  if (
+    selectedElements.length > 0 &&
+    canCreateLinkFromElements(selectedElements)
+  ) {
+    if (selectedElements.length === 1) {
+      return {
+        id: selectedElements[0].id,
+        type: "element",
+      };
+    }
+
+    if (selectedElements.length > 1) {
+      const selectedGroupId = Object.keys(appState.selectedGroupIds)[0];
+
+      if (selectedGroupId) {
+        return {
+          id: selectedGroupId,
+          type: "group",
+        };
+      }
+      return {
+        id: selectedElements[0].groupIds[0],
+        type: "group",
+      };
+    }
+  }
+
+  return null;
+};
+
+export const canCreateLinkFromElements = (
+  selectedElements: ExcalidrawElement[],
+) => {
+  if (selectedElements.length === 1) {
+    return true;
+  }
+
+  if (selectedElements.length > 1 && elementsAreInSameGroup(selectedElements)) {
+    return true;
+  }
+
+  return false;
+};
+
+export const isElementLink = (url: string) => {
+  try {
+    const _url = new URL(url);
+    return (
+      _url.searchParams.has(ELEMENT_LINK_KEY) &&
+      _url.host === window.location.host
+    );
+  } catch (error) {
+    return false;
+  }
+};
+
+export const parseElementLinkFromURL = (url: string) => {
+  try {
+    const { searchParams } = new URL(url);
+    if (searchParams.has(ELEMENT_LINK_KEY)) {
+      const id = searchParams.get(ELEMENT_LINK_KEY);
+      return id;
+    }
+  } catch {}
+
+  return null;
+};

packages/element/src/embeddable.ts

@@ -0,0 +1,535 @@
+import {
+  FONT_FAMILY,
+  VERTICAL_ALIGN,
+  escapeDoubleQuotes,
+  getFontString,
+} from "@excalidraw/common";
+
+import type { ExcalidrawProps } from "@excalidraw/excalidraw/types";
+import type { MarkRequired } from "@excalidraw/common/utility-types";
+
+import { newTextElement } from "./newElement";
+import { wrapText } from "./textWrapping";
+import { isIframeElement } from "./typeChecks";
+
+import type {
+  ExcalidrawIframeLikeElement,
+  IframeData,
+  NonDeletedExcalidrawElement,
+} from "./types";
+
+type IframeDataWithSandbox = MarkRequired<IframeData, "sandbox">;
+
+const embeddedLinkCache = new Map<string, IframeDataWithSandbox>();
+
+const RE_YOUTUBE =
+  /^(?:http(?:s)?:\/\/)?(?:www\.)?youtu(?:be\.com|\.be)\/(embed\/|watch\?v=|shorts\/|playlist\?list=|embed\/videoseries\?list=)?([a-zA-Z0-9_-]+)/;
+
+const RE_VIMEO =
+  /^(?:http(?:s)?:\/\/)?(?:(?:w){3}\.)?(?:player\.)?vimeo\.com\/(?:video\/)?([^?\s]+)(?:\?.*)?$/;
+const RE_FIGMA = /^https:\/\/(?:www\.)?figma\.com/;
+
+const RE_GH_GIST = /^https:\/\/gist\.github\.com\/([\w_-]+)\/([\w_-]+)/;
+const RE_GH_GIST_EMBED =
+  /^<script[\s\S]*?\ssrc=["'](https:\/\/gist\.github\.com\/.*?)\.js["']/i;
+
+const RE_MSFORMS = /^(?:https?:\/\/)?forms\.microsoft\.com\//;
+
+// not anchored to start to allow <blockquote> twitter embeds
+const RE_TWITTER =
+  /(?:https?:\/\/)?(?:(?:w){3}\.)?(?:twitter|x)\.com\/[^/]+\/status\/(\d+)/;
+const RE_TWITTER_EMBED =
+  /^<blockquote[\s\S]*?\shref=["'](https?:\/\/(?:twitter|x)\.com\/[^"']*)/i;
+
+const RE_VALTOWN =
+  /^https:\/\/(?:www\.)?val\.town\/(v|embed)\/[a-zA-Z_$][0-9a-zA-Z_$]+\.[a-zA-Z_$][0-9a-zA-Z_$]+/;
+
+const RE_GENERIC_EMBED =
+  /^<(?:iframe|blockquote)[\s\S]*?\s(?:src|href)=["']([^"']*)["'][\s\S]*?>$/i;
+
+const RE_GIPHY =
+  /giphy.com\/(?:clips|embed|gifs)\/[a-zA-Z0-9]*?-?([a-zA-Z0-9]+)(?:[^a-zA-Z0-9]|$)/;
+
+const RE_REDDIT =
+  /^(?:http(?:s)?:\/\/)?(?:www\.)?reddit\.com\/r\/([a-zA-Z0-9_]+)\/comments\/([a-zA-Z0-9_]+)\/([a-zA-Z0-9_]+)\/?(?:\?[^#\s]*)?(?:#[^\s]*)?$/;
+
+const RE_REDDIT_EMBED =
+  /^<blockquote[\s\S]*?\shref=["'](https?:\/\/(?:www\.)?reddit\.com\/[^"']*)/i;
+
+const parseYouTubeLikeTimestamp = (url: string): number => {
+  let timeParam: string | null | undefined;
+
+  try {
+    const urlObj = new URL(url.startsWith("http") ? url : `https://${url}`);
+    timeParam =
+      urlObj.searchParams.get("t") || urlObj.searchParams.get("start");
+  } catch (error) {
+    const timeMatch = url.match(/[?&#](?:t|start)=([^&#\s]+)/);
+    timeParam = timeMatch?.[1];
+  }
+
+  if (!timeParam) {
+    return 0;
+  }
+
+  if (/^\d+$/.test(timeParam)) {
+    return parseInt(timeParam, 10);
+  }
+
+  const timeMatch = timeParam.match(/^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/);
+  if (!timeMatch) {
+    return 0;
+  }
+
+  const [, hours = "0", minutes = "0", seconds = "0"] = timeMatch;
+  return parseInt(hours) * 3600 + parseInt(minutes) * 60 + parseInt(seconds);
+};
+
+const parseGoogleDriveVideoLink = (
+  url: string,
+): { fileId: string; resourceKey?: string; timestamp?: number } | null => {
+  try {
+    const urlObj = new URL(url.startsWith("http") ? url : `https://${url}`);
+    const hostname = urlObj.hostname.replace(/^www\./, "");
+    if (hostname !== "drive.google.com") {
+      return null;
+    }
+
+    let fileId: string | null = null;
+    const pathMatch = urlObj.pathname.match(/^\/file\/d\/([^/]+)(?:\/|$)/);
+    if (pathMatch?.[1]) {
+      fileId = pathMatch[1];
+    } else if (urlObj.pathname === "/open" || urlObj.pathname === "/uc") {
+      // Shared Drive links can be emitted as:
+      // - /open?id=<fileId> (common "open in Drive" format)
+      // - /uc?...&id=<fileId> (download/export endpoint often seen in copied links)
+      fileId = urlObj.searchParams.get("id");
+    }
+
+    if (!fileId || !/^[a-zA-Z0-9_-]+$/.test(fileId)) {
+      return null;
+    }
+
+    // Some Drive share links include `resourcekey` for access to link-shared
+    // files; preserve it in the preview URL so embeds keep working.
+    const resourceKey = urlObj.searchParams.get("resourcekey");
+    const timestamp = parseYouTubeLikeTimestamp(urlObj.toString());
+
+    return {
+      fileId,
+      resourceKey:
+        resourceKey && /^[a-zA-Z0-9_-]+$/.test(resourceKey)
+          ? resourceKey
+          : undefined,
+      // Drive accepts YouTube-like `t` formats (e.g. `t=90`, `t=1m30s`);
+      // normalize to seconds for a stable preview URL.
+      timestamp: timestamp > 0 ? timestamp : undefined,
+    };
+  } catch (error) {
+    return null;
+  }
+};
+
+const ALLOWED_DOMAINS = new Set([
+  "youtube.com",
+  "youtu.be",
+  "vimeo.com",
+  "player.vimeo.com",
+  "drive.google.com",
+  "figma.com",
+  "link.excalidraw.com",
+  "gist.github.com",
+  "twitter.com",
+  "x.com",
+  "*.simplepdf.eu",
+  "stackblitz.com",
+  "val.town",
+  "giphy.com",
+  "reddit.com",
+  "forms.microsoft.com",
+]);
+
+const ALLOW_SAME_ORIGIN = new Set([
+  "youtube.com",
+  "youtu.be",
+  "vimeo.com",
+  "player.vimeo.com",
+  "drive.google.com",
+  "figma.com",
+  "twitter.com",
+  "x.com",
+  "*.simplepdf.eu",
+  "stackblitz.com",
+  "reddit.com",
+  "forms.microsoft.com",
+]);
+
+export const createSrcDoc = (body: string) => {
+  return `<html><body>${body}</body></html>`;
+};
+
+export const getEmbedLink = (
+  link: string | null | undefined,
+): IframeDataWithSandbox | null => {
+  if (!link) {
+    return null;
+  }
+
+  if (embeddedLinkCache.has(link)) {
+    return embeddedLinkCache.get(link)!;
+  }
+
+  const originalLink = link;
+
+  const allowSameOrigin = ALLOW_SAME_ORIGIN.has(
+    matchHostname(link, ALLOW_SAME_ORIGIN) || "",
+  );
+
+  let type: "video" | "generic" = "generic";
+  let aspectRatio = { w: 560, h: 840 };
+  const ytLink = link.match(RE_YOUTUBE);
+  if (ytLink?.[2]) {
+    const startTime = parseYouTubeLikeTimestamp(originalLink);
+    const time = startTime > 0 ? `&start=${startTime}` : ``;
+    const isPortrait = link.includes("shorts");
+    type = "video";
+    switch (ytLink[1]) {
+      case "embed/":
+      case "watch?v=":
+      case "shorts/":
+        link = `https://www.youtube.com/embed/${ytLink[2]}?enablejsapi=1${time}`;
+        break;
+      case "playlist?list=":
+      case "embed/videoseries?list=":
+        link = `https://www.youtube.com/embed/videoseries?list=${ytLink[2]}&enablejsapi=1${time}`;
+        break;
+      default:
+        link = `https://www.youtube.com/embed/${ytLink[2]}?enablejsapi=1${time}`;
+        break;
+    }
+    aspectRatio = isPortrait ? { w: 315, h: 560 } : { w: 560, h: 315 };
+    embeddedLinkCache.set(originalLink, {
+      link,
+      intrinsicSize: aspectRatio,
+      type,
+      sandbox: { allowSameOrigin },
+    });
+    return {
+      link,
+      intrinsicSize: aspectRatio,
+      type,
+      sandbox: { allowSameOrigin },
+    };
+  }
+
+  const vimeoLink = link.match(RE_VIMEO);
+  if (vimeoLink?.[1]) {
+    const target = vimeoLink?.[1];
+    const error = !/^\d+$/.test(target)
+      ? new URIError("Invalid embed link format")
+      : undefined;
+    type = "video";
+    link = `https://player.vimeo.com/video/${target}?api=1`;
+    aspectRatio = { w: 560, h: 315 };
+    //warning deliberately ommited so it is displayed only once per link
+    //same link next time will be served from cache
+    embeddedLinkCache.set(originalLink, {
+      link,
+      intrinsicSize: aspectRatio,
+      type,
+      sandbox: { allowSameOrigin },
+    });
+    return {
+      link,
+      intrinsicSize: aspectRatio,
+      type,
+      error,
+      sandbox: { allowSameOrigin },
+    };
+  }
+
+  const googleDriveVideo = parseGoogleDriveVideoLink(link);
+  if (googleDriveVideo) {
+    type = "video";
+    const searchParams = new URLSearchParams();
+    if (googleDriveVideo.resourceKey) {
+      searchParams.set("resourcekey", googleDriveVideo.resourceKey);
+    }
+    if (googleDriveVideo.timestamp) {
+      searchParams.set("t", `${googleDriveVideo.timestamp}`);
+    }
+
+    const search = searchParams.toString();
+    link = `https://drive.google.com/file/d/${googleDriveVideo.fileId}/preview${
+      search ? `?${search}` : ""
+    }`;
+    aspectRatio = { w: 560, h: 315 };
+    embeddedLinkCache.set(originalLink, {
+      link,
+      intrinsicSize: aspectRatio,
+      type,
+      sandbox: { allowSameOrigin },
+    });
+    return {
+      link,
+      intrinsicSize: aspectRatio,
+      type,
+      sandbox: { allowSameOrigin },
+    };
+  }
+
+  const figmaLink = link.match(RE_FIGMA);
+  if (figmaLink) {
+    type = "generic";
+    link = `https://www.figma.com/embed?embed_host=share&url=${encodeURIComponent(
+      link,
+    )}`;
+    aspectRatio = { w: 550, h: 550 };
+    embeddedLinkCache.set(originalLink, {
+      link,
+      intrinsicSize: aspectRatio,
+      type,
+      sandbox: { allowSameOrigin },
+    });
+    return {
+      link,
+      intrinsicSize: aspectRatio,
+      type,
+      sandbox: { allowSameOrigin },
+    };
+  }
+
+  const valLink = link.match(RE_VALTOWN);
+  if (valLink) {
+    link =
+      valLink[1] === "embed" ? valLink[0] : valLink[0].replace("/v", "/embed");
+    embeddedLinkCache.set(originalLink, {
+      link,
+      intrinsicSize: aspectRatio,
+      type,
+      sandbox: { allowSameOrigin },
+    });
+    return {
+      link,
+      intrinsicSize: aspectRatio,
+      type,
+      sandbox: { allowSameOrigin },
+    };
+  }
+
+  if (RE_MSFORMS.test(link) && !link.includes("embed=true")) {
+    link += link.includes("?") ? "&embed=true" : "?embed=true";
+  }
+
+  if (RE_TWITTER.test(link)) {
+    const postId = link.match(RE_TWITTER)![1];
+    // the embed srcdoc still supports twitter.com domain only.
+    // Note that we don't attempt to parse the username as it can consist of
+    // non-latin1 characters, and the username in the url can be set to anything
+    // without affecting the embed.
+    const safeURL = escapeDoubleQuotes(
+      `https://twitter.com/x/status/${postId}`,
+    );
+
+    const ret: IframeDataWithSandbox = {
+      type: "document",
+      srcdoc: (theme: string) =>
+        createSrcDoc(
+          `<blockquote class="twitter-tweet" data-dnt="true" data-theme="${theme}"><a href="${safeURL}"></a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>`,
+        ),
+      intrinsicSize: { w: 480, h: 480 },
+      sandbox: { allowSameOrigin },
+    };
+    embeddedLinkCache.set(originalLink, ret);
+    return ret;
+  }
+
+  if (RE_REDDIT.test(link)) {
+    const [, page, postId, title] = link.match(RE_REDDIT)!;
+    const safeURL = escapeDoubleQuotes(
+      `https://reddit.com/r/${page}/comments/${postId}/${title}`,
+    );
+    const ret: IframeDataWithSandbox = {
+      type: "document",
+      srcdoc: (theme: string) =>
+        createSrcDoc(
+          `<blockquote class="reddit-embed-bq" data-embed-theme="${theme}"><a href="${safeURL}"></a><br></blockquote><script async="" src="https://embed.reddit.com/widgets.js" charset="UTF-8"></script>`,
+        ),
+      intrinsicSize: { w: 480, h: 480 },
+      sandbox: { allowSameOrigin },
+    };
+    embeddedLinkCache.set(originalLink, ret);
+    return ret;
+  }
+
+  if (RE_GH_GIST.test(link)) {
+    const [, user, gistId] = link.match(RE_GH_GIST)!;
+    const safeURL = escapeDoubleQuotes(
+      `https://gist.github.com/${user}/${gistId}`,
+    );
+    const ret: IframeDataWithSandbox = {
+      type: "document",
+      srcdoc: () =>
+        createSrcDoc(`
+          <script src="${safeURL}.js"></script>
+          <style type="text/css">
+            * { margin: 0px; }
+            table, .gist { height: 100%; }
+            .gist .gist-file { height: calc(100vh - 2px); padding: 0px; display: grid; grid-template-rows: 1fr auto; }
+          </style>
+        `),
+      intrinsicSize: { w: 550, h: 720 },
+      sandbox: { allowSameOrigin },
+    };
+    embeddedLinkCache.set(link, ret);
+    return ret;
+  }
+
+  embeddedLinkCache.set(link, {
+    link,
+    intrinsicSize: aspectRatio,
+    type,
+    sandbox: { allowSameOrigin },
+  });
+  return {
+    link,
+    intrinsicSize: aspectRatio,
+    type,
+    sandbox: { allowSameOrigin },
+  };
+};
+
+export const createPlaceholderEmbeddableLabel = (
+  element: ExcalidrawIframeLikeElement,
+): NonDeletedExcalidrawElement => {
+  let text: string;
+  if (isIframeElement(element)) {
+    text = "IFrame element";
+  } else {
+    text =
+      !element.link || element?.link === "" ? "Empty Web-Embed" : element.link;
+  }
+
+  const fontSize = Math.max(
+    Math.min(element.width / 2, element.width / text.length),
+    element.width / 30,
+  );
+  const fontFamily = FONT_FAMILY.Helvetica;
+
+  const fontString = getFontString({
+    fontSize,
+    fontFamily,
+  });
+
+  return newTextElement({
+    x: element.x + element.width / 2,
+    y: element.y + element.height / 2,
+    strokeColor:
+      element.strokeColor !== "transparent" ? element.strokeColor : "black",
+    backgroundColor: "transparent",
+    fontFamily,
+    fontSize,
+    text: wrapText(text, fontString, element.width - 20),
+    textAlign: "center",
+    verticalAlign: VERTICAL_ALIGN.MIDDLE,
+    angle: element.angle ?? 0,
+  });
+};
+
+const matchHostname = (
+  url: string,
+  /** using a Set assumes it already contains normalized bare domains */
+  allowedHostnames: Set<string> | string,
+): string | null => {
+  try {
+    const { hostname } = new URL(url);
+
+    const bareDomain = hostname.replace(/^www\./, "");
+
+    if (allowedHostnames instanceof Set) {
+      if (ALLOWED_DOMAINS.has(bareDomain)) {
+        return bareDomain;
+      }
+
+      const bareDomainWithFirstSubdomainWildcarded = bareDomain.replace(
+        /^([^.]+)/,
+        "*",
+      );
+      if (ALLOWED_DOMAINS.has(bareDomainWithFirstSubdomainWildcarded)) {
+        return bareDomainWithFirstSubdomainWildcarded;
+      }
+      return null;
+    }
+
+    const bareAllowedHostname = allowedHostnames.replace(/^www\./, "");
+    if (bareDomain === bareAllowedHostname) {
+      return bareAllowedHostname;
+    }
+  } catch (error) {
+    // ignore
+  }
+  return null;
+};
+
+export const maybeParseEmbedSrc = (str: string): string => {
+  const twitterMatch = str.match(RE_TWITTER_EMBED);
+  if (twitterMatch && twitterMatch.length === 2) {
+    return twitterMatch[1];
+  }
+
+  const redditMatch = str.match(RE_REDDIT_EMBED);
+  if (redditMatch && redditMatch.length === 2) {
+    return redditMatch[1];
+  }
+
+  const gistMatch = str.match(RE_GH_GIST_EMBED);
+  if (gistMatch && gistMatch.length === 2) {
+    return gistMatch[1];
+  }
+
+  if (RE_GIPHY.test(str)) {
+    return `https://giphy.com/embed/${RE_GIPHY.exec(str)![1]}`;
+  }
+
+  const match = str.match(RE_GENERIC_EMBED);
+  if (match && match.length === 2) {
+    return match[1];
+  }
+
+  return str;
+};
+
+export const embeddableURLValidator = (
+  url: string | null | undefined,
+  validateEmbeddable: ExcalidrawProps["validateEmbeddable"],
+): boolean => {
+  if (!url) {
+    return false;
+  }
+  if (validateEmbeddable != null) {
+    if (typeof validateEmbeddable === "function") {
+      const ret = validateEmbeddable(url);
+      // if return value is undefined, leave validation to default
+      if (typeof ret === "boolean") {
+        return ret;
+      }
+    } else if (typeof validateEmbeddable === "boolean") {
+      return validateEmbeddable;
+    } else if (validateEmbeddable instanceof RegExp) {
+      return validateEmbeddable.test(url);
+    } else if (Array.isArray(validateEmbeddable)) {
+      for (const domain of validateEmbeddable) {
+        if (domain instanceof RegExp) {
+          if (url.match(domain)) {
+            return true;
+          }
+        } else if (matchHostname(url, domain)) {
+          return true;
+        }
+      }
+      return false;
+    }
+  }
+
+  return !!matchHostname(url, ALLOWED_DOMAINS);
+};

packages/element/src/flowchart.ts

@@ -0,0 +1,763 @@
+import { invariant, toBrandedType, type Bounds } from "@excalidraw/common";
+
+import {
+  clamp,
+  type GlobalPoint,
+  pointFrom,
+  type LocalPoint,
+} from "@excalidraw/math";
+
+import type {
+  AppState,
+  PendingExcalidrawElements,
+} from "@excalidraw/excalidraw/types";
+
+import { bindBindingElement } from "./binding";
+import { updateElbowArrowPoints } from "./elbowArrow";
+import {
+  HEADING_DOWN,
+  HEADING_LEFT,
+  HEADING_RIGHT,
+  HEADING_UP,
+  compareHeading,
+  headingForPointFromElement,
+  type Heading,
+} from "./heading";
+import { LinearElementEditor } from "./linearElementEditor";
+import { mutateElement } from "./mutateElement";
+import {
+  newArrowElement,
+  newElement,
+  newStickyNoteElement,
+} from "./newElement";
+import { aabbForElement } from "./bounds";
+import { elementsAreInFrameBounds, elementOverlapsWithFrame } from "./frame";
+import {
+  isBindableElement,
+  isElbowArrow,
+  isFrameElement,
+  isFlowchartNodeElement,
+} from "./typeChecks";
+import {
+  type NonDeleted,
+  type ElementsMap,
+  type ExcalidrawBindableElement,
+  type ExcalidrawElement,
+  type ExcalidrawFlowchartNodeElement,
+  type NonDeletedExcalidrawElement,
+  type NonDeletedSceneElementsMap,
+  type Ordered,
+  type OrderedExcalidrawElement,
+} from "./types";
+
+import type { Scene } from "./Scene";
+
+export type LinkDirection = "up" | "right" | "down" | "left";
+
+const VERTICAL_OFFSET = 100;
+const HORIZONTAL_OFFSET = 100;
+
+type Interval = { start: number; end: number };
+
+const mergeIntervals = (intervals: Interval[]): Interval[] => {
+  const sorted = [...intervals].sort((a, b) => a.start - b.start);
+  const merged: Interval[] = [];
+
+  for (const interval of sorted) {
+    const last = merged[merged.length - 1];
+    if (last && interval.start <= last.end) {
+      last.end = Math.max(last.end, interval.end);
+    } else {
+      merged.push({ ...interval });
+    }
+  }
+
+  return merged;
+};
+
+const intervalIsFree = (start: number, size: number, occupied: Interval[]) =>
+  occupied.every((o) => start + size <= o.start || start >= o.end);
+
+// Nearest `start` for a segment of `size` avoiding every occupied interval,
+// searching both sides of `ideal`; a tie resolves toward the positive side.
+const findNearestFreeSlot = (
+  ideal: number,
+  size: number,
+  occupied: Interval[],
+): number => {
+  if (intervalIsFree(ideal, size, occupied)) {
+    return ideal;
+  }
+
+  const gapStarts = [-Infinity, ...occupied.map((o) => o.end)];
+  const gapEnds = [...occupied.map((o) => o.start), Infinity];
+
+  let best = ideal;
+  let bestDistance = Infinity;
+  for (let i = 0; i < gapStarts.length; i++) {
+    if (gapEnds[i] - gapStarts[i] < size) {
+      continue;
+    }
+    const start = clamp(ideal, gapStarts[i], gapEnds[i] - size);
+    const distance = Math.abs(start - ideal);
+    if (distance <= bestDistance) {
+      best = start;
+      bestDistance = distance;
+    }
+  }
+
+  return best;
+};
+
+// Walk the arrow bindings to collect every node that belongs to the same
+// flowchart as `node` — the whole connected component acts as the obstacle
+// set during placement (#8518).
+const getConnectedFlowchartNodes = (
+  node: ExcalidrawBindableElement,
+  elementsMap: ElementsMap,
+): ExcalidrawBindableElement[] => {
+  const arrows = [...elementsMap.values()].filter(isElbowArrow);
+  const visited = new Set<string>([node.id]);
+  const queue: string[] = [node.id];
+  const connected: ExcalidrawBindableElement[] = [];
+
+  while (queue.length > 0) {
+    const currentId = queue.shift()!;
+    for (const arrow of arrows) {
+      const startId = arrow.startBinding?.elementId;
+      const endId = arrow.endBinding?.elementId;
+
+      let neighborId: string | undefined;
+      if (startId === currentId) {
+        neighborId = endId;
+      } else if (endId === currentId) {
+        neighborId = startId;
+      }
+
+      if (!neighborId || visited.has(neighborId)) {
+        continue;
+      }
+
+      visited.add(neighborId);
+      const neighbor = elementsMap.get(neighborId);
+      if (neighbor && isBindableElement(neighbor)) {
+        connected.push(neighbor);
+        queue.push(neighborId);
+      }
+    }
+  }
+
+  return connected;
+};
+
+// Place a cluster of `count` equally-sized nodes next to `parent`:
+// - the primary axis (the creation direction) is fixed at exactly one gap
+//   away from the parent, forming a search band the cluster will occupy
+// - along the cross axis the cluster slides into the free slot nearest the
+//   parent-centered ideal, treating band obstacles as immovable
+// - `stickyCrossStart` anchors an already-visible pending cluster: growing it
+//   extends it at either end so the existing pending nodes keep their
+//   positions, unless the grown cluster no longer fits there
+const placeCluster = (
+  parent: ExcalidrawFlowchartNodeElement,
+  direction: LinkDirection,
+  count: number,
+  obstacles: readonly Bounds[],
+  stickyCrossStart: number | null,
+): { positions: { x: number; y: number }[]; crossStart: number } => {
+  const horizontal = direction === "left" || direction === "right";
+  // INSIGHT: new nodes copy the parent's dimensions
+  const nodePrimarySize = horizontal ? parent.width : parent.height;
+  const nodeCrossSize = horizontal ? parent.height : parent.width;
+  const primaryGap = horizontal ? HORIZONTAL_OFFSET : VERTICAL_OFFSET;
+  const crossGap = horizontal ? VERTICAL_OFFSET : HORIZONTAL_OFFSET;
+
+  const parentPrimaryStart = horizontal ? parent.x : parent.y;
+  const parentCrossCenter = horizontal
+    ? parent.y + parent.height / 2
+    : parent.x + parent.width / 2;
+
+  const primaryStart =
+    direction === "right" || direction === "down"
+      ? parentPrimaryStart + nodePrimarySize + primaryGap
+      : parentPrimaryStart - primaryGap - nodePrimarySize;
+
+  // cross-axis intervals of the obstacles sharing the band, inflated so the
+  // cluster keeps at least one gap of clearance
+  const occupied = mergeIntervals(
+    obstacles
+      .filter((bounds) => {
+        const start = horizontal ? bounds[0] : bounds[1];
+        const end = horizontal ? bounds[2] : bounds[3];
+        return start < primaryStart + nodePrimarySize && end > primaryStart;
+      })
+      .map((bounds) => ({
+        start: (horizontal ? bounds[1] : bounds[0]) - crossGap,
+        end: (horizontal ? bounds[3] : bounds[2]) + crossGap,
+      })),
+  );
+
+  const step = nodeCrossSize + crossGap;
+  const clusterCrossSize = count * nodeCrossSize + (count - 1) * crossGap;
+
+  const anchoredStart =
+    stickyCrossStart === null
+      ? null
+      : [stickyCrossStart, stickyCrossStart - step]
+          .filter((start) => intervalIsFree(start, clusterCrossSize, occupied))
+          .sort(
+            (a, b) =>
+              Math.abs(a + clusterCrossSize / 2 - parentCrossCenter) -
+              Math.abs(b + clusterCrossSize / 2 - parentCrossCenter),
+          )[0] ?? null;
+
+  const crossStart =
+    anchoredStart ??
+    findNearestFreeSlot(
+      parentCrossCenter - clusterCrossSize / 2,
+      clusterCrossSize,
+      occupied,
+    );
+
+  const positions = Array.from({ length: count }, (_, index) => {
+    const cross = crossStart + index * step;
+    return horizontal
+      ? { x: primaryStart, y: cross }
+      : { x: cross, y: primaryStart };
+  });
+
+  return { positions, crossStart };
+};
+
+const cloneFlowchartNode = (
+  template: ExcalidrawFlowchartNodeElement,
+  x: number,
+  y: number,
+) => {
+  const commonNodeProps = {
+    x,
+    y,
+    width: template.width,
+    height: template.height,
+    roundness: template.roundness,
+    roughness: template.roughness,
+    backgroundColor: template.backgroundColor,
+    strokeColor: template.strokeColor,
+    strokeWidth: template.strokeWidth,
+    opacity: template.opacity,
+    fillStyle: template.fillStyle,
+    strokeStyle: template.strokeStyle,
+  };
+
+  const node =
+    template.type === "stickynote"
+      ? newStickyNoteElement({
+          type: "stickynote",
+          ...commonNodeProps,
+          baseHeight: template.baseHeight,
+        })
+      : newElement({
+          type: template.type,
+          ...commonNodeProps,
+        });
+
+  invariant(
+    isFlowchartNodeElement(node),
+    "not an ExcalidrawFlowchartNodeElement",
+  );
+
+  return node;
+};
+
+export const addNewNodes = (
+  startNode: NonDeleted<ExcalidrawFlowchartNodeElement>,
+  appState: AppState,
+  direction: LinkDirection,
+  scene: Scene,
+  numberOfNodes: number,
+  stickyCrossStart: number | null = null,
+) => {
+  const elementsMap = scene.getNonDeletedElementsMap();
+  const obstacles = getConnectedFlowchartNodes(startNode, elementsMap).map(
+    (node) => aabbForElement(node, elementsMap),
+  );
+
+  const { positions, crossStart } = placeCluster(
+    startNode,
+    direction,
+    numberOfNodes,
+    obstacles,
+    stickyCrossStart,
+  );
+
+  const nodes: NonDeletedExcalidrawElement[] = [];
+  for (const position of positions) {
+    const nextNode = cloneFlowchartNode(startNode, position.x, position.y);
+    const bindingArrow = createBindingArrow(
+      startNode,
+      nextNode,
+      direction,
+      appState,
+      scene,
+    );
+
+    nodes.push(nextNode, bindingArrow);
+  }
+
+  return { nodes, crossStart };
+};
+
+const createBindingArrow = (
+  startBindingElement: NonDeleted<ExcalidrawFlowchartNodeElement>,
+  endBindingElement: NonDeleted<ExcalidrawFlowchartNodeElement>,
+  direction: LinkDirection,
+  appState: AppState,
+  scene: Scene,
+) => {
+  let startX: number;
+  let startY: number;
+
+  const PADDING = 6;
+
+  switch (direction) {
+    case "up": {
+      startX = startBindingElement.x + startBindingElement.width / 2;
+      startY = startBindingElement.y - PADDING;
+      break;
+    }
+    case "down": {
+      startX = startBindingElement.x + startBindingElement.width / 2;
+      startY = startBindingElement.y + startBindingElement.height + PADDING;
+      break;
+    }
+    case "right": {
+      startX = startBindingElement.x + startBindingElement.width + PADDING;
+      startY = startBindingElement.y + startBindingElement.height / 2;
+      break;
+    }
+    case "left": {
+      startX = startBindingElement.x - PADDING;
+      startY = startBindingElement.y + startBindingElement.height / 2;
+      break;
+    }
+  }
+
+  let endX: number;
+  let endY: number;
+
+  switch (direction) {
+    case "up": {
+      endX = endBindingElement.x + endBindingElement.width / 2 - startX;
+      endY = endBindingElement.y + endBindingElement.height - startY + PADDING;
+      break;
+    }
+    case "down": {
+      endX = endBindingElement.x + endBindingElement.width / 2 - startX;
+      endY = endBindingElement.y - startY - PADDING;
+      break;
+    }
+    case "right": {
+      endX = endBindingElement.x - startX - PADDING;
+      endY = endBindingElement.y - startY + endBindingElement.height / 2;
+      break;
+    }
+    case "left": {
+      endX = endBindingElement.x + endBindingElement.width - startX + PADDING;
+      endY = endBindingElement.y - startY + endBindingElement.height / 2;
+      break;
+    }
+  }
+
+  const bindingArrow = newArrowElement({
+    type: "arrow",
+    x: startX,
+    y: startY,
+    startArrowhead: null,
+    endArrowhead: appState.currentItemEndArrowhead,
+    strokeColor: startBindingElement.strokeColor,
+    strokeStyle: startBindingElement.strokeStyle,
+    strokeWidth: startBindingElement.strokeWidth,
+    opacity: startBindingElement.opacity,
+    roughness: startBindingElement.roughness,
+    points: [pointFrom(0, 0), pointFrom(endX, endY)],
+    elbowed: true,
+  });
+
+  const elementsMap = scene.getNonDeletedElementsMap();
+
+  bindBindingElement(
+    bindingArrow,
+    startBindingElement,
+    "orbit",
+    "start",
+    scene,
+  );
+  bindBindingElement(bindingArrow, endBindingElement, "orbit", "end", scene);
+
+  const changedElements = new Map<string, OrderedExcalidrawElement>();
+  changedElements.set(
+    startBindingElement.id,
+    startBindingElement as OrderedExcalidrawElement,
+  );
+  changedElements.set(
+    endBindingElement.id,
+    endBindingElement as OrderedExcalidrawElement,
+  );
+  changedElements.set(
+    bindingArrow.id,
+    bindingArrow as OrderedExcalidrawElement,
+  );
+
+  LinearElementEditor.movePoints(
+    bindingArrow,
+    scene,
+    new Map([
+      [
+        1,
+        {
+          point: bindingArrow.points[1],
+        },
+      ],
+    ]),
+  );
+
+  const update = updateElbowArrowPoints(
+    bindingArrow,
+    toBrandedType<NonDeletedSceneElementsMap>(
+      new Map([
+        ...elementsMap.entries(),
+        [startBindingElement.id, startBindingElement],
+        [endBindingElement.id, endBindingElement],
+        [bindingArrow.id, bindingArrow],
+      ] as [string, Ordered<NonDeletedExcalidrawElement>][]),
+    ),
+    { points: bindingArrow.points },
+  );
+
+  return {
+    ...bindingArrow,
+    ...update,
+    isDeleted: bindingArrow.isDeleted,
+  };
+};
+
+export class FlowChartNavigator {
+  isExploring: boolean = false;
+  // nodes that are ONE link away (successor and predecessor both included)
+  private sameLevelNodes: ExcalidrawElement[] = [];
+  private sameLevelIndex: number = 0;
+  // set it to the opposite of the defalut creation direction
+  private direction: LinkDirection | null = null;
+  // for speedier navigation
+  private visitedNodes: Set<ExcalidrawElement["id"]> = new Set();
+
+  clear() {
+    this.isExploring = false;
+    this.sameLevelNodes = [];
+    this.sameLevelIndex = 0;
+    this.direction = null;
+    this.visitedNodes.clear();
+  }
+
+  exploreByDirection(
+    element: ExcalidrawElement,
+    elementsMap: ElementsMap,
+    direction: LinkDirection,
+  ): ExcalidrawElement["id"] | null {
+    if (!isBindableElement(element)) {
+      return null;
+    }
+
+    // clear if going at a different direction
+    if (direction !== this.direction) {
+      this.clear();
+    }
+
+    // add the current node to the visited
+    if (!this.visitedNodes.has(element.id)) {
+      this.visitedNodes.add(element.id);
+    }
+
+    /**
+     * CASE:
+     * - already started exploring, AND
+     * - there are multiple nodes at the same level, AND
+     * - still going at the same direction, AND
+     *
+     * RESULT:
+     * - loop through nodes at the same level
+     *
+     * WHY:
+     * - provides user the capability to loop through nodes at the same level
+     */
+    if (
+      this.isExploring &&
+      direction === this.direction &&
+      this.sameLevelNodes.length > 1
+    ) {
+      this.sameLevelIndex =
+        (this.sameLevelIndex + 1) % this.sameLevelNodes.length;
+
+      return this.sameLevelNodes[this.sameLevelIndex].id;
+    }
+
+    const nodes = [
+      ...FlowChartNavigator.getSuccessors(element, elementsMap, direction),
+      ...FlowChartNavigator.getPredecessors(element, elementsMap, direction),
+    ];
+
+    /**
+     * CASE:
+     * - just started exploring at the given direction
+     *
+     * RESULT:
+     * - go to the first node in the given direction
+     */
+    if (nodes.length > 0) {
+      this.sameLevelIndex = 0;
+      this.isExploring = true;
+      this.sameLevelNodes = nodes;
+      this.direction = direction;
+      this.visitedNodes.add(nodes[0].id);
+
+      return nodes[0].id;
+    }
+
+    /**
+     * CASE:
+     * - (just started exploring or still going at the same direction) OR
+     * - there're no nodes at the given direction
+     *
+     * RESULT:
+     * - go to some other unvisited linked node
+     *
+     * WHY:
+     * - provide a speedier navigation from a given node to some predecessor
+     *   without the user having to change arrow key
+     */
+    if (direction === this.direction || !this.isExploring) {
+      if (!this.isExploring) {
+        // just started and no other nodes at the given direction
+        // so the current node is technically the first visited node
+        // (this is needed so that we don't get stuck between looping through )
+        this.visitedNodes.add(element.id);
+      }
+
+      const otherDirections: LinkDirection[] = [
+        "up",
+        "right",
+        "down",
+        "left",
+      ].filter((dir): dir is LinkDirection => dir !== direction);
+
+      const otherLinkedNodes = otherDirections
+        .map((dir) => [
+          ...FlowChartNavigator.getSuccessors(element, elementsMap, dir),
+          ...FlowChartNavigator.getPredecessors(element, elementsMap, dir),
+        ])
+        .flat()
+        .filter((linkedNode) => !this.visitedNodes.has(linkedNode.id));
+
+      for (const linkedNode of otherLinkedNodes) {
+        if (!this.visitedNodes.has(linkedNode.id)) {
+          this.visitedNodes.add(linkedNode.id);
+          this.isExploring = true;
+          this.direction = direction;
+          return linkedNode.id;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  private static getNodeRelatives(
+    type: "predecessors" | "successors",
+    node: ExcalidrawBindableElement,
+    elementsMap: ElementsMap,
+    direction: LinkDirection,
+  ) {
+    const items = [...elementsMap.values()].reduce(
+      (
+        acc: { relative: ExcalidrawBindableElement; heading: Heading }[],
+        el,
+      ) => {
+        let oppositeBinding;
+        if (
+          isElbowArrow(el) &&
+          // we want check existence of the opposite binding, in the direction
+          // we're interested in
+          (oppositeBinding =
+            el[type === "predecessors" ? "startBinding" : "endBinding"]) &&
+          // similarly, we need to filter only arrows bound to target node
+          el[type === "predecessors" ? "endBinding" : "startBinding"]
+            ?.elementId === node.id
+        ) {
+          const relative = elementsMap.get(oppositeBinding.elementId);
+
+          if (!relative) {
+            return acc;
+          }
+
+          invariant(
+            isBindableElement(relative),
+            "not an ExcalidrawBindableElement",
+          );
+
+          const edgePoint = (
+            type === "predecessors" ? el.points[el.points.length - 1] : [0, 0]
+          ) as Readonly<LocalPoint>;
+
+          const heading = headingForPointFromElement(
+            node,
+            aabbForElement(node, elementsMap),
+            [edgePoint[0] + el.x, edgePoint[1] + el.y] as Readonly<GlobalPoint>,
+          );
+
+          acc.push({
+            relative,
+            heading,
+          });
+        }
+        return acc;
+      },
+      [],
+    );
+
+    switch (direction) {
+      case "up":
+        return items
+          .filter((item) => compareHeading(item.heading, HEADING_UP))
+          .map((item) => item.relative);
+      case "down":
+        return items
+          .filter((item) => compareHeading(item.heading, HEADING_DOWN))
+          .map((item) => item.relative);
+      case "right":
+        return items
+          .filter((item) => compareHeading(item.heading, HEADING_RIGHT))
+          .map((item) => item.relative);
+      case "left":
+        return items
+          .filter((item) => compareHeading(item.heading, HEADING_LEFT))
+          .map((item) => item.relative);
+    }
+  }
+
+  private static getSuccessors(
+    node: ExcalidrawBindableElement,
+    elementsMap: ElementsMap,
+    direction: LinkDirection,
+  ) {
+    return FlowChartNavigator.getNodeRelatives(
+      "successors",
+      node,
+      elementsMap,
+      direction,
+    );
+  }
+
+  private static getPredecessors(
+    node: ExcalidrawBindableElement,
+    elementsMap: ElementsMap,
+    direction: LinkDirection,
+  ) {
+    return FlowChartNavigator.getNodeRelatives(
+      "predecessors",
+      node,
+      elementsMap,
+      direction,
+    );
+  }
+}
+
+export class FlowChartCreator {
+  isCreatingChart: boolean = false;
+  private numberOfNodes: number = 0;
+  private direction: LinkDirection | null = null;
+  // cross-axis anchor of the pending cluster, so growing it keeps the
+  // already-visible pending nodes in place
+  private clusterCrossStart: number | null = null;
+  pendingNodes: PendingExcalidrawElements | null = null;
+
+  createNodes(
+    startNode: NonDeleted<ExcalidrawFlowchartNodeElement>,
+    appState: AppState,
+    direction: LinkDirection,
+    scene: Scene,
+  ) {
+    const elementsMap = scene.getNonDeletedElementsMap();
+
+    if (direction !== this.direction) {
+      this.numberOfNodes = 1;
+      this.clusterCrossStart = null;
+    } else {
+      this.numberOfNodes += 1;
+    }
+
+    const { nodes, crossStart } = addNewNodes(
+      startNode,
+      appState,
+      direction,
+      scene,
+      this.numberOfNodes,
+      this.clusterCrossStart,
+    );
+
+    this.isCreatingChart = true;
+    this.direction = direction;
+    this.clusterCrossStart = crossStart;
+    this.pendingNodes = nodes;
+
+    // add pending nodes to the same frame as the start node
+    // if every pending node is at least intersecting with the frame
+    if (startNode.frameId) {
+      const frame = elementsMap.get(startNode.frameId);
+
+      invariant(
+        frame && isFrameElement(frame),
+        "not an ExcalidrawFrameElement",
+      );
+
+      if (
+        frame &&
+        this.pendingNodes.every(
+          (node) =>
+            elementsAreInFrameBounds([node], frame, elementsMap) ||
+            elementOverlapsWithFrame(node, frame, elementsMap),
+        )
+      ) {
+        this.pendingNodes = this.pendingNodes.map((node) =>
+          mutateElement(node, elementsMap, {
+            frameId: startNode.frameId,
+          }),
+        );
+      }
+    }
+  }
+
+  clear() {
+    this.isCreatingChart = false;
+    this.pendingNodes = null;
+    this.direction = null;
+    this.numberOfNodes = 0;
+    this.clusterCrossStart = null;
+  }
+}
+
+export const isNodeInFlowchart = (
+  element: ExcalidrawFlowchartNodeElement,
+  elementsMap: ElementsMap,
+) => {
+  for (const [, el] of elementsMap) {
+    if (
+      el.type === "arrow" &&
+      (el.startBinding?.elementId === element.id ||
+        el.endBinding?.elementId === element.id)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+};

packages/element/src/fractionalIndex.ts

@@ -0,0 +1,473 @@
+import { arrayToMap } from "@excalidraw/common";
+
+import {
+  validateOrderKey,
+  generateNKeysBetween,
+} from "@excalidraw/fractional-indexing";
+
+import { mutateElement, newElementWith } from "./mutateElement";
+import { getBoundTextElementId } from "./textElement";
+import { hasBoundTextElement } from "./typeChecks";
+
+import { isNonDeletedElement } from ".";
+
+import type {
+  ElementsMap,
+  ExcalidrawElement,
+  FractionalIndex,
+  Ordered,
+  OrderedExcalidrawElement,
+  SceneElementsMap,
+} from "./types";
+
+export class InvalidFractionalIndexError extends Error {
+  public code = "ELEMENT_HAS_INVALID_INDEX" as const;
+}
+
+/**
+ * Envisioned relation between array order and fractional indices:
+ *
+ * 1) Array (or array-like ordered data structure) should be used as a cache of elements order, hiding the internal fractional indices implementation.
+ * - it's undesirable to perform reorder for each related operation, therefore it's necessary to cache the order defined by fractional indices into an ordered data structure
+ * - it's easy enough to define the order of the elements from the outside (boundaries), without worrying about the underlying structure of fractional indices (especially for the host apps)
+ * - it's necessary to always keep the array support for backwards compatibility (restore) - old scenes, old libraries, supporting multiple excalidraw versions etc.
+ * - it's necessary to always keep the fractional indices in sync with the array order
+ * - elements with invalid indices should be detected and synced, without altering the already valid indices
+ *
+ * 2) Fractional indices should be used to reorder the elements, whenever the cached order is expected to be invalidated.
+ * - as the fractional indices are encoded as part of the elements, it opens up possibilities for incremental-like APIs
+ * - re-order based on fractional indices should be part of (multiplayer) operations such as reconciliation & undo/redo
+ * - technically all the z-index actions could perform also re-order based on fractional indices,but in current state it would not bring much benefits,
+ *   as it's faster & more efficient to perform re-order based on array manipulation and later synchronisation of moved indices with the array order
+ */
+
+/**
+ * Ensure that all elements have valid fractional indices.
+ *
+ * @throws `InvalidFractionalIndexError` if invalid index is detected.
+ */
+export const validateFractionalIndices = (
+  elements: readonly ExcalidrawElement[],
+  {
+    shouldThrow = false,
+    includeBoundTextValidation = false,
+    ignoreLogs,
+    reconciliationContext,
+  }: {
+    shouldThrow: boolean;
+    includeBoundTextValidation: boolean;
+    ignoreLogs?: true;
+    reconciliationContext?: {
+      localElements: ReadonlyArray<ExcalidrawElement>;
+      remoteElements: ReadonlyArray<ExcalidrawElement>;
+    };
+  },
+) => {
+  const errorMessages = [];
+  const stringifyElement = (element: ExcalidrawElement | void) =>
+    `${element?.index}:${element?.id}:${element?.type}:${element?.isDeleted}:${element?.version}:${element?.versionNonce}`;
+
+  const elementsMap = includeBoundTextValidation ? arrayToMap(elements) : null;
+
+  const indices = elements.map((x) => x.index);
+  for (const [i, index] of indices.entries()) {
+    const predecessorIndex = indices[i - 1];
+    const successorIndex = indices[i + 1];
+
+    if (!isValidFractionalIndex(index, predecessorIndex, successorIndex)) {
+      errorMessages.push(
+        `Fractional indices invariant has been compromised: "${stringifyElement(
+          elements[i - 1],
+        )}", "${stringifyElement(elements[i])}", "${stringifyElement(
+          elements[i + 1],
+        )}"`,
+      );
+    }
+
+    // disabled by default, as we don't fix it
+    if (
+      includeBoundTextValidation &&
+      elementsMap &&
+      hasBoundTextElement(elements[i]) &&
+      isNonDeletedElement(elements[i])
+    ) {
+      const container = elements[i];
+      const boundTextElementId = getBoundTextElementId(container);
+      const text = boundTextElementId
+        ? elementsMap.get(boundTextElementId)
+        : null;
+
+      if (
+        text &&
+        isNonDeletedElement(text) &&
+        text.index! <= container.index!
+      ) {
+        errorMessages.push(
+          `Fractional indices invariant for bound elements has been compromised: "${stringifyElement(
+            text,
+          )}", "${stringifyElement(container)}"`,
+        );
+      }
+    }
+  }
+
+  if (errorMessages.length) {
+    const error = new InvalidFractionalIndexError();
+    const additionalContext = [];
+
+    if (reconciliationContext) {
+      additionalContext.push("Additional reconciliation context:");
+      additionalContext.push(
+        reconciliationContext.localElements.map((x) => stringifyElement(x)),
+      );
+      additionalContext.push(
+        reconciliationContext.remoteElements.map((x) => stringifyElement(x)),
+      );
+    }
+
+    if (!ignoreLogs) {
+      // report just once and with the stacktrace
+      console.error(
+        errorMessages.join("\n\n"),
+        error.stack,
+        elements.map((x) => stringifyElement(x)),
+        ...additionalContext,
+      );
+    }
+
+    if (shouldThrow) {
+      // if enabled, gather all the errors first, throw once
+      throw error;
+    }
+  }
+};
+
+/**
+ * Order the elements based on the fractional indices.
+ * - when fractional indices are identical, break the tie based on the element id
+ * - when there is no fractional index in one of the elements, respect the order of the array
+ */
+export const orderByFractionalIndex = (
+  elements: OrderedExcalidrawElement[],
+) => {
+  return elements.sort((a, b) => {
+    // in case the indices are not the defined at runtime
+    if (isOrderedElement(a) && isOrderedElement(b)) {
+      if (a.index < b.index) {
+        return -1;
+      } else if (a.index > b.index) {
+        return 1;
+      }
+
+      // break ties based on the element id
+      return a.id < b.id ? -1 : 1;
+    }
+
+    // defensively keep the array order
+    return 1;
+  });
+};
+
+/**
+ * Synchronizes invalid fractional indices of moved elements with the array order by mutating passed elements.
+ * If the synchronization fails or the result is invalid, it fallbacks to `syncInvalidIndices`.
+ */
+export const syncMovedIndices = (
+  elements: readonly ExcalidrawElement[],
+  movedElements: ElementsMap,
+): OrderedExcalidrawElement[] => {
+  try {
+    const elementsMap = arrayToMap(elements);
+    const indicesGroups = getMovedIndicesGroups(elements, movedElements);
+
+    // try generatating indices, throws on invalid movedElements
+    const elementsUpdates = generateIndices(elements, indicesGroups);
+    const elementsCandidates = elements.map((x) => {
+      const elementUpdates = elementsUpdates.get(x);
+
+      if (elementUpdates) {
+        return { ...x, index: elementUpdates.index };
+      }
+
+      return x;
+    });
+
+    // ensure next indices are valid before mutation, throws on invalid ones
+    validateFractionalIndices(
+      elementsCandidates,
+      // we don't autofix invalid bound text indices, hence don't include it in the validation
+      {
+        includeBoundTextValidation: false,
+        shouldThrow: true,
+        ignoreLogs: true,
+      },
+    );
+
+    // split mutation so we don't end up in an incosistent state
+    for (const [element, { index }] of elementsUpdates) {
+      mutateElement(element, elementsMap, { index });
+    }
+  } catch (e) {
+    // fallback to default sync
+    syncInvalidIndices(elements);
+  }
+
+  return elements as OrderedExcalidrawElement[];
+};
+
+/**
+ * Synchronizes all invalid fractional indices within the array order by mutating elements in the passed array.
+ *
+ * WARN: in edge cases it could modify the elements which were not moved, as it's impossible to guess the actually moved elements from the elements array itself.
+ */
+export const syncInvalidIndices = <T extends ExcalidrawElement>(
+  elements: readonly T[],
+): Ordered<T>[] => {
+  const elementsMap = arrayToMap(elements);
+  const indicesGroups = getInvalidIndicesGroups(elements);
+  const elementsUpdates = generateIndices(elements, indicesGroups);
+
+  for (const [element, { index }] of elementsUpdates) {
+    mutateElement(element, elementsMap, { index });
+  }
+
+  return elements as Ordered<T>[];
+};
+
+/**
+ * Synchronizes all invalid fractional indices within the array order by creating new instances of elements with corrected indices.
+ *
+ * WARN: in edge cases it could modify the elements which were not moved, as it's impossible to guess the actually moved elements from the elements array itself.
+ */
+export const syncInvalidIndicesImmutable = (
+  elements: readonly ExcalidrawElement[],
+): SceneElementsMap | undefined => {
+  const syncedElements = arrayToMap(elements);
+  const indicesGroups = getInvalidIndicesGroups(elements);
+  const elementsUpdates = generateIndices(elements, indicesGroups);
+
+  for (const [element, { index }] of elementsUpdates) {
+    syncedElements.set(element.id, newElementWith(element, { index }));
+  }
+
+  return syncedElements as SceneElementsMap;
+};
+
+/**
+ * Get contiguous groups of indices of passed moved elements.
+ *
+ * NOTE: First and last elements within the groups are indices of lower and upper bounds.
+ */
+const getMovedIndicesGroups = (
+  elements: readonly ExcalidrawElement[],
+  movedElements: ElementsMap,
+) => {
+  const indicesGroups: number[][] = [];
+
+  let i = 0;
+
+  while (i < elements.length) {
+    if (movedElements.has(elements[i].id)) {
+      const indicesGroup = [i - 1, i]; // push the lower bound index as the first item
+
+      while (++i < elements.length) {
+        if (!movedElements.has(elements[i].id)) {
+          break;
+        }
+
+        indicesGroup.push(i);
+      }
+
+      indicesGroup.push(i); // push the upper bound index as the last item
+      indicesGroups.push(indicesGroup);
+    } else {
+      i++;
+    }
+  }
+
+  return indicesGroups;
+};
+
+/**
+ * Gets contiguous groups of all invalid indices automatically detected inside the elements array.
+ *
+ * WARN: First and last items within the groups do NOT have to be contiguous, those are the found lower and upper bounds!
+ */
+const getInvalidIndicesGroups = (elements: readonly ExcalidrawElement[]) => {
+  const indicesGroups: number[][] = [];
+
+  // once we find lowerBound / upperBound, it cannot be lower than that, so we cache it for better perf.
+  let lowerBound: ExcalidrawElement["index"] | undefined = undefined;
+  let upperBound: ExcalidrawElement["index"] | undefined = undefined;
+  let lowerBoundIndex: number = -1;
+  let upperBoundIndex: number = 0;
+
+  /** @returns maybe valid lowerBound */
+  const getLowerBound = (
+    index: number,
+  ): [ExcalidrawElement["index"] | undefined, number] => {
+    const lowerBound = elements[lowerBoundIndex]
+      ? elements[lowerBoundIndex].index
+      : undefined;
+
+    // we are already iterating left to right, therefore there is no need for additional looping
+    const candidate = elements[index - 1]?.index;
+
+    if (
+      (!lowerBound && candidate) || // first lowerBound
+      (lowerBound && candidate && candidate > lowerBound) // next lowerBound
+    ) {
+      // WARN: candidate's index could be higher or same as the current element's index
+      return [candidate, index - 1];
+    }
+
+    // cache hit! take the last lower bound
+    return [lowerBound, lowerBoundIndex];
+  };
+
+  /** @returns always valid upperBound */
+  const getUpperBound = (
+    index: number,
+  ): [ExcalidrawElement["index"] | undefined, number] => {
+    const upperBound = elements[upperBoundIndex]
+      ? elements[upperBoundIndex].index
+      : undefined;
+
+    // cache hit! don't let it find the upper bound again
+    if (upperBound && index < upperBoundIndex) {
+      return [upperBound, upperBoundIndex];
+    }
+
+    // set the current upperBoundIndex as the starting point
+    let i = upperBoundIndex;
+    while (++i < elements.length) {
+      const candidate = elements[i]?.index;
+
+      if (
+        (!upperBound && candidate) || // first upperBound
+        (upperBound && candidate && candidate > upperBound) // next upperBound
+      ) {
+        return [candidate, i];
+      }
+    }
+
+    // we reached the end, sky is the limit
+    return [undefined, i];
+  };
+
+  let i = 0;
+
+  while (i < elements.length) {
+    const current = elements[i].index;
+    [lowerBound, lowerBoundIndex] = getLowerBound(i);
+    [upperBound, upperBoundIndex] = getUpperBound(i);
+
+    if (!isValidFractionalIndex(current, lowerBound, upperBound)) {
+      // push the lower bound index as the first item
+      const indicesGroup = [lowerBoundIndex, i];
+
+      while (++i < elements.length) {
+        const current = elements[i].index;
+        const [nextLowerBound, nextLowerBoundIndex] = getLowerBound(i);
+        const [nextUpperBound, nextUpperBoundIndex] = getUpperBound(i);
+
+        if (isValidFractionalIndex(current, nextLowerBound, nextUpperBound)) {
+          break;
+        }
+
+        // assign bounds only for the moved elements
+        [lowerBound, lowerBoundIndex] = [nextLowerBound, nextLowerBoundIndex];
+        [upperBound, upperBoundIndex] = [nextUpperBound, nextUpperBoundIndex];
+
+        indicesGroup.push(i);
+      }
+
+      // push the upper bound index as the last item
+      indicesGroup.push(upperBoundIndex);
+      indicesGroups.push(indicesGroup);
+    } else {
+      i++;
+    }
+  }
+
+  return indicesGroups;
+};
+
+const isValidFractionalIndex = (
+  index: ExcalidrawElement["index"] | undefined,
+  predecessor: ExcalidrawElement["index"] | undefined,
+  successor: ExcalidrawElement["index"] | undefined,
+) => {
+  if (!index) {
+    return false;
+  }
+
+  try {
+    // Format validation
+    validateOrderKey(index);
+  } catch {
+    return false;
+  }
+
+  if (predecessor && successor) {
+    return predecessor < index && index < successor;
+  }
+
+  if (!predecessor && successor) {
+    // first element
+    return index < successor;
+  }
+
+  if (predecessor && !successor) {
+    // last element
+    return predecessor < index;
+  }
+
+  // only element in the array
+  return !!index;
+};
+
+const generateIndices = (
+  elements: readonly ExcalidrawElement[],
+  indicesGroups: number[][],
+) => {
+  const elementsUpdates = new Map<
+    ExcalidrawElement,
+    { index: FractionalIndex }
+  >();
+
+  for (const indices of indicesGroups) {
+    const lowerBoundIndex = indices.shift()!;
+    const upperBoundIndex = indices.pop()!;
+
+    const fractionalIndices = generateNKeysBetween(
+      elements[lowerBoundIndex]?.index,
+      elements[upperBoundIndex]?.index,
+      indices.length,
+    ) as FractionalIndex[];
+
+    for (let i = 0; i < indices.length; i++) {
+      const element = elements[indices[i]];
+
+      elementsUpdates.set(element, {
+        index: fractionalIndices[i],
+      });
+    }
+  }
+
+  return elementsUpdates;
+};
+
+const isOrderedElement = (
+  element: ExcalidrawElement,
+): element is OrderedExcalidrawElement => {
+  // for now it's sufficient whether the index is there
+  // meaning, the element was already ordered in the past
+  // meaning, it is not a newly inserted element, not an unrestored element, etc.
+  // it does not have to mean that the index itself is valid
+  if (element.index) {
+    return true;
+  }
+
+  return false;
+};

packages/element/src/groups.ts

@@ -0,0 +1,466 @@
+import type {
+  AppClassProperties,
+  AppState,
+  InteractiveCanvasAppState,
+} from "@excalidraw/excalidraw/types";
+import type { Mutable } from "@excalidraw/common/utility-types";
+
+import { getBoundTextElement } from "./textElement";
+
+import { isBoundToContainer } from "./typeChecks";
+
+import { makeNextSelectedElementIds, getSelectedElements } from "./selection";
+
+import type {
+  GroupId,
+  ExcalidrawElement,
+  NonDeleted,
+  ElementsMapOrArray,
+  ElementsMap,
+  NonDeletedExcalidrawElement,
+  NonDeletedElementsMapOrArray,
+} from "./types";
+
+export const selectGroup = (
+  groupId: GroupId,
+  appState: InteractiveCanvasAppState,
+  elements: readonly NonDeletedExcalidrawElement[],
+): Pick<
+  InteractiveCanvasAppState,
+  "selectedGroupIds" | "selectedElementIds" | "editingGroupId"
+> => {
+  const elementsInGroup = elements.reduce(
+    (acc: Record<string, true>, element) => {
+      if (element.groupIds.includes(groupId)) {
+        acc[element.id] = true;
+      }
+      return acc;
+    },
+    {},
+  );
+
+  if (Object.keys(elementsInGroup).length < 2) {
+    if (
+      appState.selectedGroupIds[groupId] ||
+      appState.editingGroupId === groupId
+    ) {
+      return {
+        selectedElementIds: appState.selectedElementIds,
+        selectedGroupIds: { ...appState.selectedGroupIds, [groupId]: false },
+        editingGroupId: null,
+      };
+    }
+    return appState;
+  }
+
+  return {
+    editingGroupId: appState.editingGroupId,
+    selectedGroupIds: { ...appState.selectedGroupIds, [groupId]: true },
+    selectedElementIds: {
+      ...appState.selectedElementIds,
+      ...elementsInGroup,
+    },
+  };
+};
+
+export const selectGroupsForSelectedElements = (function () {
+  type SelectGroupsReturnType = Pick<
+    InteractiveCanvasAppState,
+    "selectedGroupIds" | "editingGroupId" | "selectedElementIds"
+  >;
+
+  let lastSelectedElements: readonly NonDeletedExcalidrawElement[] | null =
+    null;
+  let lastElements: readonly NonDeletedExcalidrawElement[] | null = null;
+  let lastReturnValue: SelectGroupsReturnType | null = null;
+
+  const _selectGroups = (
+    selectedElements: readonly NonDeletedExcalidrawElement[],
+    elements: readonly NonDeletedExcalidrawElement[],
+    appState: Pick<AppState, "selectedElementIds" | "editingGroupId">,
+    prevAppState: InteractiveCanvasAppState,
+  ): SelectGroupsReturnType => {
+    if (
+      lastReturnValue !== undefined &&
+      elements === lastElements &&
+      selectedElements === lastSelectedElements &&
+      appState.editingGroupId === lastReturnValue?.editingGroupId
+    ) {
+      return lastReturnValue;
+    }
+
+    const selectedGroupIds: Record<GroupId, boolean> = {};
+    // Gather all the groups withing selected elements
+    for (const selectedElement of selectedElements) {
+      let groupIds = selectedElement.groupIds;
+      if (appState.editingGroupId) {
+        // handle the case where a group is nested within a group
+        const indexOfEditingGroup = groupIds.indexOf(appState.editingGroupId);
+        if (indexOfEditingGroup > -1) {
+          groupIds = groupIds.slice(0, indexOfEditingGroup);
+        }
+      }
+      if (groupIds.length > 0) {
+        const lastSelectedGroup = groupIds[groupIds.length - 1];
+        selectedGroupIds[lastSelectedGroup] = true;
+      }
+    }
+
+    // Gather all the elements within selected groups
+    const groupElementsIndex: Record<GroupId, string[]> = {};
+    const selectedElementIdsInGroups = elements.reduce(
+      (acc: Record<string, true>, element) => {
+        if (element.isDeleted) {
+          return acc;
+        }
+
+        const groupId = element.groupIds.find((id) => selectedGroupIds[id]);
+
+        if (groupId) {
+          acc[element.id] = true;
+
+          // Populate the index
+          if (!Array.isArray(groupElementsIndex[groupId])) {
+            groupElementsIndex[groupId] = [element.id];
+          } else {
+            groupElementsIndex[groupId].push(element.id);
+          }
+        }
+        return acc;
+      },
+      {},
+    );
+
+    for (const groupId of Object.keys(groupElementsIndex)) {
+      // If there is one element in the group, and the group is selected or it's being edited, it's not a group
+      if (groupElementsIndex[groupId].length < 2) {
+        if (selectedGroupIds[groupId]) {
+          selectedGroupIds[groupId] = false;
+        }
+      }
+    }
+
+    lastElements = elements;
+    lastSelectedElements = selectedElements;
+
+    lastReturnValue = {
+      editingGroupId: appState.editingGroupId,
+      selectedGroupIds,
+      selectedElementIds: makeNextSelectedElementIds(
+        {
+          ...appState.selectedElementIds,
+          ...selectedElementIdsInGroups,
+        },
+        prevAppState,
+      ),
+    };
+
+    return lastReturnValue;
+  };
+
+  /**
+   * When you select an element, you often want to actually select the whole group it's in, unless
+   * you're currently editing that group.
+   */
+  const selectGroupsForSelectedElements = (
+    appState: Pick<AppState, "selectedElementIds" | "editingGroupId">,
+    elements: readonly NonDeletedExcalidrawElement[],
+    prevAppState: InteractiveCanvasAppState,
+    /**
+     * supply null in cases where you don't have access to App instance and
+     * you don't care about optimizing selectElements retrieval
+     */
+    app: AppClassProperties | null,
+  ): Mutable<
+    Pick<
+      InteractiveCanvasAppState,
+      "selectedGroupIds" | "editingGroupId" | "selectedElementIds"
+    >
+  > => {
+    const selectedElements = app
+      ? app.scene.getSelectedElements({
+          selectedElementIds: appState.selectedElementIds,
+          // supplying elements explicitly in case we're passed non-state elements
+          elements,
+        })
+      : getSelectedElements(elements, appState);
+
+    if (!selectedElements.length) {
+      return {
+        selectedGroupIds: {},
+        editingGroupId: null,
+        selectedElementIds: makeNextSelectedElementIds(
+          appState.selectedElementIds,
+          prevAppState,
+        ),
+      };
+    }
+
+    return _selectGroups(selectedElements, elements, appState, prevAppState);
+  };
+
+  selectGroupsForSelectedElements.clearCache = () => {
+    lastElements = null;
+    lastSelectedElements = null;
+    lastReturnValue = null;
+  };
+
+  return selectGroupsForSelectedElements;
+})();
+
+/**
+ * If the element's group is selected, don't render an individual
+ * selection border around it.
+ */
+export const isSelectedViaGroup = (
+  appState: Pick<
+    InteractiveCanvasAppState,
+    "editingGroupId" | "selectedGroupIds"
+  >,
+  element: ExcalidrawElement,
+) => getSelectedGroupForElement(appState, element) != null;
+
+export const getSelectedGroupForElement = (
+  appState: Pick<
+    InteractiveCanvasAppState,
+    "editingGroupId" | "selectedGroupIds"
+  >,
+  element: ExcalidrawElement,
+) =>
+  element.groupIds
+    .filter((groupId) => groupId !== appState.editingGroupId)
+    .find((groupId) => appState.selectedGroupIds[groupId]);
+
+export const getSelectedGroupIds = (
+  appState: Pick<InteractiveCanvasAppState, "selectedGroupIds">,
+): GroupId[] =>
+  Object.entries(appState.selectedGroupIds)
+    .filter(([groupId, isSelected]) => isSelected)
+    .map(([groupId, isSelected]) => groupId);
+
+// given a list of elements, return the the actual group ids that should be selected
+// or used to update the elements
+export const selectGroupsFromGivenElements = (
+  elements: readonly NonDeletedExcalidrawElement[],
+  appState: InteractiveCanvasAppState,
+) => {
+  let nextAppState: InteractiveCanvasAppState = {
+    ...appState,
+    selectedGroupIds: {},
+  };
+
+  for (const element of elements) {
+    let groupIds = element.groupIds;
+    if (appState.editingGroupId) {
+      const indexOfEditingGroup = groupIds.indexOf(appState.editingGroupId);
+      if (indexOfEditingGroup > -1) {
+        groupIds = groupIds.slice(0, indexOfEditingGroup);
+      }
+    }
+    if (groupIds.length > 0) {
+      const groupId = groupIds[groupIds.length - 1];
+      nextAppState = {
+        ...nextAppState,
+        ...selectGroup(groupId, nextAppState, elements),
+      };
+    }
+  }
+
+  return nextAppState.selectedGroupIds;
+};
+
+export const editGroupForSelectedElement = (
+  appState: AppState,
+  element: NonDeleted<ExcalidrawElement>,
+): AppState => {
+  return {
+    ...appState,
+    editingGroupId: element.groupIds.length ? element.groupIds[0] : null,
+    selectedGroupIds: {},
+    selectedElementIds: {
+      [element.id]: true,
+    },
+  };
+};
+
+export const isElementInGroup = (element: ExcalidrawElement, groupId: string) =>
+  element.groupIds.includes(groupId);
+
+export const getElementsInGroup = <
+  P extends NonDeletedExcalidrawElement | ExcalidrawElement,
+>(
+  elements: P extends NonDeletedExcalidrawElement
+    ? NonDeletedElementsMapOrArray
+    : ElementsMapOrArray,
+  groupId: string,
+): P[] => {
+  const elementsInGroup: P[] = [];
+  for (const element of elements.values()) {
+    if (isElementInGroup(element, groupId)) {
+      elementsInGroup.push(element as P);
+    }
+  }
+  return elementsInGroup;
+};
+
+export const getSelectedGroupIdForElement = (
+  element: ExcalidrawElement,
+  selectedGroupIds: { [groupId: string]: boolean },
+) => element.groupIds.find((groupId) => selectedGroupIds[groupId]);
+
+export const addToGroup = (
+  prevGroupIds: ExcalidrawElement["groupIds"],
+  newGroupId: GroupId,
+  editingGroupId: AppState["editingGroupId"],
+) => {
+  // insert before the editingGroupId, or push to the end.
+  const groupIds = [...prevGroupIds];
+  const positionOfEditingGroupId = editingGroupId
+    ? groupIds.indexOf(editingGroupId)
+    : -1;
+  const positionToInsert =
+    positionOfEditingGroupId > -1 ? positionOfEditingGroupId : groupIds.length;
+  groupIds.splice(positionToInsert, 0, newGroupId);
+  return groupIds;
+};
+
+export const removeFromSelectedGroups = (
+  groupIds: ExcalidrawElement["groupIds"],
+  selectedGroupIds: { [groupId: string]: boolean },
+) => groupIds.filter((groupId) => !selectedGroupIds[groupId]);
+
+export const getMaximumGroups = <
+  T extends NonDeletedExcalidrawElement | ExcalidrawElement,
+>(
+  elements: T[],
+  elementsMap: ElementsMap,
+): T[][] => {
+  const groups: Map<String, T[]> = new Map<String, T[]>();
+  elements.forEach((element: T) => {
+    const groupId =
+      element.groupIds.length === 0
+        ? element.id
+        : element.groupIds[element.groupIds.length - 1];
+
+    const currentGroupMembers = groups.get(groupId) || [];
+
+    // Include bound text if present when grouping
+    const boundTextElement = getBoundTextElement(element, elementsMap);
+    if (boundTextElement) {
+      currentGroupMembers.push(boundTextElement as T);
+    }
+    groups.set(groupId, [...currentGroupMembers, element]);
+  });
+
+  return Array.from(groups.values());
+};
+
+export const getNonDeletedGroupIds = (elements: ElementsMap) => {
+  const nonDeletedGroupIds = new Set<string>();
+
+  for (const [, element] of elements) {
+    // defensive check
+    if (element.isDeleted) {
+      continue;
+    }
+
+    // defensive fallback
+    for (const groupId of element.groupIds ?? []) {
+      nonDeletedGroupIds.add(groupId);
+    }
+  }
+
+  return nonDeletedGroupIds;
+};
+
+export const elementsAreInSameGroup = (
+  elements: readonly ExcalidrawElement[],
+) => {
+  const allGroups = elements.flatMap((element) => element.groupIds);
+  const groupCount = new Map<string, number>();
+  let maxGroup = 0;
+
+  for (const group of allGroups) {
+    groupCount.set(group, (groupCount.get(group) ?? 0) + 1);
+    if (groupCount.get(group)! > maxGroup) {
+      maxGroup = groupCount.get(group)!;
+    }
+  }
+
+  return maxGroup === elements.length;
+};
+
+export const isInGroup = (element: ExcalidrawElement) => {
+  return element.groupIds.length > 0;
+};
+
+export const getNewGroupIdsForDuplication = (
+  groupIds: ExcalidrawElement["groupIds"],
+  editingGroupId: AppState["editingGroupId"],
+  mapper: (groupId: GroupId) => GroupId,
+) => {
+  const copy = [...groupIds];
+  const positionOfEditingGroupId = editingGroupId
+    ? groupIds.indexOf(editingGroupId)
+    : -1;
+  const endIndex =
+    positionOfEditingGroupId > -1 ? positionOfEditingGroupId : groupIds.length;
+  for (let index = 0; index < endIndex; index++) {
+    copy[index] = mapper(copy[index]);
+  }
+
+  return copy;
+};
+
+// given a list of selected elements, return the element grouped by their immediate group selected state
+// in the case if only one group is selected and all elements selected are within the group, it will respect group hierarchy in accordance to their nested grouping order
+export const getSelectedElementsByGroup = (
+  selectedElements: NonDeletedExcalidrawElement[],
+  elementsMap: ElementsMap,
+  appState: Readonly<Pick<AppState, "selectedGroupIds" | "editingGroupId">>,
+): NonDeletedExcalidrawElement[][] => {
+  const buckets: Map<string, NonDeletedExcalidrawElement[]> = new Map();
+  const selectedGroupIds = getSelectedGroupIds(appState);
+  const isSingleSelectedGroupCase =
+    selectedGroupIds.length === 1 &&
+    selectedElements.every((element) => isSelectedViaGroup(appState, element));
+
+  selectedElements.forEach((element) => {
+    // skip dependent boundTextElements, they are appended after their container
+    if (isBoundToContainer(element)) {
+      return;
+    }
+
+    let bucketKey: string;
+    const selectedGroupId = getSelectedGroupIdForElement(
+      element,
+      appState.selectedGroupIds,
+    );
+
+    if (!selectedGroupId) {
+      bucketKey = `${element.id}_element`;
+    } else {
+      // if only one group is selected, grouping is based on inner hierarchy
+      const keyIndex = isSingleSelectedGroupCase
+        ? element.groupIds.indexOf(selectedGroupId) - 1
+        : element.groupIds.indexOf(selectedGroupId);
+
+      // edge case: single selected group where element is non member of inner group
+      bucketKey =
+        keyIndex < 0
+          ? `${element.id}_element`
+          : `${element.groupIds[keyIndex]}_group`;
+    }
+
+    const currentBucketMembers = buckets.get(bucketKey) ?? [];
+    const boundTextElement = getBoundTextElement(element, elementsMap);
+
+    // preserve boundtext after container ordering
+    buckets.set(bucketKey, [
+      ...currentBucketMembers,
+      element,
+      ...(boundTextElement ? [boundTextElement] : []),
+    ]);
+  });
+  return [...buckets.values()];
+};

packages/element/src/heading.ts

@@ -0,0 +1,287 @@
+import {
+  invariant,
+  isDevEnv,
+  isTestEnv,
+  type Bounds,
+} from "@excalidraw/common";
+
+import {
+  pointFrom,
+  pointFromVector,
+  pointRotateRads,
+  pointScaleFromOrigin,
+  pointsEqual,
+  triangleIncludesPoint,
+  vectorCross,
+  vectorFromPoint,
+  vectorScale,
+} from "@excalidraw/math";
+
+import type {
+  LocalPoint,
+  GlobalPoint,
+  Triangle,
+  Vector,
+} from "@excalidraw/math";
+
+import { getCenterForBounds } from "./bounds";
+
+import type { ExcalidrawBindableElement } from "./types";
+
+export const HEADING_RIGHT = [1, 0] as Heading;
+export const HEADING_DOWN = [0, 1] as Heading;
+export const HEADING_LEFT = [-1, 0] as Heading;
+export const HEADING_UP = [0, -1] as Heading;
+export type Heading = [1, 0] | [0, 1] | [-1, 0] | [0, -1];
+
+export const vectorToHeading = (vec: Vector): Heading => {
+  const [x, y] = vec;
+  const absX = Math.abs(x);
+  const absY = Math.abs(y);
+  if (x > absY) {
+    return HEADING_RIGHT;
+  } else if (x <= -absY) {
+    return HEADING_LEFT;
+  } else if (y > absX) {
+    return HEADING_DOWN;
+  }
+  return HEADING_UP;
+};
+
+export const headingForPoint = <P extends GlobalPoint | LocalPoint>(
+  p: P,
+  o: P,
+) => vectorToHeading(vectorFromPoint<P>(p, o));
+
+export const headingForPointIsHorizontal = <P extends GlobalPoint | LocalPoint>(
+  p: P,
+  o: P,
+) => headingIsHorizontal(headingForPoint<P>(p, o));
+
+export const compareHeading = (a: Heading, b: Heading) =>
+  a[0] === b[0] && a[1] === b[1];
+
+export const headingIsHorizontal = (a: Heading) =>
+  compareHeading(a, HEADING_RIGHT) || compareHeading(a, HEADING_LEFT);
+
+export const headingIsVertical = (a: Heading) => !headingIsHorizontal(a);
+
+const headingForPointFromDiamondElement = (
+  element: Readonly<ExcalidrawBindableElement>,
+  aabb: Readonly<Bounds>,
+  point: Readonly<GlobalPoint>,
+): Heading => {
+  const midPoint = getCenterForBounds(aabb);
+
+  if (isDevEnv() || isTestEnv()) {
+    invariant(
+      element.width > 0 && element.height > 0,
+      "Diamond element has no width or height",
+    );
+    invariant(
+      !pointsEqual(midPoint, point),
+      "The point is too close to the element mid point to determine heading",
+    );
+  }
+
+  const SHRINK = 0.95; // Rounded elements tolerance
+  const top = pointFromVector(
+    vectorScale(
+      vectorFromPoint(
+        pointRotateRads(
+          pointFrom<GlobalPoint>(element.x + element.width / 2, element.y),
+          midPoint,
+          element.angle,
+        ),
+        midPoint,
+      ),
+      SHRINK,
+    ),
+    midPoint,
+  );
+  const right = pointFromVector(
+    vectorScale(
+      vectorFromPoint(
+        pointRotateRads(
+          pointFrom<GlobalPoint>(
+            element.x + element.width,
+            element.y + element.height / 2,
+          ),
+          midPoint,
+          element.angle,
+        ),
+        midPoint,
+      ),
+      SHRINK,
+    ),
+    midPoint,
+  );
+  const bottom = pointFromVector(
+    vectorScale(
+      vectorFromPoint(
+        pointRotateRads(
+          pointFrom<GlobalPoint>(
+            element.x + element.width / 2,
+            element.y + element.height,
+          ),
+          midPoint,
+          element.angle,
+        ),
+        midPoint,
+      ),
+      SHRINK,
+    ),
+    midPoint,
+  );
+  const left = pointFromVector(
+    vectorScale(
+      vectorFromPoint(
+        pointRotateRads(
+          pointFrom<GlobalPoint>(element.x, element.y + element.height / 2),
+          midPoint,
+          element.angle,
+        ),
+        midPoint,
+      ),
+      SHRINK,
+    ),
+    midPoint,
+  );
+
+  // Corners
+  if (
+    vectorCross(vectorFromPoint(point, top), vectorFromPoint(top, right)) <=
+      0 &&
+    vectorCross(vectorFromPoint(point, top), vectorFromPoint(top, left)) > 0
+  ) {
+    return headingForPoint(top, midPoint);
+  } else if (
+    vectorCross(
+      vectorFromPoint(point, right),
+      vectorFromPoint(right, bottom),
+    ) <= 0 &&
+    vectorCross(vectorFromPoint(point, right), vectorFromPoint(right, top)) > 0
+  ) {
+    return headingForPoint(right, midPoint);
+  } else if (
+    vectorCross(
+      vectorFromPoint(point, bottom),
+      vectorFromPoint(bottom, left),
+    ) <= 0 &&
+    vectorCross(
+      vectorFromPoint(point, bottom),
+      vectorFromPoint(bottom, right),
+    ) > 0
+  ) {
+    return headingForPoint(bottom, midPoint);
+  } else if (
+    vectorCross(vectorFromPoint(point, left), vectorFromPoint(left, top)) <=
+      0 &&
+    vectorCross(vectorFromPoint(point, left), vectorFromPoint(left, bottom)) > 0
+  ) {
+    return headingForPoint(left, midPoint);
+  }
+
+  // Sides
+  if (
+    vectorCross(
+      vectorFromPoint(point, midPoint),
+      vectorFromPoint(top, midPoint),
+    ) <= 0 &&
+    vectorCross(
+      vectorFromPoint(point, midPoint),
+      vectorFromPoint(right, midPoint),
+    ) > 0
+  ) {
+    const p = element.width > element.height ? top : right;
+    return headingForPoint(p, midPoint);
+  } else if (
+    vectorCross(
+      vectorFromPoint(point, midPoint),
+      vectorFromPoint(right, midPoint),
+    ) <= 0 &&
+    vectorCross(
+      vectorFromPoint(point, midPoint),
+      vectorFromPoint(bottom, midPoint),
+    ) > 0
+  ) {
+    const p = element.width > element.height ? bottom : right;
+    return headingForPoint(p, midPoint);
+  } else if (
+    vectorCross(
+      vectorFromPoint(point, midPoint),
+      vectorFromPoint(bottom, midPoint),
+    ) <= 0 &&
+    vectorCross(
+      vectorFromPoint(point, midPoint),
+      vectorFromPoint(left, midPoint),
+    ) > 0
+  ) {
+    const p = element.width > element.height ? bottom : left;
+    return headingForPoint(p, midPoint);
+  }
+
+  const p = element.width > element.height ? top : left;
+  return headingForPoint(p, midPoint);
+};
+
+// Gets the heading for the point by creating a bounding box around the rotated
+// close fitting bounding box, then creating 4 search cones around the center of
+// the external bbox.
+export const headingForPointFromElement = <Point extends GlobalPoint>(
+  element: Readonly<ExcalidrawBindableElement>,
+  aabb: Readonly<Bounds>,
+  p: Readonly<Point>,
+): Heading => {
+  const SEARCH_CONE_MULTIPLIER = 2;
+
+  const midPoint = getCenterForBounds(aabb);
+
+  if (element.type === "diamond") {
+    return headingForPointFromDiamondElement(element, aabb, p);
+  }
+
+  const topLeft = pointScaleFromOrigin(
+    pointFrom(aabb[0], aabb[1]),
+    midPoint,
+    SEARCH_CONE_MULTIPLIER,
+  ) as Point;
+  const topRight = pointScaleFromOrigin(
+    pointFrom(aabb[2], aabb[1]),
+    midPoint,
+    SEARCH_CONE_MULTIPLIER,
+  ) as Point;
+  const bottomLeft = pointScaleFromOrigin(
+    pointFrom(aabb[0], aabb[3]),
+    midPoint,
+    SEARCH_CONE_MULTIPLIER,
+  ) as Point;
+  const bottomRight = pointScaleFromOrigin(
+    pointFrom(aabb[2], aabb[3]),
+    midPoint,
+    SEARCH_CONE_MULTIPLIER,
+  ) as Point;
+
+  return triangleIncludesPoint<Point>(
+    [topLeft, topRight, midPoint] as Triangle<Point>,
+    p,
+  )
+    ? HEADING_UP
+    : triangleIncludesPoint<Point>(
+        [topRight, bottomRight, midPoint] as Triangle<Point>,
+        p,
+      )
+    ? HEADING_RIGHT
+    : triangleIncludesPoint<Point>(
+        [bottomRight, bottomLeft, midPoint] as Triangle<Point>,
+        p,
+      )
+    ? HEADING_DOWN
+    : HEADING_LEFT;
+};
+
+export const flipHeading = (h: Heading): Heading =>
+  [
+    h[0] === 0 ? 0 : h[0] > 0 ? -1 : 1,
+    h[1] === 0 ? 0 : h[1] > 0 ? -1 : 1,
+  ] as Heading;

packages/element/src/image.ts

@@ -0,0 +1,153 @@
+// -----------------------------------------------------------------------------
+// ExcalidrawImageElement & related helpers
+// -----------------------------------------------------------------------------
+
+import { MIME_TYPES, SVG_NS } from "@excalidraw/common";
+
+import type {
+  AppClassProperties,
+  DataURL,
+  BinaryFiles,
+} from "@excalidraw/excalidraw/types";
+
+import { isInitializedImageElement } from "./typeChecks";
+
+import type {
+  ExcalidrawElement,
+  FileId,
+  InitializedExcalidrawImageElement,
+} from "./types";
+
+export const loadHTMLImageElement = (dataURL: DataURL) => {
+  return new Promise<HTMLImageElement>((resolve, reject) => {
+    const image = new Image();
+    image.onload = () => {
+      resolve(image);
+    };
+    image.onerror = (error) => {
+      reject(error);
+    };
+    image.src = dataURL;
+  });
+};
+
+/** NOTE: updates cache even if already populated with given image. Thus,
+ * you should filter out the images upstream if you want to optimize this. */
+export const updateImageCache = async ({
+  fileIds,
+  files,
+  imageCache,
+}: {
+  fileIds: FileId[];
+  files: BinaryFiles;
+  imageCache: AppClassProperties["imageCache"];
+}) => {
+  const updatedFiles = new Map<FileId, true>();
+  const erroredFiles = new Map<FileId, true>();
+
+  await Promise.all(
+    fileIds.reduce((promises, fileId) => {
+      const fileData = files[fileId as string];
+      if (fileData && !updatedFiles.has(fileId)) {
+        updatedFiles.set(fileId, true);
+        return promises.concat(
+          (async () => {
+            try {
+              if (fileData.mimeType === MIME_TYPES.binary) {
+                throw new Error("Only images can be added to ImageCache");
+              }
+
+              const imagePromise = loadHTMLImageElement(fileData.dataURL);
+              const data = {
+                image: imagePromise,
+                mimeType: fileData.mimeType,
+              } as const;
+              // store the promise immediately to indicate there's an in-progress
+              // initialization
+              imageCache.set(fileId, data);
+
+              const image = await imagePromise;
+
+              imageCache.set(fileId, { ...data, image });
+            } catch (error: any) {
+              erroredFiles.set(fileId, true);
+            }
+          })(),
+        );
+      }
+      return promises;
+    }, [] as Promise<any>[]),
+  );
+
+  return {
+    imageCache,
+    /** includes errored files because they cache was updated nonetheless */
+    updatedFiles,
+    /** files that failed when creating HTMLImageElement */
+    erroredFiles,
+  };
+};
+
+export const getInitializedImageElements = (
+  elements: readonly ExcalidrawElement[],
+) =>
+  elements.filter((element) =>
+    isInitializedImageElement(element),
+  ) as InitializedExcalidrawImageElement[];
+
+export const isHTMLSVGElement = (node: Node | null): node is SVGElement => {
+  // lower-casing due to XML/HTML convention differences
+  // https://johnresig.com/blog/nodename-case-sensitivity
+  return node?.nodeName.toLowerCase() === "svg";
+};
+
+export const normalizeSVG = (SVGString: string) => {
+  const doc = new DOMParser().parseFromString(SVGString, MIME_TYPES.svg);
+  const svg = doc.querySelector("svg");
+  const errorNode = doc.querySelector("parsererror");
+  if (errorNode || !isHTMLSVGElement(svg)) {
+    throw new Error("Invalid SVG");
+  } else {
+    if (!svg.hasAttribute("xmlns")) {
+      svg.setAttribute("xmlns", SVG_NS);
+    }
+
+    let width = svg.getAttribute("width");
+    let height = svg.getAttribute("height");
+
+    // Do not use % or auto values for width/height
+    // to avoid scaling issues when rendering at different sizes/zoom levels
+    if (width?.includes("%") || width === "auto") {
+      width = null;
+    }
+    if (height?.includes("%") || height === "auto") {
+      height = null;
+    }
+
+    const viewBox = svg.getAttribute("viewBox");
+
+    if (!width || !height) {
+      width = width || "50";
+      height = height || "50";
+
+      if (viewBox) {
+        const match = viewBox.match(
+          /\d+ +\d+ +(\d+(?:\.\d+)?) +(\d+(?:\.\d+)?)/,
+        );
+        if (match) {
+          [, width, height] = match;
+        }
+      }
+
+      svg.setAttribute("width", width);
+      svg.setAttribute("height", height);
+    }
+
+    // Make sure viewBox is set
+    if (!viewBox) {
+      svg.setAttribute("viewBox", `0 0 ${width} ${height}`);
+    }
+
+    return svg.outerHTML;
+  }
+};

packages/element/src/index.ts

@@ -0,0 +1,108 @@
+import { toIterable } from "@excalidraw/common";
+
+import { isInvisiblySmallElement } from "./sizeHelpers";
+
+import type {
+  ExcalidrawElement,
+  NonDeletedExcalidrawElement,
+  NonDeleted,
+  ElementsMapOrArray,
+} from "./types";
+
+/**
+ * @deprecated unsafe, use hashElementsVersion instead
+ */
+export const getSceneVersion = (elements: readonly ExcalidrawElement[]) =>
+  elements.reduce((acc, el) => acc + el.version, 0);
+
+/**
+ * Hashes elements' versionNonce (using djb2 algo). Order of elements matters.
+ */
+export const hashElementsVersion = (elements: ElementsMapOrArray): number => {
+  let hash = 5381;
+  for (const element of toIterable(elements)) {
+    hash = (hash << 5) + hash + element.versionNonce;
+  }
+  return hash >>> 0; // Ensure unsigned 32-bit integer
+};
+
+// string hash function (using djb2). Not cryptographically secure, use only
+// for versioning and such.
+// note: hashes individual code units (not code points),
+// but for hashing purposes this is fine as it iterates through every code unit
+// (as such, no need to encode to byte string first)
+export const hashString = (s: string): number => {
+  let hash: number = 5381;
+  for (let i = 0; i < s.length; i++) {
+    const char: number = s.charCodeAt(i);
+    hash = (hash << 5) + hash + char;
+  }
+  return hash >>> 0; // Ensure unsigned 32-bit integer
+};
+
+export const isNonDeletedElement = <T extends ExcalidrawElement>(
+  element: T,
+): element is NonDeleted<T> => !element.isDeleted;
+
+export const getVisibleElements = (
+  elements: readonly ExcalidrawElement[],
+): readonly NonDeletedExcalidrawElement[] =>
+  elements.filter(
+    (el): el is NonDeletedExcalidrawElement =>
+      isNonDeletedElement(el) && !isInvisiblySmallElement(el),
+  );
+
+export const getNonDeletedElements = <T extends ExcalidrawElement>(
+  elements: readonly T[],
+): readonly NonDeleted<T>[] => elements.filter(isNonDeletedElement);
+
+export * from "./align";
+export * from "./arrowEndpointText";
+export * from "./binding";
+export * from "./bounds";
+export * from "./bucketFill";
+export * from "./collision";
+export * from "./comparisons";
+export * from "./containerCache";
+export * from "./cropElement";
+export * from "./delta";
+export * from "./distance";
+export * from "./distribute";
+export * from "./dragElements";
+export * from "./duplicate";
+export * from "./elbowArrow";
+export * from "./elementLink";
+export * from "./embeddable";
+export * from "./flowchart";
+export * from "./arrows/focus";
+export * from "./fractionalIndex";
+export * from "./frame";
+export * from "./groups";
+export * from "./heading";
+export * from "./image";
+export * from "./linearElementEditor";
+export * from "./mutateElement";
+export * from "./newElement";
+export * from "./positionElementsOnGrid";
+export * from "./renderElement";
+export * from "./resizeElements";
+export * from "./resizeTest";
+export * from "./Scene";
+export * from "./selection";
+export * from "./shape";
+export * from "./showSelectedShapeActions";
+export * from "./sizeHelpers";
+export * from "./sortElements";
+export * from "./store";
+export * from "./stickyNote";
+export * from "./textElement";
+export * from "./textMeasurements";
+export * from "./textWrapping";
+export * from "./transform";
+export * from "./transformHandles";
+export * from "./typeChecks";
+export * from "./utils";
+export * from "./zindex";
+export * from "./arrows/helpers";
+export * from "./arrowheads";
+export * from "./convertToShape";

packages/element/src/mutateElement.ts

@@ -0,0 +1,196 @@
+import {
+  getSizeFromPoints,
+  randomInteger,
+  getUpdatedTimestamp,
+} from "@excalidraw/common";
+
+import type { Radians } from "@excalidraw/math";
+
+import type { Mutable } from "@excalidraw/common/utility-types";
+
+import { ShapeCache } from "./shape";
+
+import { updateElbowArrowPoints } from "./elbowArrow";
+
+import { isElbowArrow } from "./typeChecks";
+
+import type {
+  ElementsMap,
+  ExcalidrawElbowArrowElement,
+  ExcalidrawElement,
+  NonDeletedSceneElementsMap,
+} from "./types";
+
+// `created` is lifetime metadata: it is set once when an element instance is
+// constructed (or duplicated) and never updated, so it is not part of an
+// element update. An explicit repair must construct a new element object.
+export type ElementUpdate<TElement extends ExcalidrawElement> = Omit<
+  Partial<TElement>,
+  "id" | "updated" | "created"
+>;
+
+/**
+ * This function tracks updates of text elements for the purposes for collaboration.
+ * The version is used to compare updates when more than one user is working in
+ * the same drawing.
+ *
+ * WARNING: this won't trigger the component to update, so if you need to trigger component update,
+ * use `scene.mutateElement` or `ExcalidrawImperativeAPI.mutateElement` instead.
+ */
+export const mutateElement = <TElement extends Mutable<ExcalidrawElement>>(
+  element: TElement,
+  elementsMap: ElementsMap,
+  updates: ElementUpdate<TElement>,
+  options?: {
+    isDragging?: boolean;
+    isBindingEnabled?: boolean;
+    isMidpointSnappingEnabled?: boolean;
+  },
+) => {
+  let didChange = false;
+
+  // casting to any because can't use `in` operator
+  // (see https://github.com/microsoft/TypeScript/issues/21732)
+  const { points, fixedSegments, fileId } = updates as any;
+
+  if (
+    isElbowArrow(element) &&
+    (Object.keys(updates).length === 0 || // normalization case
+      typeof points !== "undefined" || // repositioning
+      typeof fixedSegments !== "undefined") // segment fixing
+  ) {
+    updates = {
+      ...updates,
+      angle: 0 as Radians,
+      ...updateElbowArrowPoints(
+        {
+          ...(element as ExcalidrawElbowArrowElement),
+          x: updates.x || element.x,
+          y: updates.y || element.y,
+        },
+        elementsMap as NonDeletedSceneElementsMap,
+        updates as ElementUpdate<ExcalidrawElbowArrowElement>,
+        options,
+      ),
+    };
+  } else if (typeof points !== "undefined") {
+    updates = { ...getSizeFromPoints(points), ...updates };
+  }
+
+  for (const key in updates) {
+    const value = (updates as any)[key];
+    if (typeof value !== "undefined") {
+      if (
+        (element as any)[key] === value &&
+        // if object, always update because its attrs could have changed
+        // (except for specific keys we handle below)
+        (typeof value !== "object" ||
+          value === null ||
+          key === "groupIds" ||
+          key === "scale")
+      ) {
+        continue;
+      }
+
+      if (key === "scale") {
+        const prevScale = (element as any)[key];
+        const nextScale = value;
+        if (prevScale[0] === nextScale[0] && prevScale[1] === nextScale[1]) {
+          continue;
+        }
+      } else if (key === "points") {
+        const prevPoints = (element as any)[key];
+        const nextPoints = value;
+        if (prevPoints.length === nextPoints.length) {
+          let didChangePoints = false;
+          let index = prevPoints.length;
+          while (--index) {
+            const prevPoint = prevPoints[index];
+            const nextPoint = nextPoints[index];
+            if (
+              prevPoint[0] !== nextPoint[0] ||
+              prevPoint[1] !== nextPoint[1]
+            ) {
+              didChangePoints = true;
+              break;
+            }
+          }
+          if (!didChangePoints) {
+            continue;
+          }
+        }
+      }
+
+      (element as any)[key] = value;
+      didChange = true;
+    }
+  }
+
+  if (!didChange) {
+    return element;
+  }
+
+  if (
+    typeof updates.height !== "undefined" ||
+    typeof updates.width !== "undefined" ||
+    typeof fileId != "undefined" ||
+    typeof points !== "undefined"
+  ) {
+    ShapeCache.delete(element);
+  }
+
+  element.version = updates.version ?? element.version + 1;
+  element.versionNonce = updates.versionNonce ?? randomInteger();
+  element.updated = getUpdatedTimestamp();
+
+  return element;
+};
+
+export const newElementWith = <TElement extends ExcalidrawElement>(
+  element: TElement,
+  updates: ElementUpdate<TElement>,
+  /** pass `true` to always regenerate */
+  force = false,
+): TElement => {
+  let didChange = false;
+  for (const key in updates) {
+    const value = (updates as any)[key];
+    if (typeof value !== "undefined") {
+      if (
+        (element as any)[key] === value &&
+        // if object, always update because its attrs could have changed
+        (typeof value !== "object" || value === null)
+      ) {
+        continue;
+      }
+      didChange = true;
+    }
+  }
+
+  if (!didChange && !force) {
+    return element;
+  }
+
+  return {
+    ...element,
+    ...updates,
+    version: updates.version ?? element.version + 1,
+    versionNonce: updates.versionNonce ?? randomInteger(),
+    updated: getUpdatedTimestamp(),
+  };
+};
+
+/**
+ * Mutates element, bumping `version`, `versionNonce`, and `updated`.
+ *
+ * NOTE: does not trigger re-render.
+ */
+export const bumpVersion = <T extends Mutable<ExcalidrawElement>>(
+  element: T,
+  version?: ExcalidrawElement["version"],
+) => {
+  element.version = (version ?? element.version) + 1;
+  element.versionNonce = randomInteger();
+  element.updated = getUpdatedTimestamp();
+  return element;
+};

packages/element/src/newElement.ts

@@ -0,0 +1,660 @@
+import {
+  DEFAULT_ELEMENT_PROPS,
+  DEFAULT_FONT_FAMILY,
+  DEFAULT_FONT_SIZE,
+  DEFAULT_TEXT_ALIGN,
+  DEFAULT_STICKY_NOTE_SIZE,
+  STICKY_NOTE_MIN_SIZE,
+  DEFAULT_VERTICAL_ALIGN,
+  DEFAULT_STROKE_STREAMLINE,
+  VERTICAL_ALIGN,
+  randomInteger,
+  randomId,
+  getFontString,
+  getUpdatedTimestamp,
+  getLineHeight,
+} from "@excalidraw/common";
+
+import type { Radians } from "@excalidraw/math";
+
+import type { MarkOptional, Merge } from "@excalidraw/common/utility-types";
+
+import {
+  getElementAbsoluteCoords,
+  getResizedElementAbsoluteCoords,
+} from "./bounds";
+import { newElementWith } from "./mutateElement";
+import {
+  normalizeStickyNoteBackgroundColor,
+  normalizeStickyNoteStrokeColor,
+} from "./stickyNote";
+import { getBoundTextMaxWidth } from "./textElement";
+import { normalizeText, measureText } from "./textMeasurements";
+import { wrapText } from "./textWrapping";
+
+import { isLineElement } from "./typeChecks";
+
+import type {
+  ExcalidrawElement,
+  ExcalidrawImageElement,
+  ExcalidrawTextElement,
+  ExcalidrawLinearElement,
+  ExcalidrawGenericElement,
+  NonDeleted,
+  TextAlign,
+  VerticalAlign,
+  Arrowhead,
+  ExcalidrawFreeDrawElement,
+  FontFamilyValues,
+  ExcalidrawTextContainer,
+  ExcalidrawFrameElement,
+  ExcalidrawEmbeddableElement,
+  ExcalidrawMagicFrameElement,
+  ExcalidrawIframeElement,
+  ElementsMap,
+  ExcalidrawArrowElement,
+  ExcalidrawElbowArrowElement,
+  ExcalidrawLineElement,
+  ExcalidrawStickyNoteElement,
+} from "./types";
+
+export type ElementConstructorOpts = MarkOptional<
+  Omit<ExcalidrawGenericElement, "id" | "type" | "isDeleted" | "updated">,
+  | "width"
+  | "height"
+  | "angle"
+  | "groupIds"
+  | "frameId"
+  | "index"
+  | "boundElements"
+  | "seed"
+  | "version"
+  | "versionNonce"
+  | "link"
+  | "strokeStyle"
+  | "fillStyle"
+  | "strokeColor"
+  | "backgroundColor"
+  | "roughness"
+  | "strokeWidth"
+  | "roundness"
+  | "locked"
+  | "opacity"
+  | "customData"
+  | "created"
+>;
+
+const _newElementBase = <T extends ExcalidrawElement>(
+  type: T["type"],
+  {
+    x,
+    y,
+    strokeColor = DEFAULT_ELEMENT_PROPS.strokeColor,
+    backgroundColor = DEFAULT_ELEMENT_PROPS.backgroundColor,
+    fillStyle = DEFAULT_ELEMENT_PROPS.fillStyle,
+    strokeWidth = DEFAULT_ELEMENT_PROPS.strokeWidth,
+    strokeStyle = DEFAULT_ELEMENT_PROPS.strokeStyle,
+    roughness = DEFAULT_ELEMENT_PROPS.roughness,
+    opacity = DEFAULT_ELEMENT_PROPS.opacity,
+    width = 0,
+    height = 0,
+    angle = 0 as Radians,
+    groupIds = [],
+    frameId = null,
+    index = null,
+    roundness = null,
+    boundElements = null,
+    link = null,
+    locked = DEFAULT_ELEMENT_PROPS.locked,
+    ...rest
+  }: ElementConstructorOpts & Omit<Partial<ExcalidrawGenericElement>, "type">,
+) => {
+  // NOTE (mtolmacs): This is a temporary check to detect extremely large
+  // element position or sizing
+  if (
+    x < -1e6 ||
+    x > 1e6 ||
+    y < -1e6 ||
+    y > 1e6 ||
+    width < -1e6 ||
+    width > 1e6 ||
+    height < -1e6 ||
+    height > 1e6
+  ) {
+    console.error("New element size or position is too large", {
+      x,
+      y,
+      width,
+      height,
+      // @ts-ignore
+      points: rest.points,
+    });
+  }
+
+  const timestamp = getUpdatedTimestamp();
+
+  // assign type to guard against excess properties
+  const element: Merge<
+    ExcalidrawGenericElement,
+    { type: T["type"]; isDeleted: false }
+  > = {
+    id: rest.id || randomId(),
+    type,
+    x,
+    y,
+    width,
+    height,
+    angle,
+    strokeColor,
+    backgroundColor,
+    fillStyle,
+    strokeWidth,
+    strokeStyle,
+    roughness,
+    opacity,
+    groupIds,
+    frameId,
+    index,
+    roundness,
+    seed: rest.seed ?? randomInteger(),
+    version: rest.version || 1,
+    versionNonce: rest.versionNonce ?? 0,
+    isDeleted: false as false,
+    boundElements,
+    updated: timestamp,
+    // Preserve explicit null when reconstructing a legacy element with its id.
+    created: rest.created === undefined ? timestamp : rest.created,
+    link,
+    locked,
+    customData: rest.customData,
+  };
+  return element;
+};
+
+export const newElement = (
+  opts: {
+    type: ExcalidrawGenericElement["type"];
+  } & ElementConstructorOpts,
+): NonDeleted<ExcalidrawGenericElement> =>
+  _newElementBase<ExcalidrawGenericElement>(opts.type, opts);
+
+/**
+ * Style invariants of a sticky note: never-transparent colors, solid fill.
+ * Applied by the constructor and by every normalization pass. Returns the
+ * same object when nothing needs fixing.
+ */
+export const normalizeStickyNoteStyle = <T extends ExcalidrawStickyNoteElement>(
+  element: T,
+): T => {
+  return newElementWith(element as ExcalidrawStickyNoteElement, {
+    backgroundColor: normalizeStickyNoteBackgroundColor(
+      element.backgroundColor,
+    ),
+    strokeColor: normalizeStickyNoteStrokeColor(element.strokeColor),
+    fillStyle: "solid",
+  }) as T;
+};
+
+/**
+ * Geometry invariants of a *finalized* sticky note: minimum size and
+ * `baseHeight ≤ height`. Deliberately not part of the constructor — a
+ * pointer-down draft starts at 0×0 like every other tool and is previewed at
+ * its true dragged size; pointer-up, restore, the skeleton path and the
+ * action post-passes enforce this.
+ */
+export const normalizeStickyNoteGeometry = <
+  T extends ExcalidrawStickyNoteElement,
+>(
+  element: T,
+): T => {
+  const width = Math.max(element.width, STICKY_NOTE_MIN_SIZE);
+  const baseHeight = Math.max(
+    element.baseHeight || element.height || DEFAULT_STICKY_NOTE_SIZE,
+    STICKY_NOTE_MIN_SIZE,
+  );
+
+  return newElementWith(element as ExcalidrawStickyNoteElement, {
+    width,
+    height: Math.max(element.height, baseHeight),
+    baseHeight,
+  }) as T;
+};
+
+/** all sticky note invariants (style + finalized geometry) */
+export const normalizeStickyNote = <T extends ExcalidrawStickyNoteElement>(
+  element: T,
+): T => {
+  return normalizeStickyNoteGeometry(normalizeStickyNoteStyle(element));
+};
+
+export const newStickyNoteElement = (
+  opts: {
+    type: "stickynote";
+    baseHeight?: number;
+  } & ElementConstructorOpts,
+): NonDeleted<ExcalidrawStickyNoteElement> => {
+  const base = _newElementBase<ExcalidrawStickyNoteElement>("stickynote", opts);
+
+  // no size inflation here (see `normalizeStickyNoteGeometry`)
+  return normalizeStickyNoteStyle({
+    ...base,
+    baseHeight: opts.baseHeight ?? base.height,
+  });
+};
+
+export const newEmbeddableElement = (
+  opts: {
+    type: "embeddable";
+  } & ElementConstructorOpts,
+): NonDeleted<ExcalidrawEmbeddableElement> => {
+  return _newElementBase<ExcalidrawEmbeddableElement>("embeddable", opts);
+};
+
+export const newIframeElement = (
+  opts: {
+    type: "iframe";
+  } & ElementConstructorOpts,
+): NonDeleted<ExcalidrawIframeElement> => {
+  return {
+    ..._newElementBase<ExcalidrawIframeElement>("iframe", opts),
+  };
+};
+
+export const newFrameElement = (
+  opts: {
+    name?: string;
+  } & ElementConstructorOpts,
+): NonDeleted<ExcalidrawFrameElement> => {
+  const frameElement = newElementWith(
+    {
+      ..._newElementBase<ExcalidrawFrameElement>("frame", opts),
+      type: "frame",
+      name: opts?.name || null,
+    },
+    {},
+  );
+
+  return frameElement;
+};
+
+export const newMagicFrameElement = (
+  opts: {
+    name?: string;
+  } & ElementConstructorOpts,
+): NonDeleted<ExcalidrawMagicFrameElement> => {
+  const frameElement = newElementWith(
+    {
+      ..._newElementBase<ExcalidrawMagicFrameElement>("magicframe", opts),
+      type: "magicframe",
+      name: opts?.name || null,
+    },
+    {},
+  );
+
+  return frameElement;
+};
+
+/**
+ * The point of the text box its alignment pins, as ratios of width/height.
+ *
+ * This is the point that stays put as the text grows — see the sides passed to
+ * `adjustXYWithRotation` in `getAdjustedDimensions`.
+ */
+export const getTextAnchorRatios = (opts: {
+  textAlign: ExcalidrawTextElement["textAlign"];
+  verticalAlign: ExcalidrawTextElement["verticalAlign"];
+}) => ({
+  x: opts.textAlign === "center" ? 0.5 : opts.textAlign === "right" ? 1 : 0,
+  y:
+    opts.verticalAlign === VERTICAL_ALIGN.MIDDLE
+      ? 0.5
+      : opts.verticalAlign === VERTICAL_ALIGN.BOTTOM
+      ? 1
+      : 0,
+});
+
+/** computes element x/y offset based on textAlign/verticalAlign */
+const getTextElementPositionOffsets = (
+  opts: {
+    textAlign: ExcalidrawTextElement["textAlign"];
+    verticalAlign: ExcalidrawTextElement["verticalAlign"];
+  },
+  metrics: {
+    width: number;
+    height: number;
+  },
+) => {
+  const ratios = getTextAnchorRatios(opts);
+
+  return {
+    x: metrics.width * ratios.x,
+    y: metrics.height * ratios.y,
+  };
+};
+
+export const newTextElement = (
+  opts: {
+    text: string;
+    originalText?: string;
+    fontSize?: number;
+    fontFamily?: FontFamilyValues;
+    textAlign?: TextAlign;
+    verticalAlign?: VerticalAlign;
+    containerId?: ExcalidrawTextContainer["id"] | null;
+    lineHeight?: ExcalidrawTextElement["lineHeight"];
+    autoResize?: ExcalidrawTextElement["autoResize"];
+    labelPosition?: ExcalidrawTextElement["labelPosition"];
+    baseFontSize?: ExcalidrawTextElement["baseFontSize"];
+  } & ElementConstructorOpts,
+): NonDeleted<ExcalidrawTextElement> => {
+  const fontFamily = opts.fontFamily || DEFAULT_FONT_FAMILY;
+  const fontSize = opts.fontSize || DEFAULT_FONT_SIZE;
+  const lineHeight = opts.lineHeight || getLineHeight(fontFamily);
+  const text = normalizeText(opts.text);
+  const metrics = measureText(
+    text,
+    getFontString({ fontFamily, fontSize }),
+    lineHeight,
+  );
+  const textAlign = opts.textAlign || DEFAULT_TEXT_ALIGN;
+  const verticalAlign = opts.verticalAlign || DEFAULT_VERTICAL_ALIGN;
+  const offsets = getTextElementPositionOffsets(
+    { textAlign, verticalAlign },
+    metrics,
+  );
+
+  const textElementProps: NonDeleted<ExcalidrawTextElement> = {
+    ..._newElementBase<ExcalidrawTextElement>("text", opts),
+    text,
+    fontSize,
+    baseFontSize: opts.baseFontSize ?? null,
+    fontFamily,
+    textAlign,
+    verticalAlign,
+    x: opts.x - offsets.x,
+    y: opts.y - offsets.y,
+    width: metrics.width,
+    height: metrics.height,
+    containerId: opts.containerId || null,
+    originalText: opts.originalText ?? text,
+    autoResize: opts.autoResize ?? true,
+    lineHeight,
+    labelPosition: opts.labelPosition ?? null,
+  };
+
+  const textElement: NonDeleted<ExcalidrawTextElement> = newElementWith(
+    textElementProps,
+    {},
+  );
+
+  return textElement;
+};
+
+const getAdjustedDimensions = (
+  element: ExcalidrawTextElement,
+  elementsMap: ElementsMap,
+  nextText: string,
+): {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+} => {
+  let { width: nextWidth, height: nextHeight } = measureText(
+    nextText,
+    getFontString(element),
+    element.lineHeight,
+  );
+
+  // wrapped text
+  if (!element.autoResize) {
+    nextWidth = element.width;
+  }
+
+  const { textAlign, verticalAlign } = element;
+  let x: number;
+  let y: number;
+  if (
+    textAlign === "center" &&
+    verticalAlign === VERTICAL_ALIGN.MIDDLE &&
+    !element.containerId &&
+    element.autoResize
+  ) {
+    const prevMetrics = measureText(
+      element.text,
+      getFontString(element),
+      element.lineHeight,
+    );
+    const offsets = getTextElementPositionOffsets(element, {
+      width: nextWidth - prevMetrics.width,
+      height: nextHeight - prevMetrics.height,
+    });
+
+    x = element.x - offsets.x;
+    y = element.y - offsets.y;
+  } else {
+    const [x1, y1, x2, y2] = getElementAbsoluteCoords(element, elementsMap);
+
+    const [nextX1, nextY1, nextX2, nextY2] = getResizedElementAbsoluteCoords(
+      element,
+      nextWidth,
+      nextHeight,
+      false,
+    );
+    const deltaX1 = (x1 - nextX1) / 2;
+    const deltaY1 = (y1 - nextY1) / 2;
+    const deltaX2 = (x2 - nextX2) / 2;
+    const deltaY2 = (y2 - nextY2) / 2;
+
+    // grow away from the edge(s) the alignment anchors the text to, so that
+    // the anchor stays put as the text is edited. `verticalAlign` has no
+    // visual effect on unbound text, but standalone text bound to an arrow
+    // endpoint uses it to pin the side the arrow attaches to.
+    [x, y] = adjustXYWithRotation(
+      {
+        n:
+          verticalAlign === VERTICAL_ALIGN.MIDDLE ||
+          verticalAlign === VERTICAL_ALIGN.BOTTOM,
+        s:
+          verticalAlign === VERTICAL_ALIGN.MIDDLE ||
+          verticalAlign === VERTICAL_ALIGN.TOP,
+        e: textAlign === "center" || textAlign === "left",
+        w: textAlign === "center" || textAlign === "right",
+      },
+      element.x,
+      element.y,
+      element.angle,
+      deltaX1,
+      deltaY1,
+      deltaX2,
+      deltaY2,
+    );
+  }
+
+  return {
+    width: nextWidth,
+    height: nextHeight,
+    x: Number.isFinite(x) ? x : element.x,
+    y: Number.isFinite(y) ? y : element.y,
+  };
+};
+
+const adjustXYWithRotation = (
+  sides: {
+    n?: boolean;
+    e?: boolean;
+    s?: boolean;
+    w?: boolean;
+  },
+  x: number,
+  y: number,
+  angle: number,
+  deltaX1: number,
+  deltaY1: number,
+  deltaX2: number,
+  deltaY2: number,
+): [number, number] => {
+  const cos = Math.cos(angle);
+  const sin = Math.sin(angle);
+  if (sides.e && sides.w) {
+    x += deltaX1 + deltaX2;
+  } else if (sides.e) {
+    x += deltaX1 * (1 + cos);
+    y += deltaX1 * sin;
+    x += deltaX2 * (1 - cos);
+    y += deltaX2 * -sin;
+  } else if (sides.w) {
+    x += deltaX1 * (1 - cos);
+    y += deltaX1 * -sin;
+    x += deltaX2 * (1 + cos);
+    y += deltaX2 * sin;
+  }
+
+  if (sides.n && sides.s) {
+    y += deltaY1 + deltaY2;
+  } else if (sides.n) {
+    x += deltaY1 * sin;
+    y += deltaY1 * (1 - cos);
+    x += deltaY2 * -sin;
+    y += deltaY2 * (1 + cos);
+  } else if (sides.s) {
+    x += deltaY1 * -sin;
+    y += deltaY1 * (1 + cos);
+    x += deltaY2 * sin;
+    y += deltaY2 * (1 - cos);
+  }
+  return [x, y];
+};
+
+export const refreshTextDimensions = (
+  textElement: ExcalidrawTextElement,
+  container: ExcalidrawTextContainer | null,
+  elementsMap: ElementsMap,
+  text = textElement.text,
+) => {
+  if (textElement.isDeleted) {
+    return;
+  }
+  if (container || !textElement.autoResize) {
+    text = wrapText(
+      text,
+      getFontString(textElement),
+      container
+        ? getBoundTextMaxWidth(container, textElement)
+        : textElement.width,
+    );
+  }
+  const dimensions = getAdjustedDimensions(textElement, elementsMap, text);
+  return { text, ...dimensions };
+};
+
+export const newFreeDrawElement = (
+  opts: {
+    type: "freedraw";
+    points?: ExcalidrawFreeDrawElement["points"];
+    simulatePressure: boolean;
+    strokeOptions?: ExcalidrawFreeDrawElement["strokeOptions"];
+    pressures?: ExcalidrawFreeDrawElement["pressures"];
+  } & ElementConstructorOpts,
+): NonDeleted<ExcalidrawFreeDrawElement> => {
+  return {
+    ..._newElementBase<ExcalidrawFreeDrawElement>(opts.type, opts),
+    points: opts.points || [],
+    pressures: opts.pressures || [],
+    simulatePressure: opts.simulatePressure,
+    strokeOptions: opts.strokeOptions ?? {
+      variability: "variable",
+      streamline: DEFAULT_STROKE_STREAMLINE,
+    },
+  };
+};
+
+export const newLinearElement = (
+  opts: {
+    type: ExcalidrawLinearElement["type"];
+    points?: ExcalidrawLinearElement["points"];
+    polygon?: ExcalidrawLineElement["polygon"];
+  } & ElementConstructorOpts,
+): NonDeleted<ExcalidrawLinearElement> => {
+  const element = {
+    ..._newElementBase<ExcalidrawLinearElement>(opts.type, opts),
+    points: opts.points || [],
+
+    startBinding: null,
+    endBinding: null,
+    startArrowhead: null,
+    endArrowhead: null,
+  };
+
+  if (isLineElement(element)) {
+    const lineElement: NonDeleted<ExcalidrawLineElement> = {
+      ...element,
+      polygon: opts.polygon ?? false,
+    };
+
+    return lineElement;
+  }
+
+  return element;
+};
+
+export const newArrowElement = <T extends boolean>(
+  opts: {
+    type: ExcalidrawArrowElement["type"];
+    startArrowhead?: Arrowhead | null;
+    endArrowhead?: Arrowhead | null;
+    points?: ExcalidrawArrowElement["points"];
+    elbowed?: T;
+    fixedSegments?: ExcalidrawElbowArrowElement["fixedSegments"] | null;
+  } & ElementConstructorOpts,
+): T extends true
+  ? NonDeleted<ExcalidrawElbowArrowElement>
+  : NonDeleted<ExcalidrawArrowElement> => {
+  if (opts.elbowed) {
+    return {
+      ..._newElementBase<ExcalidrawElbowArrowElement>(opts.type, opts),
+      points: opts.points || [],
+      startBinding: null,
+      endBinding: null,
+      startArrowhead: opts.startArrowhead || null,
+      endArrowhead: opts.endArrowhead || null,
+      elbowed: true,
+      fixedSegments: opts.fixedSegments || [],
+      startIsSpecial: false,
+      endIsSpecial: false,
+    } as NonDeleted<ExcalidrawElbowArrowElement>;
+  }
+
+  return {
+    ..._newElementBase<ExcalidrawArrowElement>(opts.type, opts),
+    points: opts.points || [],
+    startBinding: null,
+    endBinding: null,
+    startArrowhead: opts.startArrowhead || null,
+    endArrowhead: opts.endArrowhead || null,
+    elbowed: false,
+  } as T extends true
+    ? NonDeleted<ExcalidrawElbowArrowElement>
+    : NonDeleted<ExcalidrawArrowElement>;
+};
+
+export const newImageElement = (
+  opts: {
+    type: ExcalidrawImageElement["type"];
+    status?: ExcalidrawImageElement["status"];
+    fileId?: ExcalidrawImageElement["fileId"];
+    scale?: ExcalidrawImageElement["scale"];
+    crop?: ExcalidrawImageElement["crop"];
+  } & ElementConstructorOpts,
+): NonDeleted<ExcalidrawImageElement> => {
+  return {
+    ..._newElementBase<ExcalidrawImageElement>("image", opts),
+    // in the future we'll support changing stroke color for some SVG elements,
+    // and `transparent` will likely mean "use original colors of the image"
+    strokeColor: "transparent",
+    status: opts.status ?? "pending",
+    fileId: opts.fileId ?? null,
+    scale: opts.scale ?? [1, 1],
+    crop: opts.crop ?? null,
+  };
+};

packages/element/src/positionElementsOnGrid.ts

@@ -0,0 +1,112 @@
+import { getCommonBounds } from "./bounds";
+import { type ElementUpdate, newElementWith } from "./mutateElement";
+
+import type { ExcalidrawElement } from "./types";
+
+// TODO rewrite (mostly vibe-coded)
+export const positionElementsOnGrid = <TElement extends ExcalidrawElement>(
+  elements: TElement[] | TElement[][],
+  centerX: number,
+  centerY: number,
+  padding = 50,
+): TElement[] => {
+  // Ensure there are elements to position
+  if (!elements || elements.length === 0) {
+    return [];
+  }
+
+  const res: TElement[] = [];
+  // Normalize input to work with atomic units (groups of elements)
+  // If elements is a flat array, treat each element as its own atomic unit
+  const atomicUnits: TElement[][] = Array.isArray(elements[0])
+    ? (elements as TElement[][])
+    : (elements as TElement[]).map((element) => [element]);
+
+  // Determine the number of columns for atomic units
+  // A common approach for a "grid-like" layout without specific column constraints
+  // is to aim for a roughly square arrangement.
+  const numUnits = atomicUnits.length;
+  const numColumns = Math.max(1, Math.ceil(Math.sqrt(numUnits)));
+
+  // Group atomic units into rows based on the calculated number of columns
+  const rows: TElement[][][] = [];
+  for (let i = 0; i < numUnits; i += numColumns) {
+    rows.push(atomicUnits.slice(i, i + numColumns));
+  }
+
+  // Calculate properties for each row (total width, max height)
+  // and the total actual height of all row content.
+  let totalGridActualHeight = 0; // Sum of max heights of rows, without inter-row padding
+  const rowProperties = rows.map((rowUnits) => {
+    let rowWidth = 0;
+    let maxUnitHeightInRow = 0;
+
+    const unitBounds = rowUnits.map((unit) => {
+      const [minX, minY, maxX, maxY] = getCommonBounds(unit);
+      return {
+        elements: unit,
+        bounds: [minX, minY, maxX, maxY] as const,
+        width: maxX - minX,
+        height: maxY - minY,
+      };
+    });
+
+    unitBounds.forEach((unitBound, index) => {
+      rowWidth += unitBound.width;
+      // Add padding between units in the same row, but not after the last one
+      if (index < unitBounds.length - 1) {
+        rowWidth += padding;
+      }
+      if (unitBound.height > maxUnitHeightInRow) {
+        maxUnitHeightInRow = unitBound.height;
+      }
+    });
+
+    totalGridActualHeight += maxUnitHeightInRow;
+    return {
+      unitBounds,
+      width: rowWidth,
+      maxHeight: maxUnitHeightInRow,
+    };
+  });
+
+  // Calculate the total height of the grid including padding between rows
+  const totalGridHeightWithPadding =
+    totalGridActualHeight + Math.max(0, rows.length - 1) * padding;
+
+  // Calculate the starting Y position to center the entire grid vertically around centerY
+  let currentY = centerY - totalGridHeightWithPadding / 2;
+
+  // Position atomic units row by row
+  rowProperties.forEach((rowProp) => {
+    const { unitBounds, width: rowWidth, maxHeight: rowMaxHeight } = rowProp;
+
+    // Calculate the starting X for the current row to center it horizontally around centerX
+    let currentX = centerX - rowWidth / 2;
+
+    unitBounds.forEach((unitBound) => {
+      // Calculate the offset needed to position this atomic unit
+      const [originalMinX, originalMinY] = unitBound.bounds;
+      const offsetX = currentX - originalMinX;
+      const offsetY = currentY - originalMinY;
+
+      // Apply the offset to all elements in this atomic unit
+      unitBound.elements.forEach((element) => {
+        res.push(
+          newElementWith(element, {
+            x: element.x + offsetX,
+            y: element.y + offsetY,
+          } as ElementUpdate<TElement>),
+        );
+      });
+
+      // Move X for the next unit in the row
+      currentX += unitBound.width + padding;
+    });
+
+    // Move Y to the starting position for the next row
+    // This accounts for the tallest unit in the current row and the inter-row padding
+    currentY += rowMaxHeight + padding;
+  });
+  return res;
+};

packages/element/src/resizeTest.ts

@@ -0,0 +1,294 @@
+import {
+  pointFrom,
+  pointOnLineSegment,
+  pointRotateRads,
+  type Radians,
+} from "@excalidraw/math";
+
+import {
+  SIDE_RESIZING_THRESHOLD,
+  type EditorInterface,
+} from "@excalidraw/common";
+
+import type { GlobalPoint, LineSegment, LocalPoint } from "@excalidraw/math";
+
+import type { AppState, Zoom } from "@excalidraw/excalidraw/types";
+import type { Bounds } from "@excalidraw/common";
+
+import { getElementAbsoluteCoords } from "./bounds";
+import {
+  getTransformHandlesFromCoords,
+  getTransformHandles,
+  getOmitSidesForEditorInterface,
+  canResizeFromSides,
+} from "./transformHandles";
+import { isImageElement, isLinearElement } from "./typeChecks";
+
+import type {
+  TransformHandleType,
+  TransformHandle,
+  MaybeTransformHandleType,
+} from "./transformHandles";
+import type {
+  ExcalidrawElement,
+  PointerType,
+  NonDeletedExcalidrawElement,
+  ElementsMap,
+} from "./types";
+
+const isInsideTransformHandle = (
+  transformHandle: TransformHandle,
+  x: number,
+  y: number,
+) =>
+  x >= transformHandle[0] &&
+  x <= transformHandle[0] + transformHandle[2] &&
+  y >= transformHandle[1] &&
+  y <= transformHandle[1] + transformHandle[3];
+
+export const resizeTest = <Point extends GlobalPoint | LocalPoint>(
+  element: NonDeletedExcalidrawElement,
+  elementsMap: ElementsMap,
+  appState: AppState,
+  x: number,
+  y: number,
+  zoom: Zoom,
+  pointerType: PointerType,
+  editorInterface: EditorInterface,
+): MaybeTransformHandleType => {
+  if (!appState.selectedElementIds[element.id]) {
+    return false;
+  }
+
+  const { rotation: rotationTransformHandle, ...transformHandles } =
+    getTransformHandles(
+      element,
+      zoom,
+      elementsMap,
+      pointerType,
+      getOmitSidesForEditorInterface(editorInterface),
+    );
+
+  if (
+    rotationTransformHandle &&
+    isInsideTransformHandle(rotationTransformHandle, x, y)
+  ) {
+    return "rotation" as TransformHandleType;
+  }
+
+  const filter = Object.keys(transformHandles).filter((key) => {
+    const transformHandle =
+      transformHandles[key as Exclude<TransformHandleType, "rotation">]!;
+    if (!transformHandle) {
+      return false;
+    }
+    return isInsideTransformHandle(transformHandle, x, y);
+  });
+
+  if (filter.length > 0) {
+    return filter[0] as TransformHandleType;
+  }
+
+  if (canResizeFromSides(editorInterface)) {
+    const [x1, y1, x2, y2, cx, cy] = getElementAbsoluteCoords(
+      element,
+      elementsMap,
+    );
+
+    // do not resize from the sides for linear elements with only two points
+    if (!(isLinearElement(element) && element.points.length <= 2)) {
+      const SPACING = isImageElement(element)
+        ? 0
+        : SIDE_RESIZING_THRESHOLD / zoom.value;
+      const ZOOMED_SIDE_RESIZING_THRESHOLD =
+        SIDE_RESIZING_THRESHOLD / zoom.value;
+      const sides = getSelectionBorders(
+        pointFrom(x1 - SPACING, y1 - SPACING),
+        pointFrom(x2 + SPACING, y2 + SPACING),
+        pointFrom(cx, cy),
+        element.angle,
+      );
+
+      for (const [dir, side] of Object.entries(sides)) {
+        // test to see if x, y are on the line segment
+        if (
+          pointOnLineSegment(
+            pointFrom(x, y),
+            side as LineSegment<Point>,
+            ZOOMED_SIDE_RESIZING_THRESHOLD,
+          )
+        ) {
+          return dir as TransformHandleType;
+        }
+      }
+    }
+  }
+
+  return false;
+};
+
+export const getElementWithTransformHandleType = (
+  elements: readonly NonDeletedExcalidrawElement[],
+  appState: AppState,
+  scenePointerX: number,
+  scenePointerY: number,
+  zoom: Zoom,
+  pointerType: PointerType,
+  elementsMap: ElementsMap,
+  editorInterface: EditorInterface,
+) => {
+  return elements.reduce((result, element) => {
+    if (result) {
+      return result;
+    }
+    const transformHandleType = resizeTest(
+      element,
+      elementsMap,
+      appState,
+      scenePointerX,
+      scenePointerY,
+      zoom,
+      pointerType,
+      editorInterface,
+    );
+    return transformHandleType ? { element, transformHandleType } : null;
+  }, null as { element: NonDeletedExcalidrawElement; transformHandleType: MaybeTransformHandleType } | null);
+};
+
+export const getTransformHandleTypeFromCoords = <
+  Point extends GlobalPoint | LocalPoint,
+>(
+  [x1, y1, x2, y2]: Bounds,
+  scenePointerX: number,
+  scenePointerY: number,
+  zoom: Zoom,
+  pointerType: PointerType,
+  editorInterface: EditorInterface,
+): MaybeTransformHandleType => {
+  const transformHandles = getTransformHandlesFromCoords(
+    [x1, y1, x2, y2, (x1 + x2) / 2, (y1 + y2) / 2],
+    0 as Radians,
+    zoom,
+    pointerType,
+    getOmitSidesForEditorInterface(editorInterface),
+  );
+
+  const found = Object.keys(transformHandles).find((key) => {
+    const transformHandle =
+      transformHandles[key as Exclude<TransformHandleType, "rotation">]!;
+    return (
+      transformHandle &&
+      isInsideTransformHandle(transformHandle, scenePointerX, scenePointerY)
+    );
+  });
+
+  if (found) {
+    return found as MaybeTransformHandleType;
+  }
+
+  if (canResizeFromSides(editorInterface)) {
+    const cx = (x1 + x2) / 2;
+    const cy = (y1 + y2) / 2;
+
+    const SPACING = SIDE_RESIZING_THRESHOLD / zoom.value;
+
+    const sides = getSelectionBorders(
+      pointFrom(x1 - SPACING, y1 - SPACING),
+      pointFrom(x2 + SPACING, y2 + SPACING),
+      pointFrom(cx, cy),
+      0 as Radians,
+    );
+
+    for (const [dir, side] of Object.entries(sides)) {
+      // test to see if x, y are on the line segment
+      if (
+        pointOnLineSegment(
+          pointFrom(scenePointerX, scenePointerY),
+          side as LineSegment<Point>,
+          SPACING,
+        )
+      ) {
+        return dir as TransformHandleType;
+      }
+    }
+  }
+
+  return false;
+};
+
+const RESIZE_CURSORS = ["ns", "nesw", "ew", "nwse"];
+const rotateResizeCursor = (cursor: string, angle: number) => {
+  const index = RESIZE_CURSORS.indexOf(cursor);
+  if (index >= 0) {
+    const a = Math.round(angle / (Math.PI / 4));
+    cursor = RESIZE_CURSORS[(index + a) % RESIZE_CURSORS.length];
+  }
+  return cursor;
+};
+
+/*
+ * Returns bi-directional cursor for the element being resized
+ */
+export const getCursorForResizingElement = (resizingElement: {
+  element?: ExcalidrawElement;
+  transformHandleType: MaybeTransformHandleType;
+}): string => {
+  const { element, transformHandleType } = resizingElement;
+  const shouldSwapCursors =
+    element && Math.sign(element.height) * Math.sign(element.width) === -1;
+  let cursor = null;
+
+  switch (transformHandleType) {
+    case "n":
+    case "s":
+      cursor = "ns";
+      break;
+    case "w":
+    case "e":
+      cursor = "ew";
+      break;
+    case "nw":
+    case "se":
+      if (shouldSwapCursors) {
+        cursor = "nesw";
+      } else {
+        cursor = "nwse";
+      }
+      break;
+    case "ne":
+    case "sw":
+      if (shouldSwapCursors) {
+        cursor = "nwse";
+      } else {
+        cursor = "nesw";
+      }
+      break;
+    case "rotation":
+      return "grab";
+  }
+
+  if (cursor && element) {
+    cursor = rotateResizeCursor(cursor, element.angle);
+  }
+
+  return cursor ? `${cursor}-resize` : "";
+};
+
+const getSelectionBorders = <Point extends LocalPoint | GlobalPoint>(
+  [x1, y1]: Point,
+  [x2, y2]: Point,
+  center: Point,
+  angle: Radians,
+) => {
+  const topLeft = pointRotateRads(pointFrom(x1, y1), center, angle);
+  const topRight = pointRotateRads(pointFrom(x2, y1), center, angle);
+  const bottomLeft = pointRotateRads(pointFrom(x1, y2), center, angle);
+  const bottomRight = pointRotateRads(pointFrom(x2, y2), center, angle);
+
+  return {
+    n: [topLeft, topRight],
+    e: [topRight, bottomRight],
+    s: [bottomRight, bottomLeft],
+    w: [bottomLeft, topLeft],
+  };
+};

packages/element/src/selection.ts

@@ -0,0 +1,308 @@
+import { arrayToMap, isShallowEqual, type Bounds } from "@excalidraw/common";
+
+import type {
+  AppState,
+  BoxSelectionMode,
+  InteractiveCanvasAppState,
+} from "@excalidraw/excalidraw/types";
+
+import { elementsOverlappingBBox, getElementAbsoluteCoords } from "./bounds";
+import { isElementInViewport } from "./sizeHelpers";
+import {
+  isBoundToContainer,
+  isFrameLikeElement,
+  isLinearElement,
+  isTextElement,
+} from "./typeChecks";
+import { getFrameChildren } from "./frame";
+
+import { LinearElementEditor } from "./linearElementEditor";
+import { selectGroupsForSelectedElements } from "./groups";
+
+import { isNonDeletedElement } from ".";
+
+import type {
+  ElementsMap,
+  ElementsMapOrArray,
+  ExcalidrawElement,
+  ExcalidrawFrameLikeElement,
+  NonDeleted,
+  NonDeletedExcalidrawElement,
+} from "./types";
+
+const shouldIgnoreElementFromSelection = (element: ExcalidrawElement) =>
+  element.locked || isBoundToContainer(element);
+
+const excludeElementsFromFrames = <T extends ExcalidrawElement>(
+  selectedElements: readonly T[],
+  framesInSelection: Set<ExcalidrawFrameLikeElement["id"]>,
+) => {
+  return selectedElements.filter((element) => {
+    if (element.frameId && framesInSelection.has(element.frameId)) {
+      return false;
+    }
+    return true;
+  });
+};
+
+/**
+ * Frames and their containing elements are not to be selected at the same time.
+ * Given an array of selected elements, if there are frames and their containing elements
+ * we only keep the frames.
+ * @param selectedElements
+ */
+export const excludeElementsInFramesFromSelection = <
+  T extends ExcalidrawElement,
+>(
+  selectedElements: readonly T[],
+) => {
+  const framesInSelection = new Set<T["id"]>();
+
+  selectedElements.forEach((element) => {
+    if (isFrameLikeElement(element)) {
+      framesInSelection.add(element.id);
+    }
+  });
+
+  return excludeElementsFromFrames(selectedElements, framesInSelection);
+};
+
+export const getElementsWithinSelection = <T extends ExcalidrawElement>(
+  elements: readonly T[],
+  selection: ExcalidrawElement,
+  elementsMap: ElementsMap,
+  // TODO remove (this flag is effectively unused AFAIK)
+  excludeElementsInFrames: boolean = true,
+  boxSelectionMode: BoxSelectionMode = "contain",
+): T[] => {
+  const [selectionStartX, selectionStartY, selectionEndX, selectionEndY] =
+    getElementAbsoluteCoords(selection, elementsMap);
+  const selectionX1 = Math.min(selectionStartX, selectionEndX);
+  const selectionY1 = Math.min(selectionStartY, selectionEndY);
+  const selectionX2 = Math.max(selectionStartX, selectionEndX);
+  const selectionY2 = Math.max(selectionStartY, selectionEndY);
+  const selectionBounds = [
+    selectionX1,
+    selectionY1,
+    selectionX2,
+    selectionY2,
+  ] as Bounds;
+
+  return elementsOverlappingBBox({
+    elements,
+    bounds: selectionBounds,
+    elementsMap,
+    type: boxSelectionMode,
+    shouldIgnoreElementFromSelection,
+    excludeElementsInFrames,
+  });
+};
+
+export const getVisibleAndNonSelectedElements = <
+  T extends NonDeletedExcalidrawElement,
+>(
+  elements: readonly T[],
+  selectedElements: readonly ExcalidrawElement[],
+  appState: AppState,
+  elementsMap: ElementsMap,
+) => {
+  const selectedElementsSet = new Set(
+    selectedElements.map((element) => element.id),
+  );
+  return elements.filter((element) => {
+    const isVisible = isElementInViewport(
+      element,
+      appState.width,
+      appState.height,
+      appState,
+      elementsMap,
+    );
+
+    return !selectedElementsSet.has(element.id) && isVisible;
+  });
+};
+
+// FIXME move this into the editor instance to keep utility methods stateless
+export const isSomeElementSelected = (function () {
+  let lastElements: readonly NonDeletedExcalidrawElement[] | null = null;
+  let lastSelectedElementIds: AppState["selectedElementIds"] | null = null;
+  let isSelected: boolean | null = null;
+
+  const ret = (
+    elements: readonly NonDeletedExcalidrawElement[],
+    appState: Pick<AppState, "selectedElementIds">,
+  ): boolean => {
+    if (
+      isSelected != null &&
+      elements === lastElements &&
+      appState.selectedElementIds === lastSelectedElementIds
+    ) {
+      return isSelected;
+    }
+
+    isSelected = elements.some(
+      (element) => appState.selectedElementIds[element.id],
+    );
+    lastElements = elements;
+    lastSelectedElementIds = appState.selectedElementIds;
+
+    return isSelected;
+  };
+
+  ret.clearCache = () => {
+    lastElements = null;
+    lastSelectedElementIds = null;
+    isSelected = null;
+  };
+
+  return ret;
+})();
+
+export const getSelectedElements = (
+  elements: ElementsMapOrArray,
+  appState: Pick<InteractiveCanvasAppState, "selectedElementIds">,
+  opts?: {
+    includeBoundTextElement?: boolean;
+    includeElementsInFrames?: boolean;
+  },
+) => {
+  const addedElements = new Set<ExcalidrawElement["id"]>();
+  // selection can only contain non-deleted elements
+  const selectedElements: NonDeletedExcalidrawElement[] = [];
+  for (const element of elements.values()) {
+    if (appState.selectedElementIds[element.id]) {
+      if (isNonDeletedElement(element)) {
+        selectedElements.push(element as NonDeletedExcalidrawElement);
+        addedElements.add(element.id);
+      } else {
+        console.error(
+          "[NONDELETED][INVARIANT] getSelectedElements skipping deleted selected element which should not be in the selection",
+        );
+      }
+      continue;
+    }
+    if (
+      opts?.includeBoundTextElement &&
+      isBoundToContainer(element) &&
+      isNonDeletedElement(element) &&
+      appState.selectedElementIds[element?.containerId]
+    ) {
+      selectedElements.push(element as NonDeletedExcalidrawElement);
+      addedElements.add(element.id);
+      continue;
+    }
+  }
+
+  if (opts?.includeElementsInFrames) {
+    const elementsToInclude: NonDeletedExcalidrawElement[] = [];
+    selectedElements.forEach((element) => {
+      if (isFrameLikeElement(element)) {
+        getFrameChildren(elements, element.id).forEach(
+          (e) =>
+            !addedElements.has(e.id) &&
+            elementsToInclude.push(e as NonDeletedExcalidrawElement),
+        );
+      }
+      elementsToInclude.push(element);
+    });
+
+    return elementsToInclude;
+  }
+
+  return selectedElements;
+};
+
+export const getTargetElements = (
+  elements: ElementsMapOrArray,
+  appState: Pick<
+    AppState,
+    "selectedElementIds" | "editingTextElement" | "newElement" | "activeTool"
+  >,
+) =>
+  appState.editingTextElement
+    ? [appState.editingTextElement]
+    : // the drawShape recognition preview in `newElement` is not a real
+    // in-progress element — targeting it would make the styles panel track
+    // whatever shape is currently recognized instead of the tool defaults
+    appState.newElement && appState.activeTool.type !== "autoshape"
+    ? [appState.newElement]
+    : getSelectedElements(elements, appState, {
+        includeBoundTextElement: true,
+      });
+
+/**
+ * returns prevState's selectedElementids if no change from previous, so as to
+ * retain reference identity for memoization
+ */
+export const makeNextSelectedElementIds = (
+  nextSelectedElementIds: AppState["selectedElementIds"],
+  prevState: Pick<AppState, "selectedElementIds">,
+) => {
+  if (isShallowEqual(prevState.selectedElementIds, nextSelectedElementIds)) {
+    return prevState.selectedElementIds;
+  }
+
+  return nextSelectedElementIds;
+};
+
+const _getLinearElementEditor = (
+  targetElements: readonly NonDeletedExcalidrawElement[],
+  allElements: readonly NonDeletedExcalidrawElement[],
+) => {
+  const linears = targetElements.filter(isLinearElement);
+  if (linears.length === 1) {
+    const linear = linears[0];
+    const boundElements = linear.boundElements?.map((def) => def.id) ?? [];
+    const onlySingleLinearSelected = targetElements.every(
+      (el) => el.id === linear.id || boundElements.includes(el.id),
+    );
+
+    if (onlySingleLinearSelected) {
+      return new LinearElementEditor(linear, arrayToMap(allElements));
+    }
+  }
+
+  return null;
+};
+
+export const getSelectionStateForElements = (
+  targetElements: readonly NonDeletedExcalidrawElement[],
+  allElements: readonly NonDeletedExcalidrawElement[],
+  appState: AppState,
+) => {
+  return {
+    selectedLinearElement: _getLinearElementEditor(targetElements, allElements),
+    ...selectGroupsForSelectedElements(
+      {
+        editingGroupId: appState.editingGroupId,
+        selectedElementIds: excludeElementsInFramesFromSelection(
+          targetElements,
+        ).reduce((acc: Record<ExcalidrawElement["id"], true>, element) => {
+          if (!isBoundToContainer(element)) {
+            acc[element.id] = true;
+          }
+          return acc;
+        }, {}),
+      },
+      allElements,
+      appState,
+      null,
+    ),
+  };
+};
+
+/**
+ * Returns editing or single-selected text element, if any.
+ */
+export const getActiveTextElement = (
+  selectedElements: readonly NonDeleted<ExcalidrawElement>[],
+  appState: Pick<AppState, "editingTextElement">,
+) => {
+  const activeTextElement =
+    appState.editingTextElement ||
+    (selectedElements.length === 1 &&
+      isTextElement(selectedElements[0]) &&
+      selectedElements[0]);
+
+  return activeTextElement || null;
+};

packages/element/src/showSelectedShapeActions.ts

@@ -0,0 +1,22 @@
+import type { UIAppState } from "@excalidraw/excalidraw/types";
+
+import { getSelectedElements } from "./selection";
+
+import type { NonDeletedExcalidrawElement } from "./types";
+
+export const showSelectedShapeActions = (
+  appState: UIAppState,
+  elements: readonly NonDeletedExcalidrawElement[],
+) =>
+  Boolean(
+    !appState.viewModeEnabled &&
+      appState.openDialog?.name !== "elementLinkSelector" &&
+      ((appState.activeTool.type !== "custom" &&
+        (appState.editingTextElement ||
+          (appState.activeTool.type !== "selection" &&
+            appState.activeTool.type !== "lasso" &&
+            appState.activeTool.type !== "eraser" &&
+            appState.activeTool.type !== "hand" &&
+            appState.activeTool.type !== "laser"))) ||
+        getSelectedElements(elements, appState).length),
+  );

packages/element/src/sizeHelpers.ts

@@ -0,0 +1,284 @@
+import {
+  SHIFT_LOCKING_ANGLE,
+  viewportCoordsToSceneCoords,
+} from "@excalidraw/common";
+import {
+  normalizeRadians,
+  radiansBetweenAngles,
+  radiansDifference,
+  type Radians,
+} from "@excalidraw/math";
+
+import { pointsEqual } from "@excalidraw/math";
+
+import type { AppState, Offsets, Zoom } from "@excalidraw/excalidraw/types";
+
+import { getCommonBounds, getElementBounds } from "./bounds";
+import {
+  isArrowElement,
+  isFreeDrawElement,
+  isLinearElement,
+} from "./typeChecks";
+
+import type { ElementsMap, ExcalidrawElement } from "./types";
+
+export type VerticalResizeAnchor = "top" | "bottom" | "center";
+
+/** Keeps the chosen edge or center fixed when an element's height changes. */
+export const getPositionAfterHeightChange = (
+  element: Pick<ExcalidrawElement, "x" | "y" | "height" | "angle">,
+  nextHeight: number,
+  anchor: VerticalResizeAnchor = "top",
+) => {
+  const delta = (element.height - nextHeight) / 2;
+
+  if (anchor === "center") {
+    // Rotation is about the center, so holding it is angle-independent.
+    return { x: element.x, y: element.y + delta };
+  }
+
+  const sin = Math.sin(element.angle);
+  const cos = Math.cos(element.angle);
+
+  if (anchor === "bottom") {
+    return {
+      x: element.x - delta * sin,
+      y: element.y + delta * (1 + cos),
+    };
+  }
+
+  return {
+    x: element.x + delta * sin,
+    y: element.y + delta * (1 - cos),
+  };
+};
+
+export const INVISIBLY_SMALL_ELEMENT_SIZE = 0.1;
+
+// TODO:  remove invisible elements consistently actions, so that invisible elements are not recorded by the store, exported, broadcasted or persisted
+//        - perhaps could be as part of a standalone 'cleanup' action, in addition to 'finalize'
+//        - could also be part of `_clearElements`
+export const isInvisiblySmallElement = (
+  element: ExcalidrawElement,
+): boolean => {
+  if (isLinearElement(element) || isFreeDrawElement(element)) {
+    return (
+      element.points.length < 2 ||
+      (element.points.length === 2 &&
+        isArrowElement(element) &&
+        pointsEqual(
+          element.points[0],
+          element.points[element.points.length - 1],
+          INVISIBLY_SMALL_ELEMENT_SIZE,
+        ))
+    );
+  }
+
+  return element.width === 0 && element.height === 0;
+};
+
+export const isElementInViewport = (
+  element: ExcalidrawElement,
+  width: number,
+  height: number,
+  viewTransformations: {
+    zoom: Zoom;
+    offsetLeft: number;
+    offsetTop: number;
+    scrollX: number;
+    scrollY: number;
+  },
+  elementsMap: ElementsMap,
+) => {
+  const [x1, y1, x2, y2] = getElementBounds(element, elementsMap); // scene coordinates
+  const topLeftSceneCoords = viewportCoordsToSceneCoords(
+    {
+      clientX: viewTransformations.offsetLeft,
+      clientY: viewTransformations.offsetTop,
+    },
+    viewTransformations,
+  );
+  const bottomRightSceneCoords = viewportCoordsToSceneCoords(
+    {
+      clientX: viewTransformations.offsetLeft + width,
+      clientY: viewTransformations.offsetTop + height,
+    },
+    viewTransformations,
+  );
+
+  return (
+    topLeftSceneCoords.x <= x2 &&
+    topLeftSceneCoords.y <= y2 &&
+    bottomRightSceneCoords.x >= x1 &&
+    bottomRightSceneCoords.y >= y1
+  );
+};
+
+export const isElementCompletelyInViewport = (
+  elements: ExcalidrawElement[],
+  width: number,
+  height: number,
+  viewTransformations: {
+    zoom: Zoom;
+    offsetLeft: number;
+    offsetTop: number;
+    scrollX: number;
+    scrollY: number;
+  },
+  elementsMap: ElementsMap,
+  padding?: Offsets,
+) => {
+  const [x1, y1, x2, y2] = getCommonBounds(elements, elementsMap); // scene coordinates
+  const topLeftSceneCoords = viewportCoordsToSceneCoords(
+    {
+      clientX: viewTransformations.offsetLeft + (padding?.left || 0),
+      clientY: viewTransformations.offsetTop + (padding?.top || 0),
+    },
+    viewTransformations,
+  );
+  const bottomRightSceneCoords = viewportCoordsToSceneCoords(
+    {
+      clientX: viewTransformations.offsetLeft + width - (padding?.right || 0),
+      clientY: viewTransformations.offsetTop + height - (padding?.bottom || 0),
+    },
+    viewTransformations,
+  );
+
+  return (
+    x1 >= topLeftSceneCoords.x &&
+    y1 >= topLeftSceneCoords.y &&
+    x2 <= bottomRightSceneCoords.x &&
+    y2 <= bottomRightSceneCoords.y
+  );
+};
+
+/**
+ * Makes a perfect shape or diagonal/horizontal/vertical line
+ */
+export const getPerfectElementSize = (
+  elementType: AppState["activeTool"]["type"],
+  width: number,
+  height: number,
+): { width: number; height: number } => {
+  const absWidth = Math.abs(width);
+  const absHeight = Math.abs(height);
+
+  if (
+    elementType === "line" ||
+    elementType === "arrow" ||
+    elementType === "freedraw"
+  ) {
+    const lockedAngle =
+      Math.round(Math.atan(absHeight / absWidth) / SHIFT_LOCKING_ANGLE) *
+      SHIFT_LOCKING_ANGLE;
+    if (lockedAngle === 0) {
+      height = 0;
+    } else if (lockedAngle === Math.PI / 2) {
+      width = 0;
+    } else {
+      height = absWidth * Math.tan(lockedAngle) * Math.sign(height) || height;
+    }
+  } else if (elementType !== "selection") {
+    height = absWidth * Math.sign(height);
+  }
+  return { width, height };
+};
+
+export const getLockedLinearCursorAlignSize = (
+  originX: number,
+  originY: number,
+  x: number,
+  y: number,
+  customAngle?: number,
+) => {
+  let width = x - originX;
+  let height = y - originY;
+
+  const angle = Math.atan2(height, width) as Radians;
+  let lockedAngle = (Math.round(angle / SHIFT_LOCKING_ANGLE) *
+    SHIFT_LOCKING_ANGLE) as Radians;
+
+  if (customAngle) {
+    // If custom angle is provided, we check if the angle is close to the
+    // custom angle, snap to that if close engough, otherwise snap to the
+    // higher or lower angle depending on the current angle vs custom angle.
+    const lower = (Math.floor(customAngle / SHIFT_LOCKING_ANGLE) *
+      SHIFT_LOCKING_ANGLE) as Radians;
+    if (
+      radiansBetweenAngles(
+        angle,
+        lower,
+        (lower + SHIFT_LOCKING_ANGLE) as Radians,
+      )
+    ) {
+      if (
+        radiansDifference(angle, customAngle as Radians) <
+        SHIFT_LOCKING_ANGLE / 6
+      ) {
+        lockedAngle = customAngle as Radians;
+      } else if (
+        normalizeRadians(angle) > normalizeRadians(customAngle as Radians)
+      ) {
+        lockedAngle = (lower + SHIFT_LOCKING_ANGLE) as Radians;
+      } else {
+        lockedAngle = lower;
+      }
+    }
+  }
+
+  if (lockedAngle === 0) {
+    height = 0;
+  } else if (lockedAngle === Math.PI / 2) {
+    width = 0;
+  } else {
+    // locked angle line, y = mx + b => mx - y + b = 0
+    const a1 = Math.tan(lockedAngle);
+    const b1 = -1;
+    const c1 = originY - a1 * originX;
+
+    // line through cursor, perpendicular to locked angle line
+    const a2 = -1 / a1;
+    const b2 = -1;
+    const c2 = y - a2 * x;
+
+    // intersection of the two lines above
+    const intersectX = (b1 * c2 - b2 * c1) / (a1 * b2 - a2 * b1);
+    const intersectY = (c1 * a2 - c2 * a1) / (a1 * b2 - a2 * b1);
+
+    // delta
+    width = intersectX - originX;
+    height = intersectY - originY;
+  }
+
+  return { width, height };
+};
+
+export const getNormalizedDimensions = (
+  element: Pick<ExcalidrawElement, "width" | "height" | "x" | "y">,
+): {
+  width: ExcalidrawElement["width"];
+  height: ExcalidrawElement["height"];
+  x: ExcalidrawElement["x"];
+  y: ExcalidrawElement["y"];
+} => {
+  const ret = {
+    width: element.width,
+    height: element.height,
+    x: element.x,
+    y: element.y,
+  };
+
+  if (element.width < 0) {
+    const nextWidth = Math.abs(element.width);
+    ret.width = nextWidth;
+    ret.x = element.x - nextWidth;
+  }
+
+  if (element.height < 0) {
+    const nextHeight = Math.abs(element.height);
+    ret.height = nextHeight;
+    ret.y = element.y - nextHeight;
+  }
+
+  return ret;
+};

packages/element/src/sortElements.ts

@@ -0,0 +1,119 @@
+import { arrayToMap } from "@excalidraw/common";
+
+import type { ExcalidrawElement } from "./types";
+
+const defragmentGroups = (elements: readonly ExcalidrawElement[]) => {
+  const groupIdAtLevel = (element: ExcalidrawElement, level: number) => {
+    return element.groupIds[element.groupIds.length - level - 1];
+  };
+
+  const orderLevel = (
+    levelElements: readonly ExcalidrawElement[],
+    level: number,
+  ): ExcalidrawElement[] => {
+    const buckets = new Map<string, ExcalidrawElement[]>();
+    // Slots preserve first-occurrence order: a groupId reserves its slot
+    // the first time one of its members is seen; loose elements occupy
+    // their own slot. Groups are then expanded (and recursed into) in place.
+    const slots: (ExcalidrawElement | string)[] = [];
+
+    for (const element of levelElements) {
+      const groupId = groupIdAtLevel(element, level);
+      if (groupId === undefined) {
+        slots.push(element);
+        continue;
+      }
+      let bucket = buckets.get(groupId);
+      if (!bucket) {
+        bucket = [];
+        buckets.set(groupId, bucket);
+        slots.push(groupId);
+      }
+      bucket.push(element);
+    }
+
+    return slots.flatMap((slot) =>
+      typeof slot === "string"
+        ? orderLevel(buckets.get(slot)!, level + 1)
+        : [slot],
+    );
+  };
+
+  // `groupIds` is stored innermost-first, so the outermost group is the
+  // last entry. We recurse from level 0 (outermost) inward.
+  const sortedElements = orderLevel(elements, 0);
+
+  // if there's a bug which resulted in losing some of the elements, return
+  // original instead as that's better than losing data
+  if (sortedElements.length !== elements.length) {
+    console.error("defragmentGroups: lost some elements... bailing!");
+    return elements;
+  }
+
+  return sortedElements;
+};
+
+/**
+ * In theory, when we have text elements bound to a container, they
+ * should be right after the container element in the elements array.
+ * However, this is not guaranteed due to old and potential future bugs.
+ *
+ * This function sorts containers and their bound texts together. It prefers
+ * original z-index of container (i.e. it moves bound text elements after
+ * containers).
+ */
+export const normalizeBoundElementsOrder = <T extends ExcalidrawElement>(
+  elements: readonly T[],
+) => {
+  const elementsMap = arrayToMap(elements);
+
+  const sortedElements = new Set<T>();
+
+  for (const element of elements) {
+    if (sortedElements.has(element)) {
+      continue;
+    }
+
+    if (element.boundElements?.length) {
+      sortedElements.add(element);
+      for (const boundElement of element.boundElements) {
+        const child = elementsMap.get(boundElement.id);
+        if (child && boundElement.type === "text") {
+          sortedElements.add(child);
+        }
+      }
+      continue;
+    }
+
+    // if element has a container and container lists it, skip this element
+    // as it'll be taken care of by the container
+    if (
+      element.type === "text" &&
+      element.containerId &&
+      elementsMap
+        .get(element.containerId)
+        ?.boundElements?.some((el) => el.id === element.id)
+    ) {
+      continue;
+    }
+
+    sortedElements.add(element);
+  }
+
+  // if there's a bug which resulted in losing some of the elements, return
+  // original instead as that's better than losing data
+  if (sortedElements.size !== elements.length) {
+    console.error(
+      "normalizeBoundElementsOrder: lost some elements... bailing!",
+    );
+    return elements;
+  }
+
+  return [...sortedElements];
+};
+
+export const normalizeElementOrder = (
+  elements: readonly ExcalidrawElement[],
+) => {
+  return normalizeBoundElementsOrder(defragmentGroups(elements));
+};

packages/element/src/stickyNote.ts

@@ -0,0 +1,971 @@
+import {
+  DEFAULT_ELEMENT_PROPS,
+  DEFAULT_STICKY_NOTE_BG,
+  MIN_FONT_SIZE,
+  arrayToMap,
+  STICKY_NOTE_BODY_INSET_Y,
+  STICKY_NOTE_FALLBACK_FONT_SIZE,
+  STICKY_NOTE_FOOTER,
+  STICKY_NOTE_FONT_STEP,
+  STICKY_NOTE_MAX_FONT_SIZE,
+  STICKY_NOTE_MIN_SIZE,
+  STICKY_NOTE_MIN_FONT_SIZE,
+  STICKY_NOTE_PADDING,
+  STICKY_NOTE_SHADOW_OFFSET,
+  getFontString,
+  getLineHeight,
+  isTransparent,
+  seededRandom,
+} from "@excalidraw/common";
+
+import { clamp } from "@excalidraw/math";
+
+import { updateBoundElements } from "./binding";
+import { newElementWith } from "./mutateElement";
+import { getPositionAfterHeightChange } from "./sizeHelpers";
+import { computeBoundTextPosition, getBoundTextElement } from "./textElement";
+import { measureText } from "./textMeasurements";
+import { wrapText } from "./textWrapping";
+import { isStickyNoteElement, isTextElement } from "./typeChecks";
+
+import type { Scene } from "./Scene";
+import type { VerticalResizeAnchor } from "./sizeHelpers";
+import type { TransformHandleDirection } from "./transformHandles";
+import type {
+  ElementsMap,
+  ExcalidrawElement,
+  ExcalidrawStickyNoteElement,
+  ExcalidrawTextElement,
+  ExcalidrawTextElementWithContainer,
+  NonDeletedExcalidrawElement,
+} from "./types";
+
+export type StickyNoteRenderPoint = {
+  x: number;
+  y: number;
+};
+
+export type StickyNotePathCommand =
+  | {
+      type: "move";
+      point: StickyNoteRenderPoint;
+    }
+  | {
+      type: "line";
+      point: StickyNoteRenderPoint;
+    }
+  | {
+      type: "quadratic";
+      control: StickyNoteRenderPoint;
+      point: StickyNoteRenderPoint;
+    };
+
+const STICKY_NOTE_RENDER_ROUGHNESS = [0, 1.5, 8] as const;
+const STICKY_NOTE_CORNER_RADIUS_RATIO = 0.04;
+const STICKY_NOTE_MAX_CORNER_RADIUS = 16;
+
+export const normalizeStickyNoteStrokeColor = (
+  strokeColor: string | null | undefined,
+) => {
+  return !strokeColor || isTransparent(strokeColor)
+    ? DEFAULT_ELEMENT_PROPS.strokeColor
+    : strokeColor;
+};
+
+export const normalizeStickyNoteBackgroundColor = (
+  backgroundColor: string | null | undefined,
+) => {
+  return !backgroundColor || isTransparent(backgroundColor)
+    ? DEFAULT_STICKY_NOTE_BG
+    : backgroundColor;
+};
+
+/**
+ * The update that applies a picked color to an element under the sticky
+ * note policy: a note is always filled and its label — the visible text,
+ * which the note's own `strokeColor` seeds — never goes transparent. Every
+ * color surface (actions, both eyedroppers, paste styles, bind) routes
+ * through this instead of re-deriving the rule.
+ */
+/**
+ * The element a color pick on `element` lands on. A note's label has no fill
+ * of its own, so a background pick on the label — the styles panel while
+ * editing it — goes to the note; everything else colors itself.
+ */
+export const getColorTargetElement = (
+  element: ExcalidrawElement,
+  property: "strokeColor" | "backgroundColor",
+  elementsMap: ElementsMap,
+): ExcalidrawElement => {
+  if (
+    property === "backgroundColor" &&
+    isTextElement(element) &&
+    isStickyNoteBoundText(element, elementsMap)
+  ) {
+    return elementsMap.get(element.containerId!) ?? element;
+  }
+  return element;
+};
+
+export const getColorUpdate = (
+  element: ExcalidrawElement,
+  property: "strokeColor" | "backgroundColor",
+  color: string,
+  elementsMap: ElementsMap,
+): { strokeColor: string } | { backgroundColor: string } => {
+  if (isStickyNoteElement(element)) {
+    return property === "backgroundColor"
+      ? { backgroundColor: normalizeStickyNoteBackgroundColor(color) }
+      : { strokeColor: normalizeStickyNoteStrokeColor(color) };
+  }
+  if (
+    property === "strokeColor" &&
+    isTextElement(element) &&
+    isStickyNoteBoundText(element, elementsMap)
+  ) {
+    const container = elementsMap.get(element.containerId!);
+    return {
+      strokeColor: isTransparent(color)
+        ? normalizeStickyNoteStrokeColor(container?.strokeColor)
+        : color,
+    };
+  }
+  return property === "backgroundColor"
+    ? { backgroundColor: color }
+    : { strokeColor: color };
+};
+
+/**
+ * A note's ink is one color: the container's `strokeColor` — the seed for a
+ * new label and what the creation-date footer paints with — and its label's.
+ * Run after a property write to copy the side that changed onto the other;
+ * when both changed, or neither (data that drifted), the label wins: it is
+ * the text the user styled. A transparent label always takes the note's
+ * color. Returns the same array when nothing needs to change.
+ */
+export const syncStickyNoteInk = <T extends ExcalidrawElement>(
+  elements: readonly T[],
+  prevElementsMap: ElementsMap,
+): readonly T[] => {
+  const elementsMap = arrayToMap(elements);
+  const inkById = new Map<string, string>();
+  for (const container of elements) {
+    if (!isStickyNoteElement(container) || container.isDeleted) {
+      continue;
+    }
+    const label = getBoundTextElement(container, elementsMap);
+    if (!label || label.strokeColor === container.strokeColor) {
+      continue;
+    }
+    const containerChanged =
+      prevElementsMap.get(container.id)?.strokeColor !== container.strokeColor;
+    const labelChanged =
+      prevElementsMap.get(label.id)?.strokeColor !== label.strokeColor;
+    if (
+      isTransparent(label.strokeColor) ||
+      (containerChanged && !labelChanged)
+    ) {
+      inkById.set(
+        label.id,
+        normalizeStickyNoteStrokeColor(container.strokeColor),
+      );
+    } else {
+      inkById.set(
+        container.id,
+        normalizeStickyNoteStrokeColor(label.strokeColor),
+      );
+    }
+  }
+  if (!inkById.size) {
+    return elements;
+  }
+  return elements.map((element) => {
+    const strokeColor = inkById.get(element.id);
+    return strokeColor === undefined
+      ? element
+      : (newElementWith(element as ExcalidrawElement, { strokeColor }) as T);
+  });
+};
+
+const jitter = (random: () => number, amount: number) =>
+  (random() * 2 - 1) * amount;
+
+const pointAtDistance = (
+  from: StickyNoteRenderPoint,
+  to: StickyNoteRenderPoint,
+  distance: number,
+) => {
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const length = Math.hypot(dx, dy);
+
+  if (!length) {
+    return from;
+  }
+
+  const ratio = Math.min(distance / length, 1);
+  return {
+    x: from.x + dx * ratio,
+    y: from.y + dy * ratio,
+  };
+};
+
+export const getStickyNoteCornerRadius = (
+  element: ExcalidrawStickyNoteElement,
+) => {
+  if (!element.roundness) {
+    return 0;
+  }
+
+  return Math.min(
+    Math.min(element.width, element.height) * STICKY_NOTE_CORNER_RADIUS_RATIO,
+    STICKY_NOTE_MAX_CORNER_RADIUS,
+  );
+};
+
+export const getStickyNoteRenderPoints = (
+  element: ExcalidrawStickyNoteElement,
+  {
+    offsetX = 0,
+    offsetY = 0,
+    seedOffset = 0,
+  }: {
+    offsetX?: number;
+    offsetY?: number;
+    seedOffset?: number;
+  } = {},
+): StickyNoteRenderPoint[] => {
+  const roughness = Math.max(0, Math.min(2, Math.round(element.roughness)));
+  const amount = Math.min(
+    STICKY_NOTE_RENDER_ROUGHNESS[roughness],
+    Math.min(element.width, element.height) * 0.012,
+  );
+
+  if (!amount) {
+    return [
+      { x: offsetX, y: offsetY },
+      { x: offsetX + element.width, y: offsetY },
+      { x: offsetX + element.width, y: offsetY + element.height },
+      { x: offsetX, y: offsetY + element.height },
+    ];
+  }
+
+  const random = seededRandom(element.seed + seedOffset);
+
+  return [
+    {
+      x: offsetX + jitter(random, amount),
+      y: offsetY + jitter(random, amount),
+    },
+    {
+      x: offsetX + element.width + jitter(random, amount),
+      y: offsetY + jitter(random, amount),
+    },
+    {
+      x: offsetX + element.width + jitter(random, amount),
+      y: offsetY + element.height + jitter(random, amount),
+    },
+    {
+      x: offsetX + jitter(random, amount),
+      y: offsetY + element.height + jitter(random, amount),
+    },
+  ];
+};
+
+export const getStickyNotePathCommands = (
+  element: ExcalidrawStickyNoteElement,
+  { shadow = false }: { shadow?: boolean } = {},
+): StickyNotePathCommand[] => {
+  const points = getStickyNoteRenderPoints(
+    element,
+    shadow
+      ? {
+          offsetX: STICKY_NOTE_SHADOW_OFFSET,
+          offsetY: STICKY_NOTE_SHADOW_OFFSET,
+          seedOffset: 1,
+        }
+      : undefined,
+  );
+  const radius = getStickyNoteCornerRadius(element);
+  // The note's seed keeps the same corner for the paper and shadow through
+  // redraws and resizes.
+  const liftedCorner =
+    element.roughness === 2
+      ? Math.floor(seededRandom(element.seed)() * points.length)
+      : -1;
+
+  if (!radius && liftedCorner === -1) {
+    return [
+      { type: "move", point: points[0] },
+      ...points.slice(1).map(
+        (point): StickyNotePathCommand => ({
+          type: "line",
+          point,
+        }),
+      ),
+    ];
+  }
+
+  const corners = points.map((point, index): StickyNotePathCommand[] => {
+    const prev = points[(index + points.length - 1) % points.length];
+    const next = points[(index + 1) % points.length];
+    const cornerRadius = Math.min(
+      radius,
+      Math.hypot(point.x - prev.x, point.y - prev.y) / 2,
+      Math.hypot(point.x - next.x, point.y - next.y) / 2,
+    );
+
+    if (index === liftedCorner) {
+      const size = Math.min(element.width, element.height);
+      const reach = Math.min(size * 0.18, 40);
+      // The shadow follows the paper inward at half the bend, keeping its
+      // usual down-right offset from the light at the top left.
+      const lift = Math.min(size * 0.02, 5) * (shadow ? 0.5 : 1);
+      // The bend joins the straight edges before the corner, keeping it local.
+      const tip = {
+        x: point.x + (index === 1 || index === 2 ? -lift : lift),
+        y: point.y + (index >= 2 ? -lift : lift),
+      };
+      const start = pointAtDistance(point, prev, reach);
+      const end = pointAtDistance(point, next, reach);
+      return [
+        { type: "line", point: start },
+        {
+          type: "quadratic",
+          control: pointAtDistance(point, prev, reach / 2),
+          point: pointAtDistance(tip, start, cornerRadius),
+        },
+        {
+          type: "quadratic",
+          control: tip,
+          point: pointAtDistance(tip, end, cornerRadius),
+        },
+        {
+          type: "quadratic",
+          control: pointAtDistance(point, next, reach / 2),
+          point: end,
+        },
+      ];
+    }
+
+    return [
+      { type: "line", point: pointAtDistance(point, prev, cornerRadius) },
+      {
+        type: "quadratic",
+        control: point,
+        point: pointAtDistance(point, next, cornerRadius),
+      },
+    ];
+  });
+
+  const commands: StickyNotePathCommand[] = [
+    { type: "move", point: corners[0][corners[0].length - 1].point },
+  ];
+
+  for (let index = 1; index <= corners.length; index++) {
+    commands.push(...corners[index % corners.length]);
+  }
+
+  return commands;
+};
+
+// -----------------------------------------------------------------------------
+// font size — `baseFontSize` is the size the user picked, `fontSize` the fitted one
+// -----------------------------------------------------------------------------
+
+// clamping the ceiling: the fit steps down from it in `STICKY_NOTE_FONT_STEP`
+// increments, and for values >= ~2^56 (1e20 - 2 === 1e20) that would never
+// progress and hang the editor
+export const normalizeStickyNoteFontSize = (fontSize: number) => {
+  if (!Number.isFinite(fontSize)) {
+    return STICKY_NOTE_FALLBACK_FONT_SIZE;
+  }
+  return Math.min(STICKY_NOTE_MAX_FONT_SIZE, Math.max(MIN_FONT_SIZE, fontSize));
+};
+
+/** whether the text element is the label of a sticky note */
+export const isStickyNoteBoundText = (
+  textElement: ExcalidrawTextElement,
+  elementsMap: ElementsMap,
+) => {
+  return (
+    !!textElement.containerId &&
+    isStickyNoteElement(elementsMap.get(textElement.containerId))
+  );
+};
+
+/**
+ * The font size the user picked: the ceiling the auto-fit shrinks from for a
+ * sticky note label, plain `fontSize` for any other text.
+ *
+ * Container-aware on purpose — generic binding repair (duplication, history)
+ * rewrites `containerId` without touching the ceiling, so a numeric
+ * `baseFontSize` alone does not prove the text is still sticky-bound.
+ */
+export const getBaseFontSize = (
+  textElement: ExcalidrawTextElement,
+  elementsMap: ElementsMap,
+) => {
+  return isStickyNoteBoundText(textElement, elementsMap)
+    ? textElement.baseFontSize ?? textElement.fontSize
+    : textElement.fontSize;
+};
+
+/** the update that applies a user-picked font size (see `getBaseFontSize`) */
+export const getBaseFontSizeUpdate = (
+  textElement: ExcalidrawTextElement,
+  fontSize: number,
+  elementsMap: ElementsMap,
+): { fontSize: number } | { baseFontSize: number } => {
+  return isStickyNoteBoundText(textElement, elementsMap)
+    ? { baseFontSize: normalizeStickyNoteFontSize(fontSize) }
+    : { fontSize };
+};
+
+const MONTHS = [
+  "Jan",
+  "Feb",
+  "Mar",
+  "Apr",
+  "May",
+  "Jun",
+  "Jul",
+  "Aug",
+  "Sep",
+  "Oct",
+  "Nov",
+  "Dec",
+];
+
+/**
+ * The creation-date label: absolute, so painting needs no clock and exports
+ * don't go stale, and short ("7 Sep") while the year is the current one.
+ * `null` when the note has no usable timestamp (files restored without one).
+ * Fixed English in the viewer's local time zone — the element package has no
+ * locale, and the footer is chosen by width bucket rather than measured.
+ */
+export const getStickyNoteDateLabel = (
+  created: ExcalidrawStickyNoteElement["created"],
+  { short = false, now = Date.now() }: { short?: boolean; now?: number } = {},
+): string | null => {
+  if (created === null || !Number.isFinite(created)) {
+    return null;
+  }
+  const date = new Date(created);
+  if (Number.isNaN(date.getTime())) {
+    return null;
+  }
+  const label = `${date.getDate()} ${MONTHS[date.getMonth()]}`;
+  const year = date.getFullYear();
+  return short || year === new Date(now).getFullYear()
+    ? label
+    : `${label} ${year}`;
+};
+
+/**
+ * What the footer paints and where, in note-local coordinates — shared by the
+ * canvas and SVG renderers, which take the font and opacity from
+ * `STICKY_NOTE_FOOTER`. `null` for the 0×0 creation draft and anything under
+ * the data floor, where the band would overlap the top padding.
+ */
+export const getStickyNoteFooter = (
+  element: Pick<ExcalidrawStickyNoteElement, "created" | "width" | "height">,
+  now = Date.now(),
+) => {
+  if (
+    element.width < STICKY_NOTE_MIN_SIZE ||
+    element.height < STICKY_NOTE_MIN_SIZE
+  ) {
+    return null;
+  }
+  const text = getStickyNoteDateLabel(element.created, {
+    short:
+      element.width - STICKY_NOTE_PADDING * 2 <
+      STICKY_NOTE_FOOTER.minBodyWidthForYear,
+    now,
+  });
+  if (!text) {
+    return null;
+  }
+  return {
+    text,
+    x: element.width - STICKY_NOTE_PADDING,
+    y: element.height - STICKY_NOTE_FOOTER.baselineFromBottom,
+  };
+};
+
+/**
+ * The smallest note the UI lets a user create or resize to: one line at the
+ * label's font ceiling plus padding (and, vertically, the footer), never below
+ * `STICKY_NOTE_MIN_SIZE`. Without the font term a fresh note would grow on
+ * the very first keystroke. Data-level passes (restore, action post-passes)
+ * only enforce the constant floor — the layout grows a note as needed.
+ */
+export const getStickyNoteMinSize = ({
+  fontSize,
+  fontFamily,
+}: Pick<ExcalidrawTextElement, "fontSize" | "fontFamily">) => {
+  const lineHeightPx = Math.ceil(
+    normalizeStickyNoteFontSize(fontSize) * getLineHeight(fontFamily),
+  );
+  return {
+    width: Math.max(
+      STICKY_NOTE_MIN_SIZE,
+      lineHeightPx + STICKY_NOTE_PADDING * 2,
+    ),
+    height: Math.max(
+      STICKY_NOTE_MIN_SIZE,
+      lineHeightPx + STICKY_NOTE_BODY_INSET_Y,
+    ),
+  };
+};
+
+// -----------------------------------------------------------------------------
+// layout — one pure calculation, two ways of applying it
+// -----------------------------------------------------------------------------
+
+export type StickyNoteLayoutAnchor = VerticalResizeAnchor;
+
+export type StickyNoteLayoutOpts = {
+  /** unwrapped text to lay out; defaults to the label's `originalText` */
+  originalText?: string;
+  /**
+   * absolute base-height intent — the gesture-start value to preserve, or the
+   * height a resize asked for. Omitted = keep the note's live `baseHeight`
+   * (typing, style changes, restore).
+   */
+  baseHeight?: number;
+  /**
+   * absolute font-ceiling intent (a proportional resize passes
+   * `gesture-start ceiling × scale`). Omitted = keep the label's live ceiling.
+   * Never a multiplier on the live value — that compounds across pointer-moves.
+   */
+  baseFontSize?: number;
+  /** the edge that stays put when the content correction changes the height */
+  anchor?: StickyNoteLayoutAnchor;
+};
+
+export type StickyNoteLayout = {
+  container: Pick<
+    ExcalidrawStickyNoteElement,
+    "x" | "y" | "width" | "height" | "baseHeight"
+  >;
+  text: Pick<
+    ExcalidrawTextElement,
+    | "text"
+    | "fontSize"
+    | "baseFontSize"
+    | "width"
+    | "height"
+    | "x"
+    | "y"
+    | "angle"
+  > | null;
+};
+
+type FontFit = {
+  text: string;
+  fontSize: number;
+  width: number;
+  height: number;
+};
+
+// `computeBoundTextPosition` only consults the map for arrow containers
+const NO_ELEMENTS: ElementsMap = new Map();
+
+const getStickyNoteBaseWidth = (container: ExcalidrawStickyNoteElement) => {
+  return Math.max(container.width, STICKY_NOTE_MIN_SIZE);
+};
+
+/**
+ * Largest font size on the grid `{ceiling − k·STEP} ∪ {min}` whose wrapped
+ * text fits the note; `min` when nothing fits (the note then grows). The grid
+ * is anchored at the ceiling so the result never depends on earlier edits.
+ * Warm-started from the previously fitted size: the common keystroke costs one
+ * or two wrap+measure passes, a cold search at most log2(steps) + 2.
+ */
+const fitStickyNoteFont = (
+  fit: (fontSize: number) => FontFit,
+  {
+    baseFontSize,
+    fontSizeMin,
+    maxWidth,
+    maxHeight,
+    warmStart,
+  }: {
+    baseFontSize: number;
+    fontSizeMin: number;
+    maxWidth: number;
+    maxHeight: number;
+    warmStart: number;
+  },
+): FontFit => {
+  const steps = Math.max(
+    0,
+    Math.ceil((baseFontSize - fontSizeMin) / STICKY_NOTE_FONT_STEP),
+  );
+  const sizeAt = (index: number) =>
+    index >= steps ? fontSizeMin : baseFontSize - index * STICKY_NOTE_FONT_STEP;
+
+  const fits = new Map<number, FontFit>();
+  const at = (index: number) => {
+    let result = fits.get(index);
+    if (!result) {
+      result = fit(sizeAt(index));
+      fits.set(index, result);
+    }
+    return result;
+  };
+  const doesFit = (index: number) => {
+    const result = at(index);
+    return result.width <= maxWidth && result.height <= maxHeight;
+  };
+
+  if (steps === 0) {
+    return at(0);
+  }
+
+  // the previous fitted size, snapped onto the grid and clamped into the
+  // current interval (a lowered ceiling must not keep the old larger size)
+  const warm = clamp(
+    Math.round((baseFontSize - warmStart) / STICKY_NOTE_FONT_STEP),
+    0,
+    steps,
+  );
+
+  // binary search for the smallest index (largest font) that fits
+  let lo: number;
+  let hi: number;
+  if (doesFit(warm)) {
+    if (warm === 0 || !doesFit(warm - 1)) {
+      return at(warm);
+    }
+    lo = 0;
+    hi = warm - 1;
+  } else {
+    if (warm === steps) {
+      return at(steps);
+    }
+    lo = warm + 1;
+    hi = steps;
+  }
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (doesFit(mid)) {
+      hi = mid;
+    } else {
+      lo = mid + 1;
+    }
+  }
+  return at(lo);
+};
+
+/**
+ * The single source of truth for a sticky note's geometry: wraps the label at
+ * the note's width, fits the font under the ceiling, grows the note past
+ * `baseHeight` only when the text still overflows at the minimum size, and
+ * positions the label inside. Pure — returns the updates for both elements.
+ */
+export const getStickyNoteLayout = (
+  container: ExcalidrawStickyNoteElement,
+  textElement: ExcalidrawTextElement | null,
+  opts: StickyNoteLayoutOpts = {},
+): StickyNoteLayout => {
+  const baseWidth = getStickyNoteBaseWidth(container);
+  const baseHeight = Math.max(
+    opts.baseHeight ?? (container.baseHeight || container.height),
+    STICKY_NOTE_MIN_SIZE,
+  );
+  const anchor = opts.anchor ?? "top";
+
+  if (!textElement) {
+    // an empty note sits at its base height
+    return {
+      container: {
+        ...getPositionAfterHeightChange(container, baseHeight, anchor),
+        width: baseWidth,
+        height: baseHeight,
+        baseHeight,
+      },
+      text: null,
+    };
+  }
+
+  const originalText = opts.originalText ?? textElement.originalText;
+  const baseFontSize = normalizeStickyNoteFontSize(
+    opts.baseFontSize ?? textElement.baseFontSize ?? textElement.fontSize,
+  );
+  const fontSizeMin = Math.min(STICKY_NOTE_MIN_FONT_SIZE, baseFontSize);
+  const maxWidth = Math.max(baseWidth - STICKY_NOTE_PADDING * 2, 1);
+  const maxHeight = Math.max(baseHeight - STICKY_NOTE_BODY_INSET_Y, 0);
+  const { fontFamily, lineHeight } = textElement;
+
+  const fit = (fontSize: number): FontFit => {
+    const font = getFontString({ fontFamily, fontSize });
+    const text = wrapText(originalText, font, maxWidth);
+    return { text, fontSize, ...measureText(text, font, lineHeight) };
+  };
+
+  const isBlank = !originalText.trim();
+  const fitted: FontFit = isBlank
+    ? {
+        text: "",
+        fontSize: baseFontSize,
+        ...measureText(
+          "",
+          getFontString({ fontFamily, fontSize: baseFontSize }),
+          lineHeight,
+        ),
+      }
+    : fitStickyNoteFont(fit, {
+        baseFontSize,
+        fontSizeMin,
+        maxWidth,
+        maxHeight,
+        warmStart: textElement.fontSize,
+      });
+
+  const height = isBlank
+    ? baseHeight
+    : Math.max(baseHeight, fitted.height + STICKY_NOTE_BODY_INSET_Y);
+  const nextContainer = {
+    ...getPositionAfterHeightChange(container, height, anchor),
+    width: baseWidth,
+    height,
+    baseHeight,
+  };
+  const { x, y } = computeBoundTextPosition(
+    { ...container, ...nextContainer },
+    {
+      ...textElement,
+      text: fitted.text,
+      fontSize: fitted.fontSize,
+      width: fitted.width,
+      height: fitted.height,
+    } as ExcalidrawTextElementWithContainer,
+    NO_ELEMENTS,
+  );
+
+  return {
+    container: nextContainer,
+    text: {
+      text: fitted.text,
+      fontSize: fitted.fontSize,
+      baseFontSize,
+      width: fitted.width,
+      height: fitted.height,
+      x,
+      y,
+      angle: container.angle,
+    },
+  };
+};
+
+/**
+ * Resize intents for a sticky note — the §3.3 matrix of the plan. Every value
+ * is absolute and derived from the gesture-start snapshot on each pointer-move,
+ * so releasing Shift (or Alt) mid-gesture restores the original base height
+ * and ceiling instead of keeping values a previous move scaled.
+ *
+ * - width-only gestures (free E/W, Stats W) preserve the base height
+ * - height-changing gestures use the requested height as the new base
+ * - proportional gestures (Shift on any handle, aspect-locked multi-select,
+ *   Stats group) additionally scale the font ceiling with the note
+ * - flips preserve everything
+ * - the content correction anchors at the edge the gesture holds still
+ */
+export const getStickyNoteResizeIntent = (
+  /** the note with the requested geometry already applied */
+  container: ExcalidrawStickyNoteElement,
+  originalElementsMap: ElementsMap,
+  handleDirection: TransformHandleDirection,
+  {
+    proportional,
+    fromCenter,
+    flip = false,
+  }: { proportional: boolean; fromCenter: boolean; flip?: boolean },
+): Pick<StickyNoteLayoutOpts, "baseHeight" | "baseFontSize" | "anchor"> => {
+  const origContainer = originalElementsMap.get(container.id);
+  const origSticky = isStickyNoteElement(origContainer)
+    ? origContainer
+    : container;
+  const origText = getBoundTextElement(origSticky, originalElementsMap);
+  const ceiling = origText
+    ? origText.baseFontSize ?? origText.fontSize
+    : undefined;
+
+  if (flip) {
+    return { baseHeight: origSticky.baseHeight, baseFontSize: ceiling };
+  }
+
+  const changesHeight =
+    proportional ||
+    handleDirection.includes("n") ||
+    handleDirection.includes("s");
+  const scale =
+    proportional && origSticky.width ? container.width / origSticky.width : 1;
+  const isSideHandle = handleDirection.length === 1;
+
+  return {
+    baseHeight: changesHeight ? container.height : origSticky.baseHeight,
+    baseFontSize: ceiling === undefined ? undefined : ceiling * scale,
+    anchor: fromCenter
+      ? "center"
+      : handleDirection.includes("n")
+      ? "bottom"
+      : proportional &&
+        isSideHandle &&
+        (handleDirection === "e" || handleDirection === "w")
+      ? // Shift+E/W holds the opposite side's midpoint, i.e. the vertical center
+        "center"
+      : "top",
+  };
+};
+
+/**
+ * Applies `getStickyNoteLayout` to a live scene, then runs the bound-arrow
+ * pass unless the caller already owns one (`bindings: false`) or needs to
+ * forward its context (`bindings: { simultaneouslyUpdated }` — arrows resized
+ * in the same gesture must not be moved by the pass, `updateBoundElements`
+ * skips them only when told).
+ */
+export const updateStickyNoteLayout = (
+  container: ExcalidrawStickyNoteElement,
+  scene: Scene,
+  {
+    text,
+    bindings,
+    ...layoutOpts
+  }: StickyNoteLayoutOpts & {
+    /** the label to lay out when it is an uncommitted clone (font actions clone before install) */
+    text?: ExcalidrawTextElement | null;
+    bindings?:
+      | { simultaneouslyUpdated?: readonly NonDeletedExcalidrawElement[] }
+      | false;
+  } = {},
+): StickyNoteLayout => {
+  const elementsMap = scene.getNonDeletedElementsMap();
+  const textElement =
+    text === undefined ? getBoundTextElement(container, elementsMap) : text;
+  const layout = getStickyNoteLayout(container, textElement, layoutOpts);
+
+  scene.mutateElement(container, layout.container);
+  if (textElement && layout.text) {
+    scene.mutateElement(textElement, layout.text);
+  }
+  if (bindings !== false && !container.isDeleted) {
+    updateBoundElements(
+      container as NonDeletedExcalidrawElement,
+      scene,
+      bindings || undefined,
+    );
+  }
+
+  return layout;
+};
+
+const STICKY_NOTE_LAYOUT_INPUTS = {
+  container: ["x", "y", "width", "baseHeight", "angle"],
+  text: [
+    "originalText",
+    "baseFontSize",
+    "fontFamily",
+    "lineHeight",
+    "textAlign",
+    "verticalAlign",
+  ],
+} as const;
+
+const hasStickyNoteLayoutInputChanged = (
+  container: ExcalidrawStickyNoteElement,
+  textElement: ExcalidrawTextElement | null,
+  prevElementsMap: ElementsMap,
+) => {
+  const prevContainer = prevElementsMap.get(container.id);
+  const prevText = textElement ? prevElementsMap.get(textElement.id) : null;
+  if (
+    !prevContainer ||
+    (textElement && !prevText) ||
+    (!textElement &&
+      prevContainer.boundElements?.some(({ type }) => type === "text"))
+  ) {
+    return true;
+  }
+  return (
+    STICKY_NOTE_LAYOUT_INPUTS.container.some(
+      (key) => (prevContainer as any)[key] !== container[key],
+    ) ||
+    (!!textElement &&
+      STICKY_NOTE_LAYOUT_INPUTS.text.some(
+        (key) => (prevText as any)[key] !== textElement[key],
+      ))
+  );
+};
+
+/**
+ * Applies `getStickyNoteLayout` inside an immutable elements array (property
+ * actions, paste styles, restore): the notes among `affectedIds` — or the
+ * notes whose labels are — get both halves merged into their clones. Elements
+ * that need no change keep their identity and version; when `prevElementsMap`
+ * is given, notes whose layout inputs did not change skip the fit entirely.
+ * Bound arrows are the caller's job once the result is installed.
+ */
+export const relayoutStickyNotes = <T extends ExcalidrawElement>(
+  elements: readonly T[],
+  affectedIds: ReadonlySet<ExcalidrawElement["id"]>,
+  opts?: { prevElementsMap?: ElementsMap },
+): readonly T[] => {
+  if (!affectedIds.size) {
+    return elements;
+  }
+  const elementsMap = arrayToMap(elements);
+  const containerIds = new Set<ExcalidrawElement["id"]>();
+  for (const id of affectedIds) {
+    const element = elementsMap.get(id);
+    if (!element || element.isDeleted) {
+      continue;
+    }
+    if (isStickyNoteElement(element)) {
+      containerIds.add(element.id);
+    } else if (isTextElement(element) && element.containerId) {
+      const container = elementsMap.get(element.containerId);
+      if (container && !container.isDeleted && isStickyNoteElement(container)) {
+        containerIds.add(container.id);
+      }
+    }
+  }
+  if (!containerIds.size) {
+    return elements;
+  }
+
+  const replacements = new Map<ExcalidrawElement["id"], T>();
+  for (const id of containerIds) {
+    const container = elementsMap.get(id) as ExcalidrawStickyNoteElement;
+    const textElement = getBoundTextElement(container, elementsMap);
+    if (
+      opts?.prevElementsMap &&
+      !hasStickyNoteLayoutInputChanged(
+        container,
+        textElement,
+        opts.prevElementsMap,
+      )
+    ) {
+      continue;
+    }
+    const layout = getStickyNoteLayout(container, textElement);
+    const nextContainer = newElementWith(container, layout.container);
+    if (nextContainer !== container) {
+      replacements.set(id, nextContainer as unknown as T);
+    }
+    if (textElement && layout.text) {
+      const nextText = newElementWith(textElement, layout.text);
+      if (nextText !== textElement) {
+        replacements.set(textElement.id, nextText as unknown as T);
+      }
+    }
+  }
+  if (!replacements.size) {
+    return elements;
+  }
+  return elements.map((element) => replacements.get(element.id) ?? element);
+};

packages/element/src/textElement.ts

@@ -0,0 +1,588 @@
+import {
+  ARROW_LABEL_FONT_SIZE_TO_MIN_WIDTH_RATIO,
+  ARROW_LABEL_WIDTH_FRACTION,
+  BOUND_TEXT_PADDING,
+  DEFAULT_FONT_SIZE,
+  STICKY_NOTE_BODY_INSET_Y,
+  STICKY_NOTE_PADDING,
+  TEXT_ALIGN,
+  VERTICAL_ALIGN,
+  getFontString,
+  isProdEnv,
+  invariant,
+} from "@excalidraw/common";
+
+import { pointFrom, pointRotateRads, type Radians } from "@excalidraw/math";
+
+import type { ExtractSetType } from "@excalidraw/common/utility-types";
+
+import {
+  resetOriginalContainerCache,
+  updateOriginalContainerCache,
+} from "./containerCache";
+import { LinearElementEditor } from "./linearElementEditor";
+import { getPositionAfterHeightChange } from "./sizeHelpers";
+
+import { updateStickyNoteLayout } from "./stickyNote";
+import { measureText } from "./textMeasurements";
+import { wrapText } from "./textWrapping";
+import {
+  isBoundToContainer,
+  isArrowElement,
+  isStickyNoteElement,
+  isTextElement,
+} from "./typeChecks";
+
+import { isNonDeletedElement } from ".";
+
+import type { Scene } from "./Scene";
+
+import type { MaybeTransformHandleType } from "./transformHandles";
+import type {
+  ElementsMap,
+  ExcalidrawElement,
+  ExcalidrawElementType,
+  ExcalidrawTextContainer,
+  ExcalidrawTextElement,
+  ExcalidrawTextElementWithContainer,
+  NonDeleted,
+} from "./types";
+
+export const redrawTextBoundingBox = (
+  textElement: ExcalidrawTextElement,
+  container: ExcalidrawElement | null,
+  scene: Scene,
+) => {
+  const elementsMap = scene.getNonDeletedElementsMap();
+
+  if (container && isStickyNoteElement(container)) {
+    // the sticky fit owns both halves (label + note geometry). `textElement`
+    // may be an uncommitted clone (font actions clone before install), so it
+    // is passed explicitly instead of looked up in the scene
+    updateStickyNoteLayout(container, scene, { text: textElement });
+    return;
+  }
+
+  let maxWidth = undefined;
+
+  if (!isProdEnv()) {
+    invariant(
+      !container || !isArrowElement(container) || textElement.angle === 0,
+      "text element angle must be 0 if bound to arrow container",
+    );
+  }
+
+  const boundTextUpdates = {
+    x: textElement.x,
+    y: textElement.y,
+    text: textElement.text,
+    width: textElement.width,
+    height: textElement.height,
+    angle: (container
+      ? isArrowElement(container)
+        ? 0
+        : container.angle
+      : textElement.angle) as Radians,
+  };
+
+  boundTextUpdates.text = textElement.text;
+
+  if (container || !textElement.autoResize) {
+    maxWidth = container
+      ? getBoundTextMaxWidth(container, textElement)
+      : textElement.width;
+    boundTextUpdates.text = wrapText(
+      textElement.originalText,
+      getFontString(textElement),
+      maxWidth,
+    );
+  }
+
+  const metrics = measureText(
+    boundTextUpdates.text,
+    getFontString(textElement),
+    textElement.lineHeight,
+  );
+
+  // Note: only update width for unwrapped text and bound texts (which always have autoResize set to true)
+  if (textElement.autoResize) {
+    boundTextUpdates.width = metrics.width;
+  }
+  boundTextUpdates.height = metrics.height;
+
+  if (container) {
+    const maxContainerHeight = getBoundTextMaxHeight(
+      container,
+      textElement as ExcalidrawTextElementWithContainer,
+    );
+    const maxContainerWidth = getBoundTextMaxWidth(container, textElement);
+
+    if (!isArrowElement(container) && metrics.height > maxContainerHeight) {
+      const nextHeight = computeContainerDimensionForBoundText(
+        metrics.height,
+        container.type,
+      );
+      scene.mutateElement(container, { height: nextHeight });
+      updateOriginalContainerCache(container.id, nextHeight);
+    }
+
+    if (metrics.width > maxContainerWidth) {
+      const nextWidth = computeContainerDimensionForBoundText(
+        metrics.width,
+        container.type,
+      );
+      scene.mutateElement(container, { width: nextWidth });
+    }
+
+    const updatedTextElement = {
+      ...textElement,
+      ...boundTextUpdates,
+    } as ExcalidrawTextElementWithContainer;
+
+    const { x, y } = computeBoundTextPosition(
+      container,
+      updatedTextElement,
+      elementsMap,
+    );
+
+    boundTextUpdates.x = x;
+    boundTextUpdates.y = y;
+  }
+
+  scene.mutateElement(textElement, boundTextUpdates);
+};
+
+export const handleBindTextResize = (
+  container: ExcalidrawElement,
+  scene: Scene,
+  transformHandleType: MaybeTransformHandleType,
+  shouldMaintainAspectRatio = false,
+  shouldResizeFromCenter = false,
+  flipByY = false,
+) => {
+  if (isStickyNoteElement(container)) {
+    // resize callers pass their intents to `updateStickyNoteLayout` directly
+    // and own the bound-arrow pass; this is the fallback for generic callers
+    updateStickyNoteLayout(container, scene, { bindings: false });
+    return;
+  }
+  const elementsMap = scene.getNonDeletedElementsMap();
+  const boundTextElementId = getBoundTextElementId(container);
+  if (!boundTextElementId) {
+    return;
+  }
+  resetOriginalContainerCache(container.id);
+  const textElement = getBoundTextElement(container, elementsMap);
+  if (textElement && textElement.text) {
+    if (!container) {
+      return;
+    }
+
+    let text = textElement.text;
+    let nextHeight = textElement.height;
+    let nextWidth = textElement.width;
+    const maxWidth = getBoundTextMaxWidth(container, textElement);
+    const maxHeight = getBoundTextMaxHeight(container, textElement);
+    let containerHeight = container.height;
+    if (
+      shouldMaintainAspectRatio ||
+      (transformHandleType !== "n" && transformHandleType !== "s")
+    ) {
+      if (text) {
+        text = wrapText(
+          textElement.originalText,
+          getFontString(textElement),
+          maxWidth,
+        );
+      }
+      const metrics = measureText(
+        text,
+        getFontString(textElement),
+        textElement.lineHeight,
+      );
+      nextHeight = metrics.height;
+      nextWidth = metrics.width;
+    }
+    // increase height in case text element height exceeds
+    if (nextHeight > maxHeight) {
+      containerHeight = computeContainerDimensionForBoundText(
+        nextHeight,
+        container.type,
+      );
+
+      // Crossing the opposite edge swaps the anchor for text-driven growth.
+      const shouldResizeFromTop =
+        (transformHandleType === "n" ||
+          transformHandleType === "ne" ||
+          transformHandleType === "nw") !== flipByY;
+
+      scene.mutateElement(container, {
+        height: containerHeight,
+        ...(!isArrowElement(container) &&
+          getPositionAfterHeightChange(
+            container,
+            containerHeight,
+            shouldResizeFromCenter
+              ? "center"
+              : shouldResizeFromTop
+              ? "bottom"
+              : "top",
+          )),
+      });
+    }
+
+    scene.mutateElement(textElement, {
+      text,
+      width: nextWidth,
+      height: nextHeight,
+    });
+
+    if (!isArrowElement(container)) {
+      scene.mutateElement(
+        textElement,
+        computeBoundTextPosition(container, textElement, elementsMap),
+      );
+    }
+  }
+};
+
+export const computeBoundTextPosition = (
+  container: ExcalidrawElement,
+  boundTextElement: ExcalidrawTextElementWithContainer,
+  elementsMap: ElementsMap,
+) => {
+  if (isArrowElement(container)) {
+    return LinearElementEditor.getBoundTextElementPosition(
+      container,
+      boundTextElement,
+      elementsMap,
+    );
+  }
+  const containerCoords = getContainerCoords(container);
+  const maxContainerHeight = getBoundTextMaxHeight(container, boundTextElement);
+  const maxContainerWidth = getBoundTextMaxWidth(container, boundTextElement);
+
+  let x;
+  let y;
+  if (boundTextElement.verticalAlign === VERTICAL_ALIGN.TOP) {
+    y = containerCoords.y;
+  } else if (boundTextElement.verticalAlign === VERTICAL_ALIGN.BOTTOM) {
+    y = containerCoords.y + (maxContainerHeight - boundTextElement.height);
+  } else if (isStickyNoteElement(container)) {
+    // a note's label body ends above the creation-date footer, but a label
+    // centered in that body sits visibly high — center it in the whole
+    // padded note while it stays clear of the footer, and only push it up
+    // against the body's bottom once it would overlap
+    const paddedHeight = container.height - STICKY_NOTE_PADDING * 2;
+    y =
+      containerCoords.y +
+      Math.min(
+        (paddedHeight - boundTextElement.height) / 2,
+        maxContainerHeight - boundTextElement.height,
+      );
+  } else {
+    y =
+      containerCoords.y +
+      (maxContainerHeight / 2 - boundTextElement.height / 2);
+  }
+  if (boundTextElement.textAlign === TEXT_ALIGN.LEFT) {
+    x = containerCoords.x;
+  } else if (boundTextElement.textAlign === TEXT_ALIGN.RIGHT) {
+    x = containerCoords.x + (maxContainerWidth - boundTextElement.width);
+  } else {
+    x =
+      containerCoords.x + (maxContainerWidth / 2 - boundTextElement.width / 2);
+  }
+  const angle = (container.angle ?? 0) as Radians;
+
+  if (angle !== 0) {
+    // A sticky's footer makes its body asymmetric. The body still rotates
+    // about the note's center, rather than about its own (higher) center.
+    const contentCenter = isStickyNoteElement(container)
+      ? pointFrom(
+          container.x + container.width / 2,
+          container.y + container.height / 2,
+        )
+      : pointFrom(
+          containerCoords.x + maxContainerWidth / 2,
+          containerCoords.y + maxContainerHeight / 2,
+        );
+    const textCenter = pointFrom(
+      x + boundTextElement.width / 2,
+      y + boundTextElement.height / 2,
+    );
+
+    const [rx, ry] = pointRotateRads(textCenter, contentCenter, angle);
+
+    return {
+      x: rx - boundTextElement.width / 2,
+      y: ry - boundTextElement.height / 2,
+    };
+  }
+
+  return { x, y };
+};
+
+export const getBoundTextElementId = (container: ExcalidrawElement | null) => {
+  return container?.boundElements?.length
+    ? container?.boundElements?.find((ele) => ele.type === "text")?.id || null
+    : null;
+};
+
+export const getBoundTextElement = (
+  element: ExcalidrawElement | null,
+  elementsMap: ElementsMap,
+): NonDeleted<ExcalidrawTextElementWithContainer> | null => {
+  if (!element) {
+    return null;
+  }
+  const boundTextElementId = getBoundTextElementId(element);
+
+  if (boundTextElementId) {
+    const boundTextElement = (elementsMap.get(boundTextElementId) ||
+      null) as NonDeleted<ExcalidrawTextElementWithContainer> | null;
+
+    // SAFETY: This should never happen, but log it just in case
+    if (boundTextElement && !isNonDeletedElement(boundTextElement)) {
+      console.error(
+        "[NONDELETED][INVARIANT] Bound text element `isDeleted: true` which is not expected.",
+      );
+    }
+
+    return boundTextElement;
+  }
+  return null;
+};
+
+export const getContainerElement = <
+  T extends ExcalidrawTextElement,
+  R extends ExcalidrawTextContainer,
+>(
+  element: T | null,
+  elementsMap: ElementsMap,
+): R | null => {
+  if (!element) {
+    return null;
+  }
+  if (element.containerId) {
+    return (elementsMap.get(element.containerId) || null) as R | null;
+  }
+  return null;
+};
+
+/**
+ * The point a text bound to this container centers on — and, for arrows, the
+ * point the text tool snaps a new label to.
+ */
+export const getContainerCenter = (
+  container: ExcalidrawElement,
+  elementsMap: ElementsMap,
+) => {
+  if (!isArrowElement(container)) {
+    return {
+      x: container.x + container.width / 2,
+      y: container.y + container.height / 2,
+    };
+  }
+
+  const center = LinearElementEditor.getBoundTextElementCenter(
+    container,
+    elementsMap,
+  );
+
+  return { x: center[0], y: center[1] };
+};
+
+export const getContainerCoords = (container: ExcalidrawElement) => {
+  const padding = isStickyNoteElement(container)
+    ? STICKY_NOTE_PADDING
+    : BOUND_TEXT_PADDING;
+  let offsetX = padding;
+  let offsetY = padding;
+
+  if (container.type === "ellipse") {
+    // The derivation of coordinates is explained in https://github.com/excalidraw/excalidraw/pull/6172
+    offsetX += (container.width / 2) * (1 - Math.sqrt(2) / 2);
+    offsetY += (container.height / 2) * (1 - Math.sqrt(2) / 2);
+  }
+  // The derivation of coordinates is explained in https://github.com/excalidraw/excalidraw/pull/6265
+  if (container.type === "diamond") {
+    offsetX += container.width / 4;
+    offsetY += container.height / 4;
+  }
+  return {
+    x: container.x + offsetX,
+    y: container.y + offsetY,
+  };
+};
+
+export const getTextElementAngle = (
+  textElement: ExcalidrawTextElement,
+  container: ExcalidrawTextContainer | null,
+) => {
+  if (isArrowElement(container)) {
+    return 0;
+  }
+  if (!container) {
+    return textElement.angle;
+  }
+  return container.angle;
+};
+
+export const getBoundTextElementPosition = (
+  container: ExcalidrawElement,
+  boundTextElement: ExcalidrawTextElementWithContainer,
+  elementsMap: ElementsMap,
+) => {
+  if (isArrowElement(container)) {
+    return LinearElementEditor.getBoundTextElementPosition(
+      container,
+      boundTextElement,
+      elementsMap,
+    );
+  }
+};
+
+export const shouldAllowVerticalAlign = (
+  selectedElements: readonly ExcalidrawElement[],
+  elementsMap: ElementsMap,
+) => {
+  return selectedElements.some((element) => {
+    if (isBoundToContainer(element)) {
+      const container = getContainerElement(element, elementsMap);
+      if (isArrowElement(container)) {
+        return false;
+      }
+      return true;
+    }
+    return false;
+  });
+};
+
+export const suppportsHorizontalAlign = (
+  selectedElements: readonly ExcalidrawElement[],
+  elementsMap: ElementsMap,
+) => {
+  return selectedElements.some((element) => {
+    if (isBoundToContainer(element)) {
+      const container = getContainerElement(element, elementsMap);
+      if (isArrowElement(container)) {
+        return false;
+      }
+      return true;
+    }
+
+    return isTextElement(element);
+  });
+};
+
+const VALID_CONTAINER_TYPES = new Set([
+  "rectangle",
+  "stickynote",
+  "ellipse",
+  "diamond",
+  "arrow",
+]);
+
+export const isValidTextContainer = (element: {
+  type: ExcalidrawElementType;
+}): element is ExcalidrawTextContainer =>
+  VALID_CONTAINER_TYPES.has(element.type);
+
+export const computeContainerDimensionForBoundText = (
+  dimension: number,
+  containerType: ExtractSetType<typeof VALID_CONTAINER_TYPES>,
+) => {
+  dimension = Math.ceil(dimension);
+  const padding = BOUND_TEXT_PADDING * 2;
+
+  if (containerType === "ellipse") {
+    return Math.round(((dimension + padding) / Math.sqrt(2)) * 2);
+  }
+  if (containerType === "arrow") {
+    return dimension + padding * 8;
+  }
+  if (containerType === "diamond") {
+    return 2 * (dimension + padding);
+  }
+  return dimension + padding;
+};
+
+export const getBoundTextMaxWidth = (
+  container: ExcalidrawElement,
+  boundTextElement: ExcalidrawTextElement | null,
+) => {
+  const { width } = container;
+  if (isArrowElement(container)) {
+    const minWidth =
+      (boundTextElement?.fontSize ?? DEFAULT_FONT_SIZE) *
+      ARROW_LABEL_FONT_SIZE_TO_MIN_WIDTH_RATIO;
+    return Math.max(ARROW_LABEL_WIDTH_FRACTION * width, minWidth);
+  }
+  if (container.type === "ellipse") {
+    // The width of the largest rectangle inscribed inside an ellipse is
+    // Math.round((ellipse.width / 2) * Math.sqrt(2)) which is derived from
+    // equation of an ellipse -https://github.com/excalidraw/excalidraw/pull/6172
+    return Math.round((width / 2) * Math.sqrt(2)) - BOUND_TEXT_PADDING * 2;
+  }
+  if (container.type === "diamond") {
+    // The width of the largest rectangle inscribed inside a rhombus is
+    // Math.round(width / 2) - https://github.com/excalidraw/excalidraw/pull/6265
+    return Math.round(width / 2) - BOUND_TEXT_PADDING * 2;
+  }
+  return (
+    width -
+    (isStickyNoteElement(container)
+      ? STICKY_NOTE_PADDING
+      : BOUND_TEXT_PADDING) *
+      2
+  );
+};
+
+export const getBoundTextMaxHeight = (
+  container: ExcalidrawElement,
+  boundTextElement: ExcalidrawTextElementWithContainer,
+) => {
+  const { height } = container;
+  if (isStickyNoteElement(container)) {
+    // the label body ends above the creation-date footer
+    return Math.max(0, height - STICKY_NOTE_BODY_INSET_Y);
+  }
+  if (isArrowElement(container)) {
+    const containerHeight = height - BOUND_TEXT_PADDING * 8 * 2;
+    if (containerHeight <= 0) {
+      return boundTextElement.height;
+    }
+    return height;
+  }
+  if (container.type === "ellipse") {
+    // The height of the largest rectangle inscribed inside an ellipse is
+    // Math.round((ellipse.height / 2) * Math.sqrt(2)) which is derived from
+    // equation of an ellipse - https://github.com/excalidraw/excalidraw/pull/6172
+    return Math.round((height / 2) * Math.sqrt(2)) - BOUND_TEXT_PADDING * 2;
+  }
+  if (container.type === "diamond") {
+    // The height of the largest rectangle inscribed inside a rhombus is
+    // Math.round(height / 2) - https://github.com/excalidraw/excalidraw/pull/6265
+    return Math.round(height / 2) - BOUND_TEXT_PADDING * 2;
+  }
+  return height - BOUND_TEXT_PADDING * 2;
+};
+
+/** retrieves text from text elements and concatenates to a single string */
+export const getTextFromElements = (
+  elements: readonly ExcalidrawElement[],
+  separator = "\n\n",
+) => {
+  const text = elements
+    .reduce((acc: string[], element) => {
+      if (isTextElement(element)) {
+        acc.push(element.text);
+      }
+      return acc;
+    }, [])
+    .join(separator);
+  return text;
+};
+
+export const DEFAULT_BOUND_TEXT_LABEL_POSITION = 0.5;

packages/element/src/textMeasurements.ts

@@ -0,0 +1,227 @@
+import {
+  BOUND_TEXT_PADDING,
+  DEFAULT_FONT_SIZE,
+  DEFAULT_FONT_FAMILY,
+  getFontString,
+  isTestEnv,
+  normalizeEOL,
+} from "@excalidraw/common";
+
+import type { FontString, ExcalidrawTextElement } from "./types";
+
+export const measureText = (
+  text: string,
+  font: FontString,
+  lineHeight: ExcalidrawTextElement["lineHeight"],
+) => {
+  const _text = text
+    .split("\n")
+    // replace empty lines with single space because leading/trailing empty
+    // lines would be stripped from computation
+    .map((x) => x || " ")
+    .join("\n");
+  const fontSize = parseFloat(font);
+  const height = getTextHeight(_text, fontSize, lineHeight);
+  const width = getTextWidth(_text, font);
+  return { width, height };
+};
+
+const DUMMY_TEXT = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789".toLocaleUpperCase();
+
+// FIXME rename to getApproxMinContainerWidth
+export const getApproxMinLineWidth = (
+  font: FontString,
+  lineHeight: ExcalidrawTextElement["lineHeight"],
+) => {
+  const maxCharWidth = getMaxCharWidth(font);
+  if (maxCharWidth === 0) {
+    return (
+      measureText(DUMMY_TEXT.split("").join("\n"), font, lineHeight).width +
+      BOUND_TEXT_PADDING * 2
+    );
+  }
+  return maxCharWidth + BOUND_TEXT_PADDING * 2;
+};
+
+export const getMinTextElementWidth = (
+  font: FontString,
+  lineHeight: ExcalidrawTextElement["lineHeight"],
+) => {
+  return measureText("", font, lineHeight).width + BOUND_TEXT_PADDING * 2;
+};
+
+export const isMeasureTextSupported = () => {
+  const width = getTextWidth(
+    DUMMY_TEXT,
+    getFontString({
+      fontSize: DEFAULT_FONT_SIZE,
+      fontFamily: DEFAULT_FONT_FAMILY,
+    }),
+  );
+  return width > 0;
+};
+
+export const normalizeText = (text: string) => {
+  return (
+    normalizeEOL(text)
+      // replace tabs with spaces so they render and measure correctly
+      .replace(/\t/g, "        ")
+  );
+};
+
+const splitIntoLines = (text: string) => {
+  return normalizeText(text).split("\n");
+};
+
+/**
+ * To get unitless line-height (if unknown) we can calculate it by dividing
+ * height-per-line by fontSize.
+ */
+export const detectLineHeight = (textElement: ExcalidrawTextElement) => {
+  const lineCount = splitIntoLines(textElement.text).length;
+  return (textElement.height /
+    lineCount /
+    textElement.fontSize) as ExcalidrawTextElement["lineHeight"];
+};
+
+/**
+ * We calculate the line height from the font size and the unitless line height,
+ * aligning with the W3C spec.
+ */
+export const getLineHeightInPx = (
+  fontSize: ExcalidrawTextElement["fontSize"],
+  lineHeight: ExcalidrawTextElement["lineHeight"],
+) => {
+  return fontSize * lineHeight;
+};
+
+// FIXME rename to getApproxMinContainerHeight
+export const getApproxMinLineHeight = (
+  fontSize: ExcalidrawTextElement["fontSize"],
+  lineHeight: ExcalidrawTextElement["lineHeight"],
+) => {
+  return getLineHeightInPx(fontSize, lineHeight) + BOUND_TEXT_PADDING * 2;
+};
+
+let textMetricsProvider: TextMetricsProvider | undefined;
+
+/**
+ * Set a custom text metrics provider.
+ *
+ * Useful for overriding the width calculation algorithm where canvas API is not available / desired.
+ */
+export const setCustomTextMetricsProvider = (provider: TextMetricsProvider) => {
+  textMetricsProvider = provider;
+};
+
+export interface TextMetricsProvider {
+  getLineWidth(text: string, fontString: FontString): number;
+}
+
+class CanvasTextMetricsProvider implements TextMetricsProvider {
+  private canvas: HTMLCanvasElement;
+
+  constructor() {
+    this.canvas = document.createElement("canvas");
+  }
+
+  /**
+   * We need to use the advance width as that's the closest thing to the browser wrapping algo, hence using it for:
+   * - text wrapping
+   * - wysiwyg editor (+padding)
+   *
+   * > The advance width is the distance between the glyph's initial pen position and the next glyph's initial pen position.
+   */
+  public getLineWidth(text: string, fontString: FontString): number {
+    const context = this.canvas.getContext("2d")!;
+    context.font = fontString;
+    const metrics = context.measureText(text);
+    const advanceWidth = metrics.width;
+
+    // since in test env the canvas measureText algo
+    // doesn't measure text and instead just returns number of
+    // characters hence we assume that each letteris 10px
+    if (isTestEnv()) {
+      return advanceWidth * 10;
+    }
+
+    return advanceWidth;
+  }
+}
+
+export const getLineWidth = (text: string, font: FontString) => {
+  if (!textMetricsProvider) {
+    textMetricsProvider = new CanvasTextMetricsProvider();
+  }
+
+  return textMetricsProvider.getLineWidth(text, font);
+};
+
+export const getTextWidth = (text: string, font: FontString) => {
+  const lines = splitIntoLines(text);
+  let width = 0;
+  lines.forEach((line) => {
+    width = Math.max(width, getLineWidth(line, font));
+  });
+
+  return width;
+};
+
+export const getTextHeight = (
+  text: string,
+  fontSize: number,
+  lineHeight: ExcalidrawTextElement["lineHeight"],
+) => {
+  const lineCount = splitIntoLines(text).length;
+  return getLineHeightInPx(fontSize, lineHeight) * lineCount;
+};
+
+export const charWidth = (() => {
+  const cachedCharWidth: { [key: FontString]: Array<number> } = {};
+
+  const calculate = (char: string, font: FontString) => {
+    const unicode = char.charCodeAt(0);
+    if (!cachedCharWidth[font]) {
+      cachedCharWidth[font] = [];
+    }
+    if (!cachedCharWidth[font][unicode]) {
+      const width = getLineWidth(char, font);
+      cachedCharWidth[font][unicode] = width;
+    }
+
+    return cachedCharWidth[font][unicode];
+  };
+
+  const getCache = (font: FontString) => {
+    return cachedCharWidth[font];
+  };
+
+  const clearCache = (font: FontString) => {
+    cachedCharWidth[font] = [];
+  };
+
+  return {
+    calculate,
+    getCache,
+    clearCache,
+  };
+})();
+
+export const getMinCharWidth = (font: FontString) => {
+  const cache = charWidth.getCache(font);
+  if (!cache) {
+    return 0;
+  }
+  const cacheWithOutEmpty = cache.filter((val) => val !== undefined);
+
+  return Math.min(...cacheWithOutEmpty);
+};
+
+export const getMaxCharWidth = (font: FontString) => {
+  const cache = charWidth.getCache(font);
+  if (!cache) {
+    return 0;
+  }
+  const cacheWithOutEmpty = cache.filter((val) => val !== undefined);
+  return Math.max(...cacheWithOutEmpty);
+};

packages/element/src/textWrapping.ts

@@ -0,0 +1,740 @@
+import { isDevEnv, isTestEnv } from "@excalidraw/common";
+
+import { charWidth, getLineWidth } from "./textMeasurements";
+
+import type { FontString } from "./types";
+
+/**
+ * This module approximates browser-like soft wrapping for Excalidraw text.
+ *
+ * The flow is:
+ * 1. `parseTokens()` splits a hard line into breakable tokens using a unicode-aware regex.
+ * 2. `getWrappedTextLines()` reflows each hard line into one or more visual lines and
+ *    records where each visual line came from in the source text.
+ * 3. `wrapLine()` assembles tokens into lines, and `wrapWord()` handles a single token
+ *    that is wider than the available width.
+ * 4. `trimLine()` / `trimLineEndAtSoftBreak()` mirror browser behavior around trailing
+ *    whitespace so the rendered text stays consistent with what users see on canvas.
+ *
+ * Mostly, you'll want to use wrapText(). getWrappedTextLines() is for callers
+ * that need metadata such as mapping visual lines back to `originalText`
+ * for caret placement or future editor features.
+ */
+let cachedCjkRegex: RegExp | undefined;
+let cachedLineBreakRegex: RegExp | undefined;
+let cachedEmojiRegex: RegExp | undefined;
+
+/**
+ * Test if a given text contains any CJK characters (including symbols, punctuation, etc,).
+ */
+export const containsCJK = (text: string) => {
+  if (!cachedCjkRegex) {
+    cachedCjkRegex = Regex.class(...Object.values(CJK));
+  }
+
+  return cachedCjkRegex.test(text);
+};
+
+const getLineBreakRegex = () => {
+  if (!cachedLineBreakRegex) {
+    try {
+      cachedLineBreakRegex = getLineBreakRegexAdvanced();
+    } catch {
+      cachedLineBreakRegex = getLineBreakRegexSimple();
+    }
+  }
+
+  return cachedLineBreakRegex;
+};
+
+const getEmojiRegex = () => {
+  if (!cachedEmojiRegex) {
+    cachedEmojiRegex = getEmojiRegexUnicode();
+  }
+
+  return cachedEmojiRegex;
+};
+
+/**
+ * Common symbols used across different languages.
+ */
+const COMMON = {
+  /**
+   * Natural breaking points for any grammars.
+   *
+   * Hello world
+   *      ↑ BREAK ALWAYS " " → ["Hello", " ", "world"]
+   * Hello-world
+   *       ↑ BREAK AFTER "-" → ["Hello-", "world"]
+   */
+  WHITESPACE: /\s/u,
+  HYPHEN: /-/u,
+  /**
+   * Generally do not break, unless closed symbol is followed by an opening symbol.
+   *
+   * Also, western punctation is often used in modern Korean and expects to be treated
+   * similarly to the CJK opening and closing symbols.
+   *
+   * Hello(한글)→ ["Hello", "(한", "글)"]
+   *      ↑ BREAK BEFORE "("
+   *          ↑ BREAK AFTER ")"
+   */
+  OPENING: /<\(\[\{/u,
+  CLOSING: />\)\]\}.,:;!\?…\//u,
+};
+
+/**
+ * Characters and symbols used in Chinese, Japanese and Korean.
+ */
+const CJK = {
+  /**
+   * Every CJK breaks before and after, unless it's paired with an opening or closing symbol.
+   *
+   * Does not include every possible char used in CJK texts, such as currency, parentheses or punctuation.
+   */
+  CHAR: /\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}｀＇＾〃〰〆＃＆＊＋－ー／＼＝｜￤〒￢￣/u,
+  /**
+   * Opening and closing CJK punctuation breaks before and after all such characters (in case of many),
+   * and creates pairs with neighboring characters.
+   *
+   * Hello た。→ ["Hello", "た。"]
+   *        ↑ DON'T BREAK "た。"
+   * * Hello「た」 World → ["Hello", "「た」", "World"]
+   *       ↑ DON'T BREAK "「た"
+   *        ↑ DON'T BREAK "た"
+   *      ↑ BREAK BEFORE "「"
+   *         ↑ BREAK AFTER "」"
+   */
+  // eslint-disable-next-line prettier/prettier
+  OPENING:/（［｛〈《｟｢「『【〖〔〘〚＜〝/u,
+  CLOSING: /）］｝〉》｠｣」』】〗〕〙〛＞。．，、〟‥？！：；・〜〞/u,
+  /**
+   * Currency symbols break before, not after
+   *
+   * Price￥100 → ["Price", "￥100"]
+   *      ↑ BREAK BEFORE "￥"
+   */
+  CURRENCY: /￥￦￡￠＄/u,
+};
+
+const EMOJI = {
+  FLAG: /\p{RI}\p{RI}/u,
+  JOINER:
+    /(?:\p{Emoji_Modifier}|\uFE0F\u20E3?|[\u{E0020}-\u{E007E}]+\u{E007F})?/u,
+  ZWJ: /\u200D/u,
+  ANY: /[\p{Emoji}]/u,
+  MOST: /[\p{Extended_Pictographic}\p{Emoji_Presentation}]/u,
+};
+
+/**
+ * Simple fallback for browsers (mainly Safari < 16.4) that don't support "Lookbehind assertion".
+ *
+ * Browser support as of 10/2024:
+ * - 91% Lookbehind assertion https://caniuse.com/mdn-javascript_regular_expressions_lookbehind_assertion
+ * - 94% Unicode character class escape https://caniuse.com/mdn-javascript_regular_expressions_unicode_character_class_escape
+ *
+ * Does not include advanced CJK breaking rules, but covers most of the core cases, especially for latin.
+ */
+const getLineBreakRegexSimple = () =>
+  Regex.or(
+    getEmojiRegex(),
+    Break.On(COMMON.HYPHEN, COMMON.WHITESPACE, CJK.CHAR),
+  );
+
+/**
+ * Specifies the line breaking rules based for alphabetic-based languages,
+ * Chinese, Japanese, Korean and Emojis.
+ *
+ * "Hello-world" → ["Hello-", "world"]
+ * "Hello 「世界。」🌎🗺" → ["Hello", " ", "「世", "界。」", "🌎", "🗺"]
+ */
+const getLineBreakRegexAdvanced = () =>
+  Regex.or(
+    // Unicode-defined regex for (multi-codepoint) Emojis
+    getEmojiRegex(),
+    // Rules for whitespace and hyphen
+    Break.Before(COMMON.WHITESPACE).Build(),
+    Break.After(COMMON.WHITESPACE, COMMON.HYPHEN).Build(),
+    // Rules for CJK (chars, symbols, currency)
+    Break.Before(CJK.CHAR, CJK.CURRENCY)
+      .NotPrecededBy(COMMON.OPENING, CJK.OPENING)
+      .Build(),
+    Break.After(CJK.CHAR)
+      .NotFollowedBy(COMMON.HYPHEN, COMMON.CLOSING, CJK.CLOSING)
+      .Build(),
+    // Rules for opening and closing punctuation
+    Break.BeforeMany(CJK.OPENING).NotPrecededBy(COMMON.OPENING).Build(),
+    Break.AfterMany(CJK.CLOSING).NotFollowedBy(COMMON.CLOSING).Build(),
+    Break.AfterMany(COMMON.CLOSING).FollowedBy(COMMON.OPENING).Build(),
+  );
+
+/**
+ * Matches various emoji types.
+ *
+ * 1. basic emojis (😀, 🌍)
+ * 2. flags (🇨🇿)
+ * 3. multi-codepoint emojis:
+ *    - skin tones (👍🏽)
+ *    - variation selectors (☂️)
+ *    - keycaps (1️⃣)
+ *    - tag sequences (🏴󠁧󠁢󠁥󠁮󠁧󠁿)
+ *    - emoji sequences (👨‍👩‍👧‍👦, 👩‍🚀, 🏳️‍🌈)
+ *
+ * Unicode points:
+ * - \uFE0F: presentation selector
+ * - \u20E3: enclosing keycap
+ * - \u200D: zero width joiner
+ * - \u{E0020}-\u{E007E}: tags
+ * - \u{E007F}: cancel tag
+ *
+ * @see https://unicode.org/reports/tr51/#EBNF_and_Regex, with changes:
+ * - replaced \p{Emoji} with [\p{Extended_Pictographic}\p{Emoji_Presentation}], see more in `should tokenize emojis mixed with mixed text` test
+ * - replaced \p{Emod} with \p{Emoji_Modifier} as some engines do not understand the abbreviation (i.e. https://devina.io/redos-checker)
+ */
+const getEmojiRegexUnicode = () =>
+  Regex.group(
+    Regex.or(
+      EMOJI.FLAG,
+      Regex.and(
+        EMOJI.MOST,
+        EMOJI.JOINER,
+        Regex.build(
+          `(?:${EMOJI.ZWJ.source}(?:${EMOJI.FLAG.source}|${EMOJI.ANY.source}${EMOJI.JOINER.source}))*`,
+        ),
+      ),
+    ),
+  );
+
+/**
+ * Regex utilities for unicode character classes.
+ */
+const Regex = {
+  /**
+   * Builds a regex from a string.
+   */
+  build: (regex: string): RegExp => new RegExp(regex, "u"),
+  /**
+   * Joins regexes into a single string.
+   */
+  join: (...regexes: RegExp[]): string => regexes.map((x) => x.source).join(""),
+  /**
+   * Joins regexes into a single regex as with "and" operator.
+   */
+  and: (...regexes: RegExp[]): RegExp => Regex.build(Regex.join(...regexes)),
+  /**
+   * Joins regexes into a single regex with "or" operator.
+   */
+  or: (...regexes: RegExp[]): RegExp =>
+    Regex.build(regexes.map((x) => x.source).join("|")),
+  /**
+   * Puts regexes into a matching group.
+   */
+  group: (...regexes: RegExp[]): RegExp =>
+    Regex.build(`(${Regex.join(...regexes)})`),
+  /**
+   * Puts regexes into a character class.
+   */
+  class: (...regexes: RegExp[]): RegExp =>
+    Regex.build(`[${Regex.join(...regexes)}]`),
+};
+
+/**
+ * Human-readable lookahead and lookbehind utilities for defining line break
+ * opportunities between pairs of character classes.
+ */
+const Break = {
+  /**
+   * Break on the given class of characters.
+   */
+  On: (...regexes: RegExp[]) => {
+    const joined = Regex.join(...regexes);
+    return Regex.build(`([${joined}])`);
+  },
+  /**
+   * Break before the given class of characters.
+   */
+  Before: (...regexes: RegExp[]) => {
+    const joined = Regex.join(...regexes);
+    const builder = () => Regex.build(`(?=[${joined}])`);
+    return Break.Chain(builder) as Omit<
+      ReturnType<typeof Break.Chain>,
+      "FollowedBy"
+    >;
+  },
+  /**
+   * Break after the given class of characters.
+   */
+  After: (...regexes: RegExp[]) => {
+    const joined = Regex.join(...regexes);
+    const builder = () => Regex.build(`(?<=[${joined}])`);
+    return Break.Chain(builder) as Omit<
+      ReturnType<typeof Break.Chain>,
+      "PreceededBy"
+    >;
+  },
+  /**
+   * Break before one or multiple characters of the same class.
+   */
+  BeforeMany: (...regexes: RegExp[]) => {
+    const joined = Regex.join(...regexes);
+    const builder = () => Regex.build(`(?<![${joined}])(?=[${joined}])`);
+    return Break.Chain(builder) as Omit<
+      ReturnType<typeof Break.Chain>,
+      "FollowedBy"
+    >;
+  },
+  /**
+   * Break after one or multiple character from the same class.
+   */
+  AfterMany: (...regexes: RegExp[]) => {
+    const joined = Regex.join(...regexes);
+    const builder = () => Regex.build(`(?<=[${joined}])(?![${joined}])`);
+    return Break.Chain(builder) as Omit<
+      ReturnType<typeof Break.Chain>,
+      "PreceededBy"
+    >;
+  },
+  /**
+   * Do not break before the given class of characters.
+   */
+  NotBefore: (...regexes: RegExp[]) => {
+    const joined = Regex.join(...regexes);
+    const builder = () => Regex.build(`(?![${joined}])`);
+    return Break.Chain(builder) as Omit<
+      ReturnType<typeof Break.Chain>,
+      "NotFollowedBy"
+    >;
+  },
+  /**
+   * Do not break after the given class of characters.
+   */
+  NotAfter: (...regexes: RegExp[]) => {
+    const joined = Regex.join(...regexes);
+    const builder = () => Regex.build(`(?<![${joined}])`);
+    return Break.Chain(builder) as Omit<
+      ReturnType<typeof Break.Chain>,
+      "NotPrecededBy"
+    >;
+  },
+  Chain: (rootBuilder: () => RegExp) => ({
+    /**
+     * Build the root regex.
+     */
+    Build: rootBuilder,
+    /**
+     * Specify additional class of characters that should precede the root regex.
+     */
+    PreceededBy: (...regexes: RegExp[]) => {
+      const root = rootBuilder();
+      const preceeded = Break.After(...regexes).Build();
+      const builder = () => Regex.and(preceeded, root);
+      return Break.Chain(builder) as Omit<
+        ReturnType<typeof Break.Chain>,
+        "PreceededBy"
+      >;
+    },
+    /**
+     * Specify additional class of characters that should follow the root regex.
+     */
+    FollowedBy: (...regexes: RegExp[]) => {
+      const root = rootBuilder();
+      const followed = Break.Before(...regexes).Build();
+      const builder = () => Regex.and(root, followed);
+      return Break.Chain(builder) as Omit<
+        ReturnType<typeof Break.Chain>,
+        "FollowedBy"
+      >;
+    },
+    /**
+     * Specify additional class of characters that should not precede the root regex.
+     */
+    NotPrecededBy: (...regexes: RegExp[]) => {
+      const root = rootBuilder();
+      const notPreceeded = Break.NotAfter(...regexes).Build();
+      const builder = () => Regex.and(notPreceeded, root);
+      return Break.Chain(builder) as Omit<
+        ReturnType<typeof Break.Chain>,
+        "NotPrecededBy"
+      >;
+    },
+    /**
+     * Specify additional class of characters that should not follow the root regex.
+     */
+    NotFollowedBy: (...regexes: RegExp[]) => {
+      const root = rootBuilder();
+      const notFollowed = Break.NotBefore(...regexes).Build();
+      const builder = () => Regex.and(root, notFollowed);
+      return Break.Chain(builder) as Omit<
+        ReturnType<typeof Break.Chain>,
+        "NotFollowedBy"
+      >;
+    },
+  }),
+};
+
+/**
+ * Breaks the line into the tokens based on the found line break opporutnities.
+ *
+ * Note: tokenization normalizes to NFC first so decomposed graphemes are treated as
+ * their composed variants for wrapping. Any code that needs exact source offsets should
+ * keep in mind that this assumes the input text is already NFC-normalized.
+ */
+export const parseTokens = (line: string) => {
+  const breakLineRegex = getLineBreakRegex();
+
+  // normalizing to single-codepoint composed chars due to canonical equivalence
+  // of multi-codepoint versions for chars like č, で (~ so that we don't break a line in between c and ˇ)
+  // filtering due to multi-codepoint chars like 👨‍👩‍👧‍👦, 👩🏽‍🦰
+  return line.normalize("NFC").split(breakLineRegex).filter(Boolean);
+};
+
+/**
+ * Wraps the original text into the lines based on the given width.
+ *
+ * This is a convenience adapter over `getWrappedTextLines()` for call sites
+ * that only need the rendered wrapped string and not the source offsets.
+ */
+export const wrapText = (
+  text: string,
+  font: FontString,
+  maxWidth: number,
+): string => {
+  return getWrappedTextLines(text, font, maxWidth)
+    .map((line) => line.text)
+    .join("\n");
+};
+
+/**
+ * A single rendered visual line produced from the original text.
+ *
+ * `start` and `end` are end-exclusive code-unit offsets into the original text, and do
+ * not include synthetic soft line breaks inserted by this module. If trailing whitespace
+ * was trimmed away at a wrap boundary, `end` points to the last rendered character.
+ */
+export type WrappedTextLine = {
+  text: string;
+  start: number;
+  end: number;
+};
+
+/**
+ * Splits only on existing hard line breaks and preserves original offsets.
+ */
+const getHardLineBreaks = (text: string): WrappedTextLine[] => {
+  let offset = 0;
+
+  return text.split("\n").map((line) => {
+    const start = offset;
+    const end = start + line.length;
+
+    offset = end + 1;
+
+    return {
+      text: line,
+      start,
+      end,
+    };
+  });
+};
+
+/**
+ * Returns the rendered visual lines together with their source offsets.
+ *
+ * This is the source-of-truth wrapping pipeline for callers that need more than the
+ * final wrapped string, for example caret placement or future editor/rich-text mapping.
+ */
+export const getWrappedTextLines = (
+  text: string,
+  font: FontString,
+  maxWidth: number,
+): WrappedTextLine[] => {
+  // if maxWidth is not finite or NaN which can happen in case of bugs in
+  // computation, we need to make sure we don't continue as we'll end up
+  // in an infinite loop
+  if (!Number.isFinite(maxWidth) || maxWidth < 0) {
+    return getHardLineBreaks(text);
+  }
+
+  const lines: WrappedTextLine[] = [];
+  let offset = 0;
+
+  for (const originalLine of text.split("\n")) {
+    const originalLineWidth = getLineWidth(originalLine, font);
+
+    if (originalLineWidth <= maxWidth) {
+      lines.push({
+        text: originalLine,
+        start: offset,
+        end: offset + originalLine.length,
+      });
+    } else {
+      lines.push(...wrapLine(originalLine, font, maxWidth, offset));
+    }
+
+    offset += originalLine.length + 1;
+  }
+
+  return lines;
+};
+
+/**
+ * Wraps a single hard line into one or more visual lines.
+ *
+ * The line-local offsets are tracked in original-text code units so
+ * we can map the visual line back to the source.
+ */
+const wrapLine = (
+  line: string,
+  font: FontString,
+  maxWidth: number,
+  lineStart: number,
+): WrappedTextLine[] => {
+  const lines: WrappedTextLine[] = [];
+  const tokens = parseTokens(line);
+
+  let currentLine = "";
+  let currentLineStart = lineStart;
+  let currentLineEnd = lineStart;
+  let currentLineWidth = 0;
+  // Tracks the next token's code-unit position in the original source string.
+  let tokenOffset = lineStart;
+  let tokenIndex = 0;
+
+  while (tokenIndex < tokens.length) {
+    const token = tokens[tokenIndex];
+    const tokenStart = tokenOffset;
+    const tokenEnd = tokenStart + token.length;
+    const testLine = currentLine + token;
+
+    // cache single codepoint whitespace, CJK or emoji width calc. as kerning should not apply here
+    const testLineWidth = isSingleCharacter(token)
+      ? currentLineWidth + charWidth.calculate(token, font)
+      : getLineWidth(testLine, font);
+
+    // build up the current line, skipping length check for possibly trailing whitespaces
+    if (/\s/.test(token) || testLineWidth <= maxWidth) {
+      if (!currentLine) {
+        currentLineStart = tokenStart;
+      }
+      currentLine = testLine;
+      currentLineEnd = tokenEnd;
+      currentLineWidth = testLineWidth;
+      tokenOffset = tokenEnd;
+      tokenIndex++;
+      continue;
+    }
+
+    // current line is empty => just the token (word) is longer than `maxWidth` and needs to be wrapped
+    if (!currentLine) {
+      const wrappedWord = wrapWord(token, font, maxWidth, tokenStart);
+      const trailingLine = wrappedWord[wrappedWord.length - 1] ?? {
+        text: "",
+        start: tokenStart,
+        end: tokenStart,
+      };
+      const precedingLines = wrappedWord.slice(0, -1);
+
+      lines.push(...precedingLines);
+
+      // trailing line of the wrapped word might still be joined with next token/s
+      currentLine = trailingLine.text;
+      currentLineStart = trailingLine.start;
+      currentLineEnd = trailingLine.end;
+      currentLineWidth = getLineWidth(trailingLine.text, font);
+      tokenOffset = tokenEnd;
+      tokenIndex++;
+    } else {
+      // push & reset, but don't iterate on the next token, as we didn't use it yet!
+      lines.push(
+        trimLineEndAtSoftBreak(currentLine, currentLineStart, currentLineEnd),
+      );
+
+      // purposefully not iterating and not setting `currentLine` to `token`, so that we could use a simple !currentLine check above
+      currentLine = "";
+      currentLineStart = tokenStart;
+      currentLineEnd = tokenStart;
+      currentLineWidth = 0;
+    }
+  }
+
+  // iterator done, push the trailing line if exists
+  if (currentLine) {
+    const trailingLine = trimLine(
+      currentLine,
+      currentLineStart,
+      currentLineEnd,
+      font,
+      maxWidth,
+    );
+    lines.push(trailingLine);
+  }
+
+  return lines;
+};
+
+/**
+ * Wraps a single word that could not be placed on an empty line as-is.
+ */
+const wrapWord = (
+  word: string,
+  font: FontString,
+  maxWidth: number,
+  wordStart: number,
+): WrappedTextLine[] => {
+  // multi-codepoint emojis are already broken apart and shouldn't be broken further
+  if (getEmojiRegex().test(word)) {
+    return [
+      {
+        text: word,
+        start: wordStart,
+        end: wordStart + word.length,
+      },
+    ];
+  }
+
+  satisfiesWordInvariant(word);
+
+  const lines: WrappedTextLine[] = [];
+  const chars = Array.from(word);
+
+  let currentLine = "";
+  let currentLineStart = wordStart;
+  let currentLineEnd = wordStart;
+  let currentLineWidth = 0;
+  let offset = wordStart;
+
+  for (const char of chars) {
+    const charStart = offset;
+    const charEnd = charStart + char.length;
+    const _charWidth = charWidth.calculate(char, font);
+    const testLineWidth = currentLineWidth + _charWidth;
+
+    if (testLineWidth <= maxWidth) {
+      if (!currentLine) {
+        currentLineStart = charStart;
+      }
+      currentLine = currentLine + char;
+      currentLineEnd = charEnd;
+      currentLineWidth = testLineWidth;
+      offset = charEnd;
+      continue;
+    }
+
+    if (currentLine) {
+      lines.push({
+        text: currentLine,
+        start: currentLineStart,
+        end: currentLineEnd,
+      });
+    }
+
+    currentLine = char;
+    currentLineStart = charStart;
+    currentLineEnd = charEnd;
+    currentLineWidth = _charWidth;
+    offset = charEnd;
+  }
+
+  if (currentLine) {
+    lines.push({
+      text: currentLine,
+      start: currentLineStart,
+      end: currentLineEnd,
+    });
+  }
+
+  return lines;
+};
+
+/**
+ * Trims trailing whitespace that is exceeding the `maxWidth`.
+ *
+ * Used for the trailing visual line of a hard line, where some trailing
+ * whitespace may still be visible if it fits into the available width.
+ */
+const trimLine = (
+  line: string,
+  start: number,
+  end: number,
+  font: FontString,
+  maxWidth: number,
+): WrappedTextLine => {
+  const shouldTrimWhitespaces = getLineWidth(line, font) > maxWidth;
+
+  if (!shouldTrimWhitespaces) {
+    return {
+      text: line,
+      start,
+      end,
+    };
+  }
+
+  // defensively default to `trimeEnd` in case the regex does not match
+  let [, trimmedLine, whitespaces] = line.match(/^(.+?)(\s+)$/) ?? [
+    line,
+    line.trimEnd(),
+    "",
+  ];
+
+  let trimmedLineWidth = getLineWidth(trimmedLine, font);
+
+  for (const whitespace of Array.from(whitespaces)) {
+    const _charWidth = charWidth.calculate(whitespace, font);
+    const testLineWidth = trimmedLineWidth + _charWidth;
+
+    if (testLineWidth > maxWidth) {
+      break;
+    }
+
+    trimmedLine = trimmedLine + whitespace;
+    trimmedLineWidth = testLineWidth;
+  }
+
+  return {
+    text: trimmedLine,
+    start,
+    end: end - (line.length - trimmedLine.length),
+  };
+};
+
+/**
+ * Used for internal soft-wrap boundaries, where trailing whitespace should not
+ * survive into the rendered line even though it still exists in the original
+ * text.
+ */
+const trimLineEndAtSoftBreak = (
+  line: string,
+  start: number,
+  end: number,
+): WrappedTextLine => {
+  const trimmedLine = line.trimEnd();
+
+  return {
+    text: trimmedLine,
+    start,
+    end: end - (line.length - trimmedLine.length),
+  };
+};
+
+/**
+ * Check if the given string is a single character.
+ *
+ * Handles multi-byte chars (é, 中) and purposefully does not handle multi-codepoint char (👨‍👩‍👧‍👦, 👩🏽‍🦰).
+ */
+const isSingleCharacter = (maybeSingleCharacter: string) => {
+  return (
+    maybeSingleCharacter.codePointAt(0) !== undefined &&
+    maybeSingleCharacter.codePointAt(1) === undefined
+  );
+};
+
+/**
+ * Invariant for the word wrapping algorithm.
+ */
+const satisfiesWordInvariant = (word: string) => {
+  if (isTestEnv() || isDevEnv()) {
+    if (/\s/.test(word)) {
+      throw new Error("Word should not contain any whitespaces!");
+    }
+  }
+};

packages/element/src/transform.ts

@@ -0,0 +1,895 @@
+import { pointFrom, type LocalPoint } from "@excalidraw/math";
+
+import {
+  DEFAULT_FONT_FAMILY,
+  DEFAULT_FONT_SIZE,
+  TEXT_ALIGN,
+  VERTICAL_ALIGN,
+  getSizeFromPoints,
+  randomId,
+  arrayToMap,
+  assertNever,
+  cloneJSON,
+  getFontString,
+  getUpdatedTimestamp,
+  isDevEnv,
+  toBrandedType,
+  getLineHeight,
+  DEFAULT_STICKY_NOTE_SIZE,
+  isTransparent,
+} from "@excalidraw/common";
+
+import type { MarkOptional } from "@excalidraw/common/utility-types";
+
+import { bindBindingElement } from "./binding";
+import {
+  newArrowElement,
+  newElement,
+  newEmbeddableElement,
+  newFrameElement,
+  newFreeDrawElement,
+  newIframeElement,
+  newImageElement,
+  newLinearElement,
+  newMagicFrameElement,
+  newTextElement,
+  type ElementConstructorOpts,
+  newStickyNoteElement,
+  normalizeStickyNoteGeometry,
+} from "./newElement";
+import { normalizeStickyNoteStrokeColor } from "./stickyNote";
+import { measureText, normalizeText } from "./textMeasurements";
+import { isArrowElement, isStickyNoteElement } from "./typeChecks";
+
+import { syncInvalidIndices } from "./fractionalIndex";
+
+import {
+  DEFAULT_BOUND_TEXT_LABEL_POSITION,
+  redrawTextBoundingBox,
+} from "./textElement";
+
+import { LinearElementEditor } from "./linearElementEditor";
+
+import { getCommonBounds } from "./bounds";
+
+import { Scene } from "./Scene";
+
+import type {
+  ExcalidrawArrowElement,
+  ExcalidrawBindableElement,
+  ExcalidrawElement,
+  ExcalidrawFrameElement,
+  ExcalidrawFreeDrawElement,
+  ExcalidrawGenericElement,
+  ExcalidrawIframeLikeElement,
+  ExcalidrawImageElement,
+  ExcalidrawLinearElement,
+  ExcalidrawMagicFrameElement,
+  ExcalidrawSelectionElement,
+  ExcalidrawTextElement,
+  FileId,
+  FontFamilyValues,
+  NonDeleted,
+  NonDeletedExcalidrawElement,
+  NonDeletedSceneElementsMap,
+  Ordered,
+  TextAlign,
+  VerticalAlign,
+  ExcalidrawStickyNoteElement,
+} from "./types";
+
+/**
+ * Options for elements generated from a skeleton fragment (bound labels and
+ * binding endpoints). Such elements are always constructed fresh, hence they
+ * never carry a creation time of their own.
+ */
+type FragmentConstructorOpts = MarkOptional<
+  Omit<ElementConstructorOpts, "created">,
+  "x" | "y"
+>;
+
+export type ValidLinearElement = {
+  type: "arrow" | "line";
+  x: number;
+  y: number;
+  label?: {
+    text: string;
+    fontSize?: number;
+    fontFamily?: FontFamilyValues;
+    textAlign?: TextAlign;
+    verticalAlign?: VerticalAlign;
+  } & FragmentConstructorOpts;
+  end?:
+    | (
+        | (
+            | {
+                type: Exclude<
+                  ExcalidrawBindableElement["type"],
+                  | "image"
+                  | "text"
+                  | "frame"
+                  | "magicframe"
+                  | "embeddable"
+                  | "iframe"
+                >;
+                id?: ExcalidrawGenericElement["id"];
+              }
+            | {
+                id: ExcalidrawGenericElement["id"];
+                type?: Exclude<
+                  ExcalidrawBindableElement["type"],
+                  | "image"
+                  | "text"
+                  | "frame"
+                  | "magicframe"
+                  | "embeddable"
+                  | "iframe"
+                >;
+              }
+          )
+        | ((
+            | {
+                type: "text";
+                text: string;
+              }
+            | {
+                type?: "text";
+                id: ExcalidrawTextElement["id"];
+                text: string;
+              }
+          ) &
+            Partial<Omit<ExcalidrawTextElement, "created">>)
+      ) &
+        FragmentConstructorOpts;
+  start?:
+    | (
+        | (
+            | {
+                type: Exclude<
+                  ExcalidrawBindableElement["type"],
+                  | "image"
+                  | "text"
+                  | "frame"
+                  | "magicframe"
+                  | "embeddable"
+                  | "iframe"
+                >;
+                id?: ExcalidrawGenericElement["id"];
+              }
+            | {
+                id: ExcalidrawGenericElement["id"];
+                type?: Exclude<
+                  ExcalidrawBindableElement["type"],
+                  | "image"
+                  | "text"
+                  | "frame"
+                  | "magicframe"
+                  | "embeddable"
+                  | "iframe"
+                >;
+              }
+          )
+        | ((
+            | {
+                type: "text";
+                text: string;
+              }
+            | {
+                type?: "text";
+                id: ExcalidrawTextElement["id"];
+                text: string;
+              }
+          ) &
+            Partial<Omit<ExcalidrawTextElement, "created">>)
+      ) &
+        FragmentConstructorOpts;
+} & Partial<ExcalidrawLinearElement>;
+
+export type ValidContainer =
+  | {
+      type: Exclude<ExcalidrawGenericElement["type"], "selection">;
+      id?: ExcalidrawGenericElement["id"];
+      label?: {
+        text: string;
+        fontSize?: number;
+        fontFamily?: FontFamilyValues;
+        textAlign?: TextAlign;
+        verticalAlign?: VerticalAlign;
+      } & FragmentConstructorOpts;
+    } & ElementConstructorOpts;
+
+/**
+ * A sticky note: an always-filled note whose label auto-fits. `label.fontSize`
+ * is the font ceiling the fit shrinks from; the note grows past its height
+ * (kept as `baseHeight`) only once the label hits the minimum font size.
+ */
+export type ValidStickyNote = {
+  type: "stickynote";
+  id?: ExcalidrawStickyNoteElement["id"];
+  label?: Extract<ValidContainer, { label?: unknown }>["label"];
+} & ElementConstructorOpts &
+  Partial<Pick<ExcalidrawStickyNoteElement, "baseHeight">>;
+
+export type ExcalidrawElementSkeleton =
+  | Extract<
+      Exclude<ExcalidrawElement, ExcalidrawSelectionElement>,
+      ExcalidrawIframeLikeElement | ExcalidrawFreeDrawElement
+    >
+  | ({
+      type: Extract<ExcalidrawLinearElement["type"], "line">;
+      x: number;
+      y: number;
+    } & Partial<ExcalidrawLinearElement>)
+  | ValidContainer
+  | ValidStickyNote
+  | ValidLinearElement
+  | ({
+      type: "text";
+      text: string;
+      x: number;
+      y: number;
+      id?: ExcalidrawTextElement["id"];
+    } & Partial<ExcalidrawTextElement>)
+  | ({
+      type: Extract<ExcalidrawImageElement["type"], "image">;
+      x: number;
+      y: number;
+      fileId: FileId;
+    } & Partial<ExcalidrawImageElement>)
+  | ({
+      type: "frame";
+      children: readonly ExcalidrawElement["id"][];
+      name?: string;
+    } & Partial<ExcalidrawFrameElement>)
+  | ({
+      type: "magicframe";
+      children: readonly ExcalidrawElement["id"][];
+      name?: string;
+    } & Partial<ExcalidrawMagicFrameElement>);
+
+const DEFAULT_LINEAR_ELEMENT_PROPS = {
+  width: 100,
+  height: 0,
+};
+
+const DEFAULT_DIMENSION = 100;
+
+const bindTextToContainer = (
+  container: ExcalidrawElement,
+  textProps: { text: string } & FragmentConstructorOpts,
+  scene: Scene,
+) => {
+  // a note and its label share one ink: a label that sets its own color
+  // gives it to the note (the footer paints with it); transparent falls
+  // back to the note's
+  const stickyInk = isStickyNoteElement(container)
+    ? normalizeStickyNoteStrokeColor(
+        textProps.strokeColor && !isTransparent(textProps.strokeColor)
+          ? textProps.strokeColor
+          : container.strokeColor,
+      )
+    : null;
+  const textElement: ExcalidrawTextElement = newTextElement({
+    x: 0,
+    y: 0,
+    textAlign: TEXT_ALIGN.CENTER,
+    verticalAlign: VERTICAL_ALIGN.MIDDLE,
+    ...textProps,
+    containerId: container.id,
+    strokeColor: stickyInk ?? (textProps.strokeColor || container.strokeColor),
+    labelPosition: isArrowElement(container)
+      ? DEFAULT_BOUND_TEXT_LABEL_POSITION
+      : null,
+  });
+
+  Object.assign(container, {
+    boundElements: (container.boundElements || []).concat({
+      type: "text",
+      id: textElement.id,
+    }),
+    ...(stickyInk && stickyInk !== container.strokeColor
+      ? { strokeColor: stickyInk }
+      : null),
+  });
+
+  redrawTextBoundingBox(textElement, container, scene);
+
+  return [container, textElement] as const;
+};
+
+const bindLinearElementToElement = (
+  linearElement: NonDeleted<ExcalidrawArrowElement>,
+  start: ValidLinearElement["start"],
+  end: ValidLinearElement["end"],
+  elementStore: ElementStore,
+  scene: Scene,
+): {
+  linearElement: ExcalidrawLinearElement;
+  startBoundElement?: ExcalidrawElement;
+  endBoundElement?: ExcalidrawElement;
+} => {
+  let startBoundElement;
+  let endBoundElement;
+
+  Object.assign(linearElement, {
+    startBinding: linearElement?.startBinding || null,
+    endBinding: linearElement.endBinding || null,
+  });
+
+  if (start) {
+    const width = start?.width ?? DEFAULT_DIMENSION;
+    const height = start?.height ?? DEFAULT_DIMENSION;
+
+    let existingElement;
+    if (start.id) {
+      existingElement = elementStore.getElement(start.id);
+      if (!existingElement) {
+        console.error(`No element for start binding with id ${start.id} found`);
+      }
+    }
+
+    const startX = start.x || linearElement.x - width;
+    const startY = start.y || linearElement.y - height / 2;
+    const startType = existingElement ? existingElement.type : start.type;
+
+    if (startType) {
+      if (startType === "text") {
+        let text = "";
+        if (existingElement && existingElement.type === "text") {
+          text = existingElement.text;
+        } else if (start.type === "text") {
+          text = start.text;
+        }
+        if (!text) {
+          console.error(
+            `No text found for start binding text element for ${linearElement.id}`,
+          );
+        }
+        startBoundElement = newTextElement({
+          x: startX,
+          y: startY,
+          type: "text",
+          ...existingElement,
+          ...start,
+          text,
+        });
+        // to position the text correctly when coordinates not provided
+        Object.assign(startBoundElement, {
+          x: start.x || linearElement.x - startBoundElement.width,
+          y: start.y || linearElement.y - startBoundElement.height / 2,
+        });
+      } else {
+        switch (startType) {
+          case "rectangle":
+          case "ellipse":
+          case "diamond": {
+            startBoundElement = newElement({
+              x: startX,
+              y: startY,
+              width,
+              height,
+              ...existingElement,
+              ...start,
+              type: startType,
+            });
+            break;
+          }
+          default: {
+            assertNever(
+              linearElement as never,
+              `Unhandled element start type "${start.type}"`,
+              true,
+            );
+          }
+        }
+      }
+
+      bindBindingElement(
+        linearElement,
+        startBoundElement as NonDeleted<ExcalidrawBindableElement>,
+        "orbit",
+        "start",
+        scene,
+      );
+    }
+  }
+  if (end) {
+    const height = end?.height ?? DEFAULT_DIMENSION;
+    const width = end?.width ?? DEFAULT_DIMENSION;
+
+    let existingElement;
+    if (end.id) {
+      existingElement = elementStore.getElement(end.id);
+      if (!existingElement) {
+        console.error(`No element for end binding with id ${end.id} found`);
+      }
+    }
+    const endX = end.x || linearElement.x + linearElement.width;
+    const endY = end.y || linearElement.y - height / 2;
+    const endType = existingElement ? existingElement.type : end.type;
+
+    if (endType) {
+      if (endType === "text") {
+        let text = "";
+        if (existingElement && existingElement.type === "text") {
+          text = existingElement.text;
+        } else if (end.type === "text") {
+          text = end.text;
+        }
+
+        if (!text) {
+          console.error(
+            `No text found for end binding text element for ${linearElement.id}`,
+          );
+        }
+        endBoundElement = newTextElement({
+          x: endX,
+          y: endY,
+          type: "text",
+          ...existingElement,
+          ...end,
+          text,
+        });
+        // to position the text correctly when coordinates not provided
+        Object.assign(endBoundElement, {
+          y: end.y || linearElement.y - endBoundElement.height / 2,
+        });
+      } else {
+        switch (endType) {
+          case "rectangle":
+          case "ellipse":
+          case "diamond": {
+            endBoundElement = newElement({
+              x: endX,
+              y: endY,
+              width,
+              height,
+              ...existingElement,
+              ...end,
+              type: endType,
+            });
+            break;
+          }
+          default: {
+            assertNever(
+              linearElement as never,
+              `Unhandled element end type "${endType}"`,
+              true,
+            );
+          }
+        }
+      }
+
+      bindBindingElement(
+        linearElement,
+        endBoundElement as NonDeleted<ExcalidrawBindableElement>,
+        "orbit",
+        "end",
+        scene,
+      );
+    }
+  }
+
+  // Safe check to early return for single point
+  if (linearElement.points.length < 2) {
+    return {
+      linearElement,
+      startBoundElement,
+      endBoundElement,
+    };
+  }
+
+  // Update start/end points by 0.5 so bindings don't overlap with start/end bound element coordinates.
+  const endPointIndex = linearElement.points.length - 1;
+  const delta = 0.5;
+
+  const newPoints = cloneJSON<readonly LocalPoint[]>(linearElement.points);
+
+  // left to right so shift the arrow towards right
+  if (
+    linearElement.points[endPointIndex][0] >
+    linearElement.points[endPointIndex - 1][0]
+  ) {
+    newPoints[0][0] = delta;
+    newPoints[endPointIndex][0] -= delta;
+  }
+
+  // right to left so shift the arrow towards left
+  if (
+    linearElement.points[endPointIndex][0] <
+    linearElement.points[endPointIndex - 1][0]
+  ) {
+    newPoints[0][0] = -delta;
+    newPoints[endPointIndex][0] += delta;
+  }
+  // top to bottom so shift the arrow towards top
+  if (
+    linearElement.points[endPointIndex][1] >
+    linearElement.points[endPointIndex - 1][1]
+  ) {
+    newPoints[0][1] = delta;
+    newPoints[endPointIndex][1] -= delta;
+  }
+
+  // bottom to top so shift the arrow towards bottom
+  if (
+    linearElement.points[endPointIndex][1] <
+    linearElement.points[endPointIndex - 1][1]
+  ) {
+    newPoints[0][1] = -delta;
+    newPoints[endPointIndex][1] += delta;
+  }
+
+  Object.assign(
+    linearElement,
+    LinearElementEditor.getNormalizeElementPointsAndCoords({
+      ...linearElement,
+      points: newPoints,
+    }),
+  );
+
+  return {
+    linearElement,
+    startBoundElement,
+    endBoundElement,
+  };
+};
+
+class ElementStore {
+  excalidrawElements = new Map<string, ExcalidrawElement>();
+
+  add = (ele?: ExcalidrawElement) => {
+    if (!ele) {
+      return;
+    }
+
+    this.excalidrawElements.set(ele.id, ele);
+  };
+
+  getElements = () => {
+    // programmatically created elements are always non-deleted
+    return syncInvalidIndices(
+      Array.from(this.excalidrawElements.values()),
+    ) as Ordered<NonDeletedExcalidrawElement>[];
+  };
+
+  getElementsMap = () => {
+    return toBrandedType<NonDeletedSceneElementsMap>(
+      arrayToMap(this.getElements()),
+    );
+  };
+
+  getElement = (id: string) => {
+    return this.excalidrawElements.get(id);
+  };
+}
+
+export const convertToExcalidrawElements = (
+  elementsSkeleton: ExcalidrawElementSkeleton[] | null,
+  opts?: { regenerateIds: boolean },
+) => {
+  if (!elementsSkeleton) {
+    return [];
+  }
+  const elements = cloneJSON(elementsSkeleton);
+  const elementStore = new ElementStore();
+  const elementsWithIds = new Map<string, ExcalidrawElementSkeleton>();
+  const oldToNewElementIdMap = new Map<string, string>();
+
+  // Create individual elements
+  // regenerated ids mean new instances, hence a fresh creation time as well
+  const created = getUpdatedTimestamp();
+
+  for (const element of elements) {
+    let excalidrawElement: ExcalidrawElement;
+    const originalId = element.id;
+    if (opts?.regenerateIds !== false) {
+      Object.assign(element, { id: randomId(), created });
+    }
+
+    switch (element.type) {
+      case "rectangle":
+      case "ellipse":
+      case "diamond": {
+        const width =
+          element?.label?.text && element.width === undefined
+            ? 0
+            : element?.width || DEFAULT_DIMENSION;
+        const height =
+          element?.label?.text && element.height === undefined
+            ? 0
+            : element?.height || DEFAULT_DIMENSION;
+        excalidrawElement = newElement({
+          ...element,
+          width,
+          height,
+        });
+
+        break;
+      }
+      case "line": {
+        const width = element.width || DEFAULT_LINEAR_ELEMENT_PROPS.width;
+        const height = element.height || DEFAULT_LINEAR_ELEMENT_PROPS.height;
+        excalidrawElement = newLinearElement({
+          width,
+          height,
+          points: [pointFrom(0, 0), pointFrom(width, height)],
+          ...element,
+        });
+
+        break;
+      }
+      case "arrow": {
+        const width = element.width || DEFAULT_LINEAR_ELEMENT_PROPS.width;
+        const height = element.height || DEFAULT_LINEAR_ELEMENT_PROPS.height;
+        excalidrawElement = newArrowElement({
+          width,
+          height,
+          endArrowhead: "arrow",
+          points: [pointFrom(0, 0), pointFrom(width, height)],
+          ...element,
+          type: "arrow",
+        });
+
+        Object.assign(
+          excalidrawElement,
+          getSizeFromPoints(excalidrawElement.points),
+        );
+        break;
+      }
+      case "text": {
+        const fontFamily = element?.fontFamily || DEFAULT_FONT_FAMILY;
+        const fontSize = element?.fontSize || DEFAULT_FONT_SIZE;
+        const lineHeight = element?.lineHeight || getLineHeight(fontFamily);
+        const text = element.text ?? "";
+        const normalizedText = normalizeText(text);
+        const metrics = measureText(
+          normalizedText,
+          getFontString({ fontFamily, fontSize }),
+          lineHeight,
+        );
+
+        excalidrawElement = newTextElement({
+          width: metrics.width,
+          height: metrics.height,
+          fontFamily,
+          fontSize,
+          ...element,
+        });
+        break;
+      }
+      case "image": {
+        excalidrawElement = newImageElement({
+          width: element?.width || DEFAULT_DIMENSION,
+          height: element?.height || DEFAULT_DIMENSION,
+          ...element,
+        });
+
+        break;
+      }
+      case "frame": {
+        excalidrawElement = newFrameElement({
+          x: 0,
+          y: 0,
+          ...element,
+        });
+        break;
+      }
+      case "magicframe": {
+        excalidrawElement = newMagicFrameElement({
+          x: 0,
+          y: 0,
+          ...element,
+        });
+        break;
+      }
+      case "freedraw": {
+        excalidrawElement = newFreeDrawElement({ ...element });
+        break;
+      }
+      case "iframe": {
+        excalidrawElement = newIframeElement({ ...element });
+        break;
+      }
+      case "stickynote": {
+        const width = element.width || DEFAULT_STICKY_NOTE_SIZE;
+        const height = element.height || DEFAULT_STICKY_NOTE_SIZE;
+        // finalized geometry (min size, baseHeight ≤ height) — only a
+        // pointer-down draft is exempt from it
+        excalidrawElement = normalizeStickyNoteGeometry(
+          newStickyNoteElement({
+            ...element,
+            type: "stickynote",
+            width,
+            height,
+            baseHeight: element.baseHeight ?? height,
+          }),
+        );
+        break;
+      }
+      case "embeddable": {
+        excalidrawElement = newEmbeddableElement({ ...element });
+        break;
+      }
+
+      default: {
+        excalidrawElement = element;
+        assertNever(
+          element,
+          `Unhandled element type "${(element as any).type}"`,
+          true,
+        );
+      }
+    }
+    const existingElement = elementStore.getElement(excalidrawElement.id);
+    if (existingElement) {
+      console.error(`Duplicate id found for ${excalidrawElement.id}`);
+    } else {
+      elementStore.add(excalidrawElement);
+      elementsWithIds.set(excalidrawElement.id, element);
+      if (originalId) {
+        oldToNewElementIdMap.set(originalId, excalidrawElement.id);
+      }
+    }
+  }
+
+  const elementsMap = elementStore.getElementsMap();
+  // we don't have a real scene, so we just use a temp scene to query and mutate elements
+  const scene = new Scene(elementsMap);
+
+  // Add labels and arrow bindings
+  for (const [id, element] of elementsWithIds) {
+    const excalidrawElement = elementStore.getElement(id)!;
+
+    switch (element.type) {
+      case "rectangle":
+      case "ellipse":
+      case "diamond":
+      case "stickynote":
+      case "arrow": {
+        if (element.label?.text) {
+          // for a sticky note this runs the sticky fit (via
+          // `redrawTextBoundingBox`): the label's font size becomes its ceiling
+          let [container, text] = bindTextToContainer(
+            excalidrawElement,
+            element?.label,
+            scene,
+          );
+          elementStore.add(container);
+          elementStore.add(text);
+
+          if (isArrowElement(container)) {
+            const originalStart =
+              element.type === "arrow" ? element?.start : undefined;
+            const originalEnd =
+              element.type === "arrow" ? element?.end : undefined;
+            if (originalStart && originalStart.id) {
+              const newStartId = oldToNewElementIdMap.get(originalStart.id);
+              if (newStartId) {
+                Object.assign(originalStart, { id: newStartId });
+              }
+            }
+            if (originalEnd && originalEnd.id) {
+              const newEndId = oldToNewElementIdMap.get(originalEnd.id);
+              if (newEndId) {
+                Object.assign(originalEnd, { id: newEndId });
+              }
+            }
+            const { linearElement, startBoundElement, endBoundElement } =
+              bindLinearElementToElement(
+                container as NonDeleted<ExcalidrawArrowElement>,
+                originalStart,
+                originalEnd,
+                elementStore,
+                scene,
+              );
+            container = linearElement;
+            elementStore.add(linearElement);
+            elementStore.add(startBoundElement);
+            elementStore.add(endBoundElement);
+          }
+        } else {
+          switch (element.type) {
+            case "arrow": {
+              const { start, end } = element;
+              if (start && start.id) {
+                const newStartId = oldToNewElementIdMap.get(start.id);
+                Object.assign(start, { id: newStartId });
+              }
+              if (end && end.id) {
+                const newEndId = oldToNewElementIdMap.get(end.id);
+                Object.assign(end, { id: newEndId });
+              }
+              const { linearElement, startBoundElement, endBoundElement } =
+                bindLinearElementToElement(
+                  excalidrawElement as NonDeleted<ExcalidrawArrowElement>,
+                  start,
+                  end,
+                  elementStore,
+                  scene,
+                );
+
+              elementStore.add(linearElement);
+              elementStore.add(startBoundElement);
+              elementStore.add(endBoundElement);
+              break;
+            }
+          }
+        }
+        break;
+      }
+    }
+  }
+
+  // Once all the excalidraw elements are created, we can add frames since we
+  // need to calculate coordinates and dimensions of frame which is possible after all
+  // frame children are processed.
+  for (const [id, element] of elementsWithIds) {
+    if (element.type !== "frame" && element.type !== "magicframe") {
+      continue;
+    }
+    const frame = elementStore.getElement(id);
+
+    if (!frame) {
+      throw new Error(`Excalidraw element with id ${id} doesn't exist`);
+    }
+    const childrenElements: ExcalidrawElement[] = [];
+
+    element.children.forEach((id) => {
+      const newElementId = oldToNewElementIdMap.get(id);
+      if (!newElementId) {
+        throw new Error(`Element with ${id} wasn't mapped correctly`);
+      }
+
+      const elementInFrame = elementStore.getElement(newElementId);
+      if (!elementInFrame) {
+        throw new Error(`Frame element with id ${newElementId} doesn't exist`);
+      }
+      Object.assign(elementInFrame, { frameId: frame.id });
+
+      elementInFrame?.boundElements?.forEach((boundElement) => {
+        const ele = elementStore.getElement(boundElement.id);
+        if (!ele) {
+          throw new Error(
+            `Bound element with id ${boundElement.id} doesn't exist`,
+          );
+        }
+        Object.assign(ele, { frameId: frame.id });
+        childrenElements.push(ele);
+      });
+
+      childrenElements.push(elementInFrame);
+    });
+
+    let [minX, minY, maxX, maxY] = getCommonBounds(childrenElements);
+
+    const PADDING = 10;
+    minX = minX - PADDING;
+    minY = minY - PADDING;
+    maxX = maxX + PADDING;
+    maxY = maxY + PADDING;
+
+    const frameX = frame?.x || minX;
+    const frameY = frame?.y || minY;
+    const frameWidth = frame?.width || maxX - minX;
+    const frameHeight = frame?.height || maxY - minY;
+
+    Object.assign(frame, {
+      x: frameX,
+      y: frameY,
+      width: frameWidth,
+      height: frameHeight,
+    });
+    if (
+      isDevEnv() &&
+      element.children.length &&
+      (frame?.x || frame?.y || frame?.width || frame?.height)
+    ) {
+      console.info(
+        "User provided frame attributes are being considered, if you find this inaccurate, please remove any of the attributes - x, y, width and height so frame coordinates and dimensions are calculated automatically",
+      );
+    }
+  }
+
+  return elementStore.getElements();
+};

packages/element/src/transformHandles.ts

@@ -0,0 +1,354 @@
+import {
+  DEFAULT_TRANSFORM_HANDLE_SPACING,
+  type EditorInterface,
+} from "@excalidraw/common";
+
+import { pointFrom, pointRotateRads } from "@excalidraw/math";
+
+import type { Radians } from "@excalidraw/math";
+
+import type {
+  InteractiveCanvasAppState,
+  Zoom,
+} from "@excalidraw/excalidraw/types";
+import type { Bounds } from "@excalidraw/common";
+
+import { getElementAbsoluteCoords } from "./bounds";
+import {
+  isElbowArrow,
+  isFrameLikeElement,
+  isImageElement,
+  isLinearElement,
+} from "./typeChecks";
+
+import type {
+  ElementsMap,
+  ExcalidrawElement,
+  NonDeletedExcalidrawElement,
+  PointerType,
+} from "./types";
+
+export type TransformHandleDirection =
+  | "n"
+  | "s"
+  | "w"
+  | "e"
+  | "nw"
+  | "ne"
+  | "sw"
+  | "se";
+
+export type TransformHandleType = TransformHandleDirection | "rotation";
+
+export type TransformHandle = Bounds;
+export type TransformHandles = Partial<{
+  [T in TransformHandleType]: TransformHandle;
+}>;
+export type MaybeTransformHandleType = TransformHandleType | false;
+
+const transformHandleSizes: { [k in PointerType]: number } = {
+  mouse: 8,
+  pen: 16,
+  touch: 28,
+};
+
+const ROTATION_RESIZE_HANDLE_GAP = 16;
+
+export const DEFAULT_OMIT_SIDES = {
+  e: true,
+  s: true,
+  n: true,
+  w: true,
+};
+
+export const OMIT_SIDES_FOR_MULTIPLE_ELEMENTS = {
+  e: true,
+  s: true,
+  n: true,
+  w: true,
+};
+
+export const OMIT_SIDES_FOR_FRAME = {
+  e: true,
+  s: true,
+  n: true,
+  w: true,
+  rotation: true,
+};
+
+const OMIT_SIDES_FOR_LINE_SLASH = {
+  e: true,
+  s: true,
+  n: true,
+  w: true,
+  nw: true,
+  se: true,
+};
+
+const OMIT_SIDES_FOR_LINE_BACKSLASH = {
+  e: true,
+  s: true,
+  n: true,
+  w: true,
+};
+
+const generateTransformHandle = (
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  cx: number,
+  cy: number,
+  angle: Radians,
+): TransformHandle => {
+  const [xx, yy] = pointRotateRads(
+    pointFrom(x + width / 2, y + height / 2),
+    pointFrom(cx, cy),
+    angle,
+  );
+  return [xx - width / 2, yy - height / 2, width, height];
+};
+
+export const canResizeFromSides = (editorInterface: EditorInterface) => {
+  if (
+    editorInterface.formFactor === "phone" &&
+    editorInterface.userAgent.isMobileDevice
+  ) {
+    return false;
+  }
+
+  return true;
+};
+
+export const getOmitSidesForEditorInterface = (
+  editorInterface: EditorInterface,
+) => {
+  if (canResizeFromSides(editorInterface)) {
+    return DEFAULT_OMIT_SIDES;
+  }
+
+  return {};
+};
+
+export const getTransformHandlesFromCoords = (
+  [x1, y1, x2, y2, cx, cy]: [number, number, number, number, number, number],
+  angle: Radians,
+  zoom: Zoom,
+  pointerType: PointerType,
+  omitSides: { [T in TransformHandleType]?: boolean } = {},
+  margin = 4,
+  spacing = DEFAULT_TRANSFORM_HANDLE_SPACING,
+): TransformHandles => {
+  const size = transformHandleSizes[pointerType];
+  const handleWidth = size / zoom.value;
+  const handleHeight = size / zoom.value;
+
+  const handleMarginX = size / zoom.value;
+  const handleMarginY = size / zoom.value;
+
+  const width = x2 - x1;
+  const height = y2 - y1;
+  const dashedLineMargin = margin / zoom.value;
+  const centeringOffset = (size - spacing * 2) / (2 * zoom.value);
+
+  const transformHandles: TransformHandles = {
+    nw: omitSides.nw
+      ? undefined
+      : generateTransformHandle(
+          x1 - dashedLineMargin - handleMarginX + centeringOffset,
+          y1 - dashedLineMargin - handleMarginY + centeringOffset,
+          handleWidth,
+          handleHeight,
+          cx,
+          cy,
+          angle,
+        ),
+    ne: omitSides.ne
+      ? undefined
+      : generateTransformHandle(
+          x2 + dashedLineMargin - centeringOffset,
+          y1 - dashedLineMargin - handleMarginY + centeringOffset,
+          handleWidth,
+          handleHeight,
+          cx,
+          cy,
+          angle,
+        ),
+    sw: omitSides.sw
+      ? undefined
+      : generateTransformHandle(
+          x1 - dashedLineMargin - handleMarginX + centeringOffset,
+          y2 + dashedLineMargin - centeringOffset,
+          handleWidth,
+          handleHeight,
+          cx,
+          cy,
+          angle,
+        ),
+    se: omitSides.se
+      ? undefined
+      : generateTransformHandle(
+          x2 + dashedLineMargin - centeringOffset,
+          y2 + dashedLineMargin - centeringOffset,
+          handleWidth,
+          handleHeight,
+          cx,
+          cy,
+          angle,
+        ),
+    rotation: omitSides.rotation
+      ? undefined
+      : generateTransformHandle(
+          x1 + width / 2 - handleWidth / 2,
+          y1 -
+            dashedLineMargin -
+            handleMarginY +
+            centeringOffset -
+            ROTATION_RESIZE_HANDLE_GAP / zoom.value,
+          handleWidth,
+          handleHeight,
+          cx,
+          cy,
+          angle,
+        ),
+  };
+
+  // We only want to show height handles (all cardinal directions)  above a certain size
+  // Note: we render using "mouse" size so we should also use "mouse" size for this check
+  const minimumSizeForEightHandles =
+    (5 * transformHandleSizes.mouse) / zoom.value;
+  if (Math.abs(width) > minimumSizeForEightHandles) {
+    if (!omitSides.n) {
+      transformHandles.n = generateTransformHandle(
+        x1 + width / 2 - handleWidth / 2,
+        y1 - dashedLineMargin - handleMarginY + centeringOffset,
+        handleWidth,
+        handleHeight,
+        cx,
+        cy,
+        angle,
+      );
+    }
+    if (!omitSides.s) {
+      transformHandles.s = generateTransformHandle(
+        x1 + width / 2 - handleWidth / 2,
+        y2 + dashedLineMargin - centeringOffset,
+        handleWidth,
+        handleHeight,
+        cx,
+        cy,
+        angle,
+      );
+    }
+  }
+  if (Math.abs(height) > minimumSizeForEightHandles) {
+    if (!omitSides.w) {
+      transformHandles.w = generateTransformHandle(
+        x1 - dashedLineMargin - handleMarginX + centeringOffset,
+        y1 + height / 2 - handleHeight / 2,
+        handleWidth,
+        handleHeight,
+        cx,
+        cy,
+        angle,
+      );
+    }
+    if (!omitSides.e) {
+      transformHandles.e = generateTransformHandle(
+        x2 + dashedLineMargin - centeringOffset,
+        y1 + height / 2 - handleHeight / 2,
+        handleWidth,
+        handleHeight,
+        cx,
+        cy,
+        angle,
+      );
+    }
+  }
+
+  return transformHandles;
+};
+
+export const getTransformHandles = (
+  element: ExcalidrawElement,
+  zoom: Zoom,
+  elementsMap: ElementsMap,
+  pointerType: PointerType = "mouse",
+  omitSides: { [T in TransformHandleType]?: boolean } = DEFAULT_OMIT_SIDES,
+): TransformHandles => {
+  // so that when locked element is selected (especially when you toggle lock
+  // via keyboard) the locked element is visually distinct, indicating
+  // you can't move/resize
+  if (
+    element.locked ||
+    // Elbow arrows cannot be rotated
+    isElbowArrow(element)
+  ) {
+    return {};
+  }
+
+  if (element.type === "freedraw" || isLinearElement(element)) {
+    if (element.points.length === 2) {
+      // only check the last point because starting point is always (0,0)
+      const [, p1] = element.points;
+      if (p1[0] === 0 || p1[1] === 0) {
+        omitSides = OMIT_SIDES_FOR_LINE_BACKSLASH;
+      } else if (p1[0] > 0 && p1[1] < 0) {
+        omitSides = OMIT_SIDES_FOR_LINE_SLASH;
+      } else if (p1[0] > 0 && p1[1] > 0) {
+        omitSides = OMIT_SIDES_FOR_LINE_BACKSLASH;
+      } else if (p1[0] < 0 && p1[1] > 0) {
+        omitSides = OMIT_SIDES_FOR_LINE_SLASH;
+      } else if (p1[0] < 0 && p1[1] < 0) {
+        omitSides = OMIT_SIDES_FOR_LINE_BACKSLASH;
+      }
+    }
+  } else if (isFrameLikeElement(element)) {
+    omitSides = {
+      ...omitSides,
+      rotation: true,
+    };
+  }
+  const margin = isLinearElement(element)
+    ? DEFAULT_TRANSFORM_HANDLE_SPACING + 8
+    : isImageElement(element)
+    ? 0
+    : DEFAULT_TRANSFORM_HANDLE_SPACING;
+  return getTransformHandlesFromCoords(
+    getElementAbsoluteCoords(element, elementsMap, true),
+    element.angle,
+    zoom,
+    pointerType,
+    omitSides,
+    margin,
+    isImageElement(element) ? 0 : undefined,
+  );
+};
+
+export const hasBoundingBox = (
+  elements: readonly NonDeletedExcalidrawElement[],
+  appState: InteractiveCanvasAppState,
+  editorInterface: EditorInterface,
+) => {
+  if (
+    appState.selectedLinearElement?.isEditing ||
+    appState.selectedLinearElement?.isDragging
+  ) {
+    return false;
+  }
+  if (elements.length > 1) {
+    return true;
+  }
+  const element = elements[0];
+  if (isElbowArrow(element)) {
+    // Elbow arrows cannot be resized as single selected elements
+    return false;
+  }
+  if (!isLinearElement(element)) {
+    return true;
+  }
+
+  // on mobile/tablet we currently don't show bbox because of resize issues
+  // (also prob best for simplicity's sake)
+  return element.points.length > 2 && !editorInterface.userAgent.isMobileDevice;
+};

packages/element/src/typeChecks.ts

@@ -0,0 +1,432 @@
+import { ROUNDNESS, assertNever } from "@excalidraw/common";
+
+import { pointsEqual } from "@excalidraw/math";
+
+import type { ElementOrToolType } from "@excalidraw/excalidraw/types";
+
+import type { MarkNonNullable } from "@excalidraw/common/utility-types";
+
+import type {
+  ExcalidrawElement,
+  ExcalidrawTextElement,
+  ExcalidrawEmbeddableElement,
+  ExcalidrawLinearElement,
+  ExcalidrawBindableElement,
+  ExcalidrawFreeDrawElement,
+  InitializedExcalidrawImageElement,
+  ExcalidrawImageElement,
+  ExcalidrawTextElementWithContainer,
+  ExcalidrawTextContainer,
+  ExcalidrawFrameElement,
+  RoundnessType,
+  ExcalidrawFrameLikeElement,
+  ExcalidrawElementType,
+  ExcalidrawIframeElement,
+  ExcalidrawIframeLikeElement,
+  ExcalidrawMagicFrameElement,
+  ExcalidrawArrowElement,
+  ExcalidrawElbowArrowElement,
+  ExcalidrawLineElement,
+  ExcalidrawFlowchartNodeElement,
+  ExcalidrawLinearElementSubType,
+  ExcalidrawStickyNoteElement,
+} from "./types";
+
+export const isInitializedImageElement = <T extends ExcalidrawElement>(
+  element: T | null,
+): element is T & InitializedExcalidrawImageElement => {
+  return !!element && element.type === "image" && !!element.fileId;
+};
+
+export const isImageElement = <T extends ExcalidrawElement>(
+  element: T | null,
+): element is T & ExcalidrawImageElement => {
+  return !!element && element.type === "image";
+};
+
+export const isEmbeddableElement = <T extends ExcalidrawElement>(
+  element: T | null | undefined,
+): element is T & ExcalidrawEmbeddableElement => {
+  return !!element && element.type === "embeddable";
+};
+
+export const isIframeElement = <T extends ExcalidrawElement>(
+  element: T | null,
+): element is T & ExcalidrawIframeElement => {
+  return !!element && element.type === "iframe";
+};
+
+export const isIframeLikeElement = <T extends ExcalidrawElement>(
+  element: T | null,
+): element is T & ExcalidrawIframeLikeElement => {
+  return (
+    !!element && (element.type === "iframe" || element.type === "embeddable")
+  );
+};
+
+export const isTextElement = <T extends ExcalidrawElement>(
+  element: T | null,
+): element is T & ExcalidrawTextElement => {
+  return element != null && element.type === "text";
+};
+
+export const isStickyNoteElement = <T extends ExcalidrawElement>(
+  element: T | null | undefined,
+): element is T & ExcalidrawStickyNoteElement => {
+  return element != null && element.type === "stickynote";
+};
+
+export const isFrameElement = <T extends ExcalidrawElement>(
+  element: T | null,
+): element is T & ExcalidrawFrameElement => {
+  return element != null && element.type === "frame";
+};
+
+export const isMagicFrameElement = <T extends ExcalidrawElement>(
+  element: T | null,
+): element is T & ExcalidrawMagicFrameElement => {
+  return element != null && element.type === "magicframe";
+};
+
+export const isFrameLikeElement = <T extends ExcalidrawElement>(
+  element: T | null,
+): element is T & ExcalidrawFrameLikeElement => {
+  return (
+    element != null &&
+    (element.type === "frame" || element.type === "magicframe")
+  );
+};
+
+export const isFreeDrawElement = <T extends ExcalidrawElement>(
+  element?: T | null,
+): element is T & ExcalidrawFreeDrawElement => {
+  return element != null && isFreeDrawElementType(element.type);
+};
+
+export const isFreeDrawElementType = (
+  elementType: ExcalidrawElementType,
+): boolean => {
+  return elementType === "freedraw";
+};
+
+export const isLinearElement = <T extends ExcalidrawElement>(
+  element?: T | null,
+): element is T & ExcalidrawLinearElement => {
+  return element != null && isLinearElementType(element.type);
+};
+
+export const isLineElement = <T extends ExcalidrawElement>(
+  element?: T | null,
+): element is T & ExcalidrawLineElement => {
+  return element != null && element.type === "line";
+};
+
+export const isArrowElement = <T extends ExcalidrawElement>(
+  element?: T | null,
+): element is T & ExcalidrawArrowElement => {
+  return element != null && element.type === "arrow";
+};
+
+export const isElbowArrow = <T extends ExcalidrawElement>(
+  element?: T,
+): element is T & ExcalidrawElbowArrowElement => {
+  return isArrowElement(element) && element.elbowed;
+};
+
+/**
+ * sharp or curved arrow, but not elbow
+ */
+export const isSimpleArrow = <T extends ExcalidrawElement>(
+  element?: T,
+): element is T & ExcalidrawArrowElement => {
+  return isArrowElement(element) && !element.elbowed;
+};
+
+export const isSharpArrow = <T extends ExcalidrawElement>(
+  element?: T,
+): element is T & ExcalidrawArrowElement => {
+  return isArrowElement(element) && !element.elbowed && !element.roundness;
+};
+
+export const isCurvedArrow = <T extends ExcalidrawElement>(
+  element?: T,
+): element is T & ExcalidrawArrowElement => {
+  return (
+    isArrowElement(element) && !element.elbowed && element.roundness !== null
+  );
+};
+
+export const isLinearElementType = (
+  elementType: ElementOrToolType,
+): boolean => {
+  return (
+    elementType === "arrow" || elementType === "line" // || elementType === "freedraw"
+  );
+};
+
+export const isBindingElement = <T extends ExcalidrawElement>(
+  element?: T | null,
+  includeLocked = true,
+): element is T & ExcalidrawArrowElement => {
+  return (
+    element != null &&
+    (!element.locked || includeLocked === true) &&
+    isBindingElementType(element.type)
+  );
+};
+
+export const isBindingElementType = (
+  elementType: ElementOrToolType,
+): boolean => {
+  return elementType === "arrow";
+};
+
+export const isBindableElement = <T extends ExcalidrawElement>(
+  element: T | null | undefined,
+  includeLocked = true,
+): element is T & ExcalidrawBindableElement => {
+  return (
+    element != null &&
+    (!element.locked || includeLocked === true) &&
+    (element.type === "rectangle" ||
+      element.type === "stickynote" ||
+      element.type === "diamond" ||
+      element.type === "ellipse" ||
+      element.type === "image" ||
+      element.type === "iframe" ||
+      element.type === "embeddable" ||
+      element.type === "frame" ||
+      element.type === "magicframe" ||
+      (element.type === "text" && !element.containerId))
+  );
+};
+
+export const isRectanguloidElement = <T extends ExcalidrawElement>(
+  element?: T | null,
+): element is T & ExcalidrawBindableElement => {
+  return (
+    element != null &&
+    (element.type === "rectangle" ||
+      element.type === "stickynote" ||
+      element.type === "diamond" ||
+      element.type === "image" ||
+      element.type === "iframe" ||
+      element.type === "embeddable" ||
+      element.type === "frame" ||
+      element.type === "magicframe" ||
+      (element.type === "text" && !element.containerId))
+  );
+};
+
+// TODO: Remove this when proper distance calculation is introduced
+// @see binding.ts:distanceToBindableElement()
+export const isRectangularElement = <T extends ExcalidrawElement>(
+  element?: T | null,
+): element is T & ExcalidrawBindableElement => {
+  return (
+    element != null &&
+    (element.type === "rectangle" ||
+      element.type === "stickynote" ||
+      element.type === "image" ||
+      element.type === "text" ||
+      element.type === "iframe" ||
+      element.type === "embeddable" ||
+      element.type === "frame" ||
+      element.type === "magicframe" ||
+      element.type === "freedraw")
+  );
+};
+
+export const isTextBindableContainer = <T extends ExcalidrawElement>(
+  element: T | null,
+  includeLocked = true,
+): element is T & ExcalidrawTextContainer => {
+  return (
+    element != null &&
+    (!element.locked || includeLocked === true) &&
+    (element.type === "rectangle" ||
+      element.type === "stickynote" ||
+      element.type === "diamond" ||
+      element.type === "ellipse" ||
+      isArrowElement(element))
+  );
+};
+
+export const isExcalidrawElement = (
+  element: any,
+): element is ExcalidrawElement => {
+  const type: ExcalidrawElementType | undefined = element?.type;
+  if (!type) {
+    return false;
+  }
+  switch (type) {
+    case "text":
+    case "diamond":
+    case "rectangle":
+    case "stickynote":
+    case "iframe":
+    case "embeddable":
+    case "ellipse":
+    case "arrow":
+    case "freedraw":
+    case "line":
+    case "frame":
+    case "magicframe":
+    case "image":
+    case "selection": {
+      return true;
+    }
+    default: {
+      assertNever(type, null);
+      return false;
+    }
+  }
+};
+
+export const isFlowchartNodeElement = <T extends ExcalidrawElement>(
+  element: T,
+): element is T & ExcalidrawFlowchartNodeElement => {
+  return (
+    element.type === "rectangle" ||
+    element.type === "stickynote" ||
+    element.type === "ellipse" ||
+    element.type === "diamond"
+  );
+};
+
+export const hasBoundTextElement = <T extends ExcalidrawElement>(
+  element: T | null,
+): element is T &
+  MarkNonNullable<ExcalidrawBindableElement, "boundElements"> => {
+  return (
+    isTextBindableContainer(element) &&
+    !!element.boundElements?.some(({ type }) => type === "text")
+  );
+};
+
+export const isBoundToContainer = <T extends ExcalidrawElement>(
+  element: T | null,
+): element is T & ExcalidrawTextElementWithContainer => {
+  return (
+    element !== null &&
+    "containerId" in element &&
+    element.containerId !== null &&
+    isTextElement(element)
+  );
+};
+
+export const isArrowBoundToElement = (element: ExcalidrawArrowElement) => {
+  return !!element.startBinding || !!element.endBinding;
+};
+
+export const isUsingAdaptiveRadius = (type: string) =>
+  type === "rectangle" ||
+  type === "embeddable" ||
+  type === "iframe" ||
+  type === "image";
+
+export const isUsingProportionalRadius = (type: string) =>
+  type === "line" ||
+  type === "arrow" ||
+  type === "diamond" ||
+  type === "stickynote";
+
+export const canApplyRoundnessTypeToElement = (
+  roundnessType: RoundnessType,
+  element: ExcalidrawElement,
+) => {
+  if (
+    (roundnessType === ROUNDNESS.ADAPTIVE_RADIUS ||
+      // if legacy roundness, it can be applied to elements that currently
+      // use adaptive radius
+      roundnessType === ROUNDNESS.LEGACY) &&
+    isUsingAdaptiveRadius(element.type)
+  ) {
+    return true;
+  }
+  if (
+    roundnessType === ROUNDNESS.PROPORTIONAL_RADIUS &&
+    isUsingProportionalRadius(element.type)
+  ) {
+    return true;
+  }
+
+  return false;
+};
+
+export const getDefaultRoundnessTypeForElement = (
+  element: ExcalidrawElement,
+) => {
+  if (isUsingProportionalRadius(element.type)) {
+    return {
+      type: ROUNDNESS.PROPORTIONAL_RADIUS,
+    };
+  }
+
+  if (isUsingAdaptiveRadius(element.type)) {
+    return {
+      type: ROUNDNESS.ADAPTIVE_RADIUS,
+    };
+  }
+
+  return null;
+};
+
+export const getLinearElementSubType = (
+  element: ExcalidrawLinearElement,
+): ExcalidrawLinearElementSubType => {
+  if (isSharpArrow(element)) {
+    return "sharpArrow";
+  }
+  if (isCurvedArrow(element)) {
+    return "curvedArrow";
+  }
+  if (isElbowArrow(element)) {
+    return "elbowArrow";
+  }
+  return "line";
+};
+
+/**
+ * Checks if current element points meet all the conditions for polygon=true
+ * (this isn't a element type check, for that use isLineElement).
+ *
+ * If you want to check if points *can* be turned into a polygon, use
+ *  canBecomePolygon(points).
+ */
+export const isValidPolygon = (
+  points: ExcalidrawLineElement["points"],
+): boolean => {
+  return points.length > 3 && pointsEqual(points[0], points[points.length - 1]);
+};
+
+export const canBecomePolygon = (
+  points: ExcalidrawLineElement["points"],
+): boolean => {
+  return (
+    points.length > 3 ||
+    // 3-point polygons can't have all points in a single line
+    (points.length === 3 && !pointsEqual(points[0], points[points.length - 1]))
+  );
+};
+
+export const isEligibleFrameChildType = (type: ElementOrToolType) => {
+  switch (type) {
+    case "rectangle":
+    case "stickynote":
+    case "diamond":
+    case "ellipse":
+    case "arrow":
+    case "line":
+    case "freedraw":
+    case "text":
+    case "image":
+    case "frame":
+    case "embeddable": {
+      return true;
+    }
+    default: {
+      return false;
+    }
+  }
+};

packages/element/src/types.ts

@@ -0,0 +1,496 @@
+import type { LocalPoint, Radians } from "@excalidraw/math";
+
+import type {
+  FONT_FAMILY,
+  ROUNDNESS,
+  TEXT_ALIGN,
+  THEME,
+  VERTICAL_ALIGN,
+} from "@excalidraw/common";
+
+import type {
+  MakeBrand,
+  MarkNonNullable,
+  Merge,
+  ValueOf,
+} from "@excalidraw/common/utility-types";
+
+export type ChartType = "bar" | "line" | "radar";
+export type FillStyle = "hachure" | "cross-hatch" | "solid" | "zigzag";
+export type FontFamilyKeys = keyof typeof FONT_FAMILY;
+export type FontFamilyValues = typeof FONT_FAMILY[FontFamilyKeys];
+export type Theme = typeof THEME[keyof typeof THEME];
+export type FontString = string & { _brand: "fontString" };
+export type GroupId = string;
+export type PointerType = "mouse" | "pen" | "touch";
+export type StrokeRoundness = "round" | "sharp";
+export type RoundnessType = ValueOf<typeof ROUNDNESS>;
+export type StrokeStyle = "solid" | "dashed" | "dotted";
+export type TextAlign = typeof TEXT_ALIGN[keyof typeof TEXT_ALIGN];
+
+type VerticalAlignKeys = keyof typeof VERTICAL_ALIGN;
+export type VerticalAlign = typeof VERTICAL_ALIGN[VerticalAlignKeys];
+export type FractionalIndex = string & { _brand: "franctionalIndex" };
+
+export type BoundElement = Readonly<{
+  id: ExcalidrawLinearElement["id"];
+  type: "arrow" | "text";
+}>;
+
+type _ExcalidrawElementBase = Readonly<{
+  id: string;
+  x: number;
+  y: number;
+  strokeColor: string;
+  backgroundColor: string;
+  fillStyle: FillStyle;
+  strokeWidth: number;
+  strokeStyle: StrokeStyle;
+  roundness: null | { type: RoundnessType; value?: number };
+  roughness: number;
+  opacity: number;
+  width: number;
+  height: number;
+  angle: Radians;
+  /** Random integer used to seed shape generation so that the roughjs shape
+      doesn't differ across renders. */
+  seed: number;
+  /** Integer that is sequentially incremented on each change. Used to reconcile
+      elements during collaboration or when saving to server. */
+  version: number;
+  /** Random integer that is regenerated on each change.
+      Used for deterministic reconciliation of updates during collaboration,
+      in case the versions (see above) are identical. */
+  versionNonce: number;
+  /** String in a fractional form defined by https://github.com/rocicorp/fractional-indexing.
+      Used for ordering in multiplayer scenarios, such as during reconciliation or undo / redo.
+      Always kept in sync with the array order by `syncMovedIndices` and `syncInvalidIndices`.
+      Could be null, i.e. for new elements which were not yet assigned to the scene. */
+  index: FractionalIndex | null;
+  isDeleted: boolean;
+  /** List of groups the element belongs to.
+      Ordered from deepest to shallowest. */
+  groupIds: readonly GroupId[];
+  frameId: string | null;
+  /** other elements that are bound to this element */
+  boundElements: readonly BoundElement[] | null;
+  /** epoch (ms) timestamp of last element update */
+  updated: number;
+  /** Client wall-clock creation time in epoch milliseconds; null if unknown.
+      Preserved for this element's lifetime, including edits and undo/redo,
+      and excluded from `ElementUpdate` (mutateElement / newElementWith).
+      Duplicating an element starts a new lifetime. Not an ordering clock. */
+  created: number | null;
+  link: string | null;
+  locked: boolean;
+  customData?: Record<string, any>;
+}>;
+
+export type ExcalidrawSelectionElement = _ExcalidrawElementBase & {
+  type: "selection";
+};
+
+export type ExcalidrawRectangleElement = _ExcalidrawElementBase & {
+  type: "rectangle";
+};
+
+export type ExcalidrawStickyNoteElement = _ExcalidrawElementBase &
+  Readonly<{
+    type: "stickynote";
+    /**
+     * The height the user set, from which the layout derives `height`: the
+     * note grows above it to fit its label and never shrinks below it
+     */
+    baseHeight: number;
+  }>;
+
+export type ExcalidrawDiamondElement = _ExcalidrawElementBase & {
+  type: "diamond";
+};
+
+export type ExcalidrawEllipseElement = _ExcalidrawElementBase & {
+  type: "ellipse";
+};
+
+export type ExcalidrawEmbeddableElement = _ExcalidrawElementBase &
+  Readonly<{
+    type: "embeddable";
+  }>;
+
+export type MagicGenerationData =
+  | {
+      status: "pending";
+    }
+  | { status: "done"; html: string }
+  | {
+      status: "error";
+      message?: string;
+      code: "ERR_GENERATION_INTERRUPTED" | string;
+    };
+
+export type ExcalidrawIframeElement = _ExcalidrawElementBase &
+  Readonly<{
+    type: "iframe";
+    // TODO move later to AI-specific frame
+    customData?: { generationData?: MagicGenerationData };
+  }>;
+
+export type ExcalidrawIframeLikeElement =
+  | ExcalidrawIframeElement
+  | ExcalidrawEmbeddableElement;
+
+export type IframeData =
+  | {
+      intrinsicSize: { w: number; h: number };
+      error?: Error;
+      sandbox?: { allowSameOrigin?: boolean };
+    } & (
+      | { type: "video" | "generic"; link: string }
+      | { type: "document"; srcdoc: (theme: Theme) => string }
+    );
+
+export type ImageCrop = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  naturalWidth: number;
+  naturalHeight: number;
+};
+
+export type ExcalidrawImageElement = _ExcalidrawElementBase &
+  Readonly<{
+    type: "image";
+    fileId: FileId | null;
+    /** whether respective file is persisted */
+    status: "pending" | "saved" | "error";
+    /** X and Y scale factors <-1, 1>, used for image axis flipping */
+    scale: [number, number];
+    /** whether an element is cropped */
+    crop: ImageCrop | null;
+  }>;
+
+export type InitializedExcalidrawImageElement = MarkNonNullable<
+  ExcalidrawImageElement,
+  "fileId"
+>;
+
+export type ExcalidrawFrameElement = _ExcalidrawElementBase & {
+  type: "frame";
+  name: string | null;
+};
+
+export type ExcalidrawMagicFrameElement = _ExcalidrawElementBase & {
+  type: "magicframe";
+  name: string | null;
+};
+
+export type ExcalidrawFrameLikeElement =
+  | ExcalidrawFrameElement
+  | ExcalidrawMagicFrameElement;
+
+/**
+ * These are elements that don't have any additional properties.
+ */
+export type ExcalidrawGenericElement =
+  | ExcalidrawSelectionElement
+  | ExcalidrawRectangleElement
+  | ExcalidrawDiamondElement
+  | ExcalidrawEllipseElement;
+
+export type ExcalidrawFlowchartNodeElement =
+  | ExcalidrawRectangleElement
+  | ExcalidrawStickyNoteElement
+  | ExcalidrawDiamondElement
+  | ExcalidrawEllipseElement;
+
+export type ExcalidrawRectanguloidElement =
+  | ExcalidrawRectangleElement
+  | ExcalidrawStickyNoteElement
+  | ExcalidrawImageElement
+  | ExcalidrawTextElement
+  | ExcalidrawFreeDrawElement
+  | ExcalidrawIframeLikeElement
+  | ExcalidrawFrameLikeElement
+  | ExcalidrawEmbeddableElement
+  | ExcalidrawSelectionElement;
+
+/**
+ * ExcalidrawElement should be JSON serializable and (eventually) contain
+ * no computed data. The list of all ExcalidrawElements should be shareable
+ * between peers and contain no state local to the peer.
+ */
+export type ExcalidrawElement =
+  | ExcalidrawGenericElement
+  | ExcalidrawStickyNoteElement
+  | ExcalidrawTextElement
+  | ExcalidrawLinearElement
+  | ExcalidrawArrowElement
+  | ExcalidrawFreeDrawElement
+  | ExcalidrawImageElement
+  | ExcalidrawFrameElement
+  | ExcalidrawMagicFrameElement
+  | ExcalidrawIframeElement
+  | ExcalidrawEmbeddableElement;
+
+export type ExcalidrawNonSelectionElement = Exclude<
+  ExcalidrawElement,
+  ExcalidrawSelectionElement
+>;
+
+export type Ordered<TElement extends ExcalidrawElement> = TElement & {
+  index: FractionalIndex;
+};
+
+export type OrderedExcalidrawElement = Ordered<ExcalidrawElement>;
+
+export type NonDeleted<TElement extends ExcalidrawElement> = TElement & {
+  isDeleted: false;
+};
+
+export type NonDeletedExcalidrawElement = NonDeleted<ExcalidrawElement>;
+
+export type ExcalidrawTextElement = _ExcalidrawElementBase &
+  Readonly<{
+    type: "text";
+    fontSize: number;
+    fontFamily: FontFamilyValues;
+    /**
+     * The font size the user picked, from which the layout derives `fontSize`.
+     * Today only sticky note labels have one: the auto-fit shrinks below it
+     * and never above it (compare `baseHeight`, which the note grows above).
+     * `null` for every other text. Read it through `getBaseFontSize` —
+     * generic binding repair can detach a label without clearing this, so
+     * the container decides its meaning.
+     */
+    baseFontSize: number | null;
+    text: string;
+    textAlign: TextAlign;
+    verticalAlign: VerticalAlign;
+    containerId: ExcalidrawTextContainer["id"] | null;
+    originalText: string;
+    /**
+     * If `true` the width will fit the text. If `false`, the text will
+     * wrap to fit the width.
+     *
+     * @default true
+     */
+    autoResize: boolean;
+    /**
+     * Unitless line height (aligned to W3C). To get line height in px, multiply
+     *  with font size (using `getLineHeightInPx` helper).
+     */
+    lineHeight: number & { _brand: "unitlessLineHeight" };
+    /**
+     * Position of text bound to a linear element (such as an arrow),
+     * expressed as a normalized arc-length parameter (0–1) along the
+     * container's whole path. Independent of how the path is segmented,
+     * so it survives midpoint insertion and other geometry changes.
+     * */
+    labelPosition?: number | null;
+  }>;
+
+export type ExcalidrawBindableElement =
+  | ExcalidrawRectangleElement
+  | ExcalidrawStickyNoteElement
+  | ExcalidrawDiamondElement
+  | ExcalidrawEllipseElement
+  | ExcalidrawTextElement
+  | ExcalidrawImageElement
+  | ExcalidrawIframeElement
+  | ExcalidrawEmbeddableElement
+  | ExcalidrawFrameElement
+  | ExcalidrawMagicFrameElement;
+
+export type ExcalidrawTextContainer =
+  | ExcalidrawRectangleElement
+  | ExcalidrawStickyNoteElement
+  | ExcalidrawDiamondElement
+  | ExcalidrawEllipseElement
+  | ExcalidrawArrowElement;
+
+export type ExcalidrawTextElementWithContainer = {
+  containerId: ExcalidrawTextContainer["id"];
+} & ExcalidrawTextElement;
+
+export type FixedPoint = [number, number];
+
+export type BindMode = "inside" | "orbit" | "skip";
+
+export type FixedPointBinding = {
+  elementId: ExcalidrawBindableElement["id"];
+
+  // Represents the fixed point binding information in form of a vertical and
+  // horizontal ratio (i.e. a percentage value in the 0.0-1.0 range). This ratio
+  // gives the user selected fixed point by multiplying the bound element width
+  // with fixedPoint[0] and the bound element height with fixedPoint[1] to get the
+  // bound element-local point coordinate.
+  fixedPoint: FixedPoint;
+
+  // Determines whether the arrow remains outside the shape or is allowed to
+  // go all the way inside the shape up to the exact fixed point.
+  mode: BindMode;
+};
+
+type Index = number;
+
+export type PointsPositionUpdates = Map<
+  Index,
+  { point: LocalPoint; isDragging?: boolean }
+>;
+
+export type CardinalityArrowhead =
+  | "cardinality_one"
+  | "cardinality_many"
+  | "cardinality_one_or_many"
+  | "cardinality_exactly_one"
+  | "cardinality_zero_or_one"
+  | "cardinality_zero_or_many";
+
+export type ArrowheadLegacy =
+  | "dot"
+  | "crowfoot_one"
+  | "crowfoot_many"
+  | "crowfoot_one_or_many";
+
+export type Arrowhead =
+  | "arrow"
+  | "bar"
+  | "circle"
+  | "circle_outline"
+  | "triangle"
+  | "triangle_outline"
+  | "diamond"
+  | "diamond_outline"
+  | CardinalityArrowhead;
+
+export type AnyArrowhead = Arrowhead | ArrowheadLegacy;
+
+export type ExcalidrawLinearElement = _ExcalidrawElementBase &
+  Readonly<{
+    type: "line" | "arrow";
+    points: readonly LocalPoint[];
+    startBinding: FixedPointBinding | null;
+    endBinding: FixedPointBinding | null;
+    startArrowhead: Arrowhead | null;
+    endArrowhead: Arrowhead | null;
+  }>;
+
+export type ExcalidrawLineElement = ExcalidrawLinearElement &
+  Readonly<{
+    type: "line";
+    polygon: boolean;
+  }>;
+
+export type FixedSegment = {
+  start: LocalPoint;
+  end: LocalPoint;
+  index: Index;
+};
+
+export type ExcalidrawArrowElement = ExcalidrawLinearElement &
+  Readonly<{
+    type: "arrow";
+    elbowed: boolean;
+  }>;
+
+export type ExcalidrawElbowArrowElement = Merge<
+  ExcalidrawArrowElement,
+  {
+    elbowed: true;
+    fixedSegments: readonly FixedSegment[] | null;
+    startBinding: FixedPointBinding | null;
+    endBinding: FixedPointBinding | null;
+    /**
+     * Marks that the 3rd point should be used as the 2nd point of the arrow in
+     * order to temporarily hide the first segment of the arrow without losing
+     * the data from the points array. It allows creating the expected arrow
+     * path when the arrow with fixed segments is bound on a horizontal side and
+     * moved to a vertical and vica versa.
+     */
+    startIsSpecial: boolean | null;
+    /**
+     * Marks that the 3rd point backwards from the end should be used as the 2nd
+     * point of the arrow in order to temporarily hide the last segment of the
+     * arrow without losing the data from the points array. It allows creating
+     * the expected arrow path when the arrow with fixed segments is bound on a
+     * horizontal side and moved to a vertical and vica versa.
+     */
+    endIsSpecial: boolean | null;
+  }
+>;
+
+export type StrokeVariability = "variable" | "constant";
+
+export type StrokeOptions = Readonly<{
+  variability: StrokeVariability;
+  streamline: number;
+}>;
+
+export type ExcalidrawFreeDrawElement = _ExcalidrawElementBase &
+  Readonly<{
+    type: "freedraw";
+    points: readonly LocalPoint[];
+    pressures: readonly number[];
+    simulatePressure: boolean;
+    strokeOptions: StrokeOptions;
+  }>;
+
+export type FileId = string & { _brand: "FileId" };
+
+export type ExcalidrawElementType = ExcalidrawElement["type"];
+
+/**
+ * Map of excalidraw elements.
+ * Unspecified whether deleted or non-deleted.
+ * Can be a subset of Scene elements.
+ */
+export type ElementsMap = Map<ExcalidrawElement["id"], ExcalidrawElement>;
+
+/**
+ * Map of non-deleted elements.
+ * Can be a subset of Scene elements.
+ */
+export type NonDeletedElementsMap = Map<
+  ExcalidrawElement["id"],
+  NonDeletedExcalidrawElement
+> &
+  MakeBrand<"NonDeletedElementsMap">;
+
+/**
+ * Map of all excalidraw Scene elements, including deleted.
+ * Not a subset. Use this type when you need access to current Scene elements.
+ */
+export type SceneElementsMap = Map<
+  ExcalidrawElement["id"],
+  Ordered<ExcalidrawElement>
+> &
+  MakeBrand<"SceneElementsMap">;
+
+/**
+ * Map of all non-deleted Scene elements.
+ * Not a subset. Use this type when you need access to current Scene elements.
+ */
+export type NonDeletedSceneElementsMap = Map<
+  ExcalidrawElement["id"],
+  Ordered<NonDeletedExcalidrawElement>
+> &
+  MakeBrand<"NonDeletedSceneElementsMap">;
+
+export type ElementsMapOrArray =
+  | readonly ExcalidrawElement[]
+  | Readonly<ElementsMap>;
+
+export type NonDeletedElementsMapOrArray =
+  | readonly NonDeletedExcalidrawElement[]
+  | Readonly<NonDeletedElementsMap | NonDeletedSceneElementsMap>;
+
+export type ExcalidrawLinearElementSubType =
+  | "line"
+  | "sharpArrow"
+  | "curvedArrow"
+  | "elbowArrow";
+
+export type ConvertibleGenericTypes = "rectangle" | "diamond" | "ellipse";
+export type ConvertibleLinearTypes = ExcalidrawLinearElementSubType;
+export type ConvertibleTypes = ConvertibleGenericTypes | ConvertibleLinearTypes;

packages/element/src/utils.ts

@@ -0,0 +1,788 @@
+import {
+  DEFAULT_ADAPTIVE_RADIUS,
+  DEFAULT_PROPORTIONAL_RADIUS,
+  invariant,
+  LINE_CONFIRM_THRESHOLD,
+  ROUNDNESS,
+} from "@excalidraw/common";
+
+import {
+  bezierEquation,
+  curve,
+  curveCatmullRomCubicApproxPoints,
+  curveOffsetPoints,
+  lineSegment,
+  lineSegmentIntersectionPoints,
+  pointDistance,
+  pointFrom,
+  pointFromArray,
+  pointFromVector,
+  pointRotateRads,
+  pointTranslate,
+  rectangle,
+  vectorFromPoint,
+  vectorNormalize,
+  vectorScale,
+  type GlobalPoint,
+} from "@excalidraw/math";
+
+import type { Curve, LineSegment, LocalPoint } from "@excalidraw/math";
+
+import type {
+  AppState,
+  NormalizedZoomValue,
+  Zoom,
+} from "@excalidraw/excalidraw/types";
+
+import { elementCenterPoint, getDiamondPoints } from "./bounds";
+
+import { generateLinearCollisionShape } from "./shape";
+
+import { hitElementItself, isPointInElement } from "./collision";
+import { LinearElementEditor } from "./linearElementEditor";
+import { isElbowArrow, isRectangularElement } from "./typeChecks";
+import { maxBindingDistance_simple } from "./binding";
+
+import {
+  getGlobalFixedPointForBindableElement,
+  normalizeFixedPoint,
+} from "./binding";
+import { getStickyNoteCornerRadius } from "./stickyNote";
+
+import type {
+  ElementsMap,
+  ExcalidrawArrowElement,
+  ExcalidrawBindableElement,
+  ExcalidrawDiamondElement,
+  ExcalidrawElement,
+  ExcalidrawFreeDrawElement,
+  ExcalidrawLinearElement,
+  ExcalidrawRectanguloidElement,
+} from "./types";
+
+export type LinearPathSegment = LineSegment<GlobalPoint> | Curve<GlobalPoint>;
+
+type ElementShape = [LineSegment<GlobalPoint>[], Curve<GlobalPoint>[]];
+
+const ElementShapesCache = new WeakMap<
+  ExcalidrawElement,
+  { version: ExcalidrawElement["version"]; shapes: Map<number, ElementShape> }
+>();
+
+const getElementShapesCacheEntry = <T extends ExcalidrawElement>(
+  element: T,
+  offset: number,
+): ElementShape | undefined => {
+  const record = ElementShapesCache.get(element);
+
+  if (!record) {
+    return undefined;
+  }
+
+  const { version, shapes } = record;
+
+  if (version !== element.version) {
+    ElementShapesCache.delete(element);
+    return undefined;
+  }
+
+  return shapes.get(offset);
+};
+
+const setElementShapesCacheEntry = <T extends ExcalidrawElement>(
+  element: T,
+  shape: ElementShape,
+  offset: number,
+) => {
+  const record = ElementShapesCache.get(element);
+
+  if (!record) {
+    ElementShapesCache.set(element, {
+      version: element.version,
+      shapes: new Map([[offset, shape]]),
+    });
+
+    return;
+  }
+
+  const { version, shapes } = record;
+
+  if (version !== element.version) {
+    ElementShapesCache.set(element, {
+      version: element.version,
+      shapes: new Map([[offset, shape]]),
+    });
+
+    return;
+  }
+
+  shapes.set(offset, shape);
+};
+
+/**
+ * Returns the **rotated** components of freedraw, line or arrow elements.
+ *
+ * @param element The linear element to deconstruct
+ * @returns The rotated in components.
+ */
+export function deconstructLinearOrFreeDrawElement(
+  element: ExcalidrawLinearElement | ExcalidrawFreeDrawElement,
+  elementsMap: ElementsMap,
+): ElementShape {
+  const cachedShape = getElementShapesCacheEntry(element, 0);
+
+  if (cachedShape) {
+    return cachedShape;
+  }
+
+  const ops = generateLinearCollisionShape(element, elementsMap);
+  const lines: LineSegment<GlobalPoint>[] = [];
+  const curves: Curve<GlobalPoint>[] = [];
+
+  for (let idx = 0; idx < ops.length; idx += 1) {
+    const op = ops[idx];
+    const prevPoint =
+      ops[idx - 1] && pointFromArray<LocalPoint>(ops[idx - 1].data.slice(-2));
+    switch (op.op) {
+      case "move":
+        continue;
+      case "lineTo":
+        if (!prevPoint) {
+          throw new Error("prevPoint is undefined");
+        }
+
+        lines.push(
+          lineSegment<GlobalPoint>(
+            pointFrom<GlobalPoint>(
+              element.x + prevPoint[0],
+              element.y + prevPoint[1],
+            ),
+            pointFrom<GlobalPoint>(
+              element.x + op.data[0],
+              element.y + op.data[1],
+            ),
+          ),
+        );
+        continue;
+      case "bcurveTo":
+        if (!prevPoint) {
+          throw new Error("prevPoint is undefined");
+        }
+
+        curves.push(
+          curve<GlobalPoint>(
+            pointFrom<GlobalPoint>(
+              element.x + prevPoint[0],
+              element.y + prevPoint[1],
+            ),
+            pointFrom<GlobalPoint>(
+              element.x + op.data[0],
+              element.y + op.data[1],
+            ),
+            pointFrom<GlobalPoint>(
+              element.x + op.data[2],
+              element.y + op.data[3],
+            ),
+            pointFrom<GlobalPoint>(
+              element.x + op.data[4],
+              element.y + op.data[5],
+            ),
+          ),
+        );
+        continue;
+      default: {
+        console.error("Unknown op type", op.op);
+      }
+    }
+  }
+
+  const shape: ElementShape = [lines, curves];
+  setElementShapesCacheEntry(element, shape, 0);
+
+  return shape;
+}
+
+export function getLinearElementPathSegments(
+  element: ExcalidrawLinearElement | ExcalidrawFreeDrawElement,
+  elementsMap: ElementsMap,
+): LinearPathSegment[] {
+  // For now, model elbow arrows as their unrounded logical path. Rounded
+  // joints can be incorporated once the path model supports mixed straight
+  // and curved segments.
+  if (isElbowArrow(element)) {
+    return element.points
+      .slice(1)
+      .map((point, index) =>
+        lineSegment<GlobalPoint>(
+          pointFrom<GlobalPoint>(
+            element.x + element.points[index][0],
+            element.y + element.points[index][1],
+          ),
+          pointFrom<GlobalPoint>(element.x + point[0], element.y + point[1]),
+        ),
+      );
+  }
+
+  const [lines, curves] = deconstructLinearOrFreeDrawElement(
+    element,
+    elementsMap,
+  );
+
+  // Non-elbow paths currently contain only one segment type. Mixed paths
+  // should consume an ordered operation stream instead of these type buckets.
+  return curves.length > 0 ? curves : lines;
+}
+
+/**
+ * Get the building components of a rectanguloid element in the form of
+ * line segments and curves **unrotated**.
+ *
+ * @param element Target rectanguloid element
+ * @param offset Optional offset to expand the rectanguloid shape
+ * @returns Tuple of **unrotated** line segments (0) and curves (1)
+ */
+export function deconstructRectanguloidElement(
+  element: ExcalidrawRectanguloidElement,
+  offset: number = 0,
+): ElementShape {
+  const cachedShape = getElementShapesCacheEntry(element, offset);
+
+  if (cachedShape) {
+    return cachedShape;
+  }
+
+  let radius =
+    element.type === "stickynote"
+      ? getStickyNoteCornerRadius(element)
+      : getCornerRadius(Math.min(element.width, element.height), element);
+
+  if (radius === 0) {
+    radius = 0.01;
+  }
+
+  const r = rectangle(
+    pointFrom(element.x, element.y),
+    pointFrom(element.x + element.width, element.y + element.height),
+  );
+
+  const top = lineSegment<GlobalPoint>(
+    pointFrom<GlobalPoint>(r[0][0] + radius, r[0][1]),
+    pointFrom<GlobalPoint>(r[1][0] - radius, r[0][1]),
+  );
+  const right = lineSegment<GlobalPoint>(
+    pointFrom<GlobalPoint>(r[1][0], r[0][1] + radius),
+    pointFrom<GlobalPoint>(r[1][0], r[1][1] - radius),
+  );
+  const bottom = lineSegment<GlobalPoint>(
+    pointFrom<GlobalPoint>(r[0][0] + radius, r[1][1]),
+    pointFrom<GlobalPoint>(r[1][0] - radius, r[1][1]),
+  );
+  const left = lineSegment<GlobalPoint>(
+    pointFrom<GlobalPoint>(r[0][0], r[1][1] - radius),
+    pointFrom<GlobalPoint>(r[0][0], r[0][1] + radius),
+  );
+
+  const baseCorners = [
+    curve(
+      left[1],
+      pointFrom<GlobalPoint>(
+        left[1][0] + (2 / 3) * (r[0][0] - left[1][0]),
+        left[1][1] + (2 / 3) * (r[0][1] - left[1][1]),
+      ),
+      pointFrom<GlobalPoint>(
+        top[0][0] + (2 / 3) * (r[0][0] - top[0][0]),
+        top[0][1] + (2 / 3) * (r[0][1] - top[0][1]),
+      ),
+      top[0],
+    ), // TOP LEFT
+    curve(
+      top[1],
+      pointFrom<GlobalPoint>(
+        top[1][0] + (2 / 3) * (r[1][0] - top[1][0]),
+        top[1][1] + (2 / 3) * (r[0][1] - top[1][1]),
+      ),
+      pointFrom<GlobalPoint>(
+        right[0][0] + (2 / 3) * (r[1][0] - right[0][0]),
+        right[0][1] + (2 / 3) * (r[0][1] - right[0][1]),
+      ),
+      right[0],
+    ), // TOP RIGHT
+    curve(
+      right[1],
+      pointFrom<GlobalPoint>(
+        right[1][0] + (2 / 3) * (r[1][0] - right[1][0]),
+        right[1][1] + (2 / 3) * (r[1][1] - right[1][1]),
+      ),
+      pointFrom<GlobalPoint>(
+        bottom[1][0] + (2 / 3) * (r[1][0] - bottom[1][0]),
+        bottom[1][1] + (2 / 3) * (r[1][1] - bottom[1][1]),
+      ),
+      bottom[1],
+    ), // BOTTOM RIGHT
+    curve(
+      bottom[0],
+      pointFrom<GlobalPoint>(
+        bottom[0][0] + (2 / 3) * (r[0][0] - bottom[0][0]),
+        bottom[0][1] + (2 / 3) * (r[1][1] - bottom[0][1]),
+      ),
+      pointFrom<GlobalPoint>(
+        left[0][0] + (2 / 3) * (r[0][0] - left[0][0]),
+        left[0][1] + (2 / 3) * (r[1][1] - left[0][1]),
+      ),
+      left[0],
+    ), // BOTTOM LEFT
+  ];
+
+  const corners =
+    offset > 0
+      ? baseCorners.map(
+          (corner) =>
+            curveCatmullRomCubicApproxPoints(
+              curveOffsetPoints(corner, offset),
+            )!,
+        )
+      : [
+          [baseCorners[0]],
+          [baseCorners[1]],
+          [baseCorners[2]],
+          [baseCorners[3]],
+        ];
+
+  const sides = [
+    lineSegment<GlobalPoint>(
+      corners[0][corners[0].length - 1][3],
+      corners[1][0][0],
+    ),
+    lineSegment<GlobalPoint>(
+      corners[1][corners[1].length - 1][3],
+      corners[2][0][0],
+    ),
+    lineSegment<GlobalPoint>(
+      corners[2][corners[2].length - 1][3],
+      corners[3][0][0],
+    ),
+    lineSegment<GlobalPoint>(
+      corners[3][corners[3].length - 1][3],
+      corners[0][0][0],
+    ),
+  ];
+  const shape = [sides, corners.flat()] as ElementShape;
+
+  setElementShapesCacheEntry(element, shape, offset);
+
+  return shape;
+}
+
+export function getDiamondBaseCorners(
+  element: ExcalidrawDiamondElement,
+  offset: number = 0,
+): Curve<GlobalPoint>[] {
+  const [topX, topY, rightX, rightY, bottomX, bottomY, leftX, leftY] =
+    getDiamondPoints(element);
+  const verticalRadius = element.roundness
+    ? getCornerRadius(Math.abs(topX - leftX), element)
+    : (topX - leftX) * 0.01;
+  const horizontalRadius = element.roundness
+    ? getCornerRadius(Math.abs(rightY - topY), element)
+    : (rightY - topY) * 0.01;
+
+  const [top, right, bottom, left]: GlobalPoint[] = [
+    pointFrom(element.x + topX, element.y + topY),
+    pointFrom(element.x + rightX, element.y + rightY),
+    pointFrom(element.x + bottomX, element.y + bottomY),
+    pointFrom(element.x + leftX, element.y + leftY),
+  ];
+
+  return [
+    curve(
+      pointFrom<GlobalPoint>(
+        right[0] - verticalRadius,
+        right[1] - horizontalRadius,
+      ),
+      right,
+      right,
+      pointFrom<GlobalPoint>(
+        right[0] - verticalRadius,
+        right[1] + horizontalRadius,
+      ),
+    ), // RIGHT
+    curve(
+      pointFrom<GlobalPoint>(
+        bottom[0] + verticalRadius,
+        bottom[1] - horizontalRadius,
+      ),
+      bottom,
+      bottom,
+      pointFrom<GlobalPoint>(
+        bottom[0] - verticalRadius,
+        bottom[1] - horizontalRadius,
+      ),
+    ), // BOTTOM
+    curve(
+      pointFrom<GlobalPoint>(
+        left[0] + verticalRadius,
+        left[1] + horizontalRadius,
+      ),
+      left,
+      left,
+      pointFrom<GlobalPoint>(
+        left[0] + verticalRadius,
+        left[1] - horizontalRadius,
+      ),
+    ), // LEFT
+    curve(
+      pointFrom<GlobalPoint>(
+        top[0] - verticalRadius,
+        top[1] + horizontalRadius,
+      ),
+      top,
+      top,
+      pointFrom<GlobalPoint>(
+        top[0] + verticalRadius,
+        top[1] + horizontalRadius,
+      ),
+    ), // TOP
+  ];
+}
+
+/**
+ * Get the **unrotated** building components of a diamond element
+ * in the form of line segments and curves as a tuple, in this order.
+ *
+ * @param element The element to deconstruct
+ * @param offset An optional offset
+ * @returns Tuple of line **unrotated** segments (0) and curves (1)
+ */
+export function deconstructDiamondElement(
+  element: ExcalidrawDiamondElement,
+  offset: number = 0,
+): ElementShape {
+  const cachedShape = getElementShapesCacheEntry(element, offset);
+
+  if (cachedShape) {
+    return cachedShape;
+  }
+
+  const baseCorners = getDiamondBaseCorners(element, offset);
+
+  const corners =
+    offset > 0
+      ? baseCorners.map(
+          (corner) =>
+            curveCatmullRomCubicApproxPoints(
+              curveOffsetPoints(corner, offset),
+            )!,
+        )
+      : [
+          [baseCorners[0]],
+          [baseCorners[1]],
+          [baseCorners[2]],
+          [baseCorners[3]],
+        ];
+
+  const sides = [
+    lineSegment<GlobalPoint>(
+      corners[0][corners[0].length - 1][3],
+      corners[1][0][0],
+    ),
+    lineSegment<GlobalPoint>(
+      corners[1][corners[1].length - 1][3],
+      corners[2][0][0],
+    ),
+    lineSegment<GlobalPoint>(
+      corners[2][corners[2].length - 1][3],
+      corners[3][0][0],
+    ),
+    lineSegment<GlobalPoint>(
+      corners[3][corners[3].length - 1][3],
+      corners[0][0][0],
+    ),
+  ];
+
+  const shape = [sides, corners.flat()] as ElementShape;
+
+  setElementShapesCacheEntry(element, shape, offset);
+
+  return shape;
+}
+
+// Checks if the first and last point are close enough
+// to be considered a loop
+export const isPathALoop = (
+  points: ExcalidrawLinearElement["points"],
+  /** supply if you want the loop detection to account for current zoom */
+  zoomValue: Zoom["value"] = 1 as NormalizedZoomValue,
+): boolean => {
+  if (points.length >= 3) {
+    const [first, last] = [points[0], points[points.length - 1]];
+    const distance = pointDistance(first, last);
+
+    // Adjusting LINE_CONFIRM_THRESHOLD to current zoom so that when zoomed in
+    // really close we make the threshold smaller, and vice versa.
+    return distance <= LINE_CONFIRM_THRESHOLD / zoomValue;
+  }
+  return false;
+};
+
+export const getCornerRadius = (x: number, element: ExcalidrawElement) => {
+  if (
+    element.roundness?.type === ROUNDNESS.PROPORTIONAL_RADIUS ||
+    element.roundness?.type === ROUNDNESS.LEGACY
+  ) {
+    return x * DEFAULT_PROPORTIONAL_RADIUS;
+  }
+
+  if (element.roundness?.type === ROUNDNESS.ADAPTIVE_RADIUS) {
+    const fixedRadiusSize = element.roundness?.value ?? DEFAULT_ADAPTIVE_RADIUS;
+
+    const CUTOFF_SIZE = fixedRadiusSize / DEFAULT_PROPORTIONAL_RADIUS;
+
+    if (x <= CUTOFF_SIZE) {
+      return x * DEFAULT_PROPORTIONAL_RADIUS;
+    }
+
+    return fixedRadiusSize;
+  }
+
+  return 0;
+};
+
+const getDiagonalsForBindableElement = (
+  element: ExcalidrawElement,
+  elementsMap: ElementsMap,
+) => {
+  // for rectangles, shrink the diagonals a bit because there's something
+  // going on with the focus points around the corners. Ask Mark for details.
+  const OFFSET_PX = element.type === "rectangle" ? 15 : 0;
+  const shrinkSegment = (seg: LineSegment<GlobalPoint>) => {
+    const v = vectorNormalize(vectorFromPoint(seg[1], seg[0]));
+    const offset = vectorScale(v, OFFSET_PX);
+    return lineSegment<GlobalPoint>(
+      pointTranslate(seg[0], offset),
+      pointTranslate(seg[1], vectorScale(offset, -1)),
+    );
+  };
+
+  const center = elementCenterPoint(element, elementsMap);
+  const diagonalOne = shrinkSegment(
+    isRectangularElement(element)
+      ? lineSegment<GlobalPoint>(
+          pointRotateRads(
+            pointFrom<GlobalPoint>(element.x, element.y),
+            center,
+            element.angle,
+          ),
+          pointRotateRads(
+            pointFrom<GlobalPoint>(
+              element.x + element.width,
+              element.y + element.height,
+            ),
+            center,
+            element.angle,
+          ),
+        )
+      : lineSegment<GlobalPoint>(
+          pointRotateRads(
+            pointFrom<GlobalPoint>(element.x + element.width / 2, element.y),
+            center,
+            element.angle,
+          ),
+          pointRotateRads(
+            pointFrom<GlobalPoint>(
+              element.x + element.width / 2,
+              element.y + element.height,
+            ),
+            center,
+            element.angle,
+          ),
+        ),
+  );
+  const diagonalTwo = shrinkSegment(
+    isRectangularElement(element)
+      ? lineSegment<GlobalPoint>(
+          pointRotateRads(
+            pointFrom<GlobalPoint>(element.x + element.width, element.y),
+            center,
+            element.angle,
+          ),
+          pointRotateRads(
+            pointFrom<GlobalPoint>(element.x, element.y + element.height),
+            center,
+            element.angle,
+          ),
+        )
+      : lineSegment<GlobalPoint>(
+          pointRotateRads(
+            pointFrom<GlobalPoint>(element.x, element.y + element.height / 2),
+            center,
+            element.angle,
+          ),
+          pointRotateRads(
+            pointFrom<GlobalPoint>(
+              element.x + element.width,
+              element.y + element.height / 2,
+            ),
+            center,
+            element.angle,
+          ),
+        ),
+  );
+
+  return [diagonalOne, diagonalTwo];
+};
+
+export const getSnapOutlineMidPoint = (
+  point: GlobalPoint,
+  element: ExcalidrawBindableElement,
+  elementsMap: ElementsMap,
+  zoom: AppState["zoom"],
+) => {
+  const center = elementCenterPoint(element, elementsMap);
+  const sideMidpoints =
+    element.type === "diamond"
+      ? getDiamondBaseCorners(element).map((curve) => {
+          const point = bezierEquation(curve, 0.5);
+          const rotatedPoint = pointRotateRads(point, center, element.angle);
+
+          return pointFrom<GlobalPoint>(rotatedPoint[0], rotatedPoint[1]);
+        })
+      : [
+          // RIGHT midpoint
+          pointRotateRads(
+            pointFrom<GlobalPoint>(
+              element.x + element.width,
+              element.y + element.height / 2,
+            ),
+            center,
+            element.angle,
+          ),
+          // BOTTOM midpoint
+          pointRotateRads(
+            pointFrom<GlobalPoint>(
+              element.x + element.width / 2,
+              element.y + element.height,
+            ),
+            center,
+            element.angle,
+          ),
+          // LEFT midpoint
+          pointRotateRads(
+            pointFrom<GlobalPoint>(element.x, element.y + element.height / 2),
+            center,
+            element.angle,
+          ),
+          // TOP midpoint
+          pointRotateRads(
+            pointFrom<GlobalPoint>(element.x + element.width / 2, element.y),
+            center,
+            element.angle,
+          ),
+        ];
+  const candidate = sideMidpoints.find(
+    (midpoint) =>
+      pointDistance(point, midpoint) <=
+        maxBindingDistance_simple(zoom) + element.strokeWidth / 2 &&
+      !hitElementItself({
+        point,
+        element,
+        threshold: 0,
+        elementsMap,
+        overrideShouldTestInside: true,
+      }),
+  );
+
+  return candidate;
+};
+
+export const projectFixedPointOntoDiagonal = (
+  arrow: ExcalidrawArrowElement,
+  point: GlobalPoint,
+  element: ExcalidrawBindableElement,
+  startOrEnd: "start" | "end",
+  elementsMap: ElementsMap,
+  zoom: AppState["zoom"],
+  isMidpointSnappingEnabled: boolean = true,
+): GlobalPoint | null => {
+  invariant(arrow.points.length >= 2, "Arrow must have at least two points");
+  if (arrow.width < 3 && arrow.height < 3) {
+    return null;
+  }
+
+  if (isMidpointSnappingEnabled) {
+    const sideMidPoint = getSnapOutlineMidPoint(
+      point,
+      element,
+      elementsMap,
+      zoom,
+    );
+    if (sideMidPoint) {
+      return sideMidPoint;
+    }
+  }
+
+  // Do the projection onto the diagonals (or center lines
+  // for non-rectangular shapes)
+  const [diagonalOne, diagonalTwo] = getDiagonalsForBindableElement(
+    element,
+    elementsMap,
+  );
+
+  // To avoid working with stale arrow state, we use the opposite focus point
+  // of the current endpoint, which will always be unchanged during moving of
+  // the endpoint. This is only needed when the arrow has only two points.
+  let a = LinearElementEditor.getPointAtIndexGlobalCoordinates(
+    arrow,
+    startOrEnd === "start" ? 1 : arrow.points.length - 2,
+    elementsMap,
+  );
+  if (arrow.points.length === 2) {
+    const otherBinding =
+      startOrEnd === "start" ? arrow.endBinding : arrow.startBinding;
+    const otherBindable =
+      otherBinding &&
+      (elementsMap.get(otherBinding.elementId) as
+        | ExcalidrawBindableElement
+        | undefined);
+    const otherFocusPoint =
+      otherBinding &&
+      otherBindable &&
+      getGlobalFixedPointForBindableElement(
+        normalizeFixedPoint(otherBinding.fixedPoint),
+        otherBindable,
+        elementsMap,
+      );
+    if (otherFocusPoint) {
+      a = otherFocusPoint;
+    }
+  }
+
+  const b = pointFromVector<GlobalPoint>(
+    vectorScale(
+      vectorFromPoint(point, a),
+      2 * pointDistance(a, point) +
+        Math.max(
+          pointDistance(diagonalOne[0], diagonalOne[1]),
+          pointDistance(diagonalTwo[0], diagonalTwo[1]),
+        ),
+    ),
+    a,
+  );
+  const intersector = lineSegment<GlobalPoint>(b, a);
+  const p1 = lineSegmentIntersectionPoints(diagonalOne, intersector);
+  const p2 = lineSegmentIntersectionPoints(diagonalTwo, intersector);
+  const d1 = p1 && pointDistance(a, p1);
+  const d2 = p2 && pointDistance(a, p2);
+
+  let projection = null;
+  if (d1 != null && d2 != null) {
+    projection = d1 < d2 ? p1 : p2;
+  } else {
+    projection = p1 || p2 || null;
+  }
+
+  if (projection && isPointInElement(projection, element, elementsMap)) {
+    return projection;
+  }
+
+  return null;
+};

packages/element/src/visualdebug.ts

@@ -0,0 +1,257 @@
+import {
+  isLineSegment,
+  lineSegment,
+  pointDistanceSq,
+  pointFrom,
+  type GlobalPoint,
+  type LocalPoint,
+  type LineSegment,
+} from "@excalidraw/math";
+import { type Bounds, isBounds } from "@excalidraw/common";
+import {
+  getElementBounds,
+  intersectElementWithLineSegment,
+  isFreeDrawElement,
+  isLinearElement,
+  isPathALoop,
+} from "@excalidraw/element";
+
+import type { ElementsMap, ExcalidrawElement } from "@excalidraw/element/types";
+import type { Curve } from "@excalidraw/math";
+
+// The global data holder to collect the debug operations
+declare global {
+  interface Window {
+    visualDebug?: {
+      data: DebugElement[][];
+      currentFrame?: number;
+    };
+  }
+}
+
+export type DebugElement = {
+  color: string;
+  data: LineSegment<GlobalPoint> | Curve<GlobalPoint> | DebugPolygon;
+  permanent: boolean;
+};
+
+export type DebugPolygon = {
+  type: "polygon";
+  points: GlobalPoint[];
+  fill?: boolean;
+  close?: boolean;
+};
+
+export const debugDrawHitVolume = (
+  element: ExcalidrawElement,
+  elementsMap: ElementsMap,
+  options?: {
+    rays?: number;
+    color?: string;
+    fill?: boolean;
+  },
+) => {
+  if (
+    (isLinearElement(element) || isFreeDrawElement(element)) &&
+    !isPathALoop(element.points)
+  ) {
+    return;
+  }
+
+  const [x1, y1, x2, y2] = getElementBounds(element, elementsMap);
+  const center = pointFrom<GlobalPoint>((x1 + x2) / 2, (y1 + y2) / 2);
+  const rays = options?.rays ?? 100;
+  const radius = Math.max(x2 - x1, y2 - y1) * 2;
+  const points: GlobalPoint[] = [];
+
+  for (let i = 0; i < rays; i += 1) {
+    const angle = (i / rays) * Math.PI * 2;
+    const end = pointFrom<GlobalPoint>(
+      center[0] + Math.cos(angle) * radius,
+      center[1] + Math.sin(angle) * radius,
+    );
+    const hits = intersectElementWithLineSegment(
+      element,
+      elementsMap,
+      lineSegment(center, end),
+    );
+    if (hits.length === 0) {
+      continue;
+    }
+    hits.sort(pointDistanceSq);
+    points.push(hits[0]);
+  }
+
+  if (points.length >= 3) {
+    debugDrawPolygon(points, {
+      color: options?.color ?? "orange",
+      fill: options?.fill ?? true,
+    });
+  } else {
+    console.warn(
+      `debugDrawHitVolume: could not compute hit volume for element ${element.id}`,
+    );
+  }
+};
+
+export const debugDrawCubicBezier = (
+  c: Curve<GlobalPoint>,
+  opts?: {
+    color?: string;
+    permanent?: boolean;
+  },
+) => {
+  addToCurrentFrame({
+    color: opts?.color ?? "purple",
+    permanent: !!opts?.permanent,
+    data: c,
+  });
+};
+
+export const debugDrawLine = (
+  segment: LineSegment<GlobalPoint> | LineSegment<GlobalPoint>[],
+  opts?: {
+    color?: string;
+    permanent?: boolean;
+  },
+) => {
+  const segments = (
+    isLineSegment(segment) ? [segment] : segment
+  ) as LineSegment<GlobalPoint>[];
+
+  segments.forEach((data) =>
+    addToCurrentFrame({
+      color: opts?.color ?? "red",
+      data,
+      permanent: !!opts?.permanent,
+    }),
+  );
+};
+
+export const debugDrawPolygon = (
+  points: GlobalPoint[],
+  opts?: {
+    color?: string;
+    permanent?: boolean;
+    fill?: boolean;
+    close?: boolean;
+  },
+) => {
+  if (points.length < 2) {
+    return;
+  }
+
+  addToCurrentFrame({
+    color: opts?.color ?? "orange",
+    permanent: !!opts?.permanent,
+    data: {
+      type: "polygon",
+      points,
+      fill: opts?.fill,
+      close: opts?.close,
+    },
+  });
+};
+
+export const debugDrawPoint = (
+  p: GlobalPoint,
+  opts?: {
+    color?: string;
+    permanent?: boolean;
+    fuzzy?: boolean;
+  },
+) => {
+  const xOffset = opts?.fuzzy ? Math.random() * 3 : 0;
+  const yOffset = opts?.fuzzy ? Math.random() * 3 : 0;
+
+  debugDrawLine(
+    lineSegment(
+      pointFrom<GlobalPoint>(p[0] + xOffset - 10, p[1] + yOffset - 10),
+      pointFrom<GlobalPoint>(p[0] + xOffset + 10, p[1] + yOffset + 10),
+    ),
+    {
+      color: opts?.color ?? "cyan",
+      permanent: opts?.permanent,
+    },
+  );
+  debugDrawLine(
+    lineSegment(
+      pointFrom<GlobalPoint>(p[0] + xOffset - 10, p[1] + yOffset + 10),
+      pointFrom<GlobalPoint>(p[0] + xOffset + 10, p[1] + yOffset - 10),
+    ),
+    {
+      color: opts?.color ?? "cyan",
+      permanent: opts?.permanent,
+    },
+  );
+};
+
+export const debugDrawBounds = (
+  box: Bounds | Bounds[],
+  opts?: {
+    color?: string;
+    permanent?: boolean;
+  },
+) => {
+  (isBounds(box) ? [box] : box).forEach((bbox: Bounds) =>
+    debugDrawLine(
+      [
+        lineSegment(
+          pointFrom<GlobalPoint>(bbox[0], bbox[1]),
+          pointFrom<GlobalPoint>(bbox[2], bbox[1]),
+        ),
+        lineSegment(
+          pointFrom<GlobalPoint>(bbox[2], bbox[1]),
+          pointFrom<GlobalPoint>(bbox[2], bbox[3]),
+        ),
+        lineSegment(
+          pointFrom<GlobalPoint>(bbox[2], bbox[3]),
+          pointFrom<GlobalPoint>(bbox[0], bbox[3]),
+        ),
+        lineSegment(
+          pointFrom<GlobalPoint>(bbox[0], bbox[3]),
+          pointFrom<GlobalPoint>(bbox[0], bbox[1]),
+        ),
+      ],
+      {
+        color: opts?.color ?? "green",
+        permanent: !!opts?.permanent,
+      },
+    ),
+  );
+};
+
+export const debugDrawPoints = (
+  {
+    x,
+    y,
+    points,
+  }: {
+    x: number;
+    y: number;
+    points: readonly LocalPoint[];
+  },
+  options?: any,
+) => {
+  points.forEach((p) =>
+    debugDrawPoint(pointFrom<GlobalPoint>(x + p[0], y + p[1]), options),
+  );
+};
+
+export const debugCloseFrame = () => {
+  window.visualDebug?.data.push([]);
+};
+
+export const debugClear = () => {
+  if (window.visualDebug?.data) {
+    window.visualDebug.data = [];
+  }
+};
+
+const addToCurrentFrame = (element: DebugElement) => {
+  if (window.visualDebug?.data && window.visualDebug.data.length === 0) {
+    window.visualDebug.data[0] = [];
+  }
+  window.visualDebug?.data &&
+    window.visualDebug.data[window.visualDebug.data.length - 1].push(element);
+};

packages/element/src/zindex.ts

@@ -0,0 +1,676 @@
+import { arrayToMap, findIndex, findLastIndex } from "@excalidraw/common";
+
+import { isFiniteNumber } from "@excalidraw/math";
+
+import type { AppState } from "@excalidraw/excalidraw/types";
+import type { GlobalPoint } from "@excalidraw/math";
+
+import { isFrameLikeElement, isTextElement } from "./typeChecks";
+import { getElementsInGroup } from "./groups";
+import { syncMovedIndices } from "./fractionalIndex";
+import { getSelectedElements } from "./selection";
+import { getBoundTextElement, getContainerElement } from "./textElement";
+import { getHoveredElementForBinding } from "./collision";
+
+import { getNonDeletedElements } from ".";
+
+import type { Scene } from "./Scene";
+import type {
+  ExcalidrawArrowElement,
+  ExcalidrawElement,
+  ExcalidrawFrameLikeElement,
+  NonDeletedExcalidrawElement,
+  NonDeletedSceneElementsMap,
+  OrderedExcalidrawElement,
+} from "./types";
+
+const isOfTargetFrame = (element: ExcalidrawElement, frameId: string) => {
+  return element.frameId === frameId || element.id === frameId;
+};
+
+/**
+ * Returns indices of elements to move based on selected elements.
+ * Includes contiguous deleted elements that are between two selected elements,
+ *  e.g.: [0 (selected), 1 (deleted), 2 (deleted), 3 (selected)]
+ *
+ * Specified elements (elementsToBeMoved) take precedence over
+ * appState.selectedElementsIds
+ */
+const getIndicesToMove = (
+  elements: readonly ExcalidrawElement[],
+  appState: AppState,
+  elementsToBeMoved?: readonly ExcalidrawElement[],
+) => {
+  let selectedIndices: number[] = [];
+  let deletedIndices: number[] = [];
+  let includeDeletedIndex = null;
+  let index = -1;
+  const selectedElementIds = arrayToMap(
+    elementsToBeMoved
+      ? elementsToBeMoved
+      : getSelectedElements(elements, appState, {
+          includeBoundTextElement: true,
+          includeElementsInFrames: true,
+        }),
+  );
+  while (++index < elements.length) {
+    const element = elements[index];
+    if (selectedElementIds.get(element.id)) {
+      if (deletedIndices.length) {
+        selectedIndices = selectedIndices.concat(deletedIndices);
+        deletedIndices = [];
+      }
+      selectedIndices.push(index);
+      includeDeletedIndex = index + 1;
+    } else if (element.isDeleted && includeDeletedIndex === index) {
+      includeDeletedIndex = index + 1;
+      deletedIndices.push(index);
+    } else {
+      deletedIndices = [];
+    }
+  }
+  return selectedIndices;
+};
+
+const toContiguousGroups = (array: number[]) => {
+  let cursor = 0;
+  return array.reduce((acc, value, index) => {
+    if (index > 0 && array[index - 1] !== value - 1) {
+      cursor = ++cursor;
+    }
+    (acc[cursor] || (acc[cursor] = [])).push(value);
+    return acc;
+  }, [] as number[][]);
+};
+
+/**
+ * @returns index of target element, consindering tightly-bound elements
+ * (currently non-linear elements bound to a container) as a one unit.
+ * If no binding present, returns `undefined`.
+ */
+const getTargetIndexAccountingForBinding = (
+  nextElement: ExcalidrawElement,
+  elements: readonly ExcalidrawElement[],
+  direction: "left" | "right",
+  scene: Scene,
+) => {
+  if ("containerId" in nextElement && nextElement.containerId) {
+    // TODO: why not to get the container from the nextElements?
+    const containerElement = scene.getElement(nextElement.containerId);
+    if (containerElement) {
+      return direction === "left"
+        ? Math.min(
+            elements.indexOf(containerElement),
+            elements.indexOf(nextElement),
+          )
+        : Math.max(
+            elements.indexOf(containerElement),
+            elements.indexOf(nextElement),
+          );
+    }
+  } else {
+    const boundElementId = nextElement.boundElements?.find(
+      (binding) => binding.type !== "arrow",
+    )?.id;
+    if (boundElementId) {
+      const boundTextElement = scene.getElement(boundElementId);
+      if (boundTextElement) {
+        return direction === "left"
+          ? Math.min(
+              elements.indexOf(boundTextElement),
+              elements.indexOf(nextElement),
+            )
+          : Math.max(
+              elements.indexOf(boundTextElement),
+              elements.indexOf(nextElement),
+            );
+      }
+    }
+  }
+};
+
+const getContiguousFrameRangeElements = (
+  allElements: readonly ExcalidrawElement[],
+  frameId: ExcalidrawFrameLikeElement["id"],
+) => {
+  let rangeStart = -1;
+  let rangeEnd = -1;
+  allElements.forEach((element, index) => {
+    if (isOfTargetFrame(element, frameId)) {
+      if (rangeStart === -1) {
+        rangeStart = index;
+      }
+      rangeEnd = index;
+    }
+  });
+  if (rangeStart === -1) {
+    return [];
+  }
+  return allElements.slice(rangeStart, rangeEnd + 1);
+};
+
+/**
+ * Moves the arrow element above any bindable elements it intersects with or
+ * hovers over.
+ */
+export const moveArrowAboveBindable = (
+  point: GlobalPoint,
+  arrow: ExcalidrawArrowElement,
+  elements: readonly OrderedExcalidrawElement[],
+  elementsMap: NonDeletedSceneElementsMap,
+  scene: Scene,
+  hit?: NonDeletedExcalidrawElement,
+): readonly OrderedExcalidrawElement[] => {
+  const hoveredElement = hit
+    ? hit
+    : getHoveredElementForBinding(
+        point,
+        // SAFETY: callers that omit `hit` pass non-deleted elements
+        getNonDeletedElements(elements),
+        elementsMap,
+      );
+
+  if (!hoveredElement) {
+    return elements;
+  }
+
+  const boundTextElement = getBoundTextElement(hoveredElement, elementsMap);
+  const containerElement = isTextElement(hoveredElement)
+    ? getContainerElement(hoveredElement, elementsMap)
+    : null;
+
+  const bindableIds = [
+    hoveredElement.id,
+    boundTextElement?.id,
+    containerElement?.id,
+  ].filter((id): id is NonDeletedExcalidrawElement["id"] => !!id);
+  const bindableIdx = elements.findIndex((el) => bindableIds.includes(el.id));
+  const arrowIdx = elements.findIndex((el) => el.id === arrow.id);
+
+  if (arrowIdx !== -1 && bindableIdx !== -1 && arrowIdx < bindableIdx) {
+    const updatedElements = Array.from(elements);
+    const arrow = updatedElements.splice(arrowIdx, 1)[0];
+    updatedElements.splice(bindableIdx, 0, arrow);
+
+    scene.replaceAllElements(updatedElements);
+  }
+
+  return elements;
+};
+
+/**
+ * Returns next candidate index that's available to be moved to. Currently that
+ *  is a non-deleted element, and not inside a group (unless we're editing it).
+ */
+const getTargetIndex = (
+  appState: AppState,
+  elements: readonly ExcalidrawElement[],
+  boundaryIndex: number,
+  direction: "left" | "right",
+  /**
+   * Frame id if moving frame children.
+   * If whole frame (including all children) is being moved, supply `null`.
+   */
+  containingFrame: ExcalidrawFrameLikeElement["id"] | null,
+  scene: Scene,
+) => {
+  const sourceElement = elements[boundaryIndex];
+
+  const indexFilter = (element: ExcalidrawElement) => {
+    if (element.isDeleted) {
+      return false;
+    }
+    if (containingFrame) {
+      return element.frameId === containingFrame;
+    }
+    // if we're editing group, find closest sibling irrespective of whether
+    // there's a different-group element between them (for legacy reasons)
+    if (appState.editingGroupId) {
+      return element.groupIds.includes(appState.editingGroupId);
+    }
+    return true;
+  };
+
+  const candidateIndex =
+    direction === "left"
+      ? findLastIndex(
+          elements,
+          (el) => indexFilter(el),
+          Math.max(0, boundaryIndex - 1),
+        )
+      : findIndex(elements, (el) => indexFilter(el), boundaryIndex + 1);
+
+  const nextElement = elements[candidateIndex];
+
+  if (!nextElement) {
+    return -1;
+  }
+
+  if (appState.editingGroupId) {
+    if (
+      // candidate element is a sibling in current editing group → return
+      sourceElement?.groupIds.join("") === nextElement?.groupIds.join("")
+    ) {
+      return (
+        getTargetIndexAccountingForBinding(
+          nextElement,
+          elements,
+          direction,
+          scene,
+        ) ?? candidateIndex
+      );
+    } else if (!nextElement?.groupIds.includes(appState.editingGroupId)) {
+      // candidate element is outside current editing group → prevent
+      return -1;
+    }
+  }
+
+  if (
+    !containingFrame &&
+    (nextElement.frameId || isFrameLikeElement(nextElement))
+  ) {
+    const frameElements = getContiguousFrameRangeElements(
+      elements,
+      nextElement.frameId || nextElement.id,
+    );
+    return direction === "left"
+      ? elements.indexOf(frameElements[0])
+      : elements.indexOf(frameElements[frameElements.length - 1]);
+  }
+
+  if (!nextElement.groupIds.length) {
+    return (
+      getTargetIndexAccountingForBinding(
+        nextElement,
+        elements,
+        direction,
+        scene,
+      ) ?? candidateIndex
+    );
+  }
+
+  const siblingGroupId = appState.editingGroupId
+    ? nextElement.groupIds[
+        nextElement.groupIds.indexOf(appState.editingGroupId) - 1
+      ]
+    : nextElement.groupIds[nextElement.groupIds.length - 1];
+
+  const elementsInSiblingGroup = getElementsInGroup(elements, siblingGroupId);
+
+  if (elementsInSiblingGroup.length) {
+    // assumes getElementsInGroup() returned elements are sorted
+    // by zIndex (ascending)
+    return direction === "left"
+      ? elements.indexOf(elementsInSiblingGroup[0])
+      : elements.indexOf(
+          elementsInSiblingGroup[elementsInSiblingGroup.length - 1],
+        );
+  }
+
+  return candidateIndex;
+};
+
+const getTargetElementsMap = <T extends ExcalidrawElement>(
+  elements: readonly T[],
+  indices: number[],
+) => {
+  return indices.reduce((acc, index) => {
+    const element = elements[index];
+    acc.set(element.id, element);
+    return acc;
+  }, new Map<string, ExcalidrawElement>());
+};
+
+const hasSameElementIds = (
+  prevElements: readonly ExcalidrawElement[],
+  nextElements: readonly ExcalidrawElement[],
+) => {
+  if (prevElements.length !== nextElements.length) {
+    console.error(
+      "z-index reordering failed: resulting array have different lengths",
+    );
+    return false;
+  }
+
+  const prevElementIdCounts = new Map<ExcalidrawElement["id"], number>();
+  for (const element of prevElements) {
+    prevElementIdCounts.set(
+      element.id,
+      (prevElementIdCounts.get(element.id) || 0) + 1,
+    );
+  }
+
+  for (const element of nextElements) {
+    const count = prevElementIdCounts.get(element.id);
+    if (!count) {
+      console.error(
+        "z-index reordering failed: element id mismatch / duplicate ids",
+      );
+      return false;
+    }
+    prevElementIdCounts.set(element.id, count - 1);
+  }
+
+  return true;
+};
+
+const shiftElementsByOne = (
+  elements: readonly ExcalidrawElement[],
+  appState: AppState,
+  direction: "left" | "right",
+  scene: Scene,
+) => {
+  const originalElements = elements;
+  const indicesToMove = getIndicesToMove(elements, appState);
+  const targetElementsMap = getTargetElementsMap(elements, indicesToMove);
+
+  let groupedIndices = toContiguousGroups(indicesToMove);
+
+  if (direction === "right") {
+    groupedIndices = groupedIndices.reverse();
+  }
+
+  const selectedFrames = new Set<ExcalidrawFrameLikeElement["id"]>(
+    indicesToMove
+      .filter((idx) => isFrameLikeElement(elements[idx]))
+      .map((idx) => elements[idx].id),
+  );
+
+  groupedIndices.forEach((indices, i) => {
+    const leadingIndex = indices[0];
+    const trailingIndex = indices[indices.length - 1];
+    const boundaryIndex = direction === "left" ? leadingIndex : trailingIndex;
+
+    const containingFrame = indices.some((idx) => {
+      const el = elements[idx];
+      return el.frameId && selectedFrames.has(el.frameId);
+    })
+      ? null
+      : elements[boundaryIndex]?.frameId;
+
+    const targetIndex = getTargetIndex(
+      appState,
+      elements,
+      boundaryIndex,
+      direction,
+      containingFrame,
+      scene,
+    );
+
+    if (targetIndex === -1 || boundaryIndex === targetIndex) {
+      return;
+    }
+
+    const leadingElements =
+      direction === "left"
+        ? elements.slice(0, targetIndex)
+        : elements.slice(0, leadingIndex);
+    const targetElements = elements.slice(leadingIndex, trailingIndex + 1);
+    const displacedElements =
+      direction === "left"
+        ? elements.slice(targetIndex, leadingIndex)
+        : elements.slice(trailingIndex + 1, targetIndex + 1);
+    const trailingElements =
+      direction === "left"
+        ? elements.slice(trailingIndex + 1)
+        : elements.slice(targetIndex + 1);
+
+    elements =
+      direction === "left"
+        ? [
+            ...leadingElements,
+            ...targetElements,
+            ...displacedElements,
+            ...trailingElements,
+          ]
+        : [
+            ...leadingElements,
+            ...displacedElements,
+            ...targetElements,
+            ...trailingElements,
+          ];
+  });
+
+  if (!hasSameElementIds(originalElements, elements)) {
+    return originalElements;
+  }
+
+  syncMovedIndices(elements, targetElementsMap);
+
+  return elements;
+};
+
+const shiftElementsToEnd = (
+  elements: readonly ExcalidrawElement[],
+  appState: AppState,
+  direction: "left" | "right",
+  containingFrame: ExcalidrawFrameLikeElement["id"] | null,
+  elementsToBeMoved?: readonly ExcalidrawElement[],
+) => {
+  const indicesToMove = getIndicesToMove(elements, appState, elementsToBeMoved);
+
+  // Nothing to move (e.g. `elementsToBeMoved` is empty because all selected
+  // elements were frame children handled in a prior pass). Bail out early —
+  // otherwise `leadingIndex`/`trailingIndex` below resolve to `undefined` and
+  // the resulting `slice()` calls overlap, duplicating elements.
+  if (indicesToMove.length === 0) {
+    return elements;
+  }
+
+  const targetElementsMap = getTargetElementsMap(elements, indicesToMove);
+  const displacedElements: ExcalidrawElement[] = [];
+
+  let leadingIndex: number | undefined;
+  let trailingIndex: number | undefined;
+  if (direction === "left") {
+    if (containingFrame) {
+      leadingIndex = findIndex(elements, (el) =>
+        isOfTargetFrame(el, containingFrame),
+      );
+    } else if (appState.editingGroupId) {
+      const groupElements = getElementsInGroup(
+        elements,
+        appState.editingGroupId,
+      );
+      if (!groupElements.length) {
+        return elements;
+      }
+      leadingIndex = elements.indexOf(groupElements[0]);
+    } else {
+      leadingIndex = 0;
+    }
+
+    trailingIndex = indicesToMove[indicesToMove.length - 1];
+  } else {
+    if (containingFrame) {
+      trailingIndex = findLastIndex(elements, (el) =>
+        isOfTargetFrame(el, containingFrame),
+      );
+    } else if (appState.editingGroupId) {
+      const groupElements = getElementsInGroup(
+        elements,
+        appState.editingGroupId,
+      );
+      if (!groupElements.length) {
+        return elements;
+      }
+      trailingIndex = elements.indexOf(groupElements[groupElements.length - 1]);
+    } else {
+      trailingIndex = elements.length - 1;
+    }
+
+    leadingIndex = indicesToMove[0];
+  }
+
+  if (leadingIndex === -1) {
+    leadingIndex = 0;
+  }
+
+  const isValidIndex = (index: number | undefined): index is number => {
+    return isFiniteNumber(index) && index >= 0;
+  };
+
+  if (
+    !isValidIndex(leadingIndex) ||
+    !isValidIndex(trailingIndex) ||
+    leadingIndex > trailingIndex ||
+    indicesToMove.some((index) => index < leadingIndex || index > trailingIndex)
+  ) {
+    return elements;
+  }
+
+  for (let index = leadingIndex; index < trailingIndex + 1; index++) {
+    if (!indicesToMove.includes(index)) {
+      displacedElements.push(elements[index]);
+    }
+  }
+
+  const targetElements = Array.from(targetElementsMap.values());
+  const leadingElements = elements.slice(0, leadingIndex);
+  const trailingElements = elements.slice(trailingIndex + 1);
+  const nextElements =
+    direction === "left"
+      ? [
+          ...leadingElements,
+          ...targetElements,
+          ...displacedElements,
+          ...trailingElements,
+        ]
+      : [
+          ...leadingElements,
+          ...displacedElements,
+          ...targetElements,
+          ...trailingElements,
+        ];
+
+  if (!hasSameElementIds(elements, nextElements)) {
+    return elements;
+  }
+
+  syncMovedIndices(nextElements, targetElementsMap);
+
+  return nextElements;
+};
+
+function shiftElementsAccountingForFrames(
+  allElements: readonly ExcalidrawElement[],
+  appState: AppState,
+  direction: "left" | "right",
+  shiftFunction: (
+    elements: readonly ExcalidrawElement[],
+    appState: AppState,
+    direction: "left" | "right",
+    containingFrame: ExcalidrawFrameLikeElement["id"] | null,
+    elementsToBeMoved?: readonly ExcalidrawElement[],
+  ) => ExcalidrawElement[] | readonly ExcalidrawElement[],
+) {
+  const elementsToMove = arrayToMap(
+    getSelectedElements(allElements, appState, {
+      includeBoundTextElement: true,
+      includeElementsInFrames: true,
+    }),
+  );
+
+  const frameAwareContiguousElementsToMove: {
+    regularElements: ExcalidrawElement[];
+    frameChildren: Map<ExcalidrawFrameLikeElement["id"], ExcalidrawElement[]>;
+  } = { regularElements: [], frameChildren: new Map() };
+
+  const fullySelectedFrames = new Set<ExcalidrawFrameLikeElement["id"]>();
+
+  for (const element of allElements) {
+    if (elementsToMove.has(element.id) && isFrameLikeElement(element)) {
+      fullySelectedFrames.add(element.id);
+    }
+  }
+
+  for (const element of allElements) {
+    if (elementsToMove.has(element.id)) {
+      if (
+        isFrameLikeElement(element) ||
+        (element.frameId && fullySelectedFrames.has(element.frameId))
+      ) {
+        frameAwareContiguousElementsToMove.regularElements.push(element);
+      } else if (!element.frameId) {
+        frameAwareContiguousElementsToMove.regularElements.push(element);
+      } else {
+        const frameChildren =
+          frameAwareContiguousElementsToMove.frameChildren.get(
+            element.frameId,
+          ) || [];
+        frameChildren.push(element);
+        frameAwareContiguousElementsToMove.frameChildren.set(
+          element.frameId,
+          frameChildren,
+        );
+      }
+    }
+  }
+
+  let nextElements = allElements;
+
+  const frameChildrenSets = Array.from(
+    frameAwareContiguousElementsToMove.frameChildren.entries(),
+  );
+
+  for (const [frameId, children] of frameChildrenSets) {
+    nextElements = shiftFunction(
+      nextElements,
+      appState,
+      direction,
+      frameId,
+      children,
+    );
+  }
+
+  return shiftFunction(
+    nextElements,
+    appState,
+    direction,
+    null,
+    frameAwareContiguousElementsToMove.regularElements,
+  );
+}
+
+// public API
+// -----------------------------------------------------------------------------
+
+export const moveOneLeft = (
+  allElements: readonly ExcalidrawElement[],
+  appState: AppState,
+  scene: Scene,
+) => {
+  return shiftElementsByOne(allElements, appState, "left", scene);
+};
+
+export const moveOneRight = (
+  allElements: readonly ExcalidrawElement[],
+  appState: AppState,
+  scene: Scene,
+) => {
+  return shiftElementsByOne(allElements, appState, "right", scene);
+};
+
+export const moveAllLeft = (
+  allElements: readonly ExcalidrawElement[],
+  appState: AppState,
+) => {
+  return shiftElementsAccountingForFrames(
+    allElements,
+    appState,
+    "left",
+    shiftElementsToEnd,
+  );
+};
+
+export const moveAllRight = (
+  allElements: readonly ExcalidrawElement[],
+  appState: AppState,
+) => {
+  return shiftElementsAccountingForFrames(
+    allElements,
+    appState,
+    "right",
+    shiftElementsToEnd,
+  );
+};

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);
+  });
+});