@statelyai/flow-dom 3.1.0 → 3.2.0

package/dist/esm/index.d.ts

@@ -1,8 +1,64 @@
-import { FlowColorMode, FlowEngine, FlowInputEffects, FlowInputEvent, FlowStore, FlowStoreContext, Rect } from "@statelyai/flow";
+import { EdgePathData, FlowColorMode, FlowController, FlowEngine, FlowEntityChangeNotifierOptions, FlowInputEffects, FlowInputEvent, FlowResult, FlowStore, FlowStoreContext, Point, Rect } from "@statelyai/flow";
 export * from "@statelyai/flow";
-
+//#region src/clipboard.d.ts
+declare const FLOW_CONTENT_MIME = "application/vnd.stately.flow+json";
+type ClipboardTransport = {
+  writeText?: (value: string) => Promise<void>;
+  readText?: () => Promise<string>;
+  write?: (items: unknown[]) => Promise<void>;
+  read?: () => Promise<Array<{
+    types: readonly string[];
+    getType(type: string): Promise<Blob>;
+  }>>;
+};
+type FlowClipboard = {
+  copy: (targets?: Iterable<string>) => Promise<boolean>;
+  cut: (targets?: Iterable<string>) => Promise<boolean>;
+  paste: (options?: {
+    point?: Point;
+    preservePosition?: boolean;
+  }) => Promise<FlowResult<unknown, Error>>;
+};
+declare function createFlowClipboard(flow: FlowController, options?: {
+  clipboard?: ClipboardTransport;
+  ClipboardItem?: new (items: Record<string, Blob>) => unknown;
+}): FlowClipboard;
+//#endregion
+//#region src/exportImage.d.ts
+type FlowImageExportOptions = {
+  format?: 'svg' | 'png' | 'webp';
+  region?: 'graph' | 'viewport' | 'selection' | Rect;
+  padding?: number;
+  scale?: number;
+  pixelRatio?: number;
+  background?: string;
+  styles?: 'computed' | 'none';
+  include?: (element: Element) => boolean;
+  signal?: {
+    readonly aborted: boolean;
+    addEventListener(type: 'abort', listener: () => void, options?: {
+      once?: boolean;
+    }): void;
+  };
+};
+type FlowImageExportResult = {
+  blob: Blob;
+  width: number;
+  height: number;
+};
+type FlowView = {
+  exportImage: (options?: FlowImageExportOptions) => Promise<FlowImageExportResult>;
+  refreshMeasurements: (targets?: Iterable<string | Element>) => void;
+};
+declare function createFlowView(container: HTMLElement, options?: {
+  measurements?: MeasurementObserver;
+}): FlowView;
+declare function exportFlowImage(container: HTMLElement, options?: FlowImageExportOptions): Promise<FlowImageExportResult>;
+//#endregion
 //#region src/culling.d.ts
-
+type ComputeRenderableIdsOptions = {
+  overscan?: number;
+};
 /**
  * Node/edge ids worth mounting, or `null` meaning "render everything" — either
  * because culling is disabled, the viewport hasn't been measured yet, or the
@@ -40,7 +96,7 @@ declare function renderableIdsEqual(a: RenderableIds, b: RenderableIds): boolean
  * `getGraphBounds`/`getRenderableEntities` from the live store) — which holds
  * when called inside a store-subscription selector.
  */
