@oh-just-another/state 0.59.0 → 0.60.0

package/dist/editor.d.ts

@@ -1,8 +1,8 @@
 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";
@@ -12,8 +12,12 @@ 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";
@@ -53,6 +57,13 @@ 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
@@ -127,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
@@ -155,7 +175,15 @@ export declare class Editor {
      * View-only — never persisted or recorded in history.
      */
     debugHitZones: boolean;
-    readonly actor: Actor<typeof interactionMachine>;
+    /**
+     * 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}.
+     */
+    private _readOnly;
+    actor: Actor<typeof interactionMachine>;
     private readonly listeners;
     /**
      * Typed event surface. Specific events (`mode`, `selection`,
@@ -178,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
@@ -271,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;
@@ -283,83 +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;
-    /**
-     * Press-time snapshot for a rotate gesture: the pivot (selection bbox centre)
-     * and every member's pristine `position` / `rotation`. Each frame rotates
-     * from this baseline so the cumulative angle never drifts. Cleared on gesture
-     * end (commit / cancel).
-     */
-    rotateGestureOrigin: {
-        readonly pivot: Vec2;
-        readonly origin: ReadonlyMap<ElementId, {
-            readonly position: Vec2;
-            readonly rotation: number;
-        }>;
-    } | 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
@@ -375,21 +318,6 @@ export declare class Editor {
     private readonly snapEngine;
     /** 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.
-     */
-    private snapSuppressed;
-    /**
-     * Transient transform-modifier state mirrored from the host while a drag is
-     * in flight. `alt` resizes symmetrically about the centre; `shift` locks the
-     * resize aspect ratio or constrains a move to a single axis. Read by the
-     * move / resize wrappers; never persisted.
-     */
-    private transformAltKey;
-    private transformShiftKey;
     /**
      * In-editor style memory for copy-style / paste-style. Holds the visual
      * `style` (fill / stroke / dash / …) captured from a shape; `null` until a
@@ -417,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;
     /**
@@ -465,6 +394,23 @@ 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
@@ -483,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
@@ -491,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
@@ -521,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
@@ -529,7 +475,8 @@ 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 the container-ops helpers. Built lazily in constructor. */
     private containerOpsRef;
@@ -539,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
@@ -589,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
@@ -622,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;
@@ -646,9 +590,63 @@ export declare class Editor {
      * 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,6 +738,19 @@ export declare class Editor {
      * values can be eyeballed. View-only — not recorded in history.
      */
     setDebugHitZones(on: boolean): void;
+    /**
+     * 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. */
@@ -902,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
@@ -915,29 +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 readonly caretBlink;
     get editingTextSelection(): {
         start: number;
         end: number;
@@ -1013,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
@@ -1064,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;
@@ -1073,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;
@@ -1106,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
@@ -1145,6 +1187,179 @@ export declare class Editor {
     /** 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
@@ -1253,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
@@ -1429,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.
@@ -1817,19 +2054,47 @@ 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 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). */