@dwelle/excalidraw 0.5.0-2dbdd6f → 0.5.0-2e5786f

package/CHANGELOG.md

@@ -11,8 +11,237 @@ The change should be grouped under one of the below section and must contain PR
 Please add the latest change on the top under the correct section.
 -->
 
+## Unreleased
+
+### Wheel navigation (2026-09-13) [#XXXX](https://github.com/excalidraw/excalidraw/pull/XXXX)
+
+- Scrolling while holding the wheel (middle) mouse button zooms the canvas around the pointer, the same as ctrl/cmd+wheel — a wheel-button pan can be zoomed one-handed, without reaching for a modifier.
+- New `appState.inputDevice` preference (`"auto" | "mouse" | "trackpad"`, default `"auto"`, persisted in browser storage) selecting the wheel mappings. With `"trackpad"` a plain wheel pans; with `"mouse"` a plain wheel zooms. Ctrl/cmd+wheel (how a pinch is delivered) zooms with either device. Shift+wheel pans horizontally, and ctrl/cmd+shift+wheel pans vertically. The wheel-button zoom above is unaffected. `"auto"` is reserved for detecting the device from the wheel events and resolves to `"trackpad"` until that is implemented (`resolveInputDevice()`). Set it from the new "Input device" radio in the main menu's preferences submenu, also exposed as `MainMenu.DefaultItems.Preferences.InputDevice`.
+
+### Sticky notes (2026-09-06) [#XXXX](https://github.com/excalidraw/excalidraw/pull/XXXX)
+
+- New `stickynote` element type and toolbar tool (`N`): an always-filled, flat-rendered note whose label auto-fits — the font shrinks from the user's size down to a minimum, and only then does the note grow in height (it never shrinks below the height the user gave it). Click to place a 250×250 note, drag to size it (previewed at the dragged size, snapped to a font-aware minimum on release); text editing starts right away.
+- Element model: the note carries `baseHeight` (the user's height; `height ≥ baseHeight`), its label carries `baseFontSize` (the user's font ceiling, `null`/absent on any other text) while `fontSize` holds the fitted size. Read a text element's user-facing size through `getBaseFontSize(text, elementsMap)`.
+- Sticky notes are their own color domain: new `appState.currentItemStickynoteStrokeColor` (the note's text color) and `appState.currentItemStickynoteBackgroundColor` defaults, and new customizable top-pick slots `appState.colorTopPicks.stickyNoteStroke` / `stickyNoteBackground`. The stroke and background pickers, both eyedroppers and paste-styles resolve their target (regular / sticky / mixed) at execution time. A note and its label share one ink (the stroke picker reads "Text color" for notes): coloring the label while editing colors the note too, binding a colored text gives the note its color, and the creation-date footer always paints in that ink.
+- Skeleton API: `convertToExcalidrawElements([{ type: "stickynote", x, y, label?: { text, fontSize? } }])` creates a note (and fitted label); see the element-skeleton docs.
+- Tools can be dragged out of the toolbar: drag the sticky note button onto the canvas to drop a default-sized note where you release it, previewed translucently while dragging (nothing reaches the scene, history or collaborators until the drop; Escape cancels). The mechanism is generic — other tools can opt in.
+- Toolbar: on desktop and tablet the image tool moved into the "More tools" menu (still `9`; `UIOptions.tools.image` keeps hiding it; the mobile toolbar keeps its image slot), and tool badges now show the letter shortcuts (`R`, `T`, `N`, …) instead of the numbers, which are no longer contiguous. The number keys keep working.
+- Each note shows its creation date (`element.created`) in a footer band — "7 Sep", or "7 Sep 2025" once the year differs — on canvas and in SVG/PNG exports. The band is reserved in the note's layout, so the label never overlaps it; notes without a timestamp keep the band empty.
+- Resize semantics: a note's corners resize proportionally by default and scale the label's font ceiling with the note (Shift frees them); its edges resize freely by default (Shift constrains them). Drag-creation is proportional by default too (Shift frees it) and never touches the font ceiling. Width-only gestures keep the base height, height gestures set it, aspect-locked multi-select and Stats group edits scale the ceiling; flips preserve everything. Arrows bound to a note follow it as it grows.
+
+## Excalidraw API
+
+### `setViewport` stops following a collaborator (2026-09-26) [#XXXX](https://github.com/excalidraw/excalidraw/pull/XXXX)
+
+- `setViewport` now asks to stop following a collaborator whenever it navigates (`onUserFollow` with `action: "UNFOLLOW"`, if `userToFollow` is set), as a user's pan or zoom does. `setViewport(null)` (clearing a lock) and a target that doesn't resolve don't navigate, and leave following alone.
+
+### `onDuplicate` can replace and veto duplicates (2026-09-18) [#XXXX](https://github.com/excalidraw/excalidraw/pull/XXXX)
+
+- `props.onDuplicate` may now return new objects for the duplicated elements in every duplication path. Previously the editor kept using the objects it created, so on paste (and library insert) the frame assignment and bound text redraw went to objects that were no longer in the scene, and alt-drag dragged an element that wasn't in the scene. The returned changes are now merged into the editor's duplicates, so they're part of the duplication's own undo entry and durable increment (no follow-up `updateScene` needed).
+- When pasting or inserting onto a frame, the duplicates passed to `onDuplicate` already have their `frameId` set (and are ordered under the frame).
+- Omitting a duplicate from the returned array (or returning it as deleted) now reliably prevents that element from being duplicated — previously pasting over a frame brought it back, and alt-drag broke. References to it from the remaining duplicates (bindings, `boundElements`, `frameId`) are cleared, and a bound text isn't duplicated without its container. If no duplicate remains, the duplication is cancelled and the returned elements are ignored: paste and the duplicate action do nothing, and alt-drag moves the original elements instead. When only some duplicates are vetoed during alt-drag, their originals stay where they were.
+- `onDuplicate` may return `false` to prevent the duplication as a whole (same as omitting every duplicate, without having to find them).
+- `onDuplicate` receives a third argument with lookups covering just the elements taking part in the duplication, so you don't have to derive them by scanning the scene: `{ duplicateElements, originalElements, origIdToDuplicateId, duplicateIdToOrigId }` — the duplicates by id, the elements they were made from by id, and their ids mapped in both directions (`duplicateIdToOrigId` to look up a duplicate's original while modifying it, `origIdToDuplicateId` e.g. for remapping element ids you keep in `customData`). On paste and library insert the originals are the inserted elements, which aren't part of the scene. The maps are read-only.
+
+### Host-controlled active tool (2026-07-14) [#11665](https://github.com/excalidraw/excalidraw/pull/11665)
+
+- Added `activeTool` prop (`{ type: ToolType } | { type: "custom"; customType: string }`) for forcing the active editor tool (controlled). While set, user- and API-driven tool switching is ignored — `setActiveTool` refuses non-matching activations with a console warning, non-forced toolbar buttons render disabled, and the tool-lock toggle (`Q`) is inert — and the editor snaps back if internal flows reset the tool (e.g. `restore()` on scene load). The forced tool behaves as if locked — it doesn't revert to selection after use and drawn elements aren't auto-selected — without mutating `appState.activeTool.locked`, so the user's persisted padlock preference stays untouched. Unset the prop 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 non-interactive) allowed via `interaction.enabled.tools`; otherwise the editor stays on the `selection` tool and applies the forced tool once it becomes activatable. `image` cannot be forced (its activation opens the file picker). Composes with `interaction.enabled.tools` for presentation-style hosts: force `laser` for the presenter, `selection` + `interaction={false}` for viewers.
+
+### User-driven tools while non-interactive (2026-07-14) [#11665](https://github.com/excalidraw/excalidraw/pull/11665)
+
+- Added `interaction.enabled.tools` (`{ laser?: boolean; custom?: boolean }`) — the listed tools stay user-driven while the editor is otherwise non-interactive: pointer input keeps driving the tool when it's the active tool. With `laser` enabled, pointer strokes draw laser trails and pointer positions keep broadcasting through `onPointerUpdate`, so e.g. collaborators see a presenter's laser & cursor while the presenter's editor is otherwise inert. With `custom` enabled, custom tools (`activeTool.type === "custom"`) keep receiving `onPointerDown` / `onPointerUp` — activate them with `locked: true` or they revert to the selection tool (and go inert) after the first pointer interaction. Enabling a tool does not enable user-driven tool _switching_ — the keyboard stays disabled and tool selection remains host-driven (`ExcalidrawAPI.setActiveTool`). Composes with `enabled.navigation`: the enabled tool wins the primary-pointer drag, while wheel input (and wheel-button drag) still pans/zooms. The editor consumes touch input over the canvas while the active tool is enabled (strokes don't scroll the page).
+
+- While the editor is non-interactive, `ExcalidrawAPI.setActiveTool` only activates tools allowed via `interaction.enabled.tools` — activating any other tool is refused with a console warning (previously the switch went through even though the tool couldn't be used, e.g. updating the canvas cursor). The same invariant is maintained for the tool state itself: when the active tool loses its exception (e.g. `enabled.tools` changes, or the editor becomes fully non-interactive mid-session), it resets to the default `selection` tool, so stale tool state — e.g. a presenter's laser after handing off — doesn't leak through `onChange` / collab pointer payloads.
+
+### Interaction and UI control (2026-07-05) [#11605](https://github.com/excalidraw/excalidraw/pull/11605)
+
+- Added `interaction` prop (`boolean | { enabled?: { navigation?: boolean; links?: boolean; embeds?: boolean; interactiveContent?: boolean; browserZoom?: boolean } }`). When set to `false`, the editor becomes fully inert for the user — no panning, zooming, selecting, editing, keyboard shortcuts, clipboard, or drag&drop. It implies view mode (`appState.viewModeEnabled` reports `true` and cannot be unset while non-interactive), and the page scrolls naturally over the component since wheel/touch input is no longer captured (the browser's own zoom is still prevented over the editor by default). Interactions under `enabled` are opt-in exceptions: with `navigation` allowed, the user can pan (pointer drag, wheel, PageUp/PageDown — shift for horizontal) and zoom (ctrl/cmd + wheel, pinch, and the canvas zoom & zoom-to-fit shortcuts — ctrl/cmd +/-/0, shift+1/2/3) the canvas view-mode style — respecting `appState.scrollConstraints`, so it composes with viewport locking for constrained viewers, while the rest of the keyboard stays disabled and the editor consumes wheel & touch input again (the page no longer scrolls over the editor); with `links` allowed, link icons render and linked elements stay clickable (view-mode behavior: clicking anywhere on a linked element opens its link) while the editor stays otherwise non-interactive — when links are not allowed, link icons are not rendered at all; with `embeds` allowed, embeddable & iframe elements stay interactive (hover & click activates them, view-mode style); `interactiveContent` is an additive shorthand enabling `links` & `embeds` (and future interactive content kinds) together; with `browserZoom` allowed, the browser's own zoom gestures (ctrl/cmd + wheel, pinch, keyboard) stay available over the editor (moot when `navigation` is allowed, since the editor consumes the zoom input instead). The scene still renders and remains fully controllable through the imperative API (`updateScene`, `setViewport`, ...), making it suitable for live previews, thumbnails, and annotation overlays.
+
+- Added `ui` prop (`boolean | { enabled: { zoom?: boolean; scrollBackToContent?: boolean } }`). When set to `false`, Excalidraw's default UI is not rendered — toolbar, default menu and footer controls, sidebars, canvas popups, and context menu. The object form likewise hides the default UI but opts the zoom controls and/or scroll-back-to-content button back in. Canvas content (elements, text editing, frame names, embeds) still renders, and the editor remains interactive unless `interaction={false}` is set as well. Host children continue to mount (they may be functional, e.g. a collaboration component), and host-supplied UI — including Excalidraw-exported components such as `<MainMenu>` and `<Footer>` — continues to render together with any supporting dialogs it opens. You're responsible for hiding your own presentational components.
+
+### Tool system & toolbar rework [#11649](https://github.com/excalidraw/excalidraw/pull/11649)
+
+The toolbar UI was rewritten from hidden radio/checkbox inputs to real `<button>` elements composed from a central tool registry, and all tool activation now goes through a single `setActiveTool` code path.
+
+#### Breaking changes
+
+- `ExcalidrawAPI.setActiveTool(tool, keepSelection?)` — the second parameter changed from a boolean to an options object: `setActiveTool(tool, { keepSelection?: boolean; toggle?: boolean = false })`. The hand and eraser tools are now _toggle tools_: activating one records the previously active tool, and if `toggle=true`, activating it again switches back — including via `setActiveTool` itself, so repeated `setActiveTool({ type: "hand" }, { toggle: true })` calls alternate rather than no-op. By default `false` for idempotent activation.
+
+- Tool buttons render as semantic `<button>` elements with `aria-pressed` instead of `<label>`-wrapped hidden `<input type="radio">` / `<input type="checkbox">`. If you style or query the editor DOM:
+
+  - The `.ToolIcon_type_radio`, `.ToolIcon_type_checkbox`, and `.ToolIcon--selected` class names no longer exist — the pressed state is exposed through the `.ToolIcon--checked` class and the `aria-pressed` attribute.
+  - `<Sidebar.Trigger>` (including the default Library trigger) renders a `<button>` instead of a `<label>` + checkbox.
+
+- Removed internal actions superseded by the `setActiveTool` funnel and the tool registry: `toggleHandTool`, `toggleEraserTool`, `toggleLassoTool`, `setFrameAsActiveTool`, `setEmbeddableAsActiveTool` (these `ActionName`s no longer exist).
+
+#### Behavior changes
+
+- Hand (`H`) and eraser (`E`) shortcuts now reliably toggle back to the previously active tool (previously inconsistent across platforms and input paths, and unavailable for hand in view mode). Pressing `Escape` while hand or eraser is active likewise returns to the previous tool. Re-clicking their toolbar buttons is a no-op.
+- Clicking the active selection tool switches to lasso on all platforms (previously this only worked on iOS due to a controlled-radio quirk).
+- Tool letter shortcuts are CapsLock-insensitive, `Shift+letter` never switches tools, and `Ctrl+E` no longer toggles the eraser.
+- Switching tools no longer creates undo-history entries.
+- Command palette tool commands are derived from the tool registry: the duplicate "Hand" entry is gone, "Web Embed" was added, and "Lasso" is always listed.
+- Pen mode now activates on the first pen tap on any tool button (previously deferred and occasionally dropped).
+
+#### Fixes
+
+- Mobile toolbar popovers: the active option stays highlighted after tapping it (the highlight was being suppressed by sticky touch-hover).
+- The active-tool highlight can no longer desync from the actually active tool (controlled-radio DOM desync).
+
+### Viewport control & scroll/zoom locking (2026-07-03) [#11554](https://github.com/excalidraw/excalidraw/pull/11554)
+
+`ExcalidrawAPI.scrollToContent` was rebuilt into `ExcalidrawAPI.setViewport()` — a single API for navigating the viewport (`fit: "scale-down" | "contain" | "none"`), locking scroll/zoom to a target (with rubberband overscroll), fitting around the rendered editor UI, and initializing the viewport on scene load.
+
+#### Breaking changes
+
+- `ExcalidrawAPI.scrollToContent(target?, opts?)` was replaced with `ExcalidrawAPI.setViewport(opts | null)`.
+
+  ```tsx
+  // before
+  excalidrawAPI.scrollToContent(element, {
+    fitToViewport: true,
+    animate: true,
+  });
+  // after
+  excalidrawAPI.setViewport({ target: element, fit: "contain" });
+  ```
+
+  - `target` is required and no longer defaults to the whole scene — pass `target: excalidrawAPI.getSceneElements()` for the old default. Besides element(s) or an element id / element-link URL, it now also accepts `Bounds` and `{ x, y, width?, height? }` rects (missing dimensions default to the viewport size). Deleted and non-scene elements in the target are filtered out with a console warning.
+  - `fitToContent` / `fitToViewport` were replaced by `fit: "scale-down" | "contain"` respectively, defaulting to `"scale-down"` (zoomed so the target fits, at most 100%). Previously the default depended on the target: element-id / element-link (string) targets defaulted to fit-to-content — matching the new default — while element(s) or omitted targets defaulted to recentering at the current zoom without changing it; pass `fit: "none"` for that behavior.
+  - `animate` / `duration` were replaced by `animation: boolean | { duration?: number }`. Navigation now always animates by default; previously only string targets did, while element(s) targets jumped unless `animate: true` — pass `animation: false` to jump instantly.
+  - `canvasOffsets` was replaced by `offsets`, which also accepts UI-derived offsets (see Features below).
+  - `viewportZoomFactor`, `minZoom`, and `maxZoom` are no longer supported.
+
+- `zoomToFitBounds` takes `fit: "scale-down" | "contain" | "none"` instead of `fitToViewport` / `viewportZoomFactor`, and no longer rounds the resulting zoom down to the nearest 10% step by default — pass `steppedZoom: true` to keep the old rounding.
+
+#### Features
+
+- `setViewport({ ..., lock })` locks the viewport to the resolved target: `lock.scroll` constrains panning to the target box and `lock.zoom` makes the resolved zoom the minimum zoom (zooming in stays allowed). During an animated navigation into a locked viewport, user pan, zoom, fit, and page-navigation input is consumed without mutating or cancelling the transition; the destination lock is installed together with the final viewport once the animation settles. A newer `setViewport(...)` supersedes the transition and starts from the currently rendered viewport. `setViewport(null)` cancels a pending transition and clears any pending or active lock without navigating; a navigation without `lock` likewise supersedes any lock.
+
+- `lock.overscroll` adds a rubberband to the lock: panning can overshoot the constraint by the given amount (viewport px, zoom-independent) and snaps back once wheel input settles or the active pointer or multi-finger gesture is released. Defaults to `true` = `DEFAULT_OVERSCROLL` (150px, exported from the package root); pass a number to customize, or `false` / `0` for a rigid lock. Zooming itself remains hard-clamped against the lock, gliding along its edge instead of overscrolling, and stays available during snap-back without cancelling the rubberband animation or discarding its existing screen-space overscroll.
+
+- While a lock is active, the zoom-to-fit shortcuts (shift+1/2/3) target the locked box instead of the scene elements (with no selection), so they return the viewport to the lock's resting state; reset-zoom (ctrl/cmd+0) resets to the lock's minimum zoom instead of 100%. Fit results are always re-clamped against the lock. [#11605](https://github.com/excalidraw/excalidraw/pull/11605)
+
+- Added `<Excalidraw initialState={{ viewport }} />` for initializing the viewport (and optionally installing a lock) once on scene load. Accepts the same options as `setViewport` except `animation`, and takes precedence over `initialData.scrollToContent`.
+
+- The `offsets` option (on `setViewport` and `initialState.viewport`) insets the usable viewport per side so targets aren't fitted underneath overlaid UI. It combines static pixel sides with `ui: true | ViewportOffsetsOptions`, which measures the currently rendered editor UI (toolbar, styles panel, sidebar…) — with configurable padding, per-side overrides, and reserving space for currently-hidden surfaces (`reserve: { stylesPanel?: boolean; sidebar?: boolean }`). The same measurement is exposed through the new `ExcalidrawAPI.getViewportOffsets(opts?)`, and custom UI rendered inside the editor container can opt into being measured via the `data-viewport-ui="top" | "bottom" | "side"` attribute.
+
+### Other Breaking changes
+
+- `UIAppState` no longer includes `zoom`, `shouldCacheIgnoreZoom`, and the canvas-interaction transients `snapLines`, `originSnapOffset`, `suggestedBinding`, `frameToHighlight`, and `elementsToHighlight`. These update per pointermove or per animation frame and no longer re-render the editor UI, so UI render props receiving `UIAppState` (`renderCustomStats`, custom `<Footer/>` content, etc.) don't receive them anymore and would render stale values if they read them off the full `AppState`. Subscribe through `useExcalidrawStateValue` instead — the component re-renders only when the selected value changes:
+
+  ```tsx
+  import { useExcalidrawStateValue } from "@excalidraw/excalidraw";
+
+  const ZoomReadout = () => {
+    // `undefined` on initial render, before the editor API initializes
+    const zoomValue = useExcalidrawStateValue(
+      (appState) => appState.zoom.value,
+    );
+
+    if (zoomValue == null) {
+      return null;
+    }
+
+    return <div>{(zoomValue * 100).toFixed(0)}%</div>;
+  };
+  ```
+
+  Outside of React components, you can also subscribe via `ExcalidrawAPI.onStateChange((appState) => appState.zoom.value, (zoomValue) => {...})`, or keep using the existing `onScrollChange(scrollX, scrollY, zoom)` prop.
+
+- Theme changes initiated by the default UI are now delegated to `<Excalidraw onThemeChange={(theme) => ...} />` when supplied. If `onThemeChange` is not supplied, light/dark theme toggling still falls back to updating the internal editor state.
+
+  - `MainMenu.DefaultItems.ToggleTheme` no longer accepts the item-level `onSelect` callback. Host apps that need to control light/dark/system theme should pass `onThemeChange` to `<Excalidraw />` instead.
+  - `MainMenu.DefaultItems.ToggleTheme` with system theme support now uses `allowSystemTheme` together with `theme={Theme | "system"}` only to render the selected value. For the regular light/dark item, pass `allowSystemTheme={false}`.
+  - `CommandPalette.defaultItems.toggleTheme` was removed. The default theme command is now rendered by the command palette itself when `UIOptions.canvasActions.toggleTheme` enables the action (see below).
+  - `UIOptions.canvasActions.toggleTheme` still controls default theme UI availability. When it is `null`, it defaults to `true` if `props.theme` is omitted or `props.onThemeChange` is supplied, and otherwise defaults to disabled.
+
+- Renamed the `excalidrawAPI` prop to `onExcalidrawAPI`.
+  - `onExcalidrawAPI` is now called on mount (instead of during constructor), and later on unmount (with `null` value). The API may be removed altogether in the future (you can use `onMount` & `onUnmount` to manage the `ExcalidrawAPI` object (e.g. to cache it to a global state), already).
+
+### Other Features
+
+- Added `ExcalidrawAPI.isDestroyed` flag. Set to `true` once the editor unmounts. Calling any `get*` method, `onStateChange`, or `onEvent` on a destroyed API instance will throw in development and `console.error` in production. The `ExcalidrawAPI` will be reset to `null` on unmount, but to be extra safe, you should check `ExcalidrawAPI.isDestroyed` before calling these methods to guard against subtle race conditions in your code.
+
+- Added `onMount`, `onInitialize`, and `onUnmount` props. `onMount` receives `{ excalidrawAPI, container }` once the editor root is mounted. `onInitialize` fires once the initial scene has loaded. `onUnmount` fires just before unmounting.
+
+- Same events are also accessible imperatively through `api.onEvent(...)`.
+
+  ```tsx
+  <Excalidraw
+    onExcalidrawAPI={(api) => {
+      api.onEvent("editor:mount", ({ excalidrawAPI, container }) => {
+        console.log(container);
+      });
+
+      api.onEvent("editor:initialize").then((readyApi) => {
+        readyApi.setViewport({
+          target: readyApi.getSceneElements(),
+          animation: false,
+        });
+      });
+    }}
+  />
+  ```
+
+  Note that in future releases, most, if not all, `excalidrawAPI.on*` subscriptions will be removed in favor of `excalidrawAPI.onEvent(name)`.
+
+- Also added `"editor:unmount"` lifecycle event, only accessible via `api.onEvent("editor:unmount")`.
+
+- Exported `<ExcalidrawAPIProvider/>`, `useExcalidrawAPI()`, `useExcalidrawStateValue(prop | props | selectorFunction)`, and `useOnExcalidrawStateChange(prop | props | selectorFunction, callback)` from the package. The imperative API also now exposes `onStateChange(prop | props | selectorFunction, callback?)`, and `onEvent(name, callback)`.
+
+  ```tsx
+  <ExcalidrawAPIProvider>
+    <Excalidraw />
+    <Logger />
+  </ExcalidrawAPIProvider>;
+
+  function Logger() {
+    // initially null before the ExcalidrawAPIProvider initializes after
+    // <Excalidraw/> renders
+    // When <Excalidraw/> unmounts, is reset back to null
+    const api = useExcalidrawAPI();
+
+    useExcalidrawStateValue("viewModeEnabled", (viewModeEnabled) => {
+      console.log("view mode changed:", viewModeEnabled);
+    });
+
+    React.useEffect(() => {
+      if (api) {
+        console.log("editor instance id:", api.id);
+      }
+    }, [api]);
+
+    return null;
+  }
+  ```
+
+- Added `onExport` so host apps can delay JSON export until async work completes. The handler receives the export data plus an `AbortSignal`, and may return a `Promise` or an async generator that yields progress updates for the built-in toast UI.
+
+  ```tsx
+  <Excalidraw
+    onExport={async function* (_type, { files }, { signal }) {
+      yield { type: "progress", message: "Waiting for images..." };
+
+      await waitForImagesToLoad(files, signal);
+
+      if (signal.aborted) {
+        return;
+      }
+
+      yield { type: "progress", message: "Export ready", progress: 1 };
+    }}
+  />
+  ```
+
 ## Excalidraw Library
 
+### Breaking changes
+
+- `updateActiveTool` (from `@excalidraw/common`): the `lastActiveToolBeforeEraser` property of the `data` parameter was renamed to `lastActiveTool` (it was already stored under that name on `appState.activeTool`, and is no longer eraser-specific).
+
+- `getClosestElementBounds` is no longer exported from `@excalidraw/element`. Use `getCommonBounds` / `getElementBounds` from `@excalidraw/element`, or reimplement the closest-target distance check with `getElementBounds` if you need the same behavior [#11554](https://github.com/excalidraw/excalidraw/pull/11554).
+
 ## 0.18.0 (2025-03-11)
 
 ### Highlights

package/README.md

@@ -1,10 +1,10 @@
 # Excalidraw
 
-**Excalidraw** is exported as a component to be directly embedded in your project.
+**Excalidraw** is exported as a React component that you can embed directly in your app.
 
 ## Installation
 
-Use `npm` or `yarn` to install the package.
+Install the package together with its React peer dependencies.
 
 ```bash
 npm install react react-dom @excalidraw/excalidraw
@@ -12,34 +12,131 @@ npm install react react-dom @excalidraw/excalidraw
 yarn add react react-dom @excalidraw/excalidraw
 ```
 
-> **Note**: If you don't want to wait for the next stable release and try out the unreleased changes, use `@excalidraw/excalidraw@next`.
+> **Note**: If you want to try unreleased changes, use `@excalidraw/excalidraw@next`.
 
-#### Self-hosting fonts
+## Quick start
 
-By default, Excalidraw will try to download all the used fonts from the [CDN](https://esm.run/@excalidraw/excalidraw/dist/prod).
+The minimum working setup has two easy-to-miss requirements:
 
-For self-hosting purposes, you'll have to copy the content of the folder `node_modules/@excalidraw/excalidraw/dist/prod/fonts` to the path where your assets should be served from (i.e. `public/` directory in your project). In that case, you should also set `window.EXCALIDRAW_ASSET_PATH` to the very same path, i.e. `/` in case it's in the root:
+1. Import the package CSS:
 
-```js
-<script>window.EXCALIDRAW_ASSET_PATH = "/";</script>
+```ts
+import "@excalidraw/excalidraw/index.css";
 ```
 
-### Dimensions of Excalidraw
+2. Render Excalidraw inside a container with a non-zero height.
 
-Excalidraw takes _100%_ of `width` and `height` of the containing block so make sure the container in which you render Excalidraw has non zero dimensions.
+```tsx
+import { Excalidraw } from "@excalidraw/excalidraw";
+import "@excalidraw/excalidraw/index.css";
+
+export default function App() {
+  return (
+    <div style={{ height: "100vh" }}>
+      <Excalidraw />
+    </div>
+  );
+}
+```
+
+Excalidraw fills `100%` of the width and height of its parent. If the parent has no height, the canvas will not be visible.
+
+## Next.js / SSR frameworks
+
+Excalidraw should be rendered on the client. In SSR frameworks such as Next.js, use a client component and load it dynamically with SSR disabled.
+
+```tsx
+// app/components/ExcalidrawClient.tsx
+"use client";
+
+import { Excalidraw } from "@excalidraw/excalidraw";
+import "@excalidraw/excalidraw/index.css";
+
+export default function ExcalidrawClient() {
+  return (
+    <div style={{ height: "100vh" }}>
+      <Excalidraw />
+    </div>
+  );
+}
+```
+
+```tsx
+// app/page.tsx
+import dynamic from "next/dynamic";
+
+const ExcalidrawClient = dynamic(
+  () => import("./components/ExcalidrawClient"),
+  { ssr: false },
+);
+
+export default function Page() {
+  return <ExcalidrawClient />;
+}
+```
+
+See the local examples for complete setups:
+
+- [examples/with-nextjs](https://github.com/excalidraw/excalidraw/tree/master/examples/with-nextjs)
+- [examples/with-script-in-browser](https://github.com/excalidraw/excalidraw/tree/master/examples/with-script-in-browser)
+
+## LLM / agent tips
+
+If an LLM or coding agent is setting up Excalidraw, these shortcuts usually save more time than re-prompting:
+
+- Start with a plain `<Excalidraw />` in a `100vh` container. Add refs, `initialData`, persistence, or custom UI only after the base embed works.
+- If the canvas is blank, check the CSS import and parent height first. Those are the two most common integration failures.
+- In Next.js or other SSR frameworks, assume client-only rendering first. Use `"use client"` and `dynamic(..., { ssr: false })` before debugging hydration or `window is not defined` errors.
+- If imports or entrypoints are unclear, inspect `node_modules/@excalidraw/excalidraw/package.json`. The installed package exports are the source of truth.
+- Do not set `window.EXCALIDRAW_ASSET_PATH` unless you are intentionally self-hosting fonts/assets.
+- When docs and generated code drift, copy the nearest working example from this repo, especially `examples/with-nextjs` or `examples/with-script-in-browser`.
+
+## Migrating to `@excalidraw/excalidraw@0.18.x`
+
+Version `0.18.x` removes the old `types/`-prefixed deep import paths. If you were importing types from `@excalidraw/excalidraw/types/...`, switch to the new type-only subpaths below.
+
+| Old path | New path |
+| --- | --- |
+| `@excalidraw/excalidraw/types/data/transform.js` | `@excalidraw/excalidraw/element/transform` |
+| `@excalidraw/excalidraw/types/data/types.js` | `@excalidraw/excalidraw/data/types` |
+| `@excalidraw/excalidraw/types/element/types.js` | `@excalidraw/excalidraw/element/types` |
+| `@excalidraw/excalidraw/types/utility-types.js` | `@excalidraw/excalidraw/common/utility-types` |
+| `@excalidraw/excalidraw/types/types.js` | `@excalidraw/excalidraw/types` |
+
+Drop the `.js` extension. The new package `exports` map resolves these paths without it.
+
+These deep subpaths are for `import type` only. Runtime imports should come from the package root, plus `@excalidraw/excalidraw/index.css` for styles.
+
+For example:
+
+```ts
+import { exportToSvg } from "@excalidraw/excalidraw";
+```
+
+## Self-hosting fonts
+
+By default, Excalidraw downloads the fonts it needs from the [CDN](https://esm.run/@excalidraw/excalidraw/dist/prod).
+
+For self-hosting, copy the contents of `node_modules/@excalidraw/excalidraw/dist/prod/fonts` into the path where your app serves static assets, for example `public/`. Then set `window.EXCALIDRAW_ASSET_PATH` to that same path:
+
+```html
+<script>
+  window.EXCALIDRAW_ASSET_PATH = "/";
+</script>
+```
 
 ## Demo
 
-Go to [CodeSandbox](https://codesandbox.io/p/sandbox/github/excalidraw/excalidraw/tree/master/examples/with-script-in-browser) example.
+Try the [CodeSandbox example](https://codesandbox.io/p/sandbox/github/excalidraw/excalidraw/tree/master/examples/with-script-in-browser).
 
 ## Integration
 
-Head over to the [docs](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/integration).
+Read the [integration docs](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/integration).
 
 ## API
 
-Head over to the [docs](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api).
+Read the [API docs](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api).
 
 ## Contributing
 
-Head over to the [docs](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/contributing).
+Read the [contributing docs](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/contributing).

package/dist/dev/{chunk-EWKWI3K7.js → chunk-IUKF2BNN.js}

@@ -1,5 +1,8 @@
 // locales/en.json
 var labels = {
+  signUp: "Sign up",
+  signIn: "Sign in",
+  upgrade: "Upgrade",
   paste: "Paste",
   pasteAsPlaintext: "Paste as plaintext",
   pasteCharts: "Paste charts",
@@ -25,6 +28,7 @@ var labels = {
   copyStyles: "Copy styles",
   pasteStyles: "Paste styles",
   stroke: "Stroke",
+  textColor: "Text color",
   changeStroke: "Change stroke color",
   background: "Background",
   changeBackground: "Change background color",
@@ -35,6 +39,9 @@ var labels = {
   strokeStyle_dashed: "Dashed",
   strokeStyle_dotted: "Dotted",
   sloppiness: "Sloppiness",
+  pressure: "Pressure",
+  pressure_constant: "Constant",
+  pressure_variable: "Variable",
   opacity: "Opacity",
   textAlign: "Text align",
   edges: "Edges",
@@ -106,6 +113,7 @@ var labels = {
   group: "Group selection",
   ungroup: "Ungroup selection",
   collaborators: "Collaborators",
+  you: "You",
   toggleGrid: "Toggle grid",
   addToLibrary: "Add to library",
   removeFromLibrary: "Remove from library",
@@ -185,8 +193,15 @@ var labels = {
   shapeSwitch: "Switch shape",
   preferences: "Preferences",
   preferences_toolLock: "Tool lock",
+  boxSelectionMode: "Select on",
+  boxSelectionContain: "Wrap",
+  boxSelectionOverlap: "Overlap",
   arrowBinding: "Arrow binding",
-  midpointSnapping: "Snap to midpoints"
+  midpointSnapping: "Snap to midpoints",
+  showHints: "Show hints",
+  inputDevice: "Input",
+  inputDeviceTrackpad: "Trackpad",
+  inputDeviceMouse: "Mouse"
 };
 var elementLink = {
   title: "Link to object",
@@ -238,6 +253,7 @@ var buttons = {
   undo: "Undo",
   redo: "Redo",
   resetLibrary: "Reset library",
+  reset: "Reset",
   createNewRoom: "Create new room",
   fullScreen: "Full screen",
   darkMode: "Dark mode",
@@ -325,13 +341,20 @@ var toolBar = {
   eraser: "Eraser",
   frame: "Frame tool",
   magicframe: "Wireframe to code",
+  stickynote: "Sticky note",
   embeddable: "Web Embed",
   laser: "Laser pointer",
+  autoshape: "Draw to shape",
+  bucketfill: "Bucket fill",
   hand: "Hand (panning tool)",
   extraTools: "More tools",
   mermaidToExcalidraw: "Mermaid to Excalidraw",
   convertElementType: "Toggle shape type"
 };
+var bucketfill = {
+  noRegion: "Couldn't find an enclosed region to fill here.",
+  tooComplex: "This region is too complex to fill."
+};
 var element = {
   rectangle: "Rectangle",
   diamond: "Diamond",
@@ -344,6 +367,7 @@ var element = {
   group: "Group",
   frame: "Frame",
   magicframe: "Wireframe to code",
+  stickynote: "Sticky note",
   embeddable: "Web Embed",
   selection: "Selection",
   iframe: "IFrame"
@@ -362,13 +386,17 @@ var hints = {
   freeDraw: "Click and drag, release when you're finished",
   text: "Tip: you can also add text by double-clicking anywhere with the selection tool",
   embeddable: "Click-drag to create a website embed",
+  stickynote: "Click to place a note, or drag to size it",
+  autoshape: "Draw rectangles, circles, diamonds, lines and arrows",
   text_selected: "Double-click or press {{shortcut}} to edit text",
   text_editing: "Press {{shortcut_1}} or {{shortcut_2}} to finish editing",
   linearElementMulti: "Click on last point or press {{shortcut_1}} or {{shortcut_2}} to finish",
   lockAngle: "You can constrain angle by holding {{shortcut}}",
   resize: "You can constrain proportions by holding {{shortcut_1}} while resizing,\nhold {{shortcut_2}} to resize from the center",
   resizeImage: "You can resize freely by holding {{shortcut_1}},\nhold {{shortcut_2}} to resize from the center",
+  resizeStickyNote: "hold {{shortcut_1}} to resize freely, {{shortcut_2}} to resize from the center",
   rotate: "You can constrain angles by holding {{shortcut}} while rotating",
+  toggleArrowhead: "Double-click to toggle the arrowhead",
   lineEditor_info: "Hold {{shortcut_1}} and Double-click or press {{shortcut_2}} to edit points",
   lineEditor_line_info: "Double-click or press {{shortcut}} to edit points",
   lineEditor_pointSelected: "Press {{shortcut_1}} to remove point(s),\n{{shortcut_2}} to duplicate, or drag to move",
@@ -377,6 +405,7 @@ var hints = {
   bindTextToElement: "{{shortcut}} to add text",
   createFlowchart: "{{shortcut}} to create a flowchart",
   deepBoxSelect: "Hold {{shortcut}} to deep select, and to prevent dragging",
+  cycleSelection: "{{shortcut}}-click to cycle selection, or drag to duplicate",
   eraserRevert: "Hold {{shortcut}} to revert the elements marked for deletion",
   firefox_clipboard_write: 'This feature can likely be enabled by setting the "dom.events.asyncClipboard.clipboardItem" flag to "true". To change the browser flags in Firefox, visit the "about:config" page.',
   disableSnapping: "Hold {{shortcut}} to disable snapping",
@@ -412,6 +441,10 @@ var roomDialog = {
 var errorDialog = {
   title: "Error"
 };
+var progressDialog = {
+  title: "Saving",
+  defaultMessage: "Preparing to save..."
+};
 var exportDialog = {
   disk_title: "Save to disk",
   disk_details: "Export the scene data to a file from which you can import later.",
@@ -593,7 +626,11 @@ var colorPicker = {
   colors: "Colors",
   shades: "Shades",
   hexCode: "Hex code",
-  noShades: "No shades available for this color"
+  noShades: "No shades available for this color",
+  invalidColor: "Not a valid color",
+  invalidHexLength: "Hex code must be 3, 4, 6, or 8 characters",
+  topPicksTip: "Tip: drag any color onto your top picks to pin it",
+  resetTopPicks: "Reset to default top picks"
 };
 var overwriteConfirm = {
   action: {
@@ -626,6 +663,15 @@ var overwriteConfirm = {
     }
   }
 };
+var fileDrop = {
+  replace: "Drop to replace content",
+  add: "Drop to add to canvas",
+  importLibrary: "Drop to import library",
+  replaceHint: "Hold <shift>Shift</shift> to keep existing content",
+  keepHint: "Your existing content will be kept",
+  libraryHint: "Library files will append",
+  replacedToast: "Content replaced. {{shortcut}} to undo"
+};
 var mermaid = {
   title: "Mermaid to Excalidraw",
   button: "Insert",
@@ -633,7 +679,7 @@ var mermaid = {
   syntax: "Mermaid Syntax",
   preview: "Preview",
   label: "Mermaid",
-  inputPlaceholder: "Write Mermaid diagram defintion here...",
+  inputPlaceholder: "Write Mermaid diagram definition here...",
   autoFixAvailable: "Auto-fix is available"
 };
 var ttd = {
@@ -691,7 +737,9 @@ var fontList = {
   },
   sceneFonts: "In this scene",
   availableFonts: "Available fonts",
-  empty: "No fonts found"
+  empty: "No fonts found",
+  topPicksTip: "Tip: drag any font onto your top picks to pin it",
+  resetTopPicks: "Reset to default top picks"
 };
 var userList = {
   empty: "No users found",
@@ -739,6 +787,7 @@ var en_default = {
   alerts,
   errors,
   toolBar,
+  bucketfill,
   element,
   headings,
   hints,
@@ -747,6 +796,7 @@ var en_default = {
   shareDialog,
   roomDialog,
   errorDialog,
+  progressDialog,
   exportDialog,
   helpDialog,
   clearCanvasDialog,
@@ -761,6 +811,7 @@ var en_default = {
   welcomeScreen,
   colorPicker,
   overwriteConfirm,
+  fileDrop,
   mermaid,
   ttd,
   chat,
@@ -780,6 +831,7 @@ export {
   alerts,
   errors,
   toolBar,
+  bucketfill,
   element,
   headings,
   hints,
@@ -788,6 +840,7 @@ export {
   shareDialog,
   roomDialog,
   errorDialog,
+  progressDialog,
   exportDialog,
   helpDialog,
   clearCanvasDialog,
@@ -802,6 +855,7 @@ export {
   welcomeScreen,
   colorPicker,
   overwriteConfirm,
+  fileDrop,
   mermaid,
   ttd,
   chat,
@@ -812,4 +866,4 @@ export {
   keys,
   en_default
 };
-//# sourceMappingURL=chunk-EWKWI3K7.js.map
+//# sourceMappingURL=chunk-IUKF2BNN.js.map