@oh-just-another/state 0.58.0 → 0.60.0

package/dist/editor.d.ts

@@ -1,17 +1,24 @@
 import { type Actor } from "xstate";
 import type { Bounds, FileId, ElementId, Vec2 } from "@oh-just-another/types";
 import type { SpatialGrid } from "@oh-just-another/scene";
-import { type FractionalIndex, type BrushPoint, type Link, type Patch, type Scene, type Element, type GridStyle, type TextStyle } from "@oh-just-another/scene";
-import { type AnnotationId, type CommentId, type LinkId, type LayerId } from "@oh-just-another/types";
+import { type FractionalIndex, type BrushPoint, type Link, type Patch, type Scene, type Element, type GridStyle, type ImageCrop, type TextStyle } from "@oh-just-another/scene";
+import { type AnnotationId, type Color, type CommentId, type LinkId, type LayerId } from "@oh-just-another/types";
 import { ElementCache, type RenderTarget, type TextShaper, type Rasterizer } from "@oh-just-another/renderer-core";
 import { type HistoryOptions, type HistoryProvider, type TransactionHandle } from "@oh-just-another/history";
 import { type FileDropHandler } from "./file-drop.js";
 import { interactionMachine, type InteractionContext, type InteractionEmit, type PressTarget } from "./machine.js";
 import type { Mode } from "./modes.js";
 import type { EditorEvents } from "./editor-events.js";
+import { GifPlaybackController } from "./editor/gif-playback.js";
 import { LongPressController } from "./editor/long-press.js";
 import { PinchController } from "./editor/pinch.js";
-import { type BrushStrokeState } from "./editor/public/brush.js";
+import { InteractionState, type AnnotationDrag, type ContainerHover, type EdgePreview, type GroupResizeOrigin, type HoveredLinkTarget, type LinkDragFromAnchor, type PanGesture, type RotateGestureOrigin } from "./editor/interaction-state.js";
+import { type BrushSettings, type BrushStrokeState } from "./editor/public/brush.js";
+import { type EraseStrokeState } from "./editor/public/eraser.js";
+import { type LaserStroke } from "./editor/public/laser.js";
+import type { CursorRole, CursorSpec } from "./editor/public/cursor.js";
+import { type ConvertTarget, type CropHandle, type SpawnDirection } from "./editor/public/tool-ops.js";
+import { type AlignEdge, type DistributeAxis, type FlipAxis } from "./editor/applies/arrange.js";
 import { type PeerCursor, type PeerSelection } from "./overlay.js";
 import * as Selection from "./selection.js";
 import * as LinkSelection from "./link-selection.js";
