f1ow 0.1.0

package/dist/utils/elbow.d.ts

@@ -0,0 +1,110 @@
+import { Point, Binding, CanvasElement } from '../types';
+export type Direction = 'up' | 'down' | 'left' | 'right';
+/** Shape bounding box using x/y/width/height (canvas element convention) */
+interface BBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Determine the preferred exit direction for elbow routing from a
+ * center (imprecise) binding.
+ *
+ * Unlike `directionFromShapeToPoint` which picks the face that
+ * geometrically faces the target (optimal for straight lines), this
+ * function prefers VERTICAL exits (up/down) for diagonal configurations.
+ *
+ * Rationale: For orthogonal/elbow routing, vertical exits produce
+ * clean C-shaped or S-shaped paths that route ABOVE or BELOW shapes.
+ * Horizontal exits (from side faces) create paths that run BETWEEN
+ * shapes at their vertical center — visually too close to objects and
+ * often requiring more bends.
+ *
+ * Only uses horizontal exits when the target is strongly horizontally
+ * aligned (>3× horizontal dominance after normalizing by shape size).
+ *
+ * This function should be used by BOTH:
+ * - The binding system (connection.ts) to compute edge points for
+ *   elbow connectors with center bindings
+ * - The routing system (computeElbowPoints) to determine exit direction
+ *
+ * For PRECISE bindings, always use directionFromFixedPoint instead.
+ */
+export declare function getElbowPreferredDirection(shape: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, targetPoint: Point): Direction;
+/**
+ * Determine the exit/entry direction from a binding's fixedPoint.
+ * fixedPoint is [fx, fy] in [0-1, 0-1] on the target shape's bbox.
+ *
+ *   [0.5, 0]   → top    → exit upward
+ *   [0.5, 1]   → bottom → exit downward
+ *   [0,  0.5]  → left   → exit leftward
+ *   [1,  0.5]  → right  → exit rightward
+ *
+ * For corners and arbitrary positions, pick the nearest edge.
+ */
+export declare function directionFromFixedPoint(fp: [number, number]): Direction;
+/**
+ * Determine direction from relative position of two points
+ * (used when there's no binding / fixedPoint).
+ * Picks the dominant axis between start and end.
+ */
+export declare function directionFromPoints(from: Point, to: Point): Direction;
+/**
+ * Determine the best exit direction from a shape toward a target point.
+ * Normalizes by half-dimensions so the correct face is chosen regardless
+ * of aspect ratio.
+ */
+export declare function directionFromShapeToPoint(shape: BBox, targetPoint: Point): Direction;
+/**
+ * Determine exit direction by finding which face of a shape's bounding box
+ * an edge point is closest to. Most accurate method — uses the ACTUAL
+ * computed edge point from the binding system.
+ */
+export declare function directionFromEdgePoint(shape: BBox, edgePoint: Point): Direction;
+/**
+ * Compute an orthogonal route between two points using a multi-candidate
+ * grid-based shortest-path algorithm.
+ *
+ * Generates multiple obstacle inflation configurations and routes through
+ * each, then picks the route with the fewest bends (and shortest length
+ * as tiebreaker). This produces cleaner paths, especially when shapes
+ * are positioned diagonally and the standard inflation blocks direct routes.
+ *
+ * Obstacle configurations:
+ *
+ * 1. **Standard**: Each shape inflated on all sides except its exit/entry
+ *    face. Works well when shapes are aligned horizontally or vertically.
+ *
+ * 2. **Relaxed**: Additionally excludes the face of each shape that faces
+ *    toward the other connection point. This creates L-shaped corridors
+ *    around shapes, allowing more direct paths when shapes are diagonal.
+ *    For example, if start exits RIGHT and end shape is UP-RIGHT, the
+ *    relaxed config also opens the LEFT face of the end shape, enabling
+ *    a clean 2-bend path instead of a 4-bend detour.
+ *
+ * @param start     Start connection point (world coordinates)
+ * @param end       End connection point (world coordinates)
+ * @param startDir  Exit direction from start shape
+ * @param endDir    Exit direction from end shape (face the connector arrives at)
+ * @param startBBox Bounding box of start shape (null for unbound endpoints)
+ * @param endBBox   Bounding box of end shape (null for unbound endpoints)
+ * @returns         Array of Points forming the orthogonal path (world coords)
+ */
+export declare function computeElbowRoute(start: Point, end: Point, startDir: Direction, endDir: Direction, startBBox?: BBox | null, endBBox?: BBox | null, minStubLength?: number, 
+/** Additional obstacles (intermediate shapes) to avoid — already as BBox */
+intermediateObstacles?: BBox[]): Point[];
+/** Clear the route cache (call when elements change structurally) */
+export declare function clearElbowRouteCache(): void;
+export declare function computeElbowPoints(startWorld: Point, endWorld: Point, startBinding: Binding | null, endBinding: Binding | null, allElements: CanvasElement[], minStubLength?: number): number[];
+/**
+ * Simplify an elbow path (flat number[] format) by removing redundant
+ * collinear points and zero-length segments.
+ */
+export declare function simplifyElbowPath(points: number[]): number[];
+export {};

