debug

.playwright-mcp/page-2026-06-26T08-26-20-195Z.yml

@@ -0,0 +1,124 @@
+- generic [ref=e1]:
+  - banner:
+    - heading "Excalidraw" [level=1] [ref=e2]
+  - generic [active] [ref=e5]:
+    - generic:
+      - generic:
+        - generic:
+          - button [ref=e9] [cursor=pointer]:
+            - img [ref=e10]
+          - region "Shapes":
+            - generic [ref=e16]:
+              - generic:
+                - generic:
+                  - text: To move canvas, hold
+                  - generic: Scroll wheel
+                  - text: or
+                  - generic: Space
+                  - text: while dragging, or use the hand tool
+              - heading "Shapes" [level=2] [ref=e17]
+              - generic [ref=e18]:
+                - generic "Keep selected tool active after drawing — Q" [ref=e19] [cursor=pointer]:
+                  - checkbox "Keep selected tool active after drawing"
+                  - img [ref=e21]
+                - generic "Hand (panning tool) — H or null" [ref=e29] [cursor=pointer]:
+                  - radio "Hand (panning tool)"
+                  - img [ref=e31]
+                - generic "Selection — V or 1" [ref=e38] [cursor=pointer]:
+                  - radio "Selection" [checked]
+                  - generic [ref=e39]:
+                    - img [ref=e40]
+                    - generic [ref=e45]: "1"
+                - generic "Rectangle — R or 2" [ref=e46] [cursor=pointer]:
+                  - radio "Rectangle"
+                  - generic [ref=e47]:
+                    - img [ref=e48]
+                    - generic [ref=e52]: "2"
+                - generic "Diamond — D or 3" [ref=e53] [cursor=pointer]:
+                  - radio "Diamond"
+                  - generic [ref=e54]:
+                    - img [ref=e55]
+                    - generic [ref=e59]: "3"
+                - generic "Ellipse — O or 4" [ref=e60] [cursor=pointer]:
+                  - radio "Ellipse"
+                  - generic [ref=e61]:
+                    - img [ref=e62]
+                    - generic [ref=e66]: "4"
+                - generic "Arrow — A or 5" [ref=e67] [cursor=pointer]:
+                  - radio "Arrow"
+                  - generic [ref=e68]:
+                    - img [ref=e69]
+                    - generic [ref=e74]: "5"
+                - generic "Line — L or 6" [ref=e75] [cursor=pointer]:
+                  - radio "Line"
+                  - generic [ref=e76]:
+                    - img [ref=e77]
+                    - generic [ref=e78]: "6"
+                - generic "Draw — P or 7" [ref=e79] [cursor=pointer]:
+                  - radio "Draw"
+                  - generic [ref=e80]:
+                    - img [ref=e81]
+                    - generic [ref=e85]: "7"
+                - generic "Text — T or 8" [ref=e86] [cursor=pointer]:
+                  - radio "Text"
+                  - generic [ref=e87]:
+                    - img [ref=e88]
+                    - generic [ref=e93]: "8"
+                - generic "Insert image — 9" [ref=e94] [cursor=pointer]:
+                  - radio "Insert image"
+                  - generic [ref=e95]:
+                    - img [ref=e96]
+                    - generic [ref=e101]: "9"
+                - generic "Eraser — E or 0" [ref=e102] [cursor=pointer]:
+                  - radio "Eraser"
+                  - generic [ref=e103]:
+                    - img [ref=e104]
+                    - generic [ref=e109]: "0"
+                - button "More tools" [ref=e112] [cursor=pointer]:
+                  - img [ref=e113]
+          - generic:
+            - generic [ref=e119]:
+              - link "Excalidraw+" [ref=e120] [cursor=pointer]:
+                - /url: https://plus.excalidraw.com/plus?utm_source=excalidraw&utm_medium=app&utm_content=guestBanner#excalidraw-redirect
+              - button "Live collaboration..." [ref=e121] [cursor=pointer]:
+                - img [ref=e122]
+            - generic "Library" [ref=e124]:
+              - checkbox "Library"
+              - img [ref=e127] [cursor=pointer]
+      - contentinfo:
+        - region "Canvas actions" [ref=e132]:
+          - heading "Canvas actions" [level=2] [ref=e133]
+          - generic [ref=e135]:
+            - button "Zoom out" [ref=e136] [cursor=pointer]:
+              - img [ref=e138]
+            - button "Reset zoom" [ref=e140] [cursor=pointer]: 100%
+            - button "Zoom in" [ref=e141] [cursor=pointer]:
+              - img [ref=e143]
+          - generic [ref=e145]:
+            - button "Undo" [disabled] [ref=e148]:
+              - img [ref=e150]
+            - button "Redo" [disabled] [ref=e154]:
+              - img [ref=e156]
+        - generic [ref=e158]:
+          - generic [ref=e159]:
+            - button "lock scroll" [ref=e160] [cursor=pointer]
+            - generic [ref=e161]:
+              - text: overscroll
+              - spinbutton "overscroll" [ref=e162]: "0.2"
+            - generic [ref=e163]:
+              - text: zoom factor
+              - spinbutton "zoom factor" [ref=e164]: "0.2"
+            - generic [ref=e165]:
+              - checkbox "lock zoom" [ref=e166]
+              - text: lock zoom
+            - generic [ref=e167]:
+              - checkbox "animate" [ref=e168]
+              - text: animate
+          - link "Blog post on end-to-end encryption in Excalidraw" [ref=e169] [cursor=pointer]:
+            - /url: https://plus.excalidraw.com/blog/end-to-end-encryption
+            - img [ref=e171]
+        - button "Help" [ref=e174] [cursor=pointer]:
+          - img [ref=e175]
+    - generic:
+      - img
+    - generic [ref=e180]: Drawing canvas

.playwright-mcp/page-2026-06-26T08-26-34-790Z.yml

@@ -0,0 +1,126 @@
+- generic [ref=e1]:
+  - banner:
+    - heading "Excalidraw" [level=1] [ref=e2]
+  - generic [ref=e5]:
+    - generic:
+      - generic:
+        - generic:
+          - generic:
+            - img
+            - img
+        - generic:
+          - text: Your drawings are saved in your browser's storage.
+          - text: Browser storage can be cleared unexpectedly.
+          - text: Save your work to a file regularly to avoid losing it.
+        - generic:
+          - button "Open Ctrl+O" [ref=e181] [cursor=pointer]:
+            - img [ref=e183]
+            - generic [ref=e185]: Open
+            - generic [ref=e186]: Ctrl+O
+          - button "Help ?" [ref=e187] [cursor=pointer]:
+            - img [ref=e189]
+            - generic [ref=e194]: Help
+            - generic [ref=e195]: "?"
+          - button "Live collaboration..." [ref=e196] [cursor=pointer]:
+            - img [ref=e198]
+            - generic [ref=e205]: Live collaboration...
+          - link "Sign up" [ref=e206] [cursor=pointer]:
+            - /url: https://plus.excalidraw.com/plus?utm_source=excalidraw&utm_medium=app&utm_content=welcomeScreenGuest
+            - img [ref=e208]
+            - generic [ref=e214]: Sign up
+      - generic:
+        - generic:
+          - button [ref=e9] [cursor=pointer]:
+            - img [ref=e10]
+          - region "Shapes":
+            - generic [ref=e16]:
+              - generic:
+                - generic:
+                  - text: To move canvas, hold
+                  - generic: Scroll wheel
+                  - text: or
+                  - generic: Space
+                  - text: while dragging, or use the hand tool
+              - heading "Shapes" [level=2] [ref=e17]
+              - generic [ref=e18]:
+                - generic "Keep selected tool active after drawing — Q" [ref=e19] [cursor=pointer]:
+                  - checkbox "Keep selected tool active after drawing"
+                  - img [ref=e21]
+                - generic "Hand (panning tool) — H or null" [ref=e29] [cursor=pointer]:
+                  - radio "Hand (panning tool)"
+                  - img [ref=e31]
+                - generic "Selection" [ref=e215] [cursor=pointer]:
+                  - radio "Selection" [checked]
+                  - img [ref=e217]
+                - generic "Rectangle — R or 2" [ref=e46] [cursor=pointer]:
+                  - radio "Rectangle"
+                  - img [ref=e48]
+                - generic "Diamond — D or 3" [ref=e53] [cursor=pointer]:
+                  - radio "Diamond"
+                  - img [ref=e55]
+                - generic "Ellipse — O or 4" [ref=e60] [cursor=pointer]:
+                  - radio "Ellipse"
+                  - img [ref=e62]
+                - generic "Arrow — A or 5" [ref=e67] [cursor=pointer]:
+                  - radio "Arrow"
+                  - img [ref=e69]
+                - generic "Line — L or 6" [ref=e75] [cursor=pointer]:
+                  - radio "Line"
+                  - img [ref=e77]
+                - generic "Draw — P or 7" [ref=e79] [cursor=pointer]:
+                  - radio "Draw"
+                  - img [ref=e81]
+                - generic "Text — T or 8" [ref=e86] [cursor=pointer]:
+                  - radio "Text"
+                  - img [ref=e88]
+                - generic "Insert image — 9" [ref=e94] [cursor=pointer]:
+                  - radio "Insert image"
+                  - img [ref=e96]
+                - generic "Eraser — E or 0" [ref=e102] [cursor=pointer]:
+                  - radio "Eraser"
+                  - img [ref=e104]
+                - button "More tools" [ref=e112] [cursor=pointer]:
+                  - img [ref=e113]
+          - generic:
+            - button "Live collaboration..." [ref=e121] [cursor=pointer]:
+              - img [ref=e122]
+            - generic "Library" [ref=e124]:
+              - checkbox "Library"
+              - img [ref=e127] [cursor=pointer]
+      - contentinfo:
+        - region "Canvas actions" [ref=e132]:
+          - heading "Canvas actions" [level=2] [ref=e133]
+          - generic [ref=e135]:
+            - button "Zoom out" [ref=e136] [cursor=pointer]:
+              - img [ref=e138]
+            - button "Reset zoom" [disabled] [ref=e140]: 100%
+            - button "Zoom in" [ref=e141] [cursor=pointer]:
+              - img [ref=e143]
+          - generic [ref=e145]:
+            - button "Undo" [disabled] [ref=e148]:
+              - img [ref=e150]
+            - button "Redo" [disabled] [ref=e154]:
+              - img [ref=e156]
+        - generic [ref=e158]:
+          - generic [ref=e159]:
+            - button "disable scroll lock" [active] [ref=e222] [cursor=pointer]
+            - generic [ref=e161]:
+              - text: overscroll
+              - spinbutton "overscroll" [ref=e162]: "0.2"
+            - generic [ref=e163]:
+              - text: zoom factor
+              - spinbutton "zoom factor" [ref=e164]: "0.2"
+            - generic [ref=e165]:
+              - checkbox "lock zoom" [ref=e166]
+              - text: lock zoom
+            - generic [ref=e167]:
+              - checkbox "animate" [ref=e168]
+              - text: animate
+          - link "Blog post on end-to-end encryption in Excalidraw" [ref=e169] [cursor=pointer]:
+            - /url: https://plus.excalidraw.com/blog/end-to-end-encryption
+            - img [ref=e171]
+        - button "Help" [ref=e174] [cursor=pointer]:
+          - img [ref=e175]
+    - generic:
+      - img
+    - generic [ref=e180]: Drawing canvas

examples/with-nextjs/src/excalidrawWrapper.tsx

@@ -4,8 +4,20 @@ import { Excalidraw } from "@excalidraw/excalidraw";
 
 import "@excalidraw/excalidraw/index.css";
 
+import type { ScrollConstraints } from "@excalidraw/excalidraw/types";
+
 import App from "../../with-script-in-browser/components/ExampleApp";
 
