@excalidraw/math 0.18.0-a9ca16e → 0.18.0-ab0255f

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

@@ -1,7 +1,7 @@
-import type { IMAGE_MIME_TYPES, UserIdleState, throttleRAF, MIME_TYPES, EditorInterface } from "@excalidraw/common";
+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 { PointerType, ExcalidrawLinearElement, NonDeletedExcalidrawElement, NonDeleted, TextAlign, ExcalidrawElement, GroupId, ExcalidrawBindableElement, Arrowhead, FontFamilyValues, FileId, Theme, StrokeRoundness, ExcalidrawEmbeddableElement, ExcalidrawMagicFrameElement, ExcalidrawFrameLikeElement, ExcalidrawElementType, ExcalidrawIframeLikeElement, OrderedExcalidrawElement, ExcalidrawNonSelectionElement, BindMode, ExcalidrawTextElement } from "@excalidraw/element/types";
+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 } from "@excalidraw/element";
 import type { GlobalPoint } from "@excalidraw/math";
@@ -13,6 +13,7 @@ import type Library from "./data/library";
 import type { ContextMenuItems } from "./components/ContextMenu";
 import type { SnapLine } from "./snapping";
 import type { ImportedDataState } from "./data/types";
+import type { SetViewportOptions } from "./viewport";
 import type { Language } from "./i18n";
 import type { isOverScrollBars } from "./scene/scrollbars";
 import type React from "react";
@@ -84,7 +85,7 @@ export type BinaryFileData = {
 };
 export type BinaryFileMetadata = Omit<BinaryFileData, "dataURL">;
 export type BinaryFiles = Record<ExcalidrawElement["id"], BinaryFileData>;