package/dist/utils/elbowWorkerManager.d.ts

@@ -0,0 +1,53 @@
+import { CanvasElement, Binding, Point } from '../types';
+export interface RouteParams {
+    startWorld: Point;
+    endWorld: Point;
+    startBinding: Binding | null;
+    endBinding: Binding | null;
+    minStubLength?: number;
+}
+export declare class ElbowWorkerManager {
+    private worker;
+    private requestIdCounter;
+    private pending;
+    private cachedElements;
+    private workerSupported;
+    /**
+     * Get or lazily create the Worker instance.
+     * Returns null if Workers are not supported in the current environment.
+     */
+    private _getWorker;
+    private handleMessage;
+    /**
+     * Update the Worker's element snapshot for obstacle detection.
+     * Call this whenever elements change (position, size, visibility).
+     */
+    updateElements(elements: CanvasElement[]): void;
+    /**
+     * Compute an elbow route asynchronously via the Worker.
+     * Falls back to synchronous main-thread computation when:
+     * - Worker is not available
+     * - Element count is below WORKER_THRESHOLD
+     * - Worker is busy and request times out
+     */
+    computeRoute(params: RouteParams): Promise<number[]>;
+    /**
+     * Synchronous fallback computation (original behavior).
+     */
+    computeSync(params: RouteParams): number[];
+    /**
+     * Terminate the Worker and clean up resources.
+     */
+    dispose(): void;
+    /** Whether the Worker can be used (environment supports it) */
+    get isWorkerActive(): boolean;
+}
+/**
+ * Get or create the shared ElbowWorkerManager singleton.
+ * The Worker is created lazily on first access.
+ */
+export declare function getElbowWorkerManager(): ElbowWorkerManager;
+/**
+ * Dispose the shared manager (e.g. when FlowCanvas unmounts).
+ */
+export declare function disposeElbowWorkerManager(): void;

package/dist/utils/export.d.ts

@@ -0,0 +1,17 @@
+import { default as Konva } from 'konva';
+import { CanvasElement } from '../types';
+/** Export stage to data URL (PNG) */
+export declare function exportToDataURL(stage: Konva.Stage): string;
+/** Export stage as downloadable PNG */
+export declare function downloadPNG(stage: Konva.Stage, filename?: string): void;
+/** Export elements to JSON string */
+export declare function exportToJSON(elements: unknown[]): string;
+/** Download JSON */
+export declare function downloadJSON(elements: unknown[], filename?: string): void;
+/**
+ * Export canvas elements to an SVG string.
+ * Computes tight bounding box + padding automatically.
+ */
+export declare function exportToSVG(elements: CanvasElement[]): string;
+/** Download SVG file */
+export declare function downloadSVG(elements: CanvasElement[], filename?: string): void;

package/dist/utils/exportWorkerManager.d.ts

@@ -0,0 +1,25 @@
+import { CanvasElement } from '../types';
+export declare class ExportWorkerManager {
+    private _worker;
+    private _pending;
+    private _workerSupported;
+    private _getWorker;
+    private _onMessage;
+    private _rejectAll;
+    /**
+     * Export elements to SVG string.
+     * Uses Worker for large sets, sync for small sets.
+     */
+    exportSVG(elements: CanvasElement[]): Promise<string>;
+    /**
+     * Export elements to SVG and download as file.
+     * Uses Worker for SVG generation, then triggers browser download.
+     */
+    downloadSVG(elements: CanvasElement[], filename?: string): Promise<void>;
+    /** Terminate the Worker and clean up */
+    dispose(): void;
+}
+/** Get or create the shared ExportWorkerManager singleton */
+export declare function getExportWorkerManager(): ExportWorkerManager;
+/** Dispose the shared ExportWorkerManager singleton */
+export declare function disposeExportWorkerManager(): void;

