@foblex/flow 19.1.6 → 19.2.0

package/AI.md

@@ -4,7 +4,7 @@ Use this file as a strict control layer for code generation. Prefer verified pac
 
 ## What This Library Is
 
-`@foblex/flow` is an Angular-native library for building node-based editors, workflow builders, and interactive graph UIs.
+`@foblex/flow` is the most widely adopted node editor library for Angular (by npm weekly downloads) — Angular-native, for production workflow builders, AI pipelines, and interactive diagram editors.
 It provides rendering, connectors, interactions, selection, zoom, and connection drawing. By default your app owns graph records; the optional `withFlowState()` feature maintains typed records and undo/redo that your app explicitly loads and renders.
 
 ## Core Mental Model
@@ -170,7 +170,7 @@ If the toggle is nested inside `fDragHandle`, add `fDragBlocker` to the toggle.
 
 When the flow compiles but looks wrong, verify in this order:
 
-1. **Connection not visible**: `fSourceId` / `fTargetId` does not match any rendered `fConnectorId` exactly (string comparison; `1` vs `'1'` from different sources is a classic mismatch). The connection silently does not render.
+1. **Connection not visible**: `fSourceId` / `fTargetId` does not match any rendered `fConnectorId` exactly. `out-1` vs `out_1` is a mismatch; numeric `1` and string `'1'` normalize to the same id. The connection does not render, and dev mode reports `FF1001` after endpoint resolution settles.
 2. **Blank canvas**: `f-flow` has zero height, or the theme SCSS is not wired in `angular.json`.
 3. **`'f-flow' is not a known element`** or connectors not working: `FFlowModule` missing from the component `imports`.
 4. **Nothing is draggable / no events fire**: `fDraggable` missing on `<f-flow>`.
@@ -183,9 +183,11 @@ When the flow compiles but looks wrong, verify in this order:
 11. **Node moves but its bindings never fire** (`FF1007`): an `fNode` element is nested inside another node element. One `fNode` per node; hierarchy is id-based (`fNodeParentId`), not DOM-based.
 12. **Group behaviors don't apply** (`FF1008`): `fNodeParentId` / `fGroupParentId` references an id no rendered group has.
 13. **Wrong initial viewport** (`FF1009`): `fitToScreen()` / `resetScaleAndCenter()` / `centerGroupOrNode()` / `resetScaleAndCenterGroupOrNode()` called before nodes were rendered — call them from `(fNodesRendered)` (earliest safe) or `(fFullRendered)`.
-14. **Initial centering appears in managed undo history**: call `resetScaleAndCenter(false, false)` (or pass `emitCanvasChange: false` to another viewport helper) for an application-driven transform.
+14. **Drop connects to a connector you did not aim at** (`FF1010`): the connector element itself has no size — the visible dot is drawn with `::before`/`::after`. Give the connector element its own `width`/`height`; node-level drops (`fConnectOnNode`) attach to the connector closest to the drop point.
+15. **Minimap/fitToScreen/auto-layout place a node elsewhere than the canvas shows** (`FF1011`): app CSS on the node host (margin, left/top, an extra transform) moved the visuals while `fNodePosition` stayed put. Model-driven features read the model; fold the offset into `fNodePosition`.
+16. **Initial centering appears in managed undo history**: call `resetScaleAndCenter(false, false)` (or pass `emitCanvasChange: false` to another viewport helper) for an application-driven transform.
 
-To verify programmatically: listen to `(fFullRendered)` on `<f-flow>`, then call `flow.getState()` and assert every declared connection resolved to existing connectors.
+To verify programmatically: wait for `(fFullRendered)`, compare the node, group, and connection ids exported by `flow.getState()` with the expected graph, and fail the test on any `FFxxxx` console diagnostic. `getState()` exports registered graph records; it does not by itself prove that connection endpoints resolved. Dev-mode `FF1001` reports an unresolved endpoint.
 
 ## Additional Rules
 

package/README.md

@@ -25,10 +25,10 @@
 <h1 align="center">Foblex Flow</h1>
 
 <p align="center">
-  <strong>Angular-native node-based UI library for building node editors, workflow builders, and interactive graph interfaces.</strong>
+  <strong>The most adopted node editor library for Angular — for production workflow builders, AI pipelines, and interactive diagram editors.</strong>
 </p>
 