+const scrollConstraints: ScrollConstraints = {
+  x: 0,
+  y: 0,
+  width: 850,
+  height: 400,
+  lockZoom: true,
+  overscrollAllowance: 0,
+  viewportZoomFactor: 1,
+};
+
 const ExcalidrawWrapper: React.FC = () => {
   return (
     <>
@@ -14,7 +26,7 @@ const ExcalidrawWrapper: React.FC = () => {
         useCustom={(api: any, args?: any[]) => {}}
         excalidrawLib={excalidrawLib}
       >
-        <Excalidraw />
+        <Excalidraw scrollConstraints={scrollConstraints} />
       </App>
     </>
   );

examples/with-script-in-browser/components/ExampleApp.tsx

@@ -178,7 +178,8 @@ export default function ExampleApp({
     const newElement = cloneElement(
       Excalidraw,
       {
-        excalidrawAPI: (api: ExcalidrawImperativeAPI) => setExcalidrawAPI(api),
+        onExcalidrawAPI: (api: ExcalidrawImperativeAPI | null) =>
+          setExcalidrawAPI(api),
         initialData: initialStatePromiseRef.current.promise,
         onChange: (
           elements: NonDeletedExcalidrawElement[],
@@ -820,6 +821,48 @@ export default function ExampleApp({
             />
             Export with embed scene
           </label>
+          <button
+            type="button"
+            onClick={() => {
+              if (!excalidrawAPI) {
+                return;
+              }
+
+              const elements = excalidrawAPI.getSceneElements();
+              excalidrawAPI.scrollToContent(elements[0], {
+                animate: true,
+                fitToViewport: true,
+                viewportZoomFactor: 0.9,
+                scrollLock: {
+                  lockZoom: true,
+                  overscrollAllowance: 0,
+                },
+              });
+            }}
+          >
+            Fit and lock first element
+          </button>
+          <button
+            type="button"
+            onClick={() => {
+              if (!excalidrawAPI) {
+                return;
+              }
+
+              const elements = excalidrawAPI.getSceneElements();
+              excalidrawAPI.scrollToContent(elements[1], {
+                animate: true,
+                fitToViewport: true,
+                viewportZoomFactor: 0.9,
+                scrollLock: {
+                  lockZoom: true,
+                  overscrollAllowance: 0,
+                },
+              });
+            }}
+          >
+            Fit and lock second element
+          </button>
           <button
             onClick={async () => {
               if (!excalidrawAPI) {

excalidraw-app/App.tsx

@@ -1015,7 +1015,10 @@ const ExcalidrawWrapper = () => {
             </OverwriteConfirmDialog.Action>
           )}
         </OverwriteConfirmDialog>
-        <AppFooter onChange={() => excalidrawAPI?.refresh()} />
+        <AppFooter
+          excalidrawAPI={excalidrawAPI}
+          onChange={() => excalidrawAPI?.refresh()}
+        />
         {excalidrawAPI && <AIComponents excalidrawAPI={excalidrawAPI} />}
 
         <TTDDialogTrigger />

excalidraw-app/components/AppFooter.tsx

@@ -1,13 +1,178 @@
 import { Footer } from "@excalidraw/excalidraw/index";
-import React from "react";
+import {
+  getCommonBounds,
+  getSelectedElements,
+  getVisibleSceneBounds,
+} from "@excalidraw/element";
+import React, { useCallback, useState } from "react";
+
+import type {
+  ExcalidrawImperativeAPI,
+  ScrollConstraints,
+} from "@excalidraw/excalidraw/types";
 
 import { isExcalidrawPlusSignedUser } from "../app_constants";
 
 import { DebugFooter, isVisualDebuggerEnabled } from "./DebugCanvas";
 import { EncryptedIcon } from "./EncryptedIcon";
 
+type ScrollConstraintOptions = Pick<
+  ScrollConstraints,
+  "lockZoom" | "overscrollAllowance" | "viewportZoomFactor"
+>;
+
+const ScrollConstraintsDebugFooter = ({
+  excalidrawAPI,
+}: {
+  excalidrawAPI: ExcalidrawImperativeAPI | null;
+}) => {
+  const [activeLock, setActiveLock] = useState<ScrollConstraints | null>(null);
+  const [options, setOptions] = useState<ScrollConstraintOptions>({
+    lockZoom: false,
+    overscrollAllowance: 0.2,
+    viewportZoomFactor: 0.2,
+  });
+
+  const setLock = useCallback(
+    (nextLock: ScrollConstraints) => {
+      excalidrawAPI?.setScrollConstraints(nextLock);
+      setActiveLock(nextLock);
+    },
+    [excalidrawAPI],
+  );
+
+  const toggleScrollLock = useCallback(() => {
+    if (!excalidrawAPI) {
+      return;
+    }
+
+    if (activeLock) {
+      excalidrawAPI.setScrollConstraints(null);
+      setActiveLock(null);
+      return;
+    }
+
+    const selectedElements = getSelectedElements(
+      excalidrawAPI.getSceneElements(),
+      excalidrawAPI.getAppState(),
+      {
+        includeBoundTextElement: true,
+        includeElementsInFrames: true,
+      },
+    );
+    const [x1, y1, x2, y2] = selectedElements.length
+      ? getCommonBounds(
+          selectedElements,
+          excalidrawAPI.getSceneElementsMapIncludingDeleted(),
+        )
+      : getVisibleSceneBounds(excalidrawAPI.getAppState());
+
+    setLock({
+      x: x1,
+      y: y1,
+      width: x2 - x1,
+      height: y2 - y1,
+      ...options,
+    });
+  }, [activeLock, excalidrawAPI, options, setLock]);
+
+  const updateOptions = useCallback(
+    (nextOptions: ScrollConstraintOptions) => {
+      setOptions(nextOptions);
+
+      if (activeLock) {
+        setLock({ ...activeLock, ...nextOptions });
+      }
+    },
+    [activeLock, setLock],
+  );
+
+  const updateNumberOption = useCallback(
+    (option: "overscrollAllowance" | "viewportZoomFactor", value: string) => {
+      updateOptions({
+        ...options,
+        [option]: value === "" ? undefined : Number(value),
+      });
+    },
+    [options, updateOptions],
+  );
+
+  const updateBooleanOption = useCallback(
+    (option: "lockZoom", value: boolean) => {
+      updateOptions({
+        ...options,
+        [option]: value,
+      });
+    },
+    [options, updateOptions],
+  );
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        gap: ".45rem",
+        alignItems: "center",
+        padding: "0 .35rem",
+        fontSize: 12,
+      }}
+    >
+      <button
+        className="ToolIcon_type_button"
+        type="button"
+        onClick={toggleScrollLock}
+      >
+        {activeLock ? "disable scroll lock" : "lock scroll"}
+      </button>
+      <label style={{ display: "flex", gap: ".25rem", alignItems: "center" }}>
+        overscroll
+        <input
+          type="number"
+          min={0}
+          max={1}
+          step={0.05}
+          value={options.overscrollAllowance ?? ""}
+          onChange={(event) =>
+            updateNumberOption("overscrollAllowance", event.target.value)
+          }
+          style={{ width: 56 }}
+        />
+      </label>
+      <label style={{ display: "flex", gap: ".25rem", alignItems: "center" }}>
+        zoom factor
+        <input
+          type="number"
+          min={0.1}
+          step={0.1}
+          value={options.viewportZoomFactor ?? ""}
+          onChange={(event) =>
+            updateNumberOption("viewportZoomFactor", event.target.value)
+          }
+          style={{ width: 56 }}
+        />
+      </label>
+      <label style={{ display: "flex", gap: ".2rem", alignItems: "center" }}>
+        <input
+          type="checkbox"
+          checked={!!options.lockZoom}
+          onChange={(event) =>
+            updateBooleanOption("lockZoom", event.target.checked)
+          }
+        />
+        lock zoom
+      </label>
+    </div>
+  );
+};
+
 export const AppFooter = React.memo(
-  ({ onChange }: { onChange: () => void }) => {
+  ({
+    excalidrawAPI,
+    onChange,
+  }: {
+    excalidrawAPI: ExcalidrawImperativeAPI | null;
+    onChange: () => void;
+  }) => {
     return (
       <Footer>
         <div
@@ -17,6 +182,7 @@ export const AppFooter = React.memo(
             alignItems: "center",
           }}
         >
+          <ScrollConstraintsDebugFooter excalidrawAPI={excalidrawAPI} />
           {isVisualDebuggerEnabled() && <DebugFooter onChange={onChange} />}
           {!isExcalidrawPlusSignedUser && <EncryptedIcon />}
         </div>

packages/excalidraw/actions/actionCanvas.tsx

@@ -40,6 +40,7 @@ import {
   ZoomResetIcon,
 } from "../components/icons";
 import { setCursor } from "../cursor";
+import { constrainScrollState } from "../scene/scrollConstraints";
 
 import { t } from "../i18n";
 import { getNormalizedZoom } from "../scene";
@@ -51,6 +52,8 @@ import { register } from "./register";
 
 import type { AppState, Offsets } from "../types";
 
+const canUseZoomActions = (appState: AppState) => !appState.scrollConstraints;
+
 export const actionChangeViewBackgroundColor = register<Partial<AppState>>({
   name: "changeViewBackgroundColor",
   label: "labels.canvasBackground",
@@ -139,7 +142,7 @@ export const actionZoomIn = register({
   trackEvent: { category: "canvas" },
   perform: (_elements, appState, _, app) => {
     return {
-      appState: {
+      appState: constrainScrollState({
         ...appState,
         ...getStateForZoom(
           {
@@ -150,7 +153,7 @@ export const actionZoomIn = register({
           appState,
         ),
         userToFollow: null,
-      },
+      }),
       captureUpdate: CaptureUpdateAction.EVENTUALLY,
     };
   },
@@ -180,7 +183,7 @@ export const actionZoomOut = register({
   trackEvent: { category: "canvas" },
   perform: (_elements, appState, _, app) => {
     return {
-      appState: {
+      appState: constrainScrollState({
         ...appState,
         ...getStateForZoom(
           {
@@ -191,7 +194,7 @@ export const actionZoomOut = register({
           appState,
         ),
         userToFollow: null,
-      },
+      }),
       captureUpdate: CaptureUpdateAction.EVENTUALLY,
     };
   },
@@ -243,6 +246,7 @@ export const actionResetZoom = register({
         className="reset-zoom-button zoom-button"
         title={t("buttons.resetZoom")}
         aria-label={t("buttons.resetZoom")}
+        disabled={!canUseZoomActions(appState)}
         onClick={() => {
           updateData(null);
         }}
@@ -251,6 +255,7 @@ export const actionResetZoom = register({
       </ToolButton>
     </Tooltip>
   ),
+  predicate: (_elements, appState) => canUseZoomActions(appState),
   keyTest: (event) =>
     (event.code === CODES.ZERO || event.code === CODES.NUM_ZERO) &&
     (event[KEYS.CTRL_OR_CMD] || event.shiftKey),
@@ -274,7 +279,7 @@ const zoomValueToFitBoundsOnViewport = (
   return Math.min(adjustedZoomValue, 1);
 };
 
-export const zoomToFitBounds = ({
+export function resolveViewportForBounds({
   bounds,
   appState,
   canvasOffsets,
@@ -292,7 +297,7 @@ export const zoomToFitBounds = ({
   viewportZoomFactor?: number;
   minZoom?: number;
   maxZoom?: number;
-}) => {
+}) {
   viewportZoomFactor = clamp(viewportZoomFactor, MIN_ZOOM, MAX_ZOOM);
 
   const [x1, y1, x2, y2] = bounds;
@@ -345,12 +350,58 @@ export const zoomToFitBounds = ({
     zoom: { value: newZoomValue },
   });
 
+  return {
+    bounds,
+    scrollX: centerScroll.scrollX,
+    scrollY: centerScroll.scrollY,
+    zoom: { value: newZoomValue },
+    viewportZoomFactor,
+    viewportDimensions: {
+      width: appState.width,
+      height: appState.height,
+    },
+    effectiveViewportDimensions: {
+      width: effectiveCanvasWidth,
+      height: effectiveCanvasHeight,
+    },
+  };
+}
+
+export const zoomToFitBounds = ({
+  bounds,
+  appState,
+  canvasOffsets,
+  fitToViewport = false,
+  viewportZoomFactor = 1,
+  minZoom = -Infinity,
+  maxZoom = Infinity,
+}: {
+  bounds: SceneBounds;
+  canvasOffsets?: Offsets;
+  appState: Readonly<AppState>;
+  /** whether to fit content to viewport (beyond >100%) */
+  fitToViewport: boolean;
+  /** zoom content to cover X of the viewport, when fitToViewport=true */
+  viewportZoomFactor?: number;
+  minZoom?: number;
+  maxZoom?: number;
+}) => {
+  const resolvedViewport = resolveViewportForBounds({
+    bounds,
+    appState,
+    canvasOffsets,
+    fitToViewport,
+    viewportZoomFactor,
+    minZoom,
+    maxZoom,
+  });
+
   return {
     appState: {
       ...appState,
-      scrollX: centerScroll.scrollX,
-      scrollY: centerScroll.scrollY,
-      zoom: { value: newZoomValue },
+      scrollX: resolvedViewport.scrollX,
+      scrollY: resolvedViewport.scrollY,
+      zoom: resolvedViewport.zoom,
     },
     captureUpdate: CaptureUpdateAction.EVENTUALLY,
   };
@@ -408,6 +459,7 @@ export const actionZoomToFitSelectionInViewport = register({
       canvasOffsets: app.getEditorUIOffsets(),
     });
   },
+  predicate: (_elements, appState) => canUseZoomActions(appState),
   // NOTE shift-2 should have been assigned actionZoomToFitSelection.
   // TBD on how proceed
   keyTest: (event) =>
@@ -434,6 +486,7 @@ export const actionZoomToFitSelection = register({
       canvasOffsets: app.getEditorUIOffsets(),
     });
   },
+  predicate: (_elements, appState) => canUseZoomActions(appState),
   // NOTE this action should use shift-2 per figma, alas
   keyTest: (event) =>
     event.code === CODES.THREE &&
@@ -458,6 +511,7 @@ export const actionZoomToFit = register({
       fitToViewport: false,
       canvasOffsets: app.getEditorUIOffsets(),
     }),
+  predicate: (_elements, appState) => canUseZoomActions(appState),
   keyTest: (event) =>
     event.code === CODES.ONE &&
     event.shiftKey &&

packages/excalidraw/actions/actionGroup.tsx

@@ -49,9 +49,18 @@ import { register } from "./register";
 
 import type { AppClassProperties, AppState } from "../types";
 
-const allElementsInSameGroup = (elements: readonly ExcalidrawElement[]) => {
+const allElementsInSameGroup = (
+  elements: readonly ExcalidrawElement[],
+  editingGroupId: AppState["editingGroupId"],
+) => {
   if (elements.length >= 2) {
-    const groupIds = elements[0].groupIds;
+    const editingGroupIndex = editingGroupId
+      ? elements[0].groupIds.indexOf(editingGroupId)
+      : -1;
+    const groupIds =
+      editingGroupIndex > -1
+        ? elements[0].groupIds.slice(0, editingGroupIndex)
+        : elements[0].groupIds;
     for (const groupId of groupIds) {
       if (
         elements.reduce(
@@ -78,7 +87,7 @@ const enableActionGroup = (
 
   return (
     selectedElements.length >= 2 &&
-    !allElementsInSameGroup(selectedElements) &&
+    !allElementsInSameGroup(selectedElements, appState.editingGroupId) &&
     !frameAndChildrenSelectedTogether(selectedElements)
   );
 };

packages/excalidraw/actions/actionToggleSearchMenu.ts

@@ -53,8 +53,5 @@ export const actionToggleSearchMenu = register({
     };
   },
   checked: (appState: AppState) => appState.gridModeEnabled,
-  predicate: (element, appState, props) => {
-    return props.gridModeEnabled === undefined;
-  },
   keyTest: (event) => event[KEYS.CTRL_OR_CMD] && event.key === KEYS.F,
 });

packages/excalidraw/actions/manager.tsx

@@ -95,6 +95,13 @@ export class ActionManager {
           (action.name in canvasActions
             ? canvasActions[action.name as keyof typeof canvasActions]
             : true) &&
+          (!action.predicate ||
+            action.predicate(
+              this.getElementsIncludingDeleted(),
+              this.getAppState(),
+              this.app.props,
+              this.app,
+            )) &&
           action.keyTest &&
           action.keyTest(
             event,

packages/excalidraw/appState.ts

@@ -122,6 +122,7 @@ export const getDefaultAppState = (): Omit<
     objectsSnapModeEnabled: false,
     userToFollow: null,
     followedBy: new Set(),
+    scrollConstraints: null,
     isCropping: false,
     croppingElementId: null,
     searchMatches: null,
@@ -250,6 +251,7 @@ const APP_STATE_STORAGE_CONF = (<
   objectsSnapModeEnabled: { browser: true, export: false, server: false },
   userToFollow: { browser: false, export: false, server: false },
   followedBy: { browser: false, export: false, server: false },
+  scrollConstraints: { browser: true, export: false, server: false },
   isCropping: { browser: false, export: false, server: false },
   croppingElementId: { browser: false, export: false, server: false },
   searchMatches: { browser: false, export: false, server: false },

packages/excalidraw/components/App.tsx

@@ -326,7 +326,10 @@ import {
   actionToggleCropEditor,
 } from "../actions";
 import { actionWrapTextInContainer } from "../actions/actionBoundText";
-import { actionToggleHandTool, zoomToFit } from "../actions/actionCanvas";
+import {
+  actionToggleHandTool,
+  resolveViewportForBounds,
+} from "../actions/actionCanvas";
 import { actionPaste } from "../actions/actionClipboard";
 import { actionCopyElementLink } from "../actions/actionElementLink";
 import { actionUnlockAllElements } from "../actions/actionElementLock";
@@ -370,7 +373,7 @@ import {
   hasBackground,
   isSomeElementSelected,
 } from "../scene";
-import { getStateForZoom } from "../scene/zoom";
+import { getConstrainedZoomAnchor, getStateForZoom } from "../scene/zoom";
 import {
   dataURLToString,
   generateIdFromFile,
@@ -426,6 +429,12 @@ import { isMaybeMermaidDefinition } from "../mermaid";
 
 import { LassoTrail } from "../lasso";
 
+import {
+  constrainScrollState,
+  calculateConstrainedScrollCenter,
+  areCanvasTranslatesClose,
+  getScrollConstraintsForBounds,
+} from "../scene/scrollConstraints";
 import { EraserTrail } from "../eraser";
 
 import { getShortcutKey } from "../shortcut";
@@ -488,6 +497,9 @@ import type {
   CollaboratorPointer,
   ToolType,
   OnUserFollowedPayload,
+  ScrollConstraints,
+  AnimateTranslateCanvasValues,
+  ScrollToContentOptions,
   UnsubscribeCallback,
   EmbedsValidationStatus,
   ElementsPendingErasure,
@@ -540,6 +552,7 @@ const ExcalidrawAppStateContext = React.createContext<AppState>({
   height: 0,
   offsetLeft: 0,
   offsetTop: 0,
+  scrollConstraints: null,
 });
 ExcalidrawAppStateContext.displayName = "ExcalidrawAppStateContext";
 
@@ -594,6 +607,20 @@ let isDraggingScrollBar: boolean = false;
 let currentScrollBars: ScrollBars = { horizontal: null, vertical: null };
 let touchTimeout = 0;
 let invalidateContextMenu = false;
+let scrollConstraintsAnimationTimeout: ReturnType<typeof setTimeout> | null =
+  null;
+
+const areScrollConstraintsEqual = (
+  left: ScrollConstraints | null | undefined,
+  right: ScrollConstraints | null | undefined,
+) => {
+  return left === right || (!!left && !!right && isShallowEqual(left, right));
+};
+
+const SET_SCROLL_CONSTRAINTS_CONTROLLED_WARNING =
+  "Excalidraw: `setScrollConstraints()` is ignored when the `scrollConstraints` prop is controlled.";
+const SCROLL_TO_CONTENT_SCROLL_LOCK_CONTROLLED_WARNING =
+  "Excalidraw: `scrollToContent()` with `scrollLock` is ignored when the `scrollConstraints` prop is controlled.";
 
 /**
  * Map of youtube embed video states
@@ -781,6 +808,8 @@ class App extends React.Component<AppProps, AppState> {
       onUserFollow: (cb) => this.onUserFollowEmitter.on(cb),
       onStateChange: this.onStateChange,
       onEvent: this.onEvent,
+      app: this,
+      setScrollConstraints: this.setScrollConstraints,
     };
     return api;
   }
@@ -795,6 +824,7 @@ class App extends React.Component<AppProps, AppState> {
       objectsSnapModeEnabled = false,
       theme = defaultAppState.theme,
       name = `${t("labels.untitled")}-${getDateTime()}`,
+      scrollConstraints,
     } = props;
 
     this.state = {
@@ -810,6 +840,7 @@ class App extends React.Component<AppProps, AppState> {
       name,
       width: window.innerWidth,
       height: window.innerHeight,
+      scrollConstraints: scrollConstraints ?? null,
     };
 
     this.refreshEditorInterface();
@@ -2945,7 +2976,13 @@ class App extends React.Component<AppProps, AppState> {
       toast: this.state.toast,
     };
 
-    if (initialData?.scrollToContent) {
+    if (this.props.scrollConstraints) {
+      restoredAppState = {
+        ...restoredAppState,
+        scrollConstraints: this.props.scrollConstraints,
+        ...calculateConstrainedScrollCenter(this.state, restoredAppState),
+      };
+    } else if (initialData?.scrollToContent) {
       restoredAppState = {
         ...restoredAppState,
         ...calculateScrollCenter(restoredElements, {
@@ -2954,10 +2991,18 @@ class App extends React.Component<AppProps, AppState> {
           height: this.state.height,
           offsetTop: this.state.offsetTop,
           offsetLeft: this.state.offsetLeft,
+          scrollConstraints: this.state.scrollConstraints,
         }),
       };
     }
 
+    if (initialData?.scrollX != null) {
+      restoredAppState.scrollX = initialData.scrollX;
+    }
+    if (initialData?.scrollY != null) {
+      restoredAppState.scrollY = initialData.scrollY;
+    }
+
     this.resetStore();
     this.resetHistory();
     this.syncActionResult({
@@ -3208,7 +3253,11 @@ class App extends React.Component<AppProps, AppState> {
       .forEach((element) => ShapeCache.delete(element));
     this.refreshEditorInterface();
     this.updateDOMRect();
-    this.setState({});
+    if (this.state.scrollConstraints) {
+      this.setState((state) => constrainScrollState(state));
+    } else {
+      this.setState({});
+    }
   });
 
   /** generally invoked only if fullscreen was invoked programmatically */
@@ -3458,6 +3507,15 @@ class App extends React.Component<AppProps, AppState> {
       this.setState({ viewModeEnabled: !!this.props.viewModeEnabled });
     }
 
+    if (
+      !areScrollConstraintsEqual(
+        prevProps.scrollConstraints,
+        this.props.scrollConstraints,
+      )
+    ) {
+      this.syncScrollConstraints(this.props.scrollConstraints ?? null);
+    }
+
     if (prevState.viewModeEnabled !== this.state.viewModeEnabled) {
       this.addEventListeners();
       this.deselectElements();
@@ -3518,6 +3576,33 @@ class App extends React.Component<AppProps, AppState> {
       this.props.onChange?.(elements, this.state, this.files);
       this.onChangeEmitter.trigger(elements, this.state, this.files);
     }
+
+    if (this.state.scrollConstraints?.animateOnNextUpdate) {
+      const newState = constrainScrollState(this.state, "rigid");
+      const fromValues = {
+        scrollX: this.state.scrollX,
+        scrollY: this.state.scrollY,
+        zoom: this.state.zoom.value,
+      };
+      const toValues = {
+        scrollX: newState.scrollX,
+        scrollY: newState.scrollY,
+        zoom: newState.zoom.value,
+      };
+
+      if (areCanvasTranslatesClose(fromValues, toValues)) {
+        return;
+      }
+
+      if (scrollConstraintsAnimationTimeout) {
+        clearTimeout(scrollConstraintsAnimationTimeout);
+      }
+
+      scrollConstraintsAnimationTimeout = setTimeout(() => {
+        this.cancelInProgressAnimation?.();
+        this.animateToConstrainedArea(fromValues, toValues);
+      }, 200);
+    }
   }
 
   private renderInteractiveSceneCallback = ({
@@ -4285,8 +4370,8 @@ class App extends React.Component<AppProps, AppState> {
      */
     value: number,
   ) => {
-    this.setState({
-      ...getStateForZoom(
+    this.setState(
+      getStateForZoom(
         {
           viewportX: this.state.width / 2 + this.state.offsetLeft,
           viewportY: this.state.height / 2 + this.state.offsetTop,
@@ -4294,11 +4379,13 @@ class App extends React.Component<AppProps, AppState> {
         },
         this.state,
       ),
-    });
+    );
   };
 
   private cancelInProgressAnimation: (() => void) | null = null;
 
+  private scrollToContentRequestId = 0;
+
   scrollToContent = (
     /**
      * target to scroll to
@@ -4310,30 +4397,13 @@ class App extends React.Component<AppProps, AppState> {
       | string
       | ExcalidrawElement
       | readonly ExcalidrawElement[] = this.scene.getNonDeletedElements(),
-    opts?: (
-      | {
-          fitToContent?: boolean;
-          fitToViewport?: never;
-          viewportZoomFactor?: number;
-          animate?: boolean;
-          duration?: number;
-        }
-      | {
-          fitToContent?: never;
-          fitToViewport?: boolean;
-          /** when fitToViewport=true, how much screen should the content cover,
-           * between 0.1 (10%) and 1 (100%)
-           */
-          viewportZoomFactor?: number;
-          animate?: boolean;
-          duration?: number;
-        }
-    ) & {
-      minZoom?: number;
-      maxZoom?: number;
-      canvasOffsets?: Offsets;
-    },
+    opts?: ScrollToContentOptions,
   ) => {
+    if (opts?.scrollLock && this.props.scrollConstraints !== undefined) {
+      console.warn(SCROLL_TO_CONTENT_SCROLL_LOCK_CONTROLLED_WARNING);
+      opts = { ...opts, scrollLock: undefined };
+    }
+
     if (typeof target === "string") {
       let id: string | null;
       if (isElementLink(target)) {
@@ -4345,10 +4415,29 @@ class App extends React.Component<AppProps, AppState> {
         const elements = this.scene.getElementsFromId(id);
 
         if (elements?.length) {
-          this.scrollToContent(elements, {
-            fitToContent: opts?.fitToContent ?? true,
-            animate: opts?.animate ?? true,
-          });
+          if (opts?.fitToViewport) {
+            this.scrollToContent(elements, {
+              fitToViewport: true,
+              viewportZoomFactor: opts.viewportZoomFactor,
+              animate: opts.animate ?? true,
+              duration: opts.duration,
+              scrollLock: opts.scrollLock,
+              minZoom: opts.minZoom,
+              maxZoom: opts.maxZoom,
+              canvasOffsets: opts.canvasOffsets,
+            });
+          } else {
+            this.scrollToContent(elements, {
+              fitToContent: opts?.fitToContent ?? true,
+              viewportZoomFactor: opts?.viewportZoomFactor,
+              animate: opts?.animate ?? true,
+              duration: opts?.duration,
+              scrollLock: opts?.scrollLock,
+              minZoom: opts?.minZoom,
+              maxZoom: opts?.maxZoom,
+              canvasOffsets: opts?.canvasOffsets,
+            });
+          }
         } else if (isElementLink(target)) {
           this.setState({
             toast: {
@@ -4363,27 +4452,45 @@ class App extends React.Component<AppProps, AppState> {
     }
 
     this.cancelInProgressAnimation?.();
+    this.scrollToContentRequestId += 1;
+    this.debounceConstrainScrollState.cancel();
+
+    if (scrollConstraintsAnimationTimeout) {
+      clearTimeout(scrollConstraintsAnimationTimeout);
+      scrollConstraintsAnimationTimeout = null;
+    }
+
+    if (opts?.scrollLock != null && this.state.scrollConstraints) {
+      // Clear the previous lock before starting the next locked transition so
+      // stale constraint enforcement cannot snap us back mid-flight.
+      this.setState({ scrollConstraints: null });
+    }
 
     // convert provided target into ExcalidrawElement[] if necessary
     const targetElements = Array.isArray(target) ? target : [target];
 
+    if (!targetElements.length) {
+      return;
+    }
+
     let zoom = this.state.zoom;
     let scrollX = this.state.scrollX;
     let scrollY = this.state.scrollY;
+    const targetBounds = getCommonBounds(targetElements);
 
     if (opts?.fitToContent || opts?.fitToViewport) {
-      const { appState } = zoomToFit({
+      const resolvedViewport = resolveViewportForBounds({
+        bounds: targetBounds,
         canvasOffsets: opts.canvasOffsets,
-        targetElements,
         appState: this.state,
         fitToViewport: !!opts?.fitToViewport,
         viewportZoomFactor: opts?.viewportZoomFactor,
         minZoom: opts?.minZoom,
         maxZoom: opts?.maxZoom,
       });
-      zoom = appState.zoom;
-      scrollX = appState.scrollX;
-      scrollY = appState.scrollY;
+      zoom = resolvedViewport.zoom;
+      scrollX = resolvedViewport.scrollX;
+      scrollY = resolvedViewport.scrollY;
     } else {
       // compute only the viewport location, without any zoom adjustment
       const scroll = calculateScrollCenter(targetElements, this.state);
@@ -4391,51 +4498,72 @@ class App extends React.Component<AppProps, AppState> {
       scrollY = scroll.scrollY;
     }
 
+    const scrollConstraints = opts?.scrollLock
+      ? getScrollConstraintsForBounds({
+          bounds: targetBounds,
+          zoom,
+          viewportDimensions: {
+            width: this.state.width,
+            height: this.state.height,
+          },
+          scrollLock: opts.scrollLock,
+        })
+      : null;
+    const requestId = this.scrollToContentRequestId;
+
+    const installScrollConstraints = () => {
+      if (!scrollConstraints || requestId !== this.scrollToContentRequestId) {
+        return;
+      }
+
+      this.setState({
+        scrollConstraints,
+      });
+    };
+
     // when animating, we use RequestAnimationFrame to prevent the animation
     // from slowing down other processes
     if (opts?.animate) {
-      const origScrollX = this.state.scrollX;
-      const origScrollY = this.state.scrollY;
-      const origZoom = this.state.zoom.value;
+      const fromValues = {
+        scrollX: this.state.scrollX,
+        scrollY: this.state.scrollY,
+        zoom: this.state.zoom.value,
+      };
 
-      const cancel = easeToValuesRAF({
-        fromValues: {
-          scrollX: origScrollX,
-          scrollY: origScrollY,
-          zoom: origZoom,
-        },
-        toValues: { scrollX, scrollY, zoom: zoom.value },
-        interpolateValue: (from, to, progress, key) => {
-          // for zoom, use different easing
-          if (key === "zoom") {
-            return from * Math.pow(to / from, easeOut(progress));
-          }
-          // handle using default
-          return undefined;
-        },
-        onStep: ({ scrollX, scrollY, zoom }) => {
-          this.setState({
-            scrollX,
-            scrollY,
-            zoom: { value: zoom },
-          });
-        },
+      const toValues = { scrollX, scrollY, zoom: zoom.value };
+
+      this.animateTranslateCanvas({
+        fromValues,
+        toValues,
+        duration: opts?.duration ?? 500,
         onStart: () => {
           this.setState({ shouldCacheIgnoreZoom: true });
         },
         onEnd: () => {
-          this.setState({ shouldCacheIgnoreZoom: false });
+          if (requestId !== this.scrollToContentRequestId) {
+            return;
+          }
+
+          this.setState(
+            { shouldCacheIgnoreZoom: false },
+            installScrollConstraints,
+          );
         },
         onCancel: () => {
+          if (requestId !== this.scrollToContentRequestId) {
+            return;
+          }
+
           this.setState({ shouldCacheIgnoreZoom: false });
         },
-        duration: opts?.duration ?? 500,
       });
-
-      this.cancelInProgressAnimation = () => {
-        cancel();
-        this.cancelInProgressAnimation = null;
-      };
+    } else if (scrollConstraints) {
+      this.setState({
+        scrollX,
+        scrollY,
+        zoom,
+        scrollConstraints,
+      });
     } else {
       this.setState({ scrollX, scrollY, zoom });
     }
@@ -4449,11 +4577,165 @@ class App extends React.Component<AppProps, AppState> {
 
   /** use when changing scrollX/scrollY/zoom based on user interaction */
   private translateCanvas: React.Component<any, AppState>["setState"] = (
-    state,
+    stateUpdate,
   ) => {
     this.cancelInProgressAnimation?.();
     this.maybeUnfollowRemoteUser();
-    this.setState(state);
+
+    if (scrollConstraintsAnimationTimeout) {
+      clearTimeout(scrollConstraintsAnimationTimeout);
+    }
+
+    const partialNewState =
+      typeof stateUpdate === "function"
+        ? (
+            stateUpdate as (
+              prevState: Readonly<AppState>,
+              props: Readonly<AppProps>,
+            ) => AppState
+          )(this.state, this.props)
+        : stateUpdate;
+
+    const newState: AppState = {
+      ...this.state,
+      ...partialNewState,
+      ...(this.state.scrollConstraints && {
+        // manually reset if setState in onCancel wasn't committed yet
+        shouldCacheIgnoreZoom: false,
+      }),
+    };
+
+    // RULE: cannot go below the minimum zoom level if zoom lock is enabled
+    const constrainedState =
+      newState.scrollConstraints && newState.scrollConstraints.lockZoom
+        ? constrainScrollState(newState, "elastic")
+        : newState;
+    if (constrainedState.zoom.value > newState.zoom.value) {
+      newState.zoom = constrainedState.zoom;
+      newState.scrollX = constrainedState.scrollX;
+      newState.scrollY = constrainedState.scrollY;
+
+      this.debounceConstrainScrollState(newState);
+      return;
+    }
+
+    this.setState(newState);
+    if (this.state.scrollConstraints) {
+      if (newState.zoom.value < this.state.zoom.value) {
+        // zoom-out: debounce to allow centering on user's cursor position before constraining
+        this.debounceConstrainScrollState(newState);
+      } else {
+        // zoom-in or pan: valid range only expands on zoom-in, constrain immediately
+        this.setState(constrainScrollState(newState));
+      }
+    }
+  };
+
+  private debounceConstrainScrollState = debounce((state: AppState) => {
+    const newState = constrainScrollState(state, "rigid");
+
+    const fromValues = {
+      scrollX: this.state.scrollX,
+      scrollY: this.state.scrollY,
+      zoom: this.state.zoom.value,
+    };
+    const toValues = {
+      scrollX: newState.scrollX,
+      scrollY: newState.scrollY,
+      zoom: newState.zoom.value,
+    };
+
+    if (areCanvasTranslatesClose(fromValues, toValues)) {
+      return;
+    }
+
+    this.cancelInProgressAnimation?.();
+    this.animateToConstrainedArea(fromValues, toValues);
+  }, 200);
+
+  private animateToConstrainedArea = (
+    fromValues: AnimateTranslateCanvasValues,
+    toValues: AnimateTranslateCanvasValues,
+  ) => {
+    const cleanUp = () => {
+      this.setState((state) => ({
+        shouldCacheIgnoreZoom: false,
+        scrollConstraints: {
+          ...state.scrollConstraints!,
+          animateOnNextUpdate: false,
+        },
+      }));
+    };
+
+    this.animateTranslateCanvas({
+      fromValues,
+      toValues,
+      duration: 200,
+      onStart: () => {
+        this.setState((state) => {
+          return {
+            shouldCacheIgnoreZoom: true,
+            scrollConstraints: {
+              ...state.scrollConstraints!,
+              animateOnNextUpdate: false,
+            },
+          };
+        });
+      },
+      onEnd: cleanUp,
+      onCancel: cleanUp,
+    });
+  };
+
+  private animateTranslateCanvas = ({
+    fromValues,
+    toValues,
+    duration,
+    onStart,
+    onEnd,
+    onCancel,
+  }: {
+    fromValues: AnimateTranslateCanvasValues;
+    toValues: AnimateTranslateCanvasValues;
+    duration: number;
+    onStart: () => void;
+    onEnd: () => void;
+    onCancel: () => void;
+  }) => {
+    const cancel = easeToValuesRAF({
+      fromValues,
+      toValues,
+      interpolateValue: (from, to, progress, key) => {
+        // for zoom, use different easing
+        if (key === "zoom") {
+          return from * Math.pow(to / from, easeOut(progress));
+        }
+        // handle using default
+        return undefined;
+      },
+      onStep: ({ scrollX, scrollY, zoom }) => {
+        this.setState({
+          scrollX,
+          scrollY,
+          zoom: { value: zoom },
+        });
+      },
+      onStart,
+      onEnd: () => {
+        this.cancelInProgressAnimation = null;
+        onEnd();
+      },
+      onCancel: () => {
+        this.cancelInProgressAnimation = null;
+        onCancel();
+      },
+      duration,
+    });
+
+    this.cancelInProgressAnimation = () => {
+      cancel();
+      this.cancelInProgressAnimation = null;
+    };
   };
 
   setToast = (toast: AppState["toast"]) => {
@@ -5634,16 +5916,22 @@ class App extends React.Component<AppProps, AppState> {
 
     const initialScale = gesture.initialScale;
     if (initialScale) {
-      this.setState((state) => ({
-        ...getStateForZoom(
+      this.setState((state) =>
+        constrainScrollState(
           {
-            viewportX: this.lastViewportPosition.x,
-            viewportY: this.lastViewportPosition.y,
-            nextZoom: getNormalizedZoom(initialScale * event.scale),
+            ...state,
+            ...getStateForZoom(
+              {
+                viewportX: this.lastViewportPosition.x,
+                viewportY: this.lastViewportPosition.y,
+                nextZoom: getNormalizedZoom(initialScale * event.scale),
+              },
+              state,
+            ),
           },
-          state,
+          "loose",
         ),
-      }));
+      );
     }
   });
 
@@ -12620,17 +12908,21 @@ class App extends React.Component<AppProps, AppState> {
           // reduced amplification for small deltas (small movements on a trackpad)
           Math.min(1, absDelta / 20);
 
-        this.translateCanvas((state) => ({
-          ...getStateForZoom(
+        this.translateCanvas((state) => {
+          const nextZoom = getNormalizedZoom(newZoom);
+          const anchor = getConstrainedZoomAnchor(
             {
               viewportX: this.lastViewportPosition.x,
               viewportY: this.lastViewportPosition.y,
-              nextZoom: getNormalizedZoom(newZoom),
+              nextZoom,
             },
             state,
-          ),
-          shouldCacheIgnoreZoom: true,
-        }));
+          );
+          return {
+            ...getStateForZoom({ ...anchor, nextZoom }, state),
+            shouldCacheIgnoreZoom: true,
+          };
+        });
         this.resetShouldCacheIgnoreZoomDebounced();
         return;
       }
@@ -12788,6 +13080,71 @@ class App extends React.Component<AppProps, AppState> {
     await setLanguage(currentLang);
     this.setAppState({});
   }
+
+  /**
+   * Sets the scroll constraints of the application state.
+   *
+   * @param scrollConstraints - The new scroll constraints.
+   */
+  public setScrollConstraints = (
+    scrollConstraints: ScrollConstraints | null,
+  ) => {
+    if (this.props.scrollConstraints !== undefined) {
+      console.warn(SET_SCROLL_CONSTRAINTS_CONTROLLED_WARNING);
+      return;
+    }
+
+    this.syncScrollConstraints(scrollConstraints);
+  };
+
+  private syncScrollConstraints = (
+    scrollConstraints: ScrollConstraints | null,
+  ) => {
+    this.debounceConstrainScrollState.cancel();
+
+    if (scrollConstraintsAnimationTimeout) {
+      clearTimeout(scrollConstraintsAnimationTimeout);
+      scrollConstraintsAnimationTimeout = null;
+    }
+
+    this.cancelInProgressAnimation?.();
+
+    if (scrollConstraints) {
+      this.setState(
+        {
+          scrollConstraints,
+          shouldCacheIgnoreZoom: false,
+        },
+        () => {
+          const newState = constrainScrollState(
+            {
+              ...this.state,
+              scrollConstraints,
+            },
+            "rigid",
+          );
+
+          this.animateToConstrainedArea(
+            {
+              scrollX: this.state.scrollX,
+              scrollY: this.state.scrollY,
+              zoom: this.state.zoom.value,
+            },
+            {
+              scrollX: newState.scrollX,
+              scrollY: newState.scrollY,
+              zoom: newState.zoom.value,
+            },
+          );
+        },
+      );
+    } else {
+      this.setState({
+        scrollConstraints: null,
+        shouldCacheIgnoreZoom: false,
+      });
+    }
+  };
 }
 
 // -----------------------------------------------------------------------------

packages/excalidraw/index.tsx

@@ -98,6 +98,7 @@ const ExcalidrawBase = (props: ExcalidrawProps) => {
     aiEnabled,
     showDeprecatedFonts,
     renderScrollbars,
+    scrollConstraints,
   } = props;
 
   const canvasActions = props.UIOptions?.canvasActions;
@@ -208,6 +209,7 @@ const ExcalidrawBase = (props: ExcalidrawProps) => {
           aiEnabled={aiEnabled !== false}
           showDeprecatedFonts={showDeprecatedFonts}
           renderScrollbars={renderScrollbars}
+          scrollConstraints={scrollConstraints}
         >
           {children}
         </App>

packages/excalidraw/scene/scrollConstraints.ts

@@ -0,0 +1,590 @@
+import { MAX_ZOOM } from "@excalidraw/common";
+
+import { isShallowEqual } from "@excalidraw/common";
+
+import { clamp } from "@excalidraw/math";
+
+import { getNormalizedZoom } from "./normalize";
+
+import type {
+  AnimateTranslateCanvasValues,
+  AppState,
+  ScrollConstraints,
+  ScrollToContentLockOptions,
+} from "../types";
+
+// Constants for viewport zoom factor and overscroll allowance
+const MIN_VIEWPORT_ZOOM_FACTOR = 0.1;
+const MAX_VIEWPORT_ZOOM_FACTOR = MAX_ZOOM;
+const DEFAULT_VIEWPORT_ZOOM_FACTOR = 0.2;
+const DEFAULT_OVERSCROLL_ALLOWANCE = 0.2;
+
+// Memoization variable to cache constraints for performance optimization
+let memoizedValues: {
+  previousState: Pick<
+    AppState,
+    "zoom" | "width" | "height" | "scrollConstraints"
+  >;
+  constraints: ReturnType<typeof calculateConstraints>;
+  allowOverscroll: boolean;
+} | null = null;
+
+type CanvasTranslate = Pick<AppState, "scrollX" | "scrollY" | "zoom">;
+
+export const getScrollConstraintsForBounds = ({
+  bounds,
+  zoom,
+  viewportDimensions,
+  scrollLock,
+}: {
+  bounds: readonly [number, number, number, number];
+  zoom: AppState["zoom"];
+  viewportDimensions: Pick<AppState, "width" | "height">;
+  scrollLock?: boolean | ScrollToContentLockOptions;
+}): ScrollConstraints => {
+  const [x1, y1, x2, y2] = bounds;
+  const width = x2 - x1;
+  const height = y2 - y1;
+  const baseZoom = Math.min(
+    viewportDimensions.width / width,
+    viewportDimensions.height / height,
+  );
+  const lockOptions =
+    scrollLock && typeof scrollLock === "object" ? scrollLock : undefined;
+  const viewportZoomFactor =
+    lockOptions?.viewportZoomFactor ?? zoom.value / baseZoom;
+
+  return {
+    x: x1,
+    y: y1,
+    width,
+    height,
+    animateOnNextUpdate: false,
+    lockZoom: !!lockOptions?.lockZoom,
+    overscrollAllowance: lockOptions?.overscrollAllowance,
+    viewportZoomFactor,
+  };
+};
+
+/**
+ * Calculates the zoom levels necessary to fit the constrained scrollable area within the viewport on the X and Y axes.
+ *
+ * The function considers the dimensions of the scrollable area, the dimensions of the viewport, the viewport zoom factor,
+ * and whether the zoom should be locked. It then calculates the necessary zoom levels for the X and Y axes separately.
+ * If the zoom should be locked, it calculates the maximum zoom level that fits the scrollable area within the viewport,
+ * factoring in the viewport zoom factor. If the zoom should not be locked, the maximum zoom level is set to null.
+ *
+ * @param scrollConstraints - The constraints of the scrollable area including width, height, and position.
+ * @param width - The width of the viewport.
+ * @param height - The height of the viewport.
+ * @returns An object containing the calculated zoom levels for the X and Y axes, and the initial zoom level.
+ */
+const calculateZoomLevel = (
+  scrollConstraints: ScrollConstraints,
+  width: AppState["width"],
+  height: AppState["height"],
+) => {
+  const viewportZoomFactor = scrollConstraints.viewportZoomFactor
+    ? clamp(
+        scrollConstraints.viewportZoomFactor,
+        MIN_VIEWPORT_ZOOM_FACTOR,
+        MAX_VIEWPORT_ZOOM_FACTOR,
+      )
+    : DEFAULT_VIEWPORT_ZOOM_FACTOR;
+
+  const scrollableWidth = scrollConstraints.width;
+  const scrollableHeight = scrollConstraints.height;
+  const zoomLevelX = width / scrollableWidth;
+  const zoomLevelY = height / scrollableHeight;
+  const initialZoomLevel = getNormalizedZoom(
+    Math.min(zoomLevelX, zoomLevelY) * viewportZoomFactor,
+  );
+  return { zoomLevelX, zoomLevelY, initialZoomLevel };
+};
+
+/**
+ * Calculates the effective zoom level based on the scroll constraints and current zoom.
+ *
+ * @param params - Object containing scrollConstraints, width, height, and zoom.
+ * @returns An object with the effective zoom level, initial zoom level, and zoom levels for X and Y axes.
+ */
+const calculateZoom = ({
+  scrollConstraints,
+  width,
+  height,
+  zoom,
+}: {
+  scrollConstraints: ScrollConstraints;
+  width: AppState["width"];
+  height: AppState["height"];
+  zoom: AppState["zoom"];
+}) => {
+  const { zoomLevelX, zoomLevelY, initialZoomLevel } = calculateZoomLevel(
+    scrollConstraints,
+    width,
+    height,
+  );
+  const effectiveZoom = scrollConstraints.lockZoom
+    ? Math.max(initialZoomLevel, zoom.value)
+    : zoom.value;
+  return {
+    effectiveZoom: getNormalizedZoom(effectiveZoom),
+    initialZoomLevel,
+    zoomLevelX,
+    zoomLevelY,
+  };
+};
+
+/**
+ * Calculates the scroll bounds (min and max scroll values) based on the scroll constraints and zoom level.
+ *
+ * @param params - Object containing scrollConstraints, width, height, effectiveZoom, zoomLevelX, zoomLevelY, and allowOverscroll.
+ * @returns An object with min and max scroll values for X and Y axes.
+ */
+const calculateScrollBounds = ({
+  scrollConstraints,
+  width,
+  height,
+  effectiveZoom,
+  zoomLevelX,
+  zoomLevelY,
+  allowOverscroll,
+}: {
+  scrollConstraints: ScrollConstraints;
+  width: AppState["width"];
+  height: AppState["height"];
+  effectiveZoom: number;
+  zoomLevelX: number;
+  zoomLevelY: number;
+  allowOverscroll: boolean;
+}) => {
+  const overscrollAllowance =
+    scrollConstraints.overscrollAllowance ?? DEFAULT_OVERSCROLL_ALLOWANCE;
+  const validatedOverscroll = clamp(overscrollAllowance, 0, 1);
+
+  const calculateCenter = (zoom: number) => {
+    const centerX =
+      scrollConstraints.x + (scrollConstraints.width - width / zoom) / -2;
+    const centerY =
+      scrollConstraints.y + (scrollConstraints.height - height / zoom) / -2;
+    return { centerX, centerY };
+  };
+
+  const { centerX, centerY } = calculateCenter(effectiveZoom);
+
+  const overscrollValue = Math.min(
+    validatedOverscroll * scrollConstraints.width,
+    validatedOverscroll * scrollConstraints.height,
+  );
+
+  const fitsX = effectiveZoom <= zoomLevelX;
+  const fitsY = effectiveZoom <= zoomLevelY;
+
+  const getScrollRange = (
+    axis: "x" | "y",
+    fits: boolean,
+    constraint: ScrollConstraints,
+    viewportSize: number,
+    zoom: number,
+    overscroll: number,
+  ) => {
+    const { pos, size } =
+      axis === "x"
+        ? { pos: constraint.x, size: constraint.width }
+        : { pos: constraint.y, size: constraint.height };
+    const center = axis === "x" ? centerX : centerY;
+    if (allowOverscroll) {
+      return fits
+        ? { min: center - overscroll, max: center + overscroll }
+        : {
+            min: pos - size + viewportSize / zoom - overscroll,
+            max: pos + overscroll,
+          };
+    }
+    return fits
+      ? { min: center, max: center }
+      : { min: pos - size + viewportSize / zoom, max: pos };
+  };
+
+  const xRange = getScrollRange(
+    "x",
+    fitsX,
+    scrollConstraints,
+    width,
+    effectiveZoom,
+    overscrollValue,
+  );
+  const yRange = getScrollRange(
+    "y",
+    fitsY,
+    scrollConstraints,
+    height,
+    effectiveZoom,
+    overscrollValue,
+  );
+
+  return {
+    minScrollX: xRange.min,
+    maxScrollX: xRange.max,
+    minScrollY: yRange.min,
+    maxScrollY: yRange.max,
+  };
+};
+
+/**
+ * Calculates the scroll constraints including min and max scroll values and the effective zoom level.
+ *
+ * @param params - Object containing scrollConstraints, width, height, zoom, and allowOverscroll.
+ * @returns An object with min and max scroll values, effective zoom, and initial zoom level.
+ */
+const calculateConstraints = ({
+  scrollConstraints,
+  width,
+  height,
+  zoom,
+  allowOverscroll,
+}: {
+  scrollConstraints: ScrollConstraints;
+  width: AppState["width"];
+  height: AppState["height"];
+  zoom: AppState["zoom"];
+  allowOverscroll: boolean;
+}) => {
+  const { effectiveZoom, initialZoomLevel, zoomLevelX, zoomLevelY } =
+    calculateZoom({ scrollConstraints, width, height, zoom });
+  const scrollBounds = calculateScrollBounds({
+    scrollConstraints,
+    width,
+    height,
+    effectiveZoom,
+    zoomLevelX,
+    zoomLevelY,
+    allowOverscroll,
+  });
+
+  return {
+    ...scrollBounds,
+    effectiveZoom: { value: effectiveZoom },
+    initialZoomLevel,
+  };
+};
+
+/**
+ * Constrains the scroll values within the provided min and max bounds.
+ *
+ * @param params - Object containing scrollX, scrollY, minScrollX, maxScrollX, minScrollY, maxScrollY, and constrainedZoom.
+ * @returns An object with constrained scrollX, scrollY, and zoom.
+ */
+const constrainScrollValues = ({
+  scrollX,
+  scrollY,
+  minScrollX,
+  maxScrollX,
+  minScrollY,
+  maxScrollY,
+  constrainedZoom,
+}: {
+  scrollX: number;
+  scrollY: number;
+  minScrollX: number;
+  maxScrollX: number;
+  minScrollY: number;
+  maxScrollY: number;
+  constrainedZoom: AppState["zoom"];
+}): CanvasTranslate => {
+  const constrainedScrollX = clamp(scrollX, minScrollX, maxScrollX);
+  const constrainedScrollY = clamp(scrollY, minScrollY, maxScrollY);
+  return {
+    scrollX: constrainedScrollX,
+    scrollY: constrainedScrollY,
+    zoom: constrainedZoom,
+  };
+};
+
+/**
+ * Inverts the scroll constraints to align with the state scrollX and scrollY values, which are inverted.
+ * This is a temporary fix and should be removed once issue #5965 is resolved.
+ *
+ * @param originalScrollConstraints - The original scroll constraints.
+ * @returns The aligned scroll constraints with inverted x and y coordinates.
+ */
+const alignScrollConstraints = (
+  originalScrollConstraints: ScrollConstraints,
+): ScrollConstraints => {
+  return {
+    ...originalScrollConstraints,
+    x: originalScrollConstraints.x * -1,
+    y: originalScrollConstraints.y * -1,
+  };
+};
+
+/**
+ * Determines whether the current viewport is outside the constrained area.
+ *
+ * @param state - The application state.
+ * @returns True if the viewport is outside the constrained area, false otherwise.
+ */
+const isViewportOutsideOfConstrainedArea = (state: AppState): boolean => {
+  if (!state.scrollConstraints) {
+    return false;
+  }
+
+  const {
+    scrollX,
+    scrollY,
+    width,
+    height,
+    scrollConstraints: inverseScrollConstraints,
+    zoom,
+  } = state;
+
+  const scrollConstraints = alignScrollConstraints(inverseScrollConstraints);
+
+  const adjustedWidth = width / zoom.value;
+  const adjustedHeight = height / zoom.value;
+
+  return (
+    scrollX > scrollConstraints.x ||
+    scrollX - adjustedWidth < scrollConstraints.x - scrollConstraints.width ||
+    scrollY > scrollConstraints.y ||
+    scrollY - adjustedHeight < scrollConstraints.y - scrollConstraints.height
+  );
+};
+
+/**
+ * Calculates the scroll center coordinates and the optimal zoom level to fit the constrained scrollable area within the viewport.
+ *
+ * @param state - The application state.
+ * @param scroll - Object containing current scrollX and scrollY.
+ * @returns An object with the calculated scrollX, scrollY, and zoom.
+ */
+export const calculateConstrainedScrollCenter = (
+  state: AppState,
+  { scrollX, scrollY }: Pick<AppState, "scrollX" | "scrollY">,
+): CanvasTranslate => {
+  const { width, height, scrollConstraints } = state;
+  if (!scrollConstraints) {
+    return { scrollX, scrollY, zoom: state.zoom };
+  }
+
+  const adjustedConstraints = alignScrollConstraints(scrollConstraints);
+  const zoomLevels = calculateZoomLevel(adjustedConstraints, width, height);
+  const initialZoom = { value: zoomLevels.initialZoomLevel };
+  const constraints = calculateConstraints({
+    scrollConstraints: adjustedConstraints,
+    width,
+    height,
+    zoom: initialZoom,
+    allowOverscroll: false,
+  });
+
+  return {
+    scrollX: constraints.minScrollX,
+    scrollY: constraints.minScrollY,
+    zoom: constraints.effectiveZoom,
+  };
+};
+
+/**
+ * Encodes scroll constraints into a compact string.
+ *
+ * @param constraints - The scroll constraints to encode.
+ * @returns A compact encoded string representing the scroll constraints.
+ */
+export const encodeConstraints = (constraints: ScrollConstraints): string => {
+  const payload = {
+    x: constraints.x,
+    y: constraints.y,
+    w: constraints.width,
+    h: constraints.height,
+    a: !!constraints.animateOnNextUpdate,
+    l: !!constraints.lockZoom,
+    v: constraints.viewportZoomFactor ?? 1,
+    oa: constraints.overscrollAllowance ?? DEFAULT_OVERSCROLL_ALLOWANCE,
+  };
+  const serialized = JSON.stringify(payload);
+  return encodeURIComponent(window.btoa(serialized).replace(/=+/, ""));
+};
+
+/**
+ * Decodes a compact string back into scroll constraints.
+ *
+ * @param encoded - The encoded string representing the scroll constraints.
+ * @returns The decoded scroll constraints object.
+ */
+export const decodeConstraints = (encoded: string): ScrollConstraints => {
+  try {
+    const decodedStr = window.atob(decodeURIComponent(encoded));
+    const parsed = JSON.parse(decodedStr) as {
+      x: number;
+      y: number;
+      w: number;
+      h: number;
+      a: boolean;
+      l: boolean;
+      v: number;
+      oa: number;
+    };
+    return {
+      x: parsed.x || 0,
+      y: parsed.y || 0,
+      width: parsed.w || 0,
+      height: parsed.h || 0,
+      lockZoom: parsed.l || false,
+      viewportZoomFactor: parsed.v || 1,
+      animateOnNextUpdate: parsed.a || false,
+      overscrollAllowance: parsed.oa || DEFAULT_OVERSCROLL_ALLOWANCE,
+    };
+  } catch (error) {
+    return {
+      x: 0,
+      y: 0,
+      width: 0,
+      height: 0,
+      animateOnNextUpdate: false,
+      lockZoom: false,
+      viewportZoomFactor: 1,
+      overscrollAllowance: DEFAULT_OVERSCROLL_ALLOWANCE,
+    };
+  }
+};
+
+type Options = { allowOverscroll: boolean; disableAnimation: boolean };
+const DEFAULT_OPTION: Options = {
+  allowOverscroll: true,
+  disableAnimation: false,
+};
+
+/**
+ * Constrains the AppState scroll values within the defined scroll constraints.
+ *
+ * constraintMode can be "elastic", "rigid", or "loose":
+ * - "elastic": snaps to constraints but allows overscroll
+ * - "rigid": snaps to constraints without overscroll
+ * - "loose": allows overscroll and disables animation/snapping to constraints
+ *
+ * @param state - The original AppState.
+ * @param options - Options for allowing overscroll and disabling animation.
+ * @returns A new AppState object with constrained scroll values.
+ */
+export const constrainScrollState = (
+  state: AppState,
+  constraintMode: "elastic" | "rigid" | "loose" = "elastic",
+): AppState => {
+  if (!state.scrollConstraints) {
+    return state;
+  }
+  const {
+    scrollX,
+    scrollY,
+    width,
+    height,
+    scrollConstraints: inverseScrollConstraints,
+    zoom,
+  } = state;
+
+  let allowOverscroll: boolean;
+  let disableAnimation: boolean;
+
+  switch (constraintMode) {
+    case "elastic":
+      ({ allowOverscroll, disableAnimation } = DEFAULT_OPTION);
+      break;
+    case "rigid":
+      allowOverscroll = false;
+      disableAnimation = false;
+      break;
+    case "loose":
+      allowOverscroll = true;
+      disableAnimation = true;
+      break;
+    default:
+      ({ allowOverscroll, disableAnimation } = DEFAULT_OPTION);
+      break;
+  }
+
+  const scrollConstraints = alignScrollConstraints(inverseScrollConstraints);
+
+  const canUseMemoizedValues =
+    memoizedValues &&
+    memoizedValues.previousState.scrollConstraints &&
+    memoizedValues.allowOverscroll === allowOverscroll &&
+    isShallowEqual(
+      state.scrollConstraints,
+      memoizedValues.previousState.scrollConstraints,
+    ) &&
+    isShallowEqual(
+      { zoom: zoom.value, width, height },
+      {
+        zoom: memoizedValues.previousState.zoom.value,
+        width: memoizedValues.previousState.width,
+        height: memoizedValues.previousState.height,
+      },
+    );
+
+  const constraints = canUseMemoizedValues
+    ? memoizedValues!.constraints
+    : calculateConstraints({
+        scrollConstraints,
+        width,
+        height,
+        zoom,
+        allowOverscroll,
+      });
+
+  if (!canUseMemoizedValues) {
+    memoizedValues = {
+      previousState: {
+        zoom: state.zoom,
+        width: state.width,
+        height: state.height,
+        scrollConstraints: state.scrollConstraints,
+      },
+      constraints,
+      allowOverscroll,
+    };
+  }
+
+  const constrainedValues =
+    zoom.value >= constraints.effectiveZoom.value
+      ? constrainScrollValues({
+          scrollX,
+          scrollY,
+          minScrollX: constraints.minScrollX,
+          maxScrollX: constraints.maxScrollX,
+          minScrollY: constraints.minScrollY,
+          maxScrollY: constraints.maxScrollY,
+          constrainedZoom: constraints.effectiveZoom,
+        })
+      : calculateConstrainedScrollCenter(state, { scrollX, scrollY });
+
+  return {
+    ...state,
+    scrollConstraints: {
+      ...state.scrollConstraints,
+      animateOnNextUpdate: disableAnimation
+        ? false
+        : isViewportOutsideOfConstrainedArea(state),
+    },
+    ...constrainedValues,
+  };
+};
+
+/**
+ * Checks if two canvas translate values are close within a threshold.
+ *
+ * @param from - First set of canvas translate values.
+ * @param to - Second set of canvas translate values.
+ * @returns True if the values are close, false otherwise.
+ */
+export const areCanvasTranslatesClose = (
+  from: AnimateTranslateCanvasValues,
+  to: AnimateTranslateCanvasValues,
+): boolean => {
+  const threshold = 0.1;
+  return (
+    Math.abs(from.scrollX - to.scrollX) < threshold &&
+    Math.abs(from.scrollY - to.scrollY) < threshold &&
+    Math.abs(from.zoom - to.zoom) < threshold
+  );
+};

packages/excalidraw/scene/zoom.ts

@@ -1,5 +1,67 @@
+import { constrainScrollState } from "./scrollConstraints";
+
 import type { AppState, NormalizedZoomValue } from "../types";
 
+/**
+ * When zooming out with scroll constraints active, the cursor-anchored zoom may
+ * produce a scroll position outside the valid bounds, causing a snap-back.
+ *
+ * This function adjusts the effective zoom anchor point so the resulting scroll
+ * stays within bounds — silently, without any snap. When no adjustment is needed
+ * (zoom-in, no constraints, or already within bounds) it returns the original
+ * viewport position unchanged.
+ */
+export const getConstrainedZoomAnchor = (
+  {
+    viewportX,
+    viewportY,
+    nextZoom,
+  }: { viewportX: number; viewportY: number; nextZoom: NormalizedZoomValue },
+  state: AppState,
+): { viewportX: number; viewportY: number } => {
+  if (!state.scrollConstraints || nextZoom >= state.zoom.value) {
+    return { viewportX, viewportY };
+  }
+
+  const appLayerX = viewportX - state.offsetLeft;
+  const appLayerY = viewportY - state.offsetTop;
+  const factor = 1 / nextZoom - 1 / state.zoom.value;
+
+  const newScrollX = state.scrollX + appLayerX * factor;
+  const newScrollY = state.scrollY + appLayerY * factor;
+
+  const constrained = constrainScrollState(
+    {
+      ...state,
+      scrollX: newScrollX,
+      scrollY: newScrollY,
+      zoom: { value: nextZoom },
+    },
+    "rigid",
+  );
+
+  if (
+    constrained.scrollX === newScrollX &&
+    constrained.scrollY === newScrollY
+  ) {
+    return { viewportX, viewportY };
+  }
+
+  const adjustedAppLayerX =
+    constrained.scrollX !== newScrollX
+      ? (constrained.scrollX - state.scrollX) / factor
+      : appLayerX;
+  const adjustedAppLayerY =
+    constrained.scrollY !== newScrollY
+      ? (constrained.scrollY - state.scrollY) / factor
+      : appLayerY;
+
+  return {
+    viewportX: adjustedAppLayerX + state.offsetLeft,
+    viewportY: adjustedAppLayerY + state.offsetTop,
+  };
+};
+
 export const getStateForZoom = (
   {
     viewportX,

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

@@ -961,6 +961,7 @@ exports[`contextMenu element > right-clicking on a group should select whole gro
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -1158,6 +1159,7 @@ exports[`contextMenu element > selecting 'Add to library' in context menu adds e
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": true,
@@ -1373,6 +1375,7 @@ exports[`contextMenu element > selecting 'Bring forward' in context menu brings
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -1705,6 +1708,7 @@ exports[`contextMenu element > selecting 'Bring to front' in context menu brings
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -2037,6 +2041,7 @@ exports[`contextMenu element > selecting 'Copy styles' in context menu copies st
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": true,
@@ -2252,6 +2257,7 @@ exports[`contextMenu element > selecting 'Delete' in context menu deletes elemen
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -2494,6 +2500,7 @@ exports[`contextMenu element > selecting 'Duplicate' in context menu duplicates
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -2795,6 +2802,7 @@ exports[`contextMenu element > selecting 'Group selection' in context menu group
     "id3": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -3166,6 +3174,7 @@ exports[`contextMenu element > selecting 'Paste styles' in context menu pastes s
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -3660,6 +3669,7 @@ exports[`contextMenu element > selecting 'Send backward' in context menu sends e
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -3984,6 +3994,7 @@ exports[`contextMenu element > selecting 'Send to back' in context menu sends el
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -4310,6 +4321,7 @@ exports[`contextMenu element > selecting 'Ungroup selection' in context menu ung
     "id3": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -5596,6 +5608,7 @@ exports[`contextMenu element > shows 'Group selection' in context menu for multi
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -6814,6 +6827,7 @@ exports[`contextMenu element > shows 'Ungroup selection' in context menu for gro
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -7773,6 +7787,7 @@ exports[`contextMenu element > shows context menu for canvas > [end of test] app
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -8771,6 +8786,7 @@ exports[`contextMenu element > shows context menu for element > [end of test] ap
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": true,
@@ -9766,6 +9782,7 @@ exports[`contextMenu element > shows context menu for element > [end of test] ap
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,

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

@@ -85,6 +85,7 @@ exports[`history > multiplayer undo/redo > conflicts in arrows and their bindabl
     "id4": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -719,6 +720,7 @@ exports[`history > multiplayer undo/redo > conflicts in arrows and their bindabl
     "id4": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -1282,6 +1284,7 @@ exports[`history > multiplayer undo/redo > conflicts in arrows and their bindabl
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -1643,6 +1646,7 @@ exports[`history > multiplayer undo/redo > conflicts in arrows and their bindabl
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -2006,6 +2010,7 @@ exports[`history > multiplayer undo/redo > conflicts in arrows and their bindabl
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -2267,6 +2272,7 @@ exports[`history > multiplayer undo/redo > conflicts in arrows and their bindabl
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -2724,6 +2730,7 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -3028,6 +3035,7 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -3348,6 +3356,7 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -3643,6 +3652,7 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -3930,6 +3940,7 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -4166,6 +4177,7 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -4424,6 +4436,7 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -4696,6 +4709,7 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -4926,6 +4940,7 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -5156,6 +5171,7 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -5404,6 +5420,7 @@ exports[`history > multiplayer undo/redo > conflicts in bound text elements and
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -5661,6 +5678,7 @@ exports[`history > multiplayer undo/redo > conflicts in frames and their childre
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -5919,6 +5937,7 @@ exports[`history > multiplayer undo/redo > should iterate through the history wh
     "id1": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -6249,6 +6268,7 @@ exports[`history > multiplayer undo/redo > should iterate through the history wh
     "id8": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -6677,6 +6697,7 @@ exports[`history > multiplayer undo/redo > should iterate through the history wh
     "id1": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -7053,6 +7074,7 @@ exports[`history > multiplayer undo/redo > should iterate through the history wh
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -7363,6 +7385,7 @@ exports[`history > multiplayer undo/redo > should iterate through the history wh
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -7656,6 +7679,7 @@ exports[`history > multiplayer undo/redo > should iterate through the history wh
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -7887,6 +7911,7 @@ exports[`history > multiplayer undo/redo > should iterate through the history wh
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -8240,6 +8265,7 @@ exports[`history > multiplayer undo/redo > should iterate through the history wh
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -8596,6 +8622,7 @@ exports[`history > multiplayer undo/redo > should not let remote changes to inte
     "id3": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -9000,6 +9027,7 @@ exports[`history > multiplayer undo/redo > should not let remote changes to inte
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -9280,6 +9308,7 @@ exports[`history > multiplayer undo/redo > should not let remote changes to inte
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -9545,6 +9574,7 @@ exports[`history > multiplayer undo/redo > should not override remote changes on
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -9811,6 +9841,7 @@ exports[`history > multiplayer undo/redo > should not override remote changes on
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -10047,6 +10078,7 @@ exports[`history > multiplayer undo/redo > should override remotely added groups
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -10342,6 +10374,7 @@ exports[`history > multiplayer undo/redo > should override remotely added points
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -10660,6 +10693,7 @@ exports[`history > multiplayer undo/redo > should redistribute deltas when eleme
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -10900,6 +10934,7 @@ exports[`history > multiplayer undo/redo > should redraw arrows on undo > [end o
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -11823,6 +11858,7 @@ exports[`history > multiplayer undo/redo > should update history entries after r
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -12084,6 +12120,7 @@ exports[`history > singleplayer undo/redo > remounting undo/redo buttons should
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -12320,6 +12357,7 @@ exports[`history > singleplayer undo/redo > should clear the redo stack on eleme
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -12558,6 +12596,7 @@ exports[`history > singleplayer undo/redo > should create entry when selecting f
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -12953,6 +12992,7 @@ exports[`history > singleplayer undo/redo > should create new history entry on e
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -13161,6 +13201,7 @@ exports[`history > singleplayer undo/redo > should create new history entry on e
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -13372,6 +13413,7 @@ exports[`history > singleplayer undo/redo > should create new history entry on i
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -13671,6 +13713,7 @@ exports[`history > singleplayer undo/redo > should create new history entry on i
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -13973,6 +14016,7 @@ exports[`history > singleplayer undo/redo > should create new history entry on s
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": -50,
   "scrollY": -50,
   "searchMatches": null,
@@ -14216,6 +14260,7 @@ exports[`history > singleplayer undo/redo > should disable undo/redo buttons whe
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -14454,6 +14499,7 @@ exports[`history > singleplayer undo/redo > should end up with no history entry
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -14694,6 +14740,7 @@ exports[`history > singleplayer undo/redo > should iterate through the history w
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -14940,6 +14987,7 @@ exports[`history > singleplayer undo/redo > should not clear the redo stack on s
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -15275,6 +15323,7 @@ exports[`history > singleplayer undo/redo > should not collapse when applying co
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -15443,6 +15492,7 @@ exports[`history > singleplayer undo/redo > should not end up with history entry
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -15731,6 +15781,7 @@ exports[`history > singleplayer undo/redo > should not end up with history entry
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -15995,6 +16046,7 @@ exports[`history > singleplayer undo/redo > should not modify anything on unrela
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -16148,6 +16200,7 @@ exports[`history > singleplayer undo/redo > should not override appstate changes
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -16432,6 +16485,7 @@ exports[`history > singleplayer undo/redo > should support appstate name or view
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -16594,6 +16648,7 @@ exports[`history > singleplayer undo/redo > should support bidirectional binding
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -17343,6 +17398,7 @@ exports[`history > singleplayer undo/redo > should support bidirectional binding
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -17990,6 +18046,7 @@ exports[`history > singleplayer undo/redo > should support bidirectional binding
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -18635,6 +18692,7 @@ exports[`history > singleplayer undo/redo > should support bidirectional binding
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -19387,6 +19445,7 @@ exports[`history > singleplayer undo/redo > should support bidirectional binding
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -20156,6 +20215,7 @@ exports[`history > singleplayer undo/redo > should support changes in elements'
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -20637,6 +20697,7 @@ exports[`history > singleplayer undo/redo > should support duplication of groups
     "id1": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -21149,6 +21210,7 @@ exports[`history > singleplayer undo/redo > should support element creation, del
     "id3": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,
@@ -21609,6 +21671,7 @@ exports[`history > singleplayer undo/redo > should support linear element creati
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "searchMatches": null,

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

@@ -88,6 +88,7 @@ exports[`given element A and group of elements B and given both are selected whe
     "id6": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -515,6 +516,7 @@ exports[`given element A and group of elements B and given both are selected whe
     "id6": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -928,6 +930,7 @@ exports[`regression tests > Cmd/Ctrl-click exclusively select element under poin
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -1495,6 +1498,7 @@ exports[`regression tests > Drags selected element when hitting only bounding bo
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -1705,6 +1709,7 @@ exports[`regression tests > adjusts z order when grouping > [end of test] appSta
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -2090,6 +2095,7 @@ exports[`regression tests > alt-drag duplicates an element > [end of test] appSt
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -2334,6 +2340,7 @@ exports[`regression tests > arrow keys > [end of test] appState 1`] = `
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -2517,6 +2524,7 @@ exports[`regression tests > can drag element that covers another element, while
     "id6": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -2841,6 +2849,7 @@ exports[`regression tests > change the properties of a shape > [end of test] app
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -3099,6 +3108,7 @@ exports[`regression tests > click on an element and drag it > [dragged] appState
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -3341,6 +3351,7 @@ exports[`regression tests > click on an element and drag it > [end of test] appS
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -3578,6 +3589,7 @@ exports[`regression tests > click to select a shape > [end of test] appState 1`]
     "id3": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -3837,6 +3849,7 @@ exports[`regression tests > click-drag to select a group > [end of test] appStat
     "id6": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -4150,6 +4163,7 @@ exports[`regression tests > deleting last but one element in editing group shoul
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -4590,6 +4604,7 @@ exports[`regression tests > deselects group of selected elements on pointer down
     "id3": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -4874,6 +4889,7 @@ exports[`regression tests > deselects group of selected elements on pointer up w
     "id3": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -5150,6 +5166,7 @@ exports[`regression tests > deselects selected element on pointer down when poin
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -5359,6 +5376,7 @@ exports[`regression tests > deselects selected element, on pointer up, when clic
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -5558,6 +5576,7 @@ exports[`regression tests > double click to edit a group > [end of test] appStat
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -5955,6 +5974,7 @@ exports[`regression tests > drags selected elements from point inside common bou
     "id3": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -6250,6 +6270,7 @@ exports[`regression tests > draw every type of shape > [end of test] appState 1`
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -7042,6 +7063,7 @@ exports[`regression tests > given a group of selected elements with an element t
     "id6": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -7376,6 +7398,7 @@ exports[`regression tests > given a selected element A and a not selected elemen
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -7656,6 +7679,7 @@ exports[`regression tests > given selected element A with lower z-index than uns
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -7892,6 +7916,7 @@ exports[`regression tests > given selected element A with lower z-index than uns
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -8131,6 +8156,7 @@ exports[`regression tests > key 2 selects rectangle tool > [end of test] appStat
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -8312,6 +8338,7 @@ exports[`regression tests > key 3 selects diamond tool > [end of test] appState
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -8493,6 +8520,7 @@ exports[`regression tests > key 4 selects ellipse tool > [end of test] appState
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -8674,6 +8702,7 @@ exports[`regression tests > key 5 selects arrow tool > [end of test] appState 1`
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -8907,6 +8936,7 @@ exports[`regression tests > key 6 selects line tool > [end of test] appState 1`]
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -9138,6 +9168,7 @@ exports[`regression tests > key 7 selects freedraw tool > [end of test] appState
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -9331,6 +9362,7 @@ exports[`regression tests > key a selects arrow tool > [end of test] appState 1`
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -9564,6 +9596,7 @@ exports[`regression tests > key d selects diamond tool > [end of test] appState
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -9745,6 +9778,7 @@ exports[`regression tests > key l selects line tool > [end of test] appState 1`]
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -9976,6 +10010,7 @@ exports[`regression tests > key o selects ellipse tool > [end of test] appState
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -10157,6 +10192,7 @@ exports[`regression tests > key p selects freedraw tool > [end of test] appState
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -10350,6 +10386,7 @@ exports[`regression tests > key r selects rectangle tool > [end of test] appStat
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -10535,6 +10572,7 @@ exports[`regression tests > make a group and duplicate it > [end of test] appSta
     "id6": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -11065,6 +11103,7 @@ exports[`regression tests > noop interaction after undo shouldn't create history
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -11344,6 +11383,7 @@ exports[`regression tests > pinch-to-zoom works > [end of test] appState 1`] = `
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": "-6.25000",
   "scrollY": 0,
   "scrolledOutside": false,
@@ -11470,6 +11510,7 @@ exports[`regression tests > shift click on selected element should deselect it o
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -11672,6 +11713,7 @@ exports[`regression tests > shift-click to multiselect, then drag > [end of test
     "id3": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -11993,6 +12035,7 @@ exports[`regression tests > should group elements and ungroup them > [end of tes
     "id6": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -12424,6 +12467,7 @@ exports[`regression tests > single-clicking on a subgroup of a selected group sh
     "id3": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -13063,6 +13107,7 @@ exports[`regression tests > spacebar + drag scrolls the canvas > [end of test] a
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 60,
   "scrollY": 60,
   "scrolledOutside": false,
@@ -13189,6 +13234,7 @@ exports[`regression tests > supports nested groups > [end of test] appState 1`]
     "id0": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -13822,6 +13868,7 @@ exports[`regression tests > switches from group of selected elements to another
     "id6": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -14161,6 +14208,7 @@ exports[`regression tests > switches selected element on pointer down > [end of
     "id3": true,
   },
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -14424,6 +14472,7 @@ exports[`regression tests > two-finger scroll works > [end of test] appState 1`]
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 20,
   "scrollY": "-18.53553",
   "scrolledOutside": false,
@@ -14548,6 +14597,7 @@ exports[`regression tests > undo/redo drawing an element > [end of test] appStat
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -14913,6 +14963,7 @@ exports[`regression tests > updates fontSize & fontFamily appState > [end of tes
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,
@@ -15040,6 +15091,7 @@ exports[`regression tests > zoom hotkeys > [end of test] appState 1`] = `
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,

packages/excalidraw/tests/scrollConstraints.test.tsx

@@ -0,0 +1,135 @@
+import React from "react";
+import { vi } from "vitest";
+
+import { resolvablePromise } from "@excalidraw/common";
+
+import { Excalidraw } from "../index";
+
+import { API } from "./helpers/api";
+import { act, render, waitFor } from "./test-utils";
+
+import type { ExcalidrawImperativeAPI, ScrollConstraints } from "../types";
+
+const FIRST_SCROLL_CONSTRAINTS: ScrollConstraints = {
+  x: 0,
+  y: 0,
+  width: 400,
+  height: 300,
+  lockZoom: true,
+  overscrollAllowance: 0,
+  viewportZoomFactor: 1,
+  animateOnNextUpdate: false,
+};
+
+const SECOND_SCROLL_CONSTRAINTS: ScrollConstraints = {
+  x: 100,
+  y: 200,
+  width: 500,
+  height: 350,
+  lockZoom: false,
+  overscrollAllowance: 0.2,
+  viewportZoomFactor: 0.8,
+  animateOnNextUpdate: false,
+};
+
+describe("scrollConstraints", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("syncs prop updates after mount", async () => {
+    const { rerender } = await render(<Excalidraw />);
+
+    expect(window.h.state.scrollConstraints).toBe(null);
+
+    rerender(<Excalidraw scrollConstraints={FIRST_SCROLL_CONSTRAINTS} />);
+
+    await waitFor(() => {
+      expect(window.h.state.scrollConstraints).toEqual(
+        FIRST_SCROLL_CONSTRAINTS,
+      );
+    });
+
+    rerender(<Excalidraw scrollConstraints={SECOND_SCROLL_CONSTRAINTS} />);
+
+    await waitFor(() => {
+      expect(window.h.state.scrollConstraints).toEqual(
+        SECOND_SCROLL_CONSTRAINTS,
+      );
+    });
+
+    rerender(<Excalidraw />);
+
+    await waitFor(() => {
+      expect(window.h.state.scrollConstraints).toBe(null);
+    });
+  });
+
+  it("ignores setScrollConstraints() when the prop is controlled", async () => {
+    const excalidrawAPIPromise = resolvablePromise<ExcalidrawImperativeAPI>();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    await render(
+      <Excalidraw
+        scrollConstraints={FIRST_SCROLL_CONSTRAINTS}
+        onExcalidrawAPI={(api) => {
+          if (api) {
+            excalidrawAPIPromise.resolve(api);
+          }
+        }}
+      />,
+    );
+
+    const excalidrawAPI = await excalidrawAPIPromise;
+
+    act(() => {
+      excalidrawAPI.setScrollConstraints(SECOND_SCROLL_CONSTRAINTS);
+    });
+
+    expect(warn).toHaveBeenCalledWith(
+      "Excalidraw: `setScrollConstraints()` is ignored when the `scrollConstraints` prop is controlled. Update the prop value instead.",
+    );
+    expect(window.h.state.scrollConstraints).toEqual(FIRST_SCROLL_CONSTRAINTS);
+  });
+
+  it("ignores scrollToContent() scrollLock when the prop is controlled", async () => {
+    const excalidrawAPIPromise = resolvablePromise<ExcalidrawImperativeAPI>();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    await render(
+      <Excalidraw
+        scrollConstraints={FIRST_SCROLL_CONSTRAINTS}
+        onExcalidrawAPI={(api) => {
+          if (api) {
+            excalidrawAPIPromise.resolve(api);
+          }
+        }}
+      />,
+    );
+
+    const excalidrawAPI = await excalidrawAPIPromise;
+    const rectangle = API.createElement({
+      x: 1000,
+      y: 1000,
+      width: 100,
+      height: 100,
+    });
+    API.setElements([rectangle]);
+
+    act(() => {
+      excalidrawAPI.scrollToContent(rectangle, {
+        animate: false,
+        fitToViewport: true,
+        scrollLock: {
+          lockZoom: true,
+          overscrollAllowance: 0,
+        },
+      });
+    });
+
+    expect(warn).toHaveBeenCalledWith(
+      "Excalidraw: `scrollToContent()` with `scrollLock` is ignored when the `scrollConstraints` prop is controlled. Update the prop value instead.",
+    );
+    expect(window.h.state.scrollConstraints).toEqual(FIRST_SCROLL_CONSTRAINTS);
+  });
+});

packages/excalidraw/types.ts

@@ -454,6 +454,7 @@ export interface AppState {
   userToFollow: UserToFollow | null;
   /** the socket ids of the users following the current user */
   followedBy: Set<SocketId>;
+  scrollConstraints: ScrollConstraints | null;
 
   /** image cropping */
   isCropping: boolean;
@@ -546,6 +547,8 @@ export type ExcalidrawInitialDataState = Merge<
   ImportedDataState,
   {
     libraryItems?: MaybePromise<Required<ImportedDataState>["libraryItems"]>;
+    scrollX?: number;
+    scrollY?: number;
   }
 >;
 
@@ -662,6 +665,7 @@ export interface ExcalidrawProps {
   onScrollChange?: (scrollX: number, scrollY: number, zoom: Zoom) => void;
   onUserFollow?: (payload: OnUserFollowedPayload) => void;
   children?: React.ReactNode;
+  scrollConstraints?: AppState["scrollConstraints"];
   validateEmbeddable?:
     | boolean
     | string[]
@@ -988,6 +992,8 @@ export interface ExcalidrawImperativeAPI {
   ) => UnsubscribeCallback;
   onStateChange: InstanceType<typeof App>["onStateChange"];
   onEvent: InstanceType<typeof App>["onEvent"];
+  app: InstanceType<typeof App>;
+  setScrollConstraints: InstanceType<typeof App>["setScrollConstraints"];
 }
 
 export type FrameNameBounds = {
@@ -1054,3 +1060,69 @@ export type Offsets = Partial<{
   bottom: number;
   left: number;
 }>;
+
+export type ScrollConstraints = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  animateOnNextUpdate?: boolean;
+  /**
+   * A factor that determines the minimum zoom level that should fit the
+   * constrained area into the viewport.
+   */
+  viewportZoomFactor?: number;
+  /**
+   * If true, the user will not be able to zoom out beyond the scroll
+   * constraints (taking into account the viewportZoomFactor).
+   */
+  lockZoom?: boolean;
+  /**
+   * <0-1> - how much can you scroll beyond the constrained area within the
+   * timeout window. Note you will still be snapped back to the constrained area
+   * after the timeout.
+   */
+  overscrollAllowance?: number;
+};
+
+/**
+ * Optional scroll constraint settings derived from the final viewport computed
+ * by `scrollToContent()`.
+ */
+export type ScrollToContentLockOptions = {
+  lockZoom?: boolean;
+  overscrollAllowance?: number;
+  viewportZoomFactor?: number;
+};
+
+export type ScrollToContentOptions =
+  | ({
+      fitToContent?: boolean;
+      fitToViewport?: never;
+      viewportZoomFactor?: number;
+      animate?: boolean;
+      duration?: number;
+      scrollLock?: boolean | ScrollToContentLockOptions;
+    } & {
+      minZoom?: number;
+      maxZoom?: number;
+      canvasOffsets?: Offsets;
+    })
+  | ({
+      fitToContent?: never;
+      fitToViewport?: boolean;
+      viewportZoomFactor?: number;
+      animate?: boolean;
+      duration?: number;
+      scrollLock?: boolean | ScrollToContentLockOptions;
+    } & {
+      minZoom?: number;
+      maxZoom?: number;
+      canvasOffsets?: Offsets;
+    });
+
+export type AnimateTranslateCanvasValues = {
+  scrollX: AppState["scrollX"];
+  scrollY: AppState["scrollY"];
+  zoom: AppState["zoom"]["value"];
+};

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

@@ -85,6 +85,7 @@ exports[`exportToSvg > with default arguments 1`] = `
   },
   "previousSelectedElementIds": {},
   "resizingElement": null,
+  "scrollConstraints": null,
   "scrollX": 0,
   "scrollY": 0,
   "scrolledOutside": false,

vercel.json

@@ -1,5 +1,4 @@
 {
-  "public": true,
   "headers": [
     {
       "source": "/(.*)",