package/dist/utils/fractionalIndex.d.ts

@@ -0,0 +1,51 @@
+/**
+ * fractionalIndex.ts — Fractional indexing utilities for CRDT-compatible
+ * element ordering.
+ *
+ * Fractional indices allow inserting elements between any two existing
+ * elements without shifting array indices — essential for:
+ *   - Conflict-free concurrent reordering (CRDT)
+ *   - O(1) insert-between operations (no array splice)
+ *   - Stable sort order across distributed replicas
+ *
+ * The algorithm uses string-based fractional indices. Each index is a
+ * string that can be compared lexicographically to determine order.
+ *
+ * Implementation: Uses a base-36 encoding with variable-length strings.
+ * Between any two strings "a" and "b" where a < b, we can always
+ * generate a string "c" such that a < c < b.
+ *
+ * Examples:
+ *   generateKeyBetween(null, null)   → "a0" (first element)
+ *   generateKeyBetween("a0", null)   → "a1" (after first)
+ *   generateKeyBetween(null, "a0")   → "Zz" (before first)
+ *   generateKeyBetween("a0", "a1")   → "a0V" (between)
+ */
+/**
+ * Generate a fractional index key between two existing keys.
+ *
+ * @param a - Lower bound (null = beginning of list)
+ * @param b - Upper bound (null = end of list)
+ * @returns A string key that sorts between a and b
+ *
+ * Invariants:
+ *   - If a is null and b is null, returns a default starting key
+ *   - If a is null, returns a key before b
+ *   - If b is null, returns a key after a
+ *   - generateKeyBetween(a, b) > a && generateKeyBetween(a, b) < b
+ */
+export declare function generateKeyBetween(a: string | null, b: string | null): string;
+/**
+ * Generate N evenly-spaced keys between a and b.
+ * Useful for initial element ordering or batch inserts.
+ */
+export declare function generateNKeysBetween(a: string | null, b: string | null, n: number): string[];
+/**
+ * Validate that a fractional index is well-formed.
+ */
+export declare function isValidFractionalIndex(key: string): boolean;
+/**
+ * Compare two fractional index keys.
+ * Returns negative if a < b, zero if equal, positive if a > b.
+ */
+export declare function compareFractionalKeys(a: string, b: string): number;

package/dist/utils/geometry.d.ts

@@ -0,0 +1,49 @@
+import { Point } from '../types';
+/** Snap a value to the nearest grid increment */
+export declare function snapToGrid(value: number, gridSize: number): number;
+/** Distance between two points */
+export declare function distance(a: Point, b: Point): number;
+/** Normalize a point pair to top-left + dimensions */
+export declare function normalizeRect(start: Point, end: Point): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** Rotate a point around a center */
+export declare function rotatePoint(point: Point, center: Point, angle: number): Point;
+/** Check if a point is inside a rectangle */
+export declare function isPointInRect(point: Point, rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): boolean;
+/** Get diamond polygon points from bounding box */
+export declare function getDiamondPoints(width: number, height: number): number[];
+/**
+ * Normalize a point pair to a **symmetric** (square) bounding box.
+ * The larger of |dx| or |dy| is used for both dimensions.
+ * Origin stays at the `start` corner and expands toward the `end` direction.
+ */
+export declare function normalizeSymmetricRect(start: Point, end: Point): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Constrain an endpoint so the line from `start` → `end` snaps
+ * to the nearest 45° increment (0°, 45°, 90°, 135°, …).
+ */
+export declare function constrainLineAngle(start: Point, end: Point): Point;
+/**
+ * Compute bounding width/height extents from a flat [x,y,x,y,...] points array.
+ * Used by linear element shapes and handles.
+ */
+export declare function computePointsBounds(pts: number[]): {
+    width: number;
+    height: number;
+};
+/** Convert dash style string to Konva dash array */
+export declare function getStrokeDash(style: 'solid' | 'dashed' | 'dotted', strokeWidth: number): number[];

package/dist/utils/id.d.ts

@@ -0,0 +1 @@
+export declare function generateId(): string;

package/dist/utils/image.d.ts