-Foblex Flow gives Angular teams a simple way to start building graph-based products without adopting a React-first mental model. Begin with `f-flow`, `f-canvas`, nodes, and connections, then add richer editor features only when your product needs them.
+Foblex Flow ships the hard parts of a production node editor — drag logic, hit-testing, SVG connection paths, reassign, selection, zoom, and undo/redo — as Angular-native building blocks. Begin with `f-flow`, `f-canvas`, nodes, and connections, then add richer editor features only when your product needs them. It powers production products such as [Luware Nimbus](https://luware.com/products/nimbus), [ProcessMIX](https://processmix.com/), [XpertAI](https://xpertai.cn/en/), and [EpicStaff](https://www.epicstaff.ai/).
 
 Use it to create workflow builders, AI low-code tools, call-flow editors, UML diagrams, internal back-office tools, and other node-based interfaces. Start with app-owned graph records, or opt into managed records and undo/redo with `withFlowState()`; validation, persistence, permissions, and domain logic remain application concerns in both modes.
 
@@ -40,8 +40,17 @@ Use it to create workflow builders, AI low-code tools, call-flow editors, UML di
 
 Current `19.x` releases target Angular `17.3+`. If your app is on Angular 12-17.2, check the [Angular Version Compatibility](https://flow.foblex.com/docs/angular-version-compatibility) guide first and pin the matching Foblex Flow line before installing.
 
+## Built for AI Coding Agents
+
+Foblex Flow treats AI coding agents as first-class users: the package ships a version-matched guide at `node_modules/@foblex/flow/AI.md`, `ng add` writes workspace agent rules, and stable `FFxxxx` diagnostics give agents a concrete pass/fail signal. Before generating code, verify Foblex-specific selectors and APIs against that guide or the linked official reference; do not infer APIs from other node editor libraries.
+
+Choose the integration deliberately: classic mode keeps graph records in the application, while optional `provideFFlow(withFlowState())` provides typed managed records and undo/redo for supported operations. Verify generated flows using the APIs and `FFxxxx` diagnostics described in the shipped guide.
+
+[AI setup guide](https://flow.foblex.com/docs/ai) · [Full curated LLM-readable reference](https://flow.foblex.com/llms-full.txt)
+
 ## Why Foblex Flow
 
+- The most adopted node editor library built for Angular, by npm weekly downloads — maintained full-time since 2022 and used in production commercial products.
 - Easy starting path: most editors begin with `f-flow`, `f-canvas`, nodes, connectors, and connections.
 - Angular-first API that fits Angular apps instead of wrapping a React-style state model.
 - Built for real editor interactions: drag to connect, drag to reassign, selection, zoom, minimap, snapping, alignment helpers, and waypoints.
@@ -65,7 +74,7 @@ Current `19.x` releases target Angular `17.3+`. If your app is on Angular 12-17.
 | Integration   | Classic event-driven API with app-owned records, or optional `withFlowState()` managed records, snapshots, and undo/redo; SSR-safe, zoneless-ready                        |
 | AI tooling    | `llms.txt`, bundled `AI.md`, `ng add` writes agent rules, dev diagnostics with stable `FFxxxx` error codes                                                                |
 
-Coming from React Flow? Read the honest comparison: [React Flow vs Foblex Flow for Angular teams](https://flow.foblex.com/docs/react-flow-vs-foblex-flow-for-angular-teams).
+Comparing options? Read the honest comparisons: [React Flow vs Foblex Flow for Angular teams](https://flow.foblex.com/docs/react-flow-vs-foblex-flow-for-angular-teams) and [ngx-vflow vs Foblex Flow](https://flow.foblex.com/docs/ngx-vflow-vs-foblex-flow).
 
 ## Choose Your State Integration
 
@@ -191,7 +200,7 @@ That is the rendering mental model: `f-flow` hosts the editor, `f-canvas` pans a
 
 ### For AI Agents and LLMs
 
-- [llms.txt](https://flow.foblex.com/llms.txt) — docs index for agents; [llms-full.txt](https://flow.foblex.com/llms-full.txt) — complete LLM-readable API reference
+- [llms.txt](https://flow.foblex.com/llms.txt) — docs index for agents; [llms-full.txt](https://flow.foblex.com/llms-full.txt) — full curated LLM-readable reference
 - [AI usage guide](https://github.com/Foblex/f-flow/blob/main/libs/f-flow/AI.md) — strict code-generation rules, also shipped inside this package at `node_modules/@foblex/flow/AI.md`
 
 ## Community and Support