feat(flow): add managed state and v19.1 runtime improvements

.gitignore

@@ -17,3 +17,4 @@ tmp
 
 cypress/videos
 cypress/screenshots
+/docs/design/

CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [19.1.0](https://github.com/Foblex/f-flow/compare/v19.0.0...v19.1.0) (2026-07-13)
+
+### Highlights
+
+- **Managed Flow State:** opt into `provideFFlow(withFlowState())` to get typed node/group/connection signals, immutable programmatic mutations, automatic updates from supported gestures, batched undo/redo, viewport history, and persistable `load()`/`snapshot()` data. `injectFlowState<TNode, TConnection, TGroup>()` keeps application record fields typed without a `data` wrapper, and `stateClass` allows applications to override store behavior.
+- **Large-flow runtime work:** registry removals and store notifications are batched, connection redraws are scoped to affected geometry, minimap node geometry comes from cached model-space rectangles, pointer targeting uses DOM ancestry instead of scanning every node, connector border radii are cached, and connectable-side recalculation shares one scheduler.
+
+### Features
+
+- **shadow-dom:** support flows rendered inside Angular Elements and components using `ViewEncapsulation.ShadowDom`. Normal DOM events keep using `event.target`; document-level gestures fall back to the composed path only after Shadow DOM retargeting, and coordinate hit-testing enters open shadow roots. Closed shadow roots remain unsupported. Addresses [discussion #315](https://github.com/Foblex/f-flow/discussions/315).
+- **flow-state:** supported v1 gestures automatically update managed records for connection create/reassign, node/group movement, deletion, external-item creation, optional drop-to-group, selection, and canvas pan/zoom. One drag remains one history action even when selection and movement arrive in different ticks; `changes()` increments when the outer batch settles.
+- **flow-state:** add `historyLimit`, `selectionInHistory`, `canvasTransformInHistory`, `canvasTransformDebounce`, `dropToGroup`, `connectionFactory`, `nodeFactory`, and custom `stateClass` configuration.
+- **f-canvas:** `resetScaleAndCenter`, `fitToScreen`, and `centerGroupOrNode` now accept an optional `emitCanvasChange` argument. Pass `false` for initialization or another application-driven viewport change that must not enter external or managed history.
+- **f-draggable:** add the `fDropToGroup` toggle (gesture default remains `true`). Managed state applies the emitted reparenting only when its separate `dropToGroup` option is enabled; that state option defaults to `false`.
+
+### Performance
+
+- **connections:** redraw only connections affected by a changed node. A group geometry change also includes connections owned by descendant nodes, so grouped moves and state-driven restores remain correct without returning to a full redraw.
+- **minimap:** draw node rectangles from cached model-space geometry instead of measuring every node element on each pass, and reconcile rectangles by node id when batched registry updates settle.
+- **storage:** coalesce component-store notifications, batch registry removals, and compact retained registry snapshots outside the teardown loop.
+- **dragging:** resolve pointer targets through DOM ancestry, cache connector border radii used during geometry normalization, and share connectable-side recalculation scheduling across drag handlers.
+
+### Fixes
+
+- **node/group auto-size:** `fAutoSizeToFitChildren` now emits the final `fNodeSizeChange` / `fGroupSizeChange`, waits until child parent ids have settled before fitting, and removes stale explicit dimensions when a bound size is cleared.
+- **drag-to-group:** when a target uses both `fAutoExpandOnChildHit` and `fAutoSizeToFitChildren`, emit only the settled auto-fit size instead of a transient expanded size followed by the final one.
+
+### Documentation
+
+- Add a maintained zoneless Angular starter under `starters/minimal-flow` for StackBlitz and refresh the README, comparison, and use-case pages for the v19 API.
+
+### Managed state v1 scope
+
+- Rotation, connection waypoint editing, and user resize are not captured automatically in v1. Their existing outputs remain available for application-managed updates.
+- Automatic connection cascade on node/group removal resolves connector ownership from the rendered connector registry. Before connectors render (including immediate post-`load()` mutations and SSR), remove known attached connection ids explicitly inside the same `state.batch(...)`.
+
 ## [19.0.0](https://github.com/Foblex/f-flow/compare/v18.6.1...v19.0.0) (2026-07-05)
 
 ### Highlights

ROADMAP.md

@@ -7,31 +7,44 @@ This file now tracks two things in one place:
 - what is currently queued, in progress, or planned,
 - what has already shipped, based on published GitHub releases.
 
-This roadmap is synchronized with the release history through **v18.5.0 (2026-04-14)**.
+This roadmap is synchronized with the published release history through **v19.1.0 (2026-07-13)**.
 
 Stay up to date and help shape the future via [GitHub Discussions](https://github.com/Foblex/f-flow/discussions).
 
 ---
 
 ## Snapshot
 
-| Status                     | Item                                                 | Notes                                                                                                                                                                  |
-| -------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ✅ **Released in v18.5.0** | **Layout Engines + Reference Apps**                  | Shared layout integration surface with published Dagre and ELK adapters, explicit render lifecycle outputs, and major demos promoted to standalone apps.               |
-| 🚧 **In Progress**         | **Freeform Connections**                             | Unified `<f-connector>` replacing the input/output split — a single connector that can send, receive, or do both. [↗](https://github.com/Foblex/f-flow/discussions/88) |
-| 🧭 **Planned**             | **Smart Auto-Layout on Resize**                      | When a node expands or collapses, nearby nodes shift to keep the layout clean — no manual cleanup after a resize.                                                      |
-| 🧭 **Planned**             | **Path Highlighting**                                | Trace and highlight upstream, downstream, or full connected paths from any node. Class-based — your CSS defines the look.                                              |
-| 🧭 **Planned**             | **Flow Execution Animation**                         | Animate execution along the graph — from a predefined sequence or driven by real runtime events. Ideal for AI pipelines and live workflows.                            |
-| 🧭 **Planned**             | **Layer Ordering**                                   | Reorder built-in layers (groups, connections, nodes) to match your editor's visual style.                                                                              |
-| 🧭 **Planned**             | **Config-driven Architecture (`provideFoblexFlow`)** | Modern Angular provider API — `provideFoblexFlow(withMinimap(), withMagneticLines(), ...)`. Tree-shakeable, centralized, idiomatic.                                    |
-| 🧭 **Planned**             | **Grid-Aware Resize Handles**                        | Resize handles snap to gridlines for more precise editing. [↗](https://github.com/Foblex/f-flow/discussions/130)                                                       |
+| Status                     | Item                                  | Notes                                                                                                                                                                                                                              |
+| -------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ✅ **Released in v19.1.0** | **Managed Flow State**                | `provideFFlow(withFlowState())` adds typed graph records, automatic updates from supported gestures, batched undo/redo, viewport history, and persistable snapshots. See [examples/state](https://flow.foblex.com/examples/state). |
+| ✅ **Released in v19.1.0** | **Large-Flow Runtime Performance**    | Connection redraws are scoped to affected geometry, minimap and connector geometry are cached, registry work is batched, and drag hot paths no longer scan every node.                                                             |
+| ✅ **Released in v19.1.0** | **Angular Elements / Shadow DOM**     | Pointer gestures, connection targeting, and coordinate hit-testing now work when a flow is rendered in an open shadow root through Angular Elements or `ViewEncapsulation.ShadowDom`.                                              |
+| ✅ **Released in v19.0.0** | **Interaction Architecture**          | `provideFFlow(...)` gained control schemes, click-to-connect, and opt-in keyboard accessibility, with runtime controllers and configurable provider features.                                                                      |
+| ✅ **Released in v19.0.0** | **Unified Connectors and AI Tooling** | One `[fConnector]` model replaced the input/output split, while diagnostics, bundled agent guidance, and validated LLM documentation made integration failures easier to diagnose.                                                 |
+| ✅ **Released in v18.6.0** | **Resize Reflow and Layer Ordering**  | `withReflowOnResize` shifts nearby nodes as dimensions change, and `[fLayers]` / `withFCanvas({ layers })` configure the order of groups, connections, and nodes.                                                                  |
+| 🧭 **Planned**             | **Path Highlighting**                 | Trace and highlight upstream, downstream, or full connected paths from any node. Class-based - your CSS defines the look.                                                                                                          |
+| 🧭 **Planned**             | **Flow Execution Animation**          | Animate execution along the graph from a predefined sequence or real runtime events. Ideal for AI pipelines and live workflows.                                                                                                    |
+| 🧭 **Planned**             | **Grid-Aware Resize Handles**         | Resize handles snap to gridlines for more precise editing. [Discussion #130](https://github.com/Foblex/f-flow/discussions/130)                                                                                                     |
 
 ---
 
 ## Shipped Timeline
 
 ### 2026 Releases
 
+- **[v19.1.0](https://github.com/Foblex/f-flow/releases/tag/v19.1.0)** - **2026-07-13**
+  Shipped opt-in managed graph state with typed records and batched undo/redo, a broad large-flow runtime optimization pass, and pointer plus hit-testing support for Angular Elements and open Shadow DOM.
+
+- **[v19.0.0](https://github.com/Foblex/f-flow/releases/tag/v19.0.0)** - **2026-07-05**
+  Shipped provider-driven control schemes, click-to-connect, built-in ARIA semantics with opt-in keyboard editing, the unified `[fConnector]` API, stable diagnostics, and versioned AI-agent documentation.
+
+- **[v18.6.1](https://github.com/Foblex/f-flow/releases/tag/v18.6.1)** - **2026-05-14**
+  Removed synchronous connection-label measurements from redraw loops and prevented resize reflow from planning against partially applied node state.
+
+- **[v18.6.0](https://github.com/Foblex/f-flow/releases/tag/v18.6.0)** - **2026-04-26**
+  Shipped `withReflowOnResize` with configurable resize-driven layout updates, plus configurable canvas layer ordering through `[fLayers]` and `withFCanvas({ layers })`.
+
 - **[v18.5.0](https://github.com/Foblex/f-flow/releases/tag/v18.5.0)** - **2026-04-14**  
   Shipped the shared layout integration surface, published Dagre and ELK adapters, added explicit `fNodesRendered` / `fFullRendered` lifecycle outputs, promoted major demos into standalone reference apps, and strengthened the portal/docs toolchain.
 
@@ -104,6 +117,14 @@ Stay up to date and help shape the future via [GitHub Discussions](https://githu
 
 ---
 
+## Capability Map
+
+- **State and persistence**: `v19.1.0`, `v17.7.0`
+- **Performance and scale**: `v19.1.0`, `v18.6.1`, `v18.3.0`, `v18.2.0`, `v17.9.5`, `v12.5.0`
+- **Connection authoring and routing**: `v19.1.0`, `v19.0.0`, `v18.3.0`, `v18.0.0`, `17.8.5`, `v17.8.0`, `v16.0.0`, `V12.2.0`
+- **Editor UX and interactions**: `v19.1.0`, `v19.0.0`, `v18.6.0`, `v18.4.0`, `v18.1.0`, `v17.7.0`, `v17.6.0`, `v17.5.0`, `v17.4.0`, `v17.1.1`
+- **Platform and integration**: `v19.1.0`, `v19.0.0`, `v18.5.0`, `v18.4.0`, `v18.3.0`, `v16.0.0`, `v17.5.0`, `v18.1.0`
+
 ## Reading Guide
 
 - Use **Snapshot** if you want the current state of work.

apps/f-flow-portal-e2e/cypress/e2e/undo-redo-v2.cy.ts → apps/f-flow-portal-e2e/cypress/e2e/state.cy.ts

@@ -8,9 +8,9 @@ function getTranslate(transform: string): { x: number; y: number } {
   return { x: Number.parseFloat(match[1]), y: Number.parseFloat(match[2]) };
 }
 
-describe('UndoRedoV2', () => {
+describe('ManagedFlowState', () => {
   beforeEach(() => {
-    cy.visit('http://localhost:4200/examples/undo-redo-v2');
+    cy.visit('/examples/state');
     cy.get('f-flow').scrollIntoView();
   });