frameplot 0.5.3__tar.gz → 0.5.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frameplot
-Version: 0.5.3
+Version: 0.5.6
 Summary: Turn Python-defined pipeline graphs into presentation-ready SVG and PNG diagrams.
 Author: Small Turtle 2
 License-Expression: MIT
@@ -147,6 +147,12 @@ Top-level imports are the supported public API:
 - `to_png_bytes(scale=4.0) -> bytes`
 - `save_png(path, scale=4.0) -> None`
 
+## Modeling Guidance
+
+- Keep the main graph at one abstraction level. Frameplot lays the pipeline out as a dependency-driven left-to-right graph, not as a freeform block diagram.
+- Use `DetailPanel` for repeated block internals or per-stage mechanics that would otherwise create long-range edges in the main graph.
+- Use `Group` to highlight nearby related nodes, not to force distant nodes to stay together. Groups are visual overlays and routing obstacles, so very wide groups can increase route detours.
+
 ## Advanced Example: Multi-cloud Data Pipeline
 
 The hero image at the top and the theme gallery above are generated from [`examples/theme_heroes.py`](https://github.com/smturtle2/frameplot/blob/main/examples/theme_heroes.py), using the shared pipeline definition in [`examples/hero_pipeline.py`](https://github.com/smturtle2/frameplot/blob/main/examples/hero_pipeline.py). Together they showcase:
@@ -161,6 +167,7 @@ The hero image at the top and the theme gallery above are generated from [`examp
 - 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.
+- If a sample looks stretched or routes far outside the intended block, the graph usually mixes stage-level flow with internal logic in one plane; move the internals into a `DetailPanel`.
 
 ## Development
 

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

@@ -118,6 +118,12 @@ Top-level imports are the supported public API:
 - `to_png_bytes(scale=4.0) -> bytes`
 - `save_png(path, scale=4.0) -> None`
 
+## Modeling Guidance
+
+- Keep the main graph at one abstraction level. Frameplot lays the pipeline out as a dependency-driven left-to-right graph, not as a freeform block diagram.
+- Use `DetailPanel` for repeated block internals or per-stage mechanics that would otherwise create long-range edges in the main graph.
+- Use `Group` to highlight nearby related nodes, not to force distant nodes to stay together. Groups are visual overlays and routing obstacles, so very wide groups can increase route detours.
+
 ## Advanced Example: Multi-cloud Data Pipeline
 
 The hero image at the top and the theme gallery above are generated from [`examples/theme_heroes.py`](https://github.com/smturtle2/frameplot/blob/main/examples/theme_heroes.py), using the shared pipeline definition in [`examples/hero_pipeline.py`](https://github.com/smturtle2/frameplot/blob/main/examples/hero_pipeline.py). Together they showcase:
@@ -132,6 +138,7 @@ The hero image at the top and the theme gallery above are generated from [`examp
 - 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.
+- If a sample looks stretched or routes far outside the intended block, the graph usually mixes stage-level flow with internal logic in one plane; move the internals into a `DetailPanel`.
 
 ## Development
 

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

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

{frameplot-0.5.3 → frameplot-0.5.6}/src/frameplot/api.py

@@ -19,8 +19,12 @@ class Pipeline:
     """Describe and render a pipeline diagram.
 
     The constructor accepts any iterable of nodes, edges, and groups, then
-    normalizes them to tuples for deterministic rendering. Passing `theme=None`
-    uses the default :class:`Theme`.
+    normalizes them to tuples for deterministic rendering. The main graph uses
+    dependency-driven left-to-right auto-layout, so it works best when kept to
+    one abstraction level. If stage flow and internal mechanics are mixed into
+    the same graph, ranks can stretch and routes can become unexpectedly long;
+    move those internals into a :class:`DetailPanel` instead. Passing
+    `theme=None` uses the default :class:`Theme`.
     """
 
     nodes: tuple[Node, ...]

{frameplot-0.5.3 → frameplot-0.5.6}/src/frameplot/layout/order.py

@@ -33,9 +33,6 @@ def order_nodes(
             _resort_rank(nodes_by_rank[rank], outgoing, order, validated)
             _refresh_order(nodes_by_rank[rank], order)
 
-    if isinstance(validated, ValidatedDetailPanel):
-        _apply_detail_panel_shared_source_lanes(validated, ranks, order)
-
     if isinstance(validated, ValidatedPipeline) and validated.detail_panel is not None:
         _apply_detail_panel_bias(validated, nodes_by_rank, ranks, order)
 
@@ -120,126 +117,6 @@ def _apply_detail_panel_bias(
         for index, node_id in enumerate(rank_focus_nodes):
             order[node_id] = start_row + index
 
-
-def _apply_detail_panel_shared_source_lanes(
-    validated: ValidatedDetailPanel,
-    ranks: dict[str, int],
-    order: dict[str, int],
-) -> None:
-    group_membership = _group_membership(validated)
-    components = _weak_components(validated)
-    incoming, outgoing = _forward_neighbors(validated, ranks)
-
-    for component_nodes in components:
-        component_set = set(component_nodes)
-        shared_sources = [
-            node_id
-            for node_id in component_nodes
-            if _is_detail_panel_shared_source(
-                node_id,
-                component_set,
-                group_membership,
-                incoming,
-                outgoing,
-                order,
-            )
-        ]
-        if not shared_sources:
-            continue
-
-        shared_sources.sort(key=lambda node_id: (order[node_id], validated.node_index[node_id], node_id))
-        shared_source_ids = set(shared_sources)
-        nonshared_rows = _reorder_component_nodes(
-            validated,
-            ranks,
-            component_set - shared_source_ids,
-        )
-
-        for index, node_id in enumerate(shared_sources):
-            order[node_id] = index
-        for node_id, row in nonshared_rows.items():
-            order[node_id] = row + len(shared_sources)
-
-
-def _is_detail_panel_shared_source(
-    node_id: str,
-    component_nodes: set[str],
-    group_membership: dict[str, tuple[str, ...]],
-    incoming: dict[str, list[str]],
-    outgoing: dict[str, list[str]],
-    order: dict[str, int],
-) -> bool:
-    if group_membership.get(node_id):
-        return False
-    if incoming.get(node_id):
-        return False
-
-    targets = [target_id for target_id in outgoing.get(node_id, ()) if target_id in component_nodes]
-    if len(set(targets)) < 2:
-        return False
-
-    downstream_lanes = {
-        (
-            order[target_id],
-            group_membership.get(target_id, ()),
-        )
-        for target_id in targets
-    }
-    return len(downstream_lanes) >= 2
-
-
-def _group_membership(
-    validated: ValidatedPipeline | ValidatedDetailPanel,
-) -> dict[str, tuple[str, ...]]:
-    memberships: dict[str, list[str]] = defaultdict(list)
-    for group in validated.groups:
-        for node_id in group.node_ids:
-            memberships[node_id].append(group.id)
-    return {
-        node_id: tuple(sorted(group_ids))
-        for node_id, group_ids in memberships.items()
-    }
-
-
-def _reorder_component_nodes(
-    validated: ValidatedPipeline | ValidatedDetailPanel,
-    ranks: dict[str, int],
-    included_node_ids: set[str],
-) -> dict[str, int]:
-    if not included_node_ids:
-        return {}
-
-    nodes_by_rank: dict[int, list[str]] = defaultdict(list)
-    for node_id in included_node_ids:
-        nodes_by_rank[ranks[node_id]].append(node_id)
-
-    for rank_nodes in nodes_by_rank.values():
-        rank_nodes.sort(key=validated.node_index.__getitem__)
-
-    local_order = {
-        node_id: index
-        for rank_nodes in nodes_by_rank.values()
-        for index, node_id in enumerate(rank_nodes)
-    }
-
-    incoming, outgoing = _forward_neighbors(
-        validated,
-        ranks,
-        included_node_ids=included_node_ids,
-    )
-    ordered_ranks = sorted(nodes_by_rank)
-
-    for _ in range(4):
-        for rank in ordered_ranks[1:]:
-            _resort_rank(nodes_by_rank[rank], incoming, local_order, validated)
-            _refresh_order(nodes_by_rank[rank], local_order)
-        for rank in reversed(ordered_ranks[:-1]):
-            _resort_rank(nodes_by_rank[rank], outgoing, local_order, validated)
-            _refresh_order(nodes_by_rank[rank], local_order)
-
-    return local_order
-
-
 def _detail_focus_path_nodes(
     validated: ValidatedPipeline,
     ranks: dict[str, int],

{frameplot-0.5.3 → frameplot-0.5.6}/src/frameplot/layout/route.py

@@ -810,7 +810,9 @@ def _select_forward_route(
         target_node.node.id,
         routing_groups,
     )
-    evaluations: list[tuple[bool, tuple[int, int, int, float, float, int, float, int, float, int], CandidatePath]] = []
+    evaluations: list[
+        tuple[bool, tuple[int, int, int, int, float, float, int, float, int, float, int], CandidatePath]
+    ] = []
 
     for candidate_index, (kind, candidate) in enumerate(candidates):
         clearance_ok = _path_respects_group_clearance(
@@ -1560,7 +1562,7 @@ def _select_candidate_with_priority(
     evaluations: list[
         tuple[
             bool,
-            tuple[int, int, int, float, float, int, float, int, float, int],
+            tuple[int, int, int, int, float, float, int, float, int, float, int],
             CandidatePath,
         ]
     ],
@@ -1748,7 +1750,7 @@ def _forward_priority_key(
     theme: "Theme",
     has_relevant_groups: bool,
     interactions: InteractionMetrics,
-) -> tuple[int, int, int, float, float, int, float, int, float, int]:
+) -> tuple[int, int, int, int, float, float, int, float, int, float, int]:
     collisions, backwards, bends, length = _route_metrics(
         candidate,
         nodes=nodes,
@@ -1758,6 +1760,16 @@ def _forward_priority_key(
     return (
         interactions.edge_crossings,
         collisions,
+        _clean_direct_elbow_priority(
+            kind,
+            collisions=collisions,
+            backwards=backwards,
+            bends=bends,
+            has_relevant_groups=has_relevant_groups,
+            interactions=interactions,
+            source_node=source_node,
+            target_node=target_node,
+        ),
         _forward_side_change_penalty(kind, has_relevant_groups=has_relevant_groups),
         interactions.edge_overlap_length,
         interactions.obstacle_overlap_length,
@@ -1775,6 +1787,30 @@ def _forward_priority_key(
     )
 
 
+def _clean_direct_elbow_priority(
+    kind: str,
+    *,
+    collisions: int,
+    backwards: float,
+    bends: int,
+    has_relevant_groups: bool,
+    interactions: InteractionMetrics,
+    source_node: LayoutNode,
+    target_node: LayoutNode,
+) -> int:
+    if kind != "direct_elbow" or has_relevant_groups:
+        return 1
+    if source_node.order >= target_node.order:
+        return 1
+    if collisions != 0 or bends != 1 or backwards > EPSILON:
+        return 1
+    if interactions.edge_crossings != 0 or interactions.edge_overlap_length > EPSILON:
+        return 1
+    if interactions.obstacle_overlap_length > EPSILON or interactions.obstacle_crossings != 0:
+        return 1
+    return 0
+
+
 def _forward_kind_priority(
     kind: str,
     *,

{frameplot-0.5.3 → frameplot-0.5.6}/src/frameplot/layout/text.py

@@ -64,14 +64,20 @@ def measure_text(validated: ValidatedPipeline) -> dict[str, MeasuredText]:
 def _wrap(value: str | None, width: int) -> list[str]:
     if not value:
         return []
-    wrapped = textwrap.wrap(
-        value,
-        width=width,
-        break_long_words=True,
-        break_on_hyphens=False,
-        drop_whitespace=True,
-    )
-    return wrapped or [value]
+    lines: list[str] = []
+    for explicit_line in value.splitlines() or [value]:
+        if explicit_line == "":
+            lines.append("")
+            continue
+        wrapped = textwrap.wrap(
+            explicit_line,
+            width=width,
+            break_long_words=True,
+            break_on_hyphens=False,
+            drop_whitespace=True,
+        )
+        lines.extend(wrapped or [explicit_line])
+    return lines
 
 
 def _max_line_width(lines: tuple[str, ...], font_size: float, ratio: float) -> float:

{frameplot-0.5.3 → frameplot-0.5.6}/src/frameplot/model.py

@@ -76,9 +76,10 @@ class Edge:
 class Group:
     """Highlight related nodes or edges with a labeled overlay.
 
-    Groups stay visual first, but routes leaving or re-entering grouped nodes
-    bend outside the grouped area. At least one node or edge reference is
-    required.
+    Groups stay visual first: they do not pin members together or force a
+    compact cluster. Layout still follows dependency ranks, and routes leaving
+    or re-entering grouped nodes bend outside the grouped area. At least one
+    node or edge reference is required.
     """
 
     id: str
@@ -106,8 +107,10 @@ class Group:
 class DetailPanel:
     """Expand a focus node into a lower inset with its own mini-graph.
 
-    The focus node must exist in the main pipeline graph, and the panel must
-    contain at least one node.
+    Use a detail panel when a node's internal mechanics would otherwise add
+    long-range or cross-level edges to the main graph. The focus node must
+    exist in the main pipeline graph, and the panel must contain at least one
+    node.
     """
 
     id: str

{frameplot-0.5.3 → frameplot-0.5.6}/src/frameplot/render/svg.py

@@ -51,7 +51,7 @@ def render_svg(layout: LayoutResult, theme: Theme) -> str:
     )
 
     group_layer = ET.SubElement(root, ET.QName(SVG_NS, "g"), attrib={"id": "groups"})
-    _render_groups(group_layer, layout.main, theme, metrics)
+    _render_group_shapes(group_layer, layout.main, theme, metrics)
 
     if layout.detail_panel is not None:
         guide_layer = ET.SubElement(root, ET.QName(SVG_NS, "g"), attrib={"id": "detail-panel-guides"})
@@ -62,8 +62,8 @@ def render_svg(layout: LayoutResult, theme: Theme) -> str:
             ET.QName(SVG_NS, "g"),
             attrib={"id": f"detail-panel-{layout.detail_panel.panel.id}"},
         )
-        _render_detail_panel_container(panel_layer, layout.detail_panel, theme, metrics)
-        _render_groups(panel_layer, layout.detail_panel.graph, theme, metrics)
+        _render_detail_panel_container_shape(panel_layer, layout.detail_panel, theme, metrics)
+        _render_group_shapes(panel_layer, layout.detail_panel.graph, theme, metrics)
 
     edge_layer = ET.SubElement(root, ET.QName(SVG_NS, "g"), attrib={"id": "edges"})
     _render_edges(edge_layer, layout.main.edges, marker_ids, theme, metrics)
@@ -86,6 +86,12 @@ def render_svg(layout: LayoutResult, theme: Theme) -> str:
             id_prefix=f"detail-panel-{layout.detail_panel.panel.id}-",
         )
 
+    label_layer = ET.SubElement(root, ET.QName(SVG_NS, "g"), attrib={"id": "labels"})
+    _render_group_labels(label_layer, layout.main, theme, metrics)
+    if layout.detail_panel is not None:
+        _render_detail_panel_title(label_layer, layout.detail_panel, theme, metrics)
+        _render_group_labels(label_layer, layout.detail_panel.graph, theme, metrics)
+
     return ET.tostring(root, encoding="unicode")
 
 
@@ -142,7 +148,7 @@ def _build_shadow_filter(defs: ET.Element, metrics: ResolvedThemeMetrics) -> Non
     ET.SubElement(merge, ET.QName(SVG_NS, "feMergeNode"), attrib={"in": "SourceGraphic"})
 
 
-def _render_groups(
+def _render_group_shapes(
     parent: ET.Element,
     graph: GraphLayout,
     theme: Theme,
@@ -180,18 +186,28 @@ def _render_groups(
                     "stroke-linecap": "round",
                 },
             )
-        ET.SubElement(
+
+
+def _render_group_labels(
+    parent: ET.Element,
+    graph: GraphLayout,
+    theme: Theme,
+    metrics: ResolvedThemeMetrics,
+) -> None:
+    for overlay in graph.groups:
+        _render_label_text(
             parent,
-            ET.QName(SVG_NS, "text"),
-            attrib={
-                "x": _fmt(overlay.bounds.x + theme.group_padding),
-                "y": _fmt(overlay.bounds.y + metrics.group_label_baseline_offset),
-                "fill": theme.group_label_color,
-                "font-family": theme.title_font_family,
-                "font-size": _fmt(theme.subtitle_font_size),
-                "font-weight": str(theme.title_font_weight),
-            },
-        ).text = overlay.group.label
+            text=overlay.group.label,
+            x=overlay.bounds.x + theme.group_padding,
+            baseline_y=overlay.bounds.y + metrics.group_label_baseline_offset,
+            font_family=theme.title_font_family,
+            font_size=theme.subtitle_font_size,
+            font_weight=theme.title_font_weight,
+            text_color=theme.group_label_color,
+            underpaint_color=theme.background_color,
+            underpaint_opacity=1.0,
+            underpaint_width=max(theme.stroke_width * 3.0, theme.subtitle_font_size * 0.24),
+        )
 
 
 def _render_guide_lines(parent: ET.Element, guide_lines: tuple[GuideLine, ...], theme: Theme) -> None:
@@ -209,7 +225,7 @@ def _render_guide_lines(parent: ET.Element, guide_lines: tuple[GuideLine, ...],
         )
 
 
-def _render_detail_panel_container(
+def _render_detail_panel_container_shape(
     parent: ET.Element,
     detail_panel: DetailPanelLayout,
     theme: Theme,
@@ -243,18 +259,72 @@ def _render_detail_panel_container(
         },
     )
 
+
+def _render_detail_panel_title(
+    parent: ET.Element,
+    detail_panel: DetailPanelLayout,
+    theme: Theme,
+    metrics: ResolvedThemeMetrics,
+) -> None:
+    _render_label_text(
+        parent,
+        text=detail_panel.panel.label,
+        x=detail_panel.bounds.x + theme.detail_panel_padding,
+        baseline_y=detail_panel.bounds.y + metrics.detail_panel_title_baseline_offset,
+        font_family=theme.title_font_family,
+        font_size=theme.subtitle_font_size,
+        font_weight=theme.title_font_weight,
+        text_color=theme.detail_panel_title_color,
+        underpaint_color=detail_panel.fill,
+        underpaint_opacity=1.0,
+        underpaint_width=max(theme.stroke_width * 3.0, theme.subtitle_font_size * 0.26),
+    )
+
+
+def _render_label_text(
+    parent: ET.Element,
+    *,
+    text: str,
+    x: float,
+    baseline_y: float,
+    font_family: str,
+    font_size: float,
+    font_weight: int,
+    text_color: str,
+    underpaint_color: str,
+    underpaint_opacity: float,
+    underpaint_width: float,
+) -> None:
+    ET.SubElement(
+        parent,
+        ET.QName(SVG_NS, "text"),
+        attrib={
+            "x": _fmt(x),
+            "y": _fmt(baseline_y),
+            "fill": underpaint_color,
+            "fill-opacity": _fmt(underpaint_opacity),
+            "stroke": underpaint_color,
+            "stroke-opacity": _fmt(underpaint_opacity),
+            "stroke-width": _fmt(underpaint_width),
+            "stroke-linejoin": "round",
+            "font-family": font_family,
+            "font-size": _fmt(font_size),
+            "font-weight": str(font_weight),
+        },
+    ).text = text
+
     ET.SubElement(
         parent,
         ET.QName(SVG_NS, "text"),
         attrib={
-            "x": _fmt(detail_panel.bounds.x + theme.detail_panel_padding),
-            "y": _fmt(detail_panel.bounds.y + metrics.detail_panel_title_baseline_offset),
-            "fill": theme.detail_panel_title_color,
-            "font-family": theme.title_font_family,
-            "font-size": _fmt(theme.subtitle_font_size),
-            "font-weight": str(theme.title_font_weight),
+            "x": _fmt(x),
+            "y": _fmt(baseline_y),
+            "fill": text_color,
+            "font-family": font_family,
+            "font-size": _fmt(font_size),
+            "font-weight": str(font_weight),
         },
-    ).text = detail_panel.panel.label
+    ).text = text
 
 
 def _render_edges(

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frameplot
-Version: 0.5.3
+Version: 0.5.6
 Summary: Turn Python-defined pipeline graphs into presentation-ready SVG and PNG diagrams.
 Author: Small Turtle 2
 License-Expression: MIT
@@ -147,6 +147,12 @@ Top-level imports are the supported public API:
 - `to_png_bytes(scale=4.0) -> bytes`
 - `save_png(path, scale=4.0) -> None`
 
+## Modeling Guidance
+
+- Keep the main graph at one abstraction level. Frameplot lays the pipeline out as a dependency-driven left-to-right graph, not as a freeform block diagram.
+- Use `DetailPanel` for repeated block internals or per-stage mechanics that would otherwise create long-range edges in the main graph.
+- Use `Group` to highlight nearby related nodes, not to force distant nodes to stay together. Groups are visual overlays and routing obstacles, so very wide groups can increase route detours.
+
 ## Advanced Example: Multi-cloud Data Pipeline
 
 The hero image at the top and the theme gallery above are generated from [`examples/theme_heroes.py`](https://github.com/smturtle2/frameplot/blob/main/examples/theme_heroes.py), using the shared pipeline definition in [`examples/hero_pipeline.py`](https://github.com/smturtle2/frameplot/blob/main/examples/hero_pipeline.py). Together they showcase:
@@ -161,6 +167,7 @@ The hero image at the top and the theme gallery above are generated from [`examp
 - 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.
+- If a sample looks stretched or routes far outside the intended block, the graph usually mixes stage-level flow with internal logic in one plane; move the internals into a `DetailPanel`.
 
 ## Development
 

{frameplot-0.5.3 → frameplot-0.5.6}/tests/test_rendering.py

@@ -905,6 +905,24 @@ def test_grouped_forward_edge_can_use_right_side_direct_elbow() -> None:
     assert all(not _point_in_bounds(point, inputs) for point in bends)
 
 
+def test_generate_pipeline_script_prefers_clean_single_bend_guidance_elbow() -> None:
+    namespace = runpy.run_path("test/generate_pipeline.py")
+    pipeline = namespace["build_pipeline"]()
+    layout = build_layout(pipeline)
+    routed = {edge.edge.id: edge for edge in layout.main.edges}
+    guide = layout.main.nodes["h_feature"]
+    target = layout.main.nodes["main_blocks"]
+
+    points = routed["h_to_main"].points
+    bends = _bend_points(points)
+
+    assert len(points) == 3
+    assert bends == [points[1]]
+    assert points[0] == Point(guide.right, guide.center_y)
+    assert points[1] == Point(target.center_x, guide.center_y)
+    assert points[-1] == Point(target.center_x, target.y)
+
+
 def test_back_edge_leaves_group_before_bending() -> None:
     pipeline = Pipeline(
         nodes=[
@@ -1366,6 +1384,30 @@ def test_text_measurement_and_render_share_resolved_baselines() -> None:
     assert float(texts[1].attrib["y"]) == pytest.approx(expected_subtitle_y)
 
 
+def test_text_measurement_preserves_explicit_newlines() -> None:
+    pipeline = Pipeline(
+        nodes=[Node("focus", "Primary Title", "First subtitle line\nSecond subtitle line")],
+        edges=[],
+    )
+
+    layout = build_layout(pipeline)
+    layout_node = layout.main.nodes["focus"]
+    node_group = ET.fromstring(pipeline.to_svg()).find(".//svg:g[@id='focus']", SVG_NS)
+
+    assert node_group is not None
+    texts = node_group.findall("svg:text", SVG_NS)
+
+    assert layout_node.subtitle_lines == ("First subtitle line", "Second subtitle line")
+    assert [text.text for text in texts] == [
+        "Primary Title",
+        "First subtitle line",
+        "Second subtitle line",
+    ]
+    assert float(texts[2].attrib["y"]) - float(texts[1].attrib["y"]) == pytest.approx(
+        layout_node.subtitle_line_height
+    )
+
+
 def test_detail_panel_renders_as_separate_block_with_guides() -> None:
     pipeline = Pipeline(
         nodes=[
@@ -1399,6 +1441,50 @@ def test_detail_panel_renders_as_separate_block_with_guides() -> None:
     assert svg.count('marker-end="url(#arrow-') == 4
 
 
+def test_group_and_detail_panel_labels_render_after_nodes() -> None:
+    theme = Theme.dark()
+    pipeline = Pipeline(
+        nodes=[
+            Node("source", "Source"),
+            Node("focus", "Focus"),
+        ],
+        edges=[Edge("e1", "source", "focus")],
+        groups=[Group("g1", "Shared Stage", ("source", "focus"))],
+        detail_panel=DetailPanel(
+            "detail",
+            "focus",
+            "Expanded Focus",
+            nodes=(Node("inner", "Inner"),),
+            edges=(),
+        ),
+        theme=theme,
+    )
+
+    root = ET.fromstring(pipeline.to_svg())
+    layer_ids = [child.attrib.get("id") for child in root if child.tag == f"{{{SVG_NS['svg']}}}g"]
+    labels = root.find(".//svg:g[@id='labels']", SVG_NS)
+
+    assert labels is not None
+    label_rects = labels.findall("svg:rect", SVG_NS)
+    label_texts = labels.findall("svg:text", SVG_NS)
+    shared_stage = [text for text in label_texts if text.text == "Shared Stage"]
+    expanded_focus = [text for text in label_texts if text.text == "Expanded Focus"]
+
+    assert not label_rects
+    assert len(shared_stage) == 2
+    assert len(expanded_focus) == 2
+    assert shared_stage[0].attrib["stroke"] == theme.background_color
+    assert shared_stage[0].attrib["fill"] == theme.background_color
+    assert shared_stage[1].attrib["fill"] == theme.group_label_color
+    assert "stroke" not in shared_stage[1].attrib
+    assert expanded_focus[0].attrib["stroke"] == theme.detail_panel_fill
+    assert expanded_focus[0].attrib["fill"] == theme.detail_panel_fill
+    assert expanded_focus[1].attrib["fill"] == theme.detail_panel_title_color
+    assert "stroke" not in expanded_focus[1].attrib
+    assert layer_ids.index("nodes") < layer_ids.index("labels")
+    assert layer_ids.index("edge-joins") < layer_ids.index("labels")
+
+
 def test_detail_panel_biases_focus_flow_to_lower_rows() -> None:
     pipeline = Pipeline(
         nodes=[
@@ -1472,25 +1558,33 @@ def test_detail_panel_nested_groups_keep_visible_inner_gap_and_header_clearance(
     assert child.y - parent.y > pipeline.theme.subtitle_font_size * metrics.line_height_ratio
 
 
-def test_detail_panel_shared_guidance_node_stays_above_stream_groups() -> None:
+def test_detail_panel_shared_guidance_node_uses_general_lane_ordering() -> None:
     layout = build_layout(_build_generate_pipeline_fixture())
     panel_nodes = layout.detail_panel.graph.nodes
-    panel_groups = layout.detail_panel.graph.groups
     routed = {edge.edge.id: edge for edge in layout.detail_panel.graph.edges}
     h_node = panel_nodes["panel_h"]
     source_lane_one = _source_access_segment(routed["panel_h_to_nca_c"].points)
     source_lane_two = _source_access_segment(routed["panel_h_to_nca_m"].points)
 
-    assert h_node.order == 0
-    assert panel_nodes["panel_c_in"].order == panel_nodes["panel_nca_c"].order == 1
-    assert panel_nodes["panel_m_in"].order == panel_nodes["panel_nca_m"].order == 2
-    assert all(not _point_in_bounds(Point(h_node.center_x, h_node.center_y), overlay.bounds) for overlay in panel_groups)
-    assert routed["panel_h_to_nca_c"].points[0].x == h_node.right
-    assert routed["panel_h_to_nca_m"].points[0].x == h_node.right
-    assert routed["panel_h_to_nca_c"].points[0].y != routed["panel_h_to_nca_m"].points[0].y
+    assert panel_nodes["panel_c_in"].order == panel_nodes["panel_nca_c"].order == 0
+    assert h_node.order == panel_nodes["panel_nca_m"].order == 1
+    assert panel_nodes["panel_m_in"].order == 2
+    assert h_node.order != 0
     assert _collinear_overlap_length(*source_lane_one, *source_lane_two) == pytest.approx(0.0, abs=0.01)
 
 
+def test_generate_pipeline_script_detail_panel_aligns_guidance_with_candidate_lane() -> None:
+    namespace = runpy.run_path("test/generate_pipeline.py")
+    pipeline = namespace["build_pipeline"]()
+    layout = build_layout(pipeline)
+    panel_nodes = layout.detail_panel.graph.nodes
+    routed = {edge.edge.id: edge for edge in layout.detail_panel.graph.edges}
+
+    assert panel_nodes["panel_h"].order == panel_nodes["panel_local_c"].order == panel_nodes["panel_global_c"].order == 0
+    assert panel_nodes["panel_local_m"].order == panel_nodes["panel_global_m"].order == 1
+    assert routed["panel_h_to_local_c"].points[0].y == routed["panel_h_to_local_c"].points[-1].y
+
+
 def test_generate_pipeline_row_gap_no_longer_scales_with_raw_cross_row_edge_count() -> None:
     layout = build_layout(_build_generate_pipeline_fixture())
     gap = _row_gap_between_rows(layout.main.nodes, 0, 1)