@excalidraw/math 0.18.0-1118751 → 0.18.0-143b5b6

package/dist/types/excalidraw/components/App.text.d.ts

@@ -0,0 +1,146 @@
+import { type Bounds, type StylesPanelMode } from "@excalidraw/common";
+import type { ArrowEndpoint } from "@excalidraw/element";
+import type { ExcalidrawElement, ExcalidrawTextContainer, ExcalidrawTextElement, NonDeleted, NonDeletedExcalidrawElement } from "@excalidraw/element/types";
+import { textWysiwyg } from "../wysiwyg/textWysiwyg";
+import type App from "./App";
+import type { AppState, Offsets, ViewportUIName } from "../types";
+type AppTextDependencies = {
+    getContainer: () => HTMLDivElement | null;
+    getStylesPanelMode: () => StylesPanelMode;
+};
+/**
+ * Texts, but for the text tool's pointer interaction (`AppTextTool`):
+ *
+ * - the editing session: what text to edit, or create, and where
+ *   (`startTextEditing`), and the editor's lifecycle (`handleTextWysiwyg`)
+ * - the part of the canvas a typed or pasted text is kept within
+ *   (`getTextViewportOffsets`, `getMaxTextWidth`)
+ * - the queries that find the text or container to edit at a position
+ * - the handle that turns a fixed-width text back into a growing one
+ *
+ * Every way into editing ends up here: Enter, double-click, pointerup on a
+ * selected text or container, the text tool, a drag-created text or sticky
+ * note, and a sticky note dropped from the toolbar.
+ */
+export declare class AppText {
+    private app;
+    private dependencies;
+    constructor(app: App, dependencies: AppTextDependencies);
+    textWysiwygSubmitHandler: ReturnType<typeof textWysiwyg> | null;
+    private getTextCreationGridPoint;
+    /**
+     * The side panels, besides the sidebar, that a typed or pasted text is
+     * kept clear of: the stats panel, and the full styles panel (desktop),
+     * which shows next to a text while it's edited, and once it's pasted and
+     * selected.
+     */
+    getTextSidePanels: () => ViewportUIName[];
+    /**
+     * The part of the canvas a typed or pasted text is kept within, as offsets
+     * from its edges (screen px): all of it but the sidebar and the side
+     * panels (see getTextSidePanels), less some room at each side. The stats
+     * panel covers the top of a side only, and counts only for a text beside
+     * it: one (given by its scene bounds) with rows within that room of it.
+     */
+    getTextViewportOffsets: (textBounds?: Bounds) => Required<Offsets>;
+    /**
+     * The widest a text may grow to as it's typed or pasted, in scene units:
+     * TEXT_MAX_WRAP_WIDTH, or less, so that a text never outgrows the part of
+     * the canvas it's kept within.
+     */
+    getMaxTextWidth: (offsets: Required<Offsets>) => number;
+    handleTextWysiwyg(element: NonDeleted<ExcalidrawTextElement>, { isExistingElement, initialCaretSceneCoords, initialSelection, }: {
+        isExistingElement?: boolean;
+        /**
+         * supply null if no caret positioning is desired, and instead
+         * text should be auto-selected
+         */
+        initialCaretSceneCoords?: {
+            x: number;
+            y: number;
+        } | null;
+        /** range of the text to select (takes precedence over the caret) */
+        initialSelection?: {
+            start: number;
+            end: number;
+        } | null;
+    }): void;
+    private getSelectedTextElement;
+    getSelectedTextEditingContainerAtPosition(hitElement: NonDeletedExcalidrawElement | null, sceneCoords: {
+        x: number;
+        y: number;
+    }): ExcalidrawTextContainer | null | undefined;
+    getTextElementAtPosition(x: number, y: number): NonDeleted<ExcalidrawTextElement> | null;
+    isHittingTextAutoResizeHandle: (selectedElements: NonDeleted<ExcalidrawElement>[], point: Readonly<{
+        x: number;
+        y: number;
+    }>) => boolean;
+    handleTextAutoResizeHandlePointerDown: (selectedElements: NonDeleted<ExcalidrawElement>[], point: Readonly<{
+        x: number;
+        y: number;
+    }>) => boolean;
+    /**
+     * The text container at a position — an arrow hit on its path, any other
+     * container hit anywhere in its bounds (frames are skipped so a container
+     * inside one can be hit, and a frame's children are only hit inside it,
+     * where they are drawn). Purely positional: the selection plays no part.
+     *
+     * Only what hides the rest ends the search — a filled element or an image
+     * (as for arrow binding), or an arrow — so containers below a transparent
+     * one stay in reach whatever their z-order. Of the containers found, the
+     * innermost one centered on the position wins, since that is where its
+     * label would go (an arrow counting as innermost: it is pointed at, not just
+     * enclosing); failing that, the top-most.
+     */
+    getTextBindableContainerAtPosition(x: number, y: number): NonDeleted<ExcalidrawTextContainer>;
+    /**
+     * Whether a text element's content is still being authored.
+     *
+     * Creating a text reverts the tool to selection during pointerdown, so the
+     * pointerup that follows looks like an ordinary canvas click and would
+     * capture the still-empty element as a history entry of its own. Undo would
+     * then rewind only the typing, restoring an invisible, zero-content element
+     * (and, for an endpoint label, leaving the arrow bound to it) rather than
+     * removing it. The editor's own submit captures the finished text instead,
+     * so the whole create-and-type lands in a single entry.
+     */
+    isEditingTextContent(): boolean;
+    startTextEditing: ({ sceneX, sceneY, insertAtParentCenter, container, autoEdit, initialCaretSceneCoords, initialSelection, arrowEndpoint, textElement, }: {
+        /** X position to insert text at */
+        sceneX: number;
+        /** Y position to insert text at */
+        sceneY: number;
+        /** whether to attempt to insert at element center if applicable */
+        insertAtParentCenter?: boolean;
+        container?: ExcalidrawTextContainer | null;
+        autoEdit?: boolean;
+        initialCaretSceneCoords?: {
+            x: number;
+            y: number;
+        };
+        /** range of an existing text to select (takes precedence over the caret) */
+        initialSelection?: {
+            start: number;
+            end: number;
+        };
+        /**
+         * creates the text as a label for this arrow endpoint: the binding then
+         * dictates the text's position and alignment, overriding (sceneX, sceneY)
+         */
+        arrowEndpoint?: ArrowEndpoint | null;
+        /**
+         * the text to edit: an element to edit exactly that one; `null` to always
+         * create, never adopting a selected text or one under the pointer;
+         * `undefined` to resolve it here — a single selected text, the label of a
+         * selected or passed arrow container, else the text at (sceneX, sceneY)
+         */
+        textElement?: NonDeleted<ExcalidrawTextElement> | null;
+    }) => void;
+    getTextWysiwygSnappedToCenterPosition(x: number, y: number, appState: AppState, container?: ExcalidrawTextContainer | null): {
+        viewportX: number;
+        viewportY: number;
+        elementCenterX: number;
+        elementCenterY: number;
+    } | undefined;
+}
+export {};

