@excalidraw/excalidraw 0.17.1-d9bbf1e → 0.17.1-e63dd02

package/dist/excalidraw/scene/Shape.d.ts

@@ -1,7 +1,7 @@
 import type { Drawable, Options } from "roughjs/bin/core";
 import type { RoughGenerator } from "roughjs/bin/generator";
 import type { ExcalidrawElement, NonDeletedExcalidrawElement, ExcalidrawSelectionElement } from "../element/types";
-import { EmbedsValidationStatus } from "../types";
+import type { EmbedsValidationStatus } from "../types";
 export declare const generateRoughOptions: (element: ExcalidrawElement, continuousPath?: boolean) => Options;
 /**
  * Generates the roughjs shape for given element.

package/dist/excalidraw/scene/Shape.js

@@ -1,10 +1,10 @@
 import { getDiamondPoints, getArrowheadPoints } from "../element";
-import { isPathALoop, getCornerRadius } from "../math";
+import { isPathALoop, getCornerRadius, distanceSq2d } from "../math";
 import { generateFreeDrawShape } from "../renderer/renderElement";
 import { isTransparent, assertNever } from "../utils";
 import { simplify } from "points-on-curve";
 import { ROUGHNESS } from "../constants";
-import { isEmbeddableElement, isIframeElement, isIframeLikeElement, isLinearElement, } from "../element/typeChecks";
+import { isElbowArrow, isEmbeddableElement, isIframeElement, isIframeLikeElement, isLinearElement, } from "../element/typeChecks";
 import { canChangeRoundness } from "./comparisons";
 const getDashArrayDashed = (strokeWidth) => [8, 8 + strokeWidth];
 const getDashArrayDotted = (strokeWidth) => [1.5, 6 + strokeWidth];
@@ -261,9 +261,14 @@ export const _generateElementShape = (element, generator, { isExporting, canvasB
             // points array can be empty in the beginning, so it is important to add
             // initial position to it
             const points = element.points.length ? element.points : [[0, 0]];
-            // curve is always the first element
-            // this simplifies finding the curve for an element
-            if (!element.roundness) {
+            if (isElbowArrow(element)) {
+                shape = [
+                    generator.path(generateElbowArrowShape(points, 16), generateRoughOptions(element, true)),
+                ];
+            }
+            else if (!element.roundness) {
+                // curve is always the first element
+                // this simplifies finding the curve for an element
                 if (options.fill) {
                     shape = [generator.polygon(points, options)];
                 }
@@ -322,3 +327,49 @@ export const _generateElementShape = (element, generator, { isExporting, canvasB
         }
     }
 };
+const generateElbowArrowShape = (points, radius) => {
+    const subpoints = [];
+    for (let i = 1; i < points.length - 1; i += 1) {
+        const prev = points[i - 1];
+        const next = points[i + 1];
+        const corner = Math.min(radius, Math.sqrt(distanceSq2d(points[i], next)) / 2, Math.sqrt(distanceSq2d(points[i], prev)) / 2);
+        if (prev[0] < points[i][0] && prev[1] === points[i][1]) {
+            // LEFT
+            subpoints.push([points[i][0] - corner, points[i][1]]);
+        }
+        else if (prev[0] === points[i][0] && prev[1] < points[i][1]) {
+            // UP
+            subpoints.push([points[i][0], points[i][1] - corner]);
+        }
+        else if (prev[0] > points[i][0] && prev[1] === points[i][1]) {
+            // RIGHT
+            subpoints.push([points[i][0] + corner, points[i][1]]);
+        }
+        else {
+            subpoints.push([points[i][0], points[i][1] + corner]);
+        }
+        subpoints.push(points[i]);
+        if (next[0] < points[i][0] && next[1] === points[i][1]) {
+            // LEFT
+            subpoints.push([points[i][0] - corner, points[i][1]]);
+        }
+        else if (next[0] === points[i][0] && next[1] < points[i][1]) {
+            // UP
+            subpoints.push([points[i][0], points[i][1] - corner]);
+        }
+        else if (next[0] > points[i][0] && next[1] === points[i][1]) {
+            // RIGHT
+            subpoints.push([points[i][0] + corner, points[i][1]]);
+        }
+        else {
+            subpoints.push([points[i][0], points[i][1] + corner]);
+        }
+    }
+    const d = [`M ${points[0][0]} ${points[0][1]}`];
+    for (let i = 0; i < subpoints.length; i += 3) {
+        d.push(`L ${subpoints[i][0]} ${subpoints[i][1]}`);
+        d.push(`Q ${subpoints[i + 1][0]} ${subpoints[i + 1][1]}, ${subpoints[i + 2][0]} ${subpoints[i + 2][1]}`);
+    }
+    d.push(`L ${points[points.length - 1][0]} ${points[points.length - 1][1]}`);
+    return d.join(" ");
+};

package/dist/excalidraw/scene/ShapeCache.d.ts

@@ -1,7 +1,7 @@
-import { Drawable } from "roughjs/bin/core";
-import { ExcalidrawElement } from "../element/types";
-import { ElementShape, ElementShapes } from "./types";
-import { AppState, EmbedsValidationStatus } from "../types";
+import type { Drawable } from "roughjs/bin/core";
+import type { ExcalidrawElement } from "../element/types";
+import type { ElementShape, ElementShapes } from "./types";
+import type { AppState, EmbedsValidationStatus } from "../types";
 export declare class ShapeCache {
     private static rg;
     private static cache;

package/dist/excalidraw/scene/comparisons.d.ts

@@ -1,10 +1,11 @@
-import { NonDeletedExcalidrawElement } from "../element/types";
-import { ElementOrToolType } from "../types";
+import type { NonDeletedExcalidrawElement } from "../element/types";
+import type { ElementOrToolType } from "../types";
 export declare const hasBackground: (type: ElementOrToolType) => boolean;
 export declare const hasStrokeColor: (type: ElementOrToolType) => boolean;
 export declare const hasStrokeWidth: (type: ElementOrToolType) => boolean;
 export declare const hasStrokeStyle: (type: ElementOrToolType) => boolean;
 export declare const canChangeRoundness: (type: ElementOrToolType) => boolean;
+export declare const toolIsArrow: (type: ElementOrToolType) => boolean;
 export declare const canHaveArrowheads: (type: ElementOrToolType) => boolean;
 export declare const getElementAtPosition: (elements: readonly NonDeletedExcalidrawElement[], isAtPositionFn: (element: NonDeletedExcalidrawElement) => boolean) => NonDeletedExcalidrawElement | null;
 export declare const getElementsAtPosition: (elements: readonly NonDeletedExcalidrawElement[], isAtPositionFn: (element: NonDeletedExcalidrawElement) => boolean) => NonDeletedExcalidrawElement[];

package/dist/excalidraw/scene/comparisons.js

@@ -25,10 +25,10 @@ export const hasStrokeStyle = (type) => type === "rectangle" ||
 export const canChangeRoundness = (type) => type === "rectangle" ||
     type === "iframe" ||
     type === "embeddable" ||
-    type === "arrow" ||
     type === "line" ||
     type === "diamond" ||
     type === "image";
+export const toolIsArrow = (type) => type === "arrow";
 export const canHaveArrowheads = (type) => type === "arrow";
 export const getElementAtPosition = (elements, isAtPositionFn) => {
     let hitElement = null;

package/dist/excalidraw/scene/export.d.ts

@@ -1,5 +1,5 @@
-import { ExcalidrawFrameLikeElement, NonDeletedExcalidrawElement } from "../element/types";
-import { AppState, BinaryFiles } from "../types";
+import type { ExcalidrawFrameLikeElement, NonDeletedExcalidrawElement } from "../element/types";
+import type { AppState, BinaryFiles } from "../types";
 export declare const exportToCanvas: (elements: readonly NonDeletedExcalidrawElement[], appState: AppState, files: BinaryFiles, { exportBackground, exportPadding, viewBackgroundColor, exportingFrame, }: {
     exportBackground: boolean;
     exportPadding?: number | undefined;
@@ -8,7 +8,7 @@ export declare const exportToCanvas: (elements: readonly NonDeletedExcalidrawEle
 }, createCanvas?: (width: number, height: number) => {
     canvas: HTMLCanvasElement;
     scale: number;
-}) => Promise<HTMLCanvasElement>;
+}, loadFonts?: () => Promise<void>) => Promise<HTMLCanvasElement>;
 export declare const exportToSvg: (elements: readonly NonDeletedExcalidrawElement[], appState: {
     exportBackground: boolean;
     exportPadding?: number;
@@ -23,5 +23,6 @@ export declare const exportToSvg: (elements: readonly NonDeletedExcalidrawElemen
      */
     renderEmbeddables?: boolean;
     exportingFrame?: ExcalidrawFrameLikeElement | null;
