f1ow 0.1.0

package/dist/types/index.d.ts

@@ -0,0 +1,257 @@
+export type ToolType = 'select' | 'hand' | 'rectangle' | 'ellipse' | 'diamond' | 'line' | 'arrow' | 'freedraw' | 'text' | 'image' | 'eraser';
+export type ElementType = 'rectangle' | 'ellipse' | 'diamond' | 'line' | 'arrow' | 'freedraw' | 'text' | 'image';
+export type Arrowhead = 'arrow' | 'triangle' | 'triangle_outline' | 'circle' | 'circle_outline' | 'diamond' | 'diamond_outline' | 'bar' | 'crowfoot_one' | 'crowfoot_many' | 'crowfoot_one_or_many';
+export type LineType = 'sharp' | 'curved' | 'elbow';
+export interface ElementStyle {
+    strokeColor: string;
+    fillColor: string;
+    strokeWidth: number;
+    opacity: number;
+    strokeStyle: 'solid' | 'dashed' | 'dotted';
+    roughness: number;
+    fontSize: number;
+    fontFamily: string;
+}
+export interface BaseElement {
+    id: string;
+    type: ElementType;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation: number;
+    style: ElementStyle;
+    isLocked: boolean;
+    isVisible: boolean;
+    /** Bidirectional refs: arrows/text bound to this element */
+    boundElements: BoundElement[] | null;
+    /** Group hierarchy: element belongs to these groups (innermost first, outermost last) */
+    groupIds?: string[];
+    /**
+     * Fractional index for CRDT-compatible z-ordering.
+     * When present, elements are sorted by this field instead of array position.
+     * Uses lexicographic string comparison (e.g., "a0" < "a1" < "a2").
+     * Generated via `generateKeyBetween()` from `utils/fractionalIndex.ts`.
+     * @see {@link ../utils/fractionalIndex.ts}
+     */
+    sortOrder?: string;
+    /**
+     * Collaboration metadata for CRDT sync.
+     * Optional — only populated when collaboration features are active.
+     */
+    _meta?: ElementMeta;
+}
+/**
+ * Metadata for CRDT-based collaborative editing.
+ * Stored alongside each element but not rendered — used for
+ * conflict resolution, presence tracking, and version history.
+ */
+export interface ElementMeta {
+    /** Unique ID of the user who last modified this element */
+    lastModifiedBy?: string;
+    /** Timestamp (ms since epoch) of the last modification */
+    lastModifiedAt?: number;
+    /** Monotonically increasing version counter */
+    version?: number;
+}
+/**
+ * Intent-based operations for CRDT-compatible history.
+ * Stores the *intent* of a change rather than before/after snapshots.
+ * Each operation is designed to be commutative and associative,
+ * making it suitable for conflict-free replication.
+ */
+export type CanvasOperation = {
+    type: 'add';
+    element: CanvasElement;
+} | {
+    type: 'delete';
+    elementId: string;
+} | {
+    type: 'move';
+    elementId: string;
+    dx: number;
+    dy: number;
+} | {
+    type: 'resize';
+    elementId: string;
+    width: number;
+    height: number;
+    x?: number;
+    y?: number;
+} | {
+    type: 'style';
+    elementId: string;
+    changes: Partial<ElementStyle>;
+} | {
+    type: 'rotate';
+    elementId: string;
+    rotation: number;
+} | {
+    type: 'reorder';
+    elementId: string;
+    sortOrder: string;
+} | {
+    type: 'updatePoints';
+    elementId: string;
+    points: number[];
+} | {
+    type: 'setText';
+    elementId: string;
+    text: string;
+} | {
+    type: 'batch';
+    operations: CanvasOperation[];
+};
+export interface RectangleElement extends BaseElement {
+    type: 'rectangle';
+    cornerRadius: number;
+}
+export interface EllipseElement extends BaseElement {
+    type: 'ellipse';
+}
+export interface DiamondElement extends BaseElement {
+    type: 'diamond';
+}
+export interface LineElement extends BaseElement {
+    type: 'line';
+    points: number[];
+    /** Routing type: sharp = straight segments, curved = smooth */
+    lineType: LineType;
+    /** Curvature ratio for curved mode (perpendicular offset / distance). Default 0.2. */
+    curvature?: number;
+    startBinding: Binding | null;
+    endBinding: Binding | null;
+}
+export interface ArrowElement extends BaseElement {
+    type: 'arrow';
+    points: number[];
+    /** Arrowhead at the start of the arrow (null = none) */
+    startArrowhead: Arrowhead | null;
+    /** Arrowhead at the end of the arrow (null = none) */
+    endArrowhead: Arrowhead | null;
+    /** @deprecated Use startArrowhead / endArrowhead. Kept for backward compat. */
+    startArrow?: boolean;
+    /** @deprecated Use startArrowhead / endArrowhead. Kept for backward compat. */
+    endArrow?: boolean;
+    /** Routing type: sharp = straight segments, curved = smooth Bézier */
+    lineType: LineType;
+    /** Curvature ratio for curved mode (perpendicular offset / distance). Default 0.2. */
+    curvature?: number;
+    startBinding: Binding | null;
+    endBinding: Binding | null;
+}
+export interface FreeDrawElement extends BaseElement {
+    type: 'freedraw';
+    points: number[];
+}
+export type TextAlign = 'left' | 'center' | 'right';
+export type VerticalAlign = 'top' | 'middle' | 'bottom';
+export type ImageScaleMode = 'fit' | 'fill' | 'stretch';
+/** Optional crop region for images (values in pixels on the original image) */
+export interface ImageCrop {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface TextElement extends BaseElement {
+    type: 'text';
+    text: string;
+    /** ID of the container shape this text is bound to (null = standalone) */
+    containerId: string | null;
+    /** Horizontal text alignment inside container */
+    textAlign: TextAlign;
+    /** Vertical text alignment inside container */
+    verticalAlign: VerticalAlign;
+}
+export interface ImageElement extends BaseElement {
+    type: 'image';
+    /** Base64 data URL or external URL of the image */
+    src: string;
+    /** Original intrinsic width of the loaded image (px) */
+    naturalWidth: number;
+    /** Original intrinsic height of the loaded image (px) */
+    naturalHeight: number;
+    /** How the image fits inside its bounding box */
+    scaleMode: ImageScaleMode;
+    /** Optional crop region on the original image */
+    crop: ImageCrop | null;
+    /** Border radius (px) for rounded image corners */
+    cornerRadius: number;
+    /** Alt / label text used in SVG export and accessibility */
+    alt: string;
+}
+export type CanvasElement = RectangleElement | EllipseElement | DiamondElement | LineElement | ArrowElement | FreeDrawElement | TextElement | ImageElement;
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface ViewportState {
+    x: number;
+    y: number;
+    scale: number;
+}
+export interface SelectionBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * @deprecated Use fixedPoint binding instead. Kept for backward-compat exports.
+ */
+export type ConnectionAnchor = 'top' | 'bottom' | 'left' | 'right' | 'center';
+/** Bidirectional reference stored on shapes to track bound connectors/text */
+export type BoundElement = {
+    id: string;
+    type: 'arrow' | 'line' | 'text';
+};
+/** Describes one end of a connector (arrow/line) bound to a shape */
+export interface Binding {
+    /** The element this end is connected to */
+    elementId: string;
+    /**
+     * Continuous attachment ratio [0-1, 0-1] on target's bounding box.
+     * e.g. [0.5, 0] = top center, [1, 0.5] = right center, [0.3, 0.7] = arbitrary.
+     */
+    fixedPoint: [number, number];
+    /** Gap between the edge of the shape and the arrow tip (px) */
+    gap: number;
+    /**
+     * Whether to bind to the exact fixedPoint position, or to the shape center.
+     * When false (default), the arrow connects from/to the shape's center,
+     * producing cleaner visuals with auto-routed connections.
+     * When true, the arrow connects to the exact fixedPoint on the shape.
+     */
+    isPrecise?: boolean;
+}
+/** Snap candidate returned while drawing */
+export interface SnapTarget {
+    elementId: string;
+    /** Continuous attachment point ratio on target bbox */
+    fixedPoint: [number, number];
+    /** Computed edge-point position in world coordinates */
+    position: Point;
+    /**
+     * Whether this snap uses precise (edge) binding or center binding.
+     * Automatically determined by cursor proximity to shape edge vs center.
+     * - `true`:  cursor is near the edge → attaches to that specific edge point
+     * - `false`: cursor is in the center zone → attaches to center for auto-routing
+     */
+    isPrecise: boolean;
+}
+/** State for editing individual points of a line/arrow element */
+export interface LinearEditState {
+    /** ID of the element currently being edited */
+    elementId: string;
+    /** Whether the editor is in full editing mode (point manipulation) */
+    isEditing: boolean;
+    /** Indices of currently selected points */
+    selectedPointIndices: number[];
+    /** Index of the point the cursor is hovering over (-1 = none) */
+    hoveredPointIndex: number;
+    /** Index of the midpoint the cursor is hovering over (null = none) */
+    hoveredMidpointIndex: number | null;
+    /** Whether a point is currently being dragged */
+    isDraggingPoint: boolean;
+}

package/dist/utils/alignment.d.ts

@@ -0,0 +1,34 @@
+import { CanvasElement } from '../types';
+/** A single alignment guide line */
+export interface AlignGuide {
+    /** 'h' = horizontal line (y aligned), 'v' = vertical line (x aligned) */
+    orientation: 'h' | 'v';
+    /** Position on the align axis (x for vertical, y for horizontal) */
+    position: number;
+    /** Guide extent — start coordinate on cross axis */
+    start: number;
+    /** Guide extent — end coordinate on cross axis */
+    end: number;
+}
+export interface AlignResult {
+    /** Snapped x (undefined = no x snap) */
+    x?: number;
+    /** Snapped y (undefined = no y snap) */
+    y?: number;
+    /** Guides to render */
+    guides: AlignGuide[];
+}
+/**
+ * Compute alignment guides for a moving element against all other elements.
+ *
+ * @param moving   - The element being dragged (with current position)
+ * @param others   - All other canvas elements to compare against
+ * @param threshold - Pixel distance for snapping (default 5)
+ * @returns Snapped x/y offsets and guide lines to render
+ */
+export declare function computeAlignGuides(movingBounds: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, others: CanvasElement[], excludeIds: Set<string>, threshold?: number): AlignResult;

package/dist/utils/arrowheads.d.ts

@@ -0,0 +1,20 @@
+import { Arrowhead, Point } from '../types';
+import { Context } from 'konva/lib/Context';
+export declare function arrowheadSize(strokeWidth: number): number;
+/**
+ * Draw an arrowhead of the given type at `tip`, with the arrow
+ * body arriving from direction `from`.
+ *
+ * @param ctx       Konva canvas context
+ * @param type      Arrowhead variant
+ * @param tip       Position of the arrowhead tip (world-local coords)
+ * @param from      Position the arrow body is coming *from*
+ * @param size      Size of the arrowhead (pixel length)
+ * @param stroke    Stroke color
+ * @param strokeW   Stroke width
+ */
+export declare function drawArrowhead(ctx: Context, type: Arrowhead, tip: Point, from: Point, size: number, stroke: string, strokeW: number): void;
+/**
+ * Get pairs of { x, y } from flat points array.
+ */
+export declare function flatToPoints(pts: number[]): Point[];

package/dist/utils/camera.d.ts

@@ -0,0 +1,63 @@
+import { ViewportState, CanvasElement } from '../types';
+import { AABB } from './performance';
+/** Predefined zoom steps for smooth discrete zooming */
+export declare const ZOOM_STEPS: readonly [0.1, 0.25, 0.5, 0.75, 1, 1.5, 2, 3, 4, 5];
+/** Default animation duration in ms */
+export declare const DEFAULT_ANIMATION_DURATION = 280;
+export interface ZoomAtPointOptions {
+    /** Current viewport state */
+    viewport: ViewportState;
+    /** Screen-space point to zoom toward (e.g. cursor position) */
+    point: {
+        x: number;
+        y: number;
+    };
+    /** Target zoom scale */
+    targetScale: number;
+}
+/**
+ * Compute new viewport state that zooms to `targetScale` while keeping
+ * `point` (in screen coordinates) stationary — the standard
+ * "zoom toward cursor" algorithm.
+ */
+export declare function zoomAtPoint({ viewport, point, targetScale }: ZoomAtPointOptions): ViewportState;
+/**
+ * Get the next predefined zoom step above the current scale.
+ * Falls back to MAX_ZOOM if already beyond the last step.
+ */
+export declare function getNextZoomStep(currentScale: number): number;
+/**
+ * Get the next predefined zoom step below the current scale.
+ * Falls back to MIN_ZOOM if already below the first step.
+ */
+export declare function getPrevZoomStep(currentScale: number): number;
+/**
+ * Compute the combined bounding box for a set of elements.
+ * Returns null if the array is empty.
+ */
+export declare function getElementsBounds(elements: CanvasElement[]): AABB | null;
+export interface ZoomToFitOptions {
+    /** Pixel padding around the content */
+    padding?: number;
+    /** Maximum zoom level (avoid zooming too far in on tiny content) */
+    maxZoom?: number;
+}
+/**
+ * Compute viewport state that fits the given bounding box within
+ * a stage of the given pixel dimensions.
+ */
+export declare function computeZoomToFit(bounds: AABB, stageWidth: number, stageHeight: number, options?: ZoomToFitOptions): ViewportState;
+/**
+ * Smoothly animate the viewport from its current state to a target state.
+ *
+ * @param from - Start viewport
+ * @param to - Target viewport
+ * @param setViewport - Store setter to apply intermediate states
+ * @param duration - Animation duration in ms (default 280)
+ * @returns A cancel function
+ */
+export declare function animateViewport(from: ViewportState, to: ViewportState, setViewport: (v: Partial<ViewportState>) => void, duration?: number): () => void;
+/**
+ * Cancel any in-progress viewport animation.
+ */
+export declare function cancelViewportAnimation(): void;

package/dist/utils/clipboard.d.ts

@@ -0,0 +1,4 @@
+import { CanvasElement } from '../types';
+export declare function setClipboard(elements: CanvasElement[]): void;
+export declare function getClipboard(): CanvasElement[];
+export declare function hasClipboardContent(): boolean;

package/dist/utils/clone.d.ts

@@ -0,0 +1,29 @@
+import { CanvasElement } from '../types';
+/**
+ * Clone a set of elements with proper id remapping for all cross-references.
+ *
+ * Handles:
+ * - Auto-including bound text of containers
+ * - Generating new ids and building old→new id map
+ * - Remapping containerId, boundElements, startBinding, endBinding
+ * - Remapping groupIds (generates new groupIds so clones form independent groups)
+ * - Deep-cloning nested objects (style, points, bindings) to prevent shared references
+ * - Nullifying dangling refs (when referenced element not in clone set)
+ *
+ * @param originals - Elements to clone (e.g., selected or clipboard)
+ * @param allElements - Full element list for looking up missing bound text
+ *                      (pass `originals` itself if source is clipboard)
+ * @param offset - Positional offset for the clones (default 20)
+ * @returns { clones, idMap, selectedCloneIds }
+ */
+export declare function cloneAndRemapElements(originals: CanvasElement[], allElements: CanvasElement[], offset?: number): {
+    clones: CanvasElement[];
+    idMap: Map<string, string>;
+    selectedCloneIds: string[];
+};
+/**
+ * Gather elements for copy, auto-including:
+ * - Bound text of containers
+ * - All group members of selected elements' groups
+ */
+export declare function gatherElementsForCopy(selectedIds: string[], allElements: CanvasElement[]): CanvasElement[];

package/dist/utils/connection.d.ts

@@ -0,0 +1,122 @@
+import { CanvasElement, Point, ConnectionAnchor, Binding, SnapTarget, ArrowElement, LineElement, BoundElement } from '../types';
+/** Whether an element can be a connection target */
+export declare function isConnectable(el: CanvasElement): boolean;
+/** Get the 5 named anchor positions for a bounding-box shape */
+export declare function getConnectionPoints(el: CanvasElement): Record<ConnectionAnchor, Point>;
+/**
+ * @deprecated Use fixedPoint-based getEdgePointFromFixedPoint() instead.
+ */
+export declare function getAnchorPosition(el: CanvasElement, anchor: ConnectionAnchor): Point;
+/**
+ * Compute the appropriate gap between a connector and a shape edge,
+ * based on both the connector's stroke width and a base offset.
+ * This provides a small gap between the arrow tip and the shape edge.
+ */
+export declare function computeBindingGap(connectorStrokeWidth: number): number;
+/**
+ * Compute a fixedPoint [0-1, 0-1] ratio from a world-space point
+ * relative to a shape's bounding box, accounting for rotation.
+ */
+export declare function computeFixedPoint(el: CanvasElement, worldPt: Point): [number, number];
+/**
+ * Convert a fixedPoint ratio back to a world-space target point,
+ * then compute the edge intersection from center to that target.
+ */
+export declare function getEdgePointFromFixedPoint(el: CanvasElement, fixedPoint: [number, number], gap?: number): Point;
+/**
+ * Given a shape and an external world-space point, compute the point on
+ * the shape's perimeter closest to `toward`.
+ *
+ * Handles shape rotation: transforms `toward` into the shape's local
+ * coordinate system, computes the local edge intersection, then
+ * transforms back to world space.
+ */
+export declare function getEdgePoint(el: CanvasElement, toward: Point, gap?: number): Point;
+/**
+ * Find the nearest connectable shape using **shape-aware** hit detection.
+ * The shape perimeter (+ padding) acts as a drop zone.
+ *
+ * Uses two separate distance thresholds for edge vs center binding:
+ *
+ * 1. **Edge zone** — cursor is OUTSIDE the shape but within
+ *    `edgeOuterThreshold` px of the perimeter, OR cursor is INSIDE
+ *    the shape but within `EDGE_INNER_BAND` px of the nearest edge.
+ *    → Produces precise (edge) binding at the exact cursor position.
+ *
+ * 2. **Center zone** — cursor is INSIDE the shape and farther than
+ *    `EDGE_INNER_BAND` px from any edge.
+ *    → Produces center binding (fixedPoint [0.5, 0.5]) for clean
+ *      auto-routing.
+ *
+ * The pixel-based inner band ensures consistent edge/center zones
+ * regardless of shape size.
+ *
+ * @param pos                Current pointer position (canvas coords)
+ * @param elements           All elements on canvas
+ * @param edgeOuterThreshold How far outside the shape perimeter to detect (px).
+ *                           Defaults to `EDGE_SNAP_THRESHOLD`.
+ * @param excludeIds         Element IDs to skip (e.g. the connector itself)
+ * @param toward             Direction for edge-point calculation; defaults to `pos`
+ * @param forcePrecise       Force precise mode (skip auto-detection).
+ *                           Use `undefined` for auto-detection (recommended).
+ * @param gap                Gap between connector endpoint and shape edge (px).
+ *                           Defaults to BOUND_ARROW_OFFSET. Pass `computeBindingGap(strokeWidth)`
+ *                           for a preview that matches the final binding gap.
+ * @param prevIsPrecise      Previous snap's `isPrecise` value for hysteresis.
+ *                           Pass `undefined` for first call (no hysteresis).
+ *                           Pass the previous result's `isPrecise` during drag
+ *                           to prevent edge/center mode flickering at boundary.
+ */
+export declare function findNearestSnapTarget(pos: Point, elements: CanvasElement[], edgeOuterThreshold?: number, excludeIds?: Set<string>, toward?: Point, forcePrecise?: boolean, gap?: number, prevIsPrecise?: boolean): SnapTarget | null;
+/** Check if a line/arrow element has any bindings */
+export declare function hasBinding(el: LineElement | ArrowElement): boolean;
+/**
+ * Recompute start/end points for a bound line/arrow based on current
+ * positions of the connected shapes. Called when a shape is dragged.
+ *
+ * Supports N-point connectors: only the first and last point pairs are
+ * adjusted to follow bindings; intermediate waypoints are preserved.
+ *
+ * Uses a two-pass approach for double-bound connectors to resolve the
+ * edge-point interdependency:
+ * 1. First pass: compute rough edge points using shape centers as direction.
+ * 2. Second pass: refine using the result from pass 1 as direction.
+ *
+ * Also respects `isPrecise`: when false, uses center as anchor direction;
+ * when true, uses the fixedPoint on the shape's bbox.
+ *
+ * Returns the updated `x`, `y`, `points` values to merge into the element.
+ */
+export declare function recomputeBoundPoints(connector: LineElement | ArrowElement, allElements: CanvasElement[]): Partial<LineElement | ArrowElement> | null;
+/**
+ * Find all connector (line/arrow) elements that reference `elementId`
+ * in their startBinding or endBinding.
+ */
+export declare function findConnectorsForElement(elementId: string, elements: CanvasElement[]): (LineElement | ArrowElement)[];
+/**
+ * Clear any binding that references a deleted element.
+ * Also clears boundElements references on remaining shapes.
+ * Returns updated elements array (only changed elements are cloned).
+ */
+export declare function clearBindingsForDeletedElements(deletedIds: Set<string>, elements: CanvasElement[]): CanvasElement[];
+/**
+ * Add a bound-element reference to a shape's boundElements array.
+ * Returns the updated shape — does NOT mutate in place.
+ */
+export declare function addBoundElement(shape: CanvasElement, ref: BoundElement): CanvasElement;
+/**
+ * Remove a bound-element reference from a shape's boundElements array.
+ * Returns the updated shape — does NOT mutate in place.
+ */
+export declare function removeBoundElement(shape: CanvasElement, refId: string): CanvasElement;
+/**
+ * Synchronize bidirectional boundElements when a connector's bindings change.
+ * Call this after updating a connector's startBinding / endBinding.
+ *
+ * @param connectorId  The connector (arrow/line) id
+ * @param connectorType  'arrow' | 'line'
+ * @param oldBinding   Previous binding (or null)
+ * @param newBinding   New binding (or null)
+ * @param updateElement Callback to persist the shape update
+ */
+export declare function syncBoundElements(connectorId: string, connectorType: 'arrow' | 'line', oldBinding: Binding | null, newBinding: Binding | null, elements: CanvasElement[], updateElement: (id: string, updates: Partial<CanvasElement>) => void): void;

package/dist/utils/crdtPrep.d.ts

@@ -0,0 +1,97 @@
+import { CanvasElement, CanvasOperation, ElementStyle } from '../types';
+/**
+ * Timestamped operation entry for the operation log.
+ * The operation log is an append-only list that can be shared
+ * across replicas for CRDT synchronization.
+ */
+export interface OperationEntry {
+    /** Unique operation ID (for deduplication across replicas) */
+    id: string;
+    /** The operation itself */
+    operation: CanvasOperation;
+    /** Unix timestamp (ms) when the operation was created */
+    timestamp: number;
+    /** ID of the user/client that created this operation */
+    clientId: string;
+}
+/**
+ * Operation log — append-only list of operations.
+ * In a full CRDT implementation, this would be synced via Yjs or similar.
+ */
+export declare class OperationLog {
+    private _entries;
+    private _maxEntries;
+    constructor(maxEntries?: number);
+    /** Append an operation to the log */
+    push(entry: OperationEntry): void;
+    /** Get all entries (read-only) */
+    get entries(): readonly OperationEntry[];
+    /** Get entries since a specific timestamp */
+    entriesSince(timestamp: number): OperationEntry[];
+    /** Get entries by client ID */
+    entriesByClient(clientId: string): OperationEntry[];
+    /** Clear all entries */
+    clear(): void;
+    /** Number of entries */
+    get length(): number;
+}
+/**
+ * Create an 'add' operation for a new element.
+ */
+export declare function opAdd(element: CanvasElement): CanvasOperation;
+/**
+ * Create a 'delete' operation.
+ */
+export declare function opDelete(elementId: string): CanvasOperation;
+/**
+ * Create a 'move' operation (delta-based for commutativity).
+ */
+export declare function opMove(elementId: string, dx: number, dy: number): CanvasOperation;
+/**
+ * Create a 'resize' operation.
+ */
+export declare function opResize(elementId: string, width: number, height: number, x?: number, y?: number): CanvasOperation;
+/**
+ * Create a 'style' operation (partial style update).
+ */
+export declare function opStyle(elementId: string, changes: Partial<ElementStyle>): CanvasOperation;
+/**
+ * Create a 'rotate' operation.
+ */
+export declare function opRotate(elementId: string, rotation: number): CanvasOperation;
+/**
+ * Create a 'reorder' operation (z-order change via fractional index).
+ */
+export declare function opReorder(elementId: string, sortOrder: string): CanvasOperation;
+/**
+ * Create an 'updatePoints' operation (for line/arrow/freedraw).
+ */
+export declare function opUpdatePoints(elementId: string, points: number[]): CanvasOperation;
+/**
+ * Create a 'setText' operation (for text elements).
+ */
+export declare function opSetText(elementId: string, text: string): CanvasOperation;
+/**
+ * Create a batch operation (group multiple ops into one transaction).
+ */
+export declare function opBatch(...operations: CanvasOperation[]): CanvasOperation;
+/**
+ * Apply a single operation to an elements array.
+ * Returns a new array (immutable — does not mutate input).
+ *
+ * This is the foundation for:
+ *   - Replaying operation logs
+ *   - Applying remote operations in CRDT sync
+ *   - Undo/redo via inverse operations
+ */
+export declare function applyOperation(elements: CanvasElement[], op: CanvasOperation): CanvasElement[];
+/**
+ * Detect what operations occurred between two element states.
+ * Useful for converting imperative store mutations into operations
+ * (bridge between current Zustand pattern and CRDT operations).
+ *
+ * @param before - Elements before the change
+ * @param after - Elements after the change
+ * @returns Array of operations that transform `before` into `after`
+ */
+export declare function detectOperations(before: CanvasElement[], after: CanvasElement[]): CanvasOperation[];

package/dist/utils/curve.d.ts

@@ -0,0 +1,51 @@
+import { Point } from '../types';
+/** Perpendicular offset as a fraction of the start→end distance */
+export declare const CURVE_RATIO = 0.2;
+/**
+ * Compute the quadratic Bézier control point for a curved line
+ * defined by start and end points.
+ *
+ * The control point sits at the midpoint of start→end, offset
+ * perpendicularly by `ratio × distance(start, end)`.
+ * Positive ratio = offset to the left (looking from start to end).
+ */
+export declare function computeCurveControlPoint(start: Point, end: Point, ratio?: number): Point;
+/**
+ * Evaluate a quadratic Bézier at parameter t ∈ [0, 1].
+ *   B(t) = (1-t)² P₀ + 2(1-t)t P₁ + t² P₂
+ */
+export declare function quadBezierAt(p0: Point, cp: Point, p2: Point, t: number): Point;
+/**
+ * Compute the tangent (derivative) of a quadratic Bézier at parameter t.
+ *   B'(t) = 2(1-t)(P₁ - P₀) + 2t(P₂ - P₁)
+ * Returns a non-normalized direction vector.
+ */
+export declare function quadBezierTangent(p0: Point, cp: Point, p2: Point, t: number): Point;
+/**
+ * Draw a quadratic Bézier curve path on a canvas 2D context.
+ * Does NOT call stroke() — caller decides stroke/fill.
+ */
+export declare function drawQuadBezierPath(ctx: CanvasRenderingContext2D | {
+    beginPath: () => void;
+    moveTo: (x: number, y: number) => void;
+    quadraticCurveTo: (cpx: number, cpy: number, x: number, y: number) => void;
+}, start: Point, cp: Point, end: Point): void;
+/**
+ * Compute the "arriving direction" point for an arrowhead.
+ * For start arrowhead: direction is tangent at t=0 pointing inward (from curve toward start).
+ * For end arrowhead: direction is tangent at t=1 pointing inward (from curve toward end).
+ *
+ * Returns the "previous" point that drawArrowhead expects — i.e.
+ * a point offset along the tangent away from the tip.
+ */
+export declare function curveArrowPrev(start: Point, cp: Point, end: Point, atEnd: boolean): Point;
+/**
+ * Compute the curvature ratio from a dragged control point position.
+ *
+ * Given the start/end endpoints of the line and the world position where
+ * the user has dragged the curve handle, computes the signed perpendicular
+ * offset ratio (curvature) that reproduces that position.
+ *
+ * Positive = left side (looking from start → end), negative = right side.
+ */
+export declare function curvatureFromDragPoint(start: Point, end: Point, dragWorld: Point): number;