package/dist/types/excalidraw/components/App.textTool.d.ts

@@ -0,0 +1,140 @@
+import type { ArrowEndpoint } from "@excalidraw/element";
+import type { ExcalidrawTextContainer, ExcalidrawTextElement, NonDeleted } from "@excalidraw/element/types";
+import type React from "react";
+import type App from "./App";
+import type { PointerDownState } from "../types";
+type ScenePoint = {
+    x: number;
+    y: number;
+};
+/** the modifier state a target depends on — off a pointer or keyboard event */
+export type Modifiers = Pick<KeyboardEvent, "ctrlKey" | "metaKey">;
+/** What a text-tool click at a position does. */
+export type TextToolTarget = 
+/** binds a new text to a free arrow endpoint */
+{
+    type: "endpoint";
+    endpoint: ArrowEndpoint;
+}
+/** edits this text (a label included, at its derived position) */
+ | {
+    type: "text";
+    element: NonDeleted<ExcalidrawTextElement>;
+}
+/** binds a new label to this empty container (an arrow included) */
+ | {
+    type: "container";
+    element: NonDeleted<ExcalidrawTextContainer>;
+}
+/** creates free text at the pointer */
+ | {
+    type: "free";
+};
+/**
+ * The text tool's pointer interaction.
+ *
+ * Everything hangs off one question — what would a click at this position
+ * do (`getTargetAt`)? — answered once and used for the hover affordance
+ * (`appState.textToolHover`), the cursor and the pointerdown itself, so the
+ * affordance can never promise something the click won't deliver.
+ *
+ * A click on an empty container's center is armed on pointerdown and
+ * committed on pointerup as a bound label; dragging past the autowrap
+ * threshold first turns it into a free fixed-width text at the origin
+ * instead.
+ *
+ * Text editing itself (`app.text.startTextEditing`, see `AppText`) is
+ * shared with Enter, double-click and the other entry points.
+ */
+export declare class AppTextTool {
+    private app;
+    constructor(app: App);
+    /**
+     * A click on an empty container's center, armed on pointerdown and decided
+     * on the pointer's way out: a click binds a label, a drag creates free
+     * text instead. Deferring is what keeps the drag from first binding to
+     * (and provisionally enlarging) the container.
+     */
+    private pending;
+    /**
+     * The modifiers the hover was last resolved with — what a refresh without
+     * an event of its own (the viewport moving under a still pointer) uses.
+     */
+    private lastModifiers;
+    /**
+     * What a click at this position would do, in the order the click resolves
+     * it: a free arrow endpoint (the smaller, more deliberate target; z-aware,
+     * and off while ctrl/cmd disables binding) → the text under the pointer,
+     * which the click edits → an empty container near its center, which gets
+     * a label unless ctrl/cmd opts out → free text at the pointer.
+     *
+     * Ctrl/cmd is "no binding" throughout the tool, as elsewhere in the
+     * editor. For the container it is read off the event rather than the
+     * arrow-binding preference: a label is not an arrow binding.
+     */
+    getTargetAt: (scenePointer: ScenePoint, modifiers: Modifiers) => TextToolTarget;
+    /**
+     * Keeps `appState.textToolHover` — the affordance for what a click would
+     * do — in sync with the pointer, and returns the target (for the cursor).
+     * Suppressed while something else owns the interaction: a text being
+     * edited or drag-sized, a multi-point element, a box selection, a drag of
+     * the selection, or the pointer over a scrollbar.
+     */
+    updateHover: (scenePointer: ScenePoint, modifiers: Modifiers, isOverScrollBar?: boolean) => TextToolTarget | null;
+    /**
+     * Re-resolves the hover — and the cursor that goes with it — where the
+     * pointer last was, for what changes a click's outcome without the pointer
+     * moving: the ctrl/cmd toggle (pass its event), or the viewport scrolling
+     * or zooming under the pointer (no event; the last modifiers stand). The
+     * scene position is re-derived from the pointer's viewport position, so a
+     * moved viewport resolves what is under the pointer now.
+     *
+     * Nothing to refresh with another tool or without a hovering pointer — a
+     * finger never hovers (its last move is where it lifted), and the
+     * affordance a press armed is cleared when the press resolves or is
+     * canceled. The cursor is left to viewport navigation (space/wheel
+     * panning, a scrollbar drag, the hand tool), as on pointermove.
+     */
+    refresh: (modifiers?: Modifiers) => void;
+    /**
+     * Drops a pending center click without acting on it — the tool was left,
+     * the browser took the pointer (pointercancel), or a second finger turned
+     * the press into a pinch/pan — so no pointerup of ours will decide it. The
+     * outline it armed goes with it: while pending, the hover is that click's.
+     */
+    cancel: () => void;
+    clearHover: () => void;
+    private setHover;
+    /**
+     * The cursor for what a click would do: a pointer over the arrow anchors
+     * text would attach to, a text cursor over text the click would edit, the
+     * tool's crosshair otherwise — also while the affordance is suppressed
+     * (editing, drag-sizing), where a click has nothing to point at.
+     */
+    cursorFor: (target: TextToolTarget | null) => string;
+    handlePointerDown: (event: React.PointerEvent<HTMLElement>, pointerDownState: PointerDownState) => void;
+    /**
+     * The pointer-move half of a pending center click. Once the pointer has
+     * moved past the autowrap threshold the click is a drag: free text is
+     * created at the origin and sized by the drag from here on. Horizontal
+     * only (a text is only ever sized that way) and in screen space, and
+     * deliberately wider than the generic drag threshold so a jittery click
+     * still binds. Returns whether a pending click owned the move.
+     */
+    handlePointerMove: (event: PointerEvent, pointerDownState: PointerDownState) => boolean;
+    /**
+     * The pointer-up half: a genuine pointerup binds the label. The
+     * missing-pointerup cleanup replays this with the pointerdown event (a
+     * second finger landing mid-press), and a tool switch orphans the click —
+     * both discard it instead.
+     */
+    handlePointerUp: (event: PointerEvent, pointerDownState: PointerDownState) => void;
+    private isDrag;
+    private resolvePending;
+    /**
+     * The click has been acted on: drop the affordance, revert the tool unless
+     * it is locked, restore the cursor.
+     */
+    private finish;
+}
+export {};