-declare function computeRenderableIds(engine: FlowEngine, context: FlowStoreContext, enabled: boolean | undefined): RenderableIds;
+declare function computeRenderableIds(engine: FlowEngine, context: FlowStoreContext, enabled: boolean | undefined, options?: ComputeRenderableIdsOptions): RenderableIds;
 //#endregion
 //#region src/render-styles.d.ts
 type NodePositionStyle = {
@@ -83,6 +139,34 @@ type ViewportStyle = {
  */
 declare function viewportStyle(): ViewportStyle;
 //#endregion
+//#region src/entity-geometry.d.ts
+type EntityRectTarget = {
+  id: string;
+  getRect: () => Rect | null;
+  autoSize?: boolean;
+};
+type EntityEdgeTarget = {
+  id: string;
+  getPathData: () => EdgePathData | null;
+};
+type EntityGeometryObserverOptions = FlowEntityChangeNotifierOptions & {
+  requestFrame?: (callback: FrameRequestCallback) => number;
+  cancelFrame?: (handle: number) => void;
+};
+type EntityGeometryObserver = {
+  observeRect(element: HTMLElement, target: EntityRectTarget): () => void;
+  observeEdge(element: SVGElement, target: EntityEdgeTarget): () => void;
+  /** Flush pending writes synchronously. Primarily useful for deterministic hosts/tests. */
+  flush(): void;
+  disconnect(): void;
+};
+/**
+ * Batches transient entity geometry into imperative DOM writes. One core
+ * entity-change notifier keeps dispatch O(changed); framework adapters retain
+ * ownership of content, selection, and other durable rendering.
+ */
+declare function createEntityGeometryObserver(store: FlowStore, options?: EntityGeometryObserverOptions): EntityGeometryObserver;
+//#endregion
 //#region src/index.d.ts
 type ResolvedFlowColorMode = "light" | "dark";
 declare function resolveFlowColorMode(colorMode: FlowColorMode, targetWindow?: Pick<Window, "matchMedia"> | undefined): ResolvedFlowColorMode;
@@ -99,17 +183,25 @@ type MeasurementObserver = {
   observe(element: Element, target: MeasurementTarget): void;
   /** Re-measure now (position-only changes don't fire ResizeObserver). */
   measure(element: Element): void;
+  refresh(targets?: Iterable<string | Element>): void;
   unobserve(element: Element): void;
   disconnect(): void;
 };
 type MeasurementObserverOptions = {
   container?: Element | (() => Element | null | undefined) | null;
+  equalityThreshold?: number;
 };
 declare function createMeasurementObserver(store: FlowStore, options?: MeasurementObserverOptions): MeasurementObserver;
 /** The container element registered for this store via `attachContainer`. */
 declare function getAttachedContainer(store: FlowStore): Element | undefined;
+declare function clientToCanvas(store: FlowStore, point: Point, container?: Element | null | undefined): Point;
+declare function canvasToClient(store: FlowStore, point: Point, container?: Element | null | undefined): Point;
 declare function attachContainer(store: FlowStore, element: Element): () => void;
-declare function attachViewportTransform(store: FlowStore, element: HTMLElement): () => void;
+type ViewportTransformOptions = {
+  /** Idle delay (ms) before dropping the GPU-layer hint after interaction stops. */
+  promoteIdleMs?: number;
+};
+declare function attachViewportTransform(store: FlowStore, element: HTMLElement, options?: ViewportTransformOptions): () => void;
 type AttachInputOptions = {
   container: HTMLElement;
   store: FlowStore;
@@ -117,6 +209,11 @@ type AttachInputOptions = {
     send(event: FlowInputEvent): FlowInputEffects;
     cancelSession(): void;
   };
+  /**
+   * Where keyboard events are listened for. Defaults to the flow container so
+   * multiple flow instances do not all react to global Delete/undo/arrow keys.
+   */
+  keyboardTarget?: "window" | "container" | HTMLElement;
   /**
    * Auto-pan policy, evaluated once per animation frame while a gesture
    * session holds the pointer near the container edge. Pass
@@ -135,4 +232,4 @@ type AttachInputOptions = {
 };
 declare function attachInput(options: AttachInputOptions): () => void;
 //#endregion
-export { AttachInputOptions, MeasurementObserver, MeasurementObserverOptions, MeasurementTarget, type NodePositionStyle, type RenderableIds, ResolvedFlowColorMode, type ViewportStyle, applyFlowColorMode, attachContainer, attachInput, attachViewportTransform, computeRenderableIds, createMeasurementObserver, getAttachedContainer, nodePositionStyle, renderableIdsEqual, resolveFlowColorMode, viewportStyle };
+export { AttachInputOptions, type ClipboardTransport, type ComputeRenderableIdsOptions, type EntityEdgeTarget, type EntityGeometryObserver, type EntityGeometryObserverOptions, type EntityRectTarget, FLOW_CONTENT_MIME, type FlowClipboard, type FlowImageExportOptions, type FlowImageExportResult, type FlowView, MeasurementObserver, MeasurementObserverOptions, MeasurementTarget, type NodePositionStyle, type RenderableIds, ResolvedFlowColorMode, type ViewportStyle, ViewportTransformOptions, applyFlowColorMode, attachContainer, attachInput, attachViewportTransform, canvasToClient, clientToCanvas, computeRenderableIds, createEntityGeometryObserver, createFlowClipboard, createFlowView, createMeasurementObserver, exportFlowImage, getAttachedContainer, nodePositionStyle, renderableIdsEqual, resolveFlowColorMode, viewportStyle };

package/dist/esm/index.js

@@ -1,4 +1,237 @@
+import { createEntityChangeNotifier, pathToSVG } from "@statelyai/flow";
 export * from "@statelyai/flow";
+//#region src/clipboard.ts
+const FLOW_CONTENT_MIME = "application/vnd.stately.flow+json";
+function createFlowClipboard(flow, options = {}) {
+	const clipboard = options.clipboard ?? globalThis.navigator?.clipboard;
+	let fallback = null;
+	async function write(content) {
+		fallback = content;
+		const json = JSON.stringify(content);
+		try {
+			if (clipboard?.write && options.ClipboardItem) {
+				const html = `<div data-stately-flow>${escapeHtml(json)}</div>`;
+				await clipboard.write([new options.ClipboardItem({
+					[FLOW_CONTENT_MIME]: new Blob([json], { type: FLOW_CONTENT_MIME }),
+					"text/plain": new Blob([json], { type: "text/plain" }),
+					"text/html": new Blob([html], { type: "text/html" })
+				})]);
+			} else if (clipboard?.writeText) await clipboard.writeText(json);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async function read() {
+		let readSucceeded = false;
+		try {
+			if (clipboard?.read) {
+				const items = await clipboard.read();
+				readSucceeded = true;
+				for (const item of items) {
+					const type = item.types.includes("application/vnd.stately.flow+json") ? FLOW_CONTENT_MIME : item.types.includes("text/plain") ? "text/plain" : null;
+					if (type) return parseJson(await (await item.getType(type)).text());
+				}
+			}
+			if (clipboard?.readText) {
+				const text = await clipboard.readText();
+				readSucceeded = true;
+				if (text) return parseJson(text);
+			}
+		} catch {
+			if (readSucceeded) return null;
+			return fallback;
+		}
+		return readSucceeded ? null : fallback;
+	}
+	function canRun(command, targets) {
+		if (!targets) return flow.can(command);
+		return targets.length > 0 && targets.every((id) => flow.can(command, { id }));
+	}
+	return {
+		async copy(targets) {
+			const ids = targets ? [...targets] : void 0;
+			if (!canRun("copy", ids)) return false;
+			const content = flow.content.extract(ids);
+			if (!content) return false;
+			await write(content);
+			return true;
+		},
+		async cut(targets) {
+			const ids = targets ? [...targets] : [...flow.getSnapshot().selection];
+			if (!canRun("cut", ids)) return false;
+			const content = flow.content.extract(ids);
+			if (!content) return false;
+			if (!await write(content)) return false;
+			flow.transaction((draft) => {
+				for (const id of ids) if (!draft.edges.delete(id)) draft.nodes.delete(id);
+			}, { origin: "clipboard.cut" });
+			return true;
+		},
+		async paste(insertOptions) {
+			const content = await read();
+			if (!content) return {
+				ok: false,
+				error: /* @__PURE__ */ new Error("Clipboard does not contain Flow content.")
+			};
+			return flow.content.insert(content, insertOptions);
+		}
+	};
+}
+function parseJson(value) {
+	try {
+		return JSON.parse(value);
+	} catch {
+		return null;
+	}
+}
+function escapeHtml(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+//#endregion
+//#region src/exportImage.ts
+function createFlowView(container, options = {}) {
+	return {
+		exportImage: (options) => exportFlowImage(container, options),
+		refreshMeasurements: (targets) => options.measurements?.refresh(targets)
+	};
+}
+async function exportFlowImage(container, options = {}) {
+	throwIfAborted(options.signal);
+	const win = container.ownerDocument.defaultView;
+	if (!win) throw new Error("Flow export requires a window.");
+	await nextFrame(win, options.signal);
+	const format = options.format ?? "svg";
+	const padding = Math.max(0, options.padding ?? 0);
+	const scale = Math.max(.01, options.scale ?? 1);
+	const pixelRatio = Math.max(.01, options.pixelRatio ?? win.devicePixelRatio ?? 1);
+	const region = resolveRegion(container, options.region ?? "graph");
+	const width = Math.max(1, Math.ceil((region.width + padding * 2) * scale));
+	const height = Math.max(1, Math.ceil((region.height + padding * 2) * scale));
+	const clone = container.cloneNode(true);
+	if ((options.styles ?? "computed") === "computed") inlineComputedStyles(win, container, clone);
+	if (options.include) {
+		const originals = [container, ...Array.from(container.querySelectorAll("*"))];
+		const clones = [clone, ...Array.from(clone.querySelectorAll("*"))];
+		for (let index = originals.length - 1; index >= 0; index--) if (!options.include(originals[index])) clones[index]?.remove();
+	}
+	const markup = new win.XMLSerializer().serializeToString(clone);
+	const background = options.background ? `<rect width="100%" height="100%" fill="${escapeXml(options.background)}"/>` : "";
+	const containerRect = container.getBoundingClientRect();
+	const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="${region.x - padding} ${region.y - padding} ${region.width + padding * 2} ${region.height + padding * 2}">${background}<foreignObject x="0" y="0" width="${containerRect.width}" height="${containerRect.height}">${markup}</foreignObject></svg>`;
+	const svgBlob = new Blob([svg], { type: "image/svg+xml" });
+	if (format === "svg") return {
+		blob: svgBlob,
+		width,
+		height
+	};
+	throwIfAborted(options.signal);
+	const image = await loadImage(win, await blobDataUrl(win, svgBlob, options.signal), options.signal);
+	const canvas = container.ownerDocument.createElement("canvas");
+	canvas.width = Math.ceil(width * pixelRatio);
+	canvas.height = Math.ceil(height * pixelRatio);
+	const context = canvas.getContext("2d");
+	if (!context) throw new Error("Canvas 2D context is unavailable.");
+	context.scale(pixelRatio, pixelRatio);
+	context.drawImage(image, 0, 0, width, height);
+	return {
+		blob: await canvasBlob(canvas, `image/${format}`, options.signal),
+		width,
+		height
+	};
+}
+function inlineComputedStyles(win, originalRoot, cloneRoot) {
+	const originals = [originalRoot, ...Array.from(originalRoot.querySelectorAll("*"))];
+	const clones = [cloneRoot, ...Array.from(cloneRoot.querySelectorAll("*"))];
+	for (let index = 0; index < originals.length; index++) {
+		const clone = clones[index];
+		if (!clone?.style) continue;
+		const computed = win.getComputedStyle(originals[index]);
+		for (let propertyIndex = 0; propertyIndex < computed.length; propertyIndex++) {
+			const property = computed.item(propertyIndex);
+			clone.style.setProperty(property, computed.getPropertyValue(property), computed.getPropertyPriority(property));
+		}
+	}
+}
+function blobDataUrl(win, blob, signal) {
+	return new Promise((resolve, reject) => {
+		const Reader = win.FileReader;
+		const reader = new Reader();
+		reader.onload = () => resolve(String(reader.result));
+		reader.onerror = () => reject(reader.error ?? /* @__PURE__ */ new Error("Unable to encode Flow SVG."));
+		signal?.addEventListener("abort", () => {
+			reader.abort();
+			reject(abortError());
+		}, { once: true });
+		reader.readAsDataURL(blob);
+	});
+}
+function resolveRegion(container, region) {
+	if (typeof region === "object") return region;
+	const selector = region === "selection" ? "[data-flow-selected=\"true\"], [aria-selected=\"true\"]" : region === "graph" ? "[data-entity-id]" : null;
+	const elements = selector ? Array.from(container.querySelectorAll(selector)) : [container];
+	const containerRect = container.getBoundingClientRect();
+	if (elements.length === 0) return {
+		x: 0,
+		y: 0,
+		width: containerRect.width,
+		height: containerRect.height
+	};
+	const rects = elements.map((element) => element.getBoundingClientRect());
+	const left = Math.min(...rects.map((rect) => rect.left));
+	const top = Math.min(...rects.map((rect) => rect.top));
+	const right = Math.max(...rects.map((rect) => rect.right));
+	const bottom = Math.max(...rects.map((rect) => rect.bottom));
+	return {
+		x: left - containerRect.left,
+		y: top - containerRect.top,
+		width: right - left,
+		height: bottom - top
+	};
+}
+function nextFrame(win, signal) {
+	return new Promise((resolve, reject) => {
+		const id = win.requestAnimationFrame(() => {
+			if (signal?.aborted) reject(abortError());
+			else resolve();
+		});
+		signal?.addEventListener("abort", () => {
+			win.cancelAnimationFrame(id);
+			reject(abortError());
+		}, { once: true });
+	});
+}
+function loadImage(win, url, signal) {
+	return new Promise((resolve, reject) => {
+		const ImageCtor = win.Image;
+		const image = new ImageCtor();
+		image.onload = () => resolve(image);
+		image.onerror = () => reject(/* @__PURE__ */ new Error("Unable to render Flow SVG."));
+		signal?.addEventListener("abort", () => reject(abortError()), { once: true });
+		image.src = url;
+	});
+}
+function canvasBlob(canvas, type, signal) {
+	return new Promise((resolve, reject) => {
+		canvas.toBlob((blob) => {
+			if (signal?.aborted) reject(abortError());
+			else if (blob) resolve(blob);
+			else reject(/* @__PURE__ */ new Error(`Unable to encode ${type}.`));
+		}, type);
+	});
+}
+function throwIfAborted(signal) {
+	if (signal?.aborted) throw abortError();
+}
+function abortError() {
+	const error = /* @__PURE__ */ new Error("The operation was aborted.");
+	error.name = "AbortError";
+	return error;
+}
+function escapeXml(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;").replaceAll("<", "&lt;");
+}
+//#endregion
 //#region src/culling.ts
 /** Overscan (canvas px) added around the viewport so entities just off-screen
 * stay mounted and don't pop in/out at the edges. */
@@ -37,20 +270,21 @@ function renderableIdsEqual(a, b) {
 * `getGraphBounds`/`getRenderableEntities` from the live store) — which holds
 * when called inside a store-subscription selector.
 */
-function computeRenderableIds(engine, context, enabled) {
+function computeRenderableIds(engine, context, enabled, options = {}) {
 	if (!enabled) return null;
+	const overscan = options.overscan ?? CULL_OVERSCAN;
 	const viewportSize = context.viewportSize;
 	if (viewportSize.width === 0 || viewportSize.height === 0) return null;
 	const viewport = context.viewport;
-	const left = -viewport.x / viewport.zoom - CULL_OVERSCAN;
-	const top = -viewport.y / viewport.zoom - CULL_OVERSCAN;
-	const right = left + viewportSize.width / viewport.zoom + CULL_OVERSCAN * 2;
-	const bottom = top + viewportSize.height / viewport.zoom + CULL_OVERSCAN * 2;
+	const left = -viewport.x / viewport.zoom - overscan;
+	const top = -viewport.y / viewport.zoom - overscan;
+	const right = left + viewportSize.width / viewport.zoom + overscan * 2;
+	const bottom = top + viewportSize.height / viewport.zoom + overscan * 2;
 	const bounds = engine.getGraphBounds();
 	if (left <= bounds.x && top <= bounds.y && right >= bounds.x + bounds.width && bottom >= bounds.y + bounds.height) return null;
 	const renderable = engine.getRenderableEntities({
 		cull: "viewport",
-		overscan: CULL_OVERSCAN
+		overscan
 	});
 	return {
 		nodeIds: new Set(renderable.nodes.map((node) => node.id)),
@@ -98,6 +332,107 @@ function viewportStyle() {
 	};
 }
 //#endregion
+//#region src/entity-geometry.ts
+/**
+* Batches transient entity geometry into imperative DOM writes. One core
+* entity-change notifier keeps dispatch O(changed); framework adapters retain
+* ownership of content, selection, and other durable rendering.
+*/
+function createEntityGeometryObserver(store, options = {}) {
+	const requestFrame = options.requestFrame ?? ((callback) => requestAnimationFrame(callback));
+	const cancelFrame = options.cancelFrame ?? ((handle) => cancelAnimationFrame(handle));
+	const createNotifier = () => createEntityChangeNotifier(store, { getEdgeDependents: options.getEdgeDependents });
+	let notifier = createNotifier();
+	const getNotifier = () => notifier ??= createNotifier();
+	const observations = /* @__PURE__ */ new Set();
+	const pending = /* @__PURE__ */ new Set();
+	let frame = null;
+	const flush = () => {
+		if (frame !== null) {
+			cancelFrame(frame);
+			frame = null;
+		}
+		const current = [...pending];
+		pending.clear();
+		for (const observation of current) observation.write();
+	};
+	const schedule = (observation) => {
+		pending.add(observation);
+		if (frame === null) frame = requestFrame(() => {
+			frame = null;
+			const current = [...pending];
+			pending.clear();
+			for (const pendingObservation of current) pendingObservation.write();
+		});
+	};
+	const observe = (id, write) => {
+		const observation = {
+			write,
+			unsubscribe: () => {}
+		};
+		observation.unsubscribe = getNotifier().subscribe(id, () => schedule(observation));
+		observations.add(observation);
+		write();
+		return () => {
+			observation.unsubscribe();
+			observations.delete(observation);
+			pending.delete(observation);
+		};
+	};
+	return {
+		observeRect(element, target) {
+			return observe(target.id, () => {
+				const rect = target.getRect();
+				if (!rect) return;
+				const context = store.getSnapshot().context;
+				const dragging = context.canvasState === "dragging" && context.selection.has(target.id);
+				const resizing = context.resizingEntityId === target.id;
+				const layoutAnimating = context.layoutAnimation.status === "running" && context.layoutAnimation.offsets.has(target.id);
+				element.style.transform = `translate(${rect.x}px, ${rect.y}px)`;
+				if (!target.autoSize || resizing) {
+					element.style.width = `${rect.width}px`;
+					element.style.height = `${rect.height}px`;
+				}
+				if (dragging || resizing || layoutAnimating) element.style.willChange = resizing ? "transform, width, height" : "transform";
+				else element.style.removeProperty("will-change");
+			});
+		},
+		observeEdge(element, target) {
+			return observe(target.id, () => {
+				const pathData = target.getPathData();
+				if (!pathData) return;
+				element.querySelectorAll("[data-flow-edge-segment]").forEach((path) => {
+					const index = Number(path.dataset.flowEdgeSegment);
+					const segment = pathData.segments[index];
+					if (segment) path.setAttribute("d", pathToSVG(segment));
+				});
+				const first = pathData.segments[0]?.points[0];
+				const last = pathData.segments.at(-1)?.points.at(-1);
+				if (first) {
+					const source = element.querySelector("[data-flow-edge-endpoint=\"source\"]");
+					source?.setAttribute("cx", String(first.x));
+					source?.setAttribute("cy", String(first.y));
+				}
+				if (last) {
+					const targetElement = element.querySelector("[data-flow-edge-endpoint=\"target\"]");
+					targetElement?.setAttribute("cx", String(last.x));
+					targetElement?.setAttribute("cy", String(last.y));
+				}
+			});
+		},
+		flush,
+		disconnect() {
+			if (frame !== null) cancelFrame(frame);
+			frame = null;
+			pending.clear();
+			for (const observation of observations) observation.unsubscribe();
+			observations.clear();
+			notifier?.destroy();
+			notifier = null;
+		}
+	};
+}
+//#endregion
 //#region src/index.ts
 function resolveFlowColorMode(colorMode, targetWindow = typeof window === "undefined" ? void 0 : window) {
 	if (colorMode !== "system") return colorMode;
@@ -112,6 +447,7 @@ function applyFlowColorMode(element, colorMode, targetWindow = element.ownerDocu
 }
 const containers = /* @__PURE__ */ new WeakMap();
 function createMeasurementObserver(store, options = {}) {
+	const equalityThreshold = options.equalityThreshold ?? .5;
 	const elementMap = /* @__PURE__ */ new Map();
 	let pendingMeasurements = [];
 	let rafId = null;
@@ -138,14 +474,14 @@ function createMeasurementObserver(store, options = {}) {
 		};
 		const id = "portName" in target ? `${target.nodeId}:${target.portName}` : "nodeId" in target ? target.nodeId : target.edgeId;
 		const existing = store.getSnapshot().context.measurements.get(id);
-		if (existing && Math.abs(existing.x - measurement.x) < .5 && Math.abs(existing.y - measurement.y) < .5 && Math.abs(existing.width - measurement.width) < .5 && Math.abs(existing.height - measurement.height) < .5) return;
+		if (existing && Math.abs(existing.x - measurement.x) < equalityThreshold && Math.abs(existing.y - measurement.y) < equalityThreshold && Math.abs(existing.width - measurement.width) < equalityThreshold && Math.abs(existing.height - measurement.height) < equalityThreshold) return;
 		pendingMeasurements.push({
 			id,
 			rect: measurement
 		});
 		scheduleFlush();
 	}
-	const observer = new ResizeObserver((entries) => {
+	const handleResize = (entries) => {
 		for (const entry of entries) {
 			const target = elementMap.get(entry.target);
 			if (!target) continue;
@@ -159,11 +495,17 @@ function createMeasurementObserver(store, options = {}) {
 			} : void 0;
 			pushMeasurement(entry.target, target, layoutSize);
 		}
-	});
+	};
+	let observer = null;
+	function getObserver(element) {
+		if (observer) return observer;
+		observer = new ((element.ownerDocument.defaultView?.ResizeObserver) ?? ResizeObserver)(handleResize);
+		return observer;
+	}
 	return {
 		observe(element, target) {
 			elementMap.set(element, target);
-			observer.observe(element);
+			getObserver(element).observe(element);
 		},
 		/**
 		* Re-measure an observed element immediately. ResizeObserver only fires
@@ -174,13 +516,22 @@ function createMeasurementObserver(store, options = {}) {
 			const target = elementMap.get(element);
 			if (target) pushMeasurement(element, target);
 		},
+		refresh(targets) {
+			const requested = targets ? new Set(targets) : null;
+			for (const [element, target] of elementMap) {
+				const id = "portName" in target ? `${target.nodeId}:${target.portName}` : "nodeId" in target ? target.nodeId : target.edgeId;
+				if (requested && !requested.has(element) && !requested.has(id)) continue;
+				pushMeasurement(element, target);
+			}
+		},
 		unobserve(element) {
 			elementMap.delete(element);
-			observer.unobserve(element);
+			observer?.unobserve(element);
 		},
 		disconnect() {
 			elementMap.clear();
-			observer.disconnect();
+			observer?.disconnect();
+			observer = null;
 			if (rafId !== null) {
 				cancelAnimationFrame(rafId);
 				rafId = null;
@@ -196,6 +547,23 @@ function getContainer(container) {
 function getAttachedContainer(store) {
 	return containers.get(store);
 }
+function clientToCanvas(store, point, container = containers.get(store)) {
+	const rect = container?.getBoundingClientRect();
+	const viewport = store.getSnapshot().context.viewport;
+	const zoom = viewport.zoom || 1;
+	return {
+		x: (point.x - (rect?.left ?? 0) - viewport.x) / zoom,
+		y: (point.y - (rect?.top ?? 0) - viewport.y) / zoom
+	};
+}
+function canvasToClient(store, point, container = containers.get(store)) {
+	const rect = container?.getBoundingClientRect();
+	const viewport = store.getSnapshot().context.viewport;
+	return {
+		x: point.x * viewport.zoom + viewport.x + (rect?.left ?? 0),
+		y: point.y * viewport.zoom + viewport.y + (rect?.top ?? 0)
+	};
+}
 function attachContainer(store, element) {
 	containers.set(store, element);
 	const update = () => {
@@ -206,21 +574,22 @@ function attachContainer(store, element) {
 		});
 	};
 	update();
-	const observer = new ResizeObserver(update);
+	const observer = new ((element.ownerDocument.defaultView?.ResizeObserver) ?? ResizeObserver)(update);
 	observer.observe(element);
 	return () => {
 		if (containers.get(store) === element) containers.delete(store);
 		observer.disconnect();
 	};
 }
-/** Idle delay (ms) before dropping the GPU-layer hint after interaction stops. */
-const VIEWPORT_PROMOTE_IDLE_MS = 200;
-function attachViewportTransform(store, element) {
+function attachViewportTransform(store, element, options = {}) {
+	const promoteIdleMs = options.promoteIdleMs ?? 200;
 	let prevViewport = store.getSnapshot().context.viewport;
 	let prevState = store.getSnapshot().context.canvasState;
 	let idle;
 	const writeTransform = (viewport) => {
 		element.style.transform = `translate(${viewport.x}px, ${viewport.y}px) scale(${viewport.zoom})`;
+		element.style.setProperty("--flow-zoom", String(viewport.zoom));
+		element.style.setProperty("--flow-inverse-zoom", String(1 / viewport.zoom));
 	};
 	const promote = () => {
 		element.style.willChange = "transform";
@@ -230,7 +599,7 @@ function attachViewportTransform(store, element) {
 		if (idle !== void 0) clearTimeout(idle);
 		idle = setTimeout(() => {
 			element.style.willChange = "auto";
-		}, VIEWPORT_PROMOTE_IDLE_MS);
+		}, promoteIdleMs);
 	};
 	writeTransform(prevViewport);
 	if (prevState !== "idle") promote();
@@ -257,9 +626,20 @@ function attachInput(options) {
 	const { container, store, runtime } = options;
 	const doc = container.ownerDocument;
 	const win = doc.defaultView;
+	const ElementCtor = win?.Element;
+	const HTMLElementCtor = win?.HTMLElement;
+	const keyboardTarget = options.keyboardTarget ?? "container";
+	const keyboardElement = keyboardTarget === "window" ? win : keyboardTarget === "container" ? container : keyboardTarget;
 	let capturedPointerId = null;
 	let lastClient = null;
 	let autoPanFrame = null;
+	const activeTouchPointers = /* @__PURE__ */ new Map();
+	let pinchActive = false;
+	const DOUBLE_CLICK_MS = 500;
+	const DOUBLE_CLICK_DISTANCE = 4;
+	let lastClickDown = null;
+	let clickCount = 0;
+	let lastPinch = null;
 	function stopAutoPan() {
 		if (autoPanFrame !== null) {
 			win?.cancelAnimationFrame(autoPanFrame);
@@ -305,6 +685,18 @@ function attachInput(options) {
 			alt: event.altKey
 		};
 	}
+	function computeClickDetail(event) {
+		if (event.pointerType === "touch") return event.detail || 0;
+		const now = event.timeStamp || (win ? win.performance.now() : Date.now());
+		if (lastClickDown && now - lastClickDown.time <= DOUBLE_CLICK_MS && Math.abs(event.clientX - lastClickDown.x) <= DOUBLE_CLICK_DISTANCE && Math.abs(event.clientY - lastClickDown.y) <= DOUBLE_CLICK_DISTANCE) clickCount += 1;
+		else clickCount = 1;
+		lastClickDown = {
+			time: now,
+			x: event.clientX,
+			y: event.clientY
+		};
+		return clickCount;
+	}
 	function toPoints(event) {
 		const rect = container.getBoundingClientRect();
 		const screenPoint = {
@@ -322,24 +714,28 @@ function attachInput(options) {
 		};
 	}
 	function resolveTarget(event) {
-		const element = capturedPointerId !== null ? doc.elementFromPoint(event.clientX, event.clientY) : event.target instanceof Element ? event.target : null;
+		const element = capturedPointerId !== null ? doc.elementFromPoint(event.clientX, event.clientY) : ElementCtor && event.target instanceof ElementCtor ? event.target : null;
 		if (!element) return { kind: "none" };
+		if (!container.contains(element)) return { kind: "none" };
+		const owningRoot = element.closest("[data-flow-root]");
+		if (owningRoot && owningRoot !== container) return { kind: "none" };
 		const portElement = element.closest("[data-flow-port-name]");
 		if (portElement?.dataset.flowPortName) return {
 			kind: "port",
 			nodeId: portElement.dataset.flowNodeId ?? "",
 			portName: portElement.dataset.flowPortName
 		};
-		if (element.closest("[data-flow-interactive]")) return { kind: "none" };
+		if (element.closest("[data-flow-interactive], .nodrag, input, textarea, select, button, a[href], [contenteditable]:not([contenteditable=\"false\"])")) return { kind: "none" };
 		const entityElement = element.closest("[data-entity-id]");
 		if (entityElement?.dataset.entityId) {
 			const isLabel = element.closest("[data-flow-edge-label]") !== null;
+			const part = element.closest("[data-flow-part]")?.dataset.flowPart ?? (isLabel ? "label" : void 0);
 			const entityHasDragHandle = entityElement.querySelector("[data-flow-drag-handle]") !== null;
 			const pressedDragHandle = entityHasDragHandle && element.closest("[data-flow-drag-handle]") !== null;
 			return {
 				kind: "entity",
 				id: entityElement.dataset.entityId,
-				...isLabel ? { part: "label" } : {},
+				...part ? { part } : {},
 				...entityHasDragHandle ? {
 					entityHasDragHandle,
 					pressedDragHandle
@@ -361,7 +757,9 @@ function attachInput(options) {
 		const effects = runtime.send({
 			kind,
 			pointerId: info.pointerId,
+			pointerType: info.pointerType ?? "mouse",
 			button: info.button,
+			detail: info.detail,
 			point,
 			screenPoint,
 			target: resolveTarget({
@@ -388,16 +786,116 @@ function attachInput(options) {
 		}
 		return effects;
 	}
+	function touchPoints() {
+		return [...activeTouchPointers.values()];
+	}
+	function pinchGeometry() {
+		const touches = touchPoints();
+		if (touches.length < 2) return null;
+		const [a, b] = touches;
+		const screenCenter = {
+			x: (a.clientX + b.clientX) / 2 - container.getBoundingClientRect().left,
+			y: (a.clientY + b.clientY) / 2 - container.getBoundingClientRect().top
+		};
+		const { point: center } = toPoints({
+			clientX: (a.clientX + b.clientX) / 2,
+			clientY: (a.clientY + b.clientY) / 2
+		});
+		return {
+			screenCenter,
+			center,
+			distance: Math.hypot(b.clientX - a.clientX, b.clientY - a.clientY),
+			modifiers: a.modifiers
+		};
+	}
+	function sendPinch(kind) {
+		const fallback = (kind === "pinch.end" ? lastPinch : pinchGeometry()) ?? lastPinch;
+		if (!fallback) return makeNoEffects();
+		lastPinch = fallback;
+		return runtime.send({
+			kind,
+			center: fallback.center,
+			screenCenter: fallback.screenCenter,
+			distance: fallback.distance,
+			pointerCount: activeTouchPointers.size,
+			modifiers: fallback.modifiers
+		});
+	}
+	function makeNoEffects() {
+		return {
+			preventDefault: false,
+			stopPropagation: false,
+			sessionStarted: false,
+			sessionEnded: false,
+			handledBy: null
+		};
+	}
+	function releaseCapturedPointer() {
+		if (capturedPointerId === null) return;
+		try {
+			if (container.hasPointerCapture(capturedPointerId)) container.releasePointerCapture(capturedPointerId);
+		} catch {}
+		capturedPointerId = null;
+		lastClient = null;
+		stopAutoPan();
+	}
 	function handlePointer(kind) {
 		return (event) => {
+			if (kind === "pointer.down") focusContainerForPanePress(event);
+			const pointerType = event.pointerType === "touch" || event.pointerType === "pen" || event.pointerType === "mouse" ? event.pointerType : "mouse";
+			if (pointerType === "touch") {
+				if (kind === "pointer.down") {
+					activeTouchPointers.set(event.pointerId, {
+						clientX: event.clientX,
+						clientY: event.clientY,
+						modifiers: modifiers(event)
+					});
+					if (activeTouchPointers.size === 2) {
+						runtime.cancelSession();
+						releaseCapturedPointer();
+						pinchActive = true;
+						lastPinch = pinchGeometry();
+						applyEffects(event, sendPinch("pinch.start"));
+						return;
+					}
+					if (activeTouchPointers.size > 2) {
+						applyEffects(event, sendPinch("pinch.move"));
+						return;
+					}
+				} else if (activeTouchPointers.has(event.pointerId)) {
+					if (kind === "pointer.move") {
+						activeTouchPointers.set(event.pointerId, {
+							clientX: event.clientX,
+							clientY: event.clientY,
+							modifiers: modifiers(event)
+						});
+						if (pinchActive) {
+							applyEffects(event, sendPinch("pinch.move"));
+							return;
+						}
+					} else if (kind === "pointer.up" || kind === "pointer.cancel") {
+						activeTouchPointers.delete(event.pointerId);
+						if (pinchActive) {
+							const effects = sendPinch("pinch.end");
+							pinchActive = false;
+							lastPinch = null;
+							applyEffects(event, effects);
+							return;
+						}
+					}
+				}
+			}
 			if (kind === "pointer.down" || capturedPointerId !== null && event.pointerId === capturedPointerId) lastClient = {
 				x: event.clientX,
 				y: event.clientY,
 				pointerId: event.pointerId
 			};
+			const detail = kind === "pointer.down" && event.button === 0 ? computeClickDetail(event) : event.detail;
 			applyEffects(event, sendPointer(kind, event.clientX, event.clientY, {
 				pointerId: event.pointerId,
+				pointerType,
 				button: event.button,
+				detail,
 				modifiers: modifiers(event),
 				target: event.target
 			}));
@@ -416,10 +914,33 @@ function attachInput(options) {
 			modifiers: modifiers(event)
 		}));
 	}
+	function handleContextMenu(event) {
+		applyEffects(event, sendPointer("pointer.down", event.clientX, event.clientY, {
+			pointerId: -1,
+			pointerType: "mouse",
+			button: 2,
+			detail: event.detail,
+			modifiers: modifiers(event),
+			target: event.target
+		}));
+	}
 	function isEditableTarget(target) {
-		if (!(target instanceof HTMLElement)) return false;
+		if (!HTMLElementCtor || !(target instanceof HTMLElementCtor)) return false;
 		return target.isContentEditable || target.matches("input, textarea, select, [contenteditable='true']");
 	}
+	function isInteractiveTarget(target) {
+		return !!ElementCtor && target instanceof ElementCtor && target.closest("[data-flow-interactive]") !== null;
+	}
+	function focusContainerForPanePress(event) {
+		if (keyboardTarget !== "container") return;
+		if (isEditableTarget(event.target) || isInteractiveTarget(event.target)) return;
+		if (resolveTarget({
+			clientX: event.clientX,
+			clientY: event.clientY,
+			target: event.target
+		}).kind !== "pane") return;
+		container.focus({ preventScroll: true });
+	}
 	function handleKey(kind) {
 		return (event) => {
 			applyEffects(event, runtime.send({
@@ -434,26 +955,49 @@ function attachInput(options) {
 	const onPointerMove = handlePointer("pointer.move");
 	const onPointerUp = handlePointer("pointer.up");
 	const onPointerCancel = handlePointer("pointer.cancel");
+	const onLostPointerCapture = () => {
+		stopAutoPan();
+		runtime.cancelSession();
+		capturedPointerId = null;
+		lastClient = null;
+	};
+	const onWindowBlur = () => {
+		stopAutoPan();
+		runtime.cancelSession();
+		activeTouchPointers.clear();
+		capturedPointerId = null;
+		lastClient = null;
+	};
 	const onKeyDown = handleKey("key.down");
 	const onKeyUp = handleKey("key.up");
+	if (keyboardTarget === "container" && !container.hasAttribute("tabindex")) container.tabIndex = 0;
 	container.addEventListener("pointerdown", onPointerDown);
 	container.addEventListener("pointermove", onPointerMove);
 	container.addEventListener("pointerup", onPointerUp);
 	container.addEventListener("pointercancel", onPointerCancel);
+	container.addEventListener("lostpointercapture", onLostPointerCapture);
+	container.addEventListener("contextmenu", handleContextMenu);
 	container.addEventListener("wheel", handleWheel, { passive: false });
-	win?.addEventListener("keydown", onKeyDown);
-	win?.addEventListener("keyup", onKeyUp);
+	keyboardElement?.addEventListener("keydown", onKeyDown);
+	keyboardElement?.addEventListener("keyup", onKeyUp);
+	win?.addEventListener("blur", onWindowBlur);
 	return () => {
 		stopAutoPan();
 		runtime.cancelSession();
+		activeTouchPointers.clear();
+		pinchActive = false;
+		lastPinch = null;
 		container.removeEventListener("pointerdown", onPointerDown);
 		container.removeEventListener("pointermove", onPointerMove);
 		container.removeEventListener("pointerup", onPointerUp);
 		container.removeEventListener("pointercancel", onPointerCancel);
+		container.removeEventListener("lostpointercapture", onLostPointerCapture);
+		container.removeEventListener("contextmenu", handleContextMenu);
 		container.removeEventListener("wheel", handleWheel);
-		win?.removeEventListener("keydown", onKeyDown);
-		win?.removeEventListener("keyup", onKeyUp);
+		keyboardElement?.removeEventListener("keydown", onKeyDown);
+		keyboardElement?.removeEventListener("keyup", onKeyUp);
+		win?.removeEventListener("blur", onWindowBlur);
 	};
 }
 //#endregion
-export { applyFlowColorMode, attachContainer, attachInput, attachViewportTransform, computeRenderableIds, createMeasurementObserver, getAttachedContainer, nodePositionStyle, renderableIdsEqual, resolveFlowColorMode, viewportStyle };
+export { FLOW_CONTENT_MIME, applyFlowColorMode, attachContainer, attachInput, attachViewportTransform, canvasToClient, clientToCanvas, computeRenderableIds, createEntityGeometryObserver, createFlowClipboard, createFlowView, createMeasurementObserver, exportFlowImage, getAttachedContainer, nodePositionStyle, renderableIdsEqual, resolveFlowColorMode, viewportStyle };

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "@statelyai/flow-dom",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "DOM-specific helpers for @statelyai/flow with core re-exports.",
+  "type": "module",
+  "sideEffects": false,
   "keywords": [
     "flow",
     "diagram",
@@ -25,11 +27,12 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@statelyai/flow": "0.4.2"
+    "@statelyai/flow": "0.5.0"
   },
   "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.0",
     "jsdom": "^25.0.0",
-    "tsdown": "^0.12.0",
+    "tsdown": "^0.22.13",
     "typescript": "^5.8.0",
     "vitest": "^4.1.0"
   },
@@ -37,6 +40,7 @@
     "dev": "tsdown --watch",
     "build": "tsdown",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   }
 }