Merge branch 'master' into mtolmacs/fix/grid-binding

Signed-off-by: Mark Tolmacs <mark@lazycat.hu>

.codesandbox/Dockerfile

@@ -1,4 +1,4 @@
-FROM node:18-bullseye
+FROM node:24-bullseye
 
 # Vite wants to open the browser using `open`, so we
 # need to install those utils.

.github/workflows/autorelease-excalidraw.yml

@@ -9,11 +9,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           fetch-depth: 2
       - name: Setup Node.js
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: 20.x
       - name: Set up publish access

.github/workflows/build-docker.yml

@@ -9,5 +9,5 @@ jobs:
   build-docker:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
       - run: docker build -t excalidraw .

.github/workflows/lint.yml

@@ -7,10 +7,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
       - name: Setup Node.js
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: 20.x
 

.github/workflows/locales-coverage.yml

@@ -10,12 +10,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           token: ${{ secrets.PUSH_TRANSLATIONS_COVERAGE_PAT }}
 
       - name: Setup Node.js
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: 20.x
 

.github/workflows/publish-docker.yml

@@ -11,7 +11,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
       - name: Login to DockerHub
         uses: docker/login-action@465a07811f14bebb1938fbed4728c6a1ff8901fc # v2
         with:

.github/workflows/semantic-pr-title.yml

@@ -6,11 +6,97 @@ on:
       - opened
       - edited
       - synchronize
+      - labeled
+      - unlabeled
 
 jobs:
   semantic:
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
     steps:
       - uses: amannn/action-semantic-pull-request@e32d7e603df1aa1ba07e981f2a23455dee596825 # v5
+        with:
+          requireScope: true
+          scopes: |
+            app
+            editor
+            packages/excalidraw
+            packages/utils
+            docker
+            repo
+          ignoreLabels: |
+            skip-semantic-title
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  label-scope:
+    needs: semantic
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Label scoped PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          scope_labels=(s-app s-editor s-package)
+
+          readarray -t desired_labels < <(
+            node <<'NODE'
+          const title = process.env.PR_TITLE;
+          const match = title.match(/^[a-z]+(?:\(([^)]+)\))?!?:/i);
+          const scopes = match?.[1]?.split(",").map((scope) => scope.trim()) ?? [];
+          const labels = new Set();
+
+          for (const scope of scopes) {
+            if (scope === "app") {
+              labels.add("s-app");
+            } else if (scope === "editor") {
+              labels.add("s-editor");
+            } else if (scope.startsWith("packages/")) {
+              labels.add("s-package");
+            }
+          }
+
+          process.stdout.write([...labels].join("\n"));
+          NODE
+          )
+
+          should_apply_label() {
+            local label="$1"
+
+            for desired_label in "${desired_labels[@]}"; do
+              if [[ "$desired_label" == "$label" ]]; then
+                return 0
+              fi
+            done
+
+            return 1
+          }
+
+          for label in "${scope_labels[@]}"; do
+            if ! should_apply_label "$label"; then
+              gh api \
+                --method DELETE \
+                "repos/${REPOSITORY}/issues/${PR_NUMBER}/labels/${label}" \
+                --silent 2>/dev/null || true
+            fi
+          done
+
+          for label in "${desired_labels[@]}"; do
+            if ! gh api \
+              --method POST \
+              "repos/${REPOSITORY}/issues/${PR_NUMBER}/labels" \
+              --field "labels[]=${label}" \
+              --silent; then
+              echo "::warning::Could not apply ${label}. The workflow token likely does not have issues:write permission for this PR."
+            fi
+          done

.github/workflows/sentry-production.yml

@@ -9,9 +9,9 @@ jobs:
   sentry:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
       - name: Setup Node.js
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: 20.x
       - name: Install and build

.github/workflows/size-limit.yml

@@ -10,9 +10,9 @@ jobs:
       CI_JOB_NUMBER: 1
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
       - name: Setup Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: 20.x
       - name: Install in packages/excalidraw

.github/workflows/test-coverage-pr.yml

@@ -10,9 +10,9 @@ jobs:
       pull-requests: write
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
       - name: "Install Node"
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: "20.x"
       - name: "Install Deps"

.github/workflows/test.yml

@@ -8,9 +8,9 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: 20.x
       - name: Install and test

Dockerfile

@@ -1,4 +1,4 @@
-FROM --platform=${BUILDPLATFORM} node:18 AS build
+FROM --platform=${BUILDPLATFORM} node:24@sha256:8530f76a96d88820d288761f022e318970dda93d01536919fbc16076b7983e63 AS build
 
 WORKDIR /opt/node_app
 
@@ -7,13 +7,13 @@ COPY . .
 # do not ignore optional dependencies:
 # Error: Cannot find module @rollup/rollup-linux-x64-gnu
 RUN --mount=type=cache,target=/root/.cache/yarn \
-    npm_config_target_arch=${TARGETARCH} yarn --network-timeout 600000
+    npm_config_target_arch=${TARGETARCH} yarn --frozen-lockfile --network-timeout 600000
 
 ARG NODE_ENV=production
 
 RUN npm_config_target_arch=${TARGETARCH} yarn build:app:docker
 
-FROM --platform=${TARGETPLATFORM} nginx:1.27-alpine
+FROM nginx:stable-alpine-slim@sha256:2c605dbeab79a6b2a63340474fe58119d0ef95bdc4b1f41df0aa689659b3d13b
 
 COPY --from=build /opt/node_app/excalidraw-app/build /usr/share/nginx/html
 

dev-docs/docs/codebase/transactions.mdx

@@ -1,125 +0,0 @@
-# Transactions
-
-Transactions let many live scene updates render immediately while still committing a single durable history entry.
-
-Typical use case:
-
-- AI streaming emits many `NEVER` updates for real-time feedback.
-- Those updates advance the live scene and store snapshot, but do not create undo history.
-- A transaction records the intended logical delta separately, then commits one synthetic durable increment at the end.
-
-## Key Files
-
-### `packages/excalidraw/transaction/`
-
-- `transaction.ts`
-  - `Transaction` is the per-tx instance.
-  - `updateScene()` applies live updates with `captureUpdate: NEVER`.
-  - `updateElements()` is a typed partial-patch helper over `updateScene()`.
-  - `commit()` builds synthetic snapshots and commits one durable entry.
-  - `cancel()` ends the tx without committing history.
-- `ledger.ts`
-  - `TransactionLedger` keeps per-element baseline, target, and touched props across tx steps.
-  - `buildSyntheticSnapshots()` reconciles tx intent with the live scene using `live-wins-per-prop`.
-- `undoOverridePlanner.ts`
-  - Tracks tx intermediate values.
-  - Produces undo override candidates for regular user history entries that were recorded while a tx was active.
-- `manager.ts`
-  - Owns tx lifecycle state and active-tx priority.
-  - Injects tx undo markers into durable deltas at record time.
-  - Resolves effective history deltas at undo/redo time.
-- `diff.ts` / `types.ts`
-  - Shared diff helpers and transaction-specific types.
-
-### `packages/element/src/store.ts`
-
-- `store.commitSyntheticIncrement()`
-  - Builds `StoreSnapshot -> StoreChange -> StoreDelta` from logical before/after snapshots.
-  - Commits the synthetic durable increment immediately through an isolated path.
-  - Does not flush unrelated pending micro actions.
-- `StoreDelta.markers`
-  - Carries extra history markers such as `txUndoOverrides`.
-
-### `packages/excalidraw/history.ts`
-
-- `onBeforeRecord()`
-  - Lets the transaction manager attach markers before a durable delta becomes a history entry.
-- `setEffectiveDeltaResolver()`
-  - Lets the transaction manager rewrite a history delta at undo/redo time before it is applied.
-
-## Flow
-
-1. Caller creates a transaction.
-2. `tx.updateScene()` applies live updates with `NEVER`.
-3. The ledger records net element changes; appState intent is accumulated separately.
-4. Regular user durable edits that happen while the tx is active may receive tx undo markers.
-5. `tx.commit()` asks the ledger for logical before/after snapshots and calls `store.commitSyntheticIncrement()`.
-6. Undo/redo later uses the manager's effective-delta resolver to decide whether ended tx markers should patch the baseline of a regular history entry.
-
-Result:
-
-- live rendering stays immediate;
-- one tx still produces one durable history entry;
-- interleaved regular edits can undo back to the correct pre-tx baseline.
-
-## Undo Examples
-
-### Interleaved Regular Edit
-
-1. Baseline: `rect = (x: 0, stroke: black)`
-2. Tx updates it live to `(x: 200, stroke: red)` with `NEVER`
-3. User makes a regular durable edit: `(x: 200, stroke: purple)`
-4. Tx commits; live stays purple
-
-The user history entry was recorded while the tx was active, so its local baseline is `red`.
-If undo later runs after the tx has ended, restoring `red` is wrong: the correct pre-tx baseline is `black`.
-
-To fix this:
-
-- record-time attaches a tx undo marker to the user history entry
-- perform-time checks whether the tx has already ended
-- if ended, the effective delta is patched so undo restores `black` instead of `red`
-
-### Active Tx vs Ended Tx
-
-Using the same example:
-
-- if the user undoes while the tx is still active, the marker stays inactive and undo restores the tx intermediate value (`red`)
-- if the user undoes after the tx has ended, the marker becomes active and undo restores the pre-tx baseline (`black`)
-
-So markers are recorded early, but applied conditionally.
-
-## AppState
-
-Elements use ledger snapshots. AppState does not.
-
-The transaction instead keeps:
-
-- `initialAppState`: observed appState at tx start
-- `accumulatedAppState`: merged caller intent from `tx.updateScene({ appState })`
-
-At commit, the transaction computes the final appState patch and passes it into `store.commitSyntheticIncrement()`.
-
-## Example
-
-```ts
-const tx = app.transactionManager.create();
-
-tx.updateScene({ elements: updatedElementsA });
-tx.updateScene({ elements: updatedElementsB });
-tx.updateElements({
-  elements: [
-    { id: "rect-1", type: "rectangle", updates: { strokeColor: "#f00" } },
-    { id: "rect-2", type: "rectangle", updates: { x: 120 } },
-  ],
-});
-
-tx.commit();
-```
-
-## Notes
-
-- `commit()` and `cancel()` are idempotent.
-- `updateScene()` and `updateElements()` throw after the tx has ended.
-- Conflict handling inside synthetic snapshots is fixed to `live-wins-per-prop`.
-- Multi-tx interleaving is supported through manager-owned lifecycle tracking and active-tx priority.

excalidraw-app/data/LocalData.ts

@@ -26,7 +26,6 @@ import {
   get,
 } from "idb-keyval";
 
-import { appJotaiStore, atom } from "excalidraw-app/app-jotai";
 import { getNonDeletedElements } from "@excalidraw/element";
 
 import type { LibraryPersistedData } from "@excalidraw/excalidraw/data/library";
@@ -39,6 +38,7 @@ import type {
 } from "@excalidraw/excalidraw/types";
 import type { MaybePromise } from "@excalidraw/common/utility-types";
 
+import { appJotaiStore, atom } from "../app-jotai";
 import { SAVE_TO_LOCAL_STORAGE_TIMEOUT, STORAGE_KEYS } from "../app_constants";
 
 import { FileManager } from "./FileManager";

excalidraw-app/vite.config.mts

@@ -75,6 +75,13 @@ export default defineConfig(({ mode }) => {
           find: /^@excalidraw\/utils\/(.*?)/,
           replacement: path.resolve(__dirname, "../packages/utils/src/$1"),
         },
+        {
+          find: /^@excalidraw\/fractional-indexing$/,
+          replacement: path.resolve(
+            __dirname,
+            "../packages/fractional-indexing/src/index.ts",
+          ),
+        },
       ],
     },
     build: {

package.json

@@ -56,7 +56,8 @@
     "build:element": "yarn --cwd ./packages/element build:esm",
     "build:excalidraw": "yarn --cwd ./packages/excalidraw build:esm",
     "build:math": "yarn --cwd ./packages/math build:esm",
-    "build:packages": "yarn build:common && yarn build:math && yarn build:element && yarn build:excalidraw",
+    "build:fractional-indexing": "yarn --cwd ./packages/fractional-indexing build:esm",
+    "build:packages": "yarn build:common && yarn build:fractional-indexing && yarn build:math && yarn build:element && yarn build:excalidraw",
     "build:version": "yarn --cwd ./excalidraw-app build:version",
     "build": "yarn --cwd ./excalidraw-app build",
     "build:preview": "yarn --cwd ./excalidraw-app build:preview",

packages/common/src/constants.ts

@@ -337,9 +337,10 @@ 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_MAX_IMAGE_WIDTH_OR_HEIGHT = 1440;
-
-export const MAX_ALLOWED_FILE_BYTES = 4 * 1024 * 1024;
+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"?>

packages/common/src/points.ts

@@ -1,4 +1,5 @@
 import {
+  pointFrom,
   pointFromPair,
   type GlobalPoint,
   type LocalPoint,
@@ -69,12 +70,12 @@ export const getGridPoint = (
   x: number,
   y: number,
   gridSize: NullableGridSize,
-): [number, number] => {
+): GlobalPoint => {
   if (gridSize) {
-    return [
+    return pointFrom<GlobalPoint>(
       Math.round(x / gridSize) * gridSize,
       Math.round(y / gridSize) * gridSize,
-    ];
+    );
   }
-  return [x, y];
+  return pointFrom<GlobalPoint>(x, y);
 };

packages/element/package.json

@@ -64,6 +64,7 @@
   },
   "dependencies": {
     "@excalidraw/common": "0.18.0",
-    "@excalidraw/math": "0.18.0"
+    "@excalidraw/math": "0.18.0",
+    "@excalidraw/fractional-indexing": "3.3.0"
   }
 }

packages/element/src/Scene.ts

@@ -338,29 +338,20 @@ export class Scene {
     this.callbacks.clear();
   }
 