+    skipInliningFonts?: true;
 }) => Promise<SVGSVGElement>;
 export declare const getExportSize: (elements: readonly NonDeletedExcalidrawElement[], exportPadding: number, scale: number) => [number, number];

package/dist/excalidraw/scene/export.js

@@ -1,17 +1,18 @@
 import rough from "roughjs/bin/rough";
-import { getCommonBounds, getElementAbsoluteCoords, } from "../element/bounds";
+import { getCommonBounds, getElementAbsoluteCoords } from "../element/bounds";
 import { renderSceneToSvg } from "../renderer/staticSvgScene";
 import { arrayToMap, distance, getFontString, toBrandedType } from "../utils";
-import { DEFAULT_EXPORT_PADDING, FONT_FAMILY, FRAME_STYLE, SVG_NS, THEME, THEME_FILTER, } from "../constants";
+import { DEFAULT_EXPORT_PADDING, FRAME_STYLE, FONT_FAMILY, SVG_NS, THEME, THEME_FILTER, } from "../constants";
 import { getDefaultAppState } from "../appState";
 import { serializeAsJSON } from "../data/json";
 import { getInitializedImageElements, updateImageCache, } from "../element/image";
 import { getElementsOverlappingFrame, getFrameLikeElements, getFrameLikeTitle, getRootElements, } from "../frame";
 import { newTextElement } from "../element";
 import { newElementWith } from "../element/mutateElement";
