f1ow 1.0.0 → 1.1.1

package/dist/hooks/useFlowAnimation.d.ts

@@ -0,0 +1,8 @@
+import { default as Konva } from 'konva';
+/**
+ * Animate dashOffset on a Konva node to create a "flowing" dash effect.
+ * @param nodeRef - React ref to a Konva Line or Shape node
+ * @param enabled - whether animation is active
+ * @param speed - pixels per second (default 40)
+ */
+export declare function useFlowAnimation(nodeRef: React.RefObject<Konva.Line | Konva.Shape | null>, enabled: boolean, speed?: number): void;

package/dist/lib/FlowCanvasProps.d.ts

@@ -1,8 +1,9 @@
-import { CanvasElement, ElementStyle, ToolType } from '../types';
+import { CanvasElement, ElementStyle, ToolType, ConnectionConfig } from '../types';
 import { ContextMenuItem } from '../components/ContextMenu/ContextMenu';
 import { CollaborationConfig } from '../collaboration/types';
 import { CustomElementConfig } from '../utils/elementRegistry';
 import { RenderAnnotationFn } from '../components/Canvas/AnnotationsOverlay';
+import { CanvasStore } from '../store/useCanvasStore';
 export type { ContextMenuItem };
 /** Context passed to custom context menu renderers */
 export interface ContextMenuContext {
@@ -122,6 +123,19 @@ export interface FlowCanvasProps {
      * Pass a `CollaborationConfig` to connect, or `undefined`/`null` to disable.
      */
     collaboration?: CollaborationConfig | null;
+    /**
+     * Optional canvas store instance produced by `createCanvasStore()`.
+     * When supplied, this `<FlowCanvas>` and its descendant React
+     * subscribers (Toolbar, StylePanel, overlays) read state from this
+     * isolated store instead of the module-level singleton, allowing
+     * multiple canvases to coexist on the same page without cross-talk.
+     *
+     * Note: tools, keyboard shortcuts, and the collaboration sync bridge
+     * still read from the singleton via `getState()`. Until that wiring
+     * is migrated, those subsystems target the singleton even when this
+     * prop is supplied.
+     */
+    store?: CanvasStore;
     /**
      * Register custom element types for this canvas instance.
      *
@@ -143,6 +157,22 @@ export interface FlowCanvasProps {
      * ```
      */
     customElementTypes?: CustomElementConfig[];
+    /**
+     * Configure the connection/binding system behavior.
+     * Controls snap thresholds, port visibility, default line styles, and more.
+     *
+     * @example
+     * ```tsx
+     * <FlowCanvas
+     *   connectionConfig={{
+     *     enablePorts: true,
+     *     snapThreshold: 20,
+     *     defaultLineType: 'elbow',
+     *   }}
+     * />
+     * ```
+     */
+    connectionConfig?: ConnectionConfig;
     /**
      * Configure Web Workers for background processing (elbow routing, SVG export).
      *

package/dist/lib/collaboration.d.ts

@@ -0,0 +1,10 @@
+export type { CollaborationUser, AwarenessState, CollaborationConfig, ConnectionStatus, CollaborationEvent, } from '../collaboration/types';
+export { createCollaborationProvider, destroyCollaborationProvider, getYDoc, getYProvider, getYElements, isCollaborationActive, onStatusChange, updateAwareness, getRemoteAwareness, } from '../collaboration/yjsProvider';
+export { startSync, stopSync } from '../collaboration/syncBridge';
+export { elementToYMap, yMapToElement, SYNC_FIELDS, STYLE_FIELDS } from '../collaboration/syncBridgeCodec';
+export { CollaborationManager } from '../collaboration/CollaborationManager';
+export { SyncWorkerAdapter } from '../collaboration/syncWorker';
+export type { WorkerInMessage, WorkerOutMessage, SyncWorkerCallbacks } from '../collaboration/syncWorker';
+export { useCollaboration } from '../collaboration/useCollaboration';
+export type { UseCollaborationReturn } from '../collaboration/useCollaboration';
+export { default as CursorOverlay } from '../collaboration/CursorOverlay';

package/dist/lib/index.d.ts

@@ -2,20 +2,23 @@ export { default as FlowCanvas } from './FlowCanvas';
 export type { FlowCanvasProps, FlowCanvasRef, FlowCanvasTheme, ContextMenuItem, ContextMenuContext, } from './FlowCanvasProps';
 export { DEFAULT_THEME } from './FlowCanvasProps';
 export type { AnnotationContext, AnnotationScreenBounds, RenderAnnotationFn, } from '../components/Canvas/AnnotationsOverlay';
-export type { CanvasElement, RectangleElement, EllipseElement, DiamondElement, LineElement, ArrowElement, FreeDrawElement, TextElement, ImageElement, BaseElement, ElementStyle, ElementType, ToolType, Point, ViewportState, ConnectionAnchor, BoundElement, Binding, SnapTarget, Arrowhead, LineType, TextAlign, VerticalAlign, ImageScaleMode, ImageCrop, ElementMeta, CanvasOperation, } from '../types';
-export { useCanvasStore } from '../store/useCanvasStore';
+export type { CanvasElement, RectangleElement, EllipseElement, DiamondElement, LineElement, ArrowElement, FreeDrawElement, TextElement, ImageElement, BaseElement, ElementStyle, ElementType, ToolType, Point, ViewportState, ConnectionAnchor, BoundElement, Binding, SnapTarget, Arrowhead, LineType, TextAlign, VerticalAlign, ImageScaleMode, ImageCrop, ElementMeta, CanvasOperation, AnchorId, Port, SnapMode, LineGradient, LineTaper, LineStyleExtension, ConnectionConfig, } from '../types';
+export { useCanvasStore, createCanvasStore } from '../store/useCanvasStore';
+export type { CanvasStore } from '../store/useCanvasStore';
+export { CanvasStoreProvider, useCanvasStoreInstance } from '../store/CanvasStoreContext';
+export type { CanvasStoreProviderProps } from '../store/CanvasStoreContext';
 export { DEFAULT_STYLE, STROKE_COLORS, FILL_COLORS, STROKE_WIDTHS, TOOLS, ARROWHEAD_TYPES, LINE_TYPES, ROUGHNESS_CONFIGS } from '../constants';
 export { generateId } from '../utils/id';
 export { distance, normalizeRect, rotatePoint, isPointInRect, getDiamondPoints, getStrokeDash } from '../utils/geometry';
 export { exportToDataURL, downloadPNG, exportToJSON, downloadJSON, exportToSVG, downloadSVG } from '../utils/export';
 export { drawArrowhead, arrowheadSize, flatToPoints } from '../utils/arrowheads';
 export { computeCurveControlPoint, quadBezierAt, quadBezierTangent, curveArrowPrev, CURVE_RATIO } from '../utils/curve';
+export { anchorToFixedPoint, fixedPointToAnchor, resolvePort, resolveBindingPoint, createBindingFromSnap, isBindingStale, findNearestSnapTarget, recomputeBoundPoints, computeFixedPoint, getEdgePointFromFixedPoint, isConnectable, getConnectionPoints, getEdgePoint, getAnchorPosition, findConnectorsForElement, addBoundElement, removeBoundElement, syncBoundElements, } from '../utils/connection';
 export { LABEL_PADDING_H, LABEL_PADDING_V, LABEL_CORNER, LABEL_LINE_HEIGHT, LABEL_MIN_WIDTH, measureLabelText, computePillSize } from '../utils/labelMetrics';
 export { elementRegistry, registerCustomElement } from '../utils/elementRegistry';
 export type { CustomElementConfig, ValidationResult } from '../utils/elementRegistry';
 export { computeElbowPoints, computeElbowRoute, simplifyElbowPath, clearElbowRouteCache, directionFromFixedPoint, directionFromPoints, directionFromShapeToPoint, directionFromEdgePoint, getElbowPreferredDirection, } from '../utils/elbow';
 export type { Direction } from '../utils/elbow';
-export { getConnectionPoints, getEdgePoint, getEdgePointFromFixedPoint, computeFixedPoint, getAnchorPosition, findNearestSnapTarget, isConnectable, recomputeBoundPoints, findConnectorsForElement, addBoundElement, removeBoundElement, syncBoundElements, } from '../utils/connection';
 export { fileToDataURL, loadImage, computeImageElementDimensions, createImageElement, getImageFilesFromDataTransfer, extractImageDataFromClipboard, clipboardHasImage, resolveImageSource, openImageFilePicker, } from '../utils/image';
 export { getVisibleBounds, getElementAABB, aabbOverlaps, cullToViewport, buildElementMap, cloneElementsForHistory, rafThrottle, batchElementUpdates, } from '../utils/performance';
 export type { AABB } from '../utils/performance';
@@ -41,19 +44,13 @@ export { generateKeyBetween, generateNKeysBetween, isValidFractionalIndex, compa
 export { OperationLog, opAdd, opDelete, opMove, opResize, opStyle, opRotate, opReorder, opUpdatePoints, opSetText, opBatch, applyOperation, detectOperations, } from '../utils/crdtPrep';
 export type { OperationEntry } from '../utils/crdtPrep';
 export type { CollaborationUser, AwarenessState, CollaborationConfig, ConnectionStatus, CollaborationEvent, } from '../collaboration/types';
-export { createCollaborationProvider, destroyCollaborationProvider, getYDoc, getYProvider, getYElements, isCollaborationActive, onStatusChange, updateAwareness, getRemoteAwareness, } from '../collaboration/yjsProvider';
-export { startSync, stopSync } from '../collaboration/syncBridge';
-export { elementToYMap, yMapToElement, SYNC_FIELDS, STYLE_FIELDS } from '../collaboration/syncBridgeCodec';
-export { CollaborationManager } from '../collaboration/CollaborationManager';
-export { SyncWorkerAdapter } from '../collaboration/syncWorker';
-export type { WorkerInMessage, WorkerOutMessage, SyncWorkerCallbacks } from '../collaboration/syncWorker';
 export { useCollaboration } from '../collaboration/useCollaboration';
 export type { UseCollaborationReturn } from '../collaboration/useCollaboration';
 export { default as CursorOverlay } from '../collaboration/CursorOverlay';
 export { TileCache, tileKey } from '../rendering/tileCache';
 export type { TileCoord } from '../rendering/tileCache';
 export { TileRenderer, TILE_SIZE, discreteZoom, worldTileSize, getVisibleTiles, tileBounds, getElementTiles, } from '../rendering/tileRenderer';
-export type { TileDrawFn, TileRendererOptions } from '../rendering/tileRenderer';
+export type { TileDrawFn, TileRendererOptions, TileSpatialQuery } from '../rendering/tileRenderer';
 export { useTileRenderer } from '../rendering/useTileRenderer';
 export type { UseTileRendererOptions, UseTileRendererReturn } from '../rendering/useTileRenderer';
 export { TextureAtlas } from '../webgl/textureAtlas';

package/dist/store/CanvasStoreContext.d.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from 'react';
+import { CanvasStore } from './useCanvasStore';
+export interface CanvasStoreProviderProps {
+    /** Store instance produced by `createCanvasStore()`. */
+    store: CanvasStore;
+    children: ReactNode;
+}
+export declare function CanvasStoreProvider({ store, children }: CanvasStoreProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Resolve the canvas store for the current React subtree. Falls back to
+ * the singleton `useCanvasStore` when no provider is mounted, so existing
+ * single-instance apps work without changes.
+ */
+export declare function useCanvasStoreInstance(): CanvasStore;

package/dist/store/useCanvasStore.d.ts

@@ -15,11 +15,17 @@ interface ElementDiff {
  */
 interface HistoryEntry {
     diffs: ElementDiff[];
+    /** Element order before this entry, used to restore z-order changes. */
+    beforeOrder?: string[];
+    /** Element order after this entry, used to redo z-order changes. */
+    afterOrder?: string[];
     /** Optional named mark/checkpoint for grouping */
     mark?: string;
     /** Timestamp for squash heuristics */
     timestamp: number;
 }
+type AlignMode = 'left' | 'centerH' | 'right' | 'top' | 'centerV' | 'bottom';
+type FlipAxis = 'horizontal' | 'vertical';
 interface CanvasState {
     elements: CanvasElement[];
     selectedIds: string[];
@@ -35,6 +41,8 @@ interface CanvasState {
     historyIndex: number;
     /** Baseline snapshot for computing diffs against current state */
     _historyBaseline: Map<string, CanvasElement>;
+    /** Baseline element order for z-order history. */
+    _historyOrderBaseline: string[];
     /** Whether history recording is temporarily paused */
     _historyPaused: boolean;
     showGrid: boolean;
@@ -55,6 +63,9 @@ interface CanvasState {
     sendToBack: (ids: string[]) => void;
     bringForward: (ids: string[]) => void;
     sendBackward: (ids: string[]) => void;
+    alignElements: (ids: string[], mode: AlignMode) => void;
+    rotateElements: (ids: string[], deltaDegrees: number) => void;
+    flipElements: (ids: string[], axis: FlipAxis) => void;
     toggleLockElements: (ids: string[]) => void;
     groupElements: (ids: string[]) => void;
     ungroupElements: (ids: string[]) => void;
@@ -123,5 +134,26 @@ interface CanvasState {
     canRedo: () => boolean;
     toggleGrid: () => void;
 }
+/**
+ * Factory: create a fresh canvas store instance.
+ *
+ * Each call returns an independent Zustand store with its own elements,
+ * selection, viewport, and history. Use this with `CanvasStoreProvider`
+ * to render multiple `<FlowCanvas>` instances side-by-side without state
+ * cross-talk on the React subscriber side.
+ *
+ * Note: the module-level `useCanvasStore` singleton remains exported for
+ * backward compatibility and is still used by tools, hooks, and the
+ * collaboration sync bridge that read state via `getState()`. Full
+ * multi-instance isolation across those subsystems is a follow-up phase.
+ */
+export type CanvasStore = ReturnType<typeof createCanvasStore>;
+export declare function createCanvasStore(): import('zustand').UseBoundStore<import('zustand').StoreApi<CanvasState>>;
+/**
+ * Default singleton store. Used by tools, hooks, and the collaboration sync
+ * bridge that read state via `getState()`. Most apps render a single
+ * `<FlowCanvas>` per page, in which case this singleton is what the
+ * `CanvasStoreProvider` exposes.
+ */
 export declare const useCanvasStore: import('zustand').UseBoundStore<import('zustand').StoreApi<CanvasState>>;
 export {};

package/dist/syncBridge-BBEfPdNb.js

@@ -0,0 +1,254 @@
+import * as A from "yjs";
+import { useCanvasStore as w } from "./f1ow.js";
+import { getYElements as _, getYDoc as W } from "./yjsProvider-CXmqUJXr.js";
+const R = [
+  "id",
+  "type",
+  "x",
+  "y",
+  "width",
+  "height",
+  "rotation",
+  "isLocked",
+  "isVisible",
+  "sortOrder",
+  "version"
+], T = [
+  "strokeColor",
+  "fillColor",
+  "strokeWidth",
+  "opacity",
+  "strokeStyle",
+  "roughness",
+  "fontSize",
+  "fontFamily"
+];
+function B(t, e) {
+  const s = t;
+  for (const i of R) {
+    const r = s[i];
+    r !== void 0 && e.set(i, r);
+  }
+  if (t.style)
+    for (const i of T)
+      e.set(`style.${i}`, t.style[i]);
+  switch (t.boundElements ? e.set("boundElements", JSON.stringify(t.boundElements)) : e.set("boundElements", null), t.ports && e.set("ports", JSON.stringify(t.ports)), "lineStyle" in t && t.lineStyle && e.set("lineStyle", JSON.stringify(t.lineStyle)), t.ports && e.set("ports", JSON.stringify(t.ports)), "lineStyle" in t && t.lineStyle && e.set("lineStyle", JSON.stringify(t.lineStyle)), t.groupIds && e.set("groupIds", JSON.stringify(t.groupIds)), t.type) {
+    case "rectangle":
+      e.set("cornerRadius", t.cornerRadius);
+      break;
+    case "line":
+    case "arrow":
+      e.set("points", JSON.stringify(t.points)), e.set("lineType", t.lineType), t.curvature !== void 0 && e.set("curvature", t.curvature), e.set("startBinding", t.startBinding ? JSON.stringify(t.startBinding) : null), e.set("endBinding", t.endBinding ? JSON.stringify(t.endBinding) : null), t.type === "arrow" && (e.set("startArrowhead", t.startArrowhead), e.set("endArrowhead", t.endArrowhead));
+      break;
+    case "freedraw":
+      e.set("points", JSON.stringify(t.points));
+      break;
+    case "text":
+      e.set("text", t.text), e.set("containerId", t.containerId), e.set("textAlign", t.textAlign), e.set("verticalAlign", t.verticalAlign);
+      break;
+    case "image":
+      e.set("src", t.src), e.set("naturalWidth", t.naturalWidth), e.set("naturalHeight", t.naturalHeight), e.set("scaleMode", t.scaleMode), e.set("crop", t.crop ? JSON.stringify(t.crop) : null), e.set("cornerRadius", t.cornerRadius), e.set("alt", t.alt);
+      break;
+  }
+}
+function E(t) {
+  const e = t.get("type"), s = t.get("id");
+  if (!e || !s) return null;
+  const i = {};
+  for (const n of T) {
+    const h = t.get(`style.${n}`);
+    h !== void 0 && (i[n] = h);
+  }
+  const r = {
+    id: s,
+    type: e,
+    x: t.get("x") ?? 0,
+    y: t.get("y") ?? 0,
+    width: t.get("width") ?? 100,
+    height: t.get("height") ?? 100,
+    rotation: t.get("rotation") ?? 0,
+    isLocked: t.get("isLocked") ?? !1,
+    isVisible: t.get("isVisible") ?? !0,
+    version: t.get("version") ?? 0,
+    style: i,
+    boundElements: u(t.get("boundElements")) ?? null,
+    groupIds: u(t.get("groupIds")) ?? void 0,
+    sortOrder: t.get("sortOrder") ?? void 0,
+    ports: u(t.get("ports")) ?? void 0
+  };
+  switch (e) {
+    case "rectangle":
+      r.cornerRadius = t.get("cornerRadius") ?? 0;
+      break;
+    case "line":
+    case "arrow":
+      r.points = u(t.get("points")) ?? [0, 0, 100, 0], r.lineType = t.get("lineType") ?? "sharp", r.curvature = t.get("curvature") ?? void 0, r.startBinding = u(t.get("startBinding")), r.endBinding = u(t.get("endBinding")), e === "arrow" && (r.startArrowhead = t.get("startArrowhead") ?? null, r.endArrowhead = t.get("endArrowhead") ?? "arrow");
+      {
+        const n = u(t.get("lineStyle"));
+        n && (r.lineStyle = n);
+      }
+      break;
+    case "freedraw":
+      r.points = u(t.get("points")) ?? [];
+      break;
+    case "text":
+      r.text = t.get("text") ?? "", r.containerId = t.get("containerId") ?? null, r.textAlign = t.get("textAlign") ?? "center", r.verticalAlign = t.get("verticalAlign") ?? "middle";
+      break;
+    case "image":
+      r.src = t.get("src") ?? "", r.naturalWidth = t.get("naturalWidth") ?? 0, r.naturalHeight = t.get("naturalHeight") ?? 0, r.scaleMode = t.get("scaleMode") ?? "fit", r.crop = u(t.get("crop")) ?? null, r.cornerRadius = t.get("cornerRadius") ?? 0, r.alt = t.get("alt") ?? "";
+      break;
+  }
+  return r;
+}
+function u(t) {
+  if (t == null) return null;
+  try {
+    return JSON.parse(t);
+  } catch {
+    return null;
+  }
+}
+let m = !1, S = !1, x = null, J = null, O = null, a = [];
+function $(t = 50) {
+  const e = W(), s = _();
+  if (!e || !s)
+    return;
+  if (H(), s.size > 0) {
+    m = !0;
+    const o = C(s);
+    w.getState().setElements(o), a = o, m = !1;
+  } else {
+    const o = w.getState().elements;
+    o.length > 0 && (S = !0, e.transact(() => {
+      for (const l of o) {
+        const c = new A.Map();
+        B(l, c), s.set(l.id, c);
+      }
+    }, "local-init"), S = !1), a = o;
+  }
+  const i = (o, l) => {
+    if (l.origin === "local-sync" || l.origin === "local-init" || S) return;
+    m = !0;
+    const c = w.getState();
+    let d = [...a], v = !1;
+    for (const [f, g] of o.keys)
+      if (g.action === "add" || g.action === "update") {
+        const b = s.get(f);
+        if (b) {
+          const k = E(b);
+          if (k) {
+            const N = d.findIndex((I) => I.id === f);
+            N >= 0 ? d[N] = k : d.push(k), v = !0;
+          }
+        }
+      } else g.action === "delete" && (d = d.filter((b) => b.id !== f), v = !0);
+    v && (d.sort((f, g) => f.sortOrder && g.sortOrder ? f.sortOrder < g.sortOrder ? -1 : f.sortOrder > g.sortOrder ? 1 : 0 : 0), c.setElements(d), a = d), m = !1;
+  };
+  let r = null;
+  const n = /* @__PURE__ */ new Set(), h = (o) => {
+    if (!S) {
+      for (const l of o) {
+        let c = l.target;
+        for (; c && !(c instanceof A.Map && c.parent === s); )
+          c = c.parent;
+        if (c instanceof A.Map) {
+          const d = c.get("id");
+          d && n.add(d);
+        }
+      }
+      r && clearTimeout(r), r = setTimeout(() => {
+        if (n.size === 0 || S) return;
+        m = !0;
+        let l = [...a], c = !1;
+        for (const d of n) {
+          const v = s.get(d);
+          if (!v) continue;
+          const f = E(v);
+          if (!f) continue;
+          const g = l.findIndex((b) => b.id === d);
+          g >= 0 && (l[g] = f, c = !0);
+        }
+        n.clear(), c && (w.getState().setElements(l), a = l), m = !1;
+      }, 16);
+    }
+  };
+  s.observe(i), s.observeDeep(h), J = () => {
+    s.unobserve(i), s.unobserveDeep(h), r && clearTimeout(r), n.clear();
+  }, x = w.subscribe(
+    (o) => {
+      m || o.elements !== a && (O && clearTimeout(O), O = setTimeout(() => {
+        L(o.elements, s, e);
+      }, t));
+    }
+  );
+}
+function H() {
+  x && (x(), x = null), J && (J(), J = null), O && (clearTimeout(O), O = null), a = [];
+}
+function L(t, e, s) {
+  S = !0, a = t;
+  const i = /* @__PURE__ */ new Map();
+  for (const r of t)
+    i.set(r.id, r);
+  s.transact(() => {
+    for (const [r] of e.entries())
+      i.has(r) || e.delete(r);
+    for (const r of t) {
+      let n = e.get(r.id);
+      n ? Y(r, n) : (n = new A.Map(), B(r, n), e.set(r.id, n));
+    }
+  }, "local-sync"), S = !1;
+}
+function Y(t, e) {
+  const s = t;
+  for (const r of R) {
+    const n = s[r];
+    n !== e.get(r) && e.set(r, n);
+  }
+  if (t.style)
+    for (const r of T) {
+      const n = t.style[r];
+      n !== e.get(`style.${r}`) && e.set(`style.${r}`, n);
+    }
+  const i = t.boundElements ? JSON.stringify(t.boundElements) : null;
+  switch (i !== e.get("boundElements") && e.set("boundElements", i), t.type) {
+    case "rectangle":
+      t.cornerRadius !== e.get("cornerRadius") && e.set("cornerRadius", t.cornerRadius);
+      break;
+    case "line":
+    case "arrow": {
+      const n = JSON.stringify(t.points);
+      n !== e.get("points") && e.set("points", n), t.lineType !== e.get("lineType") && e.set("lineType", t.lineType), t.curvature !== e.get("curvature") && e.set("curvature", t.curvature);
+      const h = t.startBinding ? JSON.stringify(t.startBinding) : null;
+      h !== e.get("startBinding") && e.set("startBinding", h);
+      const o = t.endBinding ? JSON.stringify(t.endBinding) : null;
+      o !== e.get("endBinding") && e.set("endBinding", o), t.type === "arrow" && (t.startArrowhead !== e.get("startArrowhead") && e.set("startArrowhead", t.startArrowhead), t.endArrowhead !== e.get("endArrowhead") && e.set("endArrowhead", t.endArrowhead));
+      break;
+    }
+    case "freedraw": {
+      const n = JSON.stringify(t.points);
+      n !== e.get("points") && e.set("points", n);
+      break;
+    }
+    case "text":
+      t.text !== e.get("text") && e.set("text", t.text), t.containerId !== e.get("containerId") && e.set("containerId", t.containerId), t.textAlign !== e.get("textAlign") && e.set("textAlign", t.textAlign), t.verticalAlign !== e.get("verticalAlign") && e.set("verticalAlign", t.verticalAlign);
+      break;
+    case "image":
+      t.src !== e.get("src") && e.set("src", t.src), t.naturalWidth !== e.get("naturalWidth") && e.set("naturalWidth", t.naturalWidth), t.naturalHeight !== e.get("naturalHeight") && e.set("naturalHeight", t.naturalHeight), t.scaleMode !== e.get("scaleMode") && e.set("scaleMode", t.scaleMode);
+      const r = t.crop ? JSON.stringify(t.crop) : null;
+      r !== e.get("crop") && e.set("crop", r), t.cornerRadius !== e.get("cornerRadius") && e.set("cornerRadius", t.cornerRadius), t.alt !== e.get("alt") && e.set("alt", t.alt);
+      break;
+  }
+}
+function C(t) {
+  const e = [];
+  for (const [, s] of t.entries()) {
+    const i = E(s);
+    i && e.push(i);
+  }
+  return e.sort((s, i) => s.sortOrder && i.sortOrder ? s.sortOrder < i.sortOrder ? -1 : s.sortOrder > i.sortOrder ? 1 : 0 : 0), e;
+}
+export {
+  $ as startSync,
+  H as stopSync
+};

package/dist/types/index.d.ts

@@ -2,6 +2,27 @@ export type ToolType = 'select' | 'hand' | 'rectangle' | 'ellipse' | 'diamond' |
 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';
+/** Gradient definition for connector strokes */
+export interface LineGradient {
+    /** Color stops: [offset (0-1), cssColor] */
+    stops: [number, string][];
+    /** Gradient follows the path direction */
+    type: 'along-path';
+}
+/** Tapered stroke: width varies from start to end */
+export interface LineTaper {
+    startWidth: number;
+    endWidth: number;
+}
+/** Extended line style options for connectors */
+export interface LineStyleExtension {
+    /** Gradient stroke along the connector path */
+    gradient?: LineGradient;
+    /** Tapered stroke width */
+    taper?: LineTaper;
+    /** Animated flow direction indicator (dash animation) */
+    flowAnimation?: boolean;
+}
 export type FreehandStyle = 'standard' | 'pen' | 'brush' | 'pencil';
 export interface ElementStyle {
     strokeColor: string;
@@ -27,6 +48,17 @@ export interface BaseElement {
     isVisible: boolean;
     /** Bidirectional refs: arrows/text bound to this element */
     boundElements: BoundElement[] | null;
+    /**
+     * Custom ports defined on this element instance.
+     * Used for architecture diagrams where shapes have named I/O points.
+     */
+    ports?: Port[];
+    /**
+     * Monotonic version counter — bumped on every geometry/port mutation.
+     * Used by binding system to detect stale worker results and cache invalidation.
+     * Auto-managed by the store; consumers should not set this directly.
+     */
+    version: number;
     /** Group hierarchy: element belongs to these groups (innermost first, outermost last) */
     groupIds?: string[];
     /**
@@ -123,6 +155,8 @@ export interface LineElement extends BaseElement {
     curvature?: number;
     startBinding: Binding | null;
     endBinding: Binding | null;
+    /** Extended line style (gradient, taper, animation) */
+    lineStyle?: LineStyleExtension;
 }
 export interface ArrowElement extends BaseElement {
     type: 'arrow';
@@ -141,6 +175,8 @@ export interface ArrowElement extends BaseElement {
     curvature?: number;
     startBinding: Binding | null;
     endBinding: Binding | null;
+    /** Extended line style (gradient, taper, animation) */
+    lineStyle?: LineStyleExtension;
 }
 export interface FreeDrawElement extends BaseElement {
     type: 'freedraw';
@@ -208,8 +244,23 @@ export interface SelectionBox {
     width: number;
     height: number;
 }
+/** Named anchor positions on a shape's bounding box (compass notation) */
+export type AnchorId = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw' | 'center' | 'auto';
+/** Custom port on an element — user-defined attachment point */
+export interface Port {
+    /** Unique port identifier within the element */
+    id: string;
+    /** Normalized [0-1, 0-1] position on the element's bounding box */
+    ratio: [number, number];
+    /** Optional display label for the port */
+    label?: string;
+    /** Optional preferred edge (used for elbow routing direction) */
+    edge?: AnchorId;
+}
+/** How the binding target was determined */
+export type SnapMode = 'anchor' | 'port' | 'edge' | 'center';
 /**
- * @deprecated Use fixedPoint binding instead. Kept for backward-compat exports.
+ * @deprecated Use AnchorId instead. Kept for backward-compat exports.
  */
 export type ConnectionAnchor = 'top' | 'bottom' | 'left' | 'right' | 'center';
 /** Bidirectional reference stored on shapes to track bound connectors/text */
@@ -221,13 +272,30 @@ export type BoundElement = {
 export interface Binding {
     /** The element this end is connected to */
     elementId: string;
+    /**
+     * Named anchor position. When set, takes precedence over fixedPoint.
+     * Resolves to a fixedPoint at bind time, but re-resolves after resize
+     * to maintain semantic meaning (e.g. "always top-center").
+     * 'auto' = let the system choose the nearest anchor.
+     */
+    anchor?: AnchorId;
+    /** Custom port ID. When set, takes precedence over anchor and fixedPoint. */
+    portId?: 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.
+     * Always populated — serves as resolved cache when anchor/port is set.
      */
     fixedPoint: [number, number];
     /** Gap between the edge of the shape and the arrow tip (px) */
     gap: number;
+    /** How the binding target was determined */
+    snapMode: SnapMode;
+    /**
+     * Version of the target element at bind time.
+     * Used to detect stale bindings (e.g. worker results arriving after element changed).
+     */
+    elementVersion: 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,
@@ -250,6 +318,12 @@ export interface SnapTarget {
      * - `false`: cursor is in the center zone → attaches to center for auto-routing
      */
     isPrecise: boolean;
+    /** Named anchor if snapped to a cardinal position */
+    anchor?: AnchorId;
+    /** Custom port ID if snapped to a port */
+    portId?: string;
+    /** How the snap target was determined */
+    snapMode: SnapMode;
 }
 /** State for editing individual points of a line/arrow element */
 export interface LinearEditState {
@@ -266,3 +340,25 @@ export interface LinearEditState {
     /** Whether a point is currently being dragged */
     isDraggingPoint: boolean;
 }
+/**
+ * Consumer-facing configuration for the connection/binding system.
+ * Pass via `FlowCanvasProps.connectionConfig`.
+ */
+export interface ConnectionConfig {
+    /** Distance outside shape perimeter to activate edge snap (px). Default: 24 */
+    snapThreshold?: number;
+    /** Hysteresis margin to prevent edge/center mode flickering (px). Default: 6 */
+    hysteresisMargin?: number;
+    /** Clearance around shapes for elbow routing (px). Default: adaptive */
+    elbowMargin?: number;
+    /** Hit radius for port dots (px, before zoom compensation). Default: 8 */
+    portHitRadius?: number;
+    /** Minimum stub length for elbow route endpoints (px). Default: 36 */
+    stubLength?: number;
+    /** Whether to render custom ports on shapes. Default: true */
+    enablePorts?: boolean;
+    /** Default line style extension applied to new connectors */
+    defaultLineStyle?: LineStyleExtension;
+    /** Default line type for new arrows/lines. Default: 'sharp' */
+    defaultLineType?: LineType;
+}

package/dist/utils/connection.d.ts

@@ -1,4 +1,4 @@
-import { CanvasElement, Point, ConnectionAnchor, Binding, SnapTarget, ArrowElement, LineElement, TextElement, BoundElement } from '../types';
+import { CanvasElement, Point, ConnectionAnchor, Binding, SnapTarget, ArrowElement, LineElement, TextElement, BoundElement, AnchorId, SnapMode } 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 */
@@ -7,6 +7,29 @@ export declare function getConnectionPoints(el: CanvasElement): Record<Connectio
  * @deprecated Use fixedPoint-based getEdgePointFromFixedPoint() instead.
  */
 export declare function getAnchorPosition(el: CanvasElement, anchor: ConnectionAnchor): Point;
+/** Map a named AnchorId to its fixedPoint ratio on the bounding box */
+export declare function anchorToFixedPoint(anchor: AnchorId): [number, number];
+/** Find the nearest cardinal AnchorId for a given fixedPoint */
+export declare function fixedPointToAnchor(fp: [number, number]): AnchorId;
+/** Resolve a port's ratio to a fixedPoint on an element */
+export declare function resolvePort(el: CanvasElement, portId: string): [number, number] | null;
+/**
+ * Resolve the effective fixedPoint for a binding, respecting priority:
+ * portId > anchor > fixedPoint.
+ *
+ * Returns the resolved fixedPoint and the effective snapMode.
+ */
+export declare function resolveBindingPoint(binding: Binding, element: CanvasElement): {
+    fixedPoint: [number, number];
+    snapMode: SnapMode;
+};
+/**
+ * Create a Binding from a SnapTarget result.
+ * Convenience helper for LinearTool and LinearElementHandles.
+ */
+export declare function createBindingFromSnap(snap: SnapTarget, gap: number, elementVersion: number): Binding;
+/** Check whether a binding's elementVersion matches the current element */
+export declare function isBindingStale(binding: Binding, element: CanvasElement): boolean;
 /**
  * Compute the appropriate gap between a connector and a shape edge,
  * based on both the connector's stroke width and a base offset.
@@ -21,8 +44,13 @@ export declare function computeFixedPoint(el: CanvasElement, worldPt: Point): [n
 /**
  * Convert a fixedPoint ratio back to a world-space target point,
  * then compute the edge intersection from center to that target.
+ *
+ * @param toward  Optional direction hint for center fixedPoint [0.5, 0.5].
+ *                When the fixedPoint is exactly center, there's no meaningful
+ *                direction — `toward` provides the other endpoint so we can
+ *                compute a stable edge exit. Without it, returns the element center.
  */
-export declare function getEdgePointFromFixedPoint(el: CanvasElement, fixedPoint: [number, number], gap?: number): Point;
+export declare function getEdgePointFromFixedPoint(el: CanvasElement, fixedPoint: [number, number], gap?: number, toward?: Point): Point;
 /**
  * Given a shape and an external world-space point, compute the point on
  * the shape's perimeter closest to `toward`.