@@ -0,0 +1,52 @@
+import { ImageElement, ElementStyle } from '../types';
+/**
+ * Read a File (image) as a base64 data URL.
+ */
+export declare function fileToDataURL(file: File): Promise<string>;
+/**
+ * Load an HTMLImageElement from a src URL (data URL or external).
+ * Returns the loaded image with its natural dimensions.
+ */
+export declare function loadImage(src: string): Promise<HTMLImageElement>;
+/**
+ * Compute element dimensions that fit the image within max bounds
+ * while preserving aspect ratio.
+ */
+export declare function computeImageElementDimensions(naturalWidth: number, naturalHeight: number, maxWidth?: number, maxHeight?: number): {
+    width: number;
+    height: number;
+};
+/**
+ * Create an ImageElement from a loaded image and its data URL.
+ */
+export declare function createImageElement(src: string, naturalWidth: number, naturalHeight: number, x: number, y: number, style?: ElementStyle): ImageElement;
+/**
+ * Extract image files from a DataTransfer (paste/drop).
+ */
+export declare function getImageFilesFromDataTransfer(dt: DataTransfer): File[];
+/**
+ * Check synchronously whether a ClipboardEvent contains image data.
+ * Must be called during the event handler (before any await),
+ * because browsers invalidate clipboardData after the handler returns.
+ */
+export declare function extractImageDataFromClipboard(e: ClipboardEvent): {
+    file: File | null;
+    imgUrl: string | null;
+};
+/**
+ * Check synchronously whether a ClipboardEvent has image content.
+ */
+export declare function clipboardHasImage(e: ClipboardEvent): boolean;
+/**
+ * Resolve the extracted clipboard image data into a data URL.
+ * This is the async part — call AFTER synchronous extraction.
+ */
+export declare function resolveImageSource(data: {
+    file: File | null;
+    imgUrl: string | null;
+}): Promise<string | null>;
+/**
+ * Open a file picker dialog for images.
+ * Returns an array of selected image files.
+ */
+export declare function openImageFilePicker(): Promise<File[]>;

package/dist/utils/performance.d.ts

