@foblex/flow 19.1.1 → 19.1.3

package/AI.md

@@ -139,9 +139,31 @@ export class Editor {
 - Rotation, connection waypoint editing, and user resize are not captured by managed state in v1.
 - `state.changes()` increments once when a standalone mutation or outer batch settles. A drag can emit selection at start and move/drop at end while remaining one history step and one `changes()` increment.
 - Use `state.snapshot()` for persistence; `load()` replaces data and resets history.
+- `canvasTransformDebounce` defaults to `350ms`. It waits for wheel/pinch zoom events to settle, then records the current canvas transform as one change and one undo item. Setting it to `0` disables batching: every emitted `fCanvasChange` is applied immediately, increments `state.changes()`, and normally creates a separate undo item. Keep the canvas `[debounceTime]` unset when managed state owns viewport history; do not stack canvas and State debounce layers.
 - For initial or other application-driven viewport positioning, suppress the event at the canvas helper: `canvas.resetScaleAndCenter(false, false)`. The second `false` means `emitCanvasChange = false`, so managed history is untouched.
 - Connection endpoints are connector ids. Automatic cascade from node/group deletion uses the rendered connector registry; before connectors render, remove known attached connection ids explicitly in the same `state.batch(...)`.
 
+### Async reflow must stay inside an open transaction
+
+When an application expands/collapses a node, its record changes synchronously but `withReflowOnResize()` emits the resulting `fMoveNodes` positions later, after Angular rendering and `ResizeObserver`. Do not use synchronous `state.batch(() => ...)` if both changes must be one undo item. Open the transaction before changing the record and close it only after reflow settles:
+
+```typescript
+state.beginBatch();
+
+try {
+  state.updateNode(nodeId, { isExpanded });
+  await new Promise<void>((resolve) => {
+    requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+  });
+} finally {
+  state.endBatch();
+}
+```
+
+The state controller applies reflow's `fMoveNodes` event inside the open transaction. One `undo()` then restores both the expanded value and every moved position. Two frames fit an immediately rendered size change; for CSS transitions, lazy content, or longer asynchronous layout, close from the real completion signal. Always close in `finally`, because an unclosed batch merges unrelated future mutations into the same history entry.
+
+If the toggle is nested inside `fDragHandle`, add `fDragBlocker` to the toggle. Otherwise its pointer down can select the node first; with `selectionInHistory: true`, that selection is a separate intentional history item even though expand and reflow share one batch.
+
 ## Common Silent Failures — Check These First
 
 When the flow compiles but looks wrong, verify in this order:
@@ -195,6 +217,7 @@ See [STYLING.md](./STYLING.md).
 - Human docs: https://flow.foblex.com/docs/get-started
 - Live examples with source: https://flow.foblex.com/examples/overview
 - Managed state example and contract: https://flow.foblex.com/examples/state
+- Managed state + asynchronous reflow recipe: https://flow.foblex.com/examples/state
 
 ## Fallback Rule
 

package/fesm2022/foblex-flow.mjs

@@ -8529,9 +8529,10 @@ let CreateConnectionFromConnectorPreparation = class CreateConnectionFromConnect
         this._startDrag(event.getPosition(), source);
     }
     _findConnector(target) {
+        const connectorElement = target.closest('[fConnector]');
         return this._store.connectors
             .getAll()
-            .find((x) => x instanceof FConnectorDirective && x.hostElement.contains(target));
+            .find((x) => x instanceof FConnectorDirective && x.hostElement === connectorElement);
     }
     _findSourcesInNode(node) {
         return getAllSourceConnectors(this._store).filter((x) => node.isContains(x.hostElement));
@@ -16130,9 +16131,10 @@ class FClickConnectFlow {
         return connector.canBeConnected ? connector : undefined;
     }
     _findUnifiedConnector(target) {
+        const connectorElement = target.closest('[fConnector]');
         return this._store.connectors
             .getAll()
-            .find((x) => x instanceof FConnectorDirective && x.hostElement.contains(target));
+            .find((x) => x instanceof FConnectorDirective && x.hostElement === connectorElement);
     }
     _resolveSourceForOutlet(outlet) {
         const node = this._store.nodes.getAll().find((n) => n.isContains(outlet.hostElement));
@@ -22490,7 +22492,7 @@ function mergeFlowStateConfig(config) {
         historyLimit: 50,
         selectionInHistory: true,
         canvasTransformInHistory: true,
-        canvasTransformDebounce: 0,
+        canvasTransformDebounce: 350,
         dropToGroup: false,
         ...config,
     };
@@ -23306,18 +23308,34 @@ class FFlowStateController {
         if (this._transformDebounceTimer !== null) {
             clearTimeout(this._transformDebounceTimer);
         }
+        this._scheduleCanvasChangeFlush(debounce);
+    }
+    _flushCanvasChange() {
+        const pending = this._pendingTransform;
+        if (!pending) {
+            return;
+        }
+        const current = this._readCanvasTransform();
+        const debounce = this._config?.canvasTransformDebounce ?? 0;
+        if (debounce > 0 && current && !this._isSameCanvasTransform(pending, current)) {
+            this._pendingTransform = current;
+            this._scheduleCanvasChangeFlush(debounce);
+            return;
+        }
+        this._pendingTransform = null;
+        const settled = debounce > 0 ? (current ?? pending) : pending;
+        this._dispatch(() => this._state.applyTransform(settled));
+    }
+    _scheduleCanvasChangeFlush(debounce) {
         this._transformDebounceTimer = setTimeout(() => {
             this._transformDebounceTimer = null;
             this._flushCanvasChange();
         }, debounce);
     }
-    _flushCanvasChange() {
-        const transform = this._pendingTransform;
-        this._pendingTransform = null;
-        if (!transform) {
-            return;
-        }
-        this._dispatch(() => this._state.applyTransform(transform));
+    _isSameCanvasTransform(first, second) {
+        return (first.position.x === second.position.x &&
+            first.position.y === second.position.y &&
+            first.scale === second.scale);
     }
     /**
      * Subscribes to every node's and group's `sizeChange` (a per-directive