@oh-just-another/state 0.59.0 → 0.61.0

package/CHANGELOG.md

@@ -1,5 +1,194 @@
 # @oh-just-another/state
 
+## 0.61.0
+
+### Minor Changes
+
+- 0548ab3: Unify the active tool into a single `editor.activeTool` value object (breaking).
+  - `state`: `editor.activeTool: ActiveTool` (`{ type, locked, lastActiveTool }`)
+    replaces `editor.mode` and `editor.toolLocked`; `setActiveTool(type)` replaces
+    `setMode`. `EditorOptions.initialMode` → `initialTool`. The typed `mode` event
+    is now `tool` and fires with the `ActiveTool` object on a type switch or a
+    lock flip. The action category `"mode"` is now `"tool"`. The vestigial
+    `"eyedropper"` mode is removed from `Mode` — colour sampling is armed from
+    the colour picker (`beginEyedropperPick`) and never was a toolbar tool.
+  - `react-ui`: `useMode()` → `useActiveTool(): ActiveTool`;
+    `DiagramRoot`/`DiagramCanvas` prop `initialMode` → `initialTool`.
+  - `editor`: `EditorAPI.getMode/setMode` → `getActiveTool/setActiveTool`;
+    `initialMode` prop → `initialTool`; re-exports `ActiveTool`.
+  - `diagram` (+ vue/svelte/angular wrappers): element methods and controller
+    `getMode/setMode` → `getActiveTool/setActiveTool`.
+
+  Tool ids are unchanged (`"select"`, `"draw-rect"`, …). There are no visible
+  behaviour changes — this is an API refactor establishing one source of truth
+  for "which tool is active".
+
+- 762dd8a: Brush capture pipeline upgrade: input streamlining (low-pass with commit-time catch-up), speed-simulated pressure for mouse/touch (slow = thick, fast = thin) with rate-limited pen pressure, sample decimation with a soft point cap, and end tapering. `BrushElement` gains an optional regeneration payload (`pressures`, `simulatePressure`, `baseWidth`) carried through serialization; `Editor.beginBrushStroke` accepts a `pointerType` argument to pick the pressure source. The live preview runs the same pipeline as the commit.
+- 4722388: Editable width for committed brush strokes. `style.strokeWidth` never
+  affected brushes (their widths are baked per point), so the property panel's
+  Thin/Medium/Thick control silently did nothing for them. A brush-only
+  selection now gets a popover range slider driving the new
+  `Editor.setBrushWidth(ids, width)`, which scales every baked point width by
+  `newWidth / baseWidth` — the stroke keeps its exact pressure profile at the
+  new thickness — and records the new `baseWidth`. Legacy strokes without a
+  recorded base fall back to their widest point. One undo step.
+- 05707ed: Drag the caption pill along its link. With the link selected, dragging the
+  pill slides the label along the drawn path (the cursor is projected back onto
+  the polyline — new `projectPointToPathT` in scene); within a few pixels of
+  the arc-length middle it snaps back to the default placement
+  (`label.position` removed, so elbow links regain longest-segment
+  auto-placement). One undo step, Escape reverts, double-click still opens the
+  inline text editor, and handle dots keep pointer priority over the pill.
+  Tunable snap radius: `LINK_LABEL_DRAG_SNAP_PX`.
+- 84450bc: Link captions: measured rounded pill, multiline, correct placement and hit-testing.
+  - `scene`: new shared label geometry (`linkLabelAnchor`, `estimateLinkLabelBox`,
+    `linkLabelBounds`, `pointAlongPath`) — one source of truth for the renderer,
+    hit-testing and culling. `findLinkAt` now also hits inside the caption pill.
+    Elbow links place an unpositioned label on the longest segment's midpoint;
+    explicit `label.position` is clamped away from the arrowheads. Tunables in
+    `constants.ts` (`LINK_LABEL_MAX_WIDTH`, paddings, clearance).
+  - `renderer-core`: the caption is a rounded pill sized by real `measureText`
+    word-wrap (multiline, `\n` breaks) instead of a square estimated box; it
+    rides the drawn geometry (flattened curve for bezier, not the chord), and
+    `computeLinkWorldBounds` unions the pill so dirty-rect / viewport culling
+    never clip it. `LABEL_POSITION` / `LABEL_FONT_SIZE` constants moved to
+    `scene` as `LINK_LABEL_DEFAULT_POSITION` / `LINK_LABEL_DEFAULT_FONT_SIZE`.
+  - `state`: `linkLabelWorld` uses the shared anchor, so the inline editor opens
+    exactly over the pill (including bezier and elbow links).
+  - `react-ui`: the inline caption editor is a multiline textarea — Enter
+    commits, Shift+Enter inserts a newline, Escape cancels.
+
+### Patch Changes
+
+- 50a2bd4: Fix: with a creation tool active (draw-edge, draw-rect, …) a press on a
+  selected shape's edge no longer grabs the shape's resize/rotate handle — it
+  starts the new link / element as expected. Selection chrome (resize, rotate,
+  group and selected-link endpoint handles) is now pressable only under the
+  select tool, and the overlay stops drawing the handles while a creation tool
+  is active (outlines stay; the hand tool keeps the chrome visible).
+- 20af638: Fix: the caption pill no longer fights the bend/segment handles. The
+  "add waypoint" and elbow segment handles slide out from under the label pill
+  along their own span (`getLinkWaypointMidpoints` is label-aware; new shared
+  `getElbowSegmentHandles` keeps the drawn dot and the grab point identical), so
+  a click on the pill selects the link and a double-click opens the inline
+  caption editor. Visible handle dots keep pointer priority — an existing
+  waypoint dot sitting inside the pill is still grabbable (dots draw above the
+  pill).
+- 3c50ef1: Tile cache honours per-element hide (B12, hide half). `renderViaTiles` accepts
+  `hideElements`: tiles bake with the set applied, and an element entering or
+  leaving the set invalidates only the tiles it touches — so the stroke-eraser
+  preview and per-element visibility no longer drop very large scenes off the
+  tile-cache path into a full re-render every frame. Group-isolation dim still
+  takes the full path (dimming almost everything would re-rasterise most tiles
+  anyway).
+- f960332: Fix: mp4 shapes survive a page reload. The video file-drop handler never
+  persisted the bytes into `Scene.files`, so a restored scene had only a dead
+  `blob:` URL and nothing to rehydrate from (the "dead-blob-url" renderer
+  warning) on every backend. The handler now stores the file (`fileId` on the
+  shape), and scene rehydration grew a video branch: it rebuilds the hidden,
+  muted, looping `<video>` element from the persisted bytes (shared
+  `createHiddenLoopingVideo` factory with the drop handler) and resumes
+  playback best-effort. Videos dropped BEFORE this fix have no stored bytes and
+  still won't restore — re-add them once.
+- Updated dependencies [762dd8a]
+- Updated dependencies [05707ed]
+- Updated dependencies [20af638]
+- Updated dependencies [84450bc]
+  - @oh-just-another/scene@0.61.0
+  - @oh-just-another/renderer-core@0.60.0
+  - @oh-just-another/history@0.57.4
+
+## 0.60.0
+
+### Minor Changes
+
+- 783749e: Brush strokes can now be closed and filled. When a fill colour is set in the drawing panel and a stroke's end is drawn back near its start (within `BRUSH_CLOSE_DISTANCE`), the committed `BrushElement` gets `closed: true` and the renderer fills the enclosed area with `style.fill` under the variable-width stroke body. Open strokes and strokes drawn without a fill colour are unchanged. `BrushElement.closed` is serialized.
+- 641842b: Brush strokes now carry host-controlled paint settings instead of a hard-coded colour. `editor.brushSettings` / `editor.setBrushSettings({ stroke, fill, opacity, width })` set the line colour, enclosed-fill colour (for a future closed-stroke fill), opacity, and base width; a committed stroke bakes them into its style, and the width drives the pressure curve. The brush renderer now paints the line from `style.stroke` (falling back to `style.fill` for strokes authored before the split), so old strokes are unchanged. Fixes the previously hard-coded `#222` brush colour.
+- 0d3934e: Eraser gains Alt-restore. While sweeping the eraser, holding Alt un-marks shapes you drag back over — rescuing them before the delete commits on pointer-up (`extendEraseStroke(world, restore)` / `beginEraseStroke(world, restore)`). Marked-for-erase shapes now preview at a dedicated `ERASE_DIM_OPACITY` (0.2 — a clear "about to delete") instead of the gentler group-isolation dim.
+- 571f13b: The eraser now shows a dedicated cursor instead of the generic crosshair: a grey ring that follows the pointer, sized to the panel's eraser width (`brushSettings.width`), plus a short fading grey trail while you drag. The OS cursor is hidden in erase mode (`cursor: none`) and the ring/trail are painted on the overlay so any radius composites cleanly. The laser and eraser trails now share one `drawFadingTrail` renderer. New `CursorRole` `"erase"`.
+- ca48e8a: Add two interaction tools: an eraser (mode `erase`, hotkey `E`) and a laser pointer (mode `laser`, hotkey `K`).
+  - Eraser: press-and-drag sweeps shapes under the cursor into a pending set (previewed dimmed) and deletes them all in one undo step on release. Attached links are removed with their shapes, like a Delete-key delete.
+  - Laser pointer: press-and-drag paints an ephemeral red trail that fades over a couple of seconds. Nothing is written to the scene or history — it lives purely on the overlay. Available in read-only mode. Collab replication of trails is a follow-up.
+
+  Both tools appear in the default toolbar (`DEFAULT_TOOLBAR` / `DEFAULT_VERTICAL_TOOLBAR`) and are registered as `mode-erase` / `mode-laser` actions. TTL, colour and width of the laser trail are tunable via `state/constants.ts`.
+
+- bdc847e: Add four editor tools:
+  - **Eyedropper** — new `eyedropper` mode (toolbar button, `Alt+I`). Click a
+    shape to sample its fill/stroke and apply it to the selection.
+    `Editor.pickColorAt` / `applyEyedropperAt` + pure `pickColorAt`.
+  - **Convert element type** — `Editor.convertSelection(target)` and pure
+    `computeConvertType` switch rectangle ↔ ellipse ↔ diamond (polygon) in place,
+    preserving position/size/style. New "Shape type" property-panel control.
+  - **Image crop** — optional normalised `crop` rect on `ImageElement` (additive,
+    serialised). New `crop` mode entered by double-clicking an image or the
+    property-panel Crop button: drag a frame, `Enter` to apply, `Esc` to cancel.
+    Canvas2D renders the cropped source region (`RenderTarget.drawImage` gains an
+    optional `crop` arg). `Editor.beginImageCrop` / `commitImageCrop` /
+    `cancelImageCrop` + pure `computeSetImageCrop` / `cropRectFromWorldDrag`.
+  - **Flowchart auto-generate** — `Cmd/Ctrl+Alt+Arrow` spawns a connected node
+    from the selected node in that direction. `Editor.spawnConnectedNode` + pure
+    `computeSpawnConnectedNode`.
+
+  Also exposes `worldToLocal` from `@oh-just-another/scene`.
+
+- 511a22a: The eyedropper is no longer a standalone toolbar tool (its palette button and the `Alt+I` hotkey / `mode-eyedropper` action are removed). Instead, every colour picker (`ColorSwatchPicker`) gains an optional pipette button via a new `onEyedrop` prop: clicking it arms `Editor.beginEyedropperPick(onPick)` and the next canvas click samples the colour of the shape under the cursor straight into that swatch — without changing the current tool mode. New editor API: `beginEyedropperPick` and the `isEyedropperArmed` flag; the cursor shows a crosshair while armed.
+- a9558d9: Reworked flowchart keyboard model. Arrow-key bindings are reworked and disambiguated by modifier: `Arrow` nudges (unchanged); `Cmd/Ctrl+Arrow` grows a flowchart CREATE session (each press adds a pending connected sibling, previewed on the overlay, committed as one undo step when Cmd/Ctrl is released, cancelled on Escape); `Alt+Arrow` navigates to the adjacent node (graph neighbour, else spatially nearest); `Cmd/Ctrl+Shift+Arrow` aligns (moved off the old plain `Alt+Arrow`). The old `Cmd/Ctrl+Alt+Arrow` spawn binding is retired.
+
+  New API: `editor.growFlowchart` / `commitFlowchart` / `cancelFlowchart` / `navigateFlowchart` / `flowchartPreview`, the pure `computeSpawnConnectedNodes`, and `endpointElementId` (scene). `<Diagram>` wires the keyup-commit / Escape-cancel lifecycle for you.
+
+- 295f38b: Thread the animated-content playback clock as a per-instance render provider instead of a process-global singleton. `RenderSceneOptions` gains an optional `clock`, forwarded to each shape renderer via `ElementRenderContext.clock` (new `AnimationClock` type export). `Editor` now passes its own per-shape playback clock through the render snapshot, so two editors on one page drive independent GIF playback and no longer overwrite a shared module global every frame. The module-global `setAnimationClock` remains as a documented process-global fallback for context-less paths (headless SVG / worker / PNG export and the tile compositor); behaviour is unchanged when no per-instance clock is supplied. Additive and backwards-compatible.
+- 7f69f29: Add scene text search, a stats/dimensions overlay, and zen mode.
+  - `state`: `searchScene(scene, query)` / `elementSearchText(element)` — a pure, case-insensitive substring index over text shapes, frame names, and edge labels; plus `Editor.selectLink(id)` to programmatically select a single connector.
+  - `react-ui`: `<SearchOverlay>` (⌘F) finds and frames matching text with next/prev navigation; `<StatsPanel>` (⌥/) shows the selection's x/y/w/h/angle and scene totals; `<ZenModeProvider>` / `useZenMode` (⌥Z, Esc to exit) hides chrome for focused work. All three are wired into `<Editor>` from `@oh-just-another/editor`.
+
+- cec8f83: Add read-only / view mode. `EditorOptions.readOnly`, `editor.readOnly`, `editor.setReadOnly()` and `editor.toggleReadOnly()` gate every scene-mutating pointer path (create / move / resize / rotate / annotation / edge edits) at the `applyEmit` choke point and in the pointer-down handlers, while pan / zoom / click + marquee select stay live. The action registry now honours each action's `viewMode` flag — in read-only only `viewMode` actions dispatch (zoom, pan, grid, select-all, cancel, and the new `toggle-read-only` action bound to `⌥R`).
+- 1975a9b: Stroke-eraser: holding Shift while erasing cuts brush strokes into fragments instead of deleting the whole element. Each brush point within the eraser capsule (radius = the on-screen eraser ring in world units, widened by the point's own half-width) is removed; surviving points split into fragment strokes (a lone kept point becomes a dot), links bound to a cut brush are detached, and it all lands in one undo step. A live preview shows the cut while you drag (touched originals hidden, fragments shown). Without Shift the eraser still deletes whole elements; non-brush shapes under Shift fall back to whole-element erase.
+- cf8b735: Add styled text runs (rich text, phase 1): a `TextElement` can now carry an optional `runs` overlay — contiguous substrings each with a partial `TextStyle` (bold / italic / colour / decoration) over the element's base style. The flat `text` stays the source of truth (`runs.map(r => r.text).join("") === text`), so plain-text scenes render, serialise and round-trip byte-for-byte unchanged.
+  - `scene`: `TextRun` type + `TextElement.runs?`; pure helpers `runsToText`, `normalizeRuns`, `sliceRuns`, and `applyStyleToRange(el, from, to, partial)` (splits/merges/coalesces runs, sheds the overlay when uniform).
+  - `serialization`: additive optional `runs` in the text schema; legacy documents (no `runs`) round-trip unchanged.
+  - `renderer-core`: the text renderer draws each visual line's style segments with per-run font + fill through the shared `RenderTarget`, so Canvas2D, WebGL2 and SVG all honour runs. Line breaking still uses the element's base metrics.
+  - `state`: `Editor.applyTextStyleToRange(id, from, to, partial)` applies a style to a character range as one undo step.
+  - `react-ui`: the text formatting controls (bold / italic / underline / strikethrough / colour) target the current inline-edit selection when one is active — styling just those characters — and fall back to whole-element styling otherwise.
+
+  Full inline rich-text editing (per-run wrap metrics, caret-aware run editing) is a follow-up.
+
+### Patch Changes
+
+- c189261: The live brush-stroke preview is now Catmull-Rom-smoothed with the same resampler `commitBrushStroke` applies on release, so a stroke reads smooth as it's drawn instead of snapping from an angular polyline to a curve only when the pointer is lifted.
+- c189261: The live brush-stroke preview now paints in the chosen palette colour and opacity instead of a hardcoded dark-grey fill, so it matches the committed stroke. The brush body colour resolution is now a single shared `brushBodyColor(style)` helper (exported from `@oh-just-another/scene`) used by both the committed-stroke renderer and the preview, so the two can't drift.
+- c189261: Brush strokes now render as a single closed outline polygon filled once, instead of a chain of per-segment quads plus a disc at every joint. The old approach overlapped itself, so at `opacity < 1` the joins double-blended into dark blotches; the single fill paints every pixel exactly once. Round joins/caps are preserved (arc points on convex corners, mitered concave corners clamped to stay a simple, non-self-intersecting polygon). The outline geometry is a new shared `brushOutline(points)` helper (exported from `@oh-just-another/scene`) used by both the committed-stroke renderer and the live preview.
+- c58054b: Brush strokes are now smoothed on commit: the sparsely-captured pointer polyline is resampled through a Catmull-Rom spline (interpolating per-point width) before it enters the scene, so a freehand line reads as a fluid curve instead of a chain of angular segments. Shares one spline resampler (`smoothStrokePoints`) with the laser trail. Tunable via `BRUSH_SMOOTH_SEGMENTS`.
+- b156869: Rework image cropping to a handle interaction. The crop frame is now the image's visible box: double-click an image to enter crop mode, then drag the 8 edge/corner handles to hide pixels (opposite edge stays fixed, the source is never stretched) or drag the image body to pan the source under the frame. A faint full-image ghost is drawn behind the frame so the hidden regions stay visible. Enter/click-outside commits (one undo step), Escape cancels. Replaces the previous rubber-band "draw a rectangle over the image" model.
+
+  New pure geometry in `tool-ops` (`computeCropHandleDrag`, `computeCropBodyPan`, `computeCommitImageCrop`, `cropFullImageLocalRect`, `cropHandleWorldPoints`, `CropHandle`) and Editor methods (`cropHandleAtWorld`, `beginImageCropHandle`, `beginImageCropBody`); `imageCropSession` now exposes the pending `{crop, position, width, height}`. The normalised `ImageCrop` data model is unchanged. Removed `cropRectFromWorldDrag`.
+
+- b0a9f3b: The eraser cursor disc is now filled solid in the trail colour (fully opaque), with the ring on top — a clear, high-contrast aim target that matches the eraser wake.
+- 1975a9b: The stroke-eraser no longer eats more of a line than the cursor ring shows. A brush point was erased when the eraser capsule reached the stroke's outer EDGE (`radius + point.width`); now it's erased when the ring covers the point's centre (`radius`), which equals the visible cursor ring at every zoom. The eraser removes exactly the centreline it passes over.
+- 1975a9b: Fix the eraser cursor freezing when you pause mid-drag (button held) and then resume. The fading trail could empty during the pause, and the resumed move then had neither an active trail nor an object change, so it never triggered a repaint — the cursor stuck until release, when the whole cut applied at once. The eraser now always repaints on move (so the ring follows the pointer) and restarts the trail if it had faded.
+- 22b90f9: The keyboard-shortcuts help dialog now lists every real binding. The `arrange` category (align / flip / distribute) was missing from the dialog's category order and is now shown, and keyTest-driven bindings (nudge arrows, Enter edit/create, plus flowchart create/navigate) surface their chips via a new display-only `Action.displayHotkey` field instead of rendering as "—". `displayHotkey` is never dispatched (only `hotkey`/`keyTest`/`sequence` are), which also closes a latent hole where a display matcher could fire a Ctrl-modified combo the `keyTest` deliberately excluded.
+- f381039: Clicking a drawn line's (brush stroke's) link-start dot no longer clone-creates a connected element — duplicating a freehand line as a "node" made no sense. The start dots and dragging a real link from a brush stroke are unchanged; only the click-to-clone (and its hover ghost) is suppressed for brush sources. Other shapes keep the spawn-connected-node behaviour.
+- bd2e26c: Make read-only (view) mode a true guard. Every mutating `Editor` method reachable from the UI (`updateStyle`, `updateTextProps`, `deleteSelected`, `duplicateSelected`, group/ungroup, align/flip/distribute, z-order, `moveSelectionBy`, `setLink`, `convertSelection`, `clear`, etc.) is now a no-op while `readOnly` is set, backstopping direct panel/hotkey calls that previously bypassed the pointer-level gate. The overlay keeps the selection outline (halo) but no longer paints resize/rotate/group handles or link endpoint grips in read-only, and the property panel / selection floating panel / mutating context-menu entries are hidden. `copy` / `copy-style` are flagged view-safe so they stay live.
+- 97de2fd: Hide the link-creation overlay entirely in read-only mode. Hovering an element no longer shows connection anchor dots, and hovering a dot no longer previews a ghost element/connector — read-only never creates links, so the whole port/ghost overlay is now gated off. Editable behaviour is unchanged.
+- 71a6c8b: Search navigation no longer blows a small match up to fill the whole canvas. Jumping to a match now centers it while preserving the current zoom, only zooming out when the match is too large to fit — a small element stays small and just lands in the center. Adds `Editor.revealSelection(padding)` and the pure `computeRevealBounds` helper (never zooms in, unlike `zoomToSelection`'s fit-to-fill).
+- dde8279: Perf: memoize the overlay-options bag per overlay target and reuse it across frames whose overlay inputs are identity-unchanged (idle / animation / peer-update frames), rebuilding only on a real state change; GIF "play" badges are still recomputed every frame. Feed the persistent spatial index (shared with the hit-test path) to the tile compositor so large-scene tile rasterisation queries the index instead of scanning every shape per tile. Group isolation (dim) / per-element hide now correctly fall back to the full `renderScene` path when the tile cache is enabled, instead of silently dropping the dim/hide effect. Behaviour is unchanged when no tile cache is used and when no isolation/hide is active.
+- 1975a9b: Two stroke-eraser fixes. (1) No more freeze on a slow or stopped cursor: the whole-scene repaint forced while erasing now happens only on frames that actually mark or cut something, not on every eraser move — a slow/idle cursor generates many pointer events per unit distance, each of which was re-rendering the entire scene. (2) Cutting a stroke no longer leaves isolated single-point dots: lone kept points (a survivor with both neighbours erased) are dropped instead of kept as stray discs.
+- 1975a9b: The stroke-eraser (Shift + erase over a brush) now cuts the stroke's **geometry by arc length** instead of dropping whole vertices. A large eraser that merely grazes a line — or one passing between two far-apart points on a fast/short stroke — removes exactly the span it covers, with the fragment edges pinned to the eraser ring. This fixes the eraser ignoring sparsely-sampled or short strokes and eating a gap unrelated to the disc size.
+- 1975a9b: Stroke-eraser no longer freezes on longer drags. The live cut was recomputed against the entire eraser path every frame (O(points × path length)), so the main thread saturated as the path grew — the cursor froze and the whole cut applied at once on release. Erased points are now accumulated incrementally (each move tests only the new segment, skipping already-erased points), making the per-move cost O(points) and the preview smooth throughout the drag.
+- 571f13b: The laser and eraser trails now render as one filled comet shape per stroke instead of a stack of alpha-blended segments. The smoothed centreline is offset into a single ribbon whose half-width tapers from the head to a pointed tail, filled once at a single opacity that fades by the freshest point's age. This removes the overlapping round-cap "beads" at every joint that made the trail look like a chain of little lasers.
+- Updated dependencies [783749e]
+- Updated dependencies [c189261]
+- Updated dependencies [c189261]
+- Updated dependencies [641842b]
+- Updated dependencies [c189261]
+- Updated dependencies [0d3934e]
+- Updated dependencies [bdc847e]
+- Updated dependencies [a9558d9]
+- Updated dependencies [295f38b]
+- Updated dependencies [cf8b735]
+  - @oh-just-another/scene@0.60.0
+  - @oh-just-another/renderer-core@0.59.0
+  - @oh-just-another/history@0.57.3
+
 ## 0.59.0
 
 ### Minor Changes

package/README.md

@@ -1,5 +1,7 @@
 # @oh-just-another/state
 
+[![npm version](https://img.shields.io/npm/v/@oh-just-another/state.svg)](https://www.npmjs.com/package/@oh-just-another/state)
+
 Interactive editor engine: tools, modes, selection, history, and hit-testing over a Scene.
 
 The L2 interaction layer. It wires a Scene together with render targets and high-level operations into an `Editor` controller — framework-agnostic, with no React dependency. Depends on `@oh-just-another/types`, `@oh-just-another/math`, `@oh-just-another/scene`, `@oh-just-another/renderer-core`, `@oh-just-another/history`, `@oh-just-another/events`, `@oh-just-another/tokens`, and `xstate` (v5). Hosts feed it normalized pointer/keyboard/wheel events; it never imports the DOM directly.
@@ -21,11 +23,11 @@ const editor = new Editor({
   mainTarget: layered.get("main"),
   overlayTarget: layered.get("overlay"),
   initialScene: emptyScene(),
-  initialMode: "select",
+  initialTool: "select",
 });
 
 editor.subscribe(() => render());
-editor.setMode("draw-rect");
+editor.setActiveTool("draw-rect");
 ```
 
 ## Concepts
@@ -34,7 +36,7 @@ editor.setMode("draw-rect");
 
 The centerpiece controller (`Editor`, `EditorOptions`, `LoadSceneOptions`). It owns the scene, selection, and viewport, and exposes a high-level API spanning:
 
-- **Tools / modes** — `mode`, `setMode`, `toolLocked` / `setToolLocked` (sticky tool).
+- **Tools** — `activeTool` (`{ type, locked, lastActiveTool }`, the single source of truth), `setActiveTool`, `setToolLocked` (sticky tool).
 - **Selection** — `selection`, `selectAll`, `deleteSelected`, `moveSelectionBy`, `focusCycle`, plus link selection (`selectedLinks`, `selectedLink`).
 - **History** — `undo`, `redo`, `canUndo`, `canRedo`, `history` (backed by `@oh-just-another/history`).
 - **Hit-testing** — `hitTest(worldPoint)` returns a `PressTarget`; `hitAnnotation`.
@@ -46,7 +48,7 @@ The centerpiece controller (`Editor`, `EditorOptions`, `LoadSceneOptions`). It o
 - **Text editing** — inline caret/selection model: `beginTextEdit`, `commitTextEdit`, `cancelTextEdit`, `setEditingText`, `setTextCaretFromPoint`, `extendTextSelectionToPoint`, `caretIndexAtWorldPoint`, `editingTextOverlay`, plus `createTextAt`.
 - **Image / file insert** — `insertImage`, `addElement`, `beginPlacement`, and a `FileDropRegistry` (see below).
 - **GIF / animation playback** — `togglePlayback`, `hoverAnimatedElement`, `isPlaybackPaused`.
-- **Brush strokes** — `beginBrushStroke`, `extendBrushStroke`, `commitBrushStroke`, `cancelBrushStroke`, `pendingBrushStroke`.
+- **Brush strokes** — `beginBrushStroke` (a `pointerType` argument picks the pressure source: real pen pressure, or speed-simulated for mouse/touch), `extendBrushStroke`, `commitBrushStroke`, `cancelBrushStroke`, `pendingBrushStroke`. Capture streamlines input, decimates samples, and tapers stroke ends on commit; the live preview matches the committed result.
 - **Annotations / comments** — `addAnnotation`, `removeAnnotation`, `toggleAnnotationResolved`, `addComment`, `removeComment`, `setSelectedAnnotation`, `setCommentAuthor`.
 - **Scene lifecycle** — `scene`, `loadScene`.