@@ -0,0 +1,65 @@
+import { CanvasElement, ViewportState } from '../types';
+/** Bounding box in world coordinates */
+export interface AABB {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+/**
+ * Compute the visible world-coordinate rectangle from the viewport
+ * state and the Stage pixel dimensions.
+ * @param viewport - current pan/zoom state
+ * @param stageWidth - pixel width of the Stage element
+ * @param stageHeight - pixel height of the Stage element
+ * @param padding - extra world-space padding around the visible area
+ *   so that elements slightly outside the viewport are still rendered
+ *   (avoids pop-in during fast pan). Default 200 world-units.
+ */
+export declare function getVisibleBounds(viewport: ViewportState, stageWidth: number, stageHeight: number, padding?: number): AABB;
+/**
+ * Compute the axis-aligned bounding box for a single element.
+ * Handles line/arrow elements whose visual extent depends on `points`.
+ */
+export declare function getElementAABB(el: CanvasElement): AABB;
+/** Check if two AABBs overlap */
+export declare function aabbOverlaps(a: AABB, b: AABB): boolean;
+/**
+ * Filter elements to only those visible in the viewport.
+ * Elements currently selected are always included (for transformer handles).
+ */
+export declare function cullToViewport(elements: CanvasElement[], viewport: ViewportState, stageWidth: number, stageHeight: number, selectedIds: ReadonlySet<string>, padding?: number): CanvasElement[];
+/** Build an id → element Map for O(1) lookups */
+export declare function buildElementMap(elements: CanvasElement[]): Map<string, CanvasElement>;
+/**
+ * Deep clone elements for history snapshots.
+ * Uses structuredClone (native, faster than JSON roundtrip)
+ * with smart handling for large image data.
+ *
+ * For ImageElements, we share the `src` string reference instead of
+ * duplicating potentially megabytes of base64 data. This is safe
+ * because src strings are immutable (never mutated in place).
+ */
+export declare function cloneElementsForHistory(elements: CanvasElement[]): CanvasElement[];
+/**
+ * Create a throttled function that runs at most once per animation frame.
+ * Unlike lodash throttle, this syncs with the browser paint cycle.
+ */
+export declare function rafThrottle<T extends (...args: any[]) => void>(fn: T): T & {
+    cancel: () => void;
+};
+/**
+ * Batch multiple element updates into a single store write.
+ * Reduces re-renders during complex operations like paste or import.
+ */
+export declare function batchElementUpdates(elements: CanvasElement[], updates: Array<{
+    id: string;
+    changes: Partial<CanvasElement>;
+}>): CanvasElement[];
+/** Convert an array to a Set for O(1) membership checks */
+export declare function toSet<T>(arr: readonly T[]): ReadonlySet<T>;
+/**
+ * Shallow compare two arrays by reference for memoization.
+ * Useful for avoiding re-computation when selectedIds hasn't actually changed.
+ */
+export declare function arraysEqual<T>(a: readonly T[], b: readonly T[]): boolean;

package/dist/utils/roughness.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Lightweight hand-drawn / rough rendering utilities for Konva shapes.
+ *
+ * Produces a hand-drawn appearance via configurable "Sloppiness"
+ * setting and rough.js — bézier curves with jittered control points and
+ * angle-aware corner rounding.
+ *
+ * Sloppiness presets:
+ *   0 — Architect  (clean, precise lines — no rough effect)
+ *   1 — Artist     (subtle hand-drawn feel, single stroke pass)
+ *   2 — Cartoonist (heavy wobble, double stroke pass)
+ *
+ * Key improvements over v1:
+ *   • xorshift seeded PRNG returning [-1,1] with direct string seed
+ *   • strokeWidth-proportional offset/roundness for consistent look
+ *   • Angle-aware corner rounding via quadratic bézier (reduces at obtuse angles)
+ *   • Segment-length clamping to prevent visual artifacts on short edges
+ *   • Per-pass seeding for more organic overlapping strokes
+ *   • Cubic bézier ellipse arcs for smoother curves
+ */
+/**
+ * Simple hash to convert any string (element ID) to a numeric seed.
+ * Uses FNV-1a–style hash.
+ */
+export declare function hashString(str: string): number;
+/**
+ * Seeded PRNG using xorshift algorithm.
+ * Accepts a string seed directly and returns values in [-1, 1].
+ *
+ * Based on a standard xorshift PRNG implementation.
+ */
+export declare function createRNG(seed: string | number): () => number;
+/**
+ * Minimal subset of Canvas 2D / Konva.Context used by rough helpers.
+ * Both `CanvasRenderingContext2D` and Konva's `Context` satisfy this.
+ */
+export interface RoughCtx {
+    beginPath(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
+    closePath(): void;
+}
+/**
+ * Number of stroke passes for a given roughness level.
+ *   - Architect (0): 1 pass (clean)
+ *   - Artist    (1): 1 pass (single hand-drawn stroke)
+ *   - Cartoonist(2): 2 passes (overlapping sketchy strokes)
+ */
+export declare function getRoughPasses(roughness: number): number;
+/**
+ * Draw a rough rectangle stroke (no fill).
+ *
+ * Uses angle-aware corner rounding for a natural hand-drawn look.
+ * Offset and roundness scale proportionally with strokeWidth.
+ */
+export declare function drawRoughRectStrokes(ctx: RoughCtx, x: number, y: number, w: number, h: number, roughness: number, rng: () => number, passes?: number, strokeWidth?: number): void;
+/**
+ * Draw a rough ellipse stroke path using cubic bézier arcs.
+ *
+ * Uses 4 cubic bézier curves (one per quadrant) with radial jitter,
+ * producing smoother, more natural curves than the v1 quadratic approach.
+ *
+ * Builds the path into the context; caller is responsible for `ctx.strokeShape()`.
+ */
+export declare function drawRoughEllipseStrokes(ctx: RoughCtx, cx: number, cy: number, rx: number, ry: number, roughness: number, rng: () => number, passes?: number, strokeWidth?: number): void;
+/**
+ * Draw a rough diamond (rhombus) stroke with corner rounding.
+ */
+export declare function drawRoughDiamondStrokes(ctx: RoughCtx, w: number, h: number, roughness: number, rng: () => number, passes?: number, strokeWidth?: number): void;
+/**
+ * Generate rough polyline points for Line/Arrow shapes.
+ *
+ * Returns a new flat array `[x0, y0, x1, y1, …]` with intermediate points
+ * jittered. First and last points are kept untouched (they may be bound).
+ */
+export declare function roughPolylinePoints(points: number[], roughness: number, rng: () => number, strokeWidth?: number): number[];
+/**
+ * Draw a rough straight-line segment for Line/Arrow shapes.
+ *
+ * Instead of connecting points with a plain `<Line>`, this draws each segment
+ * as a rough bézier, giving a hand-drawn look.
+ *
+ * @param ctx     Konva / Canvas 2D context
+ * @param points  Flat point array `[x0, y0, x1, y1, …]`
+ */
+export declare function drawRoughPolyline(ctx: RoughCtx, points: number[], roughness: number, rng: () => number, passes?: number, strokeWidth?: number): void;
+/**
+ * Draw a rough curved (quadratic bézier) line between two points with a
+ * control point. Adds wobble to the curve path.
+ *
+ * Offset scales with strokeWidth for consistent appearance.
+ */
+export declare function drawRoughCurve(ctx: RoughCtx, start: {
+    x: number;
+    y: number;
+}, cp: {
+    x: number;
+    y: number;
+}, end: {
+    x: number;
+    y: number;
+}, roughness: number, rng: () => number, passes?: number, strokeWidth?: number): void;

package/dist/utils/spatialIndex.d.ts

@@ -0,0 +1,109 @@
+import { CanvasElement, ViewportState } from '../types';
+/** An item in the R-tree: axis-aligned bounding box + element ID */
+export interface SpatialItem {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+    id: string;
+}
+/**
+ * Compute AABB for a single element.
+ * Same logic as `getElementAABB` in performance.ts but returns the
+ * SpatialItem shape (with `id`) for direct R-tree insertion.
+ */
+export declare function elementToSpatialItem(el: CanvasElement): SpatialItem;
+/**
+ * Wrapper around RBush providing element-aware spatial operations.
+ *
+ * Usage:
+ * ```ts
+ * const index = new SpatialIndex();
+ * index.rebuild(elements);
+ * const visibleIds = index.queryViewport(viewport, stageWidth, stageHeight);
+ * ```
+ */
+export declare class SpatialIndex {
+    private tree;
+    /** O(1) id → element lookup, rebuilt alongside the tree */
+    private _elementMap;
+    /**
+     * Fattened AABB entries for temporal coherence.
+     * Tracks true vs fattened bounds to skip R-tree updates
+     * when an element's true AABB still fits within its fattened AABB.
+     */
+    private _fattenedMap;
+    /**
+     * Fattening margin in world-space pixels.
+     * Covers ~5-10 frames of typical drag movement at 60fps (2-10 px/frame).
+     * Box2D uses ~10% of element size; 50px is a good universal default
+     * that covers most interactive adjustments without triggering re-insertion.
+     */
+    private _margin;
+    constructor(maxEntries?: number);
+    /** Get / set the fattening margin (world-space px) */
+    get margin(): number;
+    set margin(value: number);
+    /**
+     * Rebuild the entire index from scratch (bulk load).
+     * O(n log n) — ~5ms for 10K elements.
+     * All entries are freshly fattened.
+     */
+    rebuild(elements: CanvasElement[]): void;
+    /**
+     * Update the spatial position of a single element.
+     *
+     * Uses temporal coherence: if the element's new true AABB still fits
+     * within its fattened AABB, we only update the true bounds (O(1))
+     * and skip the expensive R-tree remove + re-insert (O(log n)).
+     *
+     * Returns `true` if the R-tree was structurally modified,
+     * `false` if the update was absorbed by the fattened margin.
+     */
+    update(element: CanvasElement): boolean;
+    /**
+     * Remove a single element from the index.
+     */
+    remove(id: string): void;
+    /**
+     * Query all elements whose AABB overlaps the given viewport region.
+     * Returns element IDs (not full objects) for efficiency.
+     *
+     * @param viewport - current pan/zoom
+     * @param stageWidth - Stage pixel width
+     * @param stageHeight - Stage pixel height
+     * @param padding - extra world-space padding (default 200)
+     */
+    queryViewport(viewport: ViewportState, stageWidth: number, stageHeight: number, padding?: number): string[];
+    /**
+     * Query all elements whose AABB overlaps the given rectangle.
+     * Returns SpatialItems (with id + bounds).
+     */
+    queryRect(minX: number, minY: number, maxX: number, maxY: number): SpatialItem[];
+    /**
+     * Point query — find elements at an exact world coordinate.
+     * Useful for hit testing / click detection.
+     * Returns matching element IDs.
+     */
+    queryPoint(wx: number, wy: number): string[];
+    /** O(1) element lookup by ID */
+    getElementById(id: string): CanvasElement | undefined;
+    /** The full element map (read-only reference) */
+    get elementMap(): ReadonlyMap<string, CanvasElement>;
+    /** Number of elements in the index */
+    get size(): number;
+    /**
+     * Get the true (non-fattened) AABB for an element.
+     * Returns undefined if the element is not in the index.
+     */
+    getTrueAABB(id: string): {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    } | undefined;
+    /** Clear all data */
+    clear(): void;
+}
+/** Get or create a shared SpatialIndex singleton */
+export declare function getSharedSpatialIndex(): SpatialIndex;