package/dist/types/excalidraw/components/App.viewport.d.ts

@@ -40,6 +40,43 @@ export declare class AppViewport {
      * user pan/zoom input. */
     get isLockedTransitionPending(): boolean;
     invalidateUIOffset: (name: ViewportUIName) => void;
+    /**
+     * The side a rendered side UI (`data-viewport-ui="side"`) docks to, and
+     * how far it reaches into the canvas from it, in screen px.
+     */
+    private measureSide;
+    /**
+     * The side a named surface docks to while it's hidden, and how far it
+     * reaches into the canvas from it: as last measured, else approximately.
+     */
+    private getReservedSide;
+    private querySideUI;
+    /**
+     * Where a rendered side UI is, relative to the editor's container, in
+     * screen px; null when it isn't rendered.
+     */
+    getSideUIRect: (name: ViewportUIName) => {
+        left: number;
+        right: number;
+        top: number;
+        bottom: number;
+    } | null;
+    /**
+     * How far the named side UIs reach into the canvas, in screen px, from
+     * the left and the right: the part of the canvas they cover. Zero at a
+     * side none of them is rendered at — e.g. with the sidebar closed, or on
+     * phones, where it's an overlay that doesn't count as viewport UI — unless
+     * a hidden one is reserved (see `ViewportOffsetsOptions.reserve`).
+     */
+    getSideInsets: (names: readonly ViewportUIName[], opts?: Pick<ViewportOffsetsOptions, "reserve">) => {
+        left: number;
+        right: number;
+    };
+    /** How far the sidebar reaches into the canvas (see `getSideInsets`). */
+    getSidebarInsets: () => {
+        left: number;
+        right: number;
+    };
     /**
      * Resolves user-supplied viewport offsets into concrete per-side pixel
      * values. Static sides take precedence over UI-derived sides.
@@ -54,7 +91,10 @@ export declare class AppViewport {
     resolveInitialViewport: (opts: Omit<SetViewportOptions, "animation">, elementsMap: NonDeletedSceneElementsMap, appState: AppState) => (Viewport & {
         scrollConstraints: ScrollConstraints | null;
     }) | null;
-    /** Navigates to a target and optionally installs scroll/zoom constraints. */
+    /**
+     * Navigates to a target and optionally installs scroll/zoom constraints.
+     * Navigating stops following a collaborator, as a user's pan does.
+     */
     setViewport: (opts: SetViewportOptions | null) => void;
     /** Use when changing scrollX/scrollY/zoom based on user interaction. */
     translate: <K extends keyof AppState>(state: AppState | Pick<AppState, K> | null | ((prevState: Readonly<AppState>, props: Readonly<AppProps>) => AppState | Pick<AppState, K> | null), opts?: {

package/dist/types/excalidraw/components/FileDropOverlay.d.ts

@@ -0,0 +1,2 @@
+import "./FileDropOverlay.scss";
+export declare const FileDropOverlay: () => import("react/jsx-runtime").JSX.Element | null;

package/dist/types/excalidraw/components/LibraryMenuSection.d.ts

@@ -15,9 +15,13 @@ interface Props {
     isItemSelected: (id: LibraryItem["id"] | null) => boolean;
     svgCache: SvgCache;
     itemsRenderedPerBatch: number;
+    /** larger items with their name below */
+    showNames?: boolean;
 }
-export declare const LibraryMenuSectionGrid: ({ children, }: {
+export declare const LibraryMenuSectionGrid: ({ children, showNames, }: {
     children: ReactNode;
+    /** fewer columns, for items rendered with `showNames` */
+    showNames?: boolean;
 }) => import("react/jsx-runtime").JSX.Element;
-export declare const LibraryMenuSection: React.MemoExoticComponent<({ items, onItemSelectToggle, onItemDrag, isItemSelected, onClick, svgCache, itemsRenderedPerBatch, }: Props) => import("react/jsx-runtime").JSX.Element>;
+export declare const LibraryMenuSection: React.MemoExoticComponent<({ items, onItemSelectToggle, onItemDrag, isItemSelected, onClick, svgCache, itemsRenderedPerBatch, showNames, }: Props) => import("react/jsx-runtime").JSX.Element>;
 export {};

package/dist/types/excalidraw/components/LibraryUnit.d.ts

@@ -1,8 +1,11 @@
 import "./LibraryUnit.scss";
 import type { LibraryItem } from "../types";
 import type { SvgCache } from "../hooks/useLibraryItemSvg";
-export declare const LibraryUnit: import("react").MemoExoticComponent<({ id, elements, isPending, onClick, selected, onToggle, onDrag, svgCache, }: {
+export declare const LibraryUnit: import("react").MemoExoticComponent<({ id, name, showName, elements, isPending, onClick, selected, onToggle, onDrag, svgCache, }: {
     id: LibraryItem["id"] | /** for pending item */ null;
+    name?: LibraryItem["name"];
+    /** render larger, with the name below the item */
+    showName?: boolean;
     elements?: LibraryItem["elements"];
     isPending?: boolean;
     onClick: (id: LibraryItem["id"] | null) => void;
@@ -11,4 +14,6 @@ export declare const LibraryUnit: import("react").MemoExoticComponent<({ id, ele
     onDrag: (id: string, event: React.DragEvent) => void;
     svgCache: SvgCache;
 }) => import("react/jsx-runtime").JSX.Element>;
-export declare const EmptyLibraryUnit: () => import("react/jsx-runtime").JSX.Element;
+export declare const EmptyLibraryUnit: ({ showName }: {
+    showName?: boolean;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/types/excalidraw/components/Tooltip.d.ts

@@ -7,12 +7,26 @@ export declare const updateTooltipPosition: (tooltip: HTMLDivElement, item: {
     width: number;
     height: number;
 }, position?: "bottom" | "top") => void;
+export declare const hideTooltip: () => void;
+/**
+ * Shows the tooltip for `item`. For elements that can't be wrapped
+ * in <Tooltip>. Pair with `hideTooltip()`.
+ */
+export declare const showTooltip: (item: HTMLElement, label: string, { long, delay, position, }?: {
+    long?: boolean;
+    /** show after a short delay (unless a tooltip was visible just now) */
+    delay?: boolean;
+    position?: "bottom" | "top";
+}) => void;
 type TooltipProps = {
     children: React.ReactNode;
     label: string;
     long?: boolean;
     style?: React.CSSProperties;
+    className?: string;
     disabled?: boolean;
+    /** show after a short delay (unless a tooltip was visible just now) */
+    delay?: boolean;
 };
-export declare const Tooltip: ({ children, label, long, style, disabled, }: TooltipProps) => import("react/jsx-runtime").JSX.Element | null;
+export declare const Tooltip: ({ children, label, long, style, className, disabled, delay, }: TooltipProps) => import("react/jsx-runtime").JSX.Element | null;
 export {};

package/dist/types/excalidraw/components/main-menu/DefaultItems.d.ts

@@ -78,6 +78,7 @@ export declare const Preferences: {
     ToggleSnapMode: () => import("react/jsx-runtime").JSX.Element;
     ToggleArrowBinding: () => import("react/jsx-runtime").JSX.Element;
     ToggleMidpointSnapping: () => import("react/jsx-runtime").JSX.Element;
+    ToggleShowHints: () => import("react/jsx-runtime").JSX.Element;
     ToggleGridMode: () => import("react/jsx-runtime").JSX.Element;
     ToggleZenMode: () => import("react/jsx-runtime").JSX.Element;
     ToggleViewMode: () => import("react/jsx-runtime").JSX.Element | null;

package/dist/types/excalidraw/data/blob.d.ts

@@ -78,7 +78,14 @@ fileHandle?: FileSystemFileHandle | null) => Promise<{
                 element: import("@excalidraw/element/types").NonDeleted<import("@excalidraw/element/types").ExcalidrawBindableElement>;
                 midPoint?: import("@excalidraw/math").GlobalPoint;
             } | null;
-            hoveredArrowTextAnchor: {
+            textToolHover: {
+                type: "text";
+                elementId: ExcalidrawElement["id"];
+            } | {
+                type: "container";
+                elementId: ExcalidrawElement["id"];
+            } | {
+                type: "arrow";
                 elementId: import("@excalidraw/element/types").ExcalidrawArrowElement["id"];
                 anchor: "start" | "end" | "label";
             } | null;
@@ -114,6 +121,7 @@ fileHandle?: FileSystemFileHandle | null) => Promise<{
             resizingElement: import("@excalidraw/element/types").NonDeletedExcalidrawElement | null;
             boxSelectionMode: import("../types").BoxSelectionMode;
             bindingPreference: "enabled" | "disabled";
+            showHints: boolean;
             inputDevice: import("../types").InputDevice;
             editingFrame: import("@excalidraw/element/types").ExcalidrawFrameLikeElement["id"] | null;
             preferredSelectionTool: {
@@ -258,7 +266,14 @@ fileHandle?: FileSystemFileHandle | null) => Promise<{
             element: import("@excalidraw/element/types").NonDeleted<import("@excalidraw/element/types").ExcalidrawBindableElement>;
             midPoint?: import("@excalidraw/math").GlobalPoint;
         } | null;
-        hoveredArrowTextAnchor: {
+        textToolHover: {
+            type: "text";
+            elementId: ExcalidrawElement["id"];
+        } | {
+            type: "container";
+            elementId: ExcalidrawElement["id"];
+        } | {
+            type: "arrow";
             elementId: import("@excalidraw/element/types").ExcalidrawArrowElement["id"];
             anchor: "start" | "end" | "label";
         } | null;
@@ -294,6 +309,7 @@ fileHandle?: FileSystemFileHandle | null) => Promise<{
         resizingElement: import("@excalidraw/element/types").NonDeletedExcalidrawElement | null;
         boxSelectionMode: import("../types").BoxSelectionMode;
         bindingPreference: "enabled" | "disabled";
+        showHints: boolean;
         inputDevice: import("../types").InputDevice;
         editingFrame: import("@excalidraw/element/types").ExcalidrawFrameLikeElement["id"] | null;
         preferredSelectionTool: {

package/dist/types/excalidraw/data/json.d.ts

@@ -76,7 +76,14 @@ export declare const loadFromJSON: (localAppState: AppState, localElements: read
             element: import("@excalidraw/element/types").NonDeleted<import("@excalidraw/element/types").ExcalidrawBindableElement>;
             midPoint?: import("@excalidraw/math").GlobalPoint;
         } | null;
-        hoveredArrowTextAnchor: {
+        textToolHover: {
+            type: "text";
+            elementId: ExcalidrawElement["id"];
+        } | {
+            type: "container";
+            elementId: ExcalidrawElement["id"];
+        } | {
+            type: "arrow";
             elementId: import("@excalidraw/element/types").ExcalidrawArrowElement["id"];
             anchor: "start" | "end" | "label";
         } | null;
@@ -112,6 +119,7 @@ export declare const loadFromJSON: (localAppState: AppState, localElements: read
         resizingElement: import("@excalidraw/element/types").NonDeletedExcalidrawElement | null;
         boxSelectionMode: import("../types").BoxSelectionMode;
         bindingPreference: "enabled" | "disabled";
+        showHints: boolean;
         inputDevice: import("../types").InputDevice;
         editingFrame: import("@excalidraw/element/types").ExcalidrawFrameLikeElement["id"] | null;
         preferredSelectionTool: {

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

@@ -1,6 +1,6 @@
 import type { IMAGE_MIME_TYPES, UserIdleState, throttleRAF, MIME_TYPES, EditorInterface, StrokeWidthKey } from "@excalidraw/common";
 import type { LinearElementEditor } from "@excalidraw/element";
-import type { MaybeTransformHandleType } from "@excalidraw/element";
+import type { ListMarkerAdvance, MaybeTransformHandleType } from "@excalidraw/element";
 import type { PointerType, ExcalidrawLinearElement, NonDeletedExcalidrawElement, NonDeleted, TextAlign, ExcalidrawElement, GroupId, ExcalidrawBindableElement, ExcalidrawArrowElement, Arrowhead, FontFamilyValues, FileId, Theme, StrokeRoundness, ExcalidrawEmbeddableElement, ExcalidrawMagicFrameElement, ExcalidrawFrameLikeElement, ExcalidrawElementType, ExcalidrawIframeLikeElement, OrderedExcalidrawElement, ExcalidrawNonSelectionElement, BindMode, ExcalidrawTextElement, StrokeVariability } from "@excalidraw/element/types";
 import type { Merge, MaybePromise, ValueOf, MakeBrand } from "@excalidraw/common/utility-types";
 import type { CaptureUpdateActionType, DurableIncrement, EphemeralIncrement, OnDuplicateData } from "@excalidraw/element";
@@ -141,7 +141,7 @@ export type InteractiveCanvasAppState = Readonly<_CommonCanvasAppState & {
     isMidpointSnappingEnabled: AppState["isMidpointSnappingEnabled"];
     gridModeEnabled: AppState["gridModeEnabled"];
     suggestedBinding: AppState["suggestedBinding"];
-    hoveredArrowTextAnchor: AppState["hoveredArrowTextAnchor"];
+    textToolHover: AppState["textToolHover"];
     isRotating: AppState["isRotating"];
     elementsToHighlight: AppState["elementsToHighlight"];
     collaborators: AppState["collaborators"];
@@ -260,6 +260,8 @@ export interface AppState {
     bindingPreference: "enabled" | "disabled";
     /** user preference whether arrow snap to midpoints while binding */
     isMidpointSnappingEnabled: boolean;
+    /** user preference whether to show contextual hints above the toolbar */
+    showHints: boolean;
     /**
      * user preference for what the wheel does: with a `trackpad` a plain wheel
      * pans; with a `mouse` a plain wheel zooms. Ctrl/cmd+wheel (how a pinch is
@@ -277,11 +279,20 @@ export interface AppState {
         midPoint?: GlobalPoint;
     } | null;
     /**
-     * Where on a hovered arrow the text tool would attach text if clicked —
-     * a free endpoint (binds the arrow to a new text element positioned against
-     * that endpoint) or the arrow's midpoint (adds a label bound to the arrow).
+     * What a text-tool click at the hovered position would act on — the text
+     * it would edit, the empty container it would label, or the arrow anchor
+     * (a free endpoint, or the midpoint for a label) it would attach text to.
+     * `null` when the click would create free text, or the tool isn't active.
+     * Drives the hover affordance only.
      */
-    hoveredArrowTextAnchor: {
+    textToolHover: {
+        type: "text";
+        elementId: ExcalidrawElement["id"];
+    } | {
+        type: "container";
+        elementId: ExcalidrawElement["id"];
+    } | {
+        type: "arrow";
         elementId: ExcalidrawArrowElement["id"];
         anchor: "start" | "end" | "label";
     } | null;
@@ -296,6 +307,10 @@ export interface AppState {
      * frame-like element whose name is currently being edited
      */
     editingFrame: ExcalidrawFrameLikeElement["id"] | null;
+    /**
+     * Elements the UI highlights with a bounding-box outline — those that
+     * would get added to a frame being dragged/resized.
+     */
     elementsToHighlight: readonly NonDeletedExcalidrawElement[] | null;
     /**
      * set when a new text is created or when an existing text is being edited
@@ -472,7 +487,7 @@ export type SearchMatch = {
         showOnCanvas: boolean;
     }[];
 };
-export type UIAppState = Omit<AppState, "cursorButton" | "scrollX" | "scrollY" | "zoom" | "shouldCacheIgnoreZoom" | "snapLines" | "originSnapOffset" | "suggestedBinding" | "hoveredArrowTextAnchor" | "frameToHighlight" | "elementsToHighlight">;
+export type UIAppState = Omit<AppState, "cursorButton" | "scrollX" | "scrollY" | "zoom" | "shouldCacheIgnoreZoom" | "snapLines" | "originSnapOffset" | "suggestedBinding" | "textToolHover" | "frameToHighlight" | "elementsToHighlight">;
 export type NormalizedZoomValue = number & {
     _brand: "normalizedZoom";
 };
@@ -961,7 +976,7 @@ export type AppClassProperties = {
     scene: App["scene"];
     syncActionResult: App["syncActionResult"];
     fonts: App["fonts"];
-    pasteFromClipboard: App["pasteFromClipboard"];
+    clipboard: App["clipboard"];
     id: App["id"];
     onInsertElements: App["onInsertElements"];
     onExportImage: App["onExportImage"];
@@ -979,11 +994,14 @@ export type AppClassProperties = {
     flowchart: App["flowchart"];
     drawShape: App["drawShape"];
     arrowText: App["arrowText"];
+    textTool: App["textTool"];
     cursor: App["cursor"];
     bucketFill: App["bucketFill"];
     duplicate: App["duplicate"];
     toolDrag: App["toolDrag"];
     activeResizeHandle: App["activeResizeHandle"];
+    selectionTool: App["selectionTool"];
+    modifiers: App["modifiers"];
     isToolLocked: App["isToolLocked"];
     getEffectiveGridSize: App["getEffectiveGridSize"];
     setPlugins: App["setPlugins"];
@@ -1036,7 +1054,10 @@ export type PointerDownState = Readonly<{
         element: NonDeleted<ExcalidrawElement> | null;
         allHitElements: NonDeleted<ExcalidrawElement>[];
         wasAddedToSelection: boolean;
+        cycleTarget: NonDeleted<ExcalidrawElement> | null;
         hasBeenDuplicated: boolean;
+        advancedListMarkers: readonly ListMarkerAdvance[];
+        editedTextId: ExcalidrawTextElement["id"] | null;
         hasHitCommonBoundingBoxOfSelectedElements: boolean;
         arrowLabel: boolean;
     };
@@ -1270,9 +1291,10 @@ export type ViewportOffsets = Offsets & {
 /**
  * Value of the `data-viewport-ui-name` attribute, identifying a
  * conditionally-rendered surface (marked with `data-viewport-ui`) so that
- * `getViewportOffsets` can reserve space for it while it's hidden (see the
- * `reserve` option). Whenever a named surface is rendered, its measured
- * footprint is remembered; reserving uses that remembered footprint, or an
- * approximate default if the surface hasn't been rendered yet.
+ * it can be measured on its own, and so that `getViewportOffsets` can
+ * reserve space for it while it's hidden (see the `reserve` option).
+ * Whenever a named surface is rendered, its measured footprint is
+ * remembered; reserving uses that remembered footprint, or an approximate
+ * default if the surface hasn't been rendered yet.
  */
-export type ViewportUIName = "sidebar" | "stylesPanel";
+export type ViewportUIName = "sidebar" | "stylesPanel" | "stats";