-  insertElementAtIndex(element: ExcalidrawElement, index: number) {
-    if (!Number.isFinite(index) || index < 0) {
-      throw new Error(
-        "insertElementAtIndex can only be called with index >= 0",
-      );
-    }
-
-    const nextElements = [
-      ...this.elements.slice(0, index),
-      element,
-      ...this.elements.slice(index),
-    ];
-
-    syncMovedIndices(nextElements, arrayToMap([element]));
-
-    this.replaceAllElements(nextElements);
-  }
-
-  insertElementsAtIndex(elements: ExcalidrawElement[], index: number) {
+  /** 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",
@@ -378,24 +369,9 @@ export class Scene {
     this.replaceAllElements(nextElements);
   }
 
+  /** low-level - generally use app.insertNewElement() */
   insertElement = (element: ExcalidrawElement) => {
-    const index = element.frameId
-      ? this.getElementIndex(element.frameId)
-      : this.elements.length;
-
-    this.insertElementAtIndex(element, index);
-  };
-
-  insertElements = (elements: ExcalidrawElement[]) => {
-    if (!elements.length) {
-      return;
-    }
-
-    const index = elements[0]?.frameId
-      ? this.getElementIndex(elements[0].frameId)
-      : this.elements.length;
-
-    this.insertElementsAtIndex(elements, index);
+    this.insertElementsAtIndex([element], null);
   };
 
   getElementIndex(elementId: string) {

packages/element/src/binding.ts

@@ -1,6 +1,7 @@
 import {
   arrayToMap,
   getFeatureFlag,
+  getGridPoint,
   invariant,
   isTransparent,
 } from "@excalidraw/common";
@@ -22,7 +23,7 @@ import {
 } from "@excalidraw/math";
 
 import type { LineSegment, LocalPoint, Radians } from "@excalidraw/math";
-import type { AppState } from "@excalidraw/excalidraw/types";
+import type { AppState, NullableGridSize } from "@excalidraw/excalidraw/types";
 import type { MapEntry, Mutable } from "@excalidraw/common/utility-types";
 import type { Bounds } from "@excalidraw/common";
 
@@ -154,6 +155,7 @@ export const bindOrUnbindBindingElement = (
     altKey?: boolean;
     angleLocked?: boolean;
     initialBinding?: boolean;
+    gridSize?: NullableGridSize;
   },
 ) => {
   const { start, end } = getBindingStrategyForDraggingBindingElementEndpoints(
@@ -170,12 +172,16 @@ export const bindOrUnbindBindingElement = (
     },
   );
 
+  const isMidpointSnappingEnabled =
+    appState.isMidpointSnappingEnabled && !appState.gridModeEnabled;
+
   bindOrUnbindBindingElementEdge(
     arrow,
     start,
     "start",
     scene,
     appState.isBindingEnabled,
+    isMidpointSnappingEnabled,
   );
   bindOrUnbindBindingElementEdge(
     arrow,
@@ -183,6 +189,7 @@ export const bindOrUnbindBindingElement = (
     "end",
     scene,
     appState.isBindingEnabled,
+    isMidpointSnappingEnabled,
   );
   if (start.focusPoint || end.focusPoint) {
     // If the strategy dictates a focus point override, then
@@ -227,6 +234,7 @@ const bindOrUnbindBindingElementEdge = (
   startOrEnd: "start" | "end",
   scene: Scene,
   shouldSnapToOutline = true,
+  isMidpointSnappingEnabled = true,
 ): void => {
   if (mode === null) {
     // null means break the binding
@@ -240,6 +248,7 @@ const bindOrUnbindBindingElementEdge = (
       scene,
       focusPoint,
       shouldSnapToOutline,
+      isMidpointSnappingEnabled,
     );
   }
 };
@@ -593,6 +602,7 @@ export const getBindingStrategyForDraggingBindingElementEndpoints = (
     finalize?: boolean;
     initialBinding?: boolean;
     zoom?: AppState["zoom"];
+    gridSize?: NullableGridSize;
   },
 ): { start: BindingStrategy; end: BindingStrategy } => {
   if (getFeatureFlag("COMPLEX_BINDINGS")) {
@@ -633,6 +643,7 @@ const getBindingStrategyForDraggingBindingElementEndpoints_simple = (
     finalize?: boolean;
     initialBinding?: boolean;
     zoom?: AppState["zoom"];
+    gridSize?: NullableGridSize;
   },
 ): { start: BindingStrategy; end: BindingStrategy } => {
   const startIdx = 0;
@@ -695,7 +706,9 @@ const getBindingStrategyForDraggingBindingElementEndpoints_simple = (
     elementsMap,
   );
   const hit = getHoveredElementForBinding(
-    globalPoint,
+    opts?.angleLocked || appState.gridModeEnabled
+      ? pointFrom<GlobalPoint>(scenePointerX, scenePointerY)
+      : globalPoint,
     elements,
     elementsMap,
     maxBindingDistance_simple(appState.zoom),
@@ -734,12 +747,11 @@ const getBindingStrategyForDraggingBindingElementEndpoints_simple = (
     });
 
   // Handle outside-outside binding to the same element
-  if (otherBinding && otherBinding.elementId === hit?.id) {
-    invariant(
-      !opts?.newArrow || appState.selectedLinearElement?.initialState.origin,
-      "appState.selectedLinearElement.initialState.origin must be defined for new arrows",
-    );
-
+  if (
+    otherBinding &&
+    otherBinding.elementId === hit?.id &&
+    (!opts?.newArrow || appState.selectedLinearElement?.initialState.origin)
+  ) {
     return {
       start: {
         mode: "inside",
@@ -748,7 +760,11 @@ const getBindingStrategyForDraggingBindingElementEndpoints_simple = (
           ? globalPoint
           : // NOTE: Can only affect the start point because new arrows always drag the end point
           opts?.newArrow
-          ? appState.selectedLinearElement!.initialState.origin!
+          ? getGridPoint(
+              appState.selectedLinearElement!.initialState.origin![0],
+              appState.selectedLinearElement!.initialState.origin![1],
+              opts.gridSize as NullableGridSize,
+            )
           : LinearElementEditor.getPointAtIndexGlobalCoordinates(
               arrow,
               0,
@@ -807,12 +823,27 @@ const getBindingStrategyForDraggingBindingElementEndpoints_simple = (
           focusPoint:
             projectFixedPointOntoDiagonal(
               arrow,
-              globalPoint,
+              opts?.angleLocked || appState.gridModeEnabled
+                ? snapBoundPointToGrid(
+                    pointFrom<GlobalPoint>(scenePointerX, scenePointerY),
+                    hit,
+                    elementsMap,
+                    appState.gridSize as NullableGridSize,
+                    arrow,
+                    LinearElementEditor.getPointAtIndexGlobalCoordinates(
+                      arrow,
+                      startDragged ? 1 : -2,
+                      elementsMap,
+                    ),
+                  )
+                : globalPoint,
               hit,
               startDragged ? "start" : "end",
               elementsMap,
               appState.zoom,
-              appState.isMidpointSnappingEnabled,
+              appState.isMidpointSnappingEnabled &&
+                !opts?.angleLocked &&
+                !appState.gridModeEnabled,
             ) || globalPoint,
         }
     : { mode: null };
@@ -857,7 +888,7 @@ const getBindingStrategyForDraggingBindingElementEndpoints_simple = (
               startDragged ? "end" : "start",
               elementsMap,
               appState.zoom,
-              appState.isMidpointSnappingEnabled,
+              false,
             ) || otherEndpoint,
         }
       : { mode: undefined }
@@ -1022,6 +1053,7 @@ export const bindBindingElement = (
   scene: Scene,
   focusPoint?: GlobalPoint,
   shouldSnapToOutline = true,
+  isMidpointSnappingEnabled = true,
 ): void => {
   const elementsMap = scene.getNonDeletedElementsMap();
 
@@ -1037,6 +1069,7 @@ export const bindBindingElement = (
         startOrEnd,
         elementsMap,
         shouldSnapToOutline,
+        isMidpointSnappingEnabled,
       ),
     };
   } else {
@@ -1741,6 +1774,92 @@ const extractBinding = (
   };
 };
 
+/**
+ * Snaps a bound arrow endpoint to the grid on the axis parallel to the
+ * bindable element's side, while preserving the binding gap distance on the
+ * perpendicular axis. In other words, the grid axis closest to the side's
+ * perpendicular (normal) is used as the snap axis and the other axis is kept at
+ * the binding gap distance.
+ */
+const snapBoundPointToGrid = (
+  outlinePoint: GlobalPoint,
+  bindableElement: ExcalidrawBindableElement,
+  elementsMap: ElementsMap,
+  gridSize: NullableGridSize,
+  arrowElement: ExcalidrawArrowElement,
+  adjacentPoint?: GlobalPoint,
+): GlobalPoint => {
+  if (!gridSize) {
+    return outlinePoint;
+  }
+
+  const aabb = aabbForElement(bindableElement, elementsMap);
+  // For ellipses and diamonds use the arrow's incoming direction instead of
+  // the position-based heading, which can give the wrong axis when the
+  // outline point is near a cardinal zone or an angled diamond face.
+  const heading =
+    adjacentPoint &&
+    (bindableElement.type === "ellipse" || bindableElement.type === "diamond")
+      ? vectorToHeading(vectorFromPoint(adjacentPoint, outlinePoint))
+      : headingForPointFromElement(bindableElement, aabb, outlinePoint);
+
+  const normalLocal = pointFrom<GlobalPoint>(heading[0], heading[1]);
+  const normalGlobal = pointRotateRads(
+    normalLocal,
+    pointFrom<GlobalPoint>(0, 0),
+    bindableElement.angle,
+  );
+
+  const bindingGap = getBindingGap(bindableElement, arrowElement);
+  const extent =
+    Math.max(bindableElement.width, bindableElement.height) + bindingGap * 2;
+  const center = getCenterForBounds(aabb);
+
+  const absNX = Math.abs(normalGlobal[0]);
+  const absNY = Math.abs(normalGlobal[1]);
+  if (absNX >= absNY) {
+    // Global X is closest to the perpendicular so snap Y, intersect horizontal line
+    const [, snappedY] = getGridPoint(
+      outlinePoint[0],
+      outlinePoint[1],
+      gridSize,
+    );
+    const intersector = lineSegment<GlobalPoint>(
+      pointFrom<GlobalPoint>(center[0] - extent, snappedY),
+      pointFrom<GlobalPoint>(center[0] + extent, snappedY),
+    );
+    const intersection = intersectElementWithLineSegment(
+      bindableElement,
+      elementsMap,
+      intersector,
+      bindingGap,
+    ).sort(
+      (a, b) =>
+        pointDistanceSq(a, outlinePoint) - pointDistanceSq(b, outlinePoint),
+    )[0];
+
+    return intersection ?? pointFrom<GlobalPoint>(outlinePoint[0], snappedY);
+  }
+
+  // Global Y is closest to the perpendicular so snap X, intersect vertical line
+  const [snappedX] = getGridPoint(outlinePoint[0], outlinePoint[1], gridSize);
+  const intersector = lineSegment<GlobalPoint>(
+    pointFrom<GlobalPoint>(snappedX, center[1] - extent),
+    pointFrom<GlobalPoint>(snappedX, center[1] + extent),
+  );
+  const intersection = intersectElementWithLineSegment(
+    bindableElement,
+    elementsMap,
+    intersector,
+    bindingGap,
+  ).sort(
+    (a, b) =>
+      pointDistanceSq(a, outlinePoint) - pointDistanceSq(b, outlinePoint),
+  )[0];
+
+  return intersection ?? pointFrom<GlobalPoint>(snappedX, outlinePoint[1]);
+};
+
 const elementArea = (element: ExcalidrawBindableElement) =>
   element.width * element.height;
 
@@ -1943,9 +2062,9 @@ export const calculateFixedPointForElbowArrowBinding = (
   return {
     fixedPoint: normalizeFixedPoint([
       (nonRotatedSnappedGlobalPoint[0] - hoveredElement.x) /
-        hoveredElement.width,
+        Math.max(hoveredElement.width, PRECISION),
       (nonRotatedSnappedGlobalPoint[1] - hoveredElement.y) /
-        hoveredElement.height,
+        Math.max(hoveredElement.height, PRECISION),
     ]),
   };
 };
@@ -1976,9 +2095,11 @@ export const calculateFixedPointForNonElbowArrowBinding = (
 
   // Calculate the ratio relative to the element's bounds
   const fixedPointX =
-    (nonRotatedPoint[0] - hoveredElement.x) / hoveredElement.width;
+    (nonRotatedPoint[0] - hoveredElement.x) /
+    Math.max(hoveredElement.width, PRECISION);
   const fixedPointY =
-    (nonRotatedPoint[1] - hoveredElement.y) / hoveredElement.height;
+    (nonRotatedPoint[1] - hoveredElement.y) /
+    Math.max(hoveredElement.height, PRECISION);
 
   return {
     fixedPoint: normalizeFixedPoint([fixedPointX, fixedPointY]),

packages/element/src/collision.ts

@@ -61,6 +61,8 @@ import { distanceToElement } from "./distance";
 
 import { getBindingGap } from "./binding";
 
+import { hasBackground } from "./comparisons";
+
 import type {
   ElementsMap,
   ExcalidrawArrowElement,
@@ -83,7 +85,7 @@ export const shouldTestInside = (element: ExcalidrawElement) => {
   }
 
   const isDraggableFromInside =
-    !isTransparent(element.backgroundColor) ||
+    (hasBackground(element.type) && !isTransparent(element.backgroundColor)) ||
     hasBoundTextElement(element) ||
     isIframeLikeElement(element) ||
     isTextElement(element);
@@ -324,7 +326,10 @@ export const getAllHoveredElementAtPoint = (
     ) {
       candidateElements.push(element);
 
-      if (!isTransparent(element.backgroundColor)) {
+      if (
+        hasBackground(element.type) &&
+        !isTransparent(element.backgroundColor)
+      ) {
         break;
       }
     }

packages/element/src/duplicate.ts

@@ -111,6 +111,9 @@ export const duplicateElements = (
          * user interaction.
          */
         type: "everything";
+        // TODO remove/review this once we add frame children order migration
+        // and invariant checks
+        preserveFrameChildrenOrder?: boolean;
       }
     | {
         /**
@@ -170,6 +173,8 @@ export const duplicateElements = (
     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") {
@@ -250,6 +255,9 @@ export const duplicateElements = (
     elementsWithDuplicates.splice(index + 1, 0, ...castArray(elements));
   };
 
+  // main
+  // ---------------------------------------------------------------------------
+
   const frameIdsToDuplicate = new Set(
     elements
       .filter(
@@ -274,7 +282,7 @@ export const duplicateElements = (
     if (groupId) {
       const groupElements = getElementsInGroup(elements, groupId).flatMap(
         (element) =>
-          isFrameLikeElement(element)
+          isFrameLikeElement(element) && !preserveFrameChildrenOrder
             ? [...getFrameChildren(elements, element.id), element]
             : [element],
       );
@@ -290,13 +298,25 @@ export const duplicateElements = (
     // frame duplication
     // -------------------------------------------------------------------------
 
-    if (element.frameId && frameIdsToDuplicate.has(element.frameId)) {
+    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) => {

packages/element/src/elbowArrow.ts

@@ -2124,8 +2124,8 @@ const normalizeArrowElementUpdate = (
     offsetY < -MAX_POS ||
     offsetY > MAX_POS ||
     offsetX + points[points.length - 1][0] < -MAX_POS ||
-    offsetY + points[points.length - 1][0] > MAX_POS ||
-    offsetX + points[points.length - 1][1] < -MAX_POS ||
+    offsetX + points[points.length - 1][0] > MAX_POS ||
+    offsetY + points[points.length - 1][1] < -MAX_POS ||
     offsetY + points[points.length - 1][1] > MAX_POS
   ) {
     console.error(

packages/element/src/fractionalIndex.ts

@@ -1,7 +1,10 @@
-import { generateNKeysBetween } from "fractional-indexing";
-
 import { arrayToMap } from "@excalidraw/common";
 
+import {
+  validateOrderKey,
+  generateNKeysBetween,
+} from "@excalidraw/fractional-indexing";
+
 import { mutateElement, newElementWith } from "./mutateElement";
 import { getBoundTextElement } from "./textElement";
 import { hasBoundTextElement } from "./typeChecks";
@@ -382,6 +385,13 @@ const isValidFractionalIndex = (
     return false;
   }
 
+  try {
+    // Format validation
+    validateOrderKey(index);
+  } catch {
+    return false;
+  }
+
   if (predecessor && successor) {
     return predecessor < index && index < successor;
   }

packages/element/src/frame.ts

@@ -19,9 +19,11 @@ import {
   getElementAbsoluteCoords,
   doBoundsIntersect,
   getElementBounds,
+  boundsContainBounds,
 } from "./bounds";
 import { mutateElement } from "./mutateElement";
 import { getBoundTextElement, getContainerElement } from "./textElement";
+import { syncMovedIndices } from "./fractionalIndex";
 import {
   isFrameElement,
   isFrameLikeElement,
@@ -101,8 +103,9 @@ export const isElementContainingFrame = (
   frame: ExcalidrawFrameLikeElement,
   elementsMap: ElementsMap,
 ) => {
-  return getElementsWithinSelection([frame], element, elementsMap).some(
-    (e) => e.id === frame.id,
+  return boundsContainBounds(
+    getElementBounds(element, elementsMap),
+    getElementBounds(frame, elementsMap),
   );
 };
 
@@ -489,10 +492,44 @@ export const filterElementsEligibleAsFrameChildren = (
   return eligibleElements;
 };
 
+export const getCommonFrameId = (elements: readonly ExcalidrawElement[]) => {
+  let commonFrameId: ExcalidrawElement["frameId"] | undefined;
+
+  for (const element of elements) {
+    if (isFrameLikeElement(element) || !element.frameId) {
+      return null;
+    }
+
+    if (commonFrameId === undefined) {
+      commonFrameId = element.frameId;
+    } else if (commonFrameId !== element.frameId) {
+      return null;
+    }
+  }
+
+  return commonFrameId ?? null;
+};
+
+export const getFrameChildrenInsertionIndex = (
+  elements: readonly ExcalidrawElement[],
+  frameId: ExcalidrawFrameLikeElement["id"],
+): number | null => {
+  for (let index = elements.length - 1; index >= 0; index--) {
+    const element = elements[index];
+
+    if (element.id === frameId) {
+      return index;
+    } else if (element.frameId === frameId) {
+      return index + 1;
+    }
+  }
+
+  return null;
+};
+
 /**
- * Retains (or repairs for target frame) the ordering invriant where children
- * elements come right before the parent frame:
- * [el, el, child, child, frame, el]
+ * Adds elements and their bound elements to frame. Reorders added elements to
+ * be just below frame, or just above its highest child (whichever is higher).
  *
  * @returns mutated allElements (same data structure)
  */
@@ -500,19 +537,11 @@ export const addElementsToFrame = <T extends ElementsMapOrArray>(
   allElements: T,
   elementsToAdd: NonDeletedExcalidrawElement[],
   frame: ExcalidrawFrameLikeElement,
-  appState: AppState,
 ): T => {
   const elementsMap = arrayToMap(allElements);
-  const currTargetFrameChildrenMap = new Map<ExcalidrawElement["id"], true>();
-  for (const element of allElements.values()) {
-    if (element.frameId === frame.id) {
-      currTargetFrameChildrenMap.set(element.id, true);
-    }
-  }
+  const commonFrameId = getCommonFrameId(elementsToAdd);
 
-  const suppliedElementsToAddSet = new Set(elementsToAdd.map((el) => el.id));
-
-  const finalElementsToAdd: ExcalidrawElement[] = [];
+  const finalElementsToAdd = new Set<ExcalidrawElement>();
 
   const otherFrames = new Set<ExcalidrawFrameLikeElement["id"]>();
 
@@ -523,7 +552,8 @@ export const addElementsToFrame = <T extends ElementsMapOrArray>(
   }
 
   // - add bound text elements if not already in the array
-  // - filter out elements that are already in the frame
+  // - keep elements already in the frame so mixed selections can be reordered
+  //   together
   for (const element of omitGroupsContainingFrameLikes(
     allElements,
     elementsToAdd,
@@ -536,38 +566,68 @@ export const addElementsToFrame = <T extends ElementsMapOrArray>(
       continue;
     }
 
-    // if the element is already in another frame (which is also in elementsToAdd),
-    // it means that frame and children are selected at the same time
-    // => keep original frame membership, do not add to the target frame
-    if (
-      element.frameId &&
-      appState.selectedElementIds[element.id] &&
-      appState.selectedElementIds[element.frameId]
-    ) {
+    if (element.frameId && element.frameId !== frame.id) {
       continue;
     }
 
-    if (!currTargetFrameChildrenMap.has(element.id)) {
-      finalElementsToAdd.push(element);
-    }
+    finalElementsToAdd.add(element);
 
     const boundTextElement = getBoundTextElement(element, elementsMap);
-    if (
-      boundTextElement &&
-      !suppliedElementsToAddSet.has(boundTextElement.id) &&
-      !currTargetFrameChildrenMap.has(boundTextElement.id)
-    ) {
-      finalElementsToAdd.push(boundTextElement);
+    if (boundTextElement && !finalElementsToAdd.has(boundTextElement)) {
+      finalElementsToAdd.add(boundTextElement);
     }
   }
 
   for (const element of finalElementsToAdd) {
-    mutateElement(element, elementsMap, {
-      frameId: frame.id,
-    });
+    // we don't always need to update the element if it's already in the frame,
+    // but we still need to accumulate in finalElementsToAdd so we potentially
+    // reorder them if added together
+    if (element.frameId !== frame.id) {
+      mutateElement(element, elementsMap, {
+        frameId: frame.id,
+      });
+    }
   }
 
-  return allElements;
+  // (re)order elements to be just below the frame,
+  // or just above the highest child if that is higher
+  // (latter case is denormalized order until we migrate)
+  // ---------------------------------------------------------------------------
+
+  if (
+    !finalElementsToAdd.size ||
+    // if all elements to add already belong to the frame, then we don't want to
+    // reorder (case: we're dragging element children within the frame)
+    commonFrameId === frame.id
+  ) {
+    return allElements;
+  }
+
+  const otherElements = Array.from(allElements.values()).filter(
+    (element) => !finalElementsToAdd.has(element),
+  );
+  const insertionIndex = getFrameChildrenInsertionIndex(
+    otherElements,
+    frame.id,
+  );
+
+  if (insertionIndex === null) {
+    return allElements;
+  }
+
+  const reorderedElements = [
+    ...otherElements.slice(0, insertionIndex),
+    ...finalElementsToAdd,
+    ...otherElements.slice(insertionIndex),
+  ];
+
+  syncMovedIndices(reorderedElements, arrayToMap([...finalElementsToAdd]));
+
+  return (
+    Array.isArray(allElements)
+      ? reorderedElements
+      : new Map(reorderedElements.map((element) => [element.id, element]))
+  ) as T;
 };
 
 export const removeElementsFromFrame = (
@@ -621,13 +681,11 @@ export const replaceAllElementsInFrame = <T extends ExcalidrawElement>(
   allElements: readonly T[],
   nextElementsInFrame: ExcalidrawElement[],
   frame: ExcalidrawFrameLikeElement,
-  app: AppClassProperties,
 ): T[] => {
   return addElementsToFrame(
     removeAllElementsFromFrame(allElements, frame),
     nextElementsInFrame,
     frame,
-    app.state,
   ).slice();
 };
 

packages/element/src/linearElementEditor.ts

@@ -359,6 +359,7 @@ export class LinearElementEditor {
       linearElementEditor,
     );
 
+    const angleLocked = shouldRotateWithDiscreteAngle(event);
     LinearElementEditor.movePoints(
       element,
       app.scene,
@@ -370,7 +371,10 @@ export class LinearElementEditor {
       },
       {
         isBindingEnabled: app.state.isBindingEnabled,
-        isMidpointSnappingEnabled: app.state.isMidpointSnappingEnabled,
+        isMidpointSnappingEnabled:
+          app.state.isMidpointSnappingEnabled &&
+          !angleLocked &&
+          !app.state.gridModeEnabled,
       },
     );
     // Set the suggested binding from the updates if available
@@ -427,7 +431,9 @@ export class LinearElementEditor {
                 "start",
                 elementsMap,
                 app.state.zoom,
-                app.state.isMidpointSnappingEnabled,
+                app.state.isMidpointSnappingEnabled &&
+                  !angleLocked &&
+                  !app.state.gridModeEnabled,
               )
             : linearElementEditor.initialState.altFocusPoint,
       },
@@ -486,7 +492,7 @@ export class LinearElementEditor {
           selectedPointsIndices,
         )}) points(0..${
           element.points.length - 1
-        }) lastClickedPoint(${lastClickedPoint})`,
+        }) lastClickedPoint(${lastClickedPoint}) isElbowArrow: ${elbowed}`,
       );
 
       // Fall back to the actual last point as a last resort.
@@ -554,6 +560,8 @@ export class LinearElementEditor {
       linearElementEditor,
     );
 
+    const angleLocked =
+      shouldRotateWithDiscreteAngle(event) && singlePointDragged;
     LinearElementEditor.movePoints(
       element,
       app.scene,
@@ -565,7 +573,10 @@ export class LinearElementEditor {
       },
       {
         isBindingEnabled: app.state.isBindingEnabled,
-        isMidpointSnappingEnabled: app.state.isMidpointSnappingEnabled,
+        isMidpointSnappingEnabled:
+          app.state.isMidpointSnappingEnabled &&
+          !angleLocked &&
+          !app.state.gridModeEnabled,
       },
     );
 
@@ -661,7 +672,9 @@ export class LinearElementEditor {
                 "start",
                 elementsMap,
                 app.state.zoom,
-                app.state.isMidpointSnappingEnabled,
+                app.state.isMidpointSnappingEnabled &&
+                  !angleLocked &&
+                  !app.state.gridModeEnabled,
               )
             : linearElementEditor.initialState.altFocusPoint,
       },
@@ -2139,13 +2152,13 @@ const pointDraggingUpdates = (
 } => {
   const naiveDraggingPoints = new Map(
     selectedPointsIndices.map((pointIndex) => {
+      // NOTE: Avoid stale point index issue potentially caused by elbow
+      // arrows unpredictably changing the number of points during dragging
+      const point = element.points[pointIndex] ?? element.points.at(-1);
       return [
         pointIndex,
         {
-          point: pointFrom<LocalPoint>(
-            element.points[pointIndex][0] + deltaX,
-            element.points[pointIndex][1] + deltaY,
-          ),
+          point: pointFrom<LocalPoint>(point[0] + deltaX, point[1] + deltaY),
           isDragging: true,
         },
       ];
@@ -2176,6 +2189,7 @@ const pointDraggingUpdates = (
       newArrow: !!app.state.newElement,
       angleLocked,
       altKey,
+      gridSize: app.getEffectiveGridSize(),
     },
   );
 

packages/element/src/selection.ts

@@ -34,7 +34,6 @@ import {
   elementOverlapsWithFrame,
   getContainingFrame,
   getFrameChildren,
-  isElementIntersectingFrame,
 } from "./frame";
 
 import { LinearElementEditor } from "./linearElementEditor";
@@ -130,13 +129,24 @@ export const getElementsWithinSelection = (
   const framesInSelection = excludeElementsInFrames
     ? new Set<NonDeletedExcalidrawElement["id"]>()
     : null;
-  let elementsInSelection: NonDeletedExcalidrawElement[] = [];
+  const groups: Record<string, NonDeletedExcalidrawElement[]> = {};
+  const elementsInSelection: Set<NonDeletedExcalidrawElement> = new Set();
 
   for (const element of elements) {
     if (shouldIgnoreElementFromSelection(element)) {
       continue;
     }
 
+    // Track only selectable top-level group members, so ignored elements such
+    // as bound text and locked elements don't affect group selection.
+    const groupId = element.groupIds.at(-1);
+    if (groupId) {
+      if (!groups[groupId]) {
+        groups[groupId] = [];
+      }
+      groups[groupId].push(element);
+    }
+
     const strokeWidth = element.strokeWidth;
     let labelAABB: Bounds | null = null;
     let elementAABB = getElementBounds(element, elementsMap);
@@ -170,7 +180,7 @@ export const getElementsWithinSelection = (
     const associatedFrame = getContainingFrame(element, elementsMap);
     if (
       associatedFrame &&
-      isElementIntersectingFrame(element, associatedFrame, elementsMap)
+      elementOverlapsWithFrame(element, associatedFrame, elementsMap)
     ) {
       const frameAABB = getElementBounds(associatedFrame, elementsMap);
       elementAABB = [
@@ -209,10 +219,9 @@ export const getElementsWithinSelection = (
     if (boundsContainBounds(selectionBounds, commonAABB)) {
       if (framesInSelection && isFrameLikeElement(element)) {
         framesInSelection.add(element.id);
-      } else {
-        elementsInSelection.push(element);
-        continue;
       }
+      elementsInSelection.add(element);
+      continue;
     }
 
     // 2. Handle the case where the label is overlapped by the selection box
@@ -221,7 +230,7 @@ export const getElementsWithinSelection = (
       labelAABB &&
       doBoundsIntersect(selectionBounds, labelAABB)
     ) {
-      elementsInSelection.push(element);
+      elementsInSelection.add(element);
       continue;
     }
 
@@ -311,7 +320,7 @@ export const getElementsWithinSelection = (
           framesInSelection.add(element.id);
         }
 
-        elementsInSelection.push(element);
+        elementsInSelection.add(element);
         continue;
       }
     }
@@ -320,21 +329,41 @@ export const getElementsWithinSelection = (
     //    as it is separately handled in App.
   }
 
-  elementsInSelection = framesInSelection
-    ? excludeElementsFromFrames(elementsInSelection, framesInSelection)
-    : elementsInSelection;
+  if (framesInSelection) {
+    elementsInSelection.forEach((element) => {
+      if (element.frameId && framesInSelection.has(element.frameId)) {
+        elementsInSelection.delete(element);
+      }
+    });
+  }
 
-  elementsInSelection = elementsInSelection.filter((element) => {
-    const containingFrame = getContainingFrame(element, elementsMap);
+  if (boxSelectionMode === "overlap") {
+    Array.from(elementsInSelection).forEach((element) => {
+      const groupId = element.groupIds.at(-1);
+      const group = groupId ? groups[groupId] : null;
 
-    if (containingFrame) {
-      return elementOverlapsWithFrame(element, containingFrame, elementsMap);
-    }
+      group?.forEach((groupElement) => elementsInSelection.add(groupElement));
+    });
+  } else if (boxSelectionMode === "contain") {
+    elementsInSelection.forEach((element) => {
+      // note: currently we only support top-level group handling since
+      // we don't support box selecting while editing the group/subgroup
+      // see https://github.com/excalidraw/excalidraw/pull/11234#issuecomment-4387654451
+      const groupId = element.groupIds.at(-1);
 
-    return true;
-  });
+      const group = groupId ? groups[groupId] : null;
 
-  return elementsInSelection;
+      if (
+        group &&
+        !group.every((groupElement) => elementsInSelection.has(groupElement))
+      ) {
+        elementsInSelection.delete(element);
+      }
+    });
+  }
+
+  // to maintain original order elements (namely for group selection)
+  return elements.filter((element) => elementsInSelection.has(element));
 };
 
 export const getVisibleAndNonSelectedElements = (

packages/element/src/sortElements.ts

@@ -1,59 +1,56 @@
-import { arrayToMapWithIndex } from "@excalidraw/common";
+import { arrayToMap } from "@excalidraw/common";
 
 import type { ExcalidrawElement } from "./types";
 
-const normalizeGroupElementOrder = (elements: readonly ExcalidrawElement[]) => {
-  const origElements: ExcalidrawElement[] = elements.slice();
-  const sortedElements = new Set<ExcalidrawElement>();
-
-  const orderInnerGroups = (
-    elements: readonly ExcalidrawElement[],
-  ): ExcalidrawElement[] => {
-    const firstGroupSig = elements[0]?.groupIds?.join("");
-    const aGroup: ExcalidrawElement[] = [elements[0]];
-    const bGroup: ExcalidrawElement[] = [];
-    for (const element of elements.slice(1)) {
-      if (element.groupIds?.join("") === firstGroupSig) {
-        aGroup.push(element);
-      } else {
-        bGroup.push(element);
-      }
-    }
-    return bGroup.length ? [...aGroup, ...orderInnerGroups(bGroup)] : aGroup;
+const defragmentGroups = (elements: readonly ExcalidrawElement[]) => {
+  const groupIdAtLevel = (element: ExcalidrawElement, level: number) => {
+    return element.groupIds[element.groupIds.length - level - 1];
   };
 
-  const groupHandledElements = new Map<string, true>();
+  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)[] = [];
 
-  origElements.forEach((element, idx) => {
-    if (groupHandledElements.has(element.id)) {
-      return;
-    }
-    if (element.groupIds?.length) {
-      const topGroup = element.groupIds[element.groupIds.length - 1];
-      const groupElements = origElements.slice(idx).filter((element) => {
-        const ret = element?.groupIds?.some((id) => id === topGroup);
-        if (ret) {
-          groupHandledElements.set(element!.id, true);
-        }
-        return ret;
-      });
-
-      for (const elem of orderInnerGroups(groupElements)) {
-        sortedElements.add(elem);
+    for (const element of levelElements) {
+      const groupId = groupIdAtLevel(element, level);
+      if (groupId === undefined) {
+        slots.push(element);
+        continue;
       }
-    } else {
-      sortedElements.add(element);
+      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.size !== elements.length) {
-    console.error("normalizeGroupElementOrder: lost some elements... bailing!");
+  if (sortedElements.length !== elements.length) {
+    console.error("defragmentGroups: lost some elements... bailing!");
     return elements;
   }
 
-  return [...sortedElements];
+  return sortedElements;
 };
 
 /**
@@ -68,39 +65,40 @@ const normalizeGroupElementOrder = (elements: readonly ExcalidrawElement[]) => {
 const normalizeBoundElementsOrder = (
   elements: readonly ExcalidrawElement[],
 ) => {
-  const elementsMap = arrayToMapWithIndex(elements);
+  const elementsMap = arrayToMap(elements);
 
-  const origElements: (ExcalidrawElement | null)[] = elements.slice();
   const sortedElements = new Set<ExcalidrawElement>();
 
-  origElements.forEach((element, idx) => {
-    if (!element) {
-      return;
+  for (const element of elements) {
+    if (sortedElements.has(element)) {
+      continue;
     }
+
     if (element.boundElements?.length) {
       sortedElements.add(element);
-      origElements[idx] = null;
-      element.boundElements.forEach((boundElement) => {
+      for (const boundElement of element.boundElements) {
         const child = elementsMap.get(boundElement.id);
         if (child && boundElement.type === "text") {
-          sortedElements.add(child[0]);
-          origElements[child[1]] = null;
+          sortedElements.add(child);
         }
-      });
-    } else if (element.type === "text" && element.containerId) {
-      const parent = elementsMap.get(element.containerId);
-      if (!parent?.[0].boundElements?.find((x) => x.id === element.id)) {
-        sortedElements.add(element);
-        origElements[idx] = null;
-
-        // if element has a container and container lists it, skip this element
-        // as it'll be taken care of by the container
       }
-    } else {
-      sortedElements.add(element);
-      origElements[idx] = null;
+      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
@@ -117,5 +115,5 @@ const normalizeBoundElementsOrder = (
 export const normalizeElementOrder = (
   elements: readonly ExcalidrawElement[],
 ) => {
-  return normalizeBoundElementsOrder(normalizeGroupElementOrder(elements));
+  return normalizeBoundElementsOrder(defragmentGroups(elements));
 };

packages/element/src/store.ts

@@ -111,67 +111,6 @@ export class Store {
     this.scheduleAction(CaptureUpdateAction.IMMEDIATELY);
   }
 
-  /**
-   * Commits a synthetic durable history entry without changing the live scene.
-   *
-   * Builds StoreSnapshot → StoreChange → StoreDelta from the provided
-   * logical before/after element maps and optional appState patches, then
-   * emits the resulting durable increment immediately through an isolated
-   * path that does not flush pending micro actions.
-   *
-   * appState patches are merged on top of the current observed appState
-   * baseline so only the provided keys participate in the synthetic diff.
-   */
-  public commitSyntheticIncrement(params: {
-    logicalBefore: {
-      elements: SceneElementsMap;
-      appState?: Partial<ObservedAppState>;
-    };
-    logicalAfter: {
-      elements: SceneElementsMap;
-      appState?: Partial<ObservedAppState>;
-    };
-  }): boolean {
-    const { logicalBefore, logicalAfter } = params;
-    const observedAppStateBaseline = this.snapshot.appState;
-    const syntheticAppStateBefore = logicalBefore.appState
-      ? { ...observedAppStateBaseline, ...logicalBefore.appState }
-      : observedAppStateBaseline;
-    const syntheticAppStateAfter = logicalAfter.appState
-      ? { ...observedAppStateBaseline, ...logicalAfter.appState }
-      : observedAppStateBaseline;
-    const didAppStateChange = Delta.isRightDifferent(
-      syntheticAppStateBefore,
-      syntheticAppStateAfter,
-    );
-    const prevSnapshot = StoreSnapshot.create(
-      logicalBefore.elements,
-      syntheticAppStateBefore,
-      {
-        didElementsChange: true,
-        didAppStateChange,
-      },
-    );
-    const nextSnapshot = StoreSnapshot.create(
-      logicalAfter.elements,
-      syntheticAppStateAfter,
-      {
-        didElementsChange: true,
-        didAppStateChange,
-      },
-    );
-    const change = StoreChange.create(prevSnapshot, nextSnapshot);
-    const delta = StoreDelta.calculate(prevSnapshot, nextSnapshot);
-
-    if (delta.isEmpty()) {
-      return false;
-    }
-
-    this.emitIsolatedDurableIncrement(change, delta);
-
-    return true;
-  }
-
   /**
    * Schedule special "micro" actions, to-be executed before the next commit, before it executes a scheduled "macro" action.
    */
@@ -267,7 +206,6 @@ export class Store {
   public clear(): void {
     this.snapshot = StoreSnapshot.empty();
     this.scheduledMacroActions = new Set();
-    this.scheduledMicroActions = [];
   }
 
   /**
@@ -307,24 +245,6 @@ export class Store {
     }
   }
 
-  /**
-   * Emits a synthetic durable increment immediately without draining the
-   * regular micro-action queue.
-   */
-  private emitIsolatedDurableIncrement(change: StoreChange, delta: StoreDelta) {
-    const nextSnapshot = this.applyChangeToSnapshot(change);
-
-    if (!nextSnapshot) {
-      return;
-    }
-
-    try {
-      this.emitDurableIncrement(nextSnapshot, change, delta);
-    } finally {
-      this.snapshot = nextSnapshot;
-    }
-  }
-
   /**
    * Performs change calculation and emits an ephemeral increment.
    *
@@ -571,89 +491,6 @@ export class EphemeralIncrement extends StoreIncrement {
   }
 }
 
-/**
- * Serializable delta marker used to recover pre-tx undo baselines
- * without rewriting history stack entries.
- */
-export type TxUndoOverride = {
-  txId: string;
-  elementId: string;
-  prop: string;
-  expectedInsertedValue: unknown;
-  preTxBaselineValue: unknown;
-  consumedKey: string;
-};
-
-export type StoreDeltaMarkers = {
-  txUndoOverrides?: TxUndoOverride[];
-};
-
-const cloneTxUndoOverride = (override: TxUndoOverride): TxUndoOverride => ({
-  ...override,
-});
-
-const cloneStoreDeltaMarkers = (
-  markers: StoreDeltaMarkers | undefined,
-): StoreDeltaMarkers | undefined =>
-  markers
-    ? {
-        ...markers,
-        txUndoOverrides: markers.txUndoOverrides?.map(cloneTxUndoOverride),
-      }
-    : undefined;
-
-const pruneStoreDeltaMarkers = (delta: StoreDelta) => {
-  const txUndoOverrides = delta.markers?.txUndoOverrides;
-  if (!txUndoOverrides || txUndoOverrides.length === 0) {
-    return;
-  }
-
-  const updatedEntries = delta.elements.updated as Record<
-    string,
-    Delta<Record<string, unknown>>
-  >;
-  const nextTxUndoOverrides = txUndoOverrides.filter((override) => {
-    const updatedEntry = updatedEntries[override.elementId];
-    return (
-      !!updatedEntry &&
-      Object.prototype.hasOwnProperty.call(updatedEntry.inserted, override.prop)
-    );
-  });
-
-  if (nextTxUndoOverrides.length === txUndoOverrides.length) {
-    return;
-  }
-
-  if (nextTxUndoOverrides.length === 0) {
-    delta.markers = undefined;
-    return;
-  }
-
-  delta.markers = {
-    ...delta.markers,
-    txUndoOverrides: nextTxUndoOverrides.map(cloneTxUndoOverride),
-  };
-};
-
-export const mergeStoreDeltaMarkers = (
-  delta: StoreDelta,
-  markers: StoreDeltaMarkers,
-) => {
-  const txUndoOverrides = markers.txUndoOverrides ?? [];
-  if (txUndoOverrides.length === 0) {
-    return;
-  }
-
-  const existing = delta.markers?.txUndoOverrides ?? [];
-  delta.markers = {
-    ...delta.markers,
-    txUndoOverrides: [
-      ...existing.map(cloneTxUndoOverride),
-      ...txUndoOverrides.map(cloneTxUndoOverride),
-    ],
-  };
-};
-
 /**
  * Represents a captured delta by the Store.
  */
@@ -662,7 +499,6 @@ export class StoreDelta {
     public readonly id: string,
     public readonly elements: ElementsDelta,
     public readonly appState: AppStateDelta,
-    public markers?: StoreDeltaMarkers,
   ) {}
 
   /**
@@ -672,16 +508,12 @@ export class StoreDelta {
     elements: ElementsDelta,
     appState: AppStateDelta,
     opts: {
-      id?: string;
-      markers?: StoreDeltaMarkers;
-    } = {},
+      id: string;
+    } = {
+      id: randomId(),
+    },
   ) {
-    return new this(
-      opts.id ?? randomId(),
-      elements,
-      appState,
-      cloneStoreDeltaMarkers(opts.markers),
-    );
+    return new this(opts.id, elements, appState);
   }
 
   /**
@@ -706,12 +538,11 @@ export class StoreDelta {
    * Restore a store delta instance from a DTO.
    */
   public static restore(storeDeltaDTO: DTO<StoreDelta>) {
-    const { id, elements, appState, markers } = storeDeltaDTO;
+    const { id, elements, appState } = storeDeltaDTO;
     return new this(
       id,
       ElementsDelta.restore(elements),
       AppStateDelta.restore(appState),
-      cloneStoreDeltaMarkers(markers),
     );
   }
 
@@ -722,12 +553,11 @@ export class StoreDelta {
     id,
     elements: { added, removed, updated },
     appState: { delta: appStateDelta },
-    markers,
   }: DTO<StoreDelta>) {
     const elements = ElementsDelta.create(added, removed, updated);
     const appState = AppStateDelta.create(appStateDelta);
 
-    return new this(id, elements, appState, cloneStoreDeltaMarkers(markers));
+    return new this(id, elements, appState);
   }
 
   /**
@@ -739,10 +569,8 @@ export class StoreDelta {
     for (const delta of deltas) {
       aggregatedDelta.elements.squash(delta.elements);
       aggregatedDelta.appState.squash(delta.appState);
-      mergeStoreDeltaMarkers(aggregatedDelta, delta.markers ?? {});
     }
 
-    pruneStoreDeltaMarkers(aggregatedDelta);
     return aggregatedDelta;
   }
 
@@ -750,12 +578,7 @@ export class StoreDelta {
    * Inverse store delta, creates new instance of `StoreDelta`.
    */
   public static inverse(delta: StoreDelta) {
-    const inversed = this.create(
-      delta.elements.inverse(),
-      delta.appState.inverse(),
-      { markers: delta.markers },
-    );
-    return inversed;
+    return this.create(delta.elements.inverse(), delta.appState.inverse());
   }
 
   /**
@@ -791,7 +614,7 @@ export class StoreDelta {
     nextElements: SceneElementsMap,
     modifierOptions?: "deleted" | "inserted",
   ): StoreDelta {
-    const nextDelta = this.create(
+    return this.create(
       delta.elements.applyLatestChanges(
         prevElements,
         nextElements,
@@ -800,11 +623,8 @@ export class StoreDelta {
       delta.appState,
       {
         id: delta.id,
-        markers: delta.markers,
       },
     );
-    pruneStoreDeltaMarkers(nextDelta);
-    return nextDelta;
   }
 
   public static empty() {

packages/element/src/typeChecks.ts

@@ -392,3 +392,23 @@ export const canBecomePolygon = (
     (points.length === 3 && !pointsEqual(points[0], points[points.length - 1]))
   );
 };
+
+export const isEligibleFrameChildType = (type: ElementOrToolType) => {
+  switch (type) {
+    case "rectangle":
+    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/tests/fractionalIndex.test.ts

@@ -1,9 +1,8 @@
 /* eslint-disable no-lone-blocks */
-import { generateKeyBetween } from "fractional-indexing";
-
 import { arrayToMap } from "@excalidraw/common";
 
 import {
+  InvalidFractionalIndexError,
   syncInvalidIndices,
   syncMovedIndices,
   validateFractionalIndices,
@@ -13,13 +12,34 @@ import { deepCopyElement } from "@excalidraw/element";
 
 import { API } from "@excalidraw/excalidraw/tests/helpers/api";
 
+import {
+  generateKeyBetween,
+  validateOrderKey,
+} from "@excalidraw/fractional-indexing";
+
 import type {
   ElementsMap,
   ExcalidrawElement,
   FractionalIndex,
 } from "@excalidraw/element/types";
 
-import { InvalidFractionalIndexError } from "../src/fractionalIndex";
+describe("fractional index format validation", () => {
+  it("should reject malformed base62 order keys", () => {
+    expect(() => validateOrderKey("a!")).toThrow();
+    expect(() => validateOrderKey("a_")).toThrow();
+    expect(() => validateOrderKey("a1!")).toThrow();
+    expect(() => validateOrderKey("a1_")).toThrow();
+    expect(() => validateOrderKey("zd0032")).toThrow();
+  });
+
+  it("should accept valid base62 order keys", () => {
+    expect(() => validateOrderKey("Zz")).not.toThrow();
+    expect(() => validateOrderKey("a0")).not.toThrow();
+    expect(() => validateOrderKey("a1")).not.toThrow();
+    expect(() => validateOrderKey("a1V")).not.toThrow();
+    expect(() => validateOrderKey("z".padEnd(28, "z"))).not.toThrow();
+  });
+});
 
 describe("sync invalid indices with array order", () => {
   describe("should NOT sync empty array", () => {
@@ -104,6 +124,46 @@ describe("sync invalid indices with array order", () => {
     });
   });
 
+  describe("should sync when fractional index is malformed", () => {
+    // "zd0032" has head "z" which requires length 28 per getIntegerLength,
+    // but the string is far too short, so validateOrderKey throws for it
+    testInvalidIndicesSync({
+      elements: [{ id: "A", index: "zd0032" }],
+      expect: {
+        unchangedElements: [],
+      },
+    });
+
+    testInvalidIndicesSync({
+      elements: [
+        { id: "A", index: "a1" },
+        { id: "B", index: "zd0032" },
+        { id: "C", index: "a3" },
+      ],
+      expect: {
+        unchangedElements: ["A", "C"],
+      },
+    });
+
+    testInvalidIndicesSync({
+      elements: [{ id: "A", index: "a!" }],
+      expect: {
+        unchangedElements: [],
+      },
+    });
+
+    testInvalidIndicesSync({
+      elements: [
+        { id: "A", index: "a1" },
+        { id: "B", index: "a!" },
+        { id: "C", index: "a2" },
+      ],
+      expect: {
+        unchangedElements: ["A", "C"],
+      },
+    });
+  });
+
   describe("should sync when fractional indices are duplicated", () => {
     testInvalidIndicesSync({
       elements: [

packages/element/tests/frame.test.tsx

@@ -2,15 +2,24 @@ import {
   convertToExcalidrawElements,
   Excalidraw,
 } from "@excalidraw/excalidraw";
+import { arrayToMap } from "@excalidraw/common";
 
 import { API } from "@excalidraw/excalidraw/tests/helpers/api";
-import { Keyboard, Pointer } from "@excalidraw/excalidraw/tests/helpers/ui";
+import { Keyboard, Pointer, UI } from "@excalidraw/excalidraw/tests/helpers/ui";
+import { getTextEditor } from "@excalidraw/excalidraw/tests/queries/dom";
 import {
   getCloneByOrigId,
   render,
 } from "@excalidraw/excalidraw/tests/test-utils";
 
-import type { ExcalidrawElement } from "../src/types";
+import { getSelectedElements } from "@excalidraw/excalidraw/scene";
+
+import { elementOverlapsWithFrame } from "../src/frame";
+
+import type {
+  ExcalidrawElement,
+  ExcalidrawFrameLikeElement,
+} from "../src/types";
 
 const { h } = window;
 const mouse = new Pointer("mouse");
@@ -125,6 +134,250 @@ describe("adding elements to frames", () => {
     });
   });
 
+  it("should treat an element fully containing a frame as overlapping the frame", () => {
+    const containingRect = API.createElement({
+      type: "rectangle",
+      x: -50,
+      y: -50,
+      width: 250,
+      height: 250,
+    });
+
+    API.setElements([containingRect, frame]);
+
+    expect(
+      elementOverlapsWithFrame(
+        containingRect,
+        frame as ExcalidrawFrameLikeElement,
+        arrayToMap(h.elements),
+      ),
+    ).toBe(true);
+  });
+
+  it("should not add a newly created element to a frame behind a non-frame element", () => {
+    const cover = API.createElement({
+      id: "cover",
+      type: "rectangle",
+      x: 10,
+      y: 10,
+      width: 80,
+      height: 80,
+      backgroundColor: "#ffc9c9",
+    });
+
+    API.setElements([frame, cover]);
+
+    UI.clickTool("rectangle");
+    mouse.downAt(20, 20);
+    mouse.moveTo(40, 40);
+    mouse.upAt(40, 40);
+
+    const createdElement = h.elements.find(
+      (element) => element.id !== frame.id && element.id !== cover.id,
+    );
+
+    expect(createdElement?.frameId).toBe(null);
+    expect(h.elements.map((element) => element.id)).toEqual([
+      frame.id,
+      cover.id,
+      createdElement?.id,
+    ]);
+  });
+
+  it("should add a newly created element to a frame over a non-frame element", () => {
+    const cover = API.createElement({
+      id: "cover",
+      type: "rectangle",
+      x: 10,
+      y: 10,
+      width: 80,
+      height: 80,
+      backgroundColor: "#ffc9c9",
+    });
+
+    API.setElements([cover, frame]);
+
+    UI.clickTool("rectangle");
+    mouse.downAt(20, 20);
+    mouse.moveTo(40, 40);
+    mouse.upAt(40, 40);
+
+    const createdElement = h.elements.find(
+      (element) => element.id !== frame.id && element.id !== cover.id,
+    );
+
+    expect(createdElement?.frameId).toBe(frame.id);
+  });
+
+  it("should highlight the target frame while creating a new element", () => {
+    API.setElements([frame]);
+
+    UI.clickTool("rectangle");
+    mouse.downAt(20, 20);
+    mouse.moveTo(40, 40);
+
+    expect(h.state.frameToHighlight?.id).toBe(frame.id);
+
+    mouse.upAt(40, 40);
+
+    expect(h.state.frameToHighlight).toBe(null);
+  });
+
+  it("should highlight the target frame while hovering with a creation tool", () => {
+    API.setElements([frame]);
+
+    UI.clickTool("rectangle");
+    mouse.moveTo(20, 20);
+
+    expect(h.state.frameToHighlight?.id).toBe(frame.id);
+
+    mouse.moveTo(200, 200);
+
+    expect(h.state.frameToHighlight).toBe(null);
+  });
+
+  it("should not add grid-snapped text outside the frame to the clicked frame", async () => {
+    const offsetFrame = API.createElement({
+      id: "offsetFrame",
+      type: "frame",
+      x: 10,
+      y: 0,
+      width: 150,
+      height: 150,
+    });
+
+    API.setElements([offsetFrame]);
+    API.setAppState({
+      gridModeEnabled: true,
+    });
+
+    UI.clickTool("text");
+    mouse.clickAt(12, 0);
+
+    await getTextEditor();
+
+    const createdText = h.elements.find(
+      (element) => element.id !== offsetFrame.id,
+    );
+
+    expect(createdText?.x).toBe(0);
+    expect(createdText?.y).toBe(0);
+    expect(createdText?.frameId).toBe(null);
+  });
+
+  it("should add a newly created element to a frame behind another frame", () => {
+    const lockedFrame = API.createElement({
+      id: "lockedFrame",
+      type: "frame",
+      x: 10,
+      y: 10,
+      width: 80,
+      height: 80,
+      locked: true,
+    });
+
+    API.setElements([frame, lockedFrame]);
+
+    UI.clickTool("rectangle");
+    mouse.downAt(20, 20);
+    mouse.moveTo(40, 40);
+    mouse.upAt(40, 40);
+
+    const createdElement = h.elements.find(
+      (element) => element.id !== frame.id && element.id !== lockedFrame.id,
+    );
+
+    expect(createdElement?.frameId).toBe(frame.id);
+  });
+
+  it("should insert a newly created frame child just below its frame", () => {
+    const frameChildUnderCursor = API.createElement({
+      id: "frameChildUnderCursor",
+      type: "rectangle",
+      x: 10,
+      y: 10,
+      width: 80,
+      height: 80,
+      backgroundColor: "#ffc9c9",
+      frameId: frame.id,
+    });
+    const otherFrameChild = API.createElement({
+      id: "otherFrameChild",
+      type: "rectangle",
+      x: 100,
+      y: 20,
+      width: 20,
+      height: 20,
+      frameId: frame.id,
+    });
+
+    API.setElements([frameChildUnderCursor, otherFrameChild, frame]);
+
+    UI.clickTool("rectangle");
+    mouse.downAt(20, 20);
+    mouse.moveTo(40, 40);
+    mouse.upAt(40, 40);
+
+    const createdElement = h.elements.find(
+      (element) =>
+        element.id !== frame.id &&
+        element.id !== frameChildUnderCursor.id &&
+        element.id !== otherFrameChild.id,
+    );
+
+    expect(createdElement?.frameId).toBe(frame.id);
+    expect(h.elements.map((element) => element.id)).toEqual([
+      frameChildUnderCursor.id,
+      otherFrameChild.id,
+      createdElement?.id,
+      frame.id,
+    ]);
+  });
+
+  it("should insert a newly created frame child above the highest frame child", () => {
+    const frameChildUnderCursor = API.createElement({
+      id: "frameChildUnderCursor",
+      type: "rectangle",
+      x: 10,
+      y: 10,
+      width: 80,
+      height: 80,
+      backgroundColor: "#ffc9c9",
+      frameId: frame.id,
+    });
+    const otherFrameChild = API.createElement({
+      id: "otherFrameChild",
+      type: "rectangle",
+      x: 100,
+      y: 20,
+      width: 20,
+      height: 20,
+      frameId: frame.id,
+    });
+
+    API.setElements([frame, frameChildUnderCursor, otherFrameChild]);
+
+    UI.clickTool("rectangle");
+    mouse.downAt(20, 20);
+    mouse.moveTo(40, 40);
+    mouse.upAt(40, 40);
+
+    const createdElement = h.elements.find(
+      (element) =>
+        element.id !== frame.id &&
+        element.id !== frameChildUnderCursor.id &&
+        element.id !== otherFrameChild.id,
+    );
+
+    expect(createdElement?.frameId).toBe(frame.id);
+    expect(h.elements.map((element) => element.id)).toEqual([
+      frame.id,
+      frameChildUnderCursor.id,
+      otherFrameChild.id,
+      createdElement?.id,
+    ]);
+  });
+
   const commonTestCases = async (
     func: typeof resizeFrameOverElement | typeof dragElementIntoFrame,
   ) => {
@@ -415,6 +668,345 @@ describe("adding elements to frames", () => {
   describe("dragging elements into the frame", async () => {
     await commonTestCases(dragElementIntoFrame);
 
+    it("should add a dragged element fully containing the frame", () => {
+      const containingRect = API.createElement({
+        type: "rectangle",
+        x: 220,
+        y: 20,
+        width: 300,
+        height: 300,
+      });
+
+      API.setElements([frame, containingRect]);
+
+      dragElementIntoFrame(frame, containingRect);
+
+      expect(API.getElement(containingRect).frameId).toBe(frame.id);
+    });
+
+    it("should drag an element into a frame", () => {
+      API.setElements([rect2, frame]);
+
+      dragElementIntoFrame(frame, rect2);
+
+      expect(rect2.frameId).toBe(frame.id);
+    });
+
+    it("should layer a dragged element above the highest frame child", () => {
+      const frameChild = API.createElement({
+        id: "frameChild",
+        type: "rectangle",
+        x: 10,
+        y: 10,
+        width: 20,
+        height: 20,
+        frameId: frame.id,
+      });
+
+      API.setElements([frame, frameChild, rect2]);
+
+      dragElementIntoFrame(frame, rect2);
+
+      expect(rect2.frameId).toBe(frame.id);
+      expect(h.elements.map((element) => element.id)).toEqual([
+        frame.id,
+        frameChild.id,
+        rect2.id,
+      ]);
+      expect(rect2.index! > frameChild.index!).toBe(true);
+      expect(rect2.index! > frame.index!).toBe(true);
+    });
+
+    it("should preview a dragged element above the highest frame child before pointerup", () => {
+      const frameChild = API.createElement({
+        id: "frameChild",
+        type: "rectangle",
+        x: 10,
+        y: 10,
+        width: 20,
+        height: 20,
+        frameId: frame.id,
+      });
+
+      API.setElements([rect2, frame, frameChild]);
+      API.setSelectedElements([rect2]);
+      API.updateElement(rect2, {
+        x: 10,
+        y: 10,
+      });
+
+      const getRenderableElementIds = (
+        selectedElementsAreBeingDragged: boolean,
+      ) => {
+        return h.app.renderer
+          .getRenderableElements({
+            zoom: h.state.zoom,
+            offsetLeft: 0,
+            offsetTop: 0,
+            scrollX: 0,
+            scrollY: 0,
+            height: 1000,
+            width: 1000,
+            editingTextElement: h.state.editingTextElement,
+            newElement: h.state.newElement,
+            selectedElements: getSelectedElements(h.elements, h.state),
+            selectedElementsAreBeingDragged,
+            frameToHighlight: frame as ExcalidrawFrameLikeElement,
+          })
+          .visibleElements.map((element) => element.id);
+      };
+
+      expect(h.elements.map((element) => element.id)).toEqual([
+        rect2.id,
+        frame.id,
+        frameChild.id,
+      ]);
+      expect(getRenderableElementIds(false)).toEqual([
+        rect2.id,
+        frame.id,
+        frameChild.id,
+      ]);
+      expect(getRenderableElementIds(true)).toEqual([
+        frame.id,
+        frameChild.id,
+        rect2.id,
+      ]);
+      expect(h.elements.map((element) => element.id)).toEqual([
+        rect2.id,
+        frame.id,
+        frameChild.id,
+      ]);
+      expect(rect2.frameId).toBe(null);
+    });
+
+    it("should not preview reorder dragged elements already in the highlighted frame", () => {
+      const frameChild = API.createElement({
+        id: "frameChild",
+        type: "rectangle",
+        x: 10,
+        y: 10,
+        width: 20,
+        height: 20,
+        frameId: frame.id,
+      });
+      const otherFrameChild = API.createElement({
+        id: "otherFrameChild",
+        type: "rectangle",
+        x: 40,
+        y: 10,
+        width: 20,
+        height: 20,
+        frameId: frame.id,
+      });
+
+      API.setElements([frameChild, frame, otherFrameChild]);
+      API.setSelectedElements([frameChild]);
+
+      const renderableElementIds = h.app.renderer
+        .getRenderableElements({
+          zoom: h.state.zoom,
+          offsetLeft: 0,
+          offsetTop: 0,
+          scrollX: 0,
+          scrollY: 0,
+          height: 1000,
+          width: 1000,
+          editingTextElement: h.state.editingTextElement,
+          newElement: h.state.newElement,
+          selectedElements: getSelectedElements(h.elements, h.state),
+          selectedElementsAreBeingDragged: true,
+          frameToHighlight: frame as ExcalidrawFrameLikeElement,
+        })
+        .visibleElements.map((element) => element.id);
+
+      expect(renderableElementIds).toEqual([
+        frameChild.id,
+        frame.id,
+        otherFrameChild.id,
+      ]);
+    });
+
+    it("should put a dragged mixed selection above the highest frame child", () => {
+      const frameChild = API.createElement({
+        id: "frameChild",
+        type: "rectangle",
+        x: 50,
+        y: 10,
+        width: 20,
+        height: 20,
+        frameId: frame.id,
+        boundElements: [{ id: "boundText", type: "text" }],
+      });
+      const boundText = API.createElement({
+        id: "boundText",
+        type: "text",
+        x: 50,
+        y: 10,
+        width: 20,
+        height: 20,
+        containerId: frameChild.id,
+        frameId: frame.id,
+      });
+      const otherFrameChild = API.createElement({
+        id: "otherFrameChild",
+        type: "rectangle",
+        x: 80,
+        y: 10,
+        width: 20,
+        height: 20,
+        frameId: frame.id,
+      });
+      const nonFrameElement = API.createElement({
+        id: "nonFrameElement",
+        type: "rectangle",
+        x: 155,
+        y: 10,
+        width: 20,
+        height: 20,
+      });
+
+      API.setElements([
+        frame,
+        frameChild,
+        boundText,
+        otherFrameChild,
+        nonFrameElement,
+      ]);
+      API.setSelectedElements([frameChild, nonFrameElement]);
+
+      mouse.downAt(
+        nonFrameElement.x + nonFrameElement.width / 2,
+        nonFrameElement.y + nonFrameElement.height / 2,
+      );
+      mouse.moveTo(frame.x + frame.width - 5, nonFrameElement.y + 10);
+      mouse.up();
+
+      expect(frameChild.frameId).toBe(frame.id);
+      expect(boundText.frameId).toBe(frame.id);
+      expect(nonFrameElement.frameId).toBe(frame.id);
+      expect(h.elements.map((element) => element.id)).toEqual([
+        frame.id,
+        otherFrameChild.id,
+        frameChild.id,
+        boundText.id,
+        nonFrameElement.id,
+      ]);
+    });
+
+    it("should not reorder dragged elements already in the highlighted frame", () => {
+      const frameChild = API.createElement({
+        id: "frameChild",
+        type: "rectangle",
+        x: 50,
+        y: 10,
+        width: 20,
+        height: 20,
+        frameId: frame.id,
+      });
+      const otherFrameChild = API.createElement({
+        id: "otherFrameChild",
+        type: "rectangle",
+        x: 80,
+        y: 10,
+        width: 20,
+        height: 20,
+        frameId: frame.id,
+      });
+
+      API.setElements([frame, frameChild, otherFrameChild]);
+      API.setSelectedElements([frameChild]);
+
+      mouse.downAt(
+        frameChild.x + frameChild.width / 2,
+        frameChild.y + frameChild.height / 2,
+      );
+      mouse.moveTo(frameChild.x + frameChild.width / 2 + 5, frameChild.y + 10);
+      mouse.up();
+
+      expect(frameChild.frameId).toBe(frame.id);
+      expect(h.elements.map((element) => element.id)).toEqual([
+        frame.id,
+        frameChild.id,
+        otherFrameChild.id,
+      ]);
+    });
+
+    it("should not drag an element into a frame behind a non-frame element", () => {
+      const cover = API.createElement({
+        id: "cover",
+        type: "rectangle",
+        x: 10,
+        y: 10,
+        width: 80,
+        height: 80,
+        backgroundColor: "#ffc9c9",
+      });
+      API.setElements([frame, cover, rect2]);
+
+      mouse.clickAt(rect2.x, rect2.y);
+      mouse.downAt(rect2.x + rect2.width / 2, rect2.y + rect2.height / 2);
+      mouse.moveTo(20, 20);
+      mouse.upAt(20, 20);
+
+      expect(rect2.frameId).toBe(null);
+    });
+
+    it("should drag an element into a frame over a non-frame element", () => {
+      const cover = API.createElement({
+        id: "cover",
+        type: "rectangle",
+        x: 10,
+        y: 10,
+        width: 80,
+        height: 80,
+        backgroundColor: "#ffc9c9",
+      });
+      API.setElements([cover, rect2, frame]);
+
+      mouse.clickAt(rect2.x, rect2.y);
+      mouse.downAt(rect2.x + rect2.width / 2, rect2.y + rect2.height / 2);
+      mouse.moveTo(20, 20);
+      mouse.upAt(20, 20);
+
+      expect(rect2.frameId).toBe(frame.id);
+    });
+
+    it("should keep dragging a frame child over a non-frame element above its frame", () => {
+      const cover = API.createElement({
+        id: "cover",
+        type: "rectangle",
+        x: 10,
+        y: 10,
+        width: 80,
+        height: 80,
+        backgroundColor: "#ffc9c9",
+      });
+      const frameChild = API.createElement({
+        id: "frameChild",
+        type: "rectangle",
+        x: 100,
+        y: 20,
+        width: 20,
+        height: 20,
+        frameId: frame.id,
+      });
+
+      API.setElements([frameChild, frame, cover]);
+      API.setSelectedElements([frameChild]);
+
+      mouse.downAt(
+        frameChild.x + frameChild.width / 2,
+        frameChild.y + frameChild.height / 2,
+      );
+      mouse.moveTo(20, 20);
+
+      expect(h.state.frameToHighlight?.id).toBe(frame.id);
+
+      mouse.upAt(20, 20);
+
+      expect(frameChild.frameId).toBe(frame.id);
+    });
+
     it.skip("should drag element inside, duplicate it and keep it in frame", () => {
       API.setElements([frame, rect2]);
 

packages/element/tests/sortElements.test.ts

@@ -326,19 +326,59 @@ describe("normalizeElementsOrder", () => {
       ]),
       [
         "BA_rect1",
+        "CBA_rect3",
+        "CBA_rect7",
         "BA_rect5",
         "BA_rect6",
         "A_rect2",
         "A_rect5",
-        "CBA_rect3",
-        "CBA_rect7",
         "rect4",
         "X_rect8",
-        "X_rect11",
         "YX_rect10",
+        "X_rect11",
         "rect9",
       ],
     );
+    assertOrder(
+      normalizeElementOrder([
+        API.createElement({
+          id: "A_rect1",
+          type: "rectangle",
+          groupIds: ["A"],
+        }),
+        API.createElement({
+          id: "CBA_rect2",
+          type: "rectangle",
+          groupIds: ["C", "B", "A"],
+        }),
+        API.createElement({
+          id: "A_rect3",
+          type: "rectangle",
+          groupIds: ["A"],
+        }),
+      ]),
+      ["A_rect1", "CBA_rect2", "A_rect3"],
+    );
+    assertOrder(
+      normalizeElementOrder([
+        API.createElement({
+          id: "abcT_rect1",
+          type: "rectangle",
+          groupIds: ["ab", "c", "T"],
+        }),
+        API.createElement({
+          id: "abcT_rect2",
+          type: "rectangle",
+          groupIds: ["a", "bc", "T"],
+        }),
+        API.createElement({
+          id: "abcT_rect3",
+          type: "rectangle",
+          groupIds: ["ab", "c", "T"],
+        }),
+      ]),
+      ["abcT_rect1", "abcT_rect3", "abcT_rect2"],
+    );
   });
 
   // TODO

packages/element/tests/store.test.ts

@@ -1,140 +0,0 @@
-import { API } from "@excalidraw/excalidraw/tests/helpers/api";
-
-import { arrayToMap } from "@excalidraw/common";
-
-import type App from "@excalidraw/excalidraw/components/App";
-
-import type { ObservedAppState } from "@excalidraw/excalidraw/types";
-import type {
-  ExcalidrawElement,
-  SceneElementsMap,
-} from "@excalidraw/element/types";
-
-import {
-  CaptureUpdateAction,
-  Store,
-  StoreSnapshot,
-  newElementWith,
-} from "../src";
-
-const getScheduledMicroActionCount = (store: Store) =>
-  (
-    store as unknown as {
-      scheduledMicroActions: Array<() => void>;
-    }
-  ).scheduledMicroActions.length;
-
-const flushMicroActions = (store: Store) => {
-  (
-    store as unknown as {
-      flushMicroActions: () => void;
-    }
-  ).flushMicroActions();
-};
-
-const toSceneElementsMap = (
-  elements: readonly ExcalidrawElement[],
-): SceneElementsMap => arrayToMap(elements) as SceneElementsMap;
-
-const createStoreHarness = (elements: SceneElementsMap) => {
-  const appState: ObservedAppState = StoreSnapshot.empty().appState;
-  const app = {
-    scene: {
-      getElementsMapIncludingDeleted: () => elements,
-    },
-    state: appState,
-  } as unknown as App;
-
-  const store = new Store(app);
-  store.snapshot = StoreSnapshot.create(elements, appState);
-
-  return { store, appState };
-};
-
-describe("Store synthetic increment isolation", () => {
-  it("keeps pending immediate micro actions queued across synthetic commit", () => {
-    const element = API.createElement({
-      type: "rectangle",
-      id: "store-isolated-immediate",
-      x: 0,
-      y: 0,
-    });
-    const baselineElements = toSceneElementsMap([element]);
-    const { store } = createStoreHarness(baselineElements);
-
-    const incrementTypes: Array<"durable" | "ephemeral"> = [];
-    const detach = store.onStoreIncrementEmitter.on((increment) => {
-      incrementTypes.push(increment.type);
-    });
-
-    store.scheduleMicroAction({
-      action: CaptureUpdateAction.IMMEDIATELY,
-      elements: [newElementWith(element, { y: 240 })],
-      appState: undefined,
-    });
-
-    expect(getScheduledMicroActionCount(store)).toBe(1);
-
-    const committed = store.commitSyntheticIncrement({
-      logicalBefore: {
-        elements: baselineElements,
-      },
-      logicalAfter: {
-        elements: toSceneElementsMap([newElementWith(element, { x: 120 })]),
-      },
-    });
-
-    expect(committed).toBe(true);
-    expect(incrementTypes).toEqual(["durable"]);
-    expect(getScheduledMicroActionCount(store)).toBe(1);
-
-    flushMicroActions(store);
-
-    expect(incrementTypes).toEqual(["durable", "durable"]);
-    expect(getScheduledMicroActionCount(store)).toBe(0);
-    detach();
-  });
-
-  it("keeps pending eventually micro actions queued across synthetic commit", () => {
-    const element = API.createElement({
-      type: "rectangle",
-      id: "store-isolated-eventually",
-      x: 0,
-      y: 0,
-    });
-    const baselineElements = toSceneElementsMap([element]);
-    const { store } = createStoreHarness(baselineElements);
-
-    const incrementTypes: Array<"durable" | "ephemeral"> = [];
-    const detach = store.onStoreIncrementEmitter.on((increment) => {
-      incrementTypes.push(increment.type);
-    });
-
-    store.scheduleMicroAction({
-      action: CaptureUpdateAction.EVENTUALLY,
-      elements: [newElementWith(element, { y: 240 })],
-      appState: undefined,
-    });
-
-    expect(getScheduledMicroActionCount(store)).toBe(1);
-
-    const committed = store.commitSyntheticIncrement({
-      logicalBefore: {
-        elements: baselineElements,
-      },
-      logicalAfter: {
-        elements: toSceneElementsMap([newElementWith(element, { x: 120 })]),
-      },
-    });
-
-    expect(committed).toBe(true);
-    expect(incrementTypes).toEqual(["durable"]);
-    expect(getScheduledMicroActionCount(store)).toBe(1);
-
-    flushMicroActions(store);
-
-    expect(incrementTypes).toEqual(["durable", "ephemeral"]);
-    expect(getScheduledMicroActionCount(store)).toBe(0);
-    detach();
-  });
-});

packages/excalidraw/actions/actionDeselect.ts

@@ -101,6 +101,7 @@ export const actionDeselect = register({
           selectionElement: null,
           showHyperlinkPopup: false,
           suggestedBinding: null,
+          frameToHighlight: null,
         },
         captureUpdate: CaptureUpdateAction.IMMEDIATELY,
       };
@@ -118,6 +119,7 @@ export const actionDeselect = register({
         selectionElement: null,
         showHyperlinkPopup: false,
         suggestedBinding: null,
+        frameToHighlight: null,
       },
       captureUpdate: CaptureUpdateAction.IMMEDIATELY,
     };

packages/excalidraw/actions/actionFinalize.tsx

@@ -27,7 +27,7 @@ import { isInvisiblySmallElement } from "@excalidraw/element";
 
 import { CaptureUpdateAction } from "@excalidraw/element";
 
-import type { GlobalPoint, LocalPoint } from "@excalidraw/math";
+import type { LocalPoint } from "@excalidraw/math";
 import type {
   ExcalidrawElement,
   ExcalidrawLinearElement,
@@ -93,32 +93,40 @@ export const actionFinalize = register<FormData>({
             ? [element.points.length - 1] // New arrow creation
             : appState.selectedLinearElement.selectedPointsIndices;
 
+        const angleLocked = shouldRotateWithDiscreteAngle(event);
+        const effectiveGridSize = event[KEYS.CTRL_OR_CMD]
+          ? null
+          : app.getEffectiveGridSize();
+
         const draggedPoints: PointsPositionUpdates =
           selectedPointsIndices.reduce((map, index) => {
             map.set(index, {
-              point: LinearElementEditor.pointFromAbsoluteCoords(
-                element,
-                pointFrom<GlobalPoint>(
-                  sceneCoords.x - linearElementEditor.pointerOffset.x,
-                  sceneCoords.y - linearElementEditor.pointerOffset.y,
-                ),
-                elementsMap,
-              ),
+              point: angleLocked
+                ? element.points[index]
+                : LinearElementEditor.createPointAt(
+                    element,
+                    elementsMap,
+                    sceneCoords.x - linearElementEditor.pointerOffset.x,
+                    sceneCoords.y - linearElementEditor.pointerOffset.y,
+                    effectiveGridSize,
+                  ),
             });
 
             return map;
           }, new Map()) ?? new Map();
+
         bindOrUnbindBindingElement(
           element,
           draggedPoints,
-          sceneCoords.x - linearElementEditor.pointerOffset.x,
-          sceneCoords.y - linearElementEditor.pointerOffset.y,
+          sceneCoords.x,
+          sceneCoords.y,
           scene,
           appState,
           {
             newArrow,
             altKey: event.altKey,
-            angleLocked: shouldRotateWithDiscreteAngle(event),
+            angleLocked,
+            gridSize: app.getEffectiveGridSize(),
           },
         );
       } else if (isLineElement(element)) {
@@ -329,8 +337,8 @@ export const actionFinalize = register<FormData>({
         selectionElement: null,
         multiElement: null,
         editingTextElement: null,
-        startBoundElement: null,
         suggestedBinding: null,
+        frameToHighlight: null,
         selectedElementIds:
           element &&
           !appState.activeTool.locked &&

packages/excalidraw/actions/actionFrame.ts

@@ -205,7 +205,6 @@ export const actionWrapSelectionInFrame = register({
       [...app.scene.getElementsIncludingDeleted(), frame],
       selectedElements,
       frame,
-      appState,
     );
 
     return {

packages/excalidraw/actions/actionGroup.tsx

@@ -277,7 +277,6 @@ export const actionUngroup = register({
             elementsMap,
           ),
           frame,
-          app,
         );
       }
     });

packages/excalidraw/actions/actionHistory.tsx

@@ -1,5 +1,4 @@
 import {
-  isWindows,
   KEYS,
   matchKey,
   arrayToMap,
@@ -114,7 +113,7 @@ export const createRedoAction: ActionCreator = (history) => ({
     ),
   keyTest: (event) =>
     (event[KEYS.CTRL_OR_CMD] && event.shiftKey && matchKey(event, KEYS.Z)) ||
-    (isWindows && event.ctrlKey && !event.shiftKey && matchKey(event, KEYS.Y)),
+    (event[KEYS.CTRL_OR_CMD] && !event.shiftKey && matchKey(event, KEYS.Y)),
   PanelComponent: ({ appState, updateData, data, app }) => {
     const { isRedoStackEmpty } = useEmitter(
       history.onHistoryChangedEmitter,

packages/excalidraw/animatedTrail.ts

@@ -1,5 +1,4 @@
 import { LaserPointer } from "@excalidraw/laser-pointer";
-
 import {
   SVG_NS,
   getSvgPathFromStroke,
@@ -8,7 +7,8 @@ import {
 
 import type { LaserPointerOptions } from "@excalidraw/laser-pointer";
 
-import type { AnimationFrameHandler } from "./animation-frame-handler";
+import { AnimationController } from "./renderer/animation";
+
 import type App from "./components/App";
 import type { AppState } from "./types";
 
@@ -34,15 +34,16 @@ export class AnimatedTrail implements Trail {
   private container?: SVGSVGElement;
   private trailElement: SVGPathElement;
   private trailAnimation?: SVGAnimateElement;
+  private key: string;
+
+  private static counter = 0;
 
   constructor(
-    private animationFrameHandler: AnimationFrameHandler,
     protected app: App,
     private options: Partial<LaserPointerOptions> &
       Partial<AnimatedTrailOptions>,
   ) {
-    this.animationFrameHandler.register(this, this.onFrame.bind(this));
-
+    this.key = `animated-trail-${AnimatedTrail.counter++}`;
     this.trailElement = document.createElementNS(SVG_NS, "path");
     if (this.options.animateTrail) {
       this.trailAnimation = document.createElementNS(SVG_NS, "animate");
@@ -73,6 +74,15 @@ export class AnimatedTrail implements Trail {
     return false;
   }
 
+  private cleanup() {
+    this.pastTrails = [];
+    this.currentTrail = undefined;
+
+    if (this.trailElement.parentNode === this.container) {
+      this.container?.removeChild(this.trailElement);
+    }
+  }
+
   start(container?: SVGSVGElement) {
     if (container) {
       this.container = container;
@@ -82,15 +92,23 @@ export class AnimatedTrail implements Trail {
       this.container.appendChild(this.trailElement);
     }
 
-    this.animationFrameHandler.start(this);
+    if (!AnimationController.running(this.key)) {
+      AnimationController.start(this.key, () => {
+        const needsNext = this.onFrame();
+        if (needsNext) {
+          return { keep: true };
+        }
+
+        this.cleanup();
+
+        return null;
+      });
+    }
   }
 
   stop() {
-    this.animationFrameHandler.stop(this);
-
-    if (this.trailElement.parentNode === this.container) {
-      this.container?.removeChild(this.trailElement);
-    }
+    AnimationController.cancel(this.key);
+    this.cleanup();
   }
 
   startPath(x: number, y: number) {
@@ -145,21 +163,25 @@ export class AnimatedTrail implements Trail {
 
     if (this.currentTrail) {
       const currentPath = this.drawTrail(this.currentTrail, this.app.state);
-
       paths.push(currentPath);
     }
 
-    this.pastTrails = this.pastTrails.filter((trail) => {
-      return trail.getStrokeOutline().length !== 0;
-    });
+    this.pastTrails = this.pastTrails.filter(
+      (t) =>
+        t.getStrokeOutline(t.options.size / this.app.state.zoom.value)
+          .length !== 0,
+    );
 
     if (paths.length === 0) {
-      this.stop();
+      // Clean up the SVG path if there are no trails to render
+      this.trailElement.setAttribute("d", "");
+
+      return false;
     }
 
     const svgPaths = paths.join(" ").trim();
-
     this.trailElement.setAttribute("d", svgPaths);
+
     if (this.trailAnimation) {
       this.trailElement.setAttribute(
         "fill",
@@ -175,6 +197,8 @@ export class AnimatedTrail implements Trail {
         (this.options.fill ?? (() => "black"))(this),
       );
     }
+
+    return true;
   }
 
   private drawTrail(trail: LaserPointer, state: AppState): string {

packages/excalidraw/animation-frame-handler.ts

@@ -1,79 +0,0 @@
-export type AnimationCallback = (timestamp: number) => void | boolean;
-
-export type AnimationTarget = {
-  callback: AnimationCallback;
-  stopped: boolean;
-};
-
-export class AnimationFrameHandler {
-  private targets = new WeakMap<object, AnimationTarget>();
-  private rafIds = new WeakMap<object, number>();
-
-  register(key: object, callback: AnimationCallback) {
-    this.targets.set(key, { callback, stopped: true });
-  }
-
-  start(key: object) {
-    const target = this.targets.get(key);
-
-    if (!target) {
-      return;
-    }
-
-    if (this.rafIds.has(key)) {
-      return;
-    }
-
-    this.targets.set(key, { ...target, stopped: false });
-    this.scheduleFrame(key);
-  }
-
-  stop(key: object) {
-    const target = this.targets.get(key);
-    if (target && !target.stopped) {
-      this.targets.set(key, { ...target, stopped: true });
-    }
-
-    this.cancelFrame(key);
-  }
-
-  private constructFrame(key: object): FrameRequestCallback {
-    return (timestamp: number) => {
-      const target = this.targets.get(key);
-
-      if (!target) {
-        return;
-      }
-
-      const shouldAbort = this.onFrame(target, timestamp);
-
-      if (!target.stopped && !shouldAbort) {
-        this.scheduleFrame(key);
-      } else {
-        this.cancelFrame(key);
-      }
-    };
-  }
-
-  private scheduleFrame(key: object) {
-    const rafId = requestAnimationFrame(this.constructFrame(key));
-
-    this.rafIds.set(key, rafId);
-  }
-
-  private cancelFrame(key: object) {
-    if (this.rafIds.has(key)) {
-      const rafId = this.rafIds.get(key)!;
-
-      cancelAnimationFrame(rafId);
-    }
-
-    this.rafIds.delete(key);
-  }
-
-  private onFrame(target: AnimationTarget, timestamp: number): boolean {
-    const shouldAbort = target.callback(timestamp);
-
-    return shouldAbort ?? false;
-  }
-}

packages/excalidraw/appState.ts

@@ -99,7 +99,6 @@ export const getDefaultAppState = (): Omit<
       open: false,
       panels: STATS_PANELS.generalStats | STATS_PANELS.elementProperties,
     },
-    startBoundElement: null,
     suggestedBinding: null,
     frameRendering: { enabled: true, clip: true, name: true, outline: true },
     frameToHighlight: null,
@@ -231,7 +230,6 @@ const APP_STATE_STORAGE_CONF = (<
   selectionElement: { browser: false, export: false, server: false },
   shouldCacheIgnoreZoom: { browser: true, export: false, server: false },
   stats: { browser: true, export: false, server: false },
-  startBoundElement: { browser: false, export: false, server: false },
   suggestedBinding: { browser: false, export: false, server: false },
   frameRendering: { browser: false, export: false, server: false },
   frameToHighlight: { browser: false, export: false, server: false },

packages/excalidraw/components/App.tsx

@@ -28,7 +28,6 @@ import {
   APP_NAME,
   CURSOR_TYPE,
   DEFAULT_TRANSFORM_HANDLE_SPACING,
-  DEFAULT_MAX_IMAGE_WIDTH_OR_HEIGHT,
   DEFAULT_VERTICAL_ALIGN,
   DRAGGING_THRESHOLD,
   ELEMENT_SHIFT_TRANSLATE_AMOUNT,
@@ -38,7 +37,6 @@ import {
   IMAGE_MIME_TYPES,
   IMAGE_RENDER_TIMEOUT,
   LINE_CONFIRM_THRESHOLD,
-  MAX_ALLOWED_FILE_BYTES,
   MIME_TYPES,
   MQ_RIGHT_SIDEBAR_MIN_WIDTH,
   POINTER_BUTTON,
@@ -176,7 +174,9 @@ import {
   isValidTextContainer,
   redrawTextBoundingBox,
   hasBoundingBox,
+  getCommonFrameId,
   getFrameChildren,
+  getFrameChildrenInsertionIndex,
   isCursorInFrame,
   addElementsToFrame,
   replaceAllElementsInFrame,
@@ -259,6 +259,7 @@ import {
   maybeHandleArrowPointlikeDrag,
   getUncroppedWidthAndHeight,
   getActiveTextElement,
+  isEligibleFrameChildType,
 } from "@excalidraw/element";
 
 import type { GlobalPoint, LocalPoint, Radians } from "@excalidraw/math";
@@ -342,7 +343,6 @@ import { ActionManager } from "../actions/manager";
 import { actions } from "../actions/register";
 import { getShortcutFromShortcutName } from "../actions/shortcuts";
 import { trackEvent } from "../analytics";
-import { AnimationFrameHandler } from "../animation-frame-handler";
 import {
   getDefaultAppState,
   isEraserActive,
@@ -361,7 +361,6 @@ import { restoreAppState, restoreElements } from "../data/restore";
 import { getCenter, getDistance } from "../gesture";
 import { History } from "../history";
 import { defaultLang, getLanguage, languages, setLanguage, t } from "../i18n";
-import { TransactionManager } from "../transaction";
 
 import {
   calculateScrollCenter,
@@ -417,7 +416,7 @@ import {
   setCursorForShape,
 } from "../cursor";
 import { ElementCanvasButtons } from "../components/ElementCanvasButtons";
-import { LaserTrails } from "../laser-trails";
+import { LaserTrails } from "../laserTrails";
 import { withBatchedUpdates, withBatchedUpdatesThrottled } from "../reactUtils";
 import { isPointHittingTextAutoResizeHandle } from "../textAutoResizeHandle";
 import { textWysiwyg } from "../wysiwyg/textWysiwyg";
@@ -604,6 +603,8 @@ const YOUTUBE_VIDEO_STATES = new Map<
   ValueOf<typeof YOUTUBE_STATES>
 >();
 
+const MAX_EMBEDDABLE_VIEWPORT_SCALE = 4;
+
 let IS_PLAIN_PASTE = false;
 let IS_PLAIN_PASTE_TIMER = 0;
 let PLAIN_PASTE_TOAST_SHOWN = false;
@@ -638,8 +639,7 @@ class App extends React.Component<AppProps, AppState> {
   public library: AppClassProperties["library"];
   public libraryItemsFromStorage: LibraryItems | undefined;
   public id: string;
-  public transactionManager: TransactionManager;
-  public store: Store;
+  private store: Store;
   private history: History;
   public excalidrawContainerValue: {
     container: HTMLDivElement | null;
@@ -702,11 +702,9 @@ class App extends React.Component<AppProps, AppState> {
   previousPointerMoveCoords: { x: number; y: number } | null = null;
   lastViewportPosition = { x: 0, y: 0 };
 
-  animationFrameHandler = new AnimationFrameHandler();
-
-  laserTrails = new LaserTrails(this.animationFrameHandler, this);
-  eraserTrail = new EraserTrail(this.animationFrameHandler, this);
-  lassoTrail = new LassoTrail(this.animationFrameHandler, this);
+  laserTrails = new LaserTrails(this);
+  eraserTrail = new EraserTrail(this);
+  lassoTrail = new LassoTrail(this);
 
   onChangeEmitter = new Emitter<
     [
@@ -834,8 +832,6 @@ class App extends React.Component<AppProps, AppState> {
 
     this.store = new Store(this);
     this.history = new History(this.store);
-    this.transactionManager = new TransactionManager(this);
-    this.transactionManager.attachHistory(this.history);
 
     this.excalidrawContainerValue = {
       container: this.excalidrawContainerRef.current,
@@ -843,6 +839,7 @@ class App extends React.Component<AppProps, AppState> {
     };
 
     this.fonts = new Fonts(this.scene);
+    this.history = new History(this.store);
 
     this.actionManager.registerAll(actions);
     this.actionManager.registerAction(createUndoAction(this.history));
@@ -1738,6 +1735,18 @@ class App extends React.Component<AppProps, AppState> {
             this.state.activeEmbeddable?.element === el &&
             this.state.activeEmbeddable?.state === "hover";
 
+          // scale video embeds based on zoom (capped) so that smaller embeds
+          // on canvas when zoomed are still of legible quality
+          // (note: for some embed types like gdrive, the quality is poor when
+          // scaling mid playback and works only when you initially start the
+          // playback at the higher zoom level)
+          const shouldScaleEmbeddableViewport = src?.type === "video";
+          const embeddableViewportScale = clamp(
+            shouldScaleEmbeddableViewport ? scale : 1,
+            0.75,
+            MAX_EMBEDDABLE_VIEWPORT_SCALE,
+          );
+
           return (
             <div
               key={el.id}
@@ -1804,31 +1813,42 @@ class App extends React.Component<AppProps, AppState> {
                     padding: `${el.strokeWidth}px`,
                   }}
                 >
-                  {(isEmbeddableElement(el)
-                    ? this.props.renderEmbeddable?.(el, this.state)
-                    : null) ?? (
-                    <iframe
-                      ref={(ref) => this.cacheEmbeddableRef(el, ref)}
-                      className="excalidraw__embeddable"
-                      srcDoc={
-                        src?.type === "document"
-                          ? src.srcdoc(this.state.theme)
-                          : undefined
-                      }
-                      src={
-                        src?.type !== "document" ? src?.link ?? "" : undefined
-                      }
-                      // https://stackoverflow.com/q/18470015
-                      scrolling="no"
-                      referrerPolicy="no-referrer-when-downgrade"
-                      title="Excalidraw Embedded Content"
-                      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
-                      allowFullScreen={true}
-                      sandbox={`${
-                        src?.sandbox?.allowSameOrigin ? "allow-same-origin" : ""
-                      } allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-presentation allow-downloads`}
-                    />
-                  )}
+                  <div
+                    className="excalidraw__embeddable__content"
+                    style={{
+                      width: `${embeddableViewportScale * 100}%`,
+                      height: `${embeddableViewportScale * 100}%`,
+                      transform: `scale(${1 / embeddableViewportScale})`,
+                    }}
+                  >
+                    {(isEmbeddableElement(el)
+                      ? this.props.renderEmbeddable?.(el, this.state)
+                      : null) ?? (
+                      <iframe
+                        ref={(ref) => this.cacheEmbeddableRef(el, ref)}
+                        className="excalidraw__embeddable"
+                        srcDoc={
+                          src?.type === "document"
+                            ? src.srcdoc(this.state.theme)
+                            : undefined
+                        }
+                        src={
+                          src?.type !== "document" ? src?.link ?? "" : undefined
+                        }
+                        // https://stackoverflow.com/q/18470015
+                        scrolling="no"
+                        referrerPolicy="no-referrer-when-downgrade"
+                        title="Excalidraw Embedded Content"
+                        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+                        allowFullScreen={true}
+                        sandbox={`${
+                          src?.sandbox?.allowSameOrigin
+                            ? "allow-same-origin"
+                            : ""
+                        } allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-presentation allow-downloads`}
+                      />
+                    )}
+                  </div>
                 </div>
               </div>
             </div>
@@ -2070,20 +2090,30 @@ class App extends React.Component<AppProps, AppState> {
     const selectedElements = this.scene.getSelectedElements(this.state);
     const { renderTopRightUI, renderTopLeftUI, renderCustomStats } = this.props;
 
-    const sceneNonce = this.scene.getSceneNonce();
-    const { elementsMap, visibleElements } =
-      this.renderer.getRenderableElements({
-        sceneNonce,
-        zoom: this.state.zoom,
-        offsetLeft: this.state.offsetLeft,
-        offsetTop: this.state.offsetTop,
-        scrollX: this.state.scrollX,
-        scrollY: this.state.scrollY,
-        height: this.state.height,
-        width: this.state.width,
-        editingTextElement: this.state.editingTextElement,
-        newElementId: this.state.newElement?.id,
-      });
+    const {
+      elementsMap,
+      visibleElements,
+      canvasNonce,
+      /**
+       * element to draw on the <NewElementCanvas> for optimization purposes.
+       * Can be null even if this.state.newElement defined
+       * (e.g. when its zIndex isn't on top) */
+      newElementCanvasElement,
+    } = this.renderer.getRenderableElements({
+      zoom: this.state.zoom,
+      offsetLeft: this.state.offsetLeft,
+      offsetTop: this.state.offsetTop,
+      scrollX: this.state.scrollX,
+      scrollY: this.state.scrollY,
+      height: this.state.height,
+      width: this.state.width,
+      editingTextElement: this.state.editingTextElement,
+      newElement: this.state.newElement,
+      selectedElements,
+      selectedElementsAreBeingDragged:
+        this.state.selectedElementsAreBeingDragged,
+      frameToHighlight: this.state.frameToHighlight,
+    });
     this.visibleElements = visibleElements;
 
     const allElementsMap = this.scene.getNonDeletedElementsMap();
@@ -2302,7 +2332,7 @@ class App extends React.Component<AppProps, AppState> {
                             elementsMap={elementsMap}
                             allElementsMap={allElementsMap}
                             visibleElements={visibleElements}
-                            sceneNonce={sceneNonce}
+                            canvasNonce={canvasNonce}
                             selectionNonce={
                               this.state.selectionElement?.versionNonce
                             }
@@ -2323,9 +2353,10 @@ class App extends React.Component<AppProps, AppState> {
                               theme: this.state.theme,
                             }}
                           />
-                          {this.state.newElement && (
+                          {newElementCanvasElement && (
                             <NewElementCanvas
                               appState={this.state}
+                              newElement={newElementCanvasElement}
                               scale={window.devicePixelRatio}
                               rc={this.rc}
                               elementsMap={elementsMap}
@@ -2353,7 +2384,7 @@ class App extends React.Component<AppProps, AppState> {
                             visibleElements={visibleElements}
                             allElementsMap={allElementsMap}
                             selectedElements={selectedElements}
-                            sceneNonce={sceneNonce}
+                            canvasNonce={canvasNonce}
                             selectionNonce={
                               this.state.selectionElement?.versionNonce
                             }
@@ -2665,7 +2696,7 @@ class App extends React.Component<AppProps, AppState> {
           locked: false,
         });
 
-        this.scene.insertElement(frame);
+        this.insertNewElement(frame);
 
         for (const child of selectedElements) {
           this.scene.mutateElement(child, { frameId: frame.id });
@@ -3743,6 +3774,7 @@ class App extends React.Component<AppProps, AppState> {
         position:
           this.editorInterface.formFactor === "desktop" ? "cursor" : "center",
         retainSeed: isPlainPaste,
+        preserveFrameChildrenOrder: true,
       });
       return;
     }
@@ -3886,6 +3918,7 @@ class App extends React.Component<AppProps, AppState> {
     position: { clientX: number; clientY: number } | "cursor" | "center";
     retainSeed?: boolean;
     fitToContent?: boolean;
+    preserveFrameChildrenOrder?: boolean;
   }) => {
     const elements = restoreElements(opts.elements, null, {
       deleteInvisibleElements: true,
@@ -3927,6 +3960,7 @@ class App extends React.Component<AppProps, AppState> {
         });
       }),
       randomizeSeed: !opts.retainSeed,
+      preserveFrameChildrenOrder: opts.preserveFrameChildrenOrder,
     });
 
     const prevElements = this.scene.getElementsIncludingDeleted();
@@ -3948,11 +3982,10 @@ class App extends React.Component<AppProps, AppState> {
         duplicatedElements,
         topLayerFrame,
       );
-      addElementsToFrame(
+      nextElements = addElementsToFrame(
         nextElements,
         eligibleElements,
         topLayerFrame,
-        this.state,
       );
     }
 
@@ -4178,7 +4211,7 @@ class App extends React.Component<AppProps, AppState> {
       return;
     }
 
-    this.scene.insertElements(textElements);
+    this.insertNewElements(textElements);
     this.store.scheduleCapture();
     this.setState({
       selectedElementIds: makeNextSelectedElementIds(
@@ -4579,6 +4612,7 @@ class App extends React.Component<AppProps, AppState> {
       }
 
       if (collaborators) {
+        this.laserTrails.updateCollabTrails(collaborators);
         this.setState({ collaborators });
       }
     },
@@ -4605,11 +4639,6 @@ class App extends React.Component<AppProps, AppState> {
     );
   };
 
-  /** Creates a new transaction for batching mutations into a single undo entry. */
-  public createTransaction: TransactionManager["create"] = () => {
-    return this.transactionManager.create();
-  };
-
   public mutateElement = <TElement extends Mutable<ExcalidrawElement>>(
     element: TElement,
     updates: ElementUpdate<TElement>,
@@ -5439,7 +5468,7 @@ class App extends React.Component<AppProps, AppState> {
     if (!event[KEYS.CTRL_OR_CMD]) {
       if (this.flowChartCreator.isCreatingChart) {
         if (this.flowChartCreator.pendingNodes?.length) {
-          this.scene.insertElements(this.flowChartCreator.pendingNodes);
+          this.insertNewElements(this.flowChartCreator.pendingNodes);
         }
 
         const firstNode = this.flowChartCreator.pendingNodes?.[0];
@@ -5537,6 +5566,7 @@ class App extends React.Component<AppProps, AppState> {
         selectedLinearElement: isSelectionLikeTool(nextActiveTool.type)
           ? prevState.selectedLinearElement
           : null,
+        frameToHighlight: null,
       } as const;
 
       if (nextActiveTool.type === "freedraw") {
@@ -6134,6 +6164,12 @@ class App extends React.Component<AppProps, AppState> {
         hitElement = elements[index];
         break;
       } else if (x1 < x && x < x2 && y1 < y && y < y2) {
+        // to allow binding to containers within frames,
+        // ignore frames in hit testing
+        if (isFrameLikeElement(elements[index])) {
+          continue;
+        }
+
         hitElement = elements[index];
         break;
       }
@@ -6223,11 +6259,6 @@ class App extends React.Component<AppProps, AppState> {
       }
     }
 
-    const topLayerFrame = this.getTopLayerFrameAtSceneCoords({
-      x: sceneX,
-      y: sceneY,
-    });
-
     const textCreationGridPoint = this.getTextCreationGridPoint(sceneX, sceneY);
 
     const newTextElementPosition = parentCenterPosition
@@ -6249,6 +6280,20 @@ class App extends React.Component<AppProps, AppState> {
           y: sceneY,
         };
 
+    const topLayerFrame = this.getTopLayerFrameAtSceneCoords({
+      x: newTextElementPosition.x,
+      y: newTextElementPosition.y,
+    });
+
+    // container has higher priority. Only add to frame if container is in the same frame.
+    const frameId =
+      topLayerFrame &&
+      (!shouldBindToContainer ||
+        !container ||
+        container.frameId === topLayerFrame.id)
+        ? topLayerFrame.id
+        : null;
+
     const element =
       existingTextElement ||
       newTextElement({
@@ -6278,7 +6323,7 @@ class App extends React.Component<AppProps, AppState> {
             ? (0 as Radians)
             : container.angle
           : (0 as Radians),
-        frameId: topLayerFrame ? topLayerFrame.id : null,
+        frameId,
       });
 
     if (!existingTextElement && shouldBindToContainer && container) {
@@ -6294,9 +6339,12 @@ class App extends React.Component<AppProps, AppState> {
     if (!existingTextElement) {
       if (container && shouldBindToContainer) {
         const containerIndex = this.scene.getElementIndex(container.id);
-        this.scene.insertElementAtIndex(element, containerIndex + 1);
+        // TODO should use insertNewElement, after we update it to handle
+        // elements with containerId + frameId at the same time (containerId
+        // should take precedence when it comes to z-index)
+        this.scene.insertElementsAtIndex([element], containerIndex + 1);
       } else {
-        this.scene.insertElement(element);
+        this.insertNewElement(element);
       }
     }
 
@@ -6678,19 +6726,161 @@ class App extends React.Component<AppProps, AppState> {
     }
   };
 
-  private getTopLayerFrameAtSceneCoords = (sceneCoords: {
-    x: number;
-    y: number;
-  }) => {
+  /**
+   * finds candidate frame under cursor (when dragging frame children/elements
+   * inside frames)
+   */
+  private getTopLayerFrameAtSceneCoords = (
+    /**
+     * should be already grid aligned (basically should be what the call site
+     * sets the element's coords to, if applicable)
+     */
+    sceneCoords: {
+      x: number;
+      y: number;
+    },
+    opts?: {
+      /** to exclude selected elements when dragging, etc. */
+      excludeElementIds?: AppState["selectedElementIds"];
+      currentFrameId?: ExcalidrawElement["frameId"];
+    },
+  ) => {
     const elementsMap = this.scene.getNonDeletedElementsMap();
-    const frames = this.scene
+    const framesUnderCursor = this.scene
       .getNonDeletedFramesLikes()
       .filter(
         (frame): frame is ExcalidrawFrameLikeElement =>
           !frame.locked && isCursorInFrame(sceneCoords, frame, elementsMap),
       );
 
-    return frames.length ? frames[frames.length - 1] : null;
+    if (!framesUnderCursor.length) {
+      return null;
+    }
+
+    const topLayerFrame = framesUnderCursor.at(-1)!;
+
+    const hitElement = this.getElementsAtPosition(
+      sceneCoords.x,
+      sceneCoords.y,
+      {
+        includeLockedElements: true,
+      },
+    ).findLast((element) => !opts?.excludeElementIds?.[element.id]);
+
+    if (hitElement) {
+      if (
+        isFrameLikeElement(hitElement) &&
+        // case: we're hitting a locked frame itself (frame's outline
+        // or later its bg once implemented)
+        !hitElement.locked
+      ) {
+        return topLayerFrame;
+      }
+
+      const hitElementIndex = this.scene.getElementIndex(hitElement.id);
+      const topLayerFrameIndex = this.scene.getElementIndex(topLayerFrame.id);
+
+      if (
+        hitElementIndex !== -1 &&
+        topLayerFrameIndex !== -1 &&
+        hitElementIndex <= topLayerFrameIndex
+      ) {
+        return topLayerFrame;
+      }
+
+      // to support a case of dragging a pre-existing frame child underneath
+      // a non-frame element covering the cursor
+      const currentFrame = opts?.currentFrameId
+        ? framesUnderCursor.find((frame) => frame.id === opts.currentFrameId) ??
+          null
+        : null;
+
+      if (currentFrame) {
+        return currentFrame;
+      }
+
+      return hitElement.frameId
+        ? framesUnderCursor.find((frame) => frame.id === hitElement.frameId) ??
+            null
+        : null;
+    }
+
+    return topLayerFrame;
+  };
+
+  private updateFrameToHighlight = (
+    frameToHighlight: AppState["frameToHighlight"],
+  ) => {
+    if (this.state.frameToHighlight !== frameToHighlight) {
+      this.setState({ frameToHighlight });
+    }
+  };
+
+  private maybeUpdateFrameToHighlightOnPointerMove = (
+    sceneCoords: { x: number; y: number },
+    isOverScrollBar: boolean,
+  ) => {
+    // currently this function is being called even during pointerdown so we
+    // need to make sure we don't re-set the state when dragging and similar
+    //
+    // But, we still want to reset on pointermove in case the state is stale
+    // so we updte even for non-eligible tool types
+    if (
+      this.state.newElement ||
+      this.state.multiElement ||
+      this.state.selectionElement ||
+      this.state.selectedElementsAreBeingDragged
+    ) {
+      return;
+    }
+
+    this.updateFrameToHighlight(
+      !isOverScrollBar && isEligibleFrameChildType(this.state.activeTool.type)
+        ? this.getTopLayerFrameAtSceneCoords(sceneCoords)
+        : null,
+    );
+  };
+
+  private insertNewElements = (elements: readonly ExcalidrawElement[]) => {
+    if (!elements.length) {
+      return;
+    }
+
+    const chunkedElements: ExcalidrawElement[][] = [];
+
+    for (const element of elements) {
+      const currentChunk = chunkedElements[chunkedElements.length - 1];
+
+      if (currentChunk?.[0].frameId === element.frameId) {
+        currentChunk.push(element);
+      } else {
+        chunkedElements.push([element]);
+      }
+    }
+
+    for (const chunk of chunkedElements) {
+      const frameId = chunk[0].frameId;
+
+      const insertionIndex = frameId
+        ? getFrameChildrenInsertionIndex(
+            this.scene.getElementsIncludingDeleted(),
+            frameId,
+          )
+        : null;
+      this.scene.insertElementsAtIndex(chunk, insertionIndex);
+    }
+  };
+
+  private insertNewElement = (element: ExcalidrawElement) => {
+    this.insertNewElements([element]);
+
+    const frame = element.frameId
+      ? this.scene.getNonDeletedElement(element.frameId)
+      : null;
+
+    this.updateFrameToHighlight(
+      frame && isFrameLikeElement(frame) ? frame : null,
+    );
   };
 
   private handleCanvasPointerMove = (
@@ -6792,6 +6982,14 @@ class App extends React.Component<AppProps, AppState> {
       }
     }
 
+    this.maybeUpdateFrameToHighlightOnPointerMove(
+      {
+        x: scenePointerX,
+        y: scenePointerY,
+      },
+      isOverScrollBar,
+    );
+
     if (
       !this.state.newElement &&
       isActiveToolNonLinearSnappable(this.state.activeTool.type)
@@ -6930,7 +7128,7 @@ class App extends React.Component<AppProps, AppState> {
               y: scenePointerY,
             },
           });
-          this.setState({ suggestedBinding: null, startBoundElement: null });
+          this.setState({ suggestedBinding: null });
           if (!this.state.activeTool.locked) {
             resetCursor(this.interactiveCanvas);
             this.setState((prevState) => ({
@@ -7065,14 +7263,16 @@ class App extends React.Component<AppProps, AppState> {
       return;
     }
 
-    if (this.state.activeTool.type === "arrow") {
+    // Set suggested binding if we're hovering with an arrow tool
+    // and not dragging out a new element
+    if (this.state.activeTool.type === "arrow" && !this.state.newElement) {
+      const scenePointer = pointFrom<GlobalPoint>(scenePointerX, scenePointerY);
       const hit = getHoveredElementForBinding(
-        pointFrom<GlobalPoint>(scenePointerX, scenePointerY),
+        scenePointer,
         this.scene.getNonDeletedElements(),
         this.scene.getNonDeletedElementsMap(),
         maxBindingDistance_simple(this.state.zoom),
       );
-      const scenePointer = pointFrom<GlobalPoint>(scenePointerX, scenePointerY);
       const elementsMap = this.scene.getNonDeletedElementsMap();
       if (hit && !isPointInElement(scenePointer, hit, elementsMap)) {
         this.setState({
@@ -7574,7 +7774,6 @@ class App extends React.Component<AppProps, AppState> {
         appState: {
           newElement: null,
           editingTextElement: null,
-          startBoundElement: null,
           suggestedBinding: null,
           selectedElementIds: makeNextSelectedElementIds(
             Object.keys(this.state.selectedElementIds)
@@ -8847,7 +9046,7 @@ class App extends React.Component<AppProps, AppState> {
       pressures: simulatePressure ? [] : [event.pressure],
     });
 
-    this.scene.insertElement(element);
+    this.insertNewElement(element);
 
     this.setState((prevState) => {
       const nextSelectedElementIds = {
@@ -8862,18 +9061,8 @@ class App extends React.Component<AppProps, AppState> {
       };
     });
 
-    const boundElement = getHoveredElementForBinding(
-      pointFrom<GlobalPoint>(
-        pointerDownState.origin.x,
-        pointerDownState.origin.y,
-      ),
-      this.scene.getNonDeletedElements(),
-      this.scene.getNonDeletedElementsMap(),
-    );
-
     this.setState({
       newElement: element,
-      startBoundElement: boundElement,
       suggestedBinding: null,
     });
   };
@@ -8914,7 +9103,7 @@ class App extends React.Component<AppProps, AppState> {
       height,
     });
 
-    this.scene.insertElement(element);
+    this.insertNewElement(element);
 
     return element;
   };
@@ -8968,7 +9157,7 @@ class App extends React.Component<AppProps, AppState> {
       link,
     });
 
-    this.scene.insertElement(element);
+    this.insertNewElement(element);
 
     return element;
   };
@@ -9212,7 +9401,7 @@ class App extends React.Component<AppProps, AppState> {
         points: [pointFrom<LocalPoint>(0, 0), pointFrom<LocalPoint>(0, 0)],
       });
 
-      this.scene.insertElement(element);
+      this.insertNewElement(element);
 
       if (isBindingElement(element)) {
         // Do the initial binding so the binding strategy has the initial state
@@ -9370,7 +9559,7 @@ class App extends React.Component<AppProps, AppState> {
         selectionElement: element,
       });
     } else {
-      this.scene.insertElement(element);
+      this.insertNewElement(element);
       this.setState({
         multiElement: null,
         newElement: element,
@@ -9403,7 +9592,7 @@ class App extends React.Component<AppProps, AppState> {
         ? newMagicFrameElement(constructorOpts)
         : newFrameElement(constructorOpts);
 
-    this.scene.insertElement(frame);
+    this.insertNewElement(frame);
 
     this.setState({
       multiElement: null,
@@ -9771,18 +9960,17 @@ class App extends React.Component<AppProps, AppState> {
           return;
         }
 
-        const selectedElementsHasAFrame = selectedElements.find((e) =>
+        const selectedElementsHasAFrame = selectedElements.some((e) =>
           isFrameLikeElement(e),
         );
-        const topLayerFrame = this.getTopLayerFrameAtSceneCoords(pointerCoords);
-        const frameToHighlight =
-          topLayerFrame && !selectedElementsHasAFrame ? topLayerFrame : null;
+        const frameToHighlight = selectedElementsHasAFrame
+          ? null
+          : this.getTopLayerFrameAtSceneCoords(pointerCoords, {
+              currentFrameId: getCommonFrameId(selectedElements),
+              excludeElementIds: this.state.selectedElementIds,
+            });
         // Only update the state if there is a difference
-        if (this.state.frameToHighlight !== frameToHighlight) {
-          flushSync(() => {
-            this.setState({ frameToHighlight });
-          });
-        }
+        this.updateFrameToHighlight(frameToHighlight);
 
         // Marking that click was used for dragging to check
         // if elements should be deselected on pointerup
@@ -10218,20 +10406,38 @@ class App extends React.Component<AppProps, AppState> {
           );
 
           let linearElementEditor = this.state.selectedLinearElement;
-          if (!linearElementEditor) {
+
+          if (
+            !linearElementEditor ||
+            linearElementEditor.elementId !== newElement.id
+          ) {
             linearElementEditor = new LinearElementEditor(
               newElement,
               this.scene.getNonDeletedElementsMap(),
             );
+          }
+
+          const lastClickedPointOutOfBounds =
+            linearElementEditor &&
+            (linearElementEditor.initialState.lastClickedPoint < 0 ||
+              linearElementEditor.initialState.lastClickedPoint >=
+                points.length);
+          if (lastClickedPointOutOfBounds) {
+            console.warn(
+              "Last clicked point is out of bounds. Attempting to fix it.",
+            );
             linearElementEditor = {
               ...linearElementEditor,
-              selectedPointsIndices: [1],
+              selectedPointsIndices: [points.length - 1],
               initialState: {
                 ...linearElementEditor.initialState,
-                lastClickedPoint: 1,
+                prevSelectedPointsIndices: null,
+                lastClickedPoint: points.length - 1,
               },
+              hoverPointIndex: points.length - 1,
             };
           }
+
           this.setState({
             newElement,
             ...LinearElementEditor.handlePointDragging(
@@ -10726,7 +10932,7 @@ class App extends React.Component<AppProps, AppState> {
               sceneCoords,
             });
           }
-          this.setState({ suggestedBinding: null, startBoundElement: null });
+          this.setState({ suggestedBinding: null });
           if (!activeTool.locked) {
             resetCursor(this.interactiveCanvas);
             this.setState((prevState) => ({
@@ -10747,9 +10953,9 @@ class App extends React.Component<AppProps, AppState> {
               ),
             }));
           } else {
-            this.setState((prevState) => ({
+            this.setState({
               newElement: null,
-            }));
+            });
           }
           // so that the scene gets rendered again to display the newly drawn linear as well
           this.scene.triggerUpdate();
@@ -10811,7 +11017,6 @@ class App extends React.Component<AppProps, AppState> {
             this.scene.getElementsMapIncludingDeleted(),
             elementsInsideFrame,
             newElement,
-            this.state,
           ),
         );
       }
@@ -10871,9 +11076,14 @@ class App extends React.Component<AppProps, AppState> {
           }
         } else {
           // update the relationships between selected elements and frames
-          const topLayerFrame = this.getTopLayerFrameAtSceneCoords(sceneCoords);
-
           const selectedElements = this.scene.getSelectedElements(this.state);
+          const topLayerFrame = this.getTopLayerFrameAtSceneCoords(
+            sceneCoords,
+            {
+              currentFrameId: getCommonFrameId(selectedElements),
+              excludeElementIds: this.state.selectedElementIds,
+            },
+          );
           let nextElements = this.scene.getElementsMapIncludingDeleted();
 
           const updateGroupIdsAfterEditingGroup = (
@@ -10922,10 +11132,8 @@ class App extends React.Component<AppProps, AppState> {
             topLayerFrame &&
             !this.state.selectedElementIds[topLayerFrame.id]
           ) {
-            const elementsToAdd = selectedElements.filter(
-              (element) =>
-                element.frameId !== topLayerFrame.id &&
-                isElementInFrame(element, nextElements, this.state),
+            const elementsToAdd = selectedElements.filter((element) =>
+              isElementInFrame(element, nextElements, this.state),
             );
 
             if (this.state.editingGroupId) {
@@ -10936,7 +11144,6 @@ class App extends React.Component<AppProps, AppState> {
               nextElements,
               elementsToAdd,
               topLayerFrame,
-              this.state,
             );
           } else if (!topLayerFrame) {
             if (this.state.editingGroupId) {
@@ -10998,7 +11205,6 @@ class App extends React.Component<AppProps, AppState> {
               elementsMap,
             ),
             frame,
-            this,
           );
         }
 
@@ -11513,9 +11719,11 @@ class App extends React.Component<AppProps, AppState> {
 
     const existingFileData = this.files[fileId];
     if (!existingFileData?.dataURL) {
+      const { maxWidthOrHeight, maxFileSizeBytes } = this.props.imageOptions;
+
       try {
         imageFile = await resizeImageFile(imageFile, {
-          maxWidthOrHeight: DEFAULT_MAX_IMAGE_WIDTH_OR_HEIGHT,
+          maxWidthOrHeight,
         });
       } catch (error: any) {
         console.error(
@@ -11524,10 +11732,10 @@ class App extends React.Component<AppProps, AppState> {
         );
       }
 
-      if (imageFile.size > MAX_ALLOWED_FILE_BYTES) {
+      if (imageFile.size > maxFileSizeBytes) {
         throw new Error(
           t("errors.fileTooBig", {
-            maxSize: `${Math.trunc(MAX_ALLOWED_FILE_BYTES / 1024 / 1024)}MB`,
+            maxSize: `${Math.trunc(maxFileSizeBytes / 1024 / 1024)}MB`,
           }),
         );
       }
@@ -11814,7 +12022,7 @@ class App extends React.Component<AppProps, AppState> {
       sceneY,
       gridPadding,
     );
-    placeholders.forEach((el) => this.scene.insertElement(el));
+    this.insertNewElements(placeholders);
 
     // Create, position, insert and select initialized (replacing placeholders)
     const initialized = await Promise.all(
@@ -11942,6 +12150,7 @@ class App extends React.Component<AppProps, AppState> {
               type: "everything",
               elements: item.elements,
               randomizeSeed: true,
+              preserveFrameChildrenOrder: true,
             }).duplicatedElements,
           }));
 

packages/excalidraw/components/LayerUI.tsx

@@ -650,8 +650,7 @@ const LayerUI = ({
 };
 
 const stripIrrelevantAppStateProps = (appState: AppState): UIAppState => {
-  const { startBoundElement, cursorButton, scrollX, scrollY, ...ret } =
-    appState;
+  const { cursorButton, scrollX, scrollY, ...ret } = appState;
   return ret;
 };
 

packages/excalidraw/components/LibraryMenuItems.tsx

@@ -199,6 +199,7 @@ export default function LibraryMenuItems({
             type: "everything",
             elements: item.elements,
             randomizeSeed: true,
+            preserveFrameChildrenOrder: true,
           }).duplicatedElements,
         };
       });

packages/excalidraw/components/SVGLayer.tsx

@@ -2,7 +2,7 @@ import { useEffect, useRef } from "react";
 
 import "./SVGLayer.scss";
 
-import type { Trail } from "../animated-trail";
+import type { Trail } from "../animatedTrail";
 
 type SVGLayerProps = {
   trails: Trail[];

packages/excalidraw/components/Stats/Dimension.tsx

@@ -206,7 +206,6 @@ const handleDimensionChange: DragInputCallbackType<
           scene.getElementsIncludingDeleted(),
           nextElementsInFrame,
           latestElement,
-          app,
         );
 
         scene.replaceAllElements(updatedElements);
@@ -302,7 +301,6 @@ const handleDragFinished: DragFinishedCallbackType = ({
       app.scene.getElementsIncludingDeleted(),
       nextElementsInFrame,
       latestElement,
-      app,
     );
 
     app.scene.replaceAllElements(updatedElements);

packages/excalidraw/components/Stats/MultiDimension.tsx

@@ -261,7 +261,6 @@ const handleDimensionChange: DragInputCallbackType<
               scene.getElementsIncludingDeleted(),
               nextElementsInFrame,
               latestElement,
-              app,
             );
 
             scene.replaceAllElements(updatedElements);
@@ -416,7 +415,6 @@ const handleDragFinished: DragFinishedCallbackType = ({
       app.scene.getElementsIncludingDeleted(),
       nextElementsInFrame,
       latestElement,
-      app,
     );
 
     app.scene.replaceAllElements(updatedElements);

packages/excalidraw/components/canvases/InteractiveCanvas.tsx

@@ -39,7 +39,7 @@ type InteractiveCanvasProps = {
   visibleElements: readonly NonDeletedExcalidrawElement[];
   selectedElements: readonly NonDeletedExcalidrawElement[];
   allElementsMap: NonDeletedSceneElementsMap;
-  sceneNonce: number | undefined;
+  canvasNonce: string;
   selectionNonce: number | undefined;
   scale: number;
   appState: InteractiveCanvasAppState;
@@ -253,6 +253,7 @@ const getRelevantAppStateProps = (
   newElement: appState.newElement,
   isBindingEnabled: appState.isBindingEnabled,
   isMidpointSnappingEnabled: appState.isMidpointSnappingEnabled,
+  gridModeEnabled: appState.gridModeEnabled,
   suggestedBinding: appState.suggestedBinding,
   isRotating: appState.isRotating,
   elementsToHighlight: appState.elementsToHighlight,
@@ -279,10 +280,10 @@ const areEqual = (
   // This could be further optimised if needed, as we don't have to render interactive canvas on each scene mutation
   if (
     prevProps.selectionNonce !== nextProps.selectionNonce ||
-    prevProps.sceneNonce !== nextProps.sceneNonce ||
+    prevProps.canvasNonce !== nextProps.canvasNonce ||
     prevProps.scale !== nextProps.scale ||
     // we need to memoize on elementsMap because they may have renewed
-    // even if sceneNonce didn't change (e.g. we filter elements out based
+    // even if canvasNonce didn't change (e.g. we filter elements out based
     // on appState)
     prevProps.elementsMap !== nextProps.elementsMap ||
     prevProps.visibleElements !== nextProps.visibleElements ||

packages/excalidraw/components/canvases/NewElementCanvas.tsx

@@ -14,6 +14,7 @@ import type { RoughCanvas } from "roughjs/bin/canvas";
 
 interface NewElementCanvasProps {
   appState: AppState;
+  newElement: NonNullable<AppState["newElement"]>;
   elementsMap: RenderableElementsMap;
   allElementsMap: NonDeletedSceneElementsMap;
   scale: number;
@@ -31,7 +32,7 @@ const NewElementCanvas = (props: NewElementCanvasProps) => {
       {
         canvas: canvasRef.current,
         scale: props.scale,
-        newElement: props.appState.newElement,
+        newElement: props.newElement,
         elementsMap: props.elementsMap,
         allElementsMap: props.allElementsMap,
         rc: props.rc,

packages/excalidraw/components/canvases/StaticCanvas.tsx

@@ -23,7 +23,7 @@ type StaticCanvasProps = {
   elementsMap: RenderableElementsMap;
   allElementsMap: NonDeletedSceneElementsMap;
   visibleElements: readonly NonDeletedExcalidrawElement[];
-  sceneNonce: number | undefined;
+  canvasNonce: string;
   selectionNonce: number | undefined;
   scale: number;
   appState: StaticCanvasAppState;
@@ -110,10 +110,10 @@ const areEqual = (
   nextProps: StaticCanvasProps,
 ) => {
   if (
-    prevProps.sceneNonce !== nextProps.sceneNonce ||
+    prevProps.canvasNonce !== nextProps.canvasNonce ||
     prevProps.scale !== nextProps.scale ||
     // we need to memoize on elementsMap because they may have renewed
-    // even if sceneNonce didn't change (e.g. we filter elements out based
+    // even if canvasNonce didn't change (e.g. we filter elements out based
     // on appState)
     prevProps.elementsMap !== nextProps.elementsMap ||
     prevProps.visibleElements !== nextProps.visibleElements

packages/excalidraw/components/shapes.tsx

@@ -119,15 +119,12 @@ export const SHAPES = [
 export const getToolbarTools = (app: AppClassProperties) => {
   return app.state.preferredSelectionTool.type === "lasso"
     ? ([
+        SHAPES[0],
         {
+          ...SHAPES[1],
           value: "lasso",
-          icon: SelectionIcon,
-          key: KEYS.V,
-          numericKey: KEYS["1"],
-          fillable: true,
-          toolbar: true,
         },
-        ...SHAPES.slice(1),
+        ...SHAPES.slice(2),
       ] as const)
     : SHAPES;
 };

packages/excalidraw/css/styles.scss

@@ -814,6 +814,14 @@ body.excalidraw-cursor-resize * {
   .excalidraw__embeddable__outer {
     width: 100%;
     height: 100%;
+  }
+
+  .excalidraw__embeddable__content {
+    width: 100%;
+    height: 100%;
+    transform-origin: top left;
+
+    &,
     & > * {
       border-radius: var(--embeddable-radius);
     }

packages/excalidraw/data/blob.ts

@@ -311,6 +311,48 @@ export const dataURLToString = (dataURL: DataURL) => {
   return base64ToString(dataURL.slice(dataURL.indexOf(",") + 1));
 };
 
+const getImageFileDimensions = async (file: File) => {
+  const browserURL = typeof window !== "undefined" ? window.URL : undefined;
+  let objectURL: string | null = null;
+  let imageSource: string;
+
+  try {
+    imageSource = browserURL?.createObjectURL
+      ? (objectURL = browserURL.createObjectURL(file))
+      : await getDataURL(file);
+  } catch {
+    objectURL = null;
+    imageSource = await getDataURL(file);
+  }
+
+  return new Promise<{ width: number; height: number }>((resolve, reject) => {
+    const image = new Image();
+
+    const cleanup = () => {
+      image.onload = null;
+      image.onerror = null;
+
+      if (objectURL && browserURL?.revokeObjectURL) {
+        browserURL.revokeObjectURL(objectURL);
+      }
+    };
+
+    image.onload = () => {
+      cleanup();
+      resolve({
+        width: image.naturalWidth || image.width,
+        height: image.naturalHeight || image.height,
+      });
+    };
+    image.onerror = (error) => {
+      cleanup();
+      reject(error);
+    };
+
+    image.src = imageSource;
+  });
+};
+
 export const resizeImageFile = async (
   file: File,
   opts: {
@@ -324,6 +366,20 @@ export const resizeImageFile = async (
     return file;
   }
 
+  if (!isSupportedImageFile(file)) {
+    throw new Error("Error: unsupported file type", { cause: "UNSUPPORTED" });
+  }
+
+  if (!opts.outputType || opts.outputType === file.type) {
+    const dimensions = await getImageFileDimensions(file);
+
+    if (
+      Math.max(dimensions.width, dimensions.height) <= opts.maxWidthOrHeight
+    ) {
+      return file;
+    }
+  }
+
   const [pica, imageBlobReduce] = await Promise.all([
     import("pica").then((res) => res.default),
     // a wrapper for pica for better API
@@ -347,10 +403,6 @@ export const resizeImageFile = async (
     };
   }
 
-  if (!isSupportedImageFile(file)) {
-    throw new Error("Error: unsupported file type", { cause: "UNSUPPORTED" });
-  }
-
   return new File(
     [await reduce.toBlob(file, { max: opts.maxWidthOrHeight, alpha: true })],
     file.name,

packages/excalidraw/data/restore.ts

@@ -1,4 +1,4 @@
-import { isFiniteNumber, pointFrom } from "@excalidraw/math";
+import { isFiniteNumber, isValidPoint, pointFrom } from "@excalidraw/math";
 
 import {
   type CombineBrandsIfNeeded,
@@ -96,6 +96,69 @@ type RestoredAppState = Omit<
   "offsetTop" | "offsetLeft" | "width" | "height"
 >;
 
+const MAX_ARROW_PX = 75_000;
+
+const restoreLinearElementPoints = (
+  points: unknown,
+  width: unknown,
+  height: unknown,
+): LocalPoint[] => {
+  const restoredPoints = Array.isArray(points)
+    ? points.reduce<LocalPoint[]>((acc, point) => {
+        if (isValidPoint(point)) {
+          acc.push(pointFrom<LocalPoint>(point[0], point[1]));
+        }
+        return acc;
+      }, [])
+    : [];
+
+  return restoredPoints.length < 2
+    ? [
+        pointFrom<LocalPoint>(0, 0),
+        pointFrom<LocalPoint>(
+          isFiniteNumber(width) ? width : 0,
+          isFiniteNumber(height) ? height : 0,
+        ),
+      ]
+    : restoredPoints;
+};
+
+const restoreFreedrawPoints = (
+  points: unknown,
+  pressures: unknown,
+): {
+  points: LocalPoint[];
+  pressures: number[];
+} => {
+  if (!Array.isArray(points)) {
+    return {
+      points: [],
+      pressures: [],
+    };
+  }
+
+  const pressureValues: readonly unknown[] = Array.isArray(pressures)
+    ? pressures
+    : [];
+  const restoredPoints: LocalPoint[] = [];
+  const restoredPressures: number[] = [];
+
+  points.forEach((point, index) => {
+    if (isValidPoint(point)) {
+      restoredPoints.push(pointFrom<LocalPoint>(point[0], point[1]));
+      if (index in pressureValues) {
+        const pressure = pressureValues[index];
+        restoredPressures.push(isFiniteNumber(pressure) ? pressure : 0.5);
+      }
+    }
+  });
+
+  return {
+    points: restoredPoints,
+    pressures: restoredPressures,
+  };
+};
+
 export const AllowedExcalidrawActiveTools: Record<
   AppState["activeTool"]["type"],
   boolean
@@ -412,10 +475,15 @@ export const restoreElement = (
 
       return element;
     case "freedraw": {
+      const { points, pressures } = restoreFreedrawPoints(
+        element.points,
+        element.pressures,
+      );
+
       return restoreElementWithProperties(element, {
-        points: element.points,
+        points,
         simulatePressure: element.simulatePressure,
-        pressures: element.pressures,
+        pressures,
       });
     }
     case "image":
@@ -433,14 +501,20 @@ export const restoreElement = (
       const endArrowhead = normalizeArrowhead(element.endArrowhead);
       let x = element.x;
       let y = element.y;
-      let points = // migrate old arrow model to new one
-        !Array.isArray(element.points) || element.points.length < 2
-          ? [pointFrom(0, 0), pointFrom(element.width, element.height)]
-          : element.points;
+      let points = restoreLinearElementPoints(
+        element.points,
+        element.width,
+        element.height,
+      );
 
       if (points[0][0] !== 0 || points[0][1] !== 0) {
         ({ points, x, y } =
-          LinearElementEditor.getNormalizeElementPointsAndCoords(element));
+          LinearElementEditor.getNormalizeElementPointsAndCoords({
+            ...element,
+            points,
+            x: x ?? 0,
+            y: y ?? 0,
+          } as ExcalidrawLinearElement));
       }
 
       return restoreElementWithProperties(element, {
@@ -454,7 +528,7 @@ export const restoreElement = (
         y,
         ...(isLineElement(element)
           ? {
-              polygon: isValidPolygon(element.points)
+              polygon: isValidPolygon(points)
                 ? element.polygon ?? false
                 : false,
             }
@@ -467,24 +541,31 @@ export const restoreElement = (
         element.endArrowhead === undefined
           ? "arrow"
           : normalizeArrowhead(element.endArrowhead);
-      const x: number | undefined = element.x;
-      const y: number | undefined = element.y;
-      const points: readonly LocalPoint[] | undefined = // migrate old arrow model to new one
-        !Array.isArray(element.points) || element.points.length < 2
-          ? [pointFrom(0, 0), pointFrom(element.width, element.height)]
-          : element.points;
+      const x = element.x as number | undefined;
+      const y = element.y as number | undefined;
+      const points = restoreLinearElementPoints(
+        element.points,
+        element.width,
+        element.height,
+      );
+      const elementWithRestoredPoints = {
+        ...element,
+        points,
+        x: x ?? 0,
+        y: y ?? 0,
+      } as ExcalidrawArrowElement;
 
       const base = {
         type: element.type,
         startBinding: repairBinding(
-          element as ExcalidrawArrowElement,
+          elementWithRestoredPoints,
           element.startBinding,
           targetElementsMap,
           existingElementsMap,
           "start",
         ),
         endBinding: repairBinding(
-          element as ExcalidrawArrowElement,
+          elementWithRestoredPoints,
           element.endBinding,
           targetElementsMap,
           existingElementsMap,
@@ -493,8 +574,8 @@ export const restoreElement = (
         startArrowhead,
         endArrowhead,
         points,
-        x,
-        y,
+        x: x ?? 0,
+        y: y ?? 0,
         elbowed: (element as ExcalidrawArrowElement).elbowed,
         ...getSizeFromPoints(points),
       };
@@ -513,12 +594,44 @@ export const restoreElement = (
           })
         : restoreElementWithProperties(element as ExcalidrawArrowElement, base);
 
-      return {
+      const normalizedRestoredElement = {
         ...restoredElement,
         ...LinearElementEditor.getNormalizeElementPointsAndCoords(
           restoredElement,
         ),
       };
+
+      // Last resort fix for extremely large arrows
+      if (
+        normalizedRestoredElement.width > MAX_ARROW_PX ||
+        normalizedRestoredElement.height > MAX_ARROW_PX
+      ) {
+        console.error(
+          `Removing extremely large arrow ${
+            normalizedRestoredElement.id
+          } (type: ${
+            isElbowArrow(normalizedRestoredElement) ? "elbow" : "simple"
+          }, width: ${normalizedRestoredElement.width}, height: ${
+            normalizedRestoredElement.height
+          }, x: ${normalizedRestoredElement.x}, y: ${
+            normalizedRestoredElement.y
+          })`,
+        );
+        return {
+          ...normalizedRestoredElement,
+          x: 0,
+          y: 0,
+          width: 100,
+          height: 100,
+          points: [
+            pointFrom<LocalPoint>(0, 0),
+            pointFrom<LocalPoint>(100, 100),
+          ],
+          isDeleted: true,
+        };
+      }
+
+      return normalizedRestoredElement;
     }
 
     // generic elements
@@ -666,6 +779,7 @@ export const restoreElements = <T extends ExcalidrawElement>(
   const existingElementsMap = existingElements
     ? arrayToMap(existingElements)
     : null;
+
   const restoredElements = syncInvalidIndices(
     (targetElements || []).reduce((elements, element) => {
       // filtering out selection, which is legacy, no longer kept in elements,
@@ -762,7 +876,7 @@ export const restoreElements = <T extends ExcalidrawElement>(
     }
   }
 
-  // NOTE (mtolmacs): Temporary fix for extremely large arrows
+  // NOTE (mtolmacs): Temporary fix for invalid/self-bound elbow arrows
   // Need to iterate again so we have attached text nodes in elementsMap
   return restoredElements.map((element) => {
     if (

packages/excalidraw/eraser/index.ts

@@ -33,9 +33,7 @@ import type { Bounds } from "@excalidraw/common";
 import type { GlobalPoint, LineSegment } from "@excalidraw/math/types";
 import type { ElementsMap, ExcalidrawElement } from "@excalidraw/element/types";
 
-import { AnimatedTrail } from "../animated-trail";
-
-import type { AnimationFrameHandler } from "../animation-frame-handler";
+import { AnimatedTrail } from "../animatedTrail";
 
 import type App from "../components/App";
 
@@ -43,8 +41,8 @@ export class EraserTrail extends AnimatedTrail {
   private elementsToErase: Set<ExcalidrawElement["id"]> = new Set();
   private groupsToErase: Set<ExcalidrawElement["id"]> = new Set();
 
-  constructor(animationFrameHandler: AnimationFrameHandler, app: App) {
-    super(animationFrameHandler, app, {
+  constructor(app: App) {
+    super(app, {
       streamline: 0.2,
       size: 5,
       keepHead: true,

packages/excalidraw/history.ts

@@ -87,22 +87,10 @@ export class HistoryChangedEvent {
   ) {}
 }
 
-export type HistoryBeforeRecordListener = (delta: StoreDelta) => void;
-export type HistoryPerformDirection = "undo" | "redo";
-export type HistoryEffectiveDeltaResolverContext = {
-  direction: HistoryPerformDirection;
-};
-export type HistoryEffectiveDeltaResolver = (
-  delta: HistoryDelta,
-  context: HistoryEffectiveDeltaResolverContext,
-) => HistoryDelta;
-
 export class History {
   public readonly onHistoryChangedEmitter = new Emitter<
     [HistoryChangedEvent]
   >();
-  private readonly onBeforeRecordEmitter = new Emitter<[StoreDelta]>();
-  private effectiveDeltaResolver: HistoryEffectiveDeltaResolver | null = null;
 
   public readonly undoStack: HistoryDelta[] = [];
   public readonly redoStack: HistoryDelta[] = [];
@@ -117,20 +105,6 @@ export class History {
 
   constructor(private readonly store: Store) {}
 
-  /**
-   * Registers a hook that runs before a durable delta is converted
-   * into a history entry.
-   */
-  public onBeforeRecord(callback: HistoryBeforeRecordListener) {
-    return this.onBeforeRecordEmitter.on(callback);
-  }
-
-  public setEffectiveDeltaResolver(
-    resolver: HistoryEffectiveDeltaResolver | null,
-  ) {
-    this.effectiveDeltaResolver = resolver;
-  }
-
   public clear() {
     this.undoStack.length = 0;
     this.redoStack.length = 0;
@@ -145,8 +119,6 @@ export class History {
       return;
     }
 
-    this.onBeforeRecordEmitter.trigger(delta);
-
     // construct history entry, so once it's emitted, it's not recorded again
     const historyDelta = HistoryDelta.inverse(delta);
 
@@ -159,14 +131,15 @@ export class History {
       this.redoStack.length = 0;
     }
 
-    this.emitHistoryChanged();
+    this.onHistoryChangedEmitter.trigger(
+      new HistoryChangedEvent(this.isUndoStackEmpty, this.isRedoStackEmpty),
+    );
   }
 
   public undo(elements: SceneElementsMap, appState: AppState) {
     return this.perform(
       elements,
       appState,
-      "undo",
       () => History.pop(this.undoStack),
       (entry: HistoryDelta) => History.push(this.redoStack, entry),
     );
@@ -176,7 +149,6 @@ export class History {
     return this.perform(
       elements,
       appState,
-      "redo",
       () => History.pop(this.redoStack),
       (entry: HistoryDelta) => History.push(this.undoStack, entry),
     );
@@ -185,7 +157,6 @@ export class History {
   private perform(
     elements: SceneElementsMap,
     appState: AppState,
-    direction: HistoryPerformDirection,
     pop: () => HistoryDelta | null,
     push: (entry: HistoryDelta) => void,
   ): [SceneElementsMap, AppState] | void {
@@ -206,15 +177,9 @@ export class History {
 
       // iterate through the history entries in case they result in no visible changes
       while (historyDelta) {
-        // Roundtrip invariant: whichever delta we execute must be the one that
-        // continues through applyLatestChanges -> inverse -> opposite stack.
-        let entryToPush = historyDelta;
         try {
-          const effectiveDelta = this.resolveEffectiveDelta(historyDelta, {
-            direction,
-          });
           [nextElements, nextAppState, containsVisibleChange] =
-            effectiveDelta.applyTo(nextElements, nextAppState, prevSnapshot);
+            historyDelta.applyTo(nextElements, nextAppState, prevSnapshot);
 
           const prevElements = prevSnapshot.elements;
           const nextSnapshot = prevSnapshot.maybeClone(
@@ -225,7 +190,7 @@ export class History {
 
           const change = StoreChange.create(prevSnapshot, nextSnapshot);
           const delta = HistoryDelta.applyLatestChanges(
-            effectiveDelta,
+            historyDelta,
             prevElements,
             nextElements,
           );
@@ -238,12 +203,12 @@ export class History {
               delta,
             });
 
-            entryToPush = delta;
+            historyDelta = delta;
           }
 
           prevSnapshot = nextSnapshot;
         } finally {
-          push(entryToPush);
+          push(historyDelta);
         }
 
         if (containsVisibleChange) {
@@ -257,16 +222,12 @@ export class History {
     } finally {
       // trigger the history change event before returning completely
       // also trigger it just once, no need doing so on each entry
-      this.emitHistoryChanged();
+      this.onHistoryChangedEmitter.trigger(
+        new HistoryChangedEvent(this.isUndoStackEmpty, this.isRedoStackEmpty),
+      );
     }
   }
 
-  private emitHistoryChanged() {
-    this.onHistoryChangedEmitter.trigger(
-      new HistoryChangedEvent(this.isUndoStackEmpty, this.isRedoStackEmpty),
-    );
-  }
-
   private static pop(stack: HistoryDelta[]): HistoryDelta | null {
     if (!stack.length) {
       return null;
@@ -285,15 +246,4 @@ export class History {
     const inversedEntry = HistoryDelta.inverse(entry);
     return stack.push(inversedEntry);
   }
-
-  private resolveEffectiveDelta(
-    delta: HistoryDelta,
-    context: HistoryEffectiveDeltaResolverContext,
-  ): HistoryDelta {
-    if (!this.effectiveDeltaResolver) {
-      return delta;
-    }
-
-    return this.effectiveDeltaResolver(delta, context);
-  }
 }

packages/excalidraw/index.tsx

@@ -6,7 +6,11 @@ import React, {
   useState,
 } from "react";
 
-import { DEFAULT_UI_OPTIONS, isShallowEqual } from "@excalidraw/common";
+import {
+  DEFAULT_IMAGE_OPTIONS,
+  DEFAULT_UI_OPTIONS,
+  isShallowEqual,
+} from "@excalidraw/common";
 
 import App, {
   ExcalidrawAPIContext,
@@ -98,6 +102,7 @@ const ExcalidrawBase = (props: ExcalidrawProps) => {
     aiEnabled,
     showDeprecatedFonts,
     renderScrollbars,
+    imageOptions,
   } = props;
 
   const canvasActions = props.UIOptions?.canvasActions;
@@ -128,6 +133,13 @@ const ExcalidrawBase = (props: ExcalidrawProps) => {
     UIOptions.canvasActions.toggleTheme = true;
   }
 
+  const normalizedImageOptions: AppProps["imageOptions"] = {
+    maxFileSizeBytes:
+      imageOptions?.maxFileSizeBytes ?? DEFAULT_IMAGE_OPTIONS.maxFileSizeBytes,
+    maxWidthOrHeight:
+      imageOptions?.maxWidthOrHeight ?? DEFAULT_IMAGE_OPTIONS.maxWidthOrHeight,
+  };
+
   const setExcalidrawAPI = useContext(ExcalidrawAPISetContext);
 
   const onExcalidrawAPIRef = useRef(onExcalidrawAPI);
@@ -208,6 +220,7 @@ const ExcalidrawBase = (props: ExcalidrawProps) => {
           aiEnabled={aiEnabled !== false}
           showDeprecatedFonts={showDeprecatedFonts}
           renderScrollbars={renderScrollbars}
+          imageOptions={normalizedImageOptions}
         >
           {children}
         </App>
@@ -225,11 +238,13 @@ const areEqual = (prevProps: ExcalidrawProps, nextProps: ExcalidrawProps) => {
   const {
     initialData: prevInitialData,
     UIOptions: prevUIOptions = {},
+    imageOptions: prevImageOptions,
     ...prev
   } = prevProps;
   const {
     initialData: nextInitialData,
     UIOptions: nextUIOptions = {},
+    imageOptions: nextImageOptions,
     ...next
   } = nextProps;
 
@@ -273,7 +288,17 @@ const areEqual = (prevProps: ExcalidrawProps, nextProps: ExcalidrawProps) => {
     return prevUIOptions[key] === nextUIOptions[key];
   });
 
-  return isUIOptionsSame && isShallowEqual(prev, next);
+  const isImageOptionsSame =
+    (prevImageOptions?.maxWidthOrHeight ??
+      DEFAULT_IMAGE_OPTIONS.maxWidthOrHeight) ===
+      (nextImageOptions?.maxWidthOrHeight ??
+        DEFAULT_IMAGE_OPTIONS.maxWidthOrHeight) &&
+    (prevImageOptions?.maxFileSizeBytes ??
+      DEFAULT_IMAGE_OPTIONS.maxFileSizeBytes) ===
+      (nextImageOptions?.maxFileSizeBytes ??
+        DEFAULT_IMAGE_OPTIONS.maxFileSizeBytes);
+
+  return isUIOptionsSame && isImageOptionsSame && isShallowEqual(prev, next);
 };
 
 export const Excalidraw = React.memo(ExcalidrawBase, areEqual);

packages/excalidraw/laserTrails.ts

@@ -2,27 +2,20 @@ import { DEFAULT_LASER_COLOR, easeOut } from "@excalidraw/common";
 
 import type { LaserPointerOptions } from "@excalidraw/laser-pointer";
 
-import { AnimatedTrail } from "./animated-trail";
+import { AnimatedTrail } from "./animatedTrail";
 import { getClientColor } from "./clients";
 
-import type { Trail } from "./animated-trail";
-import type { AnimationFrameHandler } from "./animation-frame-handler";
+import type { Trail } from "./animatedTrail";
 import type App from "./components/App";
 import type { SocketId } from "./types";
 
 export class LaserTrails implements Trail {
   public localTrail: AnimatedTrail;
   private collabTrails = new Map<SocketId, AnimatedTrail>();
-
   private container?: SVGSVGElement;
 
-  constructor(
-    private animationFrameHandler: AnimationFrameHandler,
-    private app: App,
-  ) {
-    this.animationFrameHandler.register(this, this.onFrame.bind(this));
-
-    this.localTrail = new AnimatedTrail(animationFrameHandler, app, {
+  constructor(private app: App) {
+    this.localTrail = new AnimatedTrail(app, {
       ...this.getTrailOptions(),
       fill: () => DEFAULT_LASER_COLOR,
     });
@@ -63,30 +56,45 @@ export class LaserTrails implements Trail {
 
   start(container: SVGSVGElement) {
     this.container = container;
-
-    this.animationFrameHandler.start(this);
     this.localTrail.start(container);
   }
 
   stop() {
-    this.animationFrameHandler.stop(this);
     this.localTrail.stop();
+    this.stopCollabTrails();
+    this.container = undefined;
   }
 
-  onFrame() {
-    this.updateCollabTrails();
+  private stopCollabTrails(collaborators?: App["state"]["collaborators"]) {
+    for (const [key, trail] of this.collabTrails) {
+      const collaborator = collaborators?.get(key);
+
+      if (!collaborator) {
+        trail.stop();
+        this.collabTrails.delete(key);
+      }
+    }
   }
 
-  private updateCollabTrails() {
-    if (!this.container || this.app.state.collaborators.size === 0) {
+  updateCollabTrails(collaborators: App["state"]["collaborators"]) {
+    this.stopCollabTrails(collaborators);
+
+    if (!this.container || collaborators.size === 0) {
       return;
     }
 
-    for (const [key, collaborator] of this.app.state.collaborators.entries()) {
-      let trail!: AnimatedTrail;
+    for (const [key, collaborator] of collaborators.entries()) {
+      // Current user has their own trail drawn via localTrail
+      if (collaborator.isCurrentUser) {
+        continue;
+      }
 
-      if (!this.collabTrails.has(key)) {
-        trail = new AnimatedTrail(this.animationFrameHandler, this.app, {
+      // IDEA: Use the collaborator pointer coordinates to trace out the
+      // laser pointer trail when 1) the selected collab tool is the laser
+      // pointer and 2) the collab pointer button is in the "down" state.
+      let trail = this.collabTrails.get(key);
+      if (!trail) {
+        trail = new AnimatedTrail(this.app, {
           ...this.getTrailOptions(),
           fill: () =>
             collaborator.pointer?.laserColor ||
@@ -95,36 +103,33 @@ export class LaserTrails implements Trail {
         trail.start(this.container);
 
         this.collabTrails.set(key, trail);
-      } else {
-        trail = this.collabTrails.get(key)!;
       }
 
       if (collaborator.pointer && collaborator.pointer.tool === "laser") {
-        if (collaborator.button === "down" && !trail.hasCurrentTrail) {
+        const buttonDown = collaborator.button === "down";
+        const buttonUp = collaborator.button === "up";
+        const hasTrail = trail.hasCurrentTrail;
+
+        // Initialize a new trail
+        if (buttonDown && !hasTrail) {
           trail.startPath(collaborator.pointer.x, collaborator.pointer.y);
         }
 
-        if (
-          collaborator.button === "down" &&
-          trail.hasCurrentTrail &&
-          !trail.hasLastPoint(collaborator.pointer.x, collaborator.pointer.y)
-        ) {
+        // Add only original points
+        const lastPointOriginal = !trail.hasLastPoint(
+          collaborator.pointer.x,
+          collaborator.pointer.y,
+        );
+        if (buttonDown && lastPointOriginal) {
           trail.addPointToPath(collaborator.pointer.x, collaborator.pointer.y);
         }
 
-        if (collaborator.button === "up" && trail.hasCurrentTrail) {
+        // End the trail on button up
+        if (buttonUp && hasTrail) {
           trail.addPointToPath(collaborator.pointer.x, collaborator.pointer.y);
           trail.endPath();
         }
       }
     }
-
-    for (const key of this.collabTrails.keys()) {
-      if (!this.app.state.collaborators.has(key)) {
-        const trail = this.collabTrails.get(key)!;
-        trail.stop();
-        this.collabTrails.delete(key);
-      }
-    }
   }
 }

packages/excalidraw/lasso/index.ts

@@ -25,9 +25,7 @@ import type {
   NonDeleted,
 } from "@excalidraw/element/types";
 
-import { type AnimationFrameHandler } from "../animation-frame-handler";
-
-import { AnimatedTrail } from "../animated-trail";
+import { AnimatedTrail } from "../animatedTrail";
 
 import { getLassoSelectedElementIds } from "./utils";
 
@@ -47,8 +45,8 @@ export class LassoTrail extends AnimatedTrail {
   private canvasTranslate: CanvasTranslate | null = null;
   private keepPreviousSelection: boolean = false;
 
-  constructor(animationFrameHandler: AnimationFrameHandler, app: App) {
-    super(animationFrameHandler, app, {
+  constructor(app: App) {
+    super(app, {
       animateTrail: true,
       streamline: 0.4,
       sizeMapping: (c) => {

packages/excalidraw/package.json

@@ -83,19 +83,18 @@
     "@codemirror/language": "^6.0.0",
     "@codemirror/state": "^6.0.0",
     "@codemirror/view": "^6.0.0",
+    "@lezer/highlight": "^1.0.0",
     "@excalidraw/common": "0.18.0",
     "@excalidraw/element": "0.18.0",
     "@excalidraw/laser-pointer": "1.3.1",
     "@excalidraw/math": "0.18.0",
     "@excalidraw/mermaid-to-excalidraw": "2.2.2",
     "@excalidraw/random-username": "1.1.0",
-    "@lezer/highlight": "^1.0.0",
     "browser-fs-access": "0.38.0",
     "canvas-roundrect-polyfill": "0.0.1",
     "clsx": "1.1.1",
     "cross-env": "7.0.3",
     "es6-promise-pool": "2.5.0",
-    "fractional-indexing": "3.2.0",
     "fuzzy": "0.1.3",
     "image-blob-reduce": "3.0.1",
     "jotai": "2.11.0",

packages/excalidraw/polyfill.ts

@@ -23,6 +23,94 @@ const polyfill = () => {
     });
   }
 
+  if (!Array.prototype.findLast) {
+    Object.defineProperty(Array.prototype, "findLast", {
+      value: function <T>(
+        this: T[],
+        predicate: (value: T, index: number, array: T[]) => unknown,
+        thisArg?: unknown,
+      ) {
+        return this
+          .slice()
+          .reverse()
+          .find((value, index) =>
+            predicate.call(thisArg, value, this.length - index - 1, this),
+          );
+      },
+      writable: true,
+      enumerable: false,
+      configurable: true,
+    });
+  }
+
+  if (!Array.prototype.findIndex) {
+    Object.defineProperty(Array.prototype, "findIndex", {
+      value: function <T>(
+        this: T[],
+        predicate: (value: T, index: number, array: T[]) => unknown,
+        thisArg?: unknown,
+      ) {
+        for (let index = 0; index < this.length; index++) {
+          if (predicate.call(thisArg, this[index], index, this)) {
+            return index;
+          }
+        }
+
+        return -1;
+      },
+      writable: true,
+      enumerable: false,
+      configurable: true,
+    });
+  }
+
+  if (!Array.prototype.findLastIndex) {
+    Object.defineProperty(Array.prototype, "findLastIndex", {
+      value: function <T>(
+        this: T[],
+        predicate: (value: T, index: number, array: T[]) => unknown,
+        thisArg?: unknown,
+      ) {
+        const index = this
+          .slice()
+          .reverse()
+          .findIndex((value, index) =>
+            predicate.call(thisArg, value, this.length - index - 1, this),
+          );
+
+        return index === -1 ? -1 : this.length - index - 1;
+      },
+      writable: true,
+      enumerable: false,
+      configurable: true,
+    });
+  }
+
+  if (!Array.prototype.toReversed) {
+    Object.defineProperty(Array.prototype, "toReversed", {
+      value: function <T>(this: T[]) {
+        return this.slice().reverse();
+      },
+      writable: true,
+      enumerable: false,
+      configurable: true,
+    });
+  }
+
+  if (!Array.prototype.toSorted) {
+    Object.defineProperty(Array.prototype, "toSorted", {
+      value: function <T>(
+        this: T[],
+        compareFn?: (a: T, b: T) => number,
+      ) {
+        return this.slice().sort(compareFn);
+      },
+      writable: true,
+      enumerable: false,
+      configurable: true,
+    });
+  }
+
   if (!Element.prototype.replaceChildren) {
     Element.prototype.replaceChildren = function (...nodes) {
       this.innerHTML = "";

packages/excalidraw/renderer/animation.ts

@@ -6,7 +6,10 @@ export type Animation<R extends object> = (params: {
 }) => R | null | undefined;
 
 export class AnimationController {
-  private static isRunning = false;
+  private static scheduledFrame:
+    | { id: ReturnType<typeof requestAnimationFrame>; type: "raf" }
+    | { id: ReturnType<typeof setTimeout>; type: "timeout" }
+    | null = null;
   private static animations = new Map<
     string,
     {
@@ -17,6 +20,10 @@ export class AnimationController {
   >();
 
   static start<R extends object>(key: string, animation: Animation<R>) {
+    if (AnimationController.animations.has(key)) {
+      return;
+    }
+
     const initialState = animation({
       deltaTime: 0,
       state: undefined,
@@ -29,19 +36,54 @@ export class AnimationController {
         state: initialState,
       });
 
-      if (!AnimationController.isRunning) {
-        AnimationController.isRunning = true;
-
-        if (isRenderThrottlingEnabled()) {
-          requestAnimationFrame(AnimationController.tick);
-        } else {
-          setTimeout(AnimationController.tick, 0);
-        }
-      }
+      AnimationController.scheduleNextFrame();
     }
   }
 
+  private static scheduleNextFrame() {
+    if (AnimationController.scheduledFrame) {
+      return;
+    }
+
+    if (isRenderThrottlingEnabled()) {
+      AnimationController.scheduledFrame = {
+        id: requestAnimationFrame(AnimationController.tick),
+        type: "raf",
+      };
+    } else {
+      AnimationController.scheduledFrame = {
+        id: setTimeout(AnimationController.tick, 0),
+        type: "timeout",
+      };
+    }
+  }
+
+  private static cancelScheduledFrame() {
+    if (!AnimationController.scheduledFrame) {
+      return;
+    }
+
+    if (AnimationController.scheduledFrame.type === "raf") {
+      cancelAnimationFrame(AnimationController.scheduledFrame.id);
+    } else {
+      clearTimeout(AnimationController.scheduledFrame.id);
+    }
+
+    AnimationController.scheduledFrame = null;
+  }
+
+  private static cancelScheduledFrameIfIdle() {
+    if (AnimationController.animations.size > 0) {
+      return false;
+    }
+
+    AnimationController.cancelScheduledFrame();
+    return true;
+  }
+
   private static tick() {
+    AnimationController.scheduledFrame = null;
+
     if (AnimationController.animations.size > 0) {
       for (const [key, animation] of AnimationController.animations) {
         const now = performance.now();
@@ -56,8 +98,7 @@ export class AnimationController {
         if (!state) {
           AnimationController.animations.delete(key);
 
-          if (AnimationController.animations.size === 0) {
-            AnimationController.isRunning = false;
+          if (AnimationController.cancelScheduledFrameIfIdle()) {
             return;
           }
         } else {
@@ -66,11 +107,11 @@ export class AnimationController {
         }
       }
 
-      if (isRenderThrottlingEnabled()) {
-        requestAnimationFrame(AnimationController.tick);
-      } else {
-        setTimeout(AnimationController.tick, 0);
+      if (AnimationController.cancelScheduledFrameIfIdle()) {
+        return;
       }
+
+      AnimationController.scheduleNextFrame();
     }
   }
 
@@ -80,5 +121,6 @@ export class AnimationController {
 
   static cancel(key: string) {
     AnimationController.animations.delete(key);
+    AnimationController.cancelScheduledFrameIfIdle();
   }
 }

packages/excalidraw/renderer/interactiveScene.ts

@@ -17,6 +17,7 @@ import {
   FRAME_STYLE,
   getFeatureFlag,
   invariant,
+  shouldRotateWithDiscreteAngle,
   THEME,
 } from "@excalidraw/common";
 
@@ -229,6 +230,7 @@ const renderBindingHighlightForBindableElement_simple = (
   elementsMap: ElementsMap,
   appState: InteractiveCanvasAppState,
   pointerCoords: GlobalPoint | null,
+  angleLocked = false,
 ) => {
   const enclosingFrame =
     suggestedBinding.element.frameId &&
@@ -415,6 +417,8 @@ const renderBindingHighlightForBindableElement_simple = (
 
   if (
     appState.isMidpointSnappingEnabled &&
+    !appState.gridModeEnabled &&
+    !angleLocked &&
     (isFrameLikeElement(suggestedBinding.element) ||
       isBindableElement(suggestedBinding.element))
   ) {
@@ -807,7 +811,12 @@ const renderBindingHighlightForBindableElement_complex = (
 
     context.restore();
 
-    if (appState.isMidpointSnappingEnabled) {
+    if (
+      appState.isMidpointSnappingEnabled &&
+      !appState.gridModeEnabled &&
+      (!app.lastPointerMoveEvent ||
+        !shouldRotateWithDiscreteAngle(app.lastPointerMoveEvent))
+    ) {
       // Draw midpoint indicators
       context.save();
       context.translate(
@@ -920,12 +929,16 @@ const renderBindingHighlightForBindableElement = (
         app.lastPointerMoveCoords.y,
       )
     : null;
+  const angleLocked =
+    !!app.lastPointerMoveEvent &&
+    shouldRotateWithDiscreteAngle(app.lastPointerMoveEvent);
   renderBindingHighlightForBindableElement_simple(
     context,
     suggestedBinding,
     allElementsMap,
     appState,
     pointerCoords,
+    angleLocked,
   );
   context.restore();
 };

packages/excalidraw/scene/Renderer.ts

@@ -1,9 +1,15 @@
-import { isElementInViewport } from "@excalidraw/element";
+import {
+  getCommonFrameId,
+  getFrameChildrenInsertionIndex,
+  isElementInViewport,
+} from "@excalidraw/element";
 
-import { memoize, toBrandedType } from "@excalidraw/common";
+import { arrayToMap, memoize, toBrandedType } from "@excalidraw/common";
 
 import type {
   ExcalidrawElement,
+  ExcalidrawFrameLikeElement,
+  NonDeleted,
   NonDeletedElementsMap,
   NonDeletedExcalidrawElement,
 } from "@excalidraw/element/types";
@@ -16,6 +22,21 @@ import type { RenderableElementsMap } from "./types";
 
 import type { AppState } from "../types";
 
+type GetRenderableElementsOpts = {
+  zoom: AppState["zoom"];
+  offsetLeft: AppState["offsetLeft"];
+  offsetTop: AppState["offsetTop"];
+  scrollX: AppState["scrollX"];
+  scrollY: AppState["scrollY"];
+  height: AppState["height"];
+  width: AppState["width"];
+  editingTextElement: AppState["editingTextElement"];
+  newElement: AppState["newElement"];
+  selectedElements: readonly NonDeletedExcalidrawElement[];
+  selectedElementsAreBeingDragged: AppState["selectedElementsAreBeingDragged"];
+  frameToHighlight: AppState["frameToHighlight"];
+};
+
 export class Renderer {
   private scene: Scene;
 
@@ -23,9 +44,121 @@ export class Renderer {
     this.scene = scene;
   }
 
-  public getRenderableElements = (() => {
-    const getVisibleCanvasElements = ({
-      elementsMap,
+  private getVisibleCanvasElements({
+    elementsMap,
+    zoom,
+    offsetLeft,
+    offsetTop,
+    scrollX,
+    scrollY,
+    height,
+    width,
+  }: {
+    elementsMap: NonDeletedElementsMap;
+    zoom: AppState["zoom"];
+    offsetLeft: AppState["offsetLeft"];
+    offsetTop: AppState["offsetTop"];
+    scrollX: AppState["scrollX"];
+    scrollY: AppState["scrollY"];
+    height: AppState["height"];
+    width: AppState["width"];
+  }): readonly NonDeletedExcalidrawElement[] {
+    const visibleElements: NonDeletedExcalidrawElement[] = [];
+    for (const element of elementsMap.values()) {
+      if (
+        isElementInViewport(
+          element,
+          width,
+          height,
+          {
+            zoom,
+            offsetLeft,
+            offsetTop,
+            scrollX,
+            scrollY,
+          },
+          elementsMap,
+        )
+      ) {
+        visibleElements.push(element);
+      }
+    }
+    return visibleElements;
+  }
+
+  private getRenderableElementsMap({
+    elements,
+    editingTextElement,
+    newElement,
+  }: {
+    elements: readonly NonDeletedExcalidrawElement[];
+    editingTextElement: AppState["editingTextElement"];
+    newElement: AppState["newElement"];
+  }) {
+    const elementsMap = toBrandedType<RenderableElementsMap>(new Map());
+    const newElementCanvasElement = newElement?.frameId ? null : newElement;
+
+    for (const element of elements) {
+      if (newElementCanvasElement?.id === element.id) {
+        continue;
+      }
+
+      // we don't want to render text element that's being currently edited
+      // (it's rendered on remote only)
+      if (
+        !editingTextElement ||
+        editingTextElement.type !== "text" ||
+        element.id !== editingTextElement.id
+      ) {
+        elementsMap.set(element.id, element);
+      }
+    }
+    return { elementsMap, newElementCanvasElement };
+  }
+
+  private sortSelectedElementsIntoHighlightedFrame<
+    T extends ExcalidrawElement,
+  >({
+    visibleElements,
+    selectedElements,
+    frameToHighlight,
+  }: {
+    selectedElements: readonly NonDeletedExcalidrawElement[];
+    visibleElements: readonly T[];
+    frameToHighlight: NonDeleted<ExcalidrawFrameLikeElement>;
+  }): readonly T[] {
+    if (!selectedElements.length) {
+      return visibleElements;
+    }
+
+    // we assume all selected elements are eligible frame children if
+    // frameToHighlight is defined
+    const selectedElementsMap = arrayToMap(selectedElements);
+
+    // thus, all deselected elements are the ones we won't reorder
+    const deselectedElements = visibleElements.filter(
+      (element) => !selectedElementsMap.has(element.id),
+    );
+
+    const insertionIndex = getFrameChildrenInsertionIndex(
+      deselectedElements,
+      frameToHighlight.id,
+    );
+
+    if (insertionIndex === null) {
+      return visibleElements;
+    }
+
+    return [
+      ...deselectedElements.slice(0, insertionIndex),
+      ...selectedElements,
+      ...deselectedElements.slice(insertionIndex),
+    ] as readonly T[];
+  }
+
+  private _getRenderableElements = memoize(
+    ({
+      canvasNonce,
       zoom,
       offsetLeft,
       offsetTop,
@@ -33,70 +166,27 @@ export class Renderer {
       scrollY,
       height,
       width,
-    }: {
-      elementsMap: NonDeletedElementsMap;
-      zoom: AppState["zoom"];
-      offsetLeft: AppState["offsetLeft"];
-      offsetTop: AppState["offsetTop"];
-      scrollX: AppState["scrollX"];
-      scrollY: AppState["scrollY"];
-      height: AppState["height"];
-      width: AppState["width"];
-    }): readonly NonDeletedExcalidrawElement[] => {
-      const visibleElements: NonDeletedExcalidrawElement[] = [];
-      for (const element of elementsMap.values()) {
-        if (
-          isElementInViewport(
-            element,
-            width,
-            height,
-            {
-              zoom,
-              offsetLeft,
-              offsetTop,
-              scrollX,
-              scrollY,
-            },
-            elementsMap,
-          )
-        ) {
-          visibleElements.push(element);
-        }
-      }
-      return visibleElements;
-    };
-
-    const getRenderableElements = ({
-      elements,
       editingTextElement,
-      newElementId,
-    }: {
-      elements: readonly NonDeletedExcalidrawElement[];
-      editingTextElement: AppState["editingTextElement"];
-      newElementId: ExcalidrawElement["id"] | undefined;
+      newElement,
+    }: Omit<
+      GetRenderableElementsOpts,
+      | "selectedElements"
+      | "selectedElementsAreBeingDragged"
+      | "frameToHighlight"
+    > & {
+      canvasNonce: string;
     }) => {
-      const elementsMap = toBrandedType<RenderableElementsMap>(new Map());
+      const elements = this.scene.getNonDeletedElements();
 
-      for (const element of elements) {
-        if (newElementId === element.id) {
-          continue;
-        }
+      const { elementsMap, newElementCanvasElement } =
+        this.getRenderableElementsMap({
+          elements,
+          editingTextElement,
+          newElement,
+        });
 
-        // we don't want to render text element that's being currently edited
-        // (it's rendered on remote only)
-        if (
-          !editingTextElement ||
-          editingTextElement.type !== "text" ||
-          element.id !== editingTextElement.id
-        ) {
-          elementsMap.set(element.id, element);
-        }
-      }
-      return elementsMap;
-    };
-
-    return memoize(
-      ({
+      const visibleElements = this.getVisibleCanvasElements({
+        elementsMap,
         zoom,
         offsetLeft,
         offsetTop,
@@ -104,52 +194,69 @@ export class Renderer {
         scrollY,
         height,
         width,
-        editingTextElement,
-        newElementId,
-        // cache-invalidation nonce
-        sceneNonce: _sceneNonce,
-      }: {
-        zoom: AppState["zoom"];
-        offsetLeft: AppState["offsetLeft"];
-        offsetTop: AppState["offsetTop"];
-        scrollX: AppState["scrollX"];
-        scrollY: AppState["scrollY"];
-        height: AppState["height"];
-        width: AppState["width"];
-        editingTextElement: AppState["editingTextElement"];
-        /** note: first render of newElement will always bust the cache
-         * (we'd have to prefilter elements outside of this function) */
-        newElementId: ExcalidrawElement["id"] | undefined;
-        sceneNonce: ReturnType<InstanceType<typeof Scene>["getSceneNonce"]>;
-      }) => {
-        const elements = this.scene.getNonDeletedElements();
+      });
 
-        const elementsMap = getRenderableElements({
-          elements,
-          editingTextElement,
-          newElementId,
+      return {
+        elementsMap,
+        visibleElements,
+        newElementCanvasElement,
+        canvasNonce,
+      };
+    },
+  );
+
+  public getRenderableElements = (opts: GetRenderableElementsOpts) => {
+    const { newElement } = opts;
+    const canvasNonce = `${this.scene.getSceneNonce()}${
+      newElement?.frameId ? `:${newElement.versionNonce}` : ""
+    }`;
+
+    const ret = this._getRenderableElements({
+      canvasNonce,
+
+      // don't spread `opts` because we don't want to memoize on some props
+
+      zoom: opts.zoom,
+      offsetLeft: opts.offsetLeft,
+      offsetTop: opts.offsetTop,
+      scrollX: opts.scrollX,
+      scrollY: opts.scrollY,
+      height: opts.height,
+      width: opts.width,
+      editingTextElement: opts.editingTextElement,
+      newElement: opts.newElement,
+    });
+
+    // if we're dragging elements over a frame, reorder the selected elements
+    // inside the frame during render (we don't set the `element.frameId` until
+    // pointerup else we'd have to painstainly restore the orig index if user
+    // didn't end up adding elements to the frame)
+    if (
+      opts.frameToHighlight &&
+      opts.selectedElementsAreBeingDragged &&
+      // if all dragged elements are already in the frame, don't reorder
+      getCommonFrameId(opts.selectedElements) !== opts.frameToHighlight.id
+    ) {
+      const reorderedVisibleElements =
+        this.sortSelectedElementsIntoHighlightedFrame({
+          visibleElements: ret.visibleElements,
+          selectedElements: opts.selectedElements,
+          frameToHighlight: opts.frameToHighlight,
         });
 
-        const visibleElements = getVisibleCanvasElements({
-          elementsMap,
-          zoom,
-          offsetLeft,
-          offsetTop,
-          scrollX,
-          scrollY,
-          height,
-          width,
-        });
+      return {
+        ...ret,
+        visibleElements: reorderedVisibleElements,
+      };
+    }
 
-        return { elementsMap, visibleElements };
-      },
-    );
-  })();
+    return ret;
+  };
 
   // NOTE Doesn't destroy everything (scene, rc, etc.) because it may not be
   // safe to break TS contract here (for upstream cases)
   public destroy() {
     renderStaticSceneThrottled.cancel();
-    this.getRenderableElements.clear();
+    this._getRenderableElements.clear();
   }
 }

packages/excalidraw/tests/MermaidToExcalidraw.test.tsx

@@ -83,6 +83,26 @@ mockMermaidToExcalidraw({
   },
 });
 
+const normalizeDialogSnapshot = (dialog: Element) => {
+  const dialogClone = dialog.cloneNode(true) as HTMLElement;
+
+  dialogClone
+    .querySelectorAll<HTMLElement>(".ttd-dialog-content")
+    .forEach((element) => {
+      // Radix Tabs injects this during initial mount animation prevention.
+      // Its presence depends on render timing and is unrelated to this test.
+      if (element.style.animationDuration === "0s") {
+        element.style.removeProperty("animation-duration");
+      }
+
+      if (!element.getAttribute("style")) {
+        element.removeAttribute("style");
+      }
+    });
+
+  return dialogClone.outerHTML;
+};
+
 describe("Test <MermaidToExcalidraw/>", () => {
   beforeEach(async () => {
     await render(
@@ -99,7 +119,7 @@ describe("Test <MermaidToExcalidraw/>", () => {
   it("should open mermaid popup when active tool is mermaid", async () => {
     const dialog = document.querySelector(".ttd-dialog")!;
     await waitFor(() => expect(dialog.querySelector("canvas")).not.toBeNull());
-    expect(dialog.outerHTML).toMatchSnapshot();
+    expect(normalizeDialogSnapshot(dialog)).toMatchSnapshot();
   });
 
   it("should show error in preview when mermaid library throws error", async () => {

packages/excalidraw/tests/__snapshots__/MermaidToExcalidraw.test.tsx.snap

@@ -1,6 +1,6 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Test <MermaidToExcalidraw/> > should open mermaid popup when active tool is mermaid 1`] = `"<div class="Modal Dialog ttd-dialog" role="dialog" aria-modal="true" aria-labelledby="dialog-title"><div class="Modal__background"></div><div class="Modal__content" style="--max-width: 1520px;" tabindex="0"><div class="Island"><div class="Dialog__content"><div dir="ltr" data-orientation="horizontal" class="ttd-dialog-tabs-root"><p class="dialog-mermaid-title">Mermaid to Excalidraw</p><div data-state="active" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-:r4:-trigger-mermaid" id="radix-:r4:-content-mermaid" tabindex="0" class="ttd-dialog-content" style=""><div class="ttd-dialog-desc">Currently only <a href="https://mermaid.js.org/syntax/flowchart.html" target="_blank" rel="noreferrer">Flowchart</a>, <a href="https://mermaid.js.org/syntax/sequenceDiagram.html" target="_blank" rel="noreferrer">Sequence</a>, <a href="https://mermaid.js.org/syntax/classDiagram.html" target="_blank" rel="noreferrer">Class</a>, and <a href="https://mermaid.js.org/syntax/entityRelationshipDiagram.html" target="_blank" rel="noreferrer">Entity Relationship</a> Diagrams are supported. The other types will be rendered as image in Excalidraw.</div><div class="ttd-dialog-panels"><div class="ttd-dialog-panel"><div class="ttd-dialog-panel-button-container invisible" style="justify-content: flex-start;"></div></div><div class="ttd-dialog-panel"><div class="ttd-dialog-output-wrapper "><div class="ttd-dialog-output-canvas-container"><div class="ttd-dialog-output-canvas-content"><canvas width="89" height="158" dir="ltr"></canvas></div></div></div><div class="ttd-dialog-panel-button-container" style="justify-content: flex-start;"><button type="button" class="excalidraw-button ttd-dialog-panel-button"><div class="">Insert<span><svg aria-hidden="true" focusable="false" role="img" viewBox="0 0 20 20" class="" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"><g stroke-width="1.25"><path d="M4.16602 10H15.8327"></path><path d="M12.5 13.3333L15.8333 10"></path><path d="M12.5 6.66666L15.8333 9.99999"></path></g></svg></span></div></button><div class="ttd-dialog-submit-shortcut"><div class="ttd-dialog-submit-shortcut__key">Ctrl</div><div class="ttd-dialog-submit-shortcut__key">Enter</div></div></div></div></div></div></div></div></div></div></div>"`;
+exports[`Test <MermaidToExcalidraw/> > should open mermaid popup when active tool is mermaid 1`] = `"<div class="Modal Dialog ttd-dialog" role="dialog" aria-modal="true" aria-labelledby="dialog-title"><div class="Modal__background"></div><div class="Modal__content" style="--max-width: 1520px;" tabindex="0"><div class="Island"><div class="Dialog__content"><div dir="ltr" data-orientation="horizontal" class="ttd-dialog-tabs-root"><p class="dialog-mermaid-title">Mermaid to Excalidraw</p><div data-state="active" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-:r4:-trigger-mermaid" id="radix-:r4:-content-mermaid" tabindex="0" class="ttd-dialog-content"><div class="ttd-dialog-desc">Currently only <a href="https://mermaid.js.org/syntax/flowchart.html" target="_blank" rel="noreferrer">Flowchart</a>, <a href="https://mermaid.js.org/syntax/sequenceDiagram.html" target="_blank" rel="noreferrer">Sequence</a>, <a href="https://mermaid.js.org/syntax/classDiagram.html" target="_blank" rel="noreferrer">Class</a>, and <a href="https://mermaid.js.org/syntax/entityRelationshipDiagram.html" target="_blank" rel="noreferrer">Entity Relationship</a> Diagrams are supported. The other types will be rendered as image in Excalidraw.</div><div class="ttd-dialog-panels"><div class="ttd-dialog-panel"><div class="ttd-dialog-panel-button-container invisible" style="justify-content: flex-start;"></div></div><div class="ttd-dialog-panel"><div class="ttd-dialog-output-wrapper "><div class="ttd-dialog-output-canvas-container"><div class="ttd-dialog-output-canvas-content"><canvas width="89" height="158" dir="ltr"></canvas></div></div></div><div class="ttd-dialog-panel-button-container" style="justify-content: flex-start;"><button type="button" class="excalidraw-button ttd-dialog-panel-button"><div class="">Insert<span><svg aria-hidden="true" focusable="false" role="img" viewBox="0 0 20 20" class="" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"><g stroke-width="1.25"><path d="M4.16602 10H15.8327"></path><path d="M12.5 13.3333L15.8333 10"></path><path d="M12.5 6.66666L15.8333 9.99999"></path></g></svg></span></div></button><div class="ttd-dialog-submit-shortcut"><div class="ttd-dialog-submit-shortcut__key">Ctrl</div><div class="ttd-dialog-submit-shortcut__key">Enter</div></div></div></div></div></div></div></div></div></div></div>"`;
 
 exports[`Test <MermaidToExcalidraw/> > should show error in preview when mermaid library throws error 1`] = `
 "flowchart TD

packages/excalidraw/tests/__snapshots__/contextmenu.test.tsx.snap

@@ -979,7 +979,6 @@ exports[`contextMenu element > right-clicking on a group should select whole gro
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -1173,7 +1172,6 @@ exports[`contextMenu element > selecting 'Add to library' in context menu adds e
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -1388,7 +1386,6 @@ exports[`contextMenu element > selecting 'Bring forward' in context menu brings
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -1720,7 +1717,6 @@ exports[`contextMenu element > selecting 'Bring to front' in context menu brings
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -2052,7 +2048,6 @@ exports[`contextMenu element > selecting 'Copy styles' in context menu copies st
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -2265,7 +2260,6 @@ exports[`contextMenu element > selecting 'Delete' in context menu deletes elemen
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -2509,7 +2503,6 @@ exports[`contextMenu element > selecting 'Duplicate' in context menu duplicates
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -2813,7 +2806,6 @@ exports[`contextMenu element > selecting 'Group selection' in context menu group
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -3181,7 +3173,6 @@ exports[`contextMenu element > selecting 'Paste styles' in context menu pastes s
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -3675,7 +3666,6 @@ exports[`contextMenu element > selecting 'Send backward' in context menu sends e
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -3999,7 +3989,6 @@ exports[`contextMenu element > selecting 'Send to back' in context menu sends el
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -4326,7 +4315,6 @@ exports[`contextMenu element > selecting 'Ungroup selection' in context menu ung
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -5612,7 +5600,6 @@ exports[`contextMenu element > shows 'Group selection' in context menu for multi
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -6832,7 +6819,6 @@ exports[`contextMenu element > shows 'Ungroup selection' in context menu for gro
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -7786,7 +7772,6 @@ exports[`contextMenu element > shows context menu for canvas > [end of test] app
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -8786,7 +8771,6 @@ exports[`contextMenu element > shows context menu for element > [end of test] ap
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -9781,7 +9765,6 @@ exports[`contextMenu element > shows context menu for element > [end of test] ap
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,

packages/excalidraw/tests/__snapshots__/history.test.tsx.snap

@@ -1293,7 +1293,6 @@ exports[`history > multiplayer undo/redo > conflicts in arrows and their bindabl
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -1654,7 +1653,6 @@ exports[`history > multiplayer undo/redo > conflicts in arrows and their bindabl
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -2017,7 +2015,6 @@ exports[`history > multiplayer undo/redo > conflicts in arrows and their bindabl
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -2280,7 +2277,40 @@ exports[`history > multiplayer undo/redo > conflicts in arrows and their bindabl
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
+  "startBoundElement": {
+    "angle": 0,
+    "backgroundColor": "transparent",
+    "boundElements": [
+      {
+        "id": "id4",
+        "type": "arrow",
+      },
+    ],
+    "customData": undefined,
+    "fillStyle": "solid",
+    "frameId": null,
+    "groupIds": [],
+    "height": 100,
+    "id": "id0",
+    "index": "a0",
+    "isDeleted": false,
+    "link": null,
+    "locked": false,
+    "opacity": 100,
+    "roughness": 1,
+    "roundness": null,
+    "seed": 1,
+    "strokeColor": "#1e1e1e",
+    "strokeStyle": "solid",
+    "strokeWidth": 2,
+    "type": "rectangle",
+    "updated": 1,
+    "version": 3,
+    "versionNonce": 493213705,
+    "width": 100,
+    "x": -100,
+    "y": -50,
+  },
   "stats": {
     "open": false,
     "panels": 3,
@@ -2735,7 +2765,6 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -3039,7 +3068,6 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -3359,7 +3387,6 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -3654,7 +3681,6 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -3941,7 +3967,6 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -4177,7 +4202,6 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -4435,7 +4459,6 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -4707,7 +4730,6 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -4937,7 +4959,6 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -5167,7 +5188,6 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -5415,7 +5435,6 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -5672,7 +5691,6 @@ exports[`history > multiplayer undo/redo > conflicts in frames and their childre
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -5930,7 +5948,6 @@ exports[`history > multiplayer undo/redo > should iterate through the history wh
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -6260,7 +6277,6 @@ exports[`history > multiplayer undo/redo > should iterate through the history wh
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -6691,7 +6707,6 @@ exports[`history > multiplayer undo/redo > should iterate through the history wh
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -7072,7 +7087,6 @@ exports[`history > multiplayer undo/redo > should iterate through the history wh
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -7667,7 +7681,6 @@ exports[`history > multiplayer undo/redo > should iterate through the history wh
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -7898,7 +7911,6 @@ exports[`history > multiplayer undo/redo > should iterate through the history wh
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -8251,7 +8263,6 @@ exports[`history > multiplayer undo/redo > should iterate through the history wh
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -8610,7 +8621,6 @@ exports[`history > multiplayer undo/redo > should not let remote changes to inte
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -9011,7 +9021,6 @@ exports[`history > multiplayer undo/redo > should not let remote changes to inte
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -9293,7 +9302,6 @@ exports[`history > multiplayer undo/redo > should not let remote changes to inte
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -9558,7 +9566,6 @@ exports[`history > multiplayer undo/redo > should not override remote changes on
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -9824,7 +9831,6 @@ exports[`history > multiplayer undo/redo > should not override remote changes on
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -10058,7 +10064,6 @@ exports[`history > multiplayer undo/redo > should override remotely added groups
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -10671,7 +10676,6 @@ exports[`history > multiplayer undo/redo > should redistribute deltas when eleme
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -10911,7 +10915,6 @@ exports[`history > multiplayer undo/redo > should redraw arrows on undo > [end o
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -11836,7 +11839,6 @@ exports[`history > multiplayer undo/redo > should update history entries after r
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -12095,7 +12097,6 @@ exports[`history > singleplayer undo/redo > remounting undo/redo buttons should
   "showHyperlinkPopup": false,
   "showWelcomeScreen": false,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -12333,7 +12334,6 @@ exports[`history > singleplayer undo/redo > should clear the redo stack on eleme
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -12569,7 +12569,6 @@ exports[`history > singleplayer undo/redo > should create entry when selecting f
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -12966,7 +12965,6 @@ exports[`history > singleplayer undo/redo > should create new history entry on e
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -13174,7 +13172,6 @@ exports[`history > singleplayer undo/redo > should create new history entry on e
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -13386,7 +13383,6 @@ exports[`history > singleplayer undo/redo > should create new history entry on i
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -13685,7 +13681,6 @@ exports[`history > singleplayer undo/redo > should create new history entry on i
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -13984,7 +13979,6 @@ exports[`history > singleplayer undo/redo > should create new history entry on s
   "showHyperlinkPopup": false,
   "showWelcomeScreen": false,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -14229,7 +14223,6 @@ exports[`history > singleplayer undo/redo > should disable undo/redo buttons whe
   "showHyperlinkPopup": false,
   "showWelcomeScreen": false,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -14467,7 +14460,6 @@ exports[`history > singleplayer undo/redo > should end up with no history entry
   "showHyperlinkPopup": false,
   "showWelcomeScreen": false,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -14705,7 +14697,6 @@ exports[`history > singleplayer undo/redo > should iterate through the history w
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -14953,7 +14944,6 @@ exports[`history > singleplayer undo/redo > should not clear the redo stack on s
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -15286,7 +15276,6 @@ exports[`history > singleplayer undo/redo > should not collapse when applying co
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -15459,7 +15448,6 @@ exports[`history > singleplayer undo/redo > should not end up with history entry
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -15742,7 +15730,6 @@ exports[`history > singleplayer undo/redo > should not end up with history entry
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -16006,7 +15993,6 @@ exports[`history > singleplayer undo/redo > should not modify anything on unrela
   "showHyperlinkPopup": false,
   "showWelcomeScreen": false,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -16161,7 +16147,6 @@ exports[`history > singleplayer undo/redo > should not override appstate changes
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -16443,7 +16428,6 @@ exports[`history > singleplayer undo/redo > should support appstate name or view
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -20170,7 +20154,6 @@ exports[`history > singleplayer undo/redo > should support changes in elements'
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -20653,7 +20636,6 @@ exports[`history > singleplayer undo/redo > should support duplication of groups
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -21160,7 +21142,6 @@ exports[`history > singleplayer undo/redo > should support element creation, del
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,

packages/excalidraw/tests/__snapshots__/regressionTests.test.tsx.snap

@@ -106,7 +106,6 @@ exports[`given element A and group of elements B and given both are selected whe
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -535,7 +534,6 @@ exports[`given element A and group of elements B and given both are selected whe
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -943,7 +941,6 @@ exports[`regression tests > Cmd/Ctrl-click exclusively select element under poin
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -1510,7 +1507,6 @@ exports[`regression tests > Drags selected element when hitting only bounding bo
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -1723,7 +1719,6 @@ exports[`regression tests > adjusts z order when grouping > [end of test] appSta
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -2105,7 +2100,6 @@ exports[`regression tests > alt-drag duplicates an element > [end of test] appSt
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -2349,7 +2343,6 @@ exports[`regression tests > arrow keys > [end of test] appState 1`] = `
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -2532,7 +2525,6 @@ exports[`regression tests > can drag element that covers another element, while
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -2856,7 +2848,6 @@ exports[`regression tests > change the properties of a shape > [end of test] app
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -3114,7 +3105,6 @@ exports[`regression tests > click on an element and drag it > [dragged] appState
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -3356,7 +3346,6 @@ exports[`regression tests > click on an element and drag it > [end of test] appS
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -3593,7 +3582,6 @@ exports[`regression tests > click to select a shape > [end of test] appState 1`]
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -3853,7 +3841,6 @@ exports[`regression tests > click-drag to select a group > [end of test] appStat
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -4167,7 +4154,6 @@ exports[`regression tests > deleting last but one element in editing group shoul
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -4631,7 +4617,6 @@ exports[`regression tests > deselects group of selected elements on pointer down
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -4887,7 +4872,6 @@ exports[`regression tests > deselects group of selected elements on pointer up w
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -5191,7 +5175,6 @@ exports[`regression tests > deselects selected element on pointer down when poin
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -5372,7 +5355,6 @@ exports[`regression tests > deselects selected element, on pointer up, when clic
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -5573,7 +5555,6 @@ exports[`regression tests > double click to edit a group > [end of test] appStat
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -5971,7 +5952,6 @@ exports[`regression tests > drags selected elements from point inside common bou
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -7057,7 +7037,6 @@ exports[`regression tests > given a group of selected elements with an element t
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -7392,7 +7371,6 @@ exports[`regression tests > given a selected element A and a not selected elemen
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -7671,7 +7649,6 @@ exports[`regression tests > given selected element A with lower z-index than uns
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -7907,7 +7884,6 @@ exports[`regression tests > given selected element A with lower z-index than uns
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -8146,7 +8122,6 @@ exports[`regression tests > key 2 selects rectangle tool > [end of test] appStat
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -8327,7 +8302,6 @@ exports[`regression tests > key 3 selects diamond tool > [end of test] appState
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -8508,7 +8482,6 @@ exports[`regression tests > key 4 selects ellipse tool > [end of test] appState
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -9151,7 +9124,6 @@ exports[`regression tests > key 7 selects freedraw tool > [end of test] appState
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -9579,7 +9551,6 @@ exports[`regression tests > key d selects diamond tool > [end of test] appState
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -9991,7 +9962,6 @@ exports[`regression tests > key o selects ellipse tool > [end of test] appState
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -10170,7 +10140,6 @@ exports[`regression tests > key p selects freedraw tool > [end of test] appState
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -10365,7 +10334,6 @@ exports[`regression tests > key r selects rectangle tool > [end of test] appStat
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -10554,7 +10522,6 @@ exports[`regression tests > make a group and duplicate it > [end of test] appSta
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -11080,7 +11047,6 @@ exports[`regression tests > noop interaction after undo shouldn't create history
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -11357,7 +11323,6 @@ exports[`regression tests > pinch-to-zoom works > [end of test] appState 1`] = `
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -11483,7 +11448,6 @@ exports[`regression tests > shift click on selected element should deselect it o
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -11688,7 +11652,6 @@ exports[`regression tests > shift-click to multiselect, then drag > [end of test
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -12010,7 +11973,6 @@ exports[`regression tests > should group elements and ungroup them > [end of tes
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -12444,7 +12406,6 @@ exports[`regression tests > single-clicking on a subgroup of a selected group sh
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -13076,7 +13037,6 @@ exports[`regression tests > spacebar + drag scrolls the canvas > [end of test] a
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -13204,7 +13164,6 @@ exports[`regression tests > supports nested groups > [end of test] appState 1`]
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -13865,7 +13824,6 @@ exports[`regression tests > switches from group of selected elements to another
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -14204,7 +14162,6 @@ exports[`regression tests > switches selected element on pointer down > [end of
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -14437,7 +14394,6 @@ exports[`regression tests > two-finger scroll works > [end of test] appState 1`]
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -14926,7 +14882,6 @@ exports[`regression tests > updates fontSize & fontFamily appState > [end of tes
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,
@@ -15053,7 +15008,6 @@ exports[`regression tests > zoom hotkeys > [end of test] appState 1`] = `
   "showHyperlinkPopup": false,
   "showWelcomeScreen": true,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,

packages/excalidraw/tests/animation.test.ts

@@ -0,0 +1,73 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { AnimationController } from "../renderer/animation";
+
+const FIRST_KEY = "animation-test-first";
+const SECOND_KEY = "animation-test-second";
+
+describe("AnimationController", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    window.EXCALIDRAW_THROTTLE_RENDER = false;
+  });
+
+  afterEach(() => {
+    AnimationController.cancel(FIRST_KEY);
+    AnimationController.cancel(SECOND_KEY);
+    window.EXCALIDRAW_THROTTLE_RENDER = undefined;
+    vi.useRealTimers();
+  });
+
+  it("starts a new animation after the previous last animation was cancelled", async () => {
+    let firstFrames = 0;
+    AnimationController.start(FIRST_KEY, () => {
+      firstFrames++;
+      return { keep: true };
+    });
+
+    expect(firstFrames).toBe(1);
+
+    AnimationController.cancel(FIRST_KEY);
+    await vi.runOnlyPendingTimersAsync();
+
+    let secondFrames = 0;
+    AnimationController.start(SECOND_KEY, () => {
+      secondFrames++;
+      return secondFrames === 1 ? { keep: true } : null;
+    });
+
+    expect(secondFrames).toBe(1);
+
+    await vi.runOnlyPendingTimersAsync();
+
+    expect(secondFrames).toBe(2);
+    expect(AnimationController.running(SECOND_KEY)).toBe(false);
+  });
+
+  it("cancels a frame scheduled during a tick if no animations remain", async () => {
+    let firstFrames = 0;
+    let secondFrames = 0;
+
+    AnimationController.start(FIRST_KEY, ({ state }) => {
+      if (!state) {
+        return { keep: true };
+      }
+
+      firstFrames++;
+
+      AnimationController.start(SECOND_KEY, () => {
+        secondFrames++;
+        return { keep: true };
+      });
+      AnimationController.cancel(SECOND_KEY);
+
+      return null;
+    });
+
+    await vi.runOnlyPendingTimersAsync();
+
+    expect(firstFrames).toBe(1);
+    expect(secondFrames).toBe(1);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});

packages/excalidraw/tests/clipboard.test.tsx

@@ -305,8 +305,88 @@ describe("pasting & frames", () => {
 
     await waitFor(() => {
       expect(h.elements.length).toBe(2);
+      expect(h.elements[0].type).toBe(rect.type);
+      expect(h.elements[0].frameId).toBe(frame.id);
+      expect(h.elements[1].id).toBe(frame.id);
+      expect(h.elements[0].index! < frame.index!).toBe(true);
+    });
+  });
+
+  it("should layer pasted elements above the highest frame child", async () => {
+    const frame = API.createElement({
+      type: "frame",
+      width: 100,
+      height: 100,
+      x: 0,
+      y: 0,
+    });
+    const frameChild = API.createElement({
+      id: "frameChild",
+      type: "rectangle",
+      x: 10,
+      y: 10,
+      width: 20,
+      height: 20,
+      frameId: frame.id,
+    });
+    const rect = API.createElement({ type: "rectangle" });
+
+    API.setElements([frameChild, frame]);
+
+    const clipboardJSON = await serializeAsClipboardJSON({
+      elements: [rect],
+      files: null,
+    });
+
+    mouse.moveTo(50, 50);
+
+    pasteWithCtrlCmdV(clipboardJSON);
+
+    await waitFor(() => {
+      expect(h.elements.length).toBe(3);
       expect(h.elements[1].type).toBe(rect.type);
       expect(h.elements[1].frameId).toBe(frame.id);
+      expect(h.elements.map((element) => element.id)).toEqual([
+        frameChild.id,
+        h.elements[1].id,
+        frame.id,
+      ]);
+      expect(h.elements[1].index! > frameChild.index!).toBe(true);
+      expect(h.elements[1].index! < frame.index!).toBe(true);
+    });
+  });
+
+  it("should preserve denormalized pasted frame child order", async () => {
+    const frame = API.createElement({
+      type: "frame",
+      width: 100,
+      height: 100,
+      x: 0,
+      y: 0,
+    });
+    const frameChild = API.createElement({
+      type: "rectangle",
+      x: 10,
+      y: 10,
+      width: 20,
+      height: 20,
+      frameId: frame.id,
+    });
+
+    const clipboardJSON = await serializeAsClipboardJSON({
+      elements: [frame, frameChild],
+      files: null,
+    });
+
+    mouse.moveTo(200, 200);
+
+    pasteWithCtrlCmdV(clipboardJSON);
+
+    await waitFor(() => {
+      expect(h.elements.length).toBe(2);
+      expect(h.elements[0].type).toBe(frame.type);
+      expect(h.elements[1].type).toBe(frameChild.type);
+      expect(h.elements[1].frameId).toBe(h.elements[0].id);
     });
   });
 
@@ -379,8 +459,9 @@ describe("pasting & frames", () => {
 
     await waitFor(() => {
       expect(h.elements.length).toBe(3);
-      expect(h.elements[1].type).toBe(rect.type);
-      expect(h.elements[1].frameId).toBe(frame.id);
+      expect(h.elements[0].type).toBe(rect.type);
+      expect(h.elements[0].frameId).toBe(frame.id);
+      expect(h.elements[1].id).toBe(frame.id);
       expect(h.elements[2].type).toBe(rect2.type);
       expect(h.elements[2].frameId).toBe(null);
     });
@@ -422,10 +503,11 @@ describe("pasting & frames", () => {
 
     await waitFor(() => {
       expect(h.elements.length).toBe(3);
-      expect(h.elements[1].type).toBe(rect.type);
+      expect(h.elements[0].type).toBe(rect.type);
+      expect(h.elements[0].frameId).toBe(frame.id);
+      expect(h.elements[1].type).toBe(rect2.type);
       expect(h.elements[1].frameId).toBe(frame.id);
-      expect(h.elements[2].type).toBe(rect2.type);
-      expect(h.elements[2].frameId).toBe(frame.id);
+      expect(h.elements[2].id).toBe(frame.id);
     });
   });
 
@@ -473,8 +555,9 @@ describe("pasting & frames", () => {
 
     await waitFor(() => {
       expect(h.elements.length).toBe(4);
-      expect(h.elements[1].type).toBe(rect.type);
-      expect(h.elements[1].frameId).toBe(frame.id);
+      expect(h.elements[0].type).toBe(rect.type);
+      expect(h.elements[0].frameId).toBe(frame.id);
+      expect(h.elements[1].id).toBe(frame.id);
       expect(h.elements[2].type).toBe(rect2.type);
       expect(h.elements[2].frameId).toBe(h.elements[3].id);
       expect(h.elements[3].type).toBe(frame2.type);

packages/excalidraw/tests/data/restore.test.ts

@@ -160,6 +160,39 @@ describe("restoreElements", () => {
     });
   });
 
+  it("should restore only valid freedraw points and keep pressures aligned", () => {
+    const freedrawElement = API.createElement({
+      type: "freedraw",
+      id: "id-freedraw-invalid-points",
+      points: [pointFrom(0, 0), pointFrom(10, 10)],
+    });
+
+    const restoredFreedraw = restore.restoreElements(
+      [
+        {
+          ...freedrawElement,
+          simulatePressure: false,
+          points: [
+            pointFrom(0, 0),
+            [Infinity, 10],
+            null,
+            pointFrom(20, 20),
+            [NaN, 30],
+            [40, null],
+          ],
+          pressures: [0.1, 0.2, 0.3, 0.4, 0.5, 0.6],
+        } as any,
+      ],
+      null,
+    )[0] as ExcalidrawFreeDrawElement;
+
+    expect(restoredFreedraw.points).toEqual([
+      pointFrom(0, 0),
+      pointFrom(20, 20),
+    ]);
+    expect(restoredFreedraw.pressures).toEqual([0.1, 0.4]);
+  });
+
   it("should restore line and draw elements correctly", () => {
     const lineElement = API.createElement({ type: "line", id: "id-line01" });
 
@@ -400,6 +433,52 @@ describe("restoreElements", () => {
     expect(restoredLine.points).toMatchObject(expectedLinePoints);
   });
 
+  it("should restore only valid linear points", () => {
+    const lineElement: any = API.createElement({
+      type: "line",
+      x: 10,
+      y: 20,
+      width: 100,
+      height: 200,
+    });
+    const arrowElement: any = API.createElement({
+      type: "arrow",
+      width: 100,
+      height: 200,
+    });
+
+    lineElement.points = [
+      [2, 3],
+      null,
+      [Infinity, 4],
+      [5, 7],
+      [NaN, 8],
+      [9, null],
+    ];
+    arrowElement.points = [
+      [null, 0],
+      [Infinity, 4],
+    ];
+
+    const restoredElements = restore.restoreElements(
+      [lineElement, arrowElement],
+      null,
+    );
+    const restoredLine = restoredElements[0] as ExcalidrawLinearElement;
+    const restoredArrow = restoredElements[1] as ExcalidrawArrowElement;
+
+    expect(restoredLine.points).toEqual([pointFrom(0, 0), pointFrom(3, 4)]);
+    expect(restoredLine.x).toBe(12);
+    expect(restoredLine.y).toBe(23);
+    expect(restoredLine.width).toBe(3);
+    expect(restoredLine.height).toBe(4);
+
+    expect(restoredArrow.points).toEqual([
+      pointFrom(0, 0),
+      pointFrom(100, 200),
+    ]);
+  });
+
   it("when the number of points of a line is greater or equal 2", () => {
     const lineElement_0 = API.createElement({
       type: "line",

packages/excalidraw/tests/helpers/polyfills.ts

@@ -94,3 +94,42 @@ export const testPolyfills = {
   // https://github.com/vitest-dev/vitest/pull/4164#issuecomment-2172729965
   URL,
 };
+
+export const PolyfillLocalStorage = () => {
+  // Node.js 25+ provides a native localStorage global that shadows jsdom's,
+  // and jsdom's own localStorage also uses the native one -- both are broken
+  // (empty objects without Storage methods). On older Node versions, jsdom
+  // provides a working localStorage. This polyfill replaces localStorage on
+  // all supported versions with a standard Storage implementation backed by
+  // a Map, ensuring consistent behavior regardless of the Node.js version.
+  const storage = new Map<string, string>();
+  const storagePolyfill: Storage = {
+    get length() {
+      return storage.size;
+    },
+    clear() {
+      storage.clear();
+    },
+    key(index) {
+      return Array.from(storage.keys())[index] ?? null;
+    },
+    getItem(key) {
+      return storage.get(key) ?? null;
+    },
+    setItem(key, value) {
+      storage.set(key, value);
+    },
+    removeItem(key) {
+      storage.delete(key);
+    },
+    *[Symbol.iterator]() {
+      yield* storage.entries();
+    },
+  };
+
+  Object.defineProperty(window, "localStorage", {
+    value: storagePolyfill,
+    writable: true,
+    configurable: true,
+  });
+};

packages/excalidraw/tests/image.test.tsx

@@ -1,4 +1,4 @@
-import { randomId, reseed } from "@excalidraw/common";
+import { MIME_TYPES, randomId, reseed } from "@excalidraw/common";
 
 import type { FileId } from "@excalidraw/element/types";
 
@@ -17,18 +17,41 @@ import {
 } from "./fixtures/constants";
 import { INITIALIZED_IMAGE_PROPS } from "./helpers/constants";
 
+import type { ExcalidrawProps } from "../types";
+
 const { h } = window;
 
 export const setupImageTest = async (
   sizes: { width: number; height: number }[],
+  props?: ExcalidrawProps,
 ) => {
-  await render(<Excalidraw autoFocus={true} handleKeyboardGlobally={true} />);
+  await render(
+    <Excalidraw autoFocus={true} handleKeyboardGlobally={true} {...props} />,
+  );
 
   h.state.height = 1000;
 
   mockMultipleHTMLImageElements(sizes.map((size) => [size.width, size.height]));
 };
 
+describe("resizeImageFile", () => {
+  beforeEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("returns the original file when it already fits the max dimensions", async () => {
+    mockMultipleHTMLImageElements([[100, 100]]);
+
+    const imageFile = new File([new Uint8Array([1, 2, 3])], "image.png", {
+      type: MIME_TYPES.png,
+    });
+
+    await expect(
+      blobModule.resizeImageFile(imageFile, { maxWidthOrHeight: 200 }),
+    ).resolves.toBe(imageFile);
+  });
+});
+
 describe("image insertion", () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -112,4 +135,42 @@ describe("image insertion", () => {
 
     await assert();
   });
+
+  it("passes host-configured max image dimensions to the resize helper", async () => {
+    await setupImageTest([DEER_IMAGE_DIMENSIONS], {
+      imageOptions: { maxWidthOrHeight: 2048 },
+    });
+
+    await API.drop([
+      { kind: "file", file: await API.loadFile("./fixtures/deer.png") },
+    ]);
+
+    await waitFor(() => {
+      expect(blobModule.resizeImageFile).toHaveBeenCalledWith(
+        expect.any(File),
+        { maxWidthOrHeight: 2048 },
+      );
+    });
+  });
+
+  it("enforces host-configured max image file size", async () => {
+    await setupImageTest([DEER_IMAGE_DIMENSIONS], {
+      imageOptions: { maxFileSizeBytes: 1024 * 1024 },
+    });
+
+    await API.drop([
+      {
+        kind: "file",
+        file: new File([new Uint8Array(2 * 1024 * 1024)], "image.png", {
+          type: MIME_TYPES.png,
+        }),
+      },
+    ]);
+
+    await waitFor(() => {
+      expect(h.state.errorMessage).toBe(
+        "File is too big. Maximum allowed size is 1MB.",
+      );
+    });
+  });
 });

packages/excalidraw/tests/laser.test.tsx

@@ -10,7 +10,7 @@ import { API } from "./helpers/api";
 import { Pointer } from "./helpers/ui";
 import { act, GlobalTestState, render, waitFor } from "./test-utils";
 
-import type { ExcalidrawProps } from "../types";
+import type { Collaborator, ExcalidrawProps, SocketId } from "../types";
 
 describe("laser tool interactions", () => {
   const h = window.h;
@@ -128,4 +128,36 @@ describe("laser tool interactions", () => {
     expect(h.state.scrollY).toBe(initialScrollY);
     expect(GlobalTestState.interactiveCanvas.style.cursor).toContain("");
   });
+
+  it("cleans up remote laser trails when the last collaborator leaves", async () => {
+    await render(<Excalidraw />);
+
+    const socketId = "socket-id" as SocketId;
+    const collaborators = new Map<SocketId, Collaborator>([
+      [
+        socketId,
+        {
+          pointer: {
+            x: 10,
+            y: 10,
+            tool: "laser",
+          },
+          button: "down",
+        },
+      ],
+    ]);
+    const svgLayer = document.querySelector(".SVGLayer svg")!;
+
+    act(() => {
+      h.app.updateScene({ collaborators });
+    });
+
+    expect(svgLayer.querySelectorAll("path")).toHaveLength(1);
+
+    act(() => {
+      h.app.updateScene({ collaborators: new Map() });
+    });
+
+    expect(svgLayer.querySelectorAll("path")).toHaveLength(0);
+  });
 });

packages/excalidraw/tests/selection.test.tsx

@@ -1,8 +1,12 @@
 import React from "react";
 import { vi } from "vitest";
 
-import { KEYS, ROUNDNESS, reseed } from "@excalidraw/common";
-import { getElementBounds, getElementLineSegments } from "@excalidraw/element";
+import { KEYS, ROUNDNESS, arrayToMap, reseed } from "@excalidraw/common";
+import {
+  getElementBounds,
+  getElementLineSegments,
+  getElementsWithinSelection,
+} from "@excalidraw/element";
 import { pointFrom, pointRotateRads, type LocalPoint } from "@excalidraw/math";
 
 import { SHAPES } from "../components/shapes";
@@ -269,6 +273,145 @@ describe("box-selection overlap mode", () => {
     assertSelectedElements([rect1.id]);
   });
 
+  it("should select the whole group when overlapping one group member", () => {
+    const rect1 = API.createElement({
+      type: "rectangle",
+      x: 0,
+      y: 0,
+      width: 50,
+      height: 50,
+      groupIds: ["A"],
+    });
+    const rect2 = API.createElement({
+      type: "rectangle",
+      x: 100,
+      y: 0,
+      width: 50,
+      height: 50,
+      groupIds: ["A"],
+    });
+
+    API.setElements([rect1, rect2]);
+
+    boxSelect(25, -20, 75, 70);
+
+    assertSelectedElements([rect1.id, rect2.id]);
+    expect(h.state.selectedGroupIds).toEqual({ A: true });
+  });
+
+  it("should return all group elements when overlapping one group member", () => {
+    const rect1 = API.createElement({
+      type: "rectangle",
+      id: "rect1",
+      x: 0,
+      y: 0,
+      width: 50,
+      height: 50,
+      groupIds: ["A"],
+    });
+    const rect2 = API.createElement({
+      type: "rectangle",
+      id: "rect2",
+      x: 100,
+      y: 0,
+      width: 50,
+      height: 50,
+      groupIds: ["A"],
+    });
+    const rect3 = API.createElement({
+      type: "rectangle",
+      id: "rect3",
+      x: 200,
+      y: 0,
+      width: 50,
+      height: 50,
+    });
+    const selection = API.createElement({
+      type: "rectangle",
+      x: 125,
+      y: -10,
+      width: 10,
+      height: 70,
+    });
+    const elements = [rect1, rect2, rect3];
+
+    expect(
+      getElementsWithinSelection(
+        elements,
+        selection,
+        arrayToMap([...elements, selection]),
+        false,
+        "overlap",
+      ).map((element) => element.id),
+    ).toEqual([rect1.id, rect2.id]);
+  });
+
+  it("should retain nested and interleaved group element order", () => {
+    const outerNested1 = API.createElement({
+      type: "rectangle",
+      id: "outerNested1",
+      x: 0,
+      y: 0,
+      width: 50,
+      height: 50,
+      groupIds: ["inner", "outer"],
+    });
+    const other1 = API.createElement({
+      type: "rectangle",
+      id: "other1",
+      x: 70,
+      y: 0,
+      width: 50,
+      height: 50,
+      groupIds: ["other"],
+    });
+    const outerOnly = API.createElement({
+      type: "rectangle",
+      id: "outerOnly",
+      x: 140,
+      y: 0,
+      width: 50,
+      height: 50,
+      groupIds: ["outer"],
+    });
+    const other2 = API.createElement({
+      type: "rectangle",
+      id: "other2",
+      x: 210,
+      y: 0,
+      width: 50,
+      height: 50,
+      groupIds: ["other"],
+    });
+    const outerNested2 = API.createElement({
+      type: "rectangle",
+      id: "outerNested2",
+      x: 280,
+      y: 0,
+      width: 50,
+      height: 50,
+      groupIds: ["inner", "outer"],
+    });
+    const selection = API.createElement({
+      type: "rectangle",
+      x: 295,
+      y: -10,
+      width: 10,
+      height: 70,
+    });
+    const elements = [outerNested1, other1, outerOnly, other2, outerNested2];
+
+    expect(
+      getElementsWithinSelection(
+        elements,
+        selection,
+        arrayToMap([...elements, selection]),
+        false,
+        "overlap",
+      ).map((element) => element.id),
+    ).toEqual([outerNested1.id, outerOnly.id, outerNested2.id]);
+  });
+
   it("should not select a transparent rectangle when the selection box stays inside it", () => {
     const rect1 = API.createElement({
       type: "rectangle",
@@ -615,6 +758,32 @@ describe("box-selection overlap mode", () => {
 
     assertSelectedElements([]);
   });
+
+  it("should not select a framed element when selection only overlaps its clipped-out outline", () => {
+    const frame = API.createElement({
+      type: "frame",
+      x: 100,
+      y: 100,
+      width: 100,
+      height: 100,
+    });
+    const rect1 = API.createElement({
+      type: "rectangle",
+      x: 50,
+      y: 50,
+      width: 200,
+      height: 200,
+      frameId: frame.id,
+      backgroundColor: "red",
+      fillStyle: "solid",
+    });
+
+    API.setElements([frame, rect1]);
+
+    boxSelect(40, 170, 70, 220);
+
+    assertSelectedElements([]);
+  });
 });
 
 describe("inner box-selection", () => {
@@ -690,11 +859,175 @@ describe("inner box-selection", () => {
       mouse.moveTo(rect2.x + rect2.width + 10, rect2.y + rect2.height + 10);
       mouse.up();
 
+      assertSelectedElements([rect1.id]);
+      expect(h.state.selectedGroupIds).toEqual({});
+    });
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      mouse.downAt(40, 40);
+      mouse.move(-1000, -1000);
+      mouse.moveTo(rect3.x + rect3.width + 10, rect3.y + rect3.height + 10);
+      mouse.up();
+
       assertSelectedElements([rect2.id, rect3.id]);
       expect(h.state.selectedGroupIds).toEqual({ A: true });
     });
   });
 
+  it("does not select a nested outer group until all members are contained", async () => {
+    const innerRect1 = API.createElement({
+      type: "rectangle",
+      x: 50,
+      y: 50,
+      width: 50,
+      height: 50,
+      groupIds: ["inner", "outer"],
+    });
+    const innerRect2 = API.createElement({
+      type: "rectangle",
+      x: 120,
+      y: 50,
+      width: 50,
+      height: 50,
+      groupIds: ["inner", "outer"],
+    });
+    const outerRect = API.createElement({
+      type: "rectangle",
+      x: 190,
+      y: 50,
+      width: 50,
+      height: 50,
+      groupIds: ["outer"],
+    });
+    API.setElements([innerRect1, innerRect2, outerRect]);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      mouse.downAt(0, 0);
+      mouse.move(-1000, -1000);
+      mouse.moveTo(
+        innerRect2.x + innerRect2.width + 10,
+        innerRect2.y + innerRect2.height + 10,
+      );
+      mouse.up();
+
+      assertSelectedElements([]);
+      expect(h.state.selectedGroupIds).toEqual({});
+    });
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      mouse.downAt(0, 0);
+      mouse.move(-1000, -1000);
+      mouse.moveTo(
+        outerRect.x + outerRect.width + 10,
+        outerRect.y + outerRect.height + 10,
+      );
+      mouse.up();
+
+      assertSelectedElements([innerRect1.id, innerRect2.id, outerRect.id]);
+      expect(h.state.selectedGroupIds).toEqual({ outer: true });
+    });
+  });
+
+  it.skip("checks nested containment against the current editing depth", async () => {
+    const innerRect1 = API.createElement({
+      type: "rectangle",
+      x: 50,
+      y: 50,
+      width: 50,
+      height: 50,
+      groupIds: ["inner", "outer"],
+    });
+    const innerRect2 = API.createElement({
+      type: "rectangle",
+      x: 120,
+      y: 50,
+      width: 50,
+      height: 50,
+      groupIds: ["inner", "outer"],
+    });
+    const outerRect = API.createElement({
+      type: "rectangle",
+      x: 190,
+      y: 50,
+      width: 50,
+      height: 50,
+      groupIds: ["outer"],
+    });
+    const selection = API.createElement({
+      type: "rectangle",
+      x: 40,
+      y: 40,
+      width: 140,
+      height: 70,
+    });
+    const elements = [innerRect1, innerRect2, outerRect];
+    const elementsMap = arrayToMap([...elements, selection]);
+
+    expect(
+      getElementsWithinSelection(
+        elements,
+        selection,
+        elementsMap,
+        false,
+        "contain",
+      ).map((element) => element.id),
+    ).toEqual([]);
+
+    expect(
+      getElementsWithinSelection(
+        elements,
+        selection,
+        elementsMap,
+        false,
+        "contain",
+        // "outer", /* editingGroupId - add as param once we implement nested group handling */
+      ).map((element) => element.id),
+    ).toEqual([innerRect1.id, innerRect2.id]);
+  });
+
+  it("ignores grouped bound text when checking box-selection containment", async () => {
+    const container = API.createElement({
+      type: "rectangle",
+      id: "container",
+      x: 50,
+      y: 50,
+      width: 50,
+      height: 50,
+      groupIds: ["A"],
+      boundElements: [{ type: "text", id: "bound-text" }],
+    });
+    const boundText = API.createElement({
+      type: "text",
+      id: "bound-text",
+      x: 50,
+      y: 50,
+      width: 50,
+      height: 20,
+      containerId: container.id,
+      groupIds: ["A"],
+    });
+    const rect = API.createElement({
+      type: "rectangle",
+      x: 150,
+      y: 150,
+      width: 50,
+      height: 50,
+      groupIds: ["A"],
+    });
+    API.setElements([container, boundText, rect]);
+
+    Keyboard.withModifierKeys({ ctrl: true }, () => {
+      mouse.downAt(40, 40);
+      mouse.move(-1000, -1000);
+      mouse.moveTo(rect.x + rect.width + 10, rect.y + rect.height + 10);
+      mouse.up();
+
+      expect(h.state.selectedElementIds[container.id]).toBe(true);
+      expect(h.state.selectedElementIds[rect.id]).toBe(true);
+      expect(h.state.selectedGroupIds).toEqual({ A: true });
+    });
+  });
+
   it("selecting & deselecting grouped elements visually nested inside another", async () => {
     const rect1 = API.createElement({
       type: "rectangle",
@@ -725,7 +1058,7 @@ describe("inner box-selection", () => {
     Keyboard.withModifierKeys({ ctrl: true }, () => {
       mouse.downAt(rect2.x - 20, rect2.y - 20);
       mouse.move(-1000, -1000);
-      mouse.moveTo(rect2.x + rect2.width + 10, rect2.y + rect2.height + 10);
+      mouse.moveTo(rect3.x + rect3.width + 10, rect3.y + rect3.height + 10);
       assertSelectedElements([rect2.id, rect3.id]);
       expect(h.state.selectedGroupIds).toEqual({ A: true });
       mouse.moveTo(rect2.x - 10, rect2.y - 10);

packages/excalidraw/tests/test-utils.ts

@@ -449,28 +449,29 @@ const stripProps = (
   }, {} as Record<string, any>);
 
 export const checkpointHistory = (history: History, name: string) => {
-  const normalizeHistoryEntry = (entry: History["undoStack"][number]) => {
-    const { markers, ...rest } = entry;
-
-    return {
-      ...rest,
-      ...(markers ? { markers } : {}),
+  expect(
+    history.undoStack.map((x) => ({
+      ...x,
       elements: {
-        ...entry.elements,
-        added: stripProps(entry.elements.added, ["seed", "versionNonce"]),
-        removed: stripProps(entry.elements.removed, ["seed", "versionNonce"]),
-        updated: stripProps(entry.elements.updated, ["seed", "versionNonce"]),
+        ...x.elements,
+        added: stripProps(x.elements.added, ["seed", "versionNonce"]),
+        removed: stripProps(x.elements.removed, ["seed", "versionNonce"]),
+        updated: stripProps(x.elements.updated, ["seed", "versionNonce"]),
       },
-    };
-  };
+    })),
+  ).toMatchSnapshot(`[${name}] undo stack`);
 
-  expect(history.undoStack.map(normalizeHistoryEntry)).toMatchSnapshot(
-    `[${name}] undo stack`,
-  );
-
-  expect(history.redoStack.map(normalizeHistoryEntry)).toMatchSnapshot(
-    `[${name}] redo stack`,
-  );
+  expect(
+    history.redoStack.map((x) => ({
+      ...x,
+      elements: {
+        ...x.elements,
+        added: stripProps(x.elements.added, ["seed", "versionNonce"]),
+        removed: stripProps(x.elements.removed, ["seed", "versionNonce"]),
+        updated: stripProps(x.elements.updated, ["seed", "versionNonce"]),
+      },
+    })),
+  ).toMatchSnapshot(`[${name}] redo stack`);
 };
 
 /**

packages/excalidraw/tests/tool.test.tsx

@@ -4,10 +4,12 @@ import { resolvablePromise } from "@excalidraw/common";
 
 import { Excalidraw } from "../index";
 
+import { getToolbarTools } from "../components/shapes";
+
 import { Pointer } from "./helpers/ui";
 import { act, render } from "./test-utils";
 
-import type { ExcalidrawImperativeAPI } from "../types";
+import type { AppClassProperties, ExcalidrawImperativeAPI } from "../types";
 
 describe("setActiveTool()", () => {
   const h = window.h;
@@ -66,3 +68,27 @@ describe("setActiveTool()", () => {
     expect(h.state.activeTool.customType).toBe("comment");
   });
 });
+describe("getToolbarTools()", () => {
+  const getToolValues = (preferredSelectionTool: "selection" | "lasso") =>
+    getToolbarTools({
+      state: {
+        preferredSelectionTool: {
+          type: preferredSelectionTool,
+        },
+      },
+    } as AppClassProperties).map((tool) => tool.value);
+
+  it("does not include lasso when selection is preferred", () => {
+    const toolValues = getToolValues("selection");
+
+    expect(toolValues.filter((value) => value === "selection")).toHaveLength(1);
+    expect(toolValues.filter((value) => value === "lasso")).toHaveLength(0);
+  });
+
+  it("replaces selection with lasso when lasso is preferred", () => {
+    const toolValues = getToolValues("lasso");
+
+    expect(toolValues.filter((value) => value === "lasso")).toHaveLength(1);
+    expect(toolValues.filter((value) => value === "selection")).toHaveLength(0);
+  });
+});

packages/excalidraw/transaction/diff.ts

@@ -1,289 +0,0 @@
-import { type StoreDelta } from "@excalidraw/element";
-
-import type { Delta } from "@excalidraw/element";
-
-import type { Mutable } from "@excalidraw/common/utility-types";
-import type {
-  ExcalidrawElement,
-  OrderedExcalidrawElement,
-  SceneElementsMap,
-} from "@excalidraw/element/types";
-
-import type {
-  ElementChange,
-  ElementPropName,
-  TouchedElementProps,
-} from "./types";
-
-const LEDGER_IGNORED_PROPS = new Set([
-  "version",
-  "versionNonce",
-  "seed",
-  "updated",
-  "index",
-]);
-
-export const TX_UNDO_OVERRIDE_IGNORED_PROPS = new Set([
-  "version",
-  "versionNonce",
-  "isDeleted",
-]);
-
-type ElementRecord = Record<string, unknown>;
-export type ElementUpdatedProps = Omit<
-  Partial<OrderedExcalidrawElement>,
-  "id" | "updated" | "seed"
->;
-export type ElementUpdatedPropName = Extract<keyof ElementUpdatedProps, string>;
-type ElementPropValueMap = ElementUpdatedProps;
-
-export type ElementUpdatedEntry = Delta<ElementPropValueMap>;
-export type ElementUpdatedEntryMap = Record<string, ElementUpdatedEntry>;
-
-const isPlainObject = (value: unknown): value is Record<string, unknown> =>
-  !!value && typeof value === "object" && !Array.isArray(value);
-
-export const getElementProp = <TProp extends ElementPropName>(
-  element: ExcalidrawElement,
-  prop: TProp,
-): ExcalidrawElement[TProp] =>
-  (element as ElementRecord)[prop] as ExcalidrawElement[TProp];
-
-export const setOrderedElementProp = <TProp extends ElementPropName>(
-  element: Mutable<OrderedExcalidrawElement>,
-  prop: TProp,
-  value: OrderedExcalidrawElement[TProp],
-) => {
-  (element as ElementRecord)[prop] = value;
-};
-
-/** Deep equality used by ledger conflict/touched-prop detection. */
-export const isLedgerValueEqual = (left: unknown, right: unknown): boolean => {
-  if (Object.is(left, right)) {
-    return true;
-  }
-
-  if (Array.isArray(left) && Array.isArray(right)) {
-    if (left.length !== right.length) {
-      return false;
-    }
-    for (let index = 0; index < left.length; index += 1) {
-      if (!isLedgerValueEqual(left[index], right[index])) {
-        return false;
-      }
-    }
-    return true;
-  }
-
-  if (isPlainObject(left) && isPlainObject(right)) {
-    const leftKeys = Object.keys(left);
-    const rightKeys = Object.keys(right);
-    if (leftKeys.length !== rightKeys.length) {
-      return false;
-    }
-    for (const key of leftKeys) {
-      if (!Object.prototype.hasOwnProperty.call(right, key)) {
-        return false;
-      }
-      if (!isLedgerValueEqual(left[key], right[key])) {
-        return false;
-      }
-    }
-    return true;
-  }
-
-  return false;
-};
-
-/** Shallow-copies a scene map. Entries share references with the original. */
-export const shallowCopySceneElements = (
-  elements: ReadonlyMap<string, ExcalidrawElement>,
-): SceneElementsMap => new Map(elements) as SceneElementsMap;
-
-export const createAllTouchedElementProps = (): TouchedElementProps => ({
-  kind: "all",
-});
-
-export const createPartialTouchedElementProps = (
-  props: Iterable<ElementPropName> = [],
-): TouchedElementProps => ({
-  kind: "partial",
-  props: new Set(props),
-});
-
-export const hasTouchedProps = (touchedProps: TouchedElementProps): boolean =>
-  touchedProps.kind === "all" || touchedProps.props.size > 0;
-
-export const touchesWholeElement = (
-  touchedProps: TouchedElementProps,
-): boolean => touchedProps.kind === "all";
-
-export const isPartialTouchedProps = (
-  touchedProps: TouchedElementProps,
-): touchedProps is Extract<TouchedElementProps, { kind: "partial" }> =>
-  touchedProps.kind === "partial";
-
-export const hasTouchedProp = (
-  touchedProps: TouchedElementProps,
-  prop: ElementPropName,
-): boolean => touchedProps.kind === "all" || touchedProps.props.has(prop);
-
-export const mergeTouchedProps = (
-  left: TouchedElementProps,
-  right: TouchedElementProps,
-): TouchedElementProps => {
-  if (left.kind === "all" || right.kind === "all") {
-    return createAllTouchedElementProps();
-  }
-
-  return createPartialTouchedElementProps([...left.props, ...right.props]);
-};
-
-/** Returns changed property names between two element snapshots. */
-export const collectTouchedProps = (
-  before: ExcalidrawElement | null,
-  after: ExcalidrawElement | null,
-): TouchedElementProps => {
-  if (!before || !after) {
-    return createAllTouchedElementProps();
-  }
-
-  const touchedProps = new Set<ElementPropName>();
-  const keys = new Set<ElementPropName>([
-    ...(Object.keys(before) as ElementPropName[]),
-    ...(Object.keys(after) as ElementPropName[]),
-  ]);
-
-  for (const key of keys) {
-    if (LEDGER_IGNORED_PROPS.has(key)) {
-      continue;
-    }
-    if (
-      !isLedgerValueEqual(
-        getElementProp(before, key),
-        getElementProp(after, key),
-      )
-    ) {
-      touchedProps.add(key);
-    }
-  }
-
-  return createPartialTouchedElementProps(touchedProps);
-};
-
-/** Returns ids whose element snapshot changed between two points in time. */
-export const collectChangedElementIds = (
-  before: ReadonlyMap<string, ExcalidrawElement>,
-  after: ReadonlyMap<string, ExcalidrawElement>,
-) => collectElementChanges(before, after).map((change) => change.id);
-
-export const collectElementChanges = (
-  before: ReadonlyMap<string, ExcalidrawElement>,
-  after: ReadonlyMap<string, ExcalidrawElement>,
-): ElementChange[] => {
-  const changes: ElementChange[] = [];
-  const candidateIds = new Set<string>([...before.keys(), ...after.keys()]);
-
-  for (const id of candidateIds) {
-    const beforeElement = before.get(id) ?? null;
-    const afterElement = after.get(id) ?? null;
-    const touchedProps = collectTouchedProps(beforeElement, afterElement);
-    if (!hasTouchedProps(touchedProps)) {
-      continue;
-    }
-
-    changes.push({
-      id,
-      before: beforeElement,
-      after: afterElement,
-      touchedProps,
-    });
-  }
-
-  return changes;
-};
-
-export const serializeConsumedPropKey = (
-  elementId: string,
-  prop: ElementPropName,
-) => `${elementId}\u0000${prop}`;
-
-export const getUpdatedElementEntries = (delta: StoreDelta) =>
-  delta.elements.updated as ElementUpdatedEntryMap;
-
-export const getElementPropEntries = (props: ElementPropValueMap) =>
-  Object.entries(props) as [
-    ElementUpdatedPropName,
-    ElementUpdatedProps[ElementUpdatedPropName],
-  ][];
-
-export const hasUpdatedElementEntries = (delta: StoreDelta) =>
-  Object.keys(getUpdatedElementEntries(delta)).length > 0;
-
-export const serializeIntermediateValue = (value: unknown): string => {
-  const serialize = (input: unknown, seen: WeakSet<object>): string => {
-    if (input === null) {
-      return "null";
-    }
-
-    switch (typeof input) {
-      case "undefined":
-        return "undefined";
-      case "boolean":
-        return input ? "boolean:true" : "boolean:false";
-      case "number":
-        if (Number.isNaN(input)) {
-          return "number:NaN";
-        }
-        if (Object.is(input, -0)) {
-          return "number:-0";
-        }
-        return `number:${input}`;
-      case "bigint":
-        return `bigint:${input.toString()}`;
-      case "string":
-        return `string:${JSON.stringify(input)}`;
-      case "symbol":
-        return `symbol:${String(input)}`;
-      case "function":
-        return `function:${input.name}`;
-      case "object":
-        break;
-      default:
-        return `unknown:${String(input)}`;
-    }
-
-    if (Array.isArray(input)) {
-      if (seen.has(input)) {
-        return "[CircularArray]";
-      }
-      seen.add(input);
-      const serialized = `[${input
-        .map((item) => serialize(item, seen))
-        .join(",")}]`;
-      seen.delete(input);
-      return serialized;
-    }
-
-    if (isPlainObject(input)) {
-      if (seen.has(input)) {
-        return "{CircularObject}";
-      }
-      seen.add(input);
-      const serialized = `{${Object.keys(input)
-        .sort()
-        .map((key) => `${JSON.stringify(key)}:${serialize(input[key], seen)}`)
-        .join(",")}}`;
-      seen.delete(input);
-      return serialized;
-    }
-
-    try {
-      return `object:${JSON.stringify(input)}`;
-    } catch {
-      return `object:${Object.prototype.toString.call(input)}`;
-    }
-  };
-
-  return serialize(value, new WeakSet<object>());
-};

packages/excalidraw/transaction/index.ts

@@ -1,13 +0,0 @@
-export { collectChangedElementIds } from "./diff";
-export { TransactionLedger } from "./ledger";
-export { Transaction } from "./transaction";
-export { TransactionManager } from "./manager";
-
-export type {
-  AppStateResolver,
-  AppStateResolverContext,
-  TransactionElementUpdate,
-  TransactionLedgerEntry,
-  TransactionStatus,
-  TransactionSummary,
-} from "./types";

packages/excalidraw/transaction/ledger.ts

@@ -1,333 +0,0 @@
-import { deepCopyElement } from "@excalidraw/element";
-
-import type { Mutable } from "@excalidraw/common/utility-types";
-import type {
-  ExcalidrawElement,
-  OrderedExcalidrawElement,
-  SceneElementsMap,
-} from "@excalidraw/element/types";
-
-import {
-  collectElementChanges,
-  collectTouchedProps,
-  getElementProp,
-  hasTouchedProps,
-  isLedgerValueEqual,
-  mergeTouchedProps,
-  setOrderedElementProp,
-  shallowCopySceneElements,
-  touchesWholeElement,
-} from "./diff";
-
-import type { TransactionLedgerEntry } from "./types";
-
-/**
- * Keeps transaction-level scene mutations and materializes synthetic snapshots
- * for a single durable history commit.
- */
-export class TransactionLedger {
-  private readonly entries = new Map<string, TransactionLedgerEntry>();
-
-  /** Whether the transaction has any net element mutations. */
-  hasEntries() {
-    return this.entries.size > 0;
-  }
-
-  /** Returns the ledger entry for an element, if any. */
-  getEntry(elementId: string): TransactionLedgerEntry | undefined {
-    return this.entries.get(elementId);
-  }
-
-  /** Releases all ledger entries. */
-  clear() {
-    this.entries.clear();
-  }
-
-  /** Records one element mutation step into the ledger. */
-  recordStep(
-    before: ReadonlyMap<string, ExcalidrawElement>,
-    after: ReadonlyMap<string, ExcalidrawElement>,
-  ) {
-    for (const change of collectElementChanges(before, after)) {
-      const {
-        id: elementId,
-        before: beforeElement,
-        after: afterElement,
-        touchedProps,
-      } = change;
-
-      const existing = this.entries.get(elementId);
-      if (!existing) {
-        this.entries.set(elementId, {
-          baselineElement: beforeElement
-            ? deepCopyElement(beforeElement)
-            : null,
-          targetElement: afterElement ? deepCopyElement(afterElement) : null,
-          touchedProps,
-        });
-        continue;
-      }
-
-      existing.targetElement = afterElement
-        ? deepCopyElement(afterElement)
-        : null;
-      existing.touchedProps = mergeTouchedProps(
-        existing.touchedProps,
-        touchedProps,
-      );
-
-      // Created then deleted inside one transaction leaves no durable footprint.
-      if (!existing.baselineElement && !existing.targetElement) {
-        this.entries.delete(elementId);
-        continue;
-      }
-      if (!existing.baselineElement && existing.targetElement?.isDeleted) {
-        this.entries.delete(elementId);
-      }
-    }
-  }
-
-  /**
-   * Builds synthetic element before/after snapshots with a fixed
-   * "live-wins-per-prop" strategy.
-   */
-  buildSyntheticSnapshots(live: ReadonlyMap<string, ExcalidrawElement>) {
-    // Shallow copy — untouched elements stay as live references.
-    // Only elements mutated in-place (prop-level updates) are deep-copied below.
-    const elementsBefore = shallowCopySceneElements(live);
-    const elementsAfter = shallowCopySceneElements(live);
-
-    for (const [elementId, entry] of this.entries) {
-      this.reconcileEntrySnapshots(
-        elementId,
-        entry,
-        live,
-        elementsBefore,
-        elementsAfter,
-      );
-    }
-
-    return { elementsBefore, elementsAfter };
-  }
-
-  private reconcileEntrySnapshots(
-    elementId: string,
-    entry: TransactionLedgerEntry,
-    live: ReadonlyMap<string, ExcalidrawElement>,
-    elementsBefore: SceneElementsMap,
-    elementsAfter: SceneElementsMap,
-  ) {
-    if (!entry.baselineElement) {
-      this.applyCreatedElementSnapshots(
-        elementId,
-        entry.targetElement,
-        live,
-        elementsBefore,
-        elementsAfter,
-      );
-      return;
-    }
-
-    if (!entry.targetElement) {
-      this.applyDeletedElementSnapshots(
-        elementId,
-        entry.baselineElement,
-        live,
-        elementsBefore,
-        elementsAfter,
-      );
-      return;
-    }
-
-    this.applyUpdatedElementSnapshots(
-      elementId,
-      entry,
-      live,
-      elementsBefore,
-      elementsAfter,
-    );
-  }
-
-  private applyCreatedElementSnapshots(
-    elementId: string,
-    targetElement: ExcalidrawElement | null,
-    live: ReadonlyMap<string, ExcalidrawElement>,
-    elementsBefore: SceneElementsMap,
-    elementsAfter: SceneElementsMap,
-  ) {
-    if (!targetElement) {
-      return;
-    }
-
-    const liveElement = live.get(elementId) ?? null;
-    if (
-      !liveElement ||
-      liveElement.isDeleted ||
-      hasTouchedProps(collectTouchedProps(targetElement, liveElement))
-    ) {
-      return;
-    }
-
-    elementsBefore.delete(elementId);
-    elementsAfter.set(
-      elementId,
-      deepCopyElement(targetElement) as OrderedExcalidrawElement,
-    );
-  }
-
-  private applyDeletedElementSnapshots(
-    elementId: string,
-    baselineElement: ExcalidrawElement,
-    live: ReadonlyMap<string, ExcalidrawElement>,
-    elementsBefore: SceneElementsMap,
-    elementsAfter: SceneElementsMap,
-  ) {
-    const liveElement = live.get(elementId) ?? null;
-    if (liveElement && !liveElement.isDeleted) {
-      return;
-    }
-
-    elementsBefore.set(
-      elementId,
-      deepCopyElement(baselineElement) as OrderedExcalidrawElement,
-    );
-    elementsAfter.delete(elementId);
-  }
-
-  private applyUpdatedElementSnapshots(
-    elementId: string,
-    entry: TransactionLedgerEntry,
-    live: ReadonlyMap<string, ExcalidrawElement>,
-    elementsBefore: SceneElementsMap,
-    elementsAfter: SceneElementsMap,
-  ) {
-    const liveElement = live.get(elementId) ?? null;
-    const targetElement = entry.targetElement;
-    const baselineElement = entry.baselineElement;
-    const beforeElement = elementsBefore.get(elementId);
-    const afterElement = elementsAfter.get(elementId);
-
-    if (
-      !liveElement ||
-      !baselineElement ||
-      !targetElement ||
-      !beforeElement ||
-      !afterElement
-    ) {
-      return;
-    }
-
-    if (touchesWholeElement(entry.touchedProps)) {
-      this.applyWholeElementSnapshots(
-        elementId,
-        baselineElement,
-        targetElement,
-        liveElement,
-        elementsBefore,
-        elementsAfter,
-      );
-      return;
-    }
-
-    this.applyPerPropSnapshots({
-      entry,
-      liveElement,
-      baselineElement,
-      targetElement,
-      beforeElement,
-      afterElement,
-      elementId,
-      elementsBefore,
-      elementsAfter,
-    });
-  }
-
-  private applyWholeElementSnapshots(
-    elementId: string,
-    baselineElement: ExcalidrawElement,
-    targetElement: ExcalidrawElement,
-    liveElement: ExcalidrawElement,
-    elementsBefore: SceneElementsMap,
-    elementsAfter: SceneElementsMap,
-  ) {
-    const hasLiveConflict = hasTouchedProps(
-      collectTouchedProps(targetElement, liveElement),
-    );
-    if (hasLiveConflict) {
-      return;
-    }
-
-    elementsBefore.set(
-      elementId,
-      deepCopyElement(baselineElement) as OrderedExcalidrawElement,
-    );
-    elementsAfter.set(
-      elementId,
-      deepCopyElement(targetElement) as OrderedExcalidrawElement,
-    );
-  }
-
-  private applyPerPropSnapshots(args: {
-    entry: TransactionLedgerEntry;
-    liveElement: ExcalidrawElement;
-    baselineElement: ExcalidrawElement;
-    targetElement: ExcalidrawElement;
-    beforeElement: ExcalidrawElement;
-    afterElement: ExcalidrawElement;
-    elementId: string;
-    elementsBefore: SceneElementsMap;
-    elementsAfter: SceneElementsMap;
-  }) {
-    const {
-      entry,
-      liveElement,
-      baselineElement,
-      targetElement,
-      beforeElement,
-      afterElement,
-      elementId,
-      elementsBefore,
-      elementsAfter,
-    } = args;
-
-    // Deep-copy before mutating so we never touch live elements.
-    const mutableBefore = deepCopyElement(
-      beforeElement,
-    ) as Mutable<OrderedExcalidrawElement>;
-    const mutableAfter = deepCopyElement(
-      afterElement,
-    ) as Mutable<OrderedExcalidrawElement>;
-    elementsBefore.set(elementId, mutableBefore as OrderedExcalidrawElement);
-    elementsAfter.set(elementId, mutableAfter as OrderedExcalidrawElement);
-
-    if (entry.touchedProps.kind !== "partial") {
-      return;
-    }
-
-    let appliedProps = 0;
-    for (const prop of entry.touchedProps.props) {
-      const liveValue = getElementProp(liveElement, prop);
-      const targetValue = getElementProp(targetElement, prop);
-      if (!isLedgerValueEqual(liveValue, targetValue)) {
-        continue;
-      }
-
-      setOrderedElementProp(
-        mutableBefore,
-        prop,
-        getElementProp(baselineElement, prop),
-      );
-      setOrderedElementProp(mutableAfter, prop, targetValue);
-      appliedProps += 1;
-    }
-
-    if (appliedProps === 0) {
-      return;
-    }
-
-    mutableBefore.version = baselineElement.version;
-    mutableBefore.versionNonce = baselineElement.versionNonce;
-    mutableAfter.version = targetElement.version;
-    mutableAfter.versionNonce = targetElement.versionNonce;
-  }
-}

packages/excalidraw/transaction/manager.ts

@@ -1,291 +0,0 @@
-import {
-  Delta,
-  ElementsDelta,
-  mergeStoreDeltaMarkers,
-  type StoreDelta,
-  type TxUndoOverride,
-} from "@excalidraw/element";
-
-import type { Mutable } from "@excalidraw/common/utility-types";
-
-import {
-  HistoryDelta,
-  type HistoryBeforeRecordListener,
-  type HistoryEffectiveDeltaResolverContext,
-} from "../history";
-
-import {
-  type ElementUpdatedPropName,
-  getUpdatedElementEntries,
-  hasUpdatedElementEntries,
-  isLedgerValueEqual,
-  type ElementUpdatedProps,
-  type ElementUpdatedEntryMap,
-} from "./diff";
-import { Transaction } from "./transaction";
-
-import type { AppClassProperties } from "../types";
-import type { TransactionStatus } from "./types";
-
-type TransactionRecord = {
-  tx: Transaction | null;
-  phase: TransactionStatus;
-};
-type TransactionHistoryBridge = {
-  onBeforeRecord: (callback: HistoryBeforeRecordListener) => () => void;
-  setEffectiveDeltaResolver: (
-    resolver:
-      | ((
-          delta: HistoryDelta,
-          context: HistoryEffectiveDeltaResolverContext,
-        ) => HistoryDelta)
-      | null,
-  ) => void;
-};
-
-type MutableElementUpdatedProps = Mutable<ElementUpdatedProps>;
-
-const setElementUpdatedOverride = (
-  overrides: MutableElementUpdatedProps,
-  prop: ElementUpdatedPropName,
-  value: unknown,
-) => {
-  (overrides as Record<ElementUpdatedPropName, unknown>)[prop] = value;
-};
-
-/**
- * Thin factory that holds the app reference and creates Transaction instances.
- */
-export class TransactionManager {
-  private readonly app: AppClassProperties;
-  /**
-   * Single authoritative lifecycle registry for transactions.
-   *
-   * We retain ended/canceled metadata after the tx object is released because
-   * history markers only persist `txId`; undo/redo still needs to resolve
-   * whether a tx was active or already ended when applying effective deltas.
-   */
-  private readonly transactionRecords = new Map<string, TransactionRecord>();
-  /**
-   * Active transaction ids ordered by most-recent registration first.
-   * This preserves deterministic priority when multiple active txs overlap on
-   * the same element+prop and compete to reserve override markers.
-   */
-  private readonly activeTransactionIdsByPriority: string[] = [];
-  private detachBeforeRecordHook: (() => void) | null = null;
-
-  constructor(app: AppClassProperties) {
-    this.app = app;
-  }
-
-  /**
-   * Binds transaction bookkeeping to history lifecycle hooks.
-   * Call once during app initialization.
-   */
-  attachHistory(history: TransactionHistoryBridge) {
-    this.detachBeforeRecordHook?.();
-    history.setEffectiveDeltaResolver((delta, context) =>
-      this.resolveEffectiveDelta(delta, context),
-    );
-    this.detachBeforeRecordHook = history.onBeforeRecord((delta) =>
-      this.onDurableIncrement(delta),
-    );
-  }
-
-  private removeActiveTransactionId(txId: string) {
-    const txIndex = this.activeTransactionIdsByPriority.indexOf(txId);
-    if (txIndex >= 0) {
-      this.activeTransactionIdsByPriority.splice(txIndex, 1);
-    }
-  }
-
-  private getRequiredTransactionRecord(txId: string): TransactionRecord {
-    const record = this.transactionRecords.get(txId);
-    if (!record) {
-      throw new Error(`Unknown transaction: ${txId}`);
-    }
-
-    return record;
-  }
-
-  registerTransaction(tx: Transaction) {
-    this.transactionRecords.set(tx.id, {
-      tx,
-      phase: "active",
-    });
-    this.activeTransactionIdsByPriority.unshift(tx.id);
-  }
-
-  detachTransactionInstance(txId: string) {
-    const record = this.getRequiredTransactionRecord(txId);
-    record.tx = null;
-    this.removeActiveTransactionId(txId);
-  }
-
-  getStatus(txId: string): TransactionStatus {
-    return this.getRequiredTransactionRecord(txId).phase;
-  }
-
-  private markTransactionFinished(
-    txId: string,
-    phase: Exclude<TransactionStatus, "active">,
-  ): TransactionStatus {
-    const record = this.getRequiredTransactionRecord(txId);
-    if (record.phase !== "active") {
-      return record.phase;
-    }
-
-    record.phase = phase;
-    this.removeActiveTransactionId(txId);
-    return record.phase;
-  }
-
-  markTransactionCommitted(txId: string): TransactionStatus {
-    return this.markTransactionFinished(txId, "committed");
-  }
-
-  markTransactionCanceled(txId: string): TransactionStatus {
-    return this.markTransactionFinished(txId, "canceled");
-  }
-
-  onDurableIncrement(delta: StoreDelta) {
-    if (this.activeTransactionIdsByPriority.length === 0) {
-      return;
-    }
-    if (!hasUpdatedElementEntries(delta)) {
-      return;
-    }
-
-    const txUndoOverrides = this.collectUndoOverrides(delta);
-    if (txUndoOverrides.length === 0) {
-      return;
-    }
-
-    mergeStoreDeltaMarkers(delta, { txUndoOverrides });
-  }
-
-  private collectUndoOverrides(delta: StoreDelta): TxUndoOverride[] {
-    const overrides: TxUndoOverride[] = [];
-    const reservedConsumedKeys = new Set<string>();
-
-    for (const txId of this.activeTransactionIdsByPriority) {
-      const record = this.transactionRecords.get(txId);
-      if (!record || record.phase !== "active" || !record.tx) {
-        continue;
-      }
-
-      const txOverrides = record.tx.collectUndoOverridesForDelta(
-        delta,
-        reservedConsumedKeys,
-      );
-
-      for (const override of txOverrides) {
-        if (reservedConsumedKeys.has(override.consumedKey)) {
-          continue;
-        }
-
-        reservedConsumedKeys.add(override.consumedKey);
-        overrides.push(override);
-      }
-    }
-
-    return overrides;
-  }
-
-  private resolveEffectiveDelta(
-    delta: HistoryDelta,
-    _context: HistoryEffectiveDeltaResolverContext,
-  ): HistoryDelta {
-    const txUndoOverrides = delta.markers?.txUndoOverrides;
-    if (!txUndoOverrides || txUndoOverrides.length === 0) {
-      return delta;
-    }
-
-    const updatedEntries = getUpdatedElementEntries(delta);
-    const insertedOverridesByElement = new Map<
-      string,
-      MutableElementUpdatedProps
-    >();
-
-    for (const override of txUndoOverrides) {
-      if (!this.shouldApplyUndoOverride(override.txId)) {
-        continue;
-      }
-
-      const currentEntry = updatedEntries[override.elementId];
-      if (!currentEntry) {
-        continue;
-      }
-
-      const prop = override.prop as ElementUpdatedPropName;
-      const currentInsertedValue = currentEntry.inserted[prop];
-      if (
-        !isLedgerValueEqual(
-          currentInsertedValue,
-          override.expectedInsertedValue,
-        )
-      ) {
-        // Guard against over-applying once the delta has already evolved.
-        continue;
-      }
-
-      const elementOverrides = insertedOverridesByElement.get(
-        override.elementId,
-      );
-      if (elementOverrides) {
-        setElementUpdatedOverride(
-          elementOverrides,
-          prop,
-          override.preTxBaselineValue,
-        );
-      } else {
-        const nextOverrides: MutableElementUpdatedProps = {};
-        setElementUpdatedOverride(
-          nextOverrides,
-          prop,
-          override.preTxBaselineValue,
-        );
-        insertedOverridesByElement.set(override.elementId, nextOverrides);
-      }
-    }
-
-    if (insertedOverridesByElement.size === 0) {
-      return delta;
-    }
-
-    const nextUpdatedEntries: ElementUpdatedEntryMap = {
-      ...updatedEntries,
-    };
-    for (const [elementId, insertedOverrides] of insertedOverridesByElement) {
-      const currentEntry = updatedEntries[elementId];
-      if (!currentEntry) {
-        continue;
-      }
-
-      nextUpdatedEntries[elementId] = Delta.create(
-        { ...currentEntry.deleted },
-        { ...currentEntry.inserted, ...insertedOverrides },
-      );
-    }
-
-    const effectiveElements = ElementsDelta.create(
-      delta.elements.added,
-      delta.elements.removed,
-      nextUpdatedEntries,
-    );
-
-    return HistoryDelta.create(effectiveElements, delta.appState, {
-      id: delta.id,
-      markers: delta.markers,
-    }) as HistoryDelta;
-  }
-
-  private shouldApplyUndoOverride(txId: string): boolean {
-    const record = this.transactionRecords.get(txId);
-    return !!record && record.phase !== "active";
-  }
-
-  create(): Transaction {
-    return new Transaction(this.app, this);
-  }
-}

packages/excalidraw/transaction/transaction.ts

@@ -1,286 +0,0 @@
-import { randomId } from "@excalidraw/common";
-import {
-  CaptureUpdateAction,
-  newElementWith,
-  type ElementUpdate,
-  type StoreDelta,
-  type TxUndoOverride,
-} from "@excalidraw/element";
-
-import { shallowCopySceneElements } from "./diff";
-import { TransactionLedger } from "./ledger";
-
-import {
-  type AppStateResolver,
-  type AppStateResolverContext,
-  type TransactionElementOfType,
-  type TransactionElementUpdate,
-  type TransactionStatus,
-  type TransactionSummary,
-} from "./types";
-import { TxUndoOverridePlanner } from "./undoOverridePlanner";
-
-import type { TransactionManager } from "./manager";
-import type {
-  AppClassProperties,
-  AppState,
-  ObservedAppState,
-  SceneData,
-} from "../types";
-
-type CommitOptions = {
-  resolveAppState?: AppStateResolver;
-};
-
-/**
- * A transaction that records mutations via `updateScene(NEVER)` and commits
- * a single synthetic durable history entry at the end.
- */
-export class Transaction {
-  public readonly id = `tx-${randomId()}`;
-
-  private readonly app: AppClassProperties;
-  private readonly manager: TransactionManager;
-  private readonly ledger = new TransactionLedger();
-  private readonly undoOverridePlanner = new TxUndoOverridePlanner();
-  private readonly initialAppState: Partial<ObservedAppState>;
-
-  private accumulatedAppState: Record<string, unknown> = {};
-  private cachedSummary: TransactionSummary | null = null;
-
-  constructor(app: AppClassProperties, manager: TransactionManager) {
-    this.app = app;
-    this.manager = manager;
-    this.initialAppState = { ...app.store.snapshot.appState };
-    this.manager.registerTransaction(this);
-  }
-
-  get status(): TransactionStatus {
-    return this.manager.getStatus(this.id);
-  }
-
-  private assertActive(action: string): void {
-    const status = this.status;
-    if (status !== "active") {
-      throw new Error(
-        `Cannot ${action} — transaction ${this.id} is already ${status}.`,
-      );
-    }
-  }
-
-  private closeTransaction() {
-    this.manager.detachTransactionInstance(this.id);
-    this.undoOverridePlanner.clear();
-  }
-
-  public collectUndoOverridesForDelta(
-    delta: StoreDelta,
-    reservedConsumedKeys: Set<string>,
-  ): TxUndoOverride[] {
-    if (this.status !== "active") {
-      return [];
-    }
-
-    const candidates =
-      this.undoOverridePlanner.collectCandidatesForDurableDelta(
-        delta,
-        (elementId) => this.ledger.getEntry(elementId),
-        reservedConsumedKeys,
-      );
-
-    if (candidates.length === 0) {
-      return [];
-    }
-
-    const overrides: TxUndoOverride[] = [];
-    for (const candidate of candidates) {
-      this.undoOverridePlanner.markConsumed(candidate.consumedKey);
-      overrides.push({
-        txId: this.id,
-        ...candidate,
-      });
-    }
-
-    return overrides;
-  }
-
-  updateScene<K extends keyof AppState>(data: {
-    elements?: SceneData["elements"];
-    appState?: Pick<AppState, K> | null;
-  }): void {
-    this.assertActive("updateScene");
-
-    // Snapshot before (shallow copy — replaceAllElements mutates the map in-place)
-    const before = shallowCopySceneElements(
-      this.app.scene.getElementsMapIncludingDeleted(),
-    );
-
-    // Apply through the real updateScene with NEVER.
-    this.app.api.updateScene({
-      elements: data.elements,
-      appState: data.appState,
-      captureUpdate: CaptureUpdateAction.NEVER,
-    });
-
-    // Snapshot after
-    const after = this.app.scene.getElementsMapIncludingDeleted();
-
-    this.undoOverridePlanner.recordStep(before, after);
-
-    // Record element diff into ledger
-    this.ledger.recordStep(before, after);
-
-    // Accumulate appState intent
-    if (data.appState) {
-      this.accumulatedAppState = {
-        ...this.accumulatedAppState,
-        ...(data.appState as Record<string, unknown>),
-      };
-    }
-  }
-
-  /**
-   * Partial element updates convenience API.
-   *
-   * Example:
-   * tx.updateElements({
-   *   elements: [
-   *     { id: "a", type: "rectangle", updates: { strokeColor: "#f00" } },
-   *     { id: "b", type: "rectangle", updates: { x: 10, y: 20 } },
-   *   ],
-   * })
-   */
-  updateElements<K extends keyof AppState>(data: {
-    elements: readonly TransactionElementUpdate[];
-    appState?: Pick<AppState, K> | null;
-  }): void {
-    const updatesById = new Map<string, TransactionElementUpdate>();
-
-    for (const update of data.elements) {
-      updatesById.set(update.id, update);
-    }
-
-    if (updatesById.size === 0) {
-      this.updateScene({ appState: data.appState });
-      return;
-    }
-
-    const nextElements = this.app.scene
-      .getElementsIncludingDeleted()
-      .map((element) => {
-        const update = updatesById.get(element.id);
-        if (!update) {
-          return element;
-        }
-        if (element.type !== update.type) {
-          throw new Error(
-            `Cannot apply tx.updateElements update for "${update.id}": expected "${update.type}", got "${element.type}".`,
-          );
-        }
-
-        type MatchingElement = TransactionElementOfType<typeof update.type>;
-        return newElementWith(
-          element as MatchingElement,
-          update.updates as ElementUpdate<MatchingElement>,
-        );
-      });
-
-    this.updateScene({
-      elements: nextElements,
-      appState: data.appState,
-    });
-  }
-
-  commit(options?: CommitOptions): TransactionSummary {
-    if (this.cachedSummary) {
-      return this.cachedSummary;
-    }
-
-    this.manager.markTransactionCommitted(this.id);
-    let historyCommitted = false;
-    try {
-      historyCommitted = this.hasPendingWork()
-        ? this.commitHistoryEntry(options)
-        : false;
-    } finally {
-      this.closeTransaction();
-    }
-
-    const status = this.status;
-    this.cachedSummary = {
-      id: this.id,
-      status,
-      historyCommitted,
-    };
-    this.ledger.clear();
-    return this.cachedSummary;
-  }
-
-  private hasPendingWork() {
-    return this.ledger.hasEntries() || this.hasAccumulatedAppStateIntent();
-  }
-
-  private hasAccumulatedAppStateIntent() {
-    return Object.keys(this.accumulatedAppState).length > 0;
-  }
-
-  private commitHistoryEntry(options?: CommitOptions) {
-    const liveMap = this.app.scene.getElementsMapIncludingDeleted();
-    const { elementsBefore, elementsAfter } =
-      this.ledger.buildSyntheticSnapshots(liveMap);
-
-    const appStateDelta = this.resolveCommitAppStateDelta(options);
-
-    return this.app.store.commitSyntheticIncrement({
-      logicalBefore: { elements: elementsBefore },
-      logicalAfter: {
-        elements: elementsAfter,
-        appState: appStateDelta,
-      },
-    });
-  }
-
-  private resolveCommitAppStateDelta(
-    options?: CommitOptions,
-  ): Partial<ObservedAppState> | undefined {
-    if (!this.hasAccumulatedAppStateIntent()) {
-      return undefined;
-    }
-
-    if (!options?.resolveAppState) {
-      return this.accumulatedAppState as Partial<ObservedAppState>;
-    }
-
-    const context: AppStateResolverContext = {
-      initial: this.initialAppState,
-      accumulated: this.accumulatedAppState as Partial<ObservedAppState>,
-      live: { ...this.app.store.snapshot.appState },
-    };
-    const resolved = options.resolveAppState(context);
-
-    if (!resolved || Object.keys(resolved).length === 0) {
-      return undefined;
-    }
-    return resolved;
-  }
-
-  cancel(): TransactionSummary {
-    if (this.cachedSummary) {
-      return this.cachedSummary;
-    }
-
-    if (this.status === "active") {
-      this.manager.markTransactionCanceled(this.id);
-    }
-
-    this.closeTransaction();
-    const status = this.status;
-    this.cachedSummary = {
-      id: this.id,
-      status,
-      historyCommitted: false,
-    };
-    this.ledger.clear();
-    return this.cachedSummary;
-  }
-}

packages/excalidraw/transaction/types.ts

@@ -1,83 +0,0 @@
-import type { ElementUpdate } from "@excalidraw/element";
-
-import type {
-  ExcalidrawElement,
-  ExcalidrawNonSelectionElement,
-} from "@excalidraw/element/types";
-
-import type { ObservedAppState } from "../types";
-
-export type ElementPropName = Extract<keyof ExcalidrawElement, string>;
-
-export type TouchedElementProps =
-  | { kind: "all" }
-  | { kind: "partial"; props: Set<ElementPropName> };
-
-export type ElementChange = {
-  id: ExcalidrawElement["id"];
-  before: ExcalidrawElement | null;
-  after: ExcalidrawElement | null;
-  touchedProps: TouchedElementProps;
-};
-
-/** Per-element ledger record captured during a transaction session. */
-export type TransactionLedgerEntry = {
-  baselineElement: ExcalidrawElement | null;
-  targetElement: ExcalidrawElement | null;
-  touchedProps: TouchedElementProps;
-};
-
-/** Lifecycle state of a transaction. */
-export type TransactionStatus = "active" | "committed" | "canceled";
-
-/** Per-element partial patch used by tx.updateElements(). */
-export type TransactionUpdatableElementType =
-  ExcalidrawNonSelectionElement["type"];
-
-export type TransactionElementOfType<
-  TType extends TransactionUpdatableElementType,
-> = Extract<ExcalidrawNonSelectionElement, { type: TType }>;
-
-export type TransactionElementUpdate<
-  TType extends TransactionUpdatableElementType = TransactionUpdatableElementType,
-> = TType extends TransactionUpdatableElementType
-  ? {
-      id: ExcalidrawElement["id"];
-      type: TType;
-      updates: ElementUpdate<TransactionElementOfType<TType>>;
-    }
-  : never;
-
-/** Final summary returned when a transaction is committed or canceled. */
-export type TransactionSummary = {
-  id: string;
-  status: TransactionStatus;
-  historyCommitted: boolean;
-};
-
-/** Three-way appState context provided to the resolver at commit time. */
-export type AppStateResolverContext = {
-  /** AppState snapshot captured when the transaction was created. */
-  initial: Partial<ObservedAppState>;
-  /** Merged appState intent from all updateScene calls during the transaction. */
-  accumulated: Partial<ObservedAppState>;
-  /** Current live appState at commit time. */
-  live: Partial<ObservedAppState>;
-};
-
-/**
- * Caller-provided resolver that determines which appState changes are
- * recorded in the history entry.
- *
- * Unlike elements — where per-property conflict detection works because
- * element properties are largely independent — appState keys are often
- * interdependent (e.g. selectedElementIds ↔ selectedGroupIds must stay
- * consistent). The correct merge strategy therefore depends on the
- * caller's semantic context, not on a generic policy.
- *
- * Return the appState delta to record in history, or undefined to skip
- * appState changes entirely.
- */
-export type AppStateResolver = (
-  context: AppStateResolverContext,
-) => Partial<ObservedAppState> | undefined;

packages/excalidraw/transaction/undoOverridePlanner.ts

@@ -1,283 +0,0 @@
-import type { StoreDelta, TxUndoOverride } from "@excalidraw/element";
-
-import type { ExcalidrawElement } from "@excalidraw/element/types";
-
-import {
-  TX_UNDO_OVERRIDE_IGNORED_PROPS,
-  collectElementChanges,
-  getElementProp,
-  getElementPropEntries,
-  getUpdatedElementEntries,
-  hasTouchedProp,
-  isPartialTouchedProps,
-  isLedgerValueEqual,
-  serializeConsumedPropKey,
-  serializeIntermediateValue,
-  touchesWholeElement,
-  type ElementUpdatedEntry,
-} from "./diff";
-
-import type {
-  ElementPropName,
-  TouchedElementProps,
-  TransactionLedgerEntry,
-} from "./types";
-
-type TxUndoOverrideCandidate = Omit<TxUndoOverride, "txId">;
-
-/**
- * Per-element-prop history of tx intermediate values.
- *
- * We keep:
- * - the full sequence for exact deep-equality fallback
- * - a serialized signature set for fast negative lookups
- * - the latest value for the most common positive lookup path
- */
-class TxIntermediateValueHistory {
-  private readonly values: unknown[] = [];
-  private readonly signatures = new Set<string>();
-  private latestValue: unknown;
-  private hasLatestValue = false;
-
-  /** Appends a new intermediate value, skipping consecutive duplicates. */
-  add(value: unknown) {
-    if (this.hasLatestValue && isLedgerValueEqual(this.latestValue, value)) {
-      return;
-    }
-
-    this.values.push(value);
-    this.signatures.add(serializeIntermediateValue(value));
-    this.latestValue = value;
-    this.hasLatestValue = true;
-  }
-
-  /** Returns whether the candidate appeared in this tx prop history. */
-  contains(candidate: unknown) {
-    const candidateSignature = serializeIntermediateValue(candidate);
-    if (!this.signatures.has(candidateSignature)) {
-      return false;
-    }
-
-    if (
-      this.hasLatestValue &&
-      isLedgerValueEqual(this.latestValue, candidate)
-    ) {
-      return true;
-    }
-
-    return this.values.some((value) => isLedgerValueEqual(value, candidate));
-  }
-}
-
-/**
- * Tracks tx intermediate values and computes undo baseline override markers
- * for durable user deltas recorded while tx is active.
- *
- * High-level flow:
- * 1. `recordStep()` observes every in-tx scene mutation and records the
- *    intermediate value reached by each touched element prop.
- * 2. When a durable user delta is about to be recorded,
- *    `collectCandidatesForDurableDelta()` checks whether that delta's
- *    deleted-baseline values match any tx intermediate value.
- * 3. If they do, we emit override candidates so undo can restore the pre-tx
- *    baseline once the tx has ended.
- * 4. `markConsumed()` ensures only the first polluted durable entry for a
- *    given element+prop gets patched; later user actions keep their own
- *    action-local undo baseline.
- */
-export class TxUndoOverridePlanner {
-  private readonly intermediateValuesByElementProp = new Map<
-    string,
-    Map<ElementPropName, TxIntermediateValueHistory>
-  >();
-  private readonly consumedOverridePropKeys = new Set<string>();
-
-  /** Resets planner state when the transaction finishes. */
-  clear() {
-    this.consumedOverridePropKeys.clear();
-    this.intermediateValuesByElementProp.clear();
-  }
-
-  /** Records per-prop intermediate values reached by one in-tx scene step. */
-  recordStep(
-    before: ReadonlyMap<string, ExcalidrawElement>,
-    after: ReadonlyMap<string, ExcalidrawElement>,
-  ) {
-    for (const change of collectElementChanges(before, after)) {
-      const { id: elementId, after: afterElement, touchedProps } = change;
-
-      if (!afterElement || !isPartialTouchedProps(touchedProps)) {
-        continue;
-      }
-
-      for (const prop of touchedProps.props) {
-        this.recordIntermediateValue(
-          elementId,
-          prop,
-          getElementProp(afterElement, prop),
-        );
-      }
-    }
-  }
-
-  /**
-   * Collects override candidates for one durable user delta recorded while the
-   * tx is active.
-   */
-  collectCandidatesForDurableDelta(
-    delta: StoreDelta,
-    getLedgerEntry: (elementId: string) => TransactionLedgerEntry | undefined,
-    reservedConsumedKeys: Set<string>,
-  ): TxUndoOverrideCandidate[] {
-    const candidates: TxUndoOverrideCandidate[] = [];
-
-    for (const [elementId, deltaEntry] of Object.entries(
-      getUpdatedElementEntries(delta),
-    )) {
-      const ledgerEntry = getLedgerEntry(elementId);
-      if (!ledgerEntry) {
-        continue;
-      }
-
-      const elementCandidates = this.collectCandidatesForElement(
-        elementId,
-        deltaEntry,
-        ledgerEntry,
-        reservedConsumedKeys,
-      );
-      if (elementCandidates.length > 0) {
-        candidates.push(...elementCandidates);
-      }
-    }
-
-    return candidates;
-  }
-
-  /** Evaluates one element's updated entry against the tx ledger snapshot. */
-  private collectCandidatesForElement(
-    elementId: string,
-    deltaEntry: ElementUpdatedEntry,
-    ledgerEntry: TransactionLedgerEntry,
-    reservedConsumedKeys: Set<string>,
-  ): TxUndoOverrideCandidate[] {
-    const { baselineElement, touchedProps } = ledgerEntry;
-    if (!baselineElement || touchesWholeElement(touchedProps)) {
-      return [];
-    }
-
-    const candidates: TxUndoOverrideCandidate[] = [];
-    for (const [prop, deletedValue] of getElementPropEntries(
-      deltaEntry.deleted,
-    )) {
-      const candidate = this.createCandidateForProp({
-        elementId,
-        prop,
-        deletedValue,
-        baselineElement,
-        touchedProps,
-        reservedConsumedKeys,
-      });
-      if (candidate) {
-        candidates.push(candidate);
-      }
-    }
-
-    return candidates;
-  }
-
-  /**
-   * Returns an override candidate for one element+prop when the durable delta's
-   * deleted baseline was polluted by a tx intermediate value.
-   */
-  private createCandidateForProp(args: {
-    elementId: string;
-    prop: ElementPropName;
-    deletedValue: unknown;
-    baselineElement: ExcalidrawElement;
-    touchedProps: TouchedElementProps;
-    reservedConsumedKeys: Set<string>;
-  }): TxUndoOverrideCandidate | null {
-    const { elementId, prop, deletedValue, baselineElement, touchedProps } =
-      args;
-
-    if (
-      TX_UNDO_OVERRIDE_IGNORED_PROPS.has(prop) ||
-      !hasTouchedProp(touchedProps, prop)
-    ) {
-      return null;
-    }
-
-    const consumedPropKey = serializeConsumedPropKey(elementId, prop);
-    // Override only the first polluted user entry for this element+prop.
-    // Later user actions should keep action-local undo baselines.
-    if (
-      this.consumedOverridePropKeys.has(consumedPropKey) ||
-      args.reservedConsumedKeys.has(consumedPropKey)
-    ) {
-      return null;
-    }
-
-    if (!this.matchesIntermediateValue(elementId, prop, deletedValue)) {
-      return null;
-    }
-
-    return {
-      elementId,
-      prop,
-      expectedInsertedValue: deletedValue,
-      preTxBaselineValue: getElementProp(baselineElement, prop),
-      consumedKey: consumedPropKey,
-    };
-  }
-
-  /** Marks an element+prop override as consumed by an earlier durable entry. */
-  markConsumed(consumedPropKey: string) {
-    this.consumedOverridePropKeys.add(consumedPropKey);
-  }
-
-  /** Returns the per-prop history map for one element, creating it if needed. */
-  private getOrCreatePropValues(elementId: string) {
-    const existing = this.intermediateValuesByElementProp.get(elementId);
-    if (existing) {
-      return existing;
-    }
-
-    const created = new Map<ElementPropName, TxIntermediateValueHistory>();
-    this.intermediateValuesByElementProp.set(elementId, created);
-    return created;
-  }
-
-  /** Appends one observed intermediate value for an element prop. */
-  private recordIntermediateValue(
-    elementId: string,
-    prop: ElementPropName,
-    value: unknown,
-  ) {
-    const propValues = this.getOrCreatePropValues(elementId);
-    const history = propValues.get(prop);
-    if (history) {
-      history.add(value);
-      return;
-    }
-
-    const nextHistory = new TxIntermediateValueHistory();
-    nextHistory.add(value);
-    propValues.set(prop, nextHistory);
-  }
-
-  /** Checks whether a durable delta baseline matches any tx intermediate value. */
-  private matchesIntermediateValue(
-    elementId: string,
-    prop: ElementPropName,
-    candidate: unknown,
-  ) {
-    const history = this.intermediateValuesByElementProp
-      .get(elementId)
-      ?.get(prop);
-    if (!history) {
-      return false;
-    }
-
-    return history.contains(candidate);
-  }
-}

packages/excalidraw/types.ts

@@ -224,6 +224,7 @@ export type InteractiveCanvasAppState = Readonly<
     newElement: AppState["newElement"];
     isBindingEnabled: AppState["isBindingEnabled"];
     isMidpointSnappingEnabled: AppState["isMidpointSnappingEnabled"];
+    gridModeEnabled: AppState["gridModeEnabled"];
     suggestedBinding: AppState["suggestedBinding"];
     isRotating: AppState["isRotating"];
     elementsToHighlight: AppState["elementsToHighlight"];
@@ -315,7 +316,10 @@ export interface AppState {
   bindingPreference: "enabled" | "disabled";
   /** user preference whether arrow snap to midpoints while binding */
   isMidpointSnappingEnabled: boolean;
-  startBoundElement: NonDeleted<ExcalidrawBindableElement> | null;
+  /**
+   * The bindable element the UI highlights for the user when an arrow is
+   * dragged or otherwise its endpoint being close to said element.
+   */
   suggestedBinding: {
     element: NonDeleted<ExcalidrawBindableElement>;
     midPoint?: GlobalPoint;
@@ -347,8 +351,11 @@ export interface AppState {
     type: "selection" | "lasso";
     initialized: boolean;
   };
+
+  // Pen handling
   penMode: boolean;
   penDetected: boolean;
+
   exportBackground: boolean;
   exportEmbedScene: boolean;
   exportWithDarkMode: boolean;
@@ -472,6 +479,9 @@ export interface AppState {
   // as elements are unlocked, we remove the groupId from the elements
   // and also remove groupId from this map
   lockedMultiSelections: { [groupId: string]: true };
+  // Stores the current bind mode which is detemined at various points during
+  // a drag operation (like pointer position vs bindable element) but needed
+  // globally for calculating the binding strategy
   bindMode: BindMode;
 }
 
@@ -487,10 +497,7 @@ export type SearchMatch = {
   }[];
 };
 
-export type UIAppState = Omit<
-  AppState,
-  "startBoundElement" | "cursorButton" | "scrollX" | "scrollY"
->;
+export type UIAppState = Omit<AppState, "cursorButton" | "scrollX" | "scrollY">;
 
 export type NormalizedZoomValue = number & { _brand: "normalizedZoom" };
 
@@ -639,6 +646,10 @@ export interface ExcalidrawProps {
     appState: UIAppState,
   ) => JSX.Element;
   UIOptions?: Partial<UIOptions>;
+  /**
+   * dimensions and size constraints for inserted images
+   */
+  imageOptions?: ImageOptions;
   detectScroll?: boolean;
   handleKeyboardGlobally?: boolean;
   onLibraryChange?: (libraryItems: LibraryItems) => void | Promise<any>;
@@ -725,6 +736,11 @@ export type ExportOpts = {
   ) => JSX.Element;
 };
 
+export type ImageOptions = Partial<{
+  maxWidthOrHeight: number;
+  maxFileSizeBytes: number;
+}>;
+
 // NOTE at the moment, if action name corresponds to canvasAction prop, its
 // truthiness value will determine whether the action is rendered or not
 // (see manager renderAction). We also override canvasAction values in
@@ -766,6 +782,7 @@ export type AppProps = Merge<
         canvasActions: Required<CanvasActions> & { export: ExportOpts };
       }
     >;
+    imageOptions: Required<ImageOptions>;
     detectScroll: boolean;
     handleKeyboardGlobally: boolean;
     isCollaborating: boolean;
@@ -796,9 +813,6 @@ export type AppClassProperties = {
   files: BinaryFiles;
   editorInterface: App["editorInterface"];
   scene: App["scene"];
-  store: App["store"];
-  transactionManager: App["transactionManager"];
-  createTransaction: App["createTransaction"];
   syncActionResult: App["syncActionResult"];
   fonts: App["fonts"];
   pasteFromClipboard: App["pasteFromClipboard"];
@@ -832,6 +846,7 @@ export type AppClassProperties = {
   onStateChange: App["onStateChange"];
 
   lastPointerMoveCoords: App["lastPointerMoveCoords"];
+  lastPointerMoveEvent: App["lastPointerMoveEvent"];
   bindModeHandler: App["bindModeHandler"];
 
   setAppState: App["setAppState"];
@@ -873,8 +888,13 @@ export type PointerDownState = Readonly<{
     // Whether selected element(s) were duplicated, might change during the
     // pointer interaction
     hasBeenDuplicated: boolean;
+    // Whether the pointer is hitting the common bounding box of selected
+    // elements, which is useful for discriminating between selecitng
+    // the entire selection vs a specific element
     hasHitCommonBoundingBoxOfSelectedElements: boolean;
   };
+  // This is determined on the initial pointer down event to
+  // set various interaction modalities
   withCmdOrCtrl: boolean;
   drag: {
     // Might change during the pointer interaction
@@ -900,6 +920,7 @@ export type PointerDownState = Readonly<{
     onKeyUp: null | ((event: KeyboardEvent) => void);
   };
   boxSelection: {
+    // If the box selection tool is activated on pointer down
     hasOccurred: boolean;
   };
 }>;

packages/excalidraw/wysiwyg/textWysiwyg.test.tsx

@@ -769,6 +769,63 @@ describe("textWysiwyg", () => {
       ]);
     });
 
+    it("should not add bound text to a frame when its container is not a frame child", async () => {
+      const frame = API.createElement({
+        type: "frame",
+        x: 0,
+        y: 0,
+        width: 200,
+        height: 200,
+      });
+      const rectangle = API.createElement({
+        type: "rectangle",
+        x: 10,
+        y: 20,
+        width: 90,
+        height: 75,
+        backgroundColor: "red",
+      });
+      API.setElements([frame, rectangle]);
+
+      mouse.doubleClickAt(rectangle.x + 10, rectangle.y + 10);
+
+      const text = h.elements[2] as ExcalidrawTextElementWithContainer;
+      expect(text.type).toBe("text");
+      expect(text.containerId).toBe(rectangle.id);
+      expect(text.frameId).toBe(null);
+    });
+
+    it("should bind text to a frame child container when single clicking its center", async () => {
+      const frame = API.createElement({
+        type: "frame",
+        x: 0,
+        y: 0,
+        width: 200,
+        height: 200,
+      });
+      const rectangle = API.createElement({
+        type: "rectangle",
+        x: 10,
+        y: 20,
+        width: 90,
+        height: 75,
+        backgroundColor: "red",
+        frameId: frame.id,
+      });
+      API.setElements([rectangle, frame]);
+
+      UI.clickTool("text");
+      mouse.clickAt(
+        rectangle.x + rectangle.width / 2,
+        rectangle.y + rectangle.height / 2,
+      );
+
+      const text = h.elements[1] as ExcalidrawTextElementWithContainer;
+      expect(text.type).toBe("text");
+      expect(text.containerId).toBe(rectangle.id);
+      expect(text.frameId).toBe(frame.id);
+    });
+
     it("should set the text element angle to same as container angle when binding to rotated container", async () => {
       const rectangle = API.createElement({
         type: "rectangle",

packages/fractional-indexing/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@excalidraw/fractional-indexing",
+  "version": "3.3.0",
+  "description": "Provides functions for generating ordering strings",
+  "type": "module",
+  "types": "./dist/types/fractional-indexing/src/index.d.ts",
+  "main": "./dist/prod/index.js",
+  "module": "./dist/prod/index.js",
+  "engines": {
+    "node": "^14.13.1 || >=16.0.0"
+  },
+  "scripts": {
+    "gen:types": "rimraf types && tsc",
+    "build:esm": "rimraf dist && node ../../scripts/buildBase.js && yarn gen:types"
+  },
+  "keywords": [
+    "fractional",
+    "indexing",
+    "ordering",
+    "order"
+  ],
+  "homepage": "https://github.com/rocicorp/fractional-indexing#readme",
+  "bugs": "https://github.com/excalidraw/excalidraw/issues",
+  "repository": "https://github.com/excalidraw/excalidraw",
+  "author": "arv@rocicorp.dev",
+  "license": "CC0-1.0",
+  "devDependencies": {
+    "prettier": "^2.6.0",
+    "typescript": "5.9.3"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/fractional-indexing/src/index.d.ts",
+      "development": "./dist/dev/index.js",
+      "production": "./dist/prod/index.js",
+      "default": "./dist/prod/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/*"
+  ]
+}

packages/fractional-indexing/src/index.ts

@@ -0,0 +1,322 @@
+// Vendored from https://www.npmjs.com/package/fractional-indexing
+// License: CC0 (no rights reserved).
+// This is based on https://observablehq.com/@dgreensp/implementing-fractional-indexing
+
+export const BASE_62_DIGITS =
+  "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+
+// `a` may be empty string, `b` is null or non-empty string.
+// `a < b` lexicographically if `b` is non-null.
+// no trailing zeros allowed.
+// digits is a string such as '0123456789' for base 10.  Digits must be in
+// ascending character code order!
+/**
+ * @param {string} a
+ * @param {string | null | undefined} b
+ * @param {string} digits
+ * @returns {string}
+ */
+function midpoint(
+  a: string,
+  b: string | null | undefined,
+  digits: string,
+): string {
+  const zero = digits[0];
+  if (b != null && a >= b) {
+    throw new Error(`${a} >= ${b}`);
+  }
+  if (a.slice(-1) === zero || (b && b.slice(-1) === zero)) {
+    throw new Error("trailing zero");
+  }
+  if (b) {
+    // remove longest common prefix.  pad `a` with 0s as we
+    // go.  note that we don't need to pad `b`, because it can't
+    // end before `a` while traversing the common prefix.
+    let n = 0;
+    while ((a[n] || zero) === b[n]) {
+      n++;
+    }
+    if (n > 0) {
+      return b.slice(0, n) + midpoint(a.slice(n), b.slice(n), digits);
+    }
+  }
+  // first digits (or lack of digit) are different
+  const digitA = a ? digits.indexOf(a[0]) : 0;
+  const digitB = b != null ? digits.indexOf(b[0]) : digits.length;
+  if (digitB - digitA > 1) {
+    const midDigit = Math.round(0.5 * (digitA + digitB));
+    return digits[midDigit];
+  }
+  // first digits are consecutive
+  if (b && b.length > 1) {
+    return b.slice(0, 1);
+  }
+
+  // `b` is null or has length 1 (a single digit).
+  // the first digit of `a` is the previous digit to `b`,
+  // or 9 if `b` is null.
+  // given, for example, midpoint('49', '5'), return
+  // '4' + midpoint('9', null), which will become
+  // '4' + '9' + midpoint('', null), which is '495'
+  return digits[digitA] + midpoint(a.slice(1), null, digits);
+}
+
+/**
+ * @param {string} int
+ * @return {void}
+ */
+
+function validateInteger(int: string): void {
+  if (int.length !== getIntegerLength(int[0])) {
+    throw new Error(`invalid integer part of order key: ${int}`);
+  }
+}
+
+/**
+ * @param {string} head
+ * @return {number}
+ */
+
+function getIntegerLength(head: string): number {
+  if (head >= "a" && head <= "z") {
+    return head.charCodeAt(0) - "a".charCodeAt(0) + 2;
+  } else if (head >= "A" && head <= "Z") {
+    return "Z".charCodeAt(0) - head.charCodeAt(0) + 2;
+  }
+
+  throw new Error(`invalid order key head: ${head}`);
+}
+
+/**
+ * @param {string} key
+ * @return {string}
+ */
+
+function getIntegerPart(key: string): string {
+  const integerPartLength = getIntegerLength(key[0]);
+
+  if (integerPartLength > key.length) {
+    throw new Error(`invalid order key: ${key}`);
+  }
+  return key.slice(0, integerPartLength);
+}
+
+/**
+ * @param {string} key
+ * @param {string} digits
+ * @return {void}
+ */
+export function validateOrderKey(
+  key: string,
+  digits: string = BASE_62_DIGITS,
+): void {
+  const validChars = key.split("").every((char) => digits.includes(char));
+  if (key === `A${digits[0].repeat(26)}` || !validChars) {
+    throw new Error(`invalid order key: ${key}`);
+  }
+  // getIntegerPart will throw if the first character is bad,
+  // or the key is too short.  we'd call it to check these things
+  // even if we didn't need the result
+  const i = getIntegerPart(key);
+  const f = key.slice(i.length);
+  if (f.slice(-1) === digits[0]) {
+    throw new Error(`invalid order key: ${key}`);
+  }
+}
+
+// note that this may return null, as there is a largest integer
+/**
+ * @param {string} x
+ * @param {string} digits
+ * @return {string | null}
+ */
+function incrementInteger(x: string, digits: string): string | null {
+  validateInteger(x);
+  const [head, ...digs] = x.split("");
+  let carry = true;
+  for (let i = digs.length - 1; carry && i >= 0; i--) {
+    const d = digits.indexOf(digs[i]) + 1;
+    if (d === digits.length) {
+      digs[i] = digits[0];
+    } else {
+      digs[i] = digits[d];
+      carry = false;
+    }
+  }
+  if (carry) {
+    if (head === "Z") {
+      return `a${digits[0]}`;
+    }
+    if (head === "z") {
+      return null;
+    }
+    const h = String.fromCharCode(head.charCodeAt(0) + 1);
+    if (h > "a") {
+      digs.push(digits[0]);
+    } else {
+      digs.pop();
+    }
+    return h + digs.join("");
+  }
+  return head + digs.join("");
+}
+
+// note that this may return null, as there is a smallest integer
+/**
+ * @param {string} x
+ * @param {string} digits
+ * @return {string | null}
+ */
+function decrementInteger(x: string, digits: string): string | null {
+  validateInteger(x);
+  const [head, ...digs] = x.split("");
+  let borrow = true;
+  for (let i = digs.length - 1; borrow && i >= 0; i--) {
+    const d = digits.indexOf(digs[i]) - 1;
+    if (d === -1) {
+      digs[i] = digits.slice(-1);
+    } else {
+      digs[i] = digits[d];
+      borrow = false;
+    }
+  }
+  if (borrow) {
+    if (head === "a") {
+      return `Z${digits.slice(-1)}`;
+    }
+    if (head === "A") {
+      return null;
+    }
+    const h = String.fromCharCode(head.charCodeAt(0) - 1);
+    if (h < "Z") {
+      digs.push(digits.slice(-1));
+    } else {
+      digs.pop();
+    }
+    return h + digs.join("");
+  }
+  return head + digs.join("");
+}
+
+// `a` is an order key or null (START).
+// `b` is an order key or null (END).
+// `a < b` lexicographically if both are non-null.
+// digits is a string such as '0123456789' for base 10.  Digits must be in
+// ascending character code order!
+/**
+ * @param {string | null | undefined} a
+ * @param {string | null | undefined} b
+ * @param {string=} digits
+ * @return {string}
+ */
+export function generateKeyBetween(
+  a: string | null | undefined,
+  b: string | null | undefined,
+  digits = BASE_62_DIGITS,
+): string {
+  if (a != null) {
+    validateOrderKey(a, digits);
+  }
+  if (b != null) {
+    validateOrderKey(b, digits);
+  }
+  if (a != null && b != null && a >= b) {
+    throw new Error(`${a} >= ${b}`);
+  }
+  if (a == null) {
+    if (b == null) {
+      return `a${digits[0]}`;
+    }
+
+    const ib = getIntegerPart(b);
+    const fb = b.slice(ib.length);
+    if (ib === `A${digits[0].repeat(26)}`) {
+      return ib + midpoint("", fb, digits);
+    }
+    if (ib < b) {
+      return ib;
+    }
+    const res = decrementInteger(ib, digits);
+    if (res == null) {
+      throw new Error("cannot decrement any more");
+    }
+    return res;
+  }
+
+  if (b == null) {
+    const ia = getIntegerPart(a);
+    const fa = a.slice(ia.length);
+    const i = incrementInteger(ia, digits);
+    return i == null ? ia + midpoint(fa, null, digits) : i;
+  }
+
+  const ia = getIntegerPart(a);
+  const fa = a.slice(ia.length);
+  const ib = getIntegerPart(b);
+  const fb = b.slice(ib.length);
+  if (ia === ib) {
+    return ia + midpoint(fa, fb, digits);
+  }
+  const i = incrementInteger(ia, digits);
+  if (i == null) {
+    throw new Error("cannot increment any more");
+  }
+  if (i < b) {
+    return i;
+  }
+  return ia + midpoint(fa, null, digits);
+}
+
+/**
+ * same preconditions as generateKeysBetween.
+ * n >= 0.
+ * Returns an array of n distinct keys in sorted order.
+ * If a and b are both null, returns [a0, a1, ...]
+ * If one or the other is null, returns consecutive "integer"
+ * keys.  Otherwise, returns relatively short keys between
+ * a and b.
+ * @param {string | null | undefined} a
+ * @param {string | null | undefined} b
+ * @param {number} n
+ * @param {string} digits
+ * @return {string[]}
+ */
+export function generateNKeysBetween(
+  a: string | null | undefined,
+  b: string | null | undefined,
+  n: number,
+  digits = BASE_62_DIGITS,
+): string[] {
+  if (n === 0) {
+    return [];
+  }
+  if (n === 1) {
+    return [generateKeyBetween(a, b, digits)];
+  }
+  if (b == null) {
+    let c = generateKeyBetween(a, b, digits);
+    const result = [c];
+    for (let i = 0; i < n - 1; i++) {
+      c = generateKeyBetween(c, b, digits);
+      result.push(c);
+    }
+    return result;
+  }
+  if (a == null) {
+    let c = generateKeyBetween(a, b, digits);
+    const result = [c];
+    for (let i = 0; i < n - 1; i++) {
+      c = generateKeyBetween(a, c, digits);
+      result.push(c);
+    }
+    result.reverse();
+    return result;
+  }
+  const mid = Math.floor(n / 2);
+  const c = generateKeyBetween(a, b, digits);
+  return [
+    ...generateNKeysBetween(a, c, mid, digits),
+    c,
+    ...generateNKeysBetween(c, b, n - mid - 1, digits),
+  ];
+}

packages/fractional-indexing/tsconfig.json

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

packages/math/src/constants.ts

@@ -1,5 +1,3 @@
-export const PRECISION = 10e-5;
-
 // Legendre-Gauss abscissae (x values) and weights for n=24
 // Refeerence: https://pomax.github.io/bezierinfo/legendre-gauss.html
 export const LegendreGaussN24TValues = [

packages/math/src/point.ts

@@ -1,5 +1,5 @@
 import { degreesToRadians } from "./angle";
-import { PRECISION } from "./utils";
+import { isFiniteNumber, PRECISION } from "./utils";
 import { vectorFromPoint, vectorScale } from "./vector";
 
 import type {
@@ -253,3 +253,12 @@ export const isPointWithinBounds = <P extends GlobalPoint | LocalPoint>(
     q[1] >= Math.min(p[1], r[1])
   );
 };
+
+export const isValidPoint = (point: unknown): point is LocalPoint => {
+  return (
+    Array.isArray(point) &&
+    point.length === 2 &&
+    isFiniteNumber(point[0]) &&
+    isFiniteNumber(point[1])
+  );
+};

packages/tsconfig.base.json

@@ -20,7 +20,9 @@
       "@excalidraw/math": ["./math/src/index.ts"],
       "@excalidraw/math/*": ["./math/src/*"],
       "@excalidraw/utils": ["./utils/src/index.ts"],
-      "@excalidraw/utils/*": ["./utils/src/*"]
+      "@excalidraw/utils/*": ["./utils/src/*"],
+      "@excalidraw/fractional-indexing": ["./fractional-indexing/src/index.ts"],
+      "@excalidraw/fractional-indexing/*": ["./fractional-indexing/src/*"]
     }
   }
 }

packages/utils/tests/__snapshots__/export.test.ts.snap

@@ -98,7 +98,6 @@ exports[`exportToSvg > with default arguments 1`] = `
   "showHyperlinkPopup": false,
   "showWelcomeScreen": false,
   "snapLines": [],
-  "startBoundElement": null,
   "stats": {
     "open": false,
     "panels": 3,

scripts/buildBase.js

@@ -13,7 +13,12 @@ const getConfig = (outdir) => ({
   alias: {
     "@excalidraw/utils": path.resolve(__dirname, "../packages/utils/src"),
   },
-  external: ["@excalidraw/common", "@excalidraw/element", "@excalidraw/math"],
+  external: [
+    "@excalidraw/common",
+    "@excalidraw/element",
+    "@excalidraw/math",
+    "@excalidraw/fractional-indexing",
+  ],
 });
 
 function buildDev(config) {

scripts/buildPackage.js

@@ -74,7 +74,12 @@ const getConfig = (outdir) => ({
   alias: {
     "@excalidraw/utils": path.resolve(__dirname, "../packages/utils/src"),
   },
-  external: ["@excalidraw/common", "@excalidraw/element", "@excalidraw/math"],
+  external: [
+    "@excalidraw/common",
+    "@excalidraw/element",
+    "@excalidraw/math",
+    "@excalidraw/fractional-indexing",
+  ],
   loader: {
     ".woff2": "file",
   },