frameplot 0.5.0__tar.gz → 0.5.3__tar.gz

{frameplot-0.5.0/src/frameplot.egg-info → frameplot-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frameplot
-Version: 0.5.0
+Version: 0.5.3
 Summary: Turn Python-defined pipeline graphs into presentation-ready SVG and PNG diagrams.
 Author: Small Turtle 2
 License-Expression: MIT
@@ -46,13 +46,17 @@ Turn Python-defined pipeline graphs into presentation-ready SVG and PNG diagrams
 
 All built-in presets stay on a white canvas. The same hero pipeline is rendered below once per theme so you can compare them directly.
 
-| Soft Retro | Retro | Pastel |
-| --- | --- | --- |
-| ![Soft Retro theme hero](docs/assets/frameplot-hero-soft-retro.png) | ![Retro theme hero](docs/assets/frameplot-hero-retro.png) | ![Pastel theme hero](docs/assets/frameplot-hero-pastel.png) |
+| Soft Retro | Retro |
+| --- | --- |
+| ![Soft Retro theme hero](docs/assets/frameplot-hero-soft-retro.png) | ![Retro theme hero](docs/assets/frameplot-hero-retro.png) |
 
-| Dark | Cyberpunk | Monochrome |
-| --- | --- | --- |
-| ![Dark theme hero](docs/assets/frameplot-hero-dark.png) | ![Cyberpunk theme hero](docs/assets/frameplot-hero-cyberpunk.png) | ![Monochrome theme hero](docs/assets/frameplot-hero-monochrome.png) |
+| Research | Dark |
+| --- | --- |
+| ![Research theme hero](docs/assets/frameplot-hero-research.png) | ![Dark theme hero](docs/assets/frameplot-hero-dark.png) |
+
+| Cyberpunk | Monochrome |
+| --- | --- |
+| ![Cyberpunk theme hero](docs/assets/frameplot-hero-cyberpunk.png) | ![Monochrome theme hero](docs/assets/frameplot-hero-monochrome.png) |
 
 ## Why frameplot?
 
@@ -101,17 +105,41 @@ pipeline.save_png("pipeline.png")
 
 ![Quickstart result](docs/assets/quickstart.png)
 
+## Edge-to-Edge Joins
+
+```python
+from frameplot import Edge, Node, Pipeline
+
+pipeline = Pipeline(
+    nodes=[
+        Node("source", "Source", "Primary request"),
+        Node("worker", "Worker", "Prepare response"),
+        Node("audit", "Audit", "Write side log", fill="#DBEAFE"),
+        Node("done", "Done", "Return result", fill="#D9EAD3"),
+    ],
+    edges=[
+        Edge("e1", "source", "worker"),
+        Edge("e2", "worker", "done"),
+        Edge("e3", "audit", "e2", merge_symbol="+", color="#2563EB"),
+    ],
+)
+```
+
+![Edge join result](docs/assets/edge-join.png)
+
 ## Public API
 
 Top-level imports are the supported public API:
 
 - `Node(id, title, subtitle=None, fill=None, stroke=None, text_color=None, metadata=None, width=None, height=None)`
-- `Edge(id, source, target, color=None, dashed=False, metadata=None)`
+- `Edge(id, source, target, color=None, dashed=False, merge_symbol=None, metadata=None)`
 - `Group(id, label, node_ids, edge_ids=(), stroke=None, fill=None, metadata=None)`
 - `DetailPanel(id, focus_node_id, label, nodes, edges, groups=(), stroke=None, fill=None, metadata=None)`
 - `Theme(...)`
 - `Pipeline(nodes, edges, groups=(), detail_panel=None, theme=None)`
 
+`Edge.target` may reference either a node id or another edge id. When targeting another edge, `merge_symbol="+"` or `"x"` renders a join badge at the merge point.
+
 `Pipeline` exposes:
 
 - `to_svg() -> str`
@@ -130,7 +158,7 @@ The hero image at the top and the theme gallery above are generated from [`examp
 ## Design Notes
 
 - Layout is intentionally left-to-right in v0.x.
-- Edge labels are not supported yet.
+- Edge labels are not supported yet, but edge-to-edge joins can render optional `+` / `x` badges.
 - Groups stay visual overlays, and routes leaving or re-entering grouped nodes bend outside grouped areas.
 - Detail panels render as separate lower insets attached to a focus node in the main flow.
 

{frameplot-0.5.0 → frameplot-0.5.3}/README.md

@@ -17,13 +17,17 @@ Turn Python-defined pipeline graphs into presentation-ready SVG and PNG diagrams
 
 All built-in presets stay on a white canvas. The same hero pipeline is rendered below once per theme so you can compare them directly.
 
-| Soft Retro | Retro | Pastel |
-| --- | --- | --- |
-| ![Soft Retro theme hero](docs/assets/frameplot-hero-soft-retro.png) | ![Retro theme hero](docs/assets/frameplot-hero-retro.png) | ![Pastel theme hero](docs/assets/frameplot-hero-pastel.png) |
+| Soft Retro | Retro |
+| --- | --- |
+| ![Soft Retro theme hero](docs/assets/frameplot-hero-soft-retro.png) | ![Retro theme hero](docs/assets/frameplot-hero-retro.png) |
 
-| Dark | Cyberpunk | Monochrome |
-| --- | --- | --- |
-| ![Dark theme hero](docs/assets/frameplot-hero-dark.png) | ![Cyberpunk theme hero](docs/assets/frameplot-hero-cyberpunk.png) | ![Monochrome theme hero](docs/assets/frameplot-hero-monochrome.png) |
+| Research | Dark |
+| --- | --- |
+| ![Research theme hero](docs/assets/frameplot-hero-research.png) | ![Dark theme hero](docs/assets/frameplot-hero-dark.png) |
+
+| Cyberpunk | Monochrome |
+| --- | --- |
+| ![Cyberpunk theme hero](docs/assets/frameplot-hero-cyberpunk.png) | ![Monochrome theme hero](docs/assets/frameplot-hero-monochrome.png) |
 
 ## Why frameplot?
 
@@ -72,17 +76,41 @@ pipeline.save_png("pipeline.png")
 
 ![Quickstart result](docs/assets/quickstart.png)
 
+## Edge-to-Edge Joins
+
+```python
+from frameplot import Edge, Node, Pipeline
+
+pipeline = Pipeline(
+    nodes=[
+        Node("source", "Source", "Primary request"),
+        Node("worker", "Worker", "Prepare response"),
+        Node("audit", "Audit", "Write side log", fill="#DBEAFE"),
+        Node("done", "Done", "Return result", fill="#D9EAD3"),
+    ],
+    edges=[
+        Edge("e1", "source", "worker"),
+        Edge("e2", "worker", "done"),
+        Edge("e3", "audit", "e2", merge_symbol="+", color="#2563EB"),
+    ],
+)
+```
+
+![Edge join result](docs/assets/edge-join.png)
+
 ## Public API
 
 Top-level imports are the supported public API:
 
 - `Node(id, title, subtitle=None, fill=None, stroke=None, text_color=None, metadata=None, width=None, height=None)`
-- `Edge(id, source, target, color=None, dashed=False, metadata=None)`
+- `Edge(id, source, target, color=None, dashed=False, merge_symbol=None, metadata=None)`
 - `Group(id, label, node_ids, edge_ids=(), stroke=None, fill=None, metadata=None)`
 - `DetailPanel(id, focus_node_id, label, nodes, edges, groups=(), stroke=None, fill=None, metadata=None)`
 - `Theme(...)`
 - `Pipeline(nodes, edges, groups=(), detail_panel=None, theme=None)`
 
+`Edge.target` may reference either a node id or another edge id. When targeting another edge, `merge_symbol="+"` or `"x"` renders a join badge at the merge point.
+
 `Pipeline` exposes:
 
 - `to_svg() -> str`
@@ -101,7 +129,7 @@ The hero image at the top and the theme gallery above are generated from [`examp
 ## Design Notes
 
 - Layout is intentionally left-to-right in v0.x.
-- Edge labels are not supported yet.
+- Edge labels are not supported yet, but edge-to-edge joins can render optional `+` / `x` badges.
 - Groups stay visual overlays, and routes leaving or re-entering grouped nodes bend outside grouped areas.
 - Detail panels render as separate lower insets attached to a focus node in the main flow.
 

{frameplot-0.5.0 → frameplot-0.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "frameplot"
-version = "0.5.0"
+version = "0.5.3"
 description = "Turn Python-defined pipeline graphs into presentation-ready SVG and PNG diagrams."
 readme = "README.md"
 requires-python = ">=3.11"

{frameplot-0.5.0 → frameplot-0.5.3}/src/frameplot/layout/__init__.py

@@ -38,8 +38,14 @@ class _GroupSpacingInfo:
     group_node_ids: frozenset[str]
     min_rank: int
     max_rank: int
+    min_row: int
+    max_row: int
+    member_top: float
+    member_bottom: float
     member_left: float
     member_right: float
+    top_inside_clearance: float
+    bottom_inside_clearance: float
     left_inside_clearance: float
     right_inside_clearance: float
 
@@ -77,6 +83,8 @@ def _layout_graph(validated: "ValidatedPipeline | ValidatedDetailPanel") -> Grap
     ranks = assign_ranks(validated, scc_result)
     order = order_nodes(validated, ranks)
     rank_gap_overrides: dict[tuple[int, int], float] | None = None
+    row_gap_overrides: dict[tuple[int, int], float] | None = None
+    row_gap_floor = resolve_theme_metrics(validated.theme).compact_rank_gap
 
     for _ in range(MAX_LAYOUT_STABILIZATION_PASSES):
         placed_nodes = place_nodes(
@@ -85,13 +93,20 @@ def _layout_graph(validated: "ValidatedPipeline | ValidatedDetailPanel") -> Grap
             ranks,
             order,
             rank_gap_overrides=rank_gap_overrides,
+            row_gap_overrides=row_gap_overrides,
+            row_gap_floor=row_gap_floor,
         )
         routed_edges = route_edges(validated, placed_nodes)
         overlays = compute_group_overlays(validated, placed_nodes, routed_edges)
-        next_overrides = _rank_gap_overrides(validated, placed_nodes, routed_edges, overlays)
-        if next_overrides == (rank_gap_overrides or {}):
+        next_rank_overrides = _rank_gap_overrides(validated, placed_nodes, routed_edges, overlays)
+        next_row_overrides = _row_gap_overrides(validated, placed_nodes, routed_edges, overlays)
+        if (
+            next_rank_overrides == (rank_gap_overrides or {})
+            and next_row_overrides == (row_gap_overrides or {})
+        ):
             break
-        rank_gap_overrides = next_overrides or None
+        rank_gap_overrides = next_rank_overrides or None
+        row_gap_overrides = next_row_overrides or None
 
     return _normalize_graph_layout(placed_nodes, routed_edges, overlays, validated.theme)
 
@@ -107,7 +122,7 @@ def _rank_gap_overrides(
     base_gap = metrics.compact_rank_gap
     geometry_by_component = _build_component_geometry(placed_nodes, theme)
     required_gaps: dict[tuple[int, int], float] = {}
-    used_lane_positions: dict[tuple[int, int], set[float]] = {}
+    used_lane_positions: dict[tuple[int, int], set[tuple[str, float]]] = {}
 
     for component_id, geometry in geometry_by_component.items():
         for left_rank in geometry.gap_after_rank:
@@ -122,13 +137,18 @@ def _rank_gap_overrides(
             x = round(start.x, 2)
             for left_rank, (gap_start, gap_end) in geometry.gap_after_rank.items():
                 if gap_start + 0.01 < x < gap_end - 0.01:
-                    used_lane_positions[(component_id, left_rank)].add(x)
+                    used_lane_positions[(component_id, left_rank)].add((routed_edge.edge.id, x))
 
     overrides: dict[tuple[int, int], float] = {}
-    for key, lane_positions in used_lane_positions.items():
-        if len(lane_positions) <= 1:
+    for key, lane_entries in used_lane_positions.items():
+        if len(lane_entries) <= 1:
             continue
-        required_gap = base_gap + max(lane_positions) - min(lane_positions)
+        lane_positions = sorted(position for _, position in lane_entries)
+        required_span = max(
+            lane_positions[-1] - lane_positions[0],
+            theme.route_track_gap * len(lane_positions),
+        )
+        required_gap = base_gap + required_span
         if required_gap > base_gap + EPSILON:
             required_gaps[key] = round(required_gap, 2)
 
@@ -139,6 +159,13 @@ def _rank_gap_overrides(
     ).items():
         required_gaps[key] = round(max(required_gaps.get(key, 0.0), required_gap), 2)
 
+    for key, required_gap in _join_target_gap_requirements(
+        validated,
+        placed_nodes,
+        routed_edges,
+    ).items():
+        required_gaps[key] = round(max(required_gaps.get(key, 0.0), required_gap), 2)
+
     for key, required_gap in required_gaps.items():
         if required_gap > base_gap + EPSILON:
             overrides[key] = round(required_gap, 2)
@@ -146,6 +173,114 @@ def _rank_gap_overrides(
     return overrides
 
 
+def _row_gap_overrides(
+    validated: "ValidatedPipeline | ValidatedDetailPanel",
+    placed_nodes: dict[str, LayoutNode],
+    routed_edges: tuple[RoutedEdge, ...],
+    overlays: tuple[GroupOverlay, ...],
+) -> dict[tuple[int, int], float]:
+    theme = validated.theme
+    base_gap = resolve_theme_metrics(theme).compact_rank_gap
+    geometry_by_component = _build_component_geometry(placed_nodes, theme)
+    used_lane_positions: dict[tuple[int, int], set[tuple[str, float]]] = {}
+    required_gaps: dict[tuple[int, int], float] = {}
+
+    for component_id, geometry in geometry_by_component.items():
+        for upper_row in geometry.gap_after_row:
+            used_lane_positions[(component_id, upper_row)] = set()
+
+    for routed_edge in routed_edges:
+        component_id = placed_nodes[routed_edge.edge.source].component_id
+        geometry = geometry_by_component[component_id]
+        for start, end in zip(routed_edge.points, routed_edge.points[1:]):
+            if start.y != end.y:
+                continue
+            y = round(start.y, 2)
+            for upper_row, (gap_start, gap_end) in geometry.gap_after_row.items():
+                if gap_start + EPSILON < y < gap_end - EPSILON:
+                    used_lane_positions[(component_id, upper_row)].add((routed_edge.edge.id, y))
+
+    for key, lane_entries in used_lane_positions.items():
+        if not lane_entries:
+            continue
+        lane_positions = sorted(position for _, position in lane_entries)
+        occupied_span = lane_positions[-1] - lane_positions[0]
+        required_gap = max(base_gap, occupied_span + theme.route_track_gap)
+        if required_gap > base_gap + EPSILON:
+            required_gaps[key] = round(required_gap, 2)
+
+    for key, required_gap in _group_row_boundary_gap_requirements(
+        placed_nodes,
+        overlays,
+        geometry_by_component,
+    ).items():
+        required_gaps[key] = round(max(required_gaps.get(key, 0.0), required_gap), 2)
+
+    return {
+        key: round(required_gap, 2)
+        for key, required_gap in required_gaps.items()
+        if required_gap > base_gap + EPSILON
+    }
+
+
+def _join_target_gap_requirements(
+    validated: "ValidatedPipeline | ValidatedDetailPanel",
+    placed_nodes: dict[str, LayoutNode],
+    routed_edges: tuple[RoutedEdge, ...],
+) -> dict[tuple[int, int], float]:
+    route_by_id = {route.edge.id: route for route in routed_edges}
+    joins_by_target_segment: dict[tuple[str, int], list[RoutedEdge]] = {}
+
+    for routed_edge in routed_edges:
+        if routed_edge.target_kind != "edge" or routed_edge.target_edge_id is None:
+            continue
+        if routed_edge.join_segment_index is None:
+            continue
+        joins_by_target_segment.setdefault(
+            (routed_edge.target_edge_id, routed_edge.join_segment_index),
+            [],
+        ).append(routed_edge)
+
+    required_gaps: dict[tuple[int, int], float] = {}
+    badge_diameter = max(validated.theme.arrow_size * 1.8, validated.theme.stroke_width * 6.0)
+    join_spacing = max(validated.theme.arrow_size * 1.5, validated.theme.stroke_width * 6.0)
+
+    for (target_edge_id, join_segment_index), joins in joins_by_target_segment.items():
+        target_edge = validated.edge_lookup[target_edge_id]
+        target_target = validated.edge_targets[target_edge_id]
+        source_node = placed_nodes[target_edge.source]
+        target_node = placed_nodes[target_target.node_id]
+        target_route = route_by_id.get(target_edge_id)
+        if target_route is None:
+            continue
+        if source_node.component_id != target_node.component_id:
+            continue
+        if source_node.rank >= target_node.rank or source_node.order != target_node.order:
+            continue
+        if join_segment_index >= len(target_route.points) - 1:
+            continue
+
+        start = target_route.points[join_segment_index]
+        end = target_route.points[join_segment_index + 1]
+        if start.y != end.y:
+            continue
+
+        current_segment_length = abs(end.x - start.x)
+        required_segment_length = (
+            validated.theme.route_track_gap
+            + badge_diameter * len(joins)
+            + join_spacing * max(0, len(joins) - 1)
+        )
+        if current_segment_length >= required_segment_length - EPSILON:
+            continue
+
+        required_gap = validated.theme.route_track_gap + (required_segment_length - current_segment_length)
+        key = (source_node.component_id, source_node.rank)
+        required_gaps[key] = max(required_gaps.get(key, 0.0), round(required_gap, 2))
+
+    return required_gaps
+
+
 def _group_boundary_gap_requirements(
     placed_nodes: dict[str, LayoutNode],
     overlays: tuple[GroupOverlay, ...],
@@ -217,6 +352,8 @@ def _build_group_spacing_infos(
         if not overlay.group.node_ids:
             continue
         member_nodes = [placed_nodes[node_id] for node_id in overlay.group.node_ids]
+        member_top = min(node.y for node in member_nodes)
+        member_bottom = max(node.bounds.bottom for node in member_nodes)
         member_left = min(node.x for node in member_nodes)
         member_right = max(node.right for node in member_nodes)
         infos.append(
@@ -226,8 +363,14 @@ def _build_group_spacing_infos(
                 group_node_ids=frozenset(overlay.group.node_ids),
                 min_rank=min(node.rank for node in member_nodes),
                 max_rank=max(node.rank for node in member_nodes),
+                min_row=min(node.order for node in member_nodes),
+                max_row=max(node.order for node in member_nodes),
+                member_top=member_top,
+                member_bottom=member_bottom,
                 member_left=member_left,
                 member_right=member_right,
+                top_inside_clearance=member_top - overlay.bounds.y,
+                bottom_inside_clearance=overlay.bounds.bottom - member_bottom,
                 left_inside_clearance=member_left - overlay.bounds.x,
                 right_inside_clearance=overlay.bounds.right - member_right,
             )
@@ -236,6 +379,52 @@ def _build_group_spacing_infos(
     return tuple(infos)
 
 
+def _group_row_boundary_gap_requirements(
+    placed_nodes: dict[str, LayoutNode],
+    overlays: tuple[GroupOverlay, ...],
+    geometry_by_component: dict[int, "ComponentGeometry"],
+) -> dict[tuple[int, int], float]:
+    required_gaps: dict[tuple[int, int], float] = {}
+    group_infos = _build_group_spacing_infos(placed_nodes, overlays)
+
+    for info in group_infos:
+        geometry = geometry_by_component.get(info.component_id)
+        if geometry is None:
+            continue
+
+        upper_row = _previous_row(geometry, info.min_row)
+        top_outside_node = _nearest_outside_node_by_row(
+            placed_nodes,
+            bounds=info.bounds,
+            component_id=info.component_id,
+            group_node_ids=info.group_node_ids,
+            row_predicate=lambda row: row < info.min_row,
+            side="top",
+        )
+        if upper_row is not None and top_outside_node is not None:
+            required_gaps[(info.component_id, upper_row)] = round(
+                max(required_gaps.get((info.component_id, upper_row), 0.0), info.top_inside_clearance * 2.0),
+                2,
+            )
+
+        lower_row = info.max_row
+        bottom_outside_node = _nearest_outside_node_by_row(
+            placed_nodes,
+            bounds=info.bounds,
+            component_id=info.component_id,
+            group_node_ids=info.group_node_ids,
+            row_predicate=lambda row: row > info.max_row,
+            side="bottom",
+        )
+        if lower_row in geometry.gap_after_row and bottom_outside_node is not None:
+            required_gaps[(info.component_id, lower_row)] = round(
+                max(required_gaps.get((info.component_id, lower_row), 0.0), info.bottom_inside_clearance * 2.0),
+                2,
+            )
+
+    return required_gaps
+
+
 def _nearest_outside_node(
     placed_nodes: dict[str, LayoutNode],
     *,
@@ -267,6 +456,37 @@ def _nearest_outside_node(
     return candidate
 
 
+def _nearest_outside_node_by_row(
+    placed_nodes: dict[str, LayoutNode],
+    *,
+    bounds: Bounds,
+    component_id: int,
+    group_node_ids: frozenset[str],
+    row_predicate: Callable[[int], bool],
+    side: str,
+) -> LayoutNode | None:
+    candidate: LayoutNode | None = None
+
+    for node_id, node in placed_nodes.items():
+        if node.component_id != component_id:
+            continue
+        if node_id in group_node_ids:
+            continue
+        if not row_predicate(node.order):
+            continue
+        if not _bounds_overlap_horizontally(bounds, node.bounds):
+            continue
+        if candidate is None:
+            candidate = node
+            continue
+        if side == "top" and node.bounds.bottom > candidate.bounds.bottom:
+            candidate = node
+        if side == "bottom" and node.y < candidate.y:
+            candidate = node
+
+    return candidate
+
+
 def _nearest_group_neighbor(
     info: _GroupSpacingInfo,
     group_infos: tuple[_GroupSpacingInfo, ...],
@@ -299,6 +519,10 @@ def _bounds_overlap_vertically(first: Bounds, second: Bounds) -> bool:
     return min(first.bottom, second.bottom) - max(first.y, second.y) > EPSILON
 
 
+def _bounds_overlap_horizontally(first: Bounds, second: Bounds) -> bool:
+    return min(first.right, second.right) - max(first.x, second.x) > EPSILON
+
+
 def _previous_rank(geometry: "ComponentGeometry", rank: int) -> int | None:
     candidates = [candidate_rank for candidate_rank in geometry.rank_right if candidate_rank < rank]
     if not candidates:
@@ -306,6 +530,13 @@ def _previous_rank(geometry: "ComponentGeometry", rank: int) -> int | None:
     return max(candidates)
 
 
+def _previous_row(geometry: "ComponentGeometry", row: int) -> int | None:
+    candidates = [candidate_row for candidate_row in geometry.row_bottom if candidate_row < row]
+    if not candidates:
+        return None
+    return max(candidates)
+
+
 def _normalize_graph_layout(
     placed_nodes: dict[str, LayoutNode],
     routed_edges: tuple[RoutedEdge, ...],
@@ -506,6 +737,22 @@ def _shift_edge(route: RoutedEdge, shift_x: float, shift_y: float) -> RoutedEdge
             height=route.bounds.height,
         ),
         stroke=route.stroke,
+        target_kind=route.target_kind,
+        target_node_id=route.target_node_id,
+        target_edge_id=route.target_edge_id,
+        join_point=(
+            Point(route.join_point.x + shift_x, route.join_point.y + shift_y)
+            if route.join_point is not None
+            else None
+        ),
+        badge_center=(
+            Point(route.badge_center.x + shift_x, route.badge_center.y + shift_y)
+            if route.badge_center is not None
+            else None
+        ),
+        join_segment_index=route.join_segment_index,
+        show_arrowhead=route.show_arrowhead,
+        join_badge_radius=route.join_badge_radius,
     )