-import { isFrameElement, isFrameLikeElement } from "../element/typeChecks";
+import { isFrameLikeElement, isTextElement } from "../element/typeChecks";
 import { syncInvalidIndices } from "../fractionalIndex";
 import { renderStaticScene } from "../renderer/staticScene";
+import { Fonts } from "../fonts";
 const SVG_EXPORT_TAG = `<!-- svg-source:excalidraw -->`;
 const truncateText = (element, maxWidth) => {
     if (element.width <= maxWidth) {
@@ -48,26 +49,18 @@ const truncateText = (element, maxWidth) => {
  */
 const addFrameLabelsAsTextElements = (elements, opts) => {
     const nextElements = [];
-    let frameIndex = 0;
-    let magicFrameIndex = 0;
     for (const element of elements) {
         if (isFrameLikeElement(element)) {
-            if (isFrameElement(element)) {
-                frameIndex++;
-            }
-            else {
-                magicFrameIndex++;
-            }
             let textElement = newTextElement({
                 x: element.x,
                 y: element.y - FRAME_STYLE.nameOffsetY,
-                fontFamily: FONT_FAMILY.Assistant,
+                fontFamily: FONT_FAMILY.Helvetica,
                 fontSize: FRAME_STYLE.nameFontSize,
                 lineHeight: FRAME_STYLE.nameLineHeight,
                 strokeColor: opts.exportWithDarkMode
                     ? FRAME_STYLE.nameColorDarkTheme
                     : FRAME_STYLE.nameColorLightTheme,
-                text: getFrameLikeTitle(element, isFrameElement(element) ? frameIndex : magicFrameIndex),
+                text: getFrameLikeTitle(element),
             });
             textElement.y -= textElement.height;
             textElement = truncateText(textElement, element.width);
@@ -106,7 +99,11 @@ export const exportToCanvas = async (elements, appState, files, { exportBackgrou
     canvas.width = width * appState.exportScale;
     canvas.height = height * appState.exportScale;
     return { canvas, scale: appState.exportScale };
+}, loadFonts = async () => {
+    await Fonts.loadFontsForElements(elements);
 }) => {
+    // load font faces before continuing, by default leverages browsers' [FontFace API](https://developer.mozilla.org/en-US/docs/Web/API/FontFace)
+    await loadFonts();
     const frameRendering = getFrameRenderingConfig(exportingFrame ?? null, appState.frameRendering ?? null);
     const elementsForRender = prepareElementsForRender({
         elements,
@@ -195,17 +192,6 @@ export const exportToSvg = async (elements, appState, files, opts) => {
     if (exportWithDarkMode) {
         svgRoot.setAttribute("filter", THEME_FILTER);
     }
-    let assetPath = "https://excalidraw.com/";
-    // Asset path needs to be determined only when using package
-    if (import.meta.env.VITE_IS_EXCALIDRAW_NPM_PACKAGE) {
-        assetPath =
-            window.EXCALIDRAW_ASSET_PATH ||
-                `https://unpkg.com/${import.meta.env.VITE_PKG_NAME}@${import.meta.env.PKG_VERSION}`;
-        if (assetPath?.startsWith("/")) {
-            assetPath = assetPath.replace("/", `${window.location.origin}/`);
-        }
-        assetPath = `${assetPath}/dist/excalidraw-assets/`;
-    }
     const offsetX = -minX + exportPadding;
     const offsetY = -minY + exportPadding;
     const frameElements = getFrameLikeElements(elements);
@@ -223,23 +209,35 @@ export const exportToSvg = async (elements, appState, files, opts) => {
           </rect>
         </clipPath>`;
     }
+    const fontFamilies = elements.reduce((acc, element) => {
+        if (isTextElement(element)) {
+            acc.add(element.fontFamily);
+        }
+        return acc;
+    }, new Set());
+    const fontFaces = opts?.skipInliningFonts
+        ? []
+        : await Promise.all(Array.from(fontFamilies).map(async (x) => {
+            const { fonts, metadata } = Fonts.registered.get(x) ?? {};
+            if (!Array.isArray(fonts)) {
+                console.error(`Couldn't find registered fonts for font-family "${x}"`, Fonts.registered);
+                return;
+            }
+            if (metadata?.local) {
+                // don't inline local fonts
+                return;
+            }
+            return Promise.all(fonts.map(async (font) => `@font-face {
+        font-family: ${font.fontFace.family};
+        src: url(${await font.getContent()});
+          }`));
+        }));
     svgRoot.innerHTML = `
   ${SVG_EXPORT_TAG}
   ${metadata}
   <defs>
     <style class="style-fonts">
-      @font-face {
-        font-family: "Virgil";
-        src: url("${assetPath}Virgil.woff2");
-      }
-      @font-face {
-        font-family: "Cascadia";
-        src: url("${assetPath}Cascadia.woff2");
-      }
-      @font-face {
-        font-family: "Assistant";
-        src: url("${assetPath}Assistant-Regular.woff2");
-      }
+      ${fontFaces.flat().filter(Boolean).join("\n")}
     </style>
     ${exportingFrameClipPath}
   </defs>

package/dist/excalidraw/scene/scroll.d.ts

@@ -1,5 +1,5 @@
-import { AppState, PointerCoords, Zoom } from "../types";
-import { ExcalidrawElement } from "../element/types";
+import type { AppState, PointerCoords, Zoom } from "../types";
+import type { ExcalidrawElement } from "../element/types";
 export declare const centerScrollOn: ({ scenePoint, viewportDimensions, zoom, }: {
     scenePoint: PointerCoords;
     viewportDimensions: {

package/dist/excalidraw/scene/scrollbars.d.ts

@@ -1,6 +1,6 @@
-import { InteractiveCanvasAppState } from "../types";
-import { ScrollBars } from "./types";
-import { ExcalidrawElement } from "../element/types";
+import type { InteractiveCanvasAppState } from "../types";
+import type { ScrollBars } from "./types";
+import type { ExcalidrawElement } from "../element/types";
 export declare const SCROLLBAR_MARGIN = 4;
 export declare const SCROLLBAR_WIDTH = 6;
 export declare const SCROLLBAR_COLOR = "rgba(0,0,0,0.3)";

package/dist/excalidraw/scene/selection.d.ts

@@ -1,5 +1,5 @@
-import { ElementsMap, ElementsMapOrArray, ExcalidrawElement, NonDeletedExcalidrawElement } from "../element/types";
-import { AppState, InteractiveCanvasAppState } from "../types";
+import type { ElementsMap, ElementsMapOrArray, ExcalidrawElement, NonDeletedExcalidrawElement } from "../element/types";
+import type { AppState, InteractiveCanvasAppState } from "../types";
 /**
  * Frames and their containing elements are not to be selected at the same time.
  * Given an array of selected elements, if there are frames and their containing elements

package/dist/excalidraw/scene/types.d.ts

@@ -1,8 +1,8 @@
 import type { RoughCanvas } from "roughjs/bin/canvas";
-import { Drawable } from "roughjs/bin/core";
-import { ExcalidrawElement, ExcalidrawTextElement, NonDeletedElementsMap, NonDeletedExcalidrawElement, NonDeletedSceneElementsMap } from "../element/types";
-import { AppClassProperties, AppState, EmbedsValidationStatus, ElementsPendingErasure, InteractiveCanvasAppState, StaticCanvasAppState, SocketId, UserIdleState, Device } from "../types";
-import { MakeBrand } from "../utility-types";
+import type { Drawable } from "roughjs/bin/core";
+import type { ExcalidrawElement, NonDeletedElementsMap, NonDeletedExcalidrawElement, NonDeletedSceneElementsMap } from "../element/types";
+import type { AppClassProperties, AppState, EmbedsValidationStatus, ElementsPendingErasure, InteractiveCanvasAppState, StaticCanvasAppState, SocketId, UserIdleState, Device } from "../types";
+import type { MakeBrand } from "../utility-types";
 export type RenderableElementsMap = NonDeletedElementsMap & MakeBrand<"RenderableElementsMap">;
 export type StaticCanvasRenderConfig = {
     canvasBackgroundColor: AppState["viewBackgroundColor"];
@@ -33,7 +33,7 @@ export type InteractiveCanvasRenderConfig = {
     remotePointerUserStates: Map<SocketId, UserIdleState>;
     remotePointerUsernames: Map<SocketId, string>;
     remotePointerButton: Map<SocketId, string | undefined>;
-    selectionColor?: string;
+    selectionColor: string;
     renderScrollbars?: boolean;
 };
 export type RenderInteractiveSceneCallback = {
@@ -56,6 +56,7 @@ export type InteractiveSceneRenderConfig = {
     elementsMap: RenderableElementsMap;
     visibleElements: readonly NonDeletedExcalidrawElement[];
     selectedElements: readonly NonDeletedExcalidrawElement[];
+    allElementsMap: NonDeletedSceneElementsMap;
     scale: number;
     appState: InteractiveCanvasAppState;
     renderConfig: InteractiveCanvasRenderConfig;
@@ -66,9 +67,6 @@ export type SceneScroll = {
     scrollX: number;
     scrollY: number;
 };
-export interface Scene {
-    elements: ExcalidrawTextElement[];
-}
 export type ExportType = "png" | "clipboard" | "clipboard-svg" | "backend" | "svg";
 export type ScrollBars = {
     horizontal: {

package/dist/excalidraw/scene/zoom.d.ts

@@ -1,4 +1,4 @@
-import { AppState, NormalizedZoomValue } from "../types";
+import type { AppState, NormalizedZoomValue } from "../types";
 export declare const getNormalizedZoom: (zoom: number) => NormalizedZoomValue;
 export declare const getStateForZoom: ({ viewportX, viewportY, nextZoom, }: {
     viewportX: number;

package/dist/excalidraw/shapes.d.ts

@@ -1,4 +1,6 @@
 /// <reference types="react" />
+import { type GeometricShape } from "../utils/geometry/shape";
+import type { ElementsMap, ExcalidrawElement } from "./element/types";
 export declare const SHAPES: readonly [{
     readonly icon: JSX.Element;
     readonly value: "selection";
@@ -61,3 +63,9 @@ export declare const SHAPES: readonly [{
     readonly fillable: false;
 }];
 export declare const findShapeByKey: (key: string) => "text" | "image" | "selection" | "rectangle" | "diamond" | "ellipse" | "arrow" | "line" | "freedraw" | "eraser" | null;
+/**
+ * get the pure geometric shape of an excalidraw element
+ * which is then used for hit detection
+ */
+export declare const getElementShape: (element: ExcalidrawElement, elementsMap: ElementsMap) => GeometricShape;
+export declare const getBoundTextShape: (element: ExcalidrawElement, elementsMap: ElementsMap) => GeometricShape | null;

package/dist/excalidraw/shapes.js

@@ -1,5 +1,11 @@
+import { getClosedCurveShape, getCurveShape, getEllipseShape, getFreedrawShape, getPolygonShape, } from "../utils/geometry/shape";
 import { ArrowIcon, DiamondIcon, EllipseIcon, EraserIcon, FreedrawIcon, ImageIcon, LineIcon, RectangleIcon, SelectionIcon, TextIcon, } from "./components/icons";
+import { getElementAbsoluteCoords } from "./element";
+import { shouldTestInside } from "./element/collision";
+import { LinearElementEditor } from "./element/linearElementEditor";
+import { getBoundTextElement } from "./element/textElement";
 import { KEYS } from "./keys";
+import { ShapeCache } from "./scene/ShapeCache";
 export const SHAPES = [
     {
         icon: SelectionIcon,
@@ -82,3 +88,54 @@ export const findShapeByKey = (key) => {
     });
     return shape?.value || null;
 };
+/**
+ * get the pure geometric shape of an excalidraw element
+ * which is then used for hit detection
+ */
+export const getElementShape = (element, elementsMap) => {
+    switch (element.type) {
+        case "rectangle":
+        case "diamond":
+        case "frame":
+        case "magicframe":
+        case "embeddable":
+        case "image":
+        case "iframe":
+        case "text":
+        case "selection":
+            return getPolygonShape(element);
+        case "arrow":
+        case "line": {
+            const roughShape = ShapeCache.get(element)?.[0] ??
+                ShapeCache.generateElementShape(element, null)[0];
+            const [, , , , cx, cy] = getElementAbsoluteCoords(element, elementsMap);
+            return shouldTestInside(element)
+                ? getClosedCurveShape(element, roughShape, [element.x, element.y], element.angle, [cx, cy])
+                : getCurveShape(roughShape, [element.x, element.y], element.angle, [
+                    cx,
+                    cy,
+                ]);
+        }
+        case "ellipse":
+            return getEllipseShape(element);
+        case "freedraw": {
+            const [, , , , cx, cy] = getElementAbsoluteCoords(element, elementsMap);
+            return getFreedrawShape(element, [cx, cy], shouldTestInside(element));
+        }
+    }
+};
+export const getBoundTextShape = (element, elementsMap) => {
+    const boundTextElement = getBoundTextElement(element, elementsMap);
+    if (boundTextElement) {
+        if (element.type === "arrow") {
+            return getElementShape({
+                ...boundTextElement,
+                // arrow's bound text accurate position is not stored in the element's property
+                // but rather calculated and returned from the following static method
+                ...LinearElementEditor.getBoundTextElementPosition(element, boundTextElement, elementsMap),
+            }, elementsMap);
+        }
+        return getElementShape(boundTextElement, elementsMap);
+    }
+    return null;
+};

package/dist/excalidraw/snapping.d.ts

@@ -1,7 +1,7 @@
-import { Bounds } from "./element/bounds";
-import { MaybeTransformHandleType } from "./element/transformHandles";
-import { ElementsMap, ExcalidrawElement, NonDeletedExcalidrawElement } from "./element/types";
-import { AppState, KeyboardModifiersObject, Point } from "./types";
+import type { Bounds } from "./element/bounds";
+import type { MaybeTransformHandleType } from "./element/transformHandles";
+import type { ElementsMap, ExcalidrawElement, NonDeletedExcalidrawElement } from "./element/types";
+import type { AppState, KeyboardModifiersObject, Point } from "./types";
 export declare const getSnapDistance: (zoomValue: number) => number;
 type Vector2D = {
     x: number;

package/dist/excalidraw/snapping.js

@@ -835,5 +835,6 @@ export const isActiveToolNonLinearSnappable = (activeToolType) => {
         activeToolType === TOOL_TYPE.diamond ||
         activeToolType === TOOL_TYPE.frame ||
         activeToolType === TOOL_TYPE.magicframe ||
-        activeToolType === TOOL_TYPE.image);
+        activeToolType === TOOL_TYPE.image ||
+        activeToolType === TOOL_TYPE.text);
 };

package/dist/excalidraw/store.d.ts

@@ -1,12 +1,42 @@
 import { AppStateChange, ElementsChange } from "./change";
-import { OrderedExcalidrawElement } from "./element/types";
+import type { OrderedExcalidrawElement } from "./element/types";
 import { Emitter } from "./emitter";
-import { AppState, ObservedAppState } from "./types";
+import type { AppState, ObservedAppState } from "./types";
+import type { ValueOf } from "./utility-types";
 export declare const getObservedAppState: (appState: AppState) => ObservedAppState;
-export type StoreActionType = "capture" | "update" | "none";
 export declare const StoreAction: {
-    [K in Uppercase<StoreActionType>]: StoreActionType;
+    /**
+     * Immediately undoable.
+     *
+     * Use for updates which should be captured.
+     * Should be used for most of the local updates.
+     *
+     * These updates will _immediately_ make it to the local undo / redo stacks.
+     */
+    readonly CAPTURE: "capture";
+    /**
+     * Never undoable.
+     *
+     * Use for updates which should never be recorded, such as remote updates
+     * or scene initialization.
+     *
+     * These updates will _never_ make it to the local undo / redo stacks.
+     */
+    readonly UPDATE: "update";
+    /**
+     * Eventually undoable.
+     *
+     * Use for updates which should not be captured immediately - likely
+     * exceptions which are part of some async multi-step process. Otherwise, all
+     * such updates would end up being captured with the next
+     * `StoreAction.CAPTURE` - triggered either by the next `updateScene`
+     * or internally by the editor.
+     *
+     * These updates will _eventually_ make it to the local undo / redo stacks.
+     */
+    readonly NONE: "none";
 };
+export type StoreActionType = ValueOf<typeof StoreAction>;
 /**
  * Represent an increment to the Store.
  */

package/dist/excalidraw/store.js

@@ -25,8 +25,35 @@ export const getObservedAppState = (appState) => {
 };
 const isObservedAppState = (appState) => !!Reflect.get(appState, hiddenObservedAppStateProp);
 export const StoreAction = {
+    /**
+     * Immediately undoable.
+     *
+     * Use for updates which should be captured.
+     * Should be used for most of the local updates.
+     *
+     * These updates will _immediately_ make it to the local undo / redo stacks.
+     */
     CAPTURE: "capture",
+    /**
+     * Never undoable.
+     *
+     * Use for updates which should never be recorded, such as remote updates
+     * or scene initialization.
+     *
+     * These updates will _never_ make it to the local undo / redo stacks.
+     */
     UPDATE: "update",
+    /**
+     * Eventually undoable.
+     *
+     * Use for updates which should not be captured immediately - likely
+     * exceptions which are part of some async multi-step process. Otherwise, all
+     * such updates would end up being captured with the next
+     * `StoreAction.CAPTURE` - triggered either by the next `updateScene`
+     * or internally by the editor.
+     *
+     * These updates will _eventually_ make it to the local undo / redo stacks.
+     */
     NONE: "none",
 };
 /**