@oh-just-another/state 0.57.0

package/dist/editor.d.ts

@@ -0,0 +1,1841 @@
+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 { 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 { LongPressController } from "./editor/long-press.js";
+import { PinchController } from "./editor/pinch.js";
+import { type BrushStrokeState } from "./editor/public/brush.js";
+import { type PeerCursor, type PeerSelection } from "./overlay.js";
+import * as Selection from "./selection.js";
+import * as LinkSelection from "./link-selection.js";
+export interface LoadSceneOptions {
+    /**
+     * Keep the existing undo/redo stack when swapping scenes. Used by
+     * `@collab/bindEditor` when a peer update arrives — the user's
+     * local history must survive remote edits. Default `false`:
+     * top-level callers loading a saved scene get a clean slate.
+     *
+     * When `true`, history patches that reference shapes removed by the
+     * remote peer become un-applicable: the local user sees an undo no-op
+     * or an exception on that step.
+     */
+    readonly preserveHistory?: boolean;
+}
+export interface EditorOptions {
+    readonly host: HTMLElement;
+    readonly mainTarget: RenderTarget;
+    readonly overlayTarget: RenderTarget;
+    /**
+     * Optional dedicated background target — when provided, the editor
+     * paints the grid (`renderGrid`) onto it. Hosts without a background
+     * layer can omit this; in that case the grid is drawn on `mainTarget`
+     * before shapes.
+     */
+    readonly backgroundTarget?: RenderTarget;
+    /**
+     * Called synchronously at the END of every render pass, right after the
+     * targets have been painted. Hosts whose surface defers submission
+     * (WebGL2 flush, OffscreenCanvas worker replay) MUST present here — not
+     * on `subscribe()`, which fires on `notify()` BEFORE the rAF-scheduled
+     * paint, leaving the surface one frame behind. No-op surfaces (Canvas2D)
+     * can omit it.
+     */
+    readonly onAfterRender?: () => void;
+    readonly initialScene: Scene;
+    readonly initialMode?: Mode;
+    /**
+     * Pre-existing history backend, or options for the default
+     * `History` (linear stack). Any `HistoryProvider` implementation
+     * works — `@oh-just-another/collab` ships `YjsHistory` that wraps
+     * `Y.UndoManager` for CRDT-aware undo in collaborative sessions.
+     */
+    readonly history?: HistoryProvider | HistoryOptions;
+    /**
+     * Primary input modality. Affects hit-test slop on handles and edges
+     * so a finger can grab them without precision-pointing.
+     *
+     * - `"mouse"` — pixel-accurate hit zones (default for desktop).
+     * - `"touch"` — 44 px+ touch targets (Apple HIG, WCAG AAA).
+     * - `"auto"` — pick `"touch"` if `matchMedia('(pointer: coarse)')`
+     *   reports a coarse primary pointer, else `"mouse"`. Default.
+     */
+    readonly inputMode?: "mouse" | "touch" | "auto";
+    /**
+     * Optional text shaper. When supplied, replaces the renderer's
+     * default Canvas2D `measureText` path for wrap / layout. Plug
+     * `WasmTextShaper.loadBundled()` from `@oh-just-another/text-wasm`
+     * for deterministic browser-vs-Node parity (Roboto Regular
+     * embedded; advance widths match across environments).
+     */
+    readonly textShaper?: TextShaper;
+    /**
+     * Optional rasterizer. When supplied, hosts of `renderLinks` /
+     * future path-heavy code can opt in to WASM bezier / stroke-to-
+     * fill via `WasmRasterizer.loadBundled()` from
+     * `@oh-just-another/raster-wasm`. The kernel itself doesn't consume
+     * this directly today — exposed here so the field travels with
+     * `EditorOptions` and hosts have a single config surface.
+     */
+    readonly rasterizer?: Rasterizer;
+    /**
+     * When `true`, the editor routes per-frame rendering through a
+     * tile compositor (`renderViaTiles` in renderer-canvas) backed
+     * by an InMemoryTileCache. Designed for very-large scenes
+     * (10 K+ shapes) where re-rasterising every visible shape per
+     * frame dominates frame budget. Below ~5 K shapes the plain
+     * scene-renderer is usually faster — leave this off.
+     *
+     * Host must supply a tile compositor function via
+     * `tileCompose`; the kernel doesn't import renderer-canvas
+     * directly. Pattern:
+     *
+     *   import { renderViaTiles } from "@oh-just-another/renderer-canvas";
+     *   new Editor({ ..., useTileCache: true, tileCompose: renderViaTiles });
+     */
+    readonly useTileCache?: boolean;
+    /**
+     * Compositor function called per frame when `useTileCache` is on.
+     * Receives the scene, main target, and dirty bookkeeping; should
+     * handle caching internally.
+     */
+    readonly tileCompose?: TileComposeFn;
+}
+/**
+ * Signature of the tile compositor injected via EditorOptions. Editor
+ * stays decoupled from renderer-canvas; hosts wire the concrete
+ * implementation (`renderViaTiles`).
+ */
+export type TileComposeFn = (scene: Scene, mainTarget: RenderTarget, options: {
+    readonly viewport: Bounds;
+    /**
+     * Per-shape change record (before/after world bbox) since the
+     * last frame. Compositors route by case (add / remove / move).
+     * `null` on one side = added / removed.
+     */
+    readonly changedElements: ReadonlyMap<ElementId, {
+        before: Bounds | null;
+        after: Bounds | null;
+    }>;
+    readonly zoomBucket: number;
+}) => void;
+/**
+ * Top-level interaction controller. Owns the scene + selection state, wires
+ * pointer events from the host element into the interaction machine, applies
+ * the machine's emitted effects back to the scene, and re-renders main and
+ * overlay on every change.
+ */
+/** Outcome of `Editor.groupSelected`. `noop` when nothing was selected. */
+export type GroupSelectedResult = {
+    readonly kind: "noop";
+} | {
+    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 declare class Editor {
+    readonly host: HTMLElement;
+    readonly mainTarget: RenderTarget;
+    readonly overlayTarget: RenderTarget;
+    readonly backgroundTarget: RenderTarget | null;
+    private readonly onAfterRender;
+    /**
+     * Debug: when true the overlay paints every element's mouse hit-zones
+     * (handle slop / edge endpoint / edge body). Toggled by the host
+     * debug panel via `setDebugHitZones`; read by the render orchestrator.
+     * View-only — never persisted or recorded in history.
+     */
+    debugHitZones: boolean;
+    /**
+     * When false the background grid is not painted. Toggled via `toggleGrid`
+     * (`g` hotkey, standard parity). View-only — never persisted or in history.
+     */
+    gridVisible: boolean;
+    readonly actor: Actor<typeof interactionMachine>;
+    private readonly listeners;
+    /**
+     * Typed event surface. Specific events (`mode`, `selection`,
+     * `scene`, `history`, `viewport`) fan out of `notify()` based on
+     * what actually changed since the last fire, so subscribers only
+     * wake up when their slice flips. `change` still fires once per
+     * `notify()` for callers that don't care which slice.
+     *
+     * The `subscribe()` set runs in lockstep with the typed events.
+     */
+    private readonly events;
+    /**
+     * Last-emitted snapshot of every observable slice. Used by
+     * `fanOutEvents` (in `editor/event-fanout.ts`) to decide which
+     * typed events to fire on each `notify()` — only the slices
+     * whose identity changed since the previous notify get an event.
+     */
+    private readonly eventCache;
+    private readonly unbind;
+    _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.
+     */
+    annotationDrag: {
+        id: AnnotationId;
+        originPosition: Vec2;
+        originWorldPoint: Vec2;
+        moved: boolean;
+    } | 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;
+    /**
+     * Currently selected links (connectors). Links are first-class members
+     * of the selection: they coexist with selected elements, join Cmd+A and
+     * marquee, and multi-select via Shift-click. Endpoint drag handles show
+     * only when EXACTLY one link is selected and no elements are (see
+     * `selectedLink`). Empty set = no link selected.
+     */
+    _selectedLinks: LinkSelection.LinkSelection;
+    /**
+     * Currently focused annotation thread — overlay highlights its pin
+     * with an accent ring and hosts (e.g. `<CommentsPopover>`) render
+     * the thread for this id. Independent of shape / edge selection so
+     * users can edit shapes while a comment thread is open.
+     */
+    _selectedAnnotation: AnnotationId | null;
+    /**
+     * Author identity used for comments posted via `addComment` /
+     * `addAnnotation` without an explicit author. Hosts set this once
+     * (typically from the same user object passed to `bindAwareness`).
+     * Defaults to a synthetic local user.
+     */
+    private commentAuthor;
+    /**
+     * 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.
+     */
+    linkEndpointDrag: {
+        linkId: LinkId;
+        side: "from" | "to";
+        toPoint: Vec2;
+    } | null;
+    /**
+     * Host-managed waypoint (bend-point) drag of the selected link. `index`
+     * is the position in `edge.waypoints`. `pendingInsert` means the gesture
+     * 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.
+     */
+    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.
+     */
+    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;
+    /**
+     * Active layer — new shapes created via `addElement` / `applyCreate` land
+     * here when their input doesn't specify a `layerId`. Defaults to the
+     * scene's `DEFAULT_LAYER_ID`; hosts switch via `setActiveLayer`.
+     */
+    _activeLayerId: LayerId;
+    private nextId;
+    /** Generate a short unique id with a stable prefix. */
+    private uniqueId;
+    /**
+     * Snap engine — defaults to grid + anchor + outline contributors.
+     */
+    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;
+    /**
+     * Persistent world-bounds cache shared with `renderScene` for viewport
+     * culling. Object-identity keyed — invalidates automatically whenever
+     * a scene op replaces the shape ref. Could be exposed for hit-test
+     * sharing in a follow-up.
+     */
+    readonly boundsCache: ElementCache<Bounds>;
+    /**
+     * Lazy SpatialGrid for hit-test acceleration in large scenes.
+     * Built on demand when `scene.elements.size >= LARGE_SCENE_HIT_THRESHOLD`
+     * and the cached index's source-scene reference is stale (any scene
+     * op replaces the `_scene` field, invalidating identity).
+     */
+    private spatialIndexCache;
+    /**
+     * The group the user has "entered" via double-click. While set, the
+     * hit-test stops promoting children of this group to the group root,
+     * letting the user directly manipulate inner shapes. Cleared on
+     * 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;
+    /**
+     * 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;
+    /** Host-registered custom cursor images per role (see `setCursorOverride`). */
+    private readonly cursorOverrides;
+    /**
+     * Scene rendered on the last frame. Used to compute a dirty rect by
+     * identity-diffing against the current scene — every shape / edge
+     * whose ref didn't change is also pixel-identical to its last paint
+     * and gets skipped together with the surrounding clear. `null` until
+     * the first render.
+     */
+    lastRenderedScene: Scene | null;
+    /**
+     * Last-painted isolation root — paired with `lastRenderedScene` so
+     * the dirty-rect optimization invalidates when the user enters or
+     * exits a group, even when the scene reference is unchanged. Without
+     * this, drilling into a group never triggers a redraw → the dim
+     * pass would never visibly apply.
+     */
+    lastRenderedEnteredGroup: ElementId | null;
+    /**
+     * 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.
+     */
+    private readonly autoLayoutScheduler;
+    /**
+     * Element id that the user started dragging on press-down. Tracked
+     * separately from the state machine so the editor knows what to
+     * (re)parent / drop into a container on pointerup. `null` between
+     * gestures, set in onDown when press lands on a shape and cleared
+     * in onUp / cancel.
+     */
+    dragElementId: ElementId | null;
+    /**
+     * Element that the current press added to the selection additively
+     * (shift / meta click on an unselected shape). The press promotes it
+     * so a subsequent drag moves it; on a *tap* the up-handler would
+     * otherwise `SELECT_TOGGLE` it straight back off, so it consults this
+     * to skip that redundant toggle. Reset at every press-down.
+     */
+    additivePressAdded: 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;
+    /**
+     * Remote peer cursors / selections, pushed in by the host (typically
+     * a `bindAwareness(editor, awareness)` helper in `@collab`). The
+     * editor only renders them; it doesn't fetch or interpret. Each
+     * setter triggers `render()` so the overlay updates immediately.
+     */
+    _peerCursors: readonly PeerCursor[];
+    _peerSelections: readonly PeerSelection[];
+    /**
+     * Subscribers notified on every host pointer move (world-space). Used
+     * by `@collab` to broadcast the local cursor into awareness.
+     */
+    readonly cursorListeners: Set<(point: Vec2) => void>;
+    /**
+     * Active screen-space pointer positions keyed by `pointerId`. With
+     * one entry the editor's normal single-pointer flow applies. With
+     * two or more entries we enter a pinch / pan gesture and bypass the
+     * interaction machine — `pinchOrigin` holds the baseline.
+     */
+    readonly 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
+     * to select/deselect; once the finger drags past slop, onMove promotes
+     * this to a real pan instead of a marquee lasso (mobile convention).
+     * Screen-space origin point.
+     */
+    touchPanCandidate: Vec2 | null;
+    pinch: PinchController;
+    /** Bridge for `editor/container-ops.ts`. Built lazily in constructor. */
+    private containerOpsRef;
+    /**
+     * Space-bar held → next pointer drag pans the canvas instead of
+     * doing whatever the current mode would do. Visual cursor goes to
+     * "grab" / "grabbing". Wires a window-level keydown/keyup listener
+     * in `bindPointerEvents`.
+     */
+    spaceHeld: boolean;
+    /**
+     * Host-supplied tile compositor — when set (via
+     * `EditorOptions.useTileCache` + `tileCompose`), the per-frame
+     * render path delegates to it instead of `renderScene`. Stays
+     * `null` for the typical small-scene case.
+     */
+    readonly tileComposeFn: TileComposeFn | null;
+    /**
+     * Per-shape change record (before/after world bbox) since the last
+     * tile-cache invalidation pass. Populated by `computeDirtyWorld`'s
+     * diff loop when `tileComposeFn` is on; forwarded to the compositor
+     * each frame so it can invalidate by add / remove / move correctly.
+     * (A plain id set lost adds — new id wasn't in the tile reverse
+     * index yet.)
+     */
+    tileDirtyElements: Map<ElementId, {
+        before: Bounds | null;
+        after: Bounds | null;
+    }>;
+    /**
+     * Tool-lock flag (standard model). When `false` (default), a
+     * draw-mode (`draw-rect` / `draw-ellipse` / `draw-edge` / `brush`)
+     * auto-reverts to `select` after a successful create. When `true`,
+     * the mode persists so the user can draw many shapes in a row
+     * without re-selecting the tool.
+     *
+     * Toggled via `Editor.setToolLocked(bool)` and surfaced in the
+     * toolbar as a lock affordance next to the active tool.
+     */
+    private _toolLocked;
+    /**
+     * Host-extensible file-drop dispatch. Built-ins (image / scene
+     * JSON) register themselves at editor construction; hosts add
+     * more via `registerFileDropHandler`.
+     */
+    private readonly fileDropRegistry;
+    /**
+     * Active pan gesture (right-click drag or Space + left drag).
+     * `pointerId` is captured by the host so move/up events keep
+     * arriving even after the cursor leaves the host bounds.
+     * `startPoint` is the press position — used to decide "click vs
+     * drag" at pointerup (a near-zero displacement right-click is a
+     * context-menu request, not a pan). `lastPoint` tracks the
+     * previous move so per-frame delta is correct.
+     *
+     * `button` records which mouse button started the gesture so we
+     * 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;
+    /**
+     * 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;
+    /**
+     * Long-press tracking. Starts on `pointerdown`; cancelled on
+     * `pointermove > LONG_PRESS_MAX_MOVEMENT_PX` or `pointerup` before
+     * the timer fires. Hosts subscribe via `onLongPress` to surface a
+     * context menu (mobile alternative to right-click).
+     */
+    longPress: LongPressController;
+    private readonly longPressListeners;
+    /**
+     * Live-region announcements for assistive tech. The editor pushes
+     * short, human-readable strings ("Selected Rectangle", "Moved 5 px
+     * right") that hosts pipe into an `aria-live=polite` region.
+     */
+    private readonly announceListeners;
+    /**
+     * Resolved primary input modality + derived hit slops. Computed once
+     * in the constructor from `EditorOptions.inputMode` (default `"auto"`
+     * uses `matchMedia('(pointer: coarse)')`).
+     */
+    private readonly inputMode;
+    private readonly handleHitSlop;
+    private readonly edgeHandleHitSlop;
+    private readonly edgeHitThreshold;
+    /** Link-start anchor-dot grab/click hit radii — touch-enlarged in touch mode. */
+    readonly anchorStartHitSlop: number;
+    readonly anchorClickRadius: number;
+    readonly _history: HistoryProvider;
+    /** Open transaction during a single drag/resize gesture. */
+    gestureTx: TransactionHandle | null;
+    /**
+     * Immutable snapshot of `_scene` taken when a gesture transaction opens.
+     * The history transaction only records patches for undo — cancelling it does
+     * NOT roll back `_scene`. Keeping the pre-gesture scene lets Escape (and any
+     * cancel) restore it, so a drag/move/resize/endpoint-rebind aborted with Esc
+     * leaves the scene exactly as it was. Cleared on commit.
+     */
+    private gestureStartScene;
+    /**
+     * 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
+     * built lazily below.
+     */
+    private readonly gestures;
+    constructor(options: EditorOptions);
+    /** Snapshot used by event-fanout. Kept private — internal API. */
+    private observableSnapshot;
+    get scene(): Scene;
+    get selection(): Selection.Selection;
+    get mode(): Mode;
+    get history(): HistoryProvider;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    /**
+     * The DOM element the editor was mounted onto. Read-only — external
+     * code reads it for screen-↔-world coordinate conversions on events
+     * whose coordinates are in client-space (e.g. global `contextmenu`).
+     */
+    get hostElement(): HTMLElement;
+    /** Subscribe to scene/selection/mode/history changes. */
+    subscribe(fn: () => void): () => void;
+    /**
+     * Subscribe to local world-space pointer movement. Fires on every
+     * `pointermove` over the host. `@collab` uses this to broadcast the
+     * local cursor into the awareness room.
+     */
+    onCursorMove(fn: (point: Vec2) => void): () => void;
+    /** Set the local user's identity for comments authored via this editor. */
+    setCommentAuthor(author: {
+        id: string;
+        name: string;
+    }): void;
+    /** Currently focused annotation id (or null when nothing is open). */
+    get selectedAnnotation(): AnnotationId | null;
+    /**
+     * Open or close an annotation thread. `null` clears the focus. The
+     * overlay highlights the pin; `<CommentsPopover>` reads this and
+     * renders the thread.
+     */
+    setSelectedAnnotation(id: AnnotationId | null): void;
+    addAnnotation(opts: {
+        position: Vec2;
+        elementId?: ElementId | null;
+        firstComment?: string;
+    }): AnnotationId;
+    removeAnnotation(id: AnnotationId): void;
+    toggleAnnotationResolved(id: AnnotationId): void;
+    addComment(annotationId: AnnotationId, body: string, author?: {
+        id: string;
+        name: string;
+    }): void;
+    removeComment(annotationId: AnnotationId, commentId: CommentId): void;
+    hitAnnotation(worldPoint: Vec2): AnnotationId | null;
+    /**
+     * Subscribe to long-press events — a stationary touch / mouse-press
+     * held longer than `LONG_PRESS_DELAY_MS`. The mobile-equivalent of
+     * right-click; hosts open a context menu from this. The event
+     * carries both screen-space (for menu positioning) and world-space
+     * (for target hit-test) coordinates.
+     */
+    onLongPress(fn: (payload: {
+        screenPoint: Vec2;
+        worldPoint: Vec2;
+    }) => void): () => void;
+    /**
+     * Subscribe to accessibility live-region announcements. The host
+     * pipes these strings into an `aria-live="polite"` element so a
+     * screen-reader user hears the editor's status changes. Strings
+     * are short and pre-localised by the caller of `announce`.
+     */
+    onAnnounce(fn: (message: string) => void): () => void;
+    /**
+     * Push a live-region message to all `onAnnounce` listeners. Hosts
+     * (and plugins) call this when something happened that an SR user
+     * should hear: selection changed, shape moved, mode switched, etc.
+     * The editor itself emits a small set of canonical messages from
+     * `focusCycle` / `moveSelectionBy` / `cancelInteraction`.
+     */
+    announce(message: string): void;
+    /**
+     * Replace the remote peer cursors painted by the overlay. Pass an
+     * empty array to clear. The host is expected to filter out the
+     * local user's cursor before calling.
+     */
+    setPeerCursors(cursors: readonly PeerCursor[]): void;
+    /**
+     * Replace the remote peer selections painted by the overlay. The
+     * host resolves a peer's `selection: ElementId[]` into world bounds
+     * before passing them in.
+     */
+    setPeerSelections(selections: readonly PeerSelection[]): void;
+    /**
+     * Toggle the debug hit-zone overlay (host debug panel). When on, the
+     * overlay paints every element's mouse hit-targets so the tuned slop
+     * 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. */
+    setGridVisible(on: boolean): void;
+    /** Toggle background grid visibility. */
+    toggleGrid(): void;
+    /** Whether the active draw-mode sticks after a create (toolbar lock). */
+    get toolLocked(): boolean;
+    /** All currently-selected link (connector) ids. */
+    get selectedLinks(): LinkSelection.LinkSelection;
+    /**
+     * The sole selected link — non-null ONLY when exactly one link and no
+     * elements are selected. Drives endpoint handles, the edge-style panel,
+     * caption edit and `updateSelectedLink`; a multi/mixed selection yields
+     * null so those single-link affordances stay hidden.
+     */
+    get selectedLink(): LinkId | null;
+    /**
+     * Apply an in-place mutation to the currently-selected edge as a
+     * single history step. The `updater` receives a clone of the edge
+     * and returns the next version (callers should produce a new
+     * object — Link is readonly). No-op when no edge is selected.
+     */
+    updateSelectedLink(updater: (edge: Link) => Link): void;
+    /**
+     * Register a file-drop handler. Handlers are tried in registration
+     * order; the first whose `accept(file)` returns true takes the
+     * file. Repeated calls with the same `id` replace the previous
+     * handler (idempotent for module-load wiring).
+     */
+    registerFileDropHandler(handler: FileDropHandler): void;
+    /** Drop a registered handler. */
+    unregisterFileDropHandler(id: string): void;
+    /**
+     * Dispatch a dropped file (or pasted file from clipboard) into
+     * the registered handlers. Returns `true` when a handler accepted
+     * the file, `false` otherwise — UI can show an "unsupported file"
+     * toast on `false`. `worldPoint` is where the file should land
+     * (drop-point projected to world coords; for paste, host can use
+     * cursor world point or viewport centre).
+     */
+    dispatchFileDrop(file: File, worldPoint: Vec2): Promise<boolean>;
+    /**
+     * Toggle the tool-lock affordance. With `true`, draw-modes persist
+     * after each successful shape create — the user keeps drawing
+     * rectangles without re-pressing R. With `false` (default), the
+     * editor reverts to `select` after each create.
+     */
+    setToolLocked(locked: boolean): void;
+    private maybeRevertModeAfterCreate;
+    setMode(mode: Mode): void;
+    /** Undo the latest record. No-op if there is nothing to undo. */
+    undo(): boolean;
+    /** Redo the undone record. */
+    redo(): boolean;
+    /**
+     * Add a shape to the scene and push a single record onto the history stack.
+     * Returns the resulting patch (useful for tests). Intended for code paths
+     * that create shapes outside of a pointer gesture — drag-from-palette,
+     * paste, programmatic insert.
+     */
+    addElement(shape: Element, options?: {
+        select?: boolean;
+    }): Patch;
+    /**
+     * Insert an image at the given world position. Wraps `addElement`
+     * with the image-shape boilerplate (id, layer, order, scale=1,
+     * rotation=0). Returns the new shape's id so callers can chain
+     * (e.g. immediately reparent into a container).
+     *
+     * `src` is anything the renderer accepts — a data-URL from the
+     * file-drop handler, a host CDN URL, an SVG string in
+     * `image/svg+xml;base64,...` form.
+     */
+    insertImage(input: {
+        src: string;
+        width: number;
+        height: number;
+        position: Vec2;
+        image?: HTMLImageElement;
+        animated?: boolean;
+        fileId?: FileId;
+        animationKind?: string;
+        animationData?: unknown;
+    }): ElementId;
+    addBinaryFile(blob: Blob, name?: string): Promise<FileId>;
+    /**
+     * Animation tick — runs while any shape carries
+     * `metadata.animated` (GIFs today; future video / lottie).
+     * Forces a full re-render every frame so drawImage picks up the
+     * 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.
+     */
+    private hasVisibleAnimatedElement;
+    /**
+     * Re-arm the animation tick after a change that may have brought an
+     * animated shape into (or out of) view — pan / zoom / scene edit.
+     * `AnimationTick.start()` no-ops when already running or when
+     * `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;
+    /**
+     * Toggle GIF playback for a shape — wired to a click on an animated
+     * image (resume after auto-stop, play after reduced-motion). Resuming
+     * continues from the frozen frame.
+     */
+    togglePlayback(id: ElementId): void;
+    /**
+     * Hover entered an animated shape: resume it if paused and hold off
+     * its auto-stop timer while the pointer stays over it (the auto-stop
+     * pass keeps pushing `playStartMs` forward for the hovered shape).
+     * Pass `null` when the pointer leaves all shapes.
+     */
+    hoverAnimatedElement(id: ElementId | null): void;
+    /** True when the shape's GIF is paused (drives the overlay badge). */
+    isPlaybackPaused(id: ElementId): boolean;
+    /**
+     * Record the idle cursor position so the overlay can grow the SINGLE
+     * selected element's link-start dot nearest the cursor. Only the selected
+     * element shows start dots (connecting from an unselected element on hover
+     * was a cancelled product decision). Pass `null` to clear.
+     */
+    setHoverCursorWorld(cursor: Vec2 | null): void;
+    /** Live link-draw preview polyline (elbow), or null when not drawing. */
+    get linkPreviewPath(): readonly Vec2[] | null;
+    /** Current connector attach target + mode (point=fixed / element=floating). */
+    get linkAttachTarget(): {
+        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,
+     * but defers the history entry until `commit()` is called. `update`
+     * re-positions without writing per-move patches; `cancel` removes
+     * the shape entirely and leaves history untouched (no undo entry).
+     *
+     * Typical wiring: HTML5 dragenter starts the placement, dragover
+     * updates, drop commits, dragleave / window keydown(Escape) cancel.
+     */
+    beginPlacement(shape: Element): {
+        update: (worldCenter: Vec2) => void;
+        commit: () => void;
+        cancel: () => void;
+    };
+    deleteSelected(): void;
+    /**
+     * Currently edited text shape (or null). Set by `beginTextEdit`;
+     * cleared by `commitTextEdit` / `cancelTextEdit`. The host overlay
+     * (`<TextEditorOverlay>` in `@react-ui`) subscribes via `editor`
+     * and renders a `<textarea>` positioned over the shape.
+     */
+    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
+     * the header), or null. The host overlay (`<FrameNameEditorOverlay>` in
+     * `@react-ui`) renders an input over the header and commits the name.
+     */
+    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;
+        dir: "forward" | "backward";
+    } | null;
+    /** Caret offset = the moving end of the selection. */
+    get editingTextCaret(): number | null;
+    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
+     * (only one shape at a time). Caret defaults to the end of the text.
+     */
+    /** Open inline caption editing for a link (double-click). */
+    beginLinkCaptionEdit(id: LinkId): void;
+    /**
+     * Commit the link caption. Empty / whitespace text removes the label;
+     * otherwise the label text is set, preserving any existing position /
+     * styling. One undo step. Clears caption-edit mode.
+     */
+    commitLinkCaptionEdit(text: string): void;
+    /** Cancel link caption editing without changing the label. */
+    cancelLinkCaptionEdit(): void;
+    /** World-space anchor point for a link's caption (midpoint of its path). */
+    linkLabelWorld(id: LinkId): Vec2 | null;
+    beginTextEdit(id: ElementId): void;
+    /**
+     * Start editing a frame's header name. No-op unless `id` is a frame on
+     * an unlocked layer. Commits any in-flight text edit first.
+     */
+    beginFrameNameEdit(id: ElementId): void;
+    /**
+     * Commit the edited frame name. Empty / whitespace-only clears the
+     * stored name (the renderer falls back to "Frame"). One history step;
+     * no-op when the name is unchanged. Always clears the editing state.
+     */
+    commitFrameNameEdit(name: string): void;
+    /** Abandon the frame-name edit without changing the name. */
+    cancelFrameNameEdit(): void;
+    /**
+     * Frame whose header strip (the label bar ABOVE the body) contains the
+     * world point — top-most by z-order. Used to route a double-click on the
+     * header to a name edit, since the header sits outside the frame's
+     * hit-test bounds. Assumes unrotated frames (the common case).
+     */
+    private frameHeaderAt;
+    /**
+     * Live edit transport from the hidden `<textarea>`: replace the
+     * shape's text + selection as the user types / pastes / composes.
+     * Mutates the scene WITHOUT a history entry — history is recorded
+     * once on commit. No-op when not editing.
+     */
+    setEditingText(value: string, selStart: number, selEnd: number, dir?: "forward" | "backward"): void;
+    /** Selection-only update (arrows / shift-select / click) — no text change. */
+    setEditingSelection(selStart: number, selEnd: number, dir?: "forward" | "backward"): void;
+    /**
+     * Map a world-space point to a caret offset in the edited text. Used
+     * to place / extend the caret from canvas clicks. Returns `null` when
+     * not editing or the shape is gone.
+     */
+    caretIndexAtWorldPoint(worldPoint: Vec2): number | null;
+    /**
+     * `true` when a point is inside the currently-edited text shape's
+     * world bounds. Used by the pointer binding to decide between
+     * repositioning the caret (inside) and committing (outside).
+     */
+    editedElementContainsPoint(worldPoint: Vec2): boolean;
+    /** Place a collapsed caret at the clicked point and start a drag-select. */
+    setTextCaretFromPoint(worldPoint: Vec2): void;
+    /** Extend the selection from the drag anchor to the current point. */
+    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
+     * off so the overlay can simply skip drawing it.
+     */
+    editingTextOverlay(): {
+        caret: {
+            x: number;
+            y: number;
+            height: number;
+        } | null;
+        caretColor: string;
+        selectionRects: readonly Bounds[];
+    } | null;
+    commitTextEdit(next?: string): void;
+    cancelTextEdit(): void;
+    /**
+     * Translate every selected shape by the given world-space delta.
+     * Single undo step. No-op when selection is empty. Used by arrow-key
+     * keyboard navigation; hosts pass `{ x: 1, y: 0 }` for fine nudge
+     * and `{ x: 10, y: 0 }` for shift-arrow.
+     */
+    moveSelectionBy(delta: Vec2): void;
+    /**
+     * Keyboard-friendly creation flow. Picks the shape type from the
+     * current `mode` ("draw-rect" / "draw-ellipse" / fallback to
+     * rectangle) and inserts a sensible default-sized shape at the
+     * viewport center. Returns the new shape's id, or `null` when the
+     * scene has no active layer.
+     *
+     * Hosts can bind this to "Enter" while in a draw mode, providing a
+     * mouse-free alternative to drag-out creation.
+     */
+    createElementAtCursor(): ElementId | null;
+    /**
+     * `draw-text` tool: drop an empty text shape at `worldPoint`, select
+     * it and open its inline editor immediately. The add is a single undo
+     * step; the subsequent text typed in is committed (or the empty shape
+     * removed) by `commitTextEdit`. Reverts to `select` afterwards unless
+     * the tool is locked.
+     */
+    createTextAt(worldPoint: Vec2): ElementId;
+    beginBrushStroke(world: Vec2, pressure?: number): void;
+    extendBrushStroke(world: Vec2, pressure?: number): void;
+    commitBrushStroke(): ElementId | null;
+    cancelBrushStroke(): void;
+    /** Current in-progress brush stroke, exposed for the overlay preview. */
+    get pendingBrushStroke(): {
+        readonly origin: Vec2;
+        readonly points: readonly BrushPoint[];
+    } | null;
+    arrangeAsGrid(opts?: {
+        cols?: number;
+        gap?: number;
+    }): void;
+    arrangeAsStack(opts?: {
+        direction?: "horizontal" | "vertical";
+        gap?: number;
+    }): void;
+    groupSelected(): GroupSelectedResult;
+    ungroup(): void;
+    private selectionRoots;
+    expandSelectionWithDescendants(): ReadonlySet<ElementId>;
+    focusCycle(direction: "next" | "prev"): void;
+    /**
+     * Clear selection + cancel any in-progress drag / draw gesture.
+     * Bound to Escape in default keyboard nav.
+     */
+    cancelInteraction(): void;
+    /**
+     * Duplicate the selected shapes 10 px down-right of the originals.
+     * Links between selected shapes are NOT cloned. Single undo step.
+     */
+    duplicateSelected(): void;
+    /**
+     * Clone the selection IN PLACE (zero offset), select the clones, and return
+     * the clone of `anchorId` (or null). Unlike `duplicateSelected` this also
+     * clones group descendants and frame members, remapping `parentId`/`frameId`
+     * among the clones so a duplicated frame keeps its contents. Used by
+     * `⌥`-drag duplicate — the caller then drags the clones, leaving the
+     * originals. One undo step.
+     */
+    duplicateSelectedInPlace(anchorId?: ElementId | null): ElementId | null;
+    setSelection(ids: Iterable<ElementId>): void;
+    selectAll(): void;
+    /**
+     * Internal clipboard. Stored as deep-cloned snapshots so subsequent
+     * mutations don't affect the buffer. Survives across editor calls
+     * within the same session; cross-tab paste uses host-level
+     * `navigator.clipboard` (out of scope for the editor).
+     */
+    private clipboard;
+    copySelected(): void;
+    cutSelected(): void;
+    /**
+     * Paste clipboard contents into the scene. The cluster lands so that
+     * its centroid sits at `targetWorld` (defaults to the last tracked
+     * cursor position; when even that is unavailable, falls back to a
+     * +10 px nudge so duplicates stay visible). Relative offsets
+     * between clipboard items are preserved.
+     *
+     * New shapes get fresh ids and end up selected. Single undo step.
+     */
+    paste(targetWorld?: Vec2): void;
+    /**
+     * Merge `partial` into the `style` of every shape in `ids`. Useful
+     * for the inspector / PropertyPanel: flipping `roundness`, swapping
+     * `lineJoin`, changing `stroke` colour across a multi-selection,
+     * etc. All changes go through one history record (single undo).
+     *
+     * No-op when `ids` is empty or none of the targeted shapes exist.
+     */
+    updateStyle(ids: Iterable<ElementId>, partial: Partial<TextStyle>): void;
+    /**
+     * Update non-style text properties (`fontSize`, `fontFamily`,
+     * `maxWidth`) on every selected text shape. Non-text shapes are
+     * skipped. Single undo step. Used by the text contextual panel.
+     */
+    updateTextProps(ids: Iterable<ElementId>, partial: {
+        fontSize?: number;
+        fontFamily?: string;
+        maxWidth?: number;
+    }): 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
+     * is normalised here (`normalizeHref`: adds `https://`, `mailto:`,
+     * rejects `javascript:`/`data:`); a string that normalises to nothing
+     * clears the link. The host opens it on Cmd/Ctrl-click or the
+     * hover link-popup.
+     */
+    setLink(ids: Iterable<ElementId>, href: string | null): void;
+    /**
+     * Open an element hyperlink in a new tab. Re-validates the scheme
+     * (`safeHref`) before navigating — only `http`/`https`/`mailto`, never
+     * `javascript:` / `data:` — and uses `noopener,noreferrer`. No-op for
+     * an unsafe / empty href or outside a browser.
+     */
+    openLink(href: string | undefined | null): void;
+    /** The element-level href of a shape, if safe to open; else `null`. */
+    elementLink(id: ElementId): string | null;
+    /**
+     * Topmost interactable shape at `worldPoint` that carries a safe link,
+     * with its world bounds — for the hover link-popup. `null` when none.
+     */
+    linkAt(worldPoint: Vec2): {
+        id: ElementId;
+        href: string;
+        bounds: Bounds;
+    } | null;
+    bringToFront(id?: ElementId): void;
+    sendToBack(id?: ElementId): void;
+    /** Move the target shape one step toward the top of its layer. */
+    bringForward(id?: ElementId): void;
+    /** Move the target shape one step toward the bottom of its layer. */
+    sendBackward(id?: ElementId): void;
+    compactLayerZOrder(layerId?: LayerId, options?: {
+        recordHistory?: boolean;
+    }): void;
+    /**
+     * Wipe every shape + edge from the scene. Layers and viewport survive.
+     * Clears history — restoring an empty scene through undo would be
+     * surprising and the operation is rarely chained with other edits.
+     */
+    clear(): void;
+    /** Currently active layer — new shapes default into it. */
+    get activeLayerId(): LayerId;
+    /** Switch the active layer. Hosts call this from a layer panel click. */
+    setActiveLayer(id: LayerId): void;
+    createLayer(name: string): LayerId;
+    removeLayer(id: LayerId): void;
+    renameLayer(id: LayerId, name: string): void;
+    toggleLayerVisibility(id: LayerId): void;
+    toggleLayerLock(id: LayerId): void;
+    moveSelectionToLayer(targetLayer: LayerId): void;
+    /**
+     * Pan the camera by a screen-space delta. Drives both wheel-pan and
+     * the two-finger pan gesture; deltas are in screen pixels (positive
+     * x → shapes move right relative to the user). Not recorded in
+     * history — viewport state is editor-local.
+     */
+    panBy(deltaScreen: Vec2): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    private zoomStep;
+    resetZoom(): void;
+    zoomToFit(padding?: number): void;
+    /** Fit the camera to the current selection (standard `⌥2`). No-op when empty. */
+    zoomToSelection(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
+     * selected). standard `⌘`+arrows. Candidates must lie within a 45° cone of the
+     * direction; the closest by along+lateral distance wins. No-op when nothing
+     * qualifies.
+     */
+    selectClosest(direction: "left" | "right" | "up" | "down"): void;
+    zoomAt(factor: number, anchorWorld: Vec2): void;
+    setViewportSize(width: number, height: number): void;
+    setGrid(patch: {
+        size?: number;
+        style?: GridStyle;
+        snap?: boolean;
+    }): void;
+    /** Whether snap-to-grid is currently enabled (default on). */
+    get snapToGridEnabled(): boolean;
+    /** Toggle snap-to-grid on/off. Persists in the viewport. */
+    setSnapToGrid(enabled: boolean): void;
+    /**
+     * Host hook: while held, the next move/resize/create gesture ignores
+     * snap-to-grid (Cmd/Ctrl modifier). The app wires keydown/keyup
+     * of the modifier to this. Idempotent; never touches history.
+     */
+    setSnapSuppressed(suppressed: boolean): void;
+    /**
+     * True when a gesture should snap: feature on, grid visible, AND the
+     * suppress modifier not held. Hiding the grid (`toggleGrid` / `g`) also
+     * disables snap-to-grid — snapping to an invisible grid is confusing.
+     * Re-showing the grid restores the stored snap preference.
+     */
+    private snapActive;
+    /** World-unit spacing the current gesture snaps to. */
+    private snapSpacing;
+    /**
+     * Replace the entire scene (e.g. after `parseScene`). Clears history,
+     * selection and any open gesture. Use to load a saved document.
+     */
+    loadScene(scene: Scene, options?: LoadSceneOptions): void;
+    /** Detach all DOM listeners and stop the actor. */
+    dispose(): void;
+    private bindPointerEvents;
+    /**
+     * Open a pan gesture: capture the pointer so subsequent move / up
+     * events arrive even outside the host bounds, cancel anything the
+     * machine might have started this tick, and switch the cursor.
+     */
+    beginPanGesture(pointerId: number, button: number, point: Vec2): void;
+    /**
+     * End an in-progress pan gesture. Restores the cursor unless Space
+     * is still held (then we drop back to "grab" so the user knows
+     * another drag is armed). For right-click that didn't move past
+     * the slop threshold, fires the long-press callback so the context
+     * menu opens at the click position — that's the "right-click =
+     * menu, right-drag = pan" decision rule.
+     */
+    endPanGesture(): void;
+    isDrawingPhase(ctx: InteractionContext): boolean;
+    startLongPress(screenPoint: Vec2): void;
+    cancelLongPress(): void;
+    beginPinch(): void;
+    applyPinch(): void;
+    /**
+     * Convert a point in the host element's CSS-pixel coordinate space into
+     * world coordinates. Public so drop handlers (drag-from-palette, paste)
+     * can map pointer positions back to scene space.
+     */
+    screenToWorld(point: Vec2): Vec2;
+    /**
+     * Attach target under `worldPoint` for an endpoint-rebind drop: the topmost
+     * interactable ELEMENT (group-promoted), ignoring link bodies and the dragged
+     * link's own endpoint handle. Used instead of {@link hitTest} when finishing
+     * an endpoint drag — `hitTest` would return the (now live, cursor-tracking)
+     * endpoint handle and shadow the element beneath it, blocking re-binding.
+     * `undefined` → dropped on empty space (the end stays a free point).
+     */
+    linkAttachTargetAt(worldPoint: Vec2): PressTarget | undefined;
+    hitTest(worldPoint: Vec2): PressTarget;
+    /**
+     * Recompute the canvas cursor from the current interaction state and apply
+     * it to the host element. Single chokepoint — called from pointer-move
+     * (hover), gesture begin/end, and mode changes so the cursor never drifts
+     * 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
+     * `CursorSpec` object for a DPR-aware image (`image-set(1x, 2x)`) with a
+     * hotspot + keyword fallback, or a raw CSS cursor string. Host-only view
+     * state — not persisted.
+     */
+    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.
+     */
+    private isOverLinkStartDot;
+    /** True when the given layer exists and is marked `locked`. */
+    private isLayerLocked;
+    /**
+     * Combined interactivity check: false when the shape's layer is
+     * locked, or when the shape itself or any ancestor via `parentId`
+     * carries `locked: true` (group lock propagation). Hit-test treats
+     * non-interactable hits as misses; render still draws them so the
+     * user can see what's locked.
+     */
+    private isElementInteractable;
+    /**
+     * Can this shape be moved / resized? False when the shape (or an ancestor)
+     * is `locked`, its layer is locked, or it's hidden. Distinct from
+     * `isElementInteractable`, which still allows selecting a locked shape so it
+     * can be unlocked.
+     */
+    isElementManipulable(shape: Element): boolean;
+    /**
+     * Toggle the `locked` flag on the selection (standard `⌘⇧L`). If any selected
+     * element is currently unlocked, lock all; otherwise unlock all. One undo
+     * step. A locked element stays selectable (click → select → unlock) but
+     * can't be moved or resized.
+     */
+    toggleLockSelection(): void;
+    /**
+     * Promote a hit shape to the topmost ancestor whose group we have NOT
+     * "entered" yet. Only **`group`**-typed parents promote — containers
+     * (swim-lane, frame) intentionally let click hits land on their
+     * children. Group is an abstract wrapper that has no visual identity,
+     * so promoting up to it is the only way to select it; a container has
+     * its own body, header, etc. and clicking inside it should let users
+     * pick the actual child shape (rectangle, sticky, …) — same affordance
+     * as standard.
+     *
+     * Stops at the first non-`group` parent. With `_enteredGroup` set,
+     * the walk also stops just below that group so children can be edited
+     * directly.
+     */
+    private promoteToGroupRoot;
+    /**
+     * 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`.
+     */
+    private topGroupAncestor;
+    /**
+     * True when `elementId`'s parent chain contains `groupId`. Used by the
+     * isolation exit path: a click on a shape whose parent chain *does
+     * not* lead through the entered group is a click "outside" the
+     * group, which exits isolation.
+     */
+    private isDescendantOfGroup;
+    /**
+     * Compute the dim set for isolation rendering: every shape whose
+     * parent chain does NOT pass through `enteredGroupId`. The entered
+     * group itself is treated as "inside" (returns true from
+     * isDescendantOfGroup) so it stays at full alpha — but groups have
+     * no intrinsic geometry, so this only matters for the
+     * group-bounds-outline overlay path, not the shape render.
+     *
+     * Defensive: shapes in the current selection are never dimmed. The
+     * focus shape (drilled-into child) is always a group descendant in
+     * practice, but the guard keeps the contract simple — "what you've
+     * selected, you can see".
+     */
+    computeHiddenElements(): ReadonlySet<ElementId> | undefined;
+    computeDimElements(enteredGroupId: ElementId): ReadonlySet<ElementId>;
+    /**
+     * Enter a group — subsequent hits inside this group return children
+     * directly instead of the group root. `null` exits group-edit mode.
+     * Bound to double-click on a group in the default handler.
+     */
+    enterGroup(groupId: ElementId | null): void;
+    /**
+     * Enter the single selected container — select its contents (standard `⌘⇧↓`).
+     * Members are children via `parentId` (group / template container) or via
+     * `frameId` (frame). For a group we also set `enteredGroup` so subsequent
+     * clicks land on children. No-op unless exactly one container with members
+     * is selected.
+     */
+    enterContainer(): void;
+    /**
+     * Exit to the container of the current selection — select the parent group /
+     * template container (`parentId`) or frame (`frameId`) when every selected
+     * element shares one (standard `⌘⇧↑`). Clears `enteredGroup`. No-op when there
+     * is no single common container.
+     */
+    exitContainer(): void;
+    /** Currently "entered" group, if any. */
+    get enteredGroup(): ElementId | null;
+    /**
+     * SpatialGrid-accelerated topmost-shape lookup. Linear scan for small
+     * scenes; for larger scenes builds a grid lazily, keyed by current
+     * scene-identity. Scene operations replace `_scene` (immutable patches),
+     * so reference-equality is a sufficient invalidation signal.
+     */
+    acceleratedElementAt(worldPoint: Vec2): Element | undefined;
+    /**
+     * Build (or return the cached) `SpatialGrid` for the current scene.
+     * Re-built only when `_scene` reference changes — scene operations
+     * always produce a fresh object, so reference equality is a
+     * sufficient invalidation signal.
+     *
+     * Shared between the hit-test path (`acceleratedElementAt`) and the
+     * renderer pass (passed to `renderScene` as `spatialIndex`), so
+     * the grid build cost is amortised across both consumers.
+     */
+    ensureSpatialIndex(): SpatialGrid;
+    /**
+     * Group-isolation click routing. Returns `true` if the click was
+     * handled (caller should skip the default applyEmit), `false` if the
+     * normal selection emit should still run.
+     *
+     * Three paths fire here:
+     *   1. **Double-click on a grouped shape (not yet in isolation):**
+     *      enter that group; select the raw inner shape (bypassing the
+     *      group-root promotion that ran in hitTest).
+     *   2. **Inside isolation, click on a non-descendant shape OR empty
+     *      space:** exit isolation. Let the normal click then run so the
+     *      newly clicked element / empty selection takes hold.
+     *   3. **Inside isolation, double-click on the entered group's own
+     *      child group:** drill another level deeper. (Implicit: same as
+     *      case 1 but topGroupAncestor here returns the inner child
+     *      group because the outer group is already entered.)
+     *
+     * Side-effect: updates `lastClickAt` / `lastClickWorldPoint`
+     * regardless of result, so subsequent calls can detect a double-
+     * click against this event.
+     */
+    routeIsolationClick(clickEffect: InteractionEmit | null, worldPoint: Vec2): boolean;
+    /**
+     * Given the raw shape under the cursor and its topmost group
+     * ancestor, pick which group to "enter" on a drill-down.
+     *
+     * - No group ancestor → null (drill-down doesn't apply).
+     * - Top group not yet entered → enter top.
+     * - Top group already entered → walk down the chain to find the
+     *   next group inward (one level deeper).
+     */
+    private pickDrillTarget;
+    applyEmit(emit: InteractionEmit): void;
+    /**
+     * Drag handler for annotation pins. Moves the pin to
+     * `origin + delta`. Anchor semantics: for shape-anchored
+     * annotations the `position` field is shape-local, so dragging
+     * still updates the same field — the editor doesn't try to
+     * reparent the anchor mid-drag; user wants the pin under the
+     * cursor and that's exactly what `position + (delta in world)`
+     * gives, regardless of which space the position is interpreted
+     * in (`getAnnotationWorldPosition` already adds the shape's
+     * world position when anchored).
+     *
+     * Wrapped in a single gestureTx so per-move updates collapse
+     * into one undo step.
+     */
+    private applyAnnotationMove;
+    private readonly templateTapListeners;
+    private readonly templateDropListeners;
+    /**
+     * Subscribe to template button taps. Returns an unsubscribe function.
+     * Hosts use this to route template button clicks to their own actions.
+     */
+    onTemplateTap(fn: (emit: Extract<InteractionEmit, {
+        type: "TEMPLATE_TAP";
+    }>) => void): () => void;
+    /**
+     * Subscribe to drops onto template drop-zones. Returns an unsubscribe fn.
+     * Hosts decide what to do with the drop (e.g. add a child shape, link
+     * templates together).
+     */
+    onTemplateDrop(fn: (emit: Extract<InteractionEmit, {
+        type: "TEMPLATE_DROP";
+    }>) => void): () => void;
+    /**
+     * Dispatch a TEMPLATE_DROP emit programmatically. Hosts call this from their
+     * own DOM `drop` listener after looking up which drop-zone (if any) is
+     * under the pointer via `findDropZoneAt`.
+     */
+    dispatchTemplateDrop(emit: Extract<InteractionEmit, {
+        type: "TEMPLATE_DROP";
+    }>): void;
+    private applyMove;
+    private applyGroupMove;
+    computeViewportWorld(): Bounds | null;
+    /**
+     * Identity-diff the current scene against the last rendered one and
+     * return the union AABB of every shape/edge that changed reference
+     * (added, removed, or replaced). Returns `null` to force a full
+     * clear when something that affects the entire surface changes —
+     * viewport pan/zoom/resize, layer visibility, or the first frame.
+     *
+     * Empty union (returned as a zero-area bbox far off-screen) means
+     * nothing changed; renderScene will cull every shape via its
+     * `dirtyWorld` filter — effectively a no-op main pass.
+     */
+    computeDirtyWorld(): Bounds | null;
+    combinedSelectionBounds(): Bounds | null;
+    private groupChildrenUnion;
+    /**
+     * True when the current selection should be treated as aspect-
+     * locked for group-handle resize. Currently: a single `group`-typed
+     * shape selected. Multi-selection of free shapes keeps the default
+     * 8-handle / free-aspect behaviour (matches user expectation:
+     * grouping is the explicit "lock the ratio" gesture).
+     */
+    selectionIsAspectLocked(): boolean;
+    private applyGroupResize;
+    private applyResize;
+    private applyCreate;
+    /** Generate the next "Frame N" name based on existing frames. */
+    private nextFrameName;
+    /**
+     * Assign frameId to every shape (except the frame itself) whose
+     * centre falls inside the frame's world bounds. Runs as a single
+     * undo step in the same gesture transaction as the create.
+     */
+    private assignFrameMembers;
+    /**
+     * Re-evaluate frame membership at the end of a move / resize gesture —
+     * elements dropped inside a frame join it, those dragged out are
+     * released (standard "membership on drop"). Runs inside the gesture
+     * transaction (called from pointer-up before `commitGesture`) so the
+     * frameId changes undo together with the drag. No-op when nothing
+     * changed.
+     */
+    reconcileFrameMembership(): void;
+    private applyCreateLink;
+    /** Pending shape-picker after a link was dropped on empty canvas. */
+    get linkDropMenu(): {
+        linkId: LinkId;
+        side: "from" | "to";
+        world: Vec2;
+    } | null;
+    /**
+     * Resolve a pending link-drop shape-picker by creating an element from
+     * `factory` centred at the drop point and re-pointing the dropped link
+     * end to float against it. Element + re-point land in one undo step; the
+     * new element becomes the selection. No-op when no menu is pending.
+     */
+    placeShapeAtLinkDrop(factory: (ctx: {
+        id: ElementId;
+        layerId: LayerId;
+        position: Vec2;
+        order: FractionalIndex;
+    }) => Element): void;
+    /** Dismiss the link-drop shape-picker, leaving the free-ended link. */
+    dismissLinkDropMenu(): void;
+    /**
+     * standard "click a link-start dot" gesture: spawn a new element in that
+     * dot's outward direction and link the source to it. The clone copies
+     * the source's type / style / size but NOT its text (a fresh blank of
+     * the same kind). Direction is source → new; the new element becomes the
+     * selection. Element + link land in one undo step.
+     */
+    createLinkedElementFromAnchor(fromElement: ElementId, anchorName: string): void;
+    /**
+     * Ghost geometry for what clicking a start dot would create (standard hover
+     * preview): the would-be new element's world bounds + the connector path
+     * from the dot to it. Pure — no mutation. Mirrors the placement in
+     * `createLinkedElementFromAnchor`.
+     */
+    previewClickCreate(fromElement: ElementId, anchorName: string): {
+        bounds: Bounds;
+        path: readonly Vec2[];
+        element: Element;
+        ghostScene: Scene;
+        ghostLinkId: LinkId;
+    } | null;
+    /**
+     * Build an `LinkEndpoint` for a draw-edge / re-bind gesture. Runs the
+     * scene's snap engine for the probe point, prefers anchor snap when
+     * close enough, falls back to outline snap (so the user can attach
+     * "anywhere on the right edge"), then `point` for the free-floating
+     * case.
+     *
+     * `pressTargetElement` is the shape the gesture originated from or
+     * landed on (used as a strong hint — we don't snap onto unrelated
+     * shapes when the user clearly aimed for this one).
+     */
+    private snapLinkEndpoint;
+    private applySelectByBounds;
+    private applyLassoLiveSelection;
+    /**
+     * Live endpoint-rebind move: re-point the dragged end to the cursor in the
+     * scene (a free `point` endpoint), recorded in the gesture transaction so the
+     * WHOLE link redraws under the cursor with full fidelity — real style,
+     * arrowhead, curved bow, and (via `rerouteElbows` in `render`) a live elbow
+     * re-route. One undo step on commit; Escape cancels the transaction and the
+     * link snaps back to where it was. The handle dot follows via `linkEndpointDrag`.
+     */
+    private applyLinkEndpointMove;
+    private applyLinkEndpointUpdate;
+    /** True while a waypoint of the selected link is being dragged. */
+    get isDraggingWaypoint(): boolean;
+    /**
+     * Begin a host-managed waypoint drag. `insert` splices a new waypoint at
+     * `index` on the first move (segment-midpoint "add" handle); otherwise an
+     * existing waypoint at `index` is moved. Live-mutated through the gesture
+     * transaction so the whole drag is one undo step.
+     */
+    beginWaypointDrag(linkId: LinkId, index: number, insert: boolean): void;
+    /** Live update of the dragged waypoint to `world`. */
+    updateWaypointDrag(world: Vec2): void;
+    /**
+     * Finish the waypoint drag. If the dragged waypoint landed within
+     * `WAYPOINT_COLLAPSE_RADIUS` of an adjacent path point, it is removed
+     * (drag-onto-the-line to delete). A no-move insert adds nothing.
+     */
+    endWaypointDrag(): void;
+    /** True while an elbow segment is being dragged. */
+    get isDraggingSegment(): boolean;
+    /**
+     * Begin a host-managed elbow segment drag. `axis` is the segment's
+     * orientation; `at` is its centre along its own axis (used to re-identify it
+     * across re-routes).
+     */
+    beginSegmentDrag(linkId: LinkId, axis: "h" | "v", at: number): void;
+    /**
+     * Move the dragged elbow segment perpendicular to its axis: pin its
+     * perpendicular coordinate to the cursor. The reroute pass re-flows the
+     * rest around the pin (one undo step via the gesture transaction).
+     */
+    updateSegmentDrag(world: Vec2): void;
+    /** Finish the elbow segment drag (commit the gesture as one undo step). */
+    endSegmentDrag(): void;
+    /**
+     * Double-click detector for link edit handles (waypoint / segment).
+     * Returns true when this press follows the previous handle press within
+     * the double-click window + tolerance. Updates state every call. Kept
+     * separate from the up-side double-click path (handles return early in
+     * `onDown`, so that path never sees them).
+     */
+    isHandleDoubleClick(world: Vec2): boolean;
+    /**
+     * Delete a free bend point (waypoint) from a straight / bezier link by
+     * index — double-click a waypoint handle to remove it. One undo step.
+     */
+    deleteWaypoint(linkId: LinkId, index: number): void;
+    /**
+     * Remove the pinned (fixed) elbow segment that matches the given
+     * geometry — double-click a segment handle to return it to the auto
+     * route. Matches by axis + nearest pinned perpendicular `pos` (exact for
+     * a pinned segment), `at` as tiebreak. The reroute pass re-flows on the
+     * next render (fixedSegments is part of the elbow signature). One undo
+     * step.
+     */
+    resetSegmentPin(linkId: LinkId, axis: "h" | "v", pos: number, at: number): void;
+    /** Whether the selected link has obstacle-avoidance routing enabled. */
+    get selectedLinkAvoidsObstacles(): boolean;
+    /**
+     * Toggle persistent "route around shapes" on the selected link (standard
+     * model). Enabling sets `avoidObstacles` and forces `orthogonal` routing —
+     * the elbow router then keeps the path clear of EVERY scene shape and
+     * re-routes whenever an obstacle moves into the way (see
+     * `routeElbowLink` / `elbowSignature`). Disabling drops the flag; the
+     * routing type is left as-is. One undo step; the routed path itself is
+     * derived (recomputed by `rerouteElbows`). No-op when no link is selected.
+     */
+    setSelectedLinkAvoidObstacles(enabled: boolean): void;
+    updateHoveredLinkTarget(worldPoint: Vec2): void;
+    applyLinkPreview(fromElement: ElementId | null, fromPoint: Vec2, toPoint: Vec2): void;
+    private recordGesturePatch;
+    commitGesture(): void;
+    private finalizeOpenGestureTx;
+    /**
+     * End-of-drag container hookup. Runs after the state machine has
+     * received POINTER_UP but before the gesture transaction commits,
+     * so reparent + auto-grow land in one undo step with the drag itself.
+     *
+     * Rules:
+     * - If the shape was dropped over a container and is not yet its child →
+     *   set `parentId`. If the shape extends past the dropZone, the zone is
+     *   grown (and the container's size with it).
+     * - If the shape was someone's child but its final world bounds no longer
+     *   intersect the parent's drop-zone → clear `parentId` (drag-out).
+     * - Cycles (a container inside its own descendant) are prevented by the
+     *   `containerHover` pipeline above — the exclude set rules them out.
+     */
+    applyContainerDrop(worldPoint: Vec2): void;
+    private maybeGrowContainer;
+    private clampContainerToChildren;
+    /**
+     * Return the running gesture tx, or open a new one if the drag finished
+     * with an empty transaction (a move-by-zero-pixels gesture can still
+     * carry a container reparent).
+     */
+    private beginOrAttachGesture;
+    cancelGesture(): void;
+    /**
+     * Drop ids from the selection that no longer exist in the scene. Needed
+     * after undoing a CREATE — the shape goes away and the selection becomes
+     * stale.
+     */
+    private pruneSelection;
+    notify(): void;
+    /**
+     * Pending `requestAnimationFrame` id for the next render, or null
+     * when no render is scheduled. Used to coalesce bursts of `notify()`
+     * calls (drag-pan, drag shape, multi-key, scripted batch mutations)
+     * into a single render per frame.
+     */
+    private renderRafId;
+    /** Unsubscribe for the animation-content-ready listener (decode → re-render). */
+    private animationContentOff;
+    /**
+     * Schedule a render on the next animation frame. Idempotent —
+     * multiple calls within the same frame collapse to one render.
+     *
+     * Falls back to a synchronous render when `requestAnimationFrame`
+     * is unavailable (Node without jsdom, SSR). Browser / test environments
+     * with rAF get the coalesced path.
+     *
+     * Use {@link forceRender} when you need the render to happen
+     * immediately (PNG export, screenshot, visual-regression tests that
+     * compare bitmap output after a mutation).
+     */
+    private scheduleRender;
+    /**
+     * Synchronously render the current state. Cancels any pending
+     * rAF-scheduled render so the next browser frame doesn't paint
+     * a stale state on top.
+     *
+     * Hosts only need this when they read back the rendered bitmap
+     * immediately after a mutation — `editor.toPng()`, custom
+     * `canvas.toDataURL()` flows, visual-regression test asserts.
+     * Normal interactive flows should let `scheduleRender` do its job.
+     */
+    forceRender(): void;
+    /**
+     * 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.
+     */
+    on<K extends keyof EditorEvents>(event: K, fn: EditorEvents[K]): () => void;
+    off<K extends keyof EditorEvents>(event: K, fn: EditorEvents[K]): void;
+    /**
+     * Public command — re-run the auto-layout spec on the given
+     * container shape, regardless of whether the children set actually
+     * changed. Useful as an "auto-arrange" toolbar action or for hosts
+     * adopting auto-layout after creating shapes programmatically.
+     * Returns the patch that was applied, or `null` when nothing
+     * changed (no spec, no children, or children already in position).
+     * Single undo step.
+     */
+    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`.
+     */
+    private readonly elbowRouteSig;
+    private elbowSignature;
+    /**
+     * 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).
+     */
+    private rerouteElbows;
+    private render;
+}
+//# sourceMappingURL=editor.d.ts.map