@@ -50,10 +57,17 @@ export interface EditorOptions {
     readonly onAfterRender?: () => void;
     readonly initialScene: Scene;
     readonly initialMode?: Mode;
+    /**
+     * Start the editor in read-only / view mode. Pointer edits (create /
+     * move / resize / rotate / delete) and non-`viewMode` actions are gated;
+     * pan / zoom / select still work. Toggle at runtime via
+     * {@link Editor.setReadOnly}. Defaults to `false`.
+     */
+    readonly readOnly?: boolean;
     /**
      * Pre-existing history backend, or options for the default
      * `History` (linear stack). Any `HistoryProvider` implementation
-     * works — `@oh-just-another/collab` ships `YjsHistory` that wraps
+     * works — `@oh-just-another/collab` ships `CollabHistory` that wraps
      * `Y.UndoManager` for CRDT-aware undo in collaborative sessions.
      */
     readonly history?: HistoryProvider | HistoryOptions;
@@ -124,6 +138,15 @@ export type TileComposeFn = (scene: Scene, mainTarget: RenderTarget, options: {
         after: Bounds | null;
     }>;
     readonly zoomBucket: number;
+    /**
+     * Persistent spatial index over the scene's current element world-AABBs,
+     * when the editor maintains one (large scenes, shared with the hit-test
+     * path). A tile compositor that supports it (`renderViaTiles`) queries the
+     * index for per-tile element selection instead of scanning every shape in
+     * every layer. Omitted for small scenes; compositors must fall back to a
+     * full scan when absent.
+     */
+    readonly index?: SpatialGrid;
 }) => void;
 /**
  * Top-level interaction controller. Owns the scene + selection state, wires
@@ -138,29 +161,7 @@ export type GroupSelectedResult = {
     readonly kind: "grouped";
     readonly groupId: ElementId;
 };
-/**
- * Stable keys for cursor states a host can override with a custom image via
- * {@link Editor.setCursorOverride}. Each maps to one outcome of `computeCursor`.
- */
-export type CursorRole = "default" | "pan-ready" | "pan-active" | "move" | "draw" | "text" | "link-start" | "link-handle" | "annotation" | "resize-nwse" | "resize-nesw" | "resize-ns" | "resize-ew";
-/**
- * A custom cursor: either a raw CSS `cursor` value, or an image with an
- * optional `@2x` variant (DPR-aware via `image-set`), hotspot, and keyword
- * fallback.
- */
-export type CursorSpec = string | {
-    /** 1x image URL or data-URL. */
-    readonly url: string;
-    /** Optional 2x image for hi-DPI (retina) — emitted via `image-set`. */
-    readonly url2x?: string;
-    /** Hotspot offset (px) within the image; defaults to (0, 0). */
-    readonly hotspot?: {
-        readonly x: number;
-        readonly y: number;
-    };
-    /** Keyword shown if the image can't load / is too large. */
-    readonly fallback?: string;
-};
+export type { CursorRole, CursorSpec };
 export declare class Editor {
     readonly host: HTMLElement;
     readonly mainTarget: RenderTarget;
@@ -175,11 +176,14 @@ export declare class Editor {
      */
     debugHitZones: boolean;
     /**
-     * When false the background grid is not painted. Toggled via `toggleGrid`
-     * (`g` hotkey, standard parity). View-only — never persisted or in history.
+     * Read-only / view mode. When true the pointer paths that create,
+     * move, resize, rotate or delete are gated (pan / zoom / select stay
+     * live) and the action registry only runs actions flagged
+     * `viewMode`. View-only — never persisted or recorded in history.
+     * Read via {@link readOnly}; flip via {@link setReadOnly}.
      */
-    gridVisible: boolean;
-    readonly actor: Actor<typeof interactionMachine>;
+    private _readOnly;
+    actor: Actor<typeof interactionMachine>;
     private readonly listeners;
     /**
      * Typed event surface. Specific events (`mode`, `selection`,
@@ -193,7 +197,7 @@ export declare class Editor {
     private readonly events;
     /**
      * Last-emitted snapshot of every observable slice. Used by
-     * `fanOutEvents` (in `editor/event-fanout.ts`) to decide which
+     * `fanOutEvents` to decide which
      * typed events to fire on each `notify()` — only the slices
      * whose identity changed since the previous notify get an event.
      */
@@ -202,74 +206,31 @@ export declare class Editor {
     _scene: Scene;
     _selection: Selection.Selection;
     /**
-     * Snapshot of an in-progress annotation drag (press on pin → move
-     * pointer → release). `originPosition` is the annotation's stored
-     * position at press time; per-move handler computes a delta from
-     * the current pointer in world space and writes it back.
+     * Ephemeral interaction / gesture state (previews, gesture origins,
+     * transient modifiers). Single source of truth for the short-lived fields
+     * the pointer handlers, render orchestrator and container-ops read/write
+     * while a gesture is in flight. The public fields below delegate to it so
+     * external writers keep referencing `editor.<field>` unchanged.
      */
-    annotationDrag: {
-        id: AnnotationId;
-        originPosition: Vec2;
-        originWorldPoint: Vec2;
-        moved: boolean;
-    } | null;
+    readonly interaction: InteractionState;
+    /** Snapshot of an in-progress annotation-pin drag. */
+    get annotationDrag(): AnnotationDrag | null;
+    set annotationDrag(v: AnnotationDrag | null);
     /** Live preview while drawing a new shape; null when not drawing. */
-    drawingPreview: Bounds | null;
-    edgePreview: {
-        from: Vec2;
-        to: Vec2;
-        points?: readonly Vec2[];
-    } | null;
-    /**
-     * Active "drag a link from a start-anchor" gesture. Set when a
-     * press lands on one of the selected element's link-start dots; lets
-     * the user draw a link straight from the dot without switching to the
-     * draw-edge tool. `fromWorld` is the true anchor world point (the link
-     * origin, un-offset); `origin` is the press point (for the drag
-     * threshold). Read by the pointer handlers (drive preview / commit on
-     * up) and the render orchestrator (keep the source's start dots visible
-     * during the drag). Null when no such drag is in flight. */
-    linkDragFromAnchor: {
-        fromElement: ElementId;
-        fromWorld: Vec2;
-        /** Named anchor the gesture started on — drives the click-to-create
-         * direction (outward normal) and the source link endpoint. */
-        anchorName: string;
-        origin: Vec2;
-        moved: boolean;
-    } | null;
-    /**
-     * Element being hovered while draw-edge mode is active. Drives the port-
-     * overlay render so the user sees attachment points. `null` outside
-     * draw-edge mode or when the pointer is over empty canvas.
-     */
-    hoveredLinkTarget: {
-        elementId: ElementId;
-        activeAnchor: string | null;
-        outlinePoint?: Vec2 | undefined;
-        /**
-         * What the drop will produce, for clear pre-drop feedback (standard):
-         *   - `"point"` → fixed attach to a specific dot (highlight the dot);
-         *   - `"element"` → floating attach to the whole shape (highlight the
-         *     element). Mirrors `snapLinkEndpoint`: an anchor within threshold →
-         *     point, otherwise floating.
-         */
-        mode: "point" | "element";
-    } | null;
-    /**
-     * Last idle cursor position (world) in select mode — the overlay grows the
-     * SINGLE selected element's link-start dot nearest it
-     * (`ANCHOR_DOT_HOVER_GROW_RADIUS`). Reset to null on press / gesture.
-     */
-    hoverCursorWorld: Vec2 | null;
-    /**
-     * When a link is dropped on empty canvas, the edge is created with a
-     * free `point` end and this records where, so the host can pop a
-     * mini shape-picker at that spot (standard). Picking a shape re-points the
-     * end to the new element; dismissing (Esc / click-away) leaves the free
-     * end on the canvas. `null` when no menu is pending.
-     */
-    private pendingLinkDropMenu;
+    get drawingPreview(): Bounds | null;
+    set drawingPreview(v: Bounds | null);
+    /** Live preview of an edge being drawn. */
+    get edgePreview(): EdgePreview | null;
+    set edgePreview(v: EdgePreview | null);
+    /** Active "drag a link from a start-anchor" gesture. */
+    get linkDragFromAnchor(): LinkDragFromAnchor | null;
+    set linkDragFromAnchor(v: LinkDragFromAnchor | null);
+    /** Element hovered while draw-edge mode is active (drives the port overlay). */
+    get hoveredLinkTarget(): HoveredLinkTarget | null;
+    set hoveredLinkTarget(v: HoveredLinkTarget | null);
+    /** Last idle cursor position (world) in select mode — grows the nearest dot. */
+    get hoverCursorWorld(): Vec2 | null;
+    set hoverCursorWorld(v: Vec2 | null);
     /**
      * Currently selected links (connectors). Links are first-class members
      * of the selection: they coexist with selected elements, join Cmd+A and
@@ -295,8 +256,9 @@ export declare class Editor {
     /**
      * Mid-drag preview state when the user is dragging an edge endpoint.
      * Drawn as an overlay line + handle dot so the user sees the target.
+     * State lives in `LinkHandleDragController`; this is a delegate.
      */
-    linkEndpointDrag: {
+    get linkEndpointDrag(): {
         linkId: LinkId;
         side: "from" | "to";
         toPoint: Vec2;
@@ -307,70 +269,40 @@ export declare class Editor {
      * began on a segment midpoint and will splice a new waypoint on the
      * first move (so a no-move click adds nothing). Live-mutated through the
      * gesture transaction → one undo step per drag.
+     * State lives in `LinkHandleDragController`; this is a delegate.
      */
-    linkWaypointDrag: {
+    get linkWaypointDrag(): {
         linkId: LinkId;
         index: number;
         pendingInsert: boolean;
     } | null;
     /**
-     * Host-managed elbow segment drag. `index` is the segment in the routed
-     * chain `[from, ...routedPoints, to]`; `axis` is its orientation. Dragging
-     * pins the segment's perpendicular coordinate into `Link.fixedSegments`;
-     * the reroute pass re-flows the rest. One undo step via the gesture tx.
+     * Host-managed elbow segment drag. `axis` is the segment's orientation.
+     * Dragging pins the segment's perpendicular coordinate into
+     * `Link.fixedSegments`; the reroute pass re-flows the rest. One undo
+     * step via the gesture tx.
+     * State lives in `LinkHandleDragController`; this is a delegate.
      */
-    linkSegmentDrag: {
+    get linkSegmentDrag(): {
         linkId: LinkId;
         axis: "h" | "v";
         at: number;
     } | null;
     /** Live lasso bounds during a rubber-band select gesture. */
-    lassoPreview: Bounds | null;
-    /**
-     * Selection captured at lasso-press time. Used to compute the live
-     * preview correctly: in `replace` mode the lasso starts from empty
-     * each frame; in `add` mode it starts from this snapshot so shapes
-     * the user already had selected don't blink out and back.
-     */
-    private lassoBaseSelection;
-    /** Link-selection counterpart of `lassoBaseSelection` for the marquee. */
-    private lassoBaseLinks;
-    /**
-     * Snapshot of every selected shape's `position` at press-down. Used to
-     * translate the whole group additively during a multi-shape drag. The
-     * machine still emits per-shape MOVE_SHAPE — the editor intercepts and
-     * fans out when this map is populated.
-     */
-    groupMoveOrigin: ReadonlyMap<ElementId, Vec2> | null;
-    /**
-     * Press-time snapshot of connectors that must follow a multi-element
-     * drag rigidly — both endpoints bound to moved elements, carrying
-     * absolute geometry (waypoints / fixedSegments / routedPoints). Each
-     * frame translates from these originals so the shift never compounds.
-     * Cleared on gesture commit / cancel alongside `groupMoveOrigin`.
-     */
-    groupLinkMoveOrigin: ReadonlyMap<LinkId, Link> | null;
-    /**
-     * Per-shape snapshot for a group-resize gesture — `bounds` is the
-     * shape's world AABB at press-down. Editor scales the relative
-     * position / size against the combined bounds delta each frame.
-     */
-    groupResizeOrigin: {
-        readonly combined: Bounds;
-        readonly elements: ReadonlyMap<ElementId, {
-            readonly position: Vec2;
-            readonly bounds: Bounds;
-            readonly scale: Vec2;
-        }>;
-        readonly links: ReadonlyMap<LinkId, Link>;
-    } | null;
-    /**
-     * Pristine shape snapshot for a single-shape text resize, captured on
-     * the gesture's first tick. Font scaling is computed against this base
-     * so it never compounds across pointermove ticks. Cleared on gesture
-     * end (commit / cancel).
-     */
-    private _resizeOriginElement;
+    get lassoPreview(): Bounds | null;
+    set lassoPreview(v: Bounds | null);
+    /** Snapshot of every selected shape's `position` at press-down (multi-drag). */
+    get groupMoveOrigin(): ReadonlyMap<ElementId, Vec2> | null;
+    set groupMoveOrigin(v: ReadonlyMap<ElementId, Vec2> | null);
+    /** Press-time snapshot of connectors that follow a multi-element drag rigidly. */
+    get groupLinkMoveOrigin(): ReadonlyMap<LinkId, Link> | null;
+    set groupLinkMoveOrigin(v: ReadonlyMap<LinkId, Link> | null);
+    /** Per-shape snapshot for a group-resize gesture. */
+    get groupResizeOrigin(): GroupResizeOrigin | null;
+    set groupResizeOrigin(v: GroupResizeOrigin | null);
+    /** Press-time snapshot for a rotate gesture. */
+    get rotateGestureOrigin(): RotateGestureOrigin | null;
+    set rotateGestureOrigin(v: RotateGestureOrigin | null);
     /**
      * Active layer — new shapes created via `addElement` / `applyCreate` land
      * here when their input doesn't specify a `layerId`. Defaults to the
@@ -387,12 +319,11 @@ export declare class Editor {
     /** Snap threshold in world units. */
     private readonly snapThreshold;
     /**
-     * Transient flag set by the host while a snap-suppress modifier
-     * (Cmd / Ctrl) is held during a drag — lets the user pull a shape off
-     * the grid for one gesture without toggling snap off. Read by the
-     * move / resize / create wrappers; never persisted.
+     * In-editor style memory for copy-style / paste-style. Holds the visual
+     * `style` (fill / stroke / dash / …) captured from a shape; `null` until a
+     * copy happens. Not the OS clipboard — a lightweight per-editor buffer.
      */
-    private snapSuppressed;
+    private styleClipboard;
     /**
      * Persistent world-bounds cache shared with `renderScene` for viewport
      * culling. Object-identity keyed — invalidates automatically whenever
@@ -414,36 +345,37 @@ export declare class Editor {
      * escape, click outside the group's descendants, or `cancelInteraction`.
      */
     _enteredGroup: ElementId | null;
-    /**
-     * Double-click detection state. Updated on every non-drag pointer
-     * up; the next pointer-up within `DOUBLE_CLICK_MS` and within
-     * `DOUBLE_CLICK_TOLERANCE_PX` of `lastClickWorldPoint` counts as a
-     * double-click. Used to trigger group drill-down (enter isolation).
-     */
-    private lastClickAt;
-    private lastClickWorldPoint;
-    /**
-     * Separate double-click tracker for link edit handles (waypoint /
-     * segment). Kept apart from `lastClickAt` because a handle press
-     * returns early in `onDown` (begin-drag) and never reaches the up-side
-     * double-click path that updates `lastClickAt`. Updated by
-     * `isHandleDoubleClick` on each handle press.
-     */
-    private lastHandleClickAt;
-    private lastHandleClickWorld;
     /**
      * In-progress brush stroke. Hosts push points via
      * `extendBrushStroke`; the overlay reads it through
      * `pendingBrushStroke` to draw a live preview.
      */
-    brushStroke: BrushStrokeState | null;
+    get brushStroke(): BrushStrokeState | null;
+    set brushStroke(v: BrushStrokeState | null);
+    /**
+     * The in-progress brush stroke with its captured vertices Catmull-Rom-smoothed
+     * for the LIVE overlay preview — the SAME resampler `commitBrushStroke` applies
+     * on release (see {@link smoothBrushPoints}), so the stroke reads smooth while
+     * drawn instead of snapping from an angular polyline to a curve on release. A
+     * fresh object each call (points diverge from `brushStroke.points`), so the
+     * overlay memo repaints every move that grows the stroke.
+     */
+    private get brushPreviewStroke();
+    /** In-progress eraser stroke (pending-delete set), or null between strokes. */
+    get eraseStroke(): EraseStrokeState | null;
+    set eraseStroke(v: EraseStrokeState | null);
+    /** Ids swept by the current eraser stroke — previewed dimmed, deleted on release. */
+    get pendingErase(): ReadonlySet<ElementId>;
+    /** Live laser-pointer trails (ephemeral, fading). Empty when none active. */
+    get laserStrokes(): readonly LaserStroke[];
     /**
      * Last world-space pointer position observed by the host's onMove
      * handler. `paste()` uses it as the default drop target so a fresh
      * paste lands under the cursor instead of overlapping the originals.
      * `null` until the pointer first enters the host.
      */
-    lastPointerWorld: Vec2 | null;
+    get lastPointerWorld(): Vec2 | null;
+    set lastPointerWorld(v: Vec2 | null);
     /** Host-registered custom cursor images per role (see `setCursorOverride`). */
     private readonly cursorOverrides;
     /**
@@ -462,17 +394,32 @@ export declare class Editor {
      * pass would never visibly apply.
      */
     lastRenderedEnteredGroup: ElementId | null;
+    /**
+     * Whether the last paint had eraser-dim active — paired with
+     * `lastRenderedScene` like {@link lastRenderedEnteredGroup}. When an eraser
+     * stroke ENDS by cancel (Esc), the marked shapes un-dim without a scene
+     * change, so the dirty-rect diff is empty and the dim would linger on screen;
+     * this lets that active→inactive transition force one full repaint.
+     */
+    lastRenderedEraseActive: boolean;
+    /**
+     * Set whenever an eraser move actually CHANGES the marked / cut set (a new
+     * shape marked, un-marked, or a brush point cut). Gates the forced full
+     * repaint during erasing: only the frames that change the preview repaint the
+     * whole scene; a slowly-moving or stopped cursor over already-covered area
+     * skips the expensive main pass (only the overlay cursor / trail refresh).
+     * Cleared after each paint.
+     */
+    private eraseDirty;
     /**
      * Fractional-order compaction scheduler (microtask-coalesced).
      * Triggered from every `notify()`; only does real work when at
      * least one shape/edge order string crossed AUTO_COMPACT_THRESHOLD.
-     * See `./auto-compact.ts` for the extracted logic.
      */
     private readonly autoCompactScheduler;
     /**
      * Auto-layout scheduler — microtask-coalesced re-run of every
-     * shape carrying `metadata.autoLayout`. See
-     * `./auto-layout-scheduler.ts` for the extracted logic.
+     * shape carrying `metadata.autoLayout`.
      */
     private readonly autoLayoutScheduler;
     /**
@@ -482,7 +429,8 @@ export declare class Editor {
      * gestures, set in onDown when press lands on a shape and cleared
      * in onUp / cancel.
      */
-    dragElementId: ElementId | null;
+    get dragElementId(): ElementId | null;
+    set dragElementId(v: ElementId | null);
     /**
      * Element that the current press added to the selection additively
      * (shift / meta click on an unselected shape). The press promotes it
@@ -490,17 +438,16 @@ export declare class Editor {
      * otherwise `SELECT_TOGGLE` it straight back off, so it consults this
      * to skip that redundant toggle. Reset at every press-down.
      */
-    additivePressAdded: ElementId | null;
+    get additivePressAdded(): ElementId | null;
+    set additivePressAdded(v: ElementId | null);
     /**
      * Live container highlight: the container shape the dragged item is
      * currently hovering over. Drawn by the overlay as a dashed
      * accent rect on the container's drop-zone so the user sees where the
      * shape will land after release.
      */
-    containerHover: {
-        id: ElementId;
-        dropZone: Bounds;
-    } | null;
+    get containerHover(): ContainerHover | null;
+    set containerHover(v: ContainerHover | null);
     /**
      * Remote peer cursors / selections, pushed in by the host (typically
      * a `bindAwareness(editor, awareness)` helper in `@collab`). The
@@ -520,7 +467,7 @@ export declare class Editor {
      * two or more entries we enter a pinch / pan gesture and bypass the
      * interaction machine — `pinchOrigin` holds the baseline.
      */
-    readonly activePointers: Map<number, Vec2>;
+    get activePointers(): Map<number, Vec2>;
     /**
      * One-finger-pan candidate: set at pointer-down when a TOUCH press lands
      * on empty canvas in select mode. A tap (no movement) still falls through
@@ -528,9 +475,10 @@ export declare class Editor {
      * this to a real pan instead of a marquee lasso (mobile convention).
      * Screen-space origin point.
      */
-    touchPanCandidate: Vec2 | null;
+    get touchPanCandidate(): Vec2 | null;
+    set touchPanCandidate(v: Vec2 | null);
     pinch: PinchController;
-    /** Bridge for `editor/container-ops.ts`. Built lazily in constructor. */
+    /** Bridge for the container-ops helpers. Built lazily in constructor. */
     private containerOpsRef;
     /**
      * Space-bar held → next pointer drag pans the canvas instead of
@@ -538,7 +486,8 @@ export declare class Editor {
      * "grab" / "grabbing". Wires a window-level keydown/keyup listener
      * in `bindPointerEvents`.
      */
-    spaceHeld: boolean;
+    get spaceHeld(): boolean;
+    set spaceHeld(v: boolean);
     /**
      * Host-supplied tile compositor — when set (via
      * `EditorOptions.useTileCache` + `tileCompose`), the per-frame
@@ -588,20 +537,16 @@ export declare class Editor {
      * only treat right-click releases as potential context-menu
      * triggers (Space + left-drag never opens a menu).
      */
-    panGesture: {
-        pointerId: number;
-        button: number;
-        startPoint: Vec2;
-        lastPoint: Vec2;
-        moved: boolean;
-    } | null;
+    get panGesture(): PanGesture | null;
+    set panGesture(v: PanGesture | null);
     /**
      * Set on a right-click pointerdown so the upcoming native
      * `contextmenu` event can be unconditionally preventDefault'ed
      * (the gesture decides whether to fire the menu manually on
      * pointerup based on whether the user dragged).
      */
-    suppressNextContextMenu: boolean;
+    get suppressNextContextMenu(): boolean;
+    set suppressNextContextMenu(v: boolean);
     /**
      * Long-press tracking. Starts on `pointerdown`; cancelled on
      * `pointermove > LONG_PRESS_MAX_MOVEMENT_PX` or `pointerup` before
@@ -621,13 +566,13 @@ export declare class Editor {
      * in the constructor from `EditorOptions.inputMode` (default `"auto"`
      * uses `matchMedia('(pointer: coarse)')`).
      */
-    private readonly inputMode;
-    private readonly handleHitSlop;
-    private readonly edgeHandleHitSlop;
-    private readonly edgeHitThreshold;
+    private inputMode;
+    private handleHitSlop;
+    private edgeHandleHitSlop;
+    private edgeHitThreshold;
     /** Link-start anchor-dot grab/click hit radii — touch-enlarged in touch mode. */
-    readonly anchorStartHitSlop: number;
-    readonly anchorClickRadius: number;
+    anchorStartHitSlop: number;
+    anchorClickRadius: number;
     readonly _history: HistoryProvider;
     /** Open transaction during a single drag/resize gesture. */
     gestureTx: TransactionHandle | null;
@@ -642,13 +587,66 @@ export declare class Editor {
     /**
      * Wraps gesture lifecycle (transaction open/commit/cancel +
      * post-create mode revert) so editor.ts doesn't carry the bodies.
-     * Implementation lives in `./editor/gesture-tx.ts`; the
-     * controller calls back through the narrow `GestureRef` bridge
+     * The controller calls back through the narrow `GestureRef` bridge
      * built lazily below.
      */
-    private readonly gestures;
+    private gestures;
+    /**
+     * Owns the inline text-edit session (edited shape, pending creation,
+     * origin snapshot, live selection, drag anchor and caret blink).
+     * Editor keeps thin delegate wrappers so the public API is unchanged.
+     */
+    private textEdit;
+    /**
+     * Owns the link edit-handle drags (waypoint / segment / endpoint) and
+     * the handle double-click detector. Editor keeps thin delegate
+     * wrappers so the public API is unchanged.
+     */
+    private linkHandles;
     constructor(options: EditorOptions);
-    /** Snapshot used by event-fanout. Kept private — internal API. */
+    /**
+     * Build the interaction controllers (gestures, text edit, link-handle
+     * drag, long-press, pinch) and the container-ops bridge. Each wires to a
+     * narrow getter/setter surface over the editor's mutable fields, so the
+     * controllers live in their own modules without importing Editor. The
+     * getters/setters in the object literals rebind `this`, so a single
+     * `self` alias captures the Editor reference for all of them.
+     */
+    private initControllers;
+    /**
+     * Install process-global hooks the host opted into: a custom text shaper
+     * and rasterizer for the WebGL2 backend, plus the scene text measurer that
+     * routes through the renderer's own metrics so selection boxes hug text.
+     */
+    private initGlobalHooks;
+    /**
+     * Resolve the input mode (`touch` vs `mouse`, `auto` reads the coarse-
+     * pointer media query) and the derived hit slops / thresholds once.
+     */
+    private initInputMode;
+    /**
+     * Create and start the interaction state-machine actor, wire its render /
+     * emit subscriptions, register the built-in file-drop handlers, and apply
+     * the initial mode.
+     */
+    private initActor;
+    /**
+     * Last {@link observableSnapshot} object, reused while none of its slices
+     * have flipped. `null` until the first snapshot is built.
+     */
+    private snapshotCache;
+    /**
+     * Snapshot used by event-fanout. Kept private — internal API.
+     *
+     * Memoized by slice identity: `notify()` fires on many mutations that touch
+     * no observable slice (annotation focus, cursor pushes, viewport-only re-arm),
+     * so rebuilding the object every call is pure churn on the hot drag path.
+     * We reuse the cached object whenever all six slices compare equal (refs for
+     * mode/selection/selectedLinks/scene — scene uses structural sharing so a new
+     * ref iff something changed — plus the two history booleans), and only
+     * allocate a fresh one on a real flip. `fanOutEvents` sees identical values
+     * either way, so emitted events are unchanged.
+     */
     private observableSnapshot;
     get scene(): Scene;
     get selection(): Selection.Selection;
@@ -740,9 +738,24 @@ export declare class Editor {
      * values can be eyeballed. View-only — not recorded in history.
      */
     setDebugHitZones(on: boolean): void;
-    /** Show/hide the background grid (standard `g`). View-only — not in history. */
+    /**
+     * Read-only / view mode flag. `true` gates pointer edits and
+     * non-`viewMode` actions while leaving pan / zoom / select live.
+     */
+    get readOnly(): boolean;
+    /**
+     * Enter / leave read-only (view) mode. Notifies subscribers so the UI
+     * can re-render disabled chrome, and repaints (no visual diff today, but
+     * keeps the contract symmetric with other view toggles). Idempotent.
+     */
+    setReadOnly(on: boolean): void;
+    /** Toggle read-only (view) mode. */
+    toggleReadOnly(): void;
+    /** Whether the background grid is enabled for the scene. */
+    get gridEnabled(): boolean;
+    /** Show/hide the background grid (`g`). Persists in the viewport, not in history. */
     setGridVisible(on: boolean): void;
-    /** Toggle background grid visibility. */
+    /** Toggle the background grid on/off. */
     toggleGrid(): void;
     /** Whether the active draw-mode sticks after a create (toolbar lock). */
     get toolLocked(): boolean;
@@ -817,7 +830,7 @@ export declare class Editor {
         width: number;
         height: number;
         position: Vec2;
-        image?: HTMLImageElement;
+        image?: ImageBitmap | HTMLImageElement;
         animated?: boolean;
         fileId?: FileId;
         animationKind?: string;
@@ -831,24 +844,12 @@ export declare class Editor {
      * current frame of natively-animated elements. Self-terminates
      * when no animated shapes remain.
      *
-     * Lifecycle managed by the `AnimationTick` helper (see
-     * `./animation-tick.ts`). `insertImage({animated:true})` and
-     * `loadScene` start the tick; `dispose()` stops it.
-     */
-    /** EMA of animation-tick render cost (ms) — drives the adaptive throttle. */
-    private gifRenderCostEma;
-    /** Wall-clock of the last animation-tick render — for the interval throttle. */
-    private lastGifTickMs;
-    private readonly animationTick;
-    private hasAnimatedElement;
-    /**
-     * True when at least one animated shape's world AABB intersects the
-     * current viewport. Drives viewport-culling of the animation tick —
-     * off-screen GIFs don't burn decode / render cost, and the wall-clock
-     * frame selection means they show the right frame the moment they
-     * scroll back in.
+     * Lifecycle managed by the `AnimationTick` helper.
+     * `insertImage({animated:true})` and `loadScene` start the tick;
+     * `dispose()` stops it.
      */
-    private hasVisibleAnimatedElement;
+    private readonly animation;
+    private hasAnimatedElement;
     /**
      * Re-arm the animation tick after a change that may have brought an
      * animated shape into (or out of) view — pan / zoom / scene edit.
@@ -856,29 +857,12 @@ export declare class Editor {
      * `isAnimated()` is false, so this is cheap to call from `notify()`.
      */
     private maybeAnimate;
-    /** Bound `visibilitychange` handler — pause/resume the tick. */
-    private readonly onVisibilityChange;
-    /**
-     * Transient per-shape playback state for animated images. `originMs`
-     * is the wall-clock the current play run started; `frozenMs` is the
-     * playback offset a paused shape is held at. Not serialised — purely
-     * a runtime view, rebuilt on insert / rehydrate.
-     */
-    private readonly playbackState;
-    /** Element id currently hovered — a hovered heavy GIF keeps playing
-     *  (its auto-stop timer is held off). Set by the pointer hover path. */
-    private hoveredAnimatedId;
-    private static nowMs;
-    private static prefersReducedMotion;
-    /**
-     * Seed playback for a freshly-animated shape. Start paused (frozen on
-     * frame 0) when the user prefers reduced motion; playing otherwise.
-     */
-    private initPlayback;
-    /** Playback timestamp fed to the renderer's animation clock for a
-     *  shape: wall-clock when unmanaged, play offset when playing, the
-     *  frozen frame when paused. */
-    private playbackClock;
+    /**
+     * Per-shape GIF playback state (auto-stop + reduced-motion). Extracted into
+     * a controller; the Editor keeps the orchestration (scene iteration,
+     * animation tick, render scheduling) and delegates state ops here.
+     */
+    readonly gifPlayback: GifPlaybackController;
     /**
      * Toggle GIF playback for a shape — wired to a click on an animated
      * image (resume after auto-stop, play after reduced-motion). Resuming
@@ -908,25 +892,6 @@ export declare class Editor {
         elementId: ElementId;
         mode: "point" | "element";
     } | null;
-    /**
-     * Freeze heavy GIFs after `GIF_AUTOSTOP_MS` of continuous play.
-     * Light GIFs (small byte payload) loop forever. Called from the tick
-     * before each animation render.
-     */
-    private autoStopHeavyGifs;
-    /**
-     * Restore transient `animationData` for animated image shapes after
-     * a scene load. The raw GIF bytes don't survive serialisation
-     * (`serializeScene` strips the ArrayBuffer), but they're persisted
-     * in `Scene.files` via the shape's `fileId`. Here we copy the bytes
-     * back onto `shape.animationData` so the registered animation
-     * adapter (host-side, e.g. the gifuct decoder) can produce frames.
-     *
-     * Applied directly to `_scene` (no history entry — this is an
-     * internal rehydration, not a user edit). No-op for shapes that
-     * already carry live `animationData` or lack a resolvable file.
-     */
-    private rehydrateAnimatedImages;
     /**
      * Drag-to-place flow for palette templates. Adds the shape to the
      * scene immediately so the user sees it dragging under the cursor,
@@ -948,11 +913,10 @@ export declare class Editor {
      * cleared by `commitTextEdit` / `cancelTextEdit`. The host overlay
      * (`<TextEditorOverlay>` in `@react-ui`) subscribes via `editor`
      * and renders a `<textarea>` positioned over the shape.
+     * State lives in `TextEditController`; this is a delegate.
      */
-    private _editingTextElement;
     get editingTextElement(): ElementId | null;
     /** Link whose caption is being edited inline (double-click), or null. */
-    private _editingLinkCaption;
     get editingLinkCaption(): LinkId | null;
     /**
      * Frame whose NAME (header label) is being edited inline (double-click
@@ -961,30 +925,6 @@ export declare class Editor {
      */
     private _editingFrameName;
     get editingFrameName(): ElementId | null;
-    /**
-     * When the `draw-text` tool just placed a shape and opened its
-     * editor, this holds that shape's id until the first commit. A
-     * pending creation isn't in history yet: committing non-empty text
-     * records a single add patch (whole shape = one undo); committing
-     * empty / cancelling removes it with no history entry at all.
-     */
-    private _pendingTextCreate;
-    /**
-     * Snapshot of the shape at edit start. Used to revert on cancel and
-     * as the `before` of the single commit patch. `null` for a pending
-     * creation (the shape didn't exist yet).
-     */
-    private _textEditOrigin;
-    /**
-     * Live selection inside the edited text, mirrored from the hidden
-     * `<textarea>` (`start`/`end` are source offsets, `dir` is the
-     * anchored end). The caret is `dir === "backward" ? start : end`.
-     */
-    private _textSel;
-    /** Anchor offset for a canvas drag-select inside the edited text. */
-    private _textDragAnchor;
-    private _caretBlinkOn;
-    private _caretBlinkTimer;
     get editingTextSelection(): {
         start: number;
         end: number;
@@ -995,10 +935,6 @@ export declare class Editor {
     get caretBlinkOn(): boolean;
     /** `true` while a canvas drag-select inside the edited text is active. */
     get isTextDragging(): boolean;
-    private startCaretBlink;
-    private stopCaretBlink;
-    /** Reset the caret to solid (called on type / move so it never blinks off mid-action). */
-    private wakeCaret;
     /**
      * Begin editing a text shape's body. No-op when the shape doesn't
      * exist or isn't a text shape. Concurrent edits commit themselves
@@ -1064,15 +1000,6 @@ export declare class Editor {
     extendTextSelectionToPoint(worldPoint: Vec2): void;
     /** End a canvas drag-select (clears the drag anchor). */
     endTextDragSelect(): void;
-    /** Build the editable layout for a text shape using the main target's metrics. */
-    private editingTextLayout;
-    /**
-     * A measure callback bound to a shape's font, using the main target's
-     * `measureText` — the SAME source the renderer draws with (WebGL2
-     * reports MSDF advances) and the bounder measures with. Caret /
-     * selection geometry therefore lines up exactly with the glyphs.
-     */
-    private measureFor;
     /**
      * World-space caret + selection geometry for the overlay pass.
      * Returns `null` when not editing. The caret is `null` while blinked
@@ -1115,6 +1042,15 @@ export declare class Editor {
      * the tool is locked.
      */
     createTextAt(worldPoint: Vec2): ElementId;
+    /** Current brush paint settings (line colour, fill, opacity, width). */
+    private _brushSettings;
+    get brushSettings(): BrushSettings;
+    /**
+     * Update one or more brush paint settings (e.g. from the drawing panel). New
+     * strokes pick them up on commit; the width also drives the pressure curve and
+     * the eraser radius. Merges over the current settings.
+     */
+    setBrushSettings(patch: Partial<BrushSettings>): void;
     beginBrushStroke(world: Vec2, pressure?: number): void;
     extendBrushStroke(world: Vec2, pressure?: number): void;
     commitBrushStroke(): ElementId | null;
@@ -1124,6 +1060,53 @@ export declare class Editor {
         readonly origin: Vec2;
         readonly points: readonly BrushPoint[];
     } | null;
+    /**
+     * Start an eraser stroke at `world`, seeding it with the shape under it so a
+     * plain click erases. With `restore` (Alt held at press) it seeds nothing —
+     * the gesture is in un-mark mode, and there's nothing marked yet to rescue.
+     */
+    beginEraseStroke(world: Vec2, restore?: boolean, strokeErase?: boolean): void;
+    /**
+     * Incrementally mark the brush points erased by the eraser segment `a → b`
+     * (world). Iterates the current brushes and grows `stroke.erased` in place —
+     * O(points) per move (each already-erased point is skipped), so a long drag
+     * no longer costs O(points × path length) per frame. Radius is the on-screen
+     * eraser ring converted to world units.
+     */
+    private markStrokeEraseSegment;
+    /**
+     * Extend the eraser stroke to `world`, sweeping shapes along the segment.
+     * `restore` (Alt held) un-marks swept shapes instead of marking them.
+     */
+    extendEraseStroke(world: Vec2, restore?: boolean): void;
+    /**
+     * Commit the eraser stroke — delete every swept shape in ONE undo step (with
+     * their attached links). No-op delete when nothing was swept. Returns the
+     * count removed.
+     */
+    commitEraseStroke(): number;
+    /** Abort the eraser stroke without deleting anything. */
+    cancelEraseStroke(): void;
+    /** True only while the pointer is down in laser mode (a trail is being laid). */
+    get laserDrawing(): boolean;
+    /** Start a laser trail at `world` (ephemeral — never enters the scene). */
+    beginLaserStroke(world: Vec2): void;
+    /** Append a point to the active laser trail (no-op unless drawing). */
+    extendLaserStroke(world: Vec2): void;
+    /** End the active laser trail — it keeps fading via the animation tick. */
+    endLaserStroke(): void;
+    /**
+     * True while any laser trail OR eraser trail still has visible points (drives
+     * the fade tick — so the trail keeps melting after the pointer stops).
+     */
+    hasActiveLaser(): boolean;
+    /** Live eraser drag trail (ephemeral, fading). Empty when none active. */
+    get eraserTrail(): readonly LaserStroke[];
+    /**
+     * Drop expired laser/eraser trail points (called once per frame before paint).
+     * Self-terminating: once both arrays empty the animation tick stops.
+     */
+    private pruneLaser;
     arrangeAsGrid(opts?: {
         cols?: number;
         gap?: number;
@@ -1157,6 +1140,14 @@ export declare class Editor {
      */
     duplicateSelectedInPlace(anchorId?: ElementId | null): ElementId | null;
     setSelection(ids: Iterable<ElementId>): void;
+    /**
+     * Programmatically select a single link by id (or clear the link
+     * selection with `null`), clearing the element selection so the link
+     * becomes the sole selection. Used by host navigation (search / jump-to)
+     * to frame an edge with {@link zoomToSelection}. No-op when nothing
+     * would change.
+     */
+    selectLink(id: LinkId | null): void;
     selectAll(): void;
     /**
      * Internal clipboard. Stored as deep-cloned snapshots so subsequent
@@ -1185,7 +1176,190 @@ export declare class Editor {
      *
      * No-op when `ids` is empty or none of the targeted shapes exist.
      */
+    /**
+     * Capture the visual style of the first selected element into the style
+     * buffer, for a later {@link pasteSelectionStyle}. No-op / clears nothing
+     * when the selection is empty.
+     */
+    copySelectionStyle(): void;
+    /** Apply the copied style (if any) to every selected element. One undo step. */
+    pasteSelectionStyle(): void;
+    /** Whether a style has been copied and can be pasted. */
+    get hasStyleClipboard(): boolean;
     updateStyle(ids: Iterable<ElementId>, partial: Partial<TextStyle>): void;
+    /**
+     * Apply a partial text style (bold / italic / colour / decoration) to the
+     * character range `[from, to)` of a single text element, producing styled
+     * runs (rich text). One undo step. No-op when the id isn't a text shape or
+     * the range is empty. Read-only editors ignore it. Use this — rather than
+     * `updateStyle` — to style only PART of a text block (e.g. the current
+     * inline-edit selection).
+     */
+    applyTextStyleToRange(id: ElementId, from: number, to: number, partial: Partial<TextStyle>): void;
+    /**
+     * The fill (or stroke, per `role`) colour of the top-most shape under the
+     * world point, or `null` on empty canvas. Pure read — no mutation.
+     */
+    pickColorAt(worldPoint: Vec2, role?: "fill" | "stroke"): Color | null;
+    /** One-shot callback armed by {@link beginEyedropperPick}; consumes the next canvas click. */
+    private pendingEyedropperPick;
+    /** `true` while a colour-picker pipette is armed and waiting for a canvas click. */
+    get isEyedropperArmed(): boolean;
+    /**
+     * Arm the eyedropper for a one-shot canvas pick that routes the sampled colour
+     * to `onPick` (e.g. a colour-picker swatch) instead of the selection fill. Does
+     * NOT change the tool mode — the next canvas press is intercepted by
+     * {@link applyEyedropperAt}. Cancelled by a mode switch or an empty-canvas click.
+     */
+    beginEyedropperPick(onPick: (color: Color) => void): void;
+    /**
+     * Sample the colour under `worldPoint`. When a pipette pick is armed (see
+     * {@link beginEyedropperPick}), route the colour to that callback and disarm.
+     * Otherwise (legacy tool path) apply it as the current selection's fill and
+     * revert to `select` mode. Returns the sampled colour, or `null` on empty
+     * canvas. Read-only editors sample but don't mutate.
+     */
+    applyEyedropperAt(worldPoint: Vec2): Color | null;
+    /**
+     * Convert every convertible selected shape (rectangle / ellipse / diamond)
+     * to `target`, preserving position, size and style. One undo step; no-op
+     * when nothing applies. See {@link ConvertTarget}.
+     */
+    convertSelection(target: ConvertTarget): void;
+    /**
+     * Flowchart auto-generate: clone the single selected node offset in
+     * `direction` and connect the two with a fresh link. Selects the new node.
+     * No-op unless exactly one element is selected. One undo step.
+     */
+    spawnConnectedNode(direction: SpawnDirection): void;
+    /**
+     * Pending flowchart-create session, or `null` when idle. Holds the ORIGINAL
+     * source id + direction, the current sibling `count`, and the pending
+     * `elements` + `links` (a PREVIEW — not yet in the scene / history). Grown by
+     * {@link growFlowchart}, committed by {@link commitFlowchart}, discarded by
+     * {@link cancelFlowchart}.
+     */
+    private flowchartSession;
+    /**
+     * Grow the flowchart-create preview one step in `direction`. Starts a session
+     * (count = 1) when idle or when the direction changes; otherwise bumps the
+     * sibling count up to {@link FLOWCHART_MAX_SIBLINGS}. Recomputes the pending
+     * nodes/links from the ORIGINAL source each call. PREVIEW ONLY — never
+     * touches the scene or history until {@link commitFlowchart}. No-op in
+     * read-only mode or unless exactly one element is selected.
+     */
+    growFlowchart(direction: SpawnDirection): void;
+    /**
+     * Commit the pending flowchart-create preview: add every pending node + link
+     * to the scene as ONE undo step, select the first new node, clear the
+     * session. Returns the first new node's id, or `null` when no session is
+     * active.
+     */
+    commitFlowchart(): ElementId | null;
+    /** Discard the pending flowchart-create preview without committing. */
+    cancelFlowchart(): void;
+    /**
+     * The pending flowchart-create preview (nodes + links), or `null` when no
+     * session is active. Read by the render snapshot to paint the preview on the
+     * overlay. Reference-stable between renders (only changes on grow / commit /
+     * cancel) so the overlay memo doesn't thrash.
+     */
+    get flowchartPreview(): {
+        readonly elements: readonly Element[];
+        readonly links: readonly Link[];
+    } | null;
+    /**
+     * Move the selection to an adjacent node. With exactly one element selected,
+     * prefers a graph neighbour (linked node) best aligned with `direction`;
+     * falls back to the spatial {@link selectClosest} when no neighbour lies that
+     * way. No-op unless exactly one element is selected.
+     */
+    navigateFlowchart(direction: "left" | "right" | "up" | "down"): void;
+    /**
+     * Live image-crop session, or `null` when not cropping. Excalidraw-style:
+     * the crop frame IS the element's visible box, and the user drags edge /
+     * corner handles inward (hides pixels) or the image body (pans the source).
+     *
+     * - `id` — the image being cropped.
+     * - `crop` — pending normalised source rect.
+     * - `position` / `width` / `height` — the pending element box (world position
+     *   + local size); a handle drag moves them, a body pan leaves them fixed.
+     * - `drag` — the active gesture, or `null` when only hovering.
+     * - `dragStartWorld` — pointer world position at drag start (body pan basis).
+     *
+     * Seeded on {@link beginImageCrop}; committed by {@link commitImageCrop} (one
+     * undo step), abandoned by {@link cancelImageCrop}.
+     */
+    cropSession: {
+        id: ElementId;
+        crop: ImageCrop;
+        position: Vec2;
+        width: number;
+        height: number;
+        drag: {
+            kind: "handle";
+            handle: CropHandle;
+        } | {
+            kind: "body";
+        } | null;
+        dragStartWorld: Vec2 | null;
+    } | null;
+    /** The image-crop session (read-only accessor for UI / overlay). */
+    get imageCropSession(): {
+        readonly id: ElementId;
+        readonly crop: ImageCrop;
+        readonly position: Vec2;
+        readonly width: number;
+        readonly height: number;
+    } | null;
+    /**
+     * Enter crop mode for the image `id`, seeding the pending crop / box from its
+     * current state (or the full image). No-op for non-image shapes or in
+     * read-only. Typically triggered by a double-click on an image.
+     */
+    beginImageCrop(id: ElementId): void;
+    /**
+     * Hit-test `worldPoint` against the pending crop chrome: a crop handle when
+     * within {@link CROP_HANDLE_HIT_RADIUS} (screen px, zoom-compensated) of one,
+     * `"body"` when inside the window, else `null`. Returns `null` when not
+     * cropping.
+     */
+    cropHandleAtWorld(worldPoint: Vec2): CropHandle | "body" | null;
+    /** Begin dragging crop handle `handle` from `worldPoint`. */
+    beginImageCropHandle(handle: CropHandle, worldPoint: Vec2): void;
+    /** Begin panning the image body under the fixed window from `worldPoint`. */
+    beginImageCropBody(worldPoint: Vec2): void;
+    /**
+     * Update the active crop drag to `worldPoint` — resize the window (handle) or
+     * pan the source (body). Geometry is recomputed from the ORIGINAL element so
+     * it stays stable across many moves. No-op when no drag is active.
+     */
+    updateImageCropDrag(worldPoint: Vec2): void;
+    /** Finish the current crop drag (keeps the pending crop / box). */
+    endImageCropDrag(): void;
+    /** Apply the pending crop + box and leave crop mode. One undo step. */
+    commitImageCrop(): void;
+    /** Abandon the crop session without changing the image. */
+    cancelImageCrop(): void;
+    /**
+     * Synthetic element carrying the PENDING crop box (position / size) over the
+     * original element's rotation / scale — the frame the user currently sees.
+     * Used to project the crop frame and handles.
+     */
+    private pendingCropElement;
+    /**
+     * World-space corners (clockwise) of the pending crop frame, or `null` when
+     * not cropping. The frame is the pending element box mapped through its
+     * local→world transform (so rotation / scale are honoured).
+     */
+    private cropFrameCorners;
+    /**
+     * Ghost-image overlay descriptor for the crop session: the ORIGINAL element
+     * (its transform + live bitmap handle) and the virtual full-image LOCAL rect
+     * the whole bitmap occupies. `null` when not cropping. The overlay paints the
+     * full bitmap faintly over this rect so hidden parts stay visible.
+     */
+    private cropGhost;
     /**
      * Update non-style text properties (`fontSize`, `fontFamily`,
      * `maxWidth`) on every selected text shape. Non-text shapes are
@@ -1196,6 +1370,12 @@ export declare class Editor {
         fontFamily?: string;
         maxWidth?: number;
     }): void;
+    /**
+     * Step the font size of every selected text shape up or down by one gentle
+     * multiplicative increment (each shape relative to its own size). One
+     * undoable step; no-op when no text is selected.
+     */
+    adjustSelectionFontSize(direction: "increase" | "decrease"): void;
     /**
      * Set (or clear, with `null`) the element-level hyperlink (`href`) on
      * every shape in `ids`. Single undo step. Pass a raw user string — it
@@ -1229,6 +1409,32 @@ export declare class Editor {
     bringForward(id?: ElementId): void;
     /** Move the target shape one step toward the bottom of its layer. */
     sendBackward(id?: ElementId): void;
+    /**
+     * Mirror the current selection about its bounding-box centre on the given
+     * axis — `horizontal` flips left↔right, `vertical` flips top↔bottom. A single
+     * element flips about its own centre. One undoable step.
+     */
+    flipSelection(axis: FlipAxis): void;
+    /**
+     * Align the selection to the given edge / centre line of its bounding box
+     * (e.g. `left` flushes every shape's left edge; `h-center` lines up
+     * horizontal centres). Needs two or more elements. One undoable step.
+     */
+    alignSelection(edge: AlignEdge): void;
+    /**
+     * Evenly space the selection along the given axis so the gaps between
+     * adjacent shapes are equal; the outermost shapes stay put. Needs three or
+     * more elements. One undoable step.
+     */
+    distributeSelection(axis: DistributeAxis): void;
+    /**
+     * Rotate the whole selection by `delta` radians about its bounding-box centre
+     * (a single shape turns about its own centre). One undoable step. The live
+     * rotate gesture drives the same maths from a press-time snapshot.
+     */
+    rotateSelection(delta: number): void;
+    /** Apply a batch of arrange patches as a single undoable step. */
+    private commitArrange;
     compactLayerZOrder(layerId?: LayerId, options?: {
         recordHistory?: boolean;
     }): void;
@@ -1262,6 +1468,13 @@ export declare class Editor {
     zoomToFit(padding?: number): void;
     /** Fit the camera to the current selection (standard `⌥2`). No-op when empty. */
     zoomToSelection(padding?: number): void;
+    /**
+     * Center the camera on the current selection for a reveal / jump-to (search
+     * navigation). Unlike {@link zoomToSelection}, it does NOT fill the screen —
+     * a small match keeps its size and is merely centered; the zoom only drops to
+     * fit an oversized match. No-op when the selection is empty.
+     */
+    revealSelection(padding?: number): void;
     /**
      * Select the nearest interactable top-level element in `direction` from the
      * current selection's centre (or the viewport centre when nothing is
@@ -1273,7 +1486,7 @@ export declare class Editor {
     zoomAt(factor: number, anchorWorld: Vec2): void;
     setViewportSize(width: number, height: number): void;
     setGrid(patch: {
-        size?: number;
+        enabled?: boolean;
         style?: GridStyle;
         snap?: boolean;
     }): void;
@@ -1288,13 +1501,20 @@ export declare class Editor {
      */
     setSnapSuppressed(suppressed: boolean): void;
     /**
-     * True when a gesture should snap. Snapping is coupled to grid *display*:
-     * it is active only while a grid is actually shown — the toggle is on
-     * (`gridVisible`, `g` hotkey) AND the scene has a positive `gridSize` (the
-     * same condition `renderGrid` paints under). Snapping to an invisible grid
-     * is confusing, so no grid → no snap, always. `snapToGrid` is an extra
-     * programmatic opt-out; the suppress modifier (Cmd/Ctrl) bypasses snapping
-     * for the current gesture.
+     * Host hook: mirror the Alt / Shift modifier state so an in-flight resize or
+     * move reacts to it — `alt` resizes about the centre, `shift` locks the
+     * resize aspect ratio (or constrains a move to one axis). The app wires
+     * keydown/keyup of the modifiers to this. Idempotent; never touches history.
+     */
+    setTransformModifiers(mods: {
+        readonly alt: boolean;
+        readonly shift: boolean;
+    }): void;
+    /**
+     * True when a gesture should snap. Snapping is coupled to grid display:
+     * it is active only while the grid is enabled (`gridEnabled`) — snapping to
+     * a hidden grid is confusing. `snapToGrid` is an extra programmatic opt-out;
+     * the suppress modifier (Cmd/Ctrl) bypasses snapping for the current gesture.
      */
     private snapActive;
     /** World-unit spacing the current gesture snaps to. */
@@ -1350,16 +1570,6 @@ export declare class Editor {
      * out of sync. `worldPoint` defaults to the last known pointer position.
      */
     refreshCursor(worldPoint?: Vec2): void;
-    /**
-     * The CSS cursor for the current state. Priority: active gesture → text edit → pan affordance →
-     * draw tool → idle hover hit-test. Pure read of editor state; no side effects.
-     */
-    private computeCursor;
-    /**
-     * Resolve a cursor role to a CSS `cursor` value: a host-registered custom
-     * image (via {@link setCursorOverride}) if present, else `fallbackKeyword`.
-     */
-    private resolveCursor;
     /**
      * Register (or clear, with `null`) a custom cursor image for a state role.
      * The image is shown wherever `computeCursor` resolves that role; pass a
@@ -1369,12 +1579,11 @@ export declare class Editor {
      */
     setCursorOverride(role: CursorRole, spec: CursorSpec | null): void;
     /**
-     * True when `p` is within the grab radius of one of the single selected
-     * element's link-start dots — used to show a `crosshair` (start a link).
-     * Mirrors the anchor-drag hit-test in pointer-binding so the cursor matches
-     * exactly where a press would begin a link.
+     * Read-only lookup of a host-registered cursor override. Used by the cursor
+     * module to resolve a role without exposing the mutable override map (mutate
+     * only via {@link setCursorOverride}, so `refreshCursor` stays in sync).
      */
-    private isOverLinkStartDot;
+    getCursorOverride(role: CursorRole): CursorSpec | undefined;
     /** True when the given layer exists and is marked `locked`. */
     private isLayerLocked;
     /**
@@ -1418,8 +1627,7 @@ export declare class Editor {
      * Topmost group ancestor of `shape` (walks parentId chain, returns
      * the highest `type === "group"` parent). `null` if `shape` has no
      * group ancestor. Used by drill-down: a double-click on a shape
-     * with a group ancestor enters that group. Body extracted to
-     * `./group-helpers.ts`.
+     * with a group ancestor enters that group.
      */
     private topGroupAncestor;
     /**
@@ -1443,7 +1651,22 @@ export declare class Editor {
      * selected, you can see".
      */
     computeHiddenElements(): ReadonlySet<ElementId> | undefined;
+    /**
+     * Live stroke-erase preview: while a Shift-held eraser gesture drags, the
+     * fragments each touched brush WOULD become, plus the set of touched
+     * originals to hide in the main pass. `null` outside a stroke-erase gesture
+     * or when the path touches no brush. Recomputed each frame from the
+     * path-so-far — never mutates the scene or history.
+     */
+    private computeStrokeErasePreview;
     computeDimElements(enteredGroupId: ElementId): ReadonlySet<ElementId>;
+    /**
+     * Dim set fed to the renderer: group-isolation dim UNION the eraser's
+     * pending-delete set (shapes swept by the current eraser stroke are shown
+     * dimmed so the user sees what release will delete). `undefined` when neither
+     * is active, keeping the fast tile-cache render path.
+     */
+    private computeDimSet;
     /**
      * Enter a group — subsequent hits inside this group return children
      * directly instead of the group root. `null` exits group-edit mode.
@@ -1583,6 +1806,13 @@ export declare class Editor {
      * grouping is the explicit "lock the ratio" gesture).
      */
     selectionIsAspectLocked(): boolean;
+    /**
+     * Per-frame rotate during a grip drag: turn the press-time snapshot by
+     * `deltaAngle` about its pivot. Shift snaps the swept angle to
+     * {@link ROTATE_SNAP_RADIANS} steps. Recorded as gesture patches (one undo
+     * step on commit).
+     */
+    private applyRotate;
     private applyGroupResize;
     private applyResize;
     private applyCreate;
@@ -1808,9 +2038,8 @@ export declare class Editor {
     /**
      * Typed event surface — subscribe to a specific slice (`mode`,
      * `selection`, `scene`, `history`, `viewport`) or the umbrella
-     * `change`. Replaces ad-hoc selectors over the coarse `subscribe()`
-     * for callers that only care about one dimension. The legacy
-     * `subscribe()` still works and fires in lock-step.
+     * `change`. For callers that only care about one dimension;
+     * `subscribe()` fires in lock-step with these.
      */
     on<K extends keyof EditorEvents>(event: K, fn: EditorEvents[K]): () => void;
     off<K extends keyof EditorEvents>(event: K, fn: EditorEvents[K]): void;
@@ -1825,20 +2054,48 @@ export declare class Editor {
      */
     runLayout(parentId: ElementId): Patch | null;
     /**
-     * Per-link signature of the inputs that determine an elbow route
-     * (endpoint refs + bound-shape bounds + fixedSegments). When unchanged
-     * between frames the A* route is reused — see `rerouteElbows`.
+     * Derived elbow-route cache, keyed by link — the source of truth for
+     * A*-routed corners, living OUTSIDE the immutable `Scene`. Each entry holds
+     * the routed interior `points` (between from/to) plus the `sig` of the
+     * inputs it was computed from (endpoint refs + bound-shape bounds +
+     * fixedSegments), so an unchanged link short-circuits the reroute.
+     *
+     * `rerouteElbows` still MIRRORS `points` onto `Link.routedPoints` in
+     * `_scene` because three readers still consume the baked field: the render
+     * path (`getLinkPath` in `renderer-core`), the headless `getLinkPath`, and
+     * serialization (`schema.ts`). The mirror is compat-only derived state — no
+     * history push / notify.
+     *
+     * TODO(fable R7a): drop the `_scene` mirror once (a) the render path reads
+     * routes from this cache via the `RenderSnapshot`, and (b) headless
+     * `getLinkPath` / serialization stop depending on baked `routedPoints`.
+     * That eviction changes headless geometry, serialized output, and
+     * collab-synced fields, so it spans the scene / serialization / renderer /
+     * headless goldens and must land as its own cross-package change — out of
+     * scope for this state-only pass.
+     */
+    private readonly elbowRoutes;
+    /**
+     * Choke-point reroute (standard model): recompute the route for every
+     * orthogonal link whose inputs changed since the last pass, store it in the
+     * derived {@link elbowRoutes} cache, and mirror it onto `_scene`. Runs once
+     * per frame before paint — derived state, so no history push / notify (would
+     * loop). Cheap when nothing moved (signature short-circuit).
      */
-    private readonly elbowRouteSig;
-    private elbowSignature;
+    private rerouteElbows;
     /**
-     * Choke-point reroute (standard model): recompute `routedPoints` for
-     * every orthogonal link whose inputs changed since the last pass, and
-     * bake the result into `_scene`. Runs once per frame before paint —
-     * derived state, so no history push / notify (would loop). Cheap when
-     * nothing moved (signature short-circuit).
+     * Collect everything {@link renderEditor} paints from into a flat
+     * {@link RenderSnapshot}. Resolves the derived viewport / dirty-rect / dim /
+     * hide inputs and the shared spatial index up front (same order the
+     * orchestrator used to call them in), so the paint pass stays side-effect
+     * free and the orchestrator stays decoupled from this class.
+     *
+     * `computeDirtyWorld` is order-sensitive (it diffs against
+     * `lastRenderedScene` and populates `tileDirtyElements`); it runs here and
+     * the `lastRendered*` bookkeeping is applied in `render()` after the paint.
      */
-    private rerouteElbows;
+    private buildRenderSnapshot;
     private render;
 }
+/** Distance from point `p` to the finite segment `a`–`b` (world space). */
 //# sourceMappingURL=editor.d.ts.map