@squeed/flow-sdk 2.0.29 → 2.0.31

package/README.md

@@ -12,6 +12,42 @@ Requires React 18 and Chakra UI 3.36 or later. Peer dependencies: `react`, `reac
 
 The Markdown renderer is a required peer supplied by the consuming application, not embedded in the SDK bundle. It remains part of the application's dependency footprint.
 
+## Ownership And Code Patterns
+
+The dependency direction is **Squeed app -> public SDK API**. This package owns
+reusable diagram behavior, not application document storage, project ownership,
+authentication, navigation, or backend transport. Consumers retain changed
+documents and application state. See the
+[app pattern](../squeed/README.md#ownership-and-code-patterns) and
+[contribution rules](CONTRIBUTING.md).
+
+| Location                                           | Responsibility                                              |
+| -------------------------------------------------- | ----------------------------------------------------------- |
+| `src/core`                                         | Compilation, immutable document edits, and callback binding |
+| `src/engine`                                       | Geometry, layout, viewport, gestures, and canvas rendering  |
+| `src/components`, `src/nodes`                      | Public composition, shared controls, and node views         |
+| `src/types`, `src/hooks`, `src/theme`, `src/utils` | Contracts and existing shared support                       |
+| `src/index.ts`                                     | Consumer-facing exports; internal modules use local imports |
+| `examples`, `tests`                                | Consumer demonstrations, fixtures, and verification         |
+
+Reuse the existing owner of a behavior instead of adding a parallel helper or
+host-specific branch. Keep pure document operations independent of UI and
+storage. Prefer design/configuration defaults over imperative presentation fixes.
+JSON edits use the shared callback binding and emit one immutable document;
+raw graph consumers own their mutations. Preserve read-only restrictions.
+
+Use PascalCase for components/types, `use...` for hooks, and lower-camel-case
+module names for non-component operations. Use exported types at public
+boundaries, distinguish type-only dependencies from runtime dependencies, and
+avoid runtime import cycles. Document public contract changes and test the
+owning module plus affected consumer behavior.
+
+The current tree still has runtime cycles between `squeedEdits`/`parentGroups`
+and `NodeForm`/`StructuredFieldControls`. SDK examples and the app's local
+examples are not automatically synchronized or interchangeable contracts.
+These remain structural review items; passing behavior or release tests alone
+does not establish that the code follows this pattern.
+
 ## Quick Start
 
 ```tsx
@@ -208,7 +244,16 @@ Mark the visible shape with `data-flow-node-surface`, excluding captions and
 form summaries. For SVG views, put it on the closed geometry element (such as
 `circle`, `polygon`, or `path`), not the surrounding `svg`. Connectors, draw
 handles, and animated borders use that surface; layout still reserves the full
-node bounds. Unmarked custom views retain rectangular host bounds.
+node bounds. In `TB` and `BT`, ordinary icon-label connectors also reserve the
+caption below the icon, so paths and arrowheads do not cross wrapped labels or
+subtitles. Horizontal connectors still attach to the icon surface. Unmarked
+custom views retain rectangular host bounds.
+
+Edge-label placement is scoped to each canvas and skips empty label layers.
+The existing placement is reused while node bounds, edge paths, and label
+dimensions are unchanged. Geometry changes and font loading recheck placement;
+unrelated updates do not resample SVG paths. This does not change JSON loading,
+repair streaming, or playback.
 
 For content and custom-shape views, use `<FlowPort id="tools" role="source"
 side="bottom" position={0.5} />` inside the node. `side` accepts `top`, `right`,
@@ -592,6 +637,10 @@ engine.isolateBranch(nodeId, 60, true);
 engine.restoreView(true);
 ```
 
+Pass `true` as the fourth argument to `focusBranch`, `focusNode`, or
+`focusConnections` after a view toggle to fit the new geometry together with
+the layout animation. Existing three-argument calls keep their behavior.
+
 Animation defaults to false. Explicit false overrides the config default.
 Transitions interpolate pan and zoom over 300ms; center preserves zoom.
 Reduced-motion preferences disable animation. New viewport commands cancel
@@ -1196,6 +1245,11 @@ Helpers reuse untouched branches and do not fire callbacks themselves. The `upda
 
 ### Node Hover Overlay
 
+Reuse `config.nodeOverlayActions` for standard hover buttons. An action's optional
+`nodeTypes` array limits it to matching node types (for example, `["grid"]`).
+Omitting `nodeTypes` preserves the existing all-node behavior; actions continue
+to dispatch through `callbacks.onNodeHoverAction`.
+
 ```tsx
 import { HStack, IconButton } from "@chakra-ui/react";
 import { PiPencilSimple, PiTrash } from "react-icons/pi";