-export type ToolType = "selection" | "lasso" | "rectangle" | "diamond" | "ellipse" | "arrow" | "line" | "freedraw" | "text" | "image" | "eraser" | "hand" | "frame" | "magicframe" | "embeddable" | "laser";
+export type ToolType = "selection" | "lasso" | "rectangle" | "diamond" | "ellipse" | "arrow" | "line" | "freedraw" | "text" | "image" | "eraser" | "hand" | "frame" | "magicframe" | "embeddable" | "laser" | "autoshape" | "bucketfill";
 export type ElementOrToolType = ExcalidrawElementType | ToolType | "custom";
 export type ActiveTool = {
     type: ToolType;
@@ -138,7 +139,9 @@ export type InteractiveCanvasAppState = Readonly<_CommonCanvasAppState & {
     newElement: AppState["newElement"];
     isBindingEnabled: AppState["isBindingEnabled"];
     isMidpointSnappingEnabled: AppState["isMidpointSnappingEnabled"];
+    gridModeEnabled: AppState["gridModeEnabled"];
     suggestedBinding: AppState["suggestedBinding"];
+    hoveredArrowTextAnchor: AppState["hoveredArrowTextAnchor"];
     isRotating: AppState["isRotating"];
     elementsToHighlight: AppState["elementsToHighlight"];
     collaborators: AppState["collaborators"];
@@ -172,6 +175,42 @@ export type ObservedElementsAppState = {
     lockedMultiSelections: AppState["lockedMultiSelections"];
     activeLockedId: AppState["activeLockedId"];
 };
+export type BoxSelectionMode = "contain" | "overlap";
+/**
+ * A box, in scene coordinates, that pan & zoom are constrained to.
+ *
+ * This is a private type. For public API, only use specific properties,
+ * needed.
+ */
+export type ScrollConstraints = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** when set, panning is constrained so the viewport stays within the box */
+    lockScroll: boolean;
+    /** when set, the viewport cannot zoom out below `zoom` */
+    lockZoom: boolean;
+    /**
+     * The zoom resolved after the `setViewport` navigation settled.
+     */
+    zoom: number;
+    /**
+     * Pixel amount the viewport may overscroll past its resting clamp before
+     * snapping back (rubberband). Screen pixels, zoom-independent. Resolved
+     * from `lock.overscroll` at the time the lock was installed (`true` →
+     * default give, `false` → 0).
+     */
+    overscroll: number;
+    /**
+     * Extra scrollable margin around the box (CSS-style), letting the viewport
+     * scroll past each box edge to reveal that much empty space. Values are
+     * viewport pixels and zoom-independent (a fixed on-screen distance).
+     * Resolved from the `offsets` passed to `setViewport` (see
+     * {@link ViewportOffsets}) at the time the lock was installed.
+     */
+    offsets?: Offsets;
+};
 export interface AppState {
     contextMenu: {
         items: ContextMenuItems;
@@ -210,15 +249,29 @@ export interface AppState {
      * `bindingPreference` and keyboard modifiers (ctrl/alt)
      */
     isBindingEnabled: boolean;
+    /** user box selection preference; defaults to "contain" when unset */
+    boxSelectionMode: BoxSelectionMode;
     /** user arrow binding preference */
     bindingPreference: "enabled" | "disabled";
     /** user preference whether arrow snap to midpoints while binding */
     isMidpointSnappingEnabled: boolean;
-    startBoundElement: NonDeleted<ExcalidrawBindableElement> | null;
+    /**
+     * The bindable element the UI highlights for the user when an arrow is
+     * dragged or otherwise its endpoint being close to said element.
+     */
     suggestedBinding: {
         element: NonDeleted<ExcalidrawBindableElement>;
         midPoint?: GlobalPoint;
     } | 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).
+     */
+    hoveredArrowTextAnchor: {
+        elementId: ExcalidrawArrowElement["id"];
+        anchor: "start" | "end" | "label";
+    } | null;
     frameToHighlight: NonDeleted<ExcalidrawFrameLikeElement> | null;
     frameRendering: {
         enabled: boolean;
@@ -226,8 +279,11 @@ export interface AppState {
         outline: boolean;
         clip: boolean;
     };
-    editingFrame: string | null;
-    elementsToHighlight: NonDeleted<ExcalidrawElement>[] | null;
+    /**
+     * frame-like element whose name is currently being edited
+     */
+    editingFrame: ExcalidrawFrameLikeElement["id"] | null;
+    elementsToHighlight: readonly NonDeletedExcalidrawElement[] | null;
     /**
      * set when a new text is created or when an existing text is being edited
      */
@@ -254,9 +310,10 @@ export interface AppState {
     currentItemStrokeColor: string;
     currentItemBackgroundColor: string;
     currentItemFillStyle: ExcalidrawElement["fillStyle"];
-    currentItemStrokeWidth: number;
+    currentItemStrokeWidthKey: StrokeWidthKey;
     currentItemStrokeStyle: ExcalidrawElement["strokeStyle"];
     currentItemRoughness: number;
+    currentItemStrokeVariability: StrokeVariability;
     currentItemOpacity: number;
     currentItemFontFamily: FontFamilyValues;
     currentItemFontSize: number;
@@ -269,6 +326,7 @@ export interface AppState {
     viewBackgroundColor: string;
     scrollX: number;
     scrollY: number;
+    scrollConstraints: ScrollConstraints | null;
     cursorButton: "up" | "down";
     scrolledOutside: boolean;
     name: string | null;
@@ -386,7 +444,7 @@ export type SearchMatch = {
         showOnCanvas: boolean;
     }[];
 };
-export type UIAppState = Omit<AppState, "startBoundElement" | "cursorButton" | "scrollX" | "scrollY">;
+export type UIAppState = Omit<AppState, "cursorButton" | "scrollX" | "scrollY" | "zoom" | "shouldCacheIgnoreZoom" | "snapLines" | "originSnapOffset" | "suggestedBinding" | "hoveredArrowTextAnchor" | "frameToHighlight" | "elementsToHighlight">;
 export type NormalizedZoomValue = number & {
     _brand: "normalizedZoom";
 };
@@ -430,6 +488,9 @@ export type LibraryItemsSource = ((currentLibraryItems: LibraryItems) => MaybePr
 export type ExcalidrawInitialDataState = Merge<ImportedDataState, {
     libraryItems?: MaybePromise<Required<ImportedDataState>["libraryItems"]>;
 }>;
+export type ExcalidrawInitialState = {
+    viewport?: Omit<SetViewportOptions, "animation">;
+};
 export type OnUserFollowedPayload = {
     userToFollow: UserToFollow;
     action: "FOLLOW" | "UNFOLLOW";
@@ -440,13 +501,120 @@ export type OnExportProgress = {
     /** 0-1 range */
     progress?: number;
 };
+export type InteractionConfig = {
+    /**
+     * Interactions that stay enabled while the editor is otherwise
+     * non-interactive. Opt-in: anything omitted or `false` is disabled.
+     */
+    enabled?: {
+        /**
+         * Element links render their link icon and stay clickable — clicking
+         * anywhere on a linked element opens the link, same as in view mode.
+         * When disabled, link icons are not rendered at all.
+         *
+         * @default false
+         */
+        links?: boolean;
+        /**
+         * Embeddable & iframe elements stay interactive — hovering & clicking
+         * activates them so their content can be used, same as in view mode.
+         *
+         * @default false
+         */
+        embeds?: boolean;
+        /**
+         * Umbrella for all interactive content on canvas — shorthand for
+         * enabling `links` & `embeds` (and future interactive content kinds)
+         * together. Additive: `interactiveContent: true` enables them
+         * regardless of their individual values.
+         *
+         * @default false
+         */
+        interactiveContent?: boolean;
+        /**
+         * Canvas navigation — panning (pointer drag, wheel, PageUp/PageDown)
+         * and zooming (ctrl/cmd + wheel, pinch, and the canvas zoom &
+         * zoom-to-fit shortcuts: ctrl/cmd +/-/0, shift+1/2/3), same as in view
+         * mode. Respects `appState.scrollConstraints` if set, so it composes
+         * with viewport locking. The rest of the keyboard stays disabled. Note
+         * the editor consumes wheel & touch input again when enabled, so the
+         * page no longer scrolls over the editor.
+         *
+         * @default false
+         */
+        navigation?: boolean;
+        /**
+         * Whether the browser's own zoom remains available over the editor —
+         * ctrl/cmd + wheel, pinch, and (while the editor has focus)
+         * ctrl/cmd +/-/0 shortcuts. Prevented by default, mirroring the
+         * interactive editor. Regular page scrolling stays available either way.
+         * With `navigation` enabled, the zoom input (wheel, pinch, keyboard
+         * shortcuts) zooms the canvas instead either way, making this moot.
+         *
+         * @default false
+         */
+        browserZoom?: boolean;
+        /**
+         * Tools that stay user-driven while the editor is otherwise
+         * non-interactive: pointer input keeps driving the listed tool when it's
+         * the active tool. Does not enable user-driven tool *switching* — the
+         * keyboard stays disabled and tool selection remains host-driven
+         * (`ExcalidrawAPI.setActiveTool`).
+         *
+         * Composes with `navigation`: the enabled tool wins the primary-pointer
+         * drag, while wheel input (and wheel-button drag) still pans/zooms.
+         */
+        tools?: {
+            /**
+             * The laser pointer stays usable — pointer strokes draw laser trails
+             * and pointer positions keep broadcasting via `onPointerUpdate`, so
+             * e.g. collaborators see a presenter's laser & cursor.
+             *
+             * @default false
+             */
+            laser?: boolean;
+            /**
+             * Custom tools (`activeTool.type === "custom"`) stay usable — the
+             * editor keeps dispatching `onPointerDown` / `onPointerUp` for them.
+             * Tool behavior is host-implemented; activate custom tools with
+             * `locked: true` or they revert to the selection tool (and go inert)
+             * after the first pointer interaction.
+             *
+             * @default false
+             */
+            custom?: boolean;
+        };
+    };
+};
+export type UIConfig = {
+    /**
+     * Default UI controls that stay enabled while the rest of Excalidraw's
+     * default UI is hidden. Opt-in: anything omitted or `false` is disabled.
+     */
+    enabled: {
+        /**
+         * The zoom-out, reset-zoom, and zoom-in controls.
+         *
+         * @default false
+         */
+        zoom?: boolean;
+        /**
+         * The button shown when the viewport is scrolled away from all content.
+         *
+         * @default false
+         */
+        scrollBackToContent?: boolean;
+    };
+};
 export interface ExcalidrawProps {
     onChange?: (elements: readonly OrderedExcalidrawElement[], appState: AppState, files: BinaryFiles) => void;
+    onThemeChange?: (theme: Theme | "system") => void;
     /**
      * note: only subscribes if the props.onIncrement is defined on initial render
      */
     onIncrement?: (event: DurableIncrement | EphemeralIncrement) => void;
     initialData?: (() => MaybePromise<ExcalidrawInitialDataState | null>) | MaybePromise<ExcalidrawInitialDataState | null>;
+    initialState?: ExcalidrawInitialState;
     /**
      * Invoked as soon as the Excalidraw API is available
      * NOTE editor is not yet mounted, and state is not yet initialized
@@ -493,6 +661,70 @@ export interface ExcalidrawProps {
     renderTopRightUI?: (isMobile: boolean, appState: UIAppState) => JSX.Element | null;
     langCode?: Language["code"];
     viewModeEnabled?: boolean;
+    /**
+     * Whether the editor accepts user input (pointer, keyboard, wheel, touch,
+     * clipboard, drag&drop). When `false`, the scene still renders and reacts
+     * to programmatic updates (imperative API), but the user cannot affect it
+     * in any way. Implies view mode.
+     *
+     * Pass a config object to keep specific interactions enabled while the
+     * editor is otherwise non-interactive (see `InteractionConfig`):
+     *
+     * ```tsx
+     * <Excalidraw interaction={{ enabled: { links: true } }} />
+     * ```
+     *
+     * @default true
+     */
+    interaction?: boolean | InteractionConfig;
+    /**
+     * Whether Excalidraw's default UI is rendered — toolbar, default menus,
+     * footer controls, sidebars, and canvas popups. Host UI passed through
+     * children (including exported components such as `MainMenu` and `Footer`)
+     * or render props continues to render, together with any supporting dialogs
+     * it opens.
+     *
+     * Canvas content (elements, text editing surface, frame names, embeds) still
+     * renders, and the editor remains interactive unless `interaction` is set to
+     * `false`.
+     *
+     * Pass a config object to keep specific default controls rendered while the
+     * rest of the default UI is hidden (see `UIConfig`):
+     *
+     * ```tsx
+     * <Excalidraw ui={{ enabled: { zoom: true } }} />
+     * ```
+     *
+     * NOTE: this is WIP and what default UI is/is not rendered when ui=false
+     * may yet change.
+     *
+     * @default true
+     */
+    ui?: boolean | UIConfig;
+    /**
+     * Forces the active editor tool (controlled). While set, user- and
+     * API-driven tool switching is ignored — `setActiveTool` refuses with a
+     * console warning, non-forced toolbar buttons render disabled — and the
+     * editor snaps back if internal flows reset the tool. The forced tool
+     * behaves as if locked (see the tool lock / padlock): it doesn't revert to
+     * the selection tool after use, and elements drawn with it aren't
+     * auto-selected — without mutating `appState.activeTool.locked`, so the
+     * user's persisted padlock preference stays untouched. Unset to return
+     * tool control to the editor (the current tool stays active).
+     *
+     * The forced tool must be activatable to take effect: not disabled via
+     * `UIOptions.tools`, and — while the editor is non-interactive — allowed
+     * via `interaction.enabled.tools`. Otherwise the editor stays on (or, when
+     * non-interactive, resets to) the `selection` tool, and the forced tool is
+     * applied once it becomes activatable. `image` cannot be forced (its
+     * activation opens the file picker).
+     */
+    activeTool?: {
+        type: Exclude<ToolType, "image">;
+    } | {
+        type: "custom";
+        customType: string;
+    };
     zenModeEnabled?: boolean;
     gridModeEnabled?: boolean;
     objectsSnapModeEnabled?: boolean;
@@ -501,6 +733,10 @@ export interface ExcalidrawProps {
     name?: string;
     renderCustomStats?: (elements: readonly NonDeletedExcalidrawElement[], appState: UIAppState) => JSX.Element;
     UIOptions?: Partial<UIOptions>;
+    /**
+     * dimensions and size constraints for inserted images
+     */
+    imageOptions?: ImageOptions;
     detectScroll?: boolean;
     handleKeyboardGlobally?: boolean;
     onLibraryChange?: (libraryItems: LibraryItems) => void | Promise<any>;
@@ -555,12 +791,21 @@ export type ExportOpts = {
     onExportToBackend?: (exportedElements: readonly NonDeletedExcalidrawElement[], appState: UIAppState, files: BinaryFiles) => void;
     renderCustomUI?: (exportedElements: readonly NonDeletedExcalidrawElement[], appState: UIAppState, files: BinaryFiles, canvas: HTMLCanvasElement) => JSX.Element;
 };
+export type ImageOptions = Partial<{
+    maxWidthOrHeight: number;
+    maxFileSizeBytes: number;
+}>;
 export type CanvasActions = Partial<{
     changeViewBackgroundColor: boolean;
     clearCanvas: boolean;
     export: false | ExportOpts;
     loadScene: boolean;
     saveToActiveFile: boolean;
+    /**
+     * defaults to true if `props.theme` is omitted or `props.onThemeChange`
+     * is supplied (at which point the theme is considered as host-app controlled),
+     * else default to false
+     * */
     toggleTheme: boolean | null;
     saveAsImage: boolean;
 }>;
@@ -584,6 +829,7 @@ export type AppProps = Merge<ExcalidrawProps, {
             export: ExportOpts;
         };
     }>;
+    imageOptions: Required<ImageOptions>;
     detectScroll: boolean;
     handleKeyboardGlobally: boolean;
     isCollaborating: boolean;
@@ -615,8 +861,7 @@ export type AppClassProperties = {
     id: App["id"];
     onInsertElements: App["onInsertElements"];
     onExportImage: App["onExportImage"];
-    lastViewportPosition: App["lastViewportPosition"];
-    scrollToContent: App["scrollToContent"];
+    viewport: App["viewport"];
     addFiles: App["addFiles"];
     addElementsFromPasteOrLibrary: App["addElementsFromPasteOrLibrary"];
     togglePenMode: App["togglePenMode"];
@@ -627,11 +872,13 @@ export type AppClassProperties = {
     onMagicframeToolSelect: App["onMagicframeToolSelect"];
     getName: App["getName"];
     dismissLinearEditor: App["dismissLinearEditor"];
-    flowChartCreator: App["flowChartCreator"];
+    flowchart: App["flowchart"];
+    drawShape: App["drawShape"];
+    cursor: App["cursor"];
+    isToolLocked: App["isToolLocked"];
     getEffectiveGridSize: App["getEffectiveGridSize"];
     setPlugins: App["setPlugins"];
     plugins: App["plugins"];
-    getEditorUIOffsets: App["getEditorUIOffsets"];
     visibleElements: App["visibleElements"];
     excalidrawContainerValue: App["excalidrawContainerValue"];
     onPointerUpEmitter: App["onPointerUpEmitter"];
@@ -640,8 +887,11 @@ export type AppClassProperties = {
     onEvent: App["onEvent"];
     onStateChange: App["onStateChange"];
     lastPointerMoveCoords: App["lastPointerMoveCoords"];
+    lastPointerMoveEvent: App["lastPointerMoveEvent"];
     bindModeHandler: App["bindModeHandler"];
     setAppState: App["setAppState"];
+    isInteractionEnabled: App["isInteractionEnabled"];
+    isNavigationEnabled: App["isNavigationEnabled"];
 };
 export type PointerDownState = Readonly<{
     origin: Readonly<{
@@ -728,15 +978,16 @@ export interface ExcalidrawImperativeAPI {
     getAppState: () => InstanceType<typeof App>["state"];
     getFiles: () => InstanceType<typeof App>["files"];
     getName: InstanceType<typeof App>["getName"];
-    scrollToContent: InstanceType<typeof App>["scrollToContent"];
+    setViewport: InstanceType<typeof App>["viewport"]["setViewport"];
+    getViewportOffsets: InstanceType<typeof App>["viewport"]["getOffsets"];
     registerAction: (action: Action) => void;
     refresh: InstanceType<typeof App>["refresh"];
     setToast: InstanceType<typeof App>["setToast"];
     addFiles: (data: BinaryFileData[]) => void;
     id: string;
     setActiveTool: InstanceType<typeof App>["setActiveTool"];
-    setCursor: InstanceType<typeof App>["setCursor"];
-    resetCursor: InstanceType<typeof App>["resetCursor"];
+    setCursor: InstanceType<typeof App>["cursor"]["set"];
+    resetCursor: InstanceType<typeof App>["cursor"]["reset"];
     toggleSidebar: InstanceType<typeof App>["toggleSidebar"];
     getEditorInterface: () => EditorInterface;
     /**
@@ -759,7 +1010,6 @@ export type FrameNameBounds = {
     y: number;
     width: number;
     height: number;
-    angle: number;
 };
 export type FrameNameBoundsCache = {
     get: (frameElement: ExcalidrawFrameLikeElement | ExcalidrawMagicFrameElement) => FrameNameBounds | null;
@@ -778,12 +1028,12 @@ export type Primitive = number | string | boolean | bigint | symbol | null | und
 export type JSONValue = string | number | boolean | null | object;
 export type EmbedsValidationStatus = Map<ExcalidrawIframeLikeElement["id"], boolean>;
 export type ElementsPendingErasure = Set<ExcalidrawElement["id"]>;
-export type PendingExcalidrawElements = ExcalidrawElement[];
+export type PendingExcalidrawElements = NonDeletedExcalidrawElement[];
 /** Runtime gridSize value. Null indicates disabled grid. */
 export type NullableGridSize = (AppState["gridSize"] & MakeBrand<"NullableGridSize">) | null;
 export type GenerateDiagramToCode = (props: {
-    frame: ExcalidrawMagicFrameElement;
-    children: readonly ExcalidrawElement[];
+    frame: NonDeleted<ExcalidrawMagicFrameElement>;
+    children: readonly NonDeletedExcalidrawElement[];
 }) => MaybePromise<{
     html: string;
 }>;
@@ -793,3 +1043,102 @@ export type Offsets = Partial<{
     bottom: number;
     left: number;
 }>;
+/**
+ * Value of the `data-viewport-ui` attribute, marking a DOM node as a UI
+ * surface that occludes the canvas. Such nodes are measured by
+ * `getViewportOffsets` to compute the default per-side viewport offsets:
+ *
+ * - `top` / `bottom` — offsets that side by the node's bottom/top edge
+ * - `side` — a panel hugging the left or right edge. Which side is not
+ *   declared but resolved geometrically: if the node's horizontal center
+ *   lies in the left half of the viewport it counts against the left
+ *   offset (by its right edge), otherwise against the right offset (by
+ *   `viewportWidth - left edge`). Measuring the rendered position instead
+ *   of declaring a side means RTL layouts and host-configurable docking
+ *   (e.g. sidebar side) are handled for free — but it assumes the surface
+ *   actually hugs one edge; don't mark a centered/near-full-width node as
+ *   `side` (its midpoint would classify it to one side and the offset
+ *   would swallow most of the viewport).
+ *
+ * The attribute should only be present while the surface is actually
+ * rendered — omit it (don't just hide the node) when the surface shouldn't
+ * push the viewport around.
+ */
+export type ViewportUIDock = "top" | "bottom" | "side";
+/**
+ * Options for `getViewportOffsets` (and the `ui` key of
+ * {@link ViewportOffsets}), controlling how offsets are derived from the
+ * currently rendered editor UI.
+ *
+ * NOTE unlike the physical sides of {@link Offsets}, the horizontal values
+ * here are logical, i.e. flipped in RTL layouts (`left` refers to the
+ * reading-direction start side).
+ */
+export type ViewportOffsetsOptions = {
+    /** padding added to each measured side (default 24) */
+    padding?: number;
+    paddingTop?: number;
+    paddingRight?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
+    /** final value for the given side, replacing the measured UI size
+     * (padding is not added on top) */
+    top?: number;
+    bottom?: number;
+    left?: number;
+    right?: number;
+    /**
+     * Reserve space for the given conditionally-rendered surfaces even while
+     * they're hidden, so the resulting offsets don't shift when they
+     * (dis)appear. Uses the surface's last-measured footprint, falling back
+     * to an approximate default if it hasn't been rendered yet. Ignored on
+     * phones (where these surfaces never occlude the canvas).
+     */
+    reserve?: {
+        /** styles panel (rendered when a tool or selection is active) */
+        stylesPanel?: boolean;
+        /** sidebar (e.g. library) */
+        sidebar?: boolean;
+    };
+};
+/**
+ * Viewport offsets accepted by the `setViewport`-family APIs (`setViewport`,
+ * `props.initialState.viewport`), insetting the usable viewport area per
+ * side so the target isn't fitted/centered underneath overlaid UI.
+ *
+ * Two (combinable) ways to specify:
+ *
+ * - **Static sides** (`top`/`right`/`bottom`/`left`) — absolute pixel
+ *   values, used as-is: physical (not flipped in RTL), zoom-independent,
+ *   no padding added. Sides not specified default to `0` (unless `ui` is
+ *   set, see below).
+ *
+ * - **`ui`** — derive the offsets from the editor UI (toolbar, styles
+ *   panel, sidebar...) as rendered at the time the viewport is set,
+ *   equivalent to calling `getViewportOffsets()`. Pass `true` for the
+ *   defaults, or options ({@link ViewportOffsetsOptions}) to customize
+ *   padding or reserve space for currently-hidden surfaces.
+ *
+ * When both are given, a static side always wins for that side — it
+ * replaces whatever `ui` would yield (including `ui`'s own side overrides,
+ * which — unlike the physical static sides — are RTL-relative). The
+ * remaining sides fall back to the `ui`-derived values.
+ *
+ * @example
+ * { top: 40 }                              // top 40px, other sides 0
+ * { ui: true }                             // measured UI + default padding
+ * { ui: { reserve: { stylesPanel: true } } } // + keep space for hidden panel
+ * { top: 40, ui: true }                    // top exactly 40px, rest from UI
+ */
+export type ViewportOffsets = Offsets & {
+    ui?: true | ViewportOffsetsOptions;
+};
+/**
+ * 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.
+ */
+export type ViewportUIName = "sidebar" | "stylesPanel";