nodebpy 520.25.0__tar.gz → 520.27.0__tar.gz

{nodebpy-520.25.0 → nodebpy-520.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: nodebpy
-Version: 520.25.0
+Version: 520.27.0
 Summary: Build nodes trees in Blender more elegantly with code
 Author: Brady Johnston
 Author-email: Brady Johnston <brady.johnston@me.com>

{nodebpy-520.25.0 → nodebpy-520.27.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nodebpy"
-version = "520.25.0"
+version = "520.27.0"
 description = "Build nodes trees in Blender more elegantly with code"
 readme = "README.md"
 authors = [

{nodebpy-520.25.0 → nodebpy-520.27.0}/src/nodebpy/assets/__main__.py

@@ -90,8 +90,11 @@ def parse_args(
         ),
         epilog=(
             "subcommands:\n"
-            "  dump <blend> <output-dir>    dump every node-group asset in a "
+            "  dump <blend> <output-dir> [--names ...]\n"
+            "                               dump every node-group asset in a "
             ".blend to per-asset .py source files\n"
+            "                               (or only those matching --names, "
+            "wildcards supported)\n"
             "  build <source-dir> <blend>   rebuild the .blend asset library "
             "from dumped .py source files\n"
             "  ensure <source-dir> <blend>  rebuild only when the .blend or "

{nodebpy-520.25.0 → nodebpy-520.27.0}/src/nodebpy/assets/_library.py

@@ -467,7 +467,7 @@ def dump_library(
     blend_path: str | Path,
     output_dir: str | Path,
     *,
-    names: set[str] | None = None,
+    names: Iterable[str] | None = None,
     nodebpy_pkg: str = "nodebpy",
     snapshot_positions: bool = False,
     keep_reroutes: bool = False,
@@ -511,11 +511,20 @@ def dump_library(
     output_dir:
         Directory to write the per-asset modules into (created if needed).
     names:
-        Restrict the dump to these asset (node-group or material) names;
-        defaults to all. A full dump first clears the managed subdirectories
-        (``geometry``/``shader``/``compositor``/``materials``) so files from
-        renamed or deleted assets don't linger; a filtered dump leaves the
-        other assets' files in place.
+        Restrict the dump to the assets (node groups or materials) matching
+        these exact names or :mod:`fnmatch` wildcard patterns (``"Style *"``);
+        defaults to all. A pattern matching nothing raises. Meant for quick
+        iteration on a few assets: only the selected assets' modules are
+        regenerated, plus the ``_shared`` helper and ``materials/`` modules
+        they depend on — byte-identical to what a full dump writes for them,
+        because the whole library is still appended to decide what is shared
+        (a helper also used by an unselected asset stays in ``_shared``;
+        an unselected nested asset stays imported from its own module).
+        Edits to unselected assets are not picked up; a full dump (or the
+        ``check`` subcommand) catches those. A full dump first clears the
+        managed subdirectories (``geometry``/``shader``/``compositor``/
+        ``materials``) so files from renamed or deleted assets don't linger;
+        a filtered dump leaves the other assets' files in place.
     nodebpy_pkg:
         Import anchor for nodebpy in the generated sources, as for
         :func:`nodebpy.export.to_python`.
@@ -572,13 +581,18 @@ def dump_library(
         else (output_dir, blend_path)
     )
 
-    # Append every wanted asset in one load, so groups shared between assets
-    # (including assets nested in other assets) arrive as single trees and the
-    # sharing structure can be read off the session directly. Dependencies of
-    # other kinds (materials, images, …) come along too; everything appended
-    # is cleaned back out afterwards. The pre-append checks run inside the
-    # load context (the load itself happens on exit, with nothing selected
-    # when a check raises), so the .blend is opened only once.
+    # Append every asset in one load — even for a filtered dump — so groups
+    # shared between assets (including assets nested in other assets) arrive
+    # as single trees and the sharing structure can be read off the session
+    # directly: whether a helper is embedded or goes to _shared/ depends on
+    # how many assets reach it, and an asset outside the selection counts
+    # just the same. Appending is cheap next to code generation, which only
+    # runs for the selected roots. Dependencies of other kinds (materials,
+    # images, …) come along too; everything appended is cleaned back out
+    # afterwards. The pre-append checks run inside the load context (the
+    # load itself happens on exit, with nothing selected when a check
+    # raises), so the .blend is opened only once.
+    patterns = list(names) if names is not None else None
     before = {
         coll: set(getattr(bpy.data, coll).keys()) for coll in _CLEANUP_COLLECTIONS
     }
@@ -589,25 +603,28 @@ def dump_library(
         # assets_only exposes exactly the asset-marked materials: they are
         # dump roots alongside the node-group assets.
         available_materials = list(src.materials)
-        wanted = [n for n in available if names is None or n in names]
-        wanted_materials = [
-            n for n in available_materials if names is None or n in names
-        ]
-        if names is not None and (
-            missing := names - set(wanted) - set(wanted_materials)
-        ):
-            raise KeyError(f"Assets not found in {blend_path}: {sorted(missing)}")
-        clashes = sorted(n for n in wanted if n in bpy.data.node_groups)
+        selected: set[str] | None = None
+        if patterns is not None:
+            roots = available + available_materials
+            selected = {
+                n for n in roots if any(fnmatch.fnmatchcase(n, p) for p in patterns)
+            }
+            unmatched = [
+                p for p in patterns if not any(fnmatch.fnmatchcase(n, p) for n in roots)
+            ]
+            if unmatched:
+                raise KeyError(f"No assets in {blend_path} match: {unmatched}")
+        clashes = sorted(n for n in available if n in bpy.data.node_groups)
         if clashes:
             raise RuntimeError(
                 f"Node groups already exist in this session: {clashes}. "
                 "Appending would rename them and corrupt the dumped sources — "
                 "dump from a fresh session (e.g. python -m nodebpy.assets dump)."
             )
-        dst.node_groups = list(wanted)
+        dst.node_groups = list(available)
         # A same-named material already in the session renames the appended
         # one — caught by the post-append renamed-datablock guard below.
-        dst.materials = list(wanted_materials)
+        dst.materials = list(available_materials)
     added = {
         coll: [db for db in getattr(bpy.data, coll) if db.name not in before[coll]]
         for coll in _CLEANUP_COLLECTIONS
@@ -641,11 +658,12 @@ def dump_library(
             format=format,
             library_blend=anchor_blend.resolve() if typed_api else None,
             anchor_dir=anchor_dir.resolve(),
+            roots=selected,
             # A full dump owns the managed subdirectories: clear stale modules
             # from assets since renamed or deleted, so the next build_library
             # doesn't silently resurrect them. A filtered dump (names=...)
             # leaves the other assets' files alone.
-            clean_stale=names is None,
+            clean_stale=selected is None,
         )
     finally:
         for coll in _CLEANUP_COLLECTIONS:
@@ -699,6 +717,7 @@ def _dump_appended(
     format: bool,
     library_blend: Path | None = None,
     anchor_dir: Path | None = None,
+    roots: set[str] | None = None,
     clean_stale: bool = False,
 ) -> dict[str, Path]:
     """Partition the appended groups (and material roots and referenced
@@ -713,7 +732,11 @@ def _dump_appended(
     typed API — see ``dump_library(typed_api=...)`` — and ``anchor_dir``
     (default: ``output_dir``) is the directory the ``PackageLibrary``
     relative paths are computed against — see
-    ``dump_library(library_anchor=...)``. ``clean_stale`` removes
+    ``dump_library(library_anchor=...)``. ``roots`` restricts the modules
+    written to those assets (node-group or material names) plus the shared
+    helpers and materials they depend on — the partition itself is always
+    computed over every appended asset, so a filtered dump writes exactly
+    what a full one would for those modules. ``clean_stale`` removes
     modules under the managed subdirectories that this dump did not write
     (hand-written ``__init__.py`` files are kept, as ever).
     """
@@ -820,6 +843,24 @@ def _dump_appended(
     # and group calls to any of them use the typed parameter names.
     typed_groups = external if library_blend is not None else set()
 
+    # The modules this dump writes. A filtered dump writes the selected roots
+    # plus the modules they depend on that no other asset owns: the _shared
+    # helpers in their closures, the materials their footers record and those
+    # materials' shared helpers. Unselected assets — nested in a selected one
+    # or not — keep their own modules untouched and are imported as usual.
+    if roots is None:
+        write_assets = list(asset_trees)
+        write_materials = set(material_trees)
+    else:
+        write_assets = [t for t in asset_trees if t.name in roots]
+        write_materials = {k for k, m in material_trees.items() if m in roots}
+        for tree in write_assets:
+            for mat_name in module_dependencies(tree.name).get("materials", ()):
+                if (key := f"material:{mat_name}") in material_trees:
+                    write_materials.add(key)
+    write_roots = {t.name for t in write_assets} | write_materials
+    write_shared = shared & set().union(*(closures[r] for r in write_roots))
+
     def write_module(key: str, module: str, *, kind: str) -> Path:
         group = trees[key]
         # Emitted here: the tree itself plus, for roots, its private helpers.
@@ -876,13 +917,13 @@ def _dump_appended(
         return path
 
     written: dict[str, Path] = {}
-    for tree in asset_trees:
+    for tree in write_assets:
         written[tree.name] = write_module(tree.name, modules[tree.name], kind="asset")
     all_written = set(written.values())
-    for name in sorted(shared):
+    for name in sorted(write_shared):
         all_written.add(write_module(name, modules[name], kind="shared"))
     asset_material_names = set(asset_materials)
-    for key in sorted(material_trees):
+    for key in sorted(write_materials):
         path = write_module(key, modules[key], kind="material")
         all_written.add(path)
         # Material roots are assets the caller asked for, so they belong in
@@ -895,12 +936,14 @@ def _dump_appended(
     if library_blend is not None:
         # Typed API: each tree directory re-exports its asset classes, so
         # ``from <pkg>.<tree_dir> import <Class>`` (or an aliased module
-        # import) works like the old single-file API.
+        # import) works like the old single-file API. A filtered dump only
+        # exports modules that exist on disk (a full dump wrote them all).
         for dirname in set(_TREE_DIRS.values()):
             exports = sorted(
                 (modules[t.name].split("/")[1], class_names[t.name])
                 for t in asset_trees
                 if modules[t.name].startswith(f"{dirname}/")
+                and (output_dir / f"{modules[t.name]}.py").is_file()
             )
             if exports:
                 _write_dir_exports(output_dir / dirname, exports)
@@ -1406,7 +1449,7 @@ def _add_arrangement_flags(parser, description: str) -> None:  # pragma: no cove
         choices=["LEFT_DOWN", "RIGHT_DOWN", "LEFT_UP", "RIGHT_UP", "BALANCED"],
         help=(
             "Direction of layout — which corner nodes align towards, or "
-            "'balanced' to even out the four extremes (default: right_up)."
+            "'balanced' to even out the four extremes (default: balanced)."
         ),
     )
     layout.add_argument(
@@ -1442,6 +1485,38 @@ def _add_arrangement_flags(parser, description: str) -> None:  # pragma: no cove
         action="store_true",
         help="Fit the widths of collapsed nodes to their display name.",
     )
+    layout.add_argument(
+        "--no-sequential-frames",
+        dest="sequential_frames",
+        action="store_false",
+        help=(
+            "Do not rank frames as stages of the flow (by default every node "
+            "of a frame comes after every node of the frame feeding it, so "
+            "frames line up left to right instead of stacking)."
+        ),
+    )
+    layout.add_argument(
+        "--no-balance-heights",
+        dest="balance_heights",
+        action="store_false",
+        help=(
+            "Do not promote feeder chains into emptier columns to shorten the "
+            "tallest column."
+        ),
+    )
+    layout.add_argument(
+        "--balance-aspect",
+        type=float,
+        help=("Width-to-height ratio the height balancing aims for (default: 1.6)."),
+    )
+    layout.add_argument(
+        "--reroute-margin-y-fac",
+        type=float,
+        help=(
+            "Fraction of the vertical spacing kept between consecutive "
+            "reroutes in a column (default: 0.35)."
+        ),
+    )
 
 
 def _arrange_options_from_args(args) -> SugiyamaOptions | None:
@@ -1466,6 +1541,14 @@ def _arrange_options_from_args(args) -> SugiyamaOptions | None:
         overrides["stack_margin_y_fac"] = args.stack_margin_y_fac
     if args.optimize_sizes:
         overrides["optimize_sizes"] = True
+    if not args.sequential_frames:
+        overrides["sequential_frames"] = False
+    if not args.balance_heights:
+        overrides["balance_heights"] = False
+    if args.balance_aspect is not None:
+        overrides["balance_aspect"] = args.balance_aspect
+    if args.reroute_margin_y_fac is not None:
+        overrides["reroute_margin_y_fac"] = args.reroute_margin_y_fac
     return SugiyamaOptions(**overrides) if overrides else None
 
 
@@ -1634,7 +1717,15 @@ def _parse_args(argv: list[str] | None = None):
     dump.add_argument(
         "--names",
         nargs="+",
-        help="Only dump these asset (node-group or material) names (default: all).",
+        metavar="NAME",
+        help=(
+            "Only dump the assets (node groups or materials) matching these "
+            "names; fnmatch wildcards supported ('Style *', quoted to keep the "
+            "shell from expanding them). Default: all. The _shared helpers "
+            "and materials the selection depends on are written too, and the "
+            "other assets' files are left untouched — for quick iteration on "
+            "a few assets; a full dump (or 'check') catches edits elsewhere."
+        ),
     )
     _add_dump_flags(dump)
     dump.add_argument(
@@ -1816,7 +1907,7 @@ def _dump_command(args) -> None:
     written = dump_library(
         args.blend,
         args.output,
-        names=set(args.names) if args.names else None,
+        names=args.names or None,
         nodebpy_pkg=args.nodebpy_pkg,
         snapshot_positions=args.snapshot_positions,
         keep_reroutes=args.keep_reroutes,

{nodebpy-520.25.0 → nodebpy-520.27.0}/src/nodebpy/assets/_pipeline.py

@@ -97,6 +97,10 @@ _CONFIG_KEYS: dict[str, tuple[str | None, str]] = {
     "no-stack-collapsed": ("stack_collapsed", "off"),
     "stack-margin-y-fac": ("stack_margin_y_fac", "value"),
     "optimize-sizes": ("optimize_sizes", "flag"),
+    "no-sequential-frames": ("sequential_frames", "off"),
+    "no-balance-heights": ("balance_heights", "off"),
+    "balance-aspect": ("balance_aspect", "value"),
+    "reroute-margin-y-fac": ("reroute_margin_y_fac", "value"),
 }
 
 # Which dest each positional config key fills, per subcommand: the dump
@@ -132,6 +136,10 @@ _OPTION_DEFAULTS: dict[str, object] = {
     "stack_collapsed": True,
     "stack_margin_y_fac": None,
     "optimize_sizes": False,
+    "sequential_frames": True,
+    "balance_heights": True,
+    "balance_aspect": None,
+    "reroute_margin_y_fac": None,
 }
 
 # The resolved options the stamp fingerprint covers: everything, beyond the
@@ -140,6 +148,8 @@ _OPTION_DEFAULTS: dict[str, object] = {
 # it gates the session check, not the output.
 _STAMP_DESTS = (
     "add_reroutes",
+    "balance_aspect",
+    "balance_heights",
     "compress",
     "direction",
     "iterations",
@@ -149,6 +159,8 @@ _STAMP_DESTS = (
     "nodebpy_pkg",
     "on_missing",
     "optimize_sizes",
+    "reroute_margin_y_fac",
+    "sequential_frames",
     "snapshot_positions",
     "socket_alignment",
     "spacing",

{nodebpy-520.25.0 → nodebpy-520.27.0}/src/nodebpy/builder/layout.py

@@ -871,13 +871,33 @@ class SugiyamaOptions:
         Fit the widths of collapsed nodes to their display name.
     iterations : int
         Number of crossing-minimization iterations.
+    sequential_frames : bool
+        Rank frames as stages of the flow: every node of a frame comes
+        after every node of the frame (or intermediate node) feeding it, so
+        successive frames line up left to right instead of stacking into a
+        staircase. Frames with no links between them (parallel branches)
+        still share columns and stack vertically.
+    balance_heights : bool
+        Shorten the tallest column by moving nodes whose feeders serve only
+        them (a private upstream chain) one column left, while that makes
+        the drawing smaller overall. Counters the tall sliver a node with
+        many inputs otherwise produces, at the price of slightly longer
+        links routed through reroutes / dummy nodes.
+    balance_aspect : float
+        Width-to-height ratio the balancing aims for: it keeps promoting
+        feeders left while the drawing's bounding box (height, or width
+        divided by this ratio, whichever is larger) shrinks.
+    reroute_margin_y_fac : float
+        Fraction of the vertical margin kept between consecutive reroutes
+        (and the dummy nodes long links are routed through) in a column;
+        bundles of long links pack tighter than nodes.
     """
 
     # Defaults calibrated against hand-approved node-arrange addon output
     # ("30" x/y spacing, no socket alignment, top-right node alignment).
     margin: tuple[float, float] = (30.0, 30.0)
     direction: Literal["LEFT_DOWN", "RIGHT_DOWN", "BALANCED", "LEFT_UP", "RIGHT_UP"] = (
-        "RIGHT_UP"
+        "BALANCED"
     )
     socket_alignment: Literal["NONE", "MODERATE", "FULL"] = "NONE"
     add_reroutes: bool = False
@@ -886,6 +906,10 @@ class SugiyamaOptions:
     stack_margin_y_fac: float = 0.5
     optimize_sizes: bool = False
     iterations: int = 50
+    sequential_frames: bool = True
+    balance_heights: bool = True
+    balance_aspect: float = 1.6
+    reroute_margin_y_fac: float = 0.35
 
 
 type ArrangeMethod = (
@@ -959,6 +983,10 @@ def _arrange_sugiyama(tree: bpy.types.NodeTree, options: SugiyamaOptions) -> Non
         stack_collapsed=options.stack_collapsed,
         optimize_sizes=options.optimize_sizes,
         stack_margin_y_fac=options.stack_margin_y_fac,
+        sequential_frames=options.sequential_frames,
+        balance_heights=options.balance_heights,
+        balance_aspect=options.balance_aspect,
+        reroute_margin_y_fac=options.reroute_margin_y_fac,
     )
     sugiyama.sugiyama_layout(tree, settings=settings, margin=Vector(options.margin))
 

{nodebpy-520.25.0 → nodebpy-520.27.0}/src/nodebpy/export/plot.py

@@ -1069,31 +1069,81 @@ def _draw_frames(cv: _Canvas, tree: bpy.types.NodeTree) -> None:
 def _zone_members(
     tree: bpy.types.NodeTree, start: bpy.types.Node, end: bpy.types.Node
 ) -> set[bpy.types.Node]:
-    """Nodes on a path from *start* to *end*: forward-reachable from the zone
-    input and backward-reachable from the zone output."""
+    """The nodes Blender draws inside a zone: the zone's input and output
+    nodes and every node fed, directly or through other nodes, from the
+    zone input. A node that only feeds into the zone from outside (a group
+    input, a constant, a value computed elsewhere) stays outside."""
     forward: dict[bpy.types.Node, set[bpy.types.Node]] = {}
-    backward: dict[bpy.types.Node, set[bpy.types.Node]] = {}
     for link in tree.links:
         if link.from_node is None or link.to_node is None:
             continue
         forward.setdefault(link.from_node, set()).add(link.to_node)
-        backward.setdefault(link.to_node, set()).add(link.from_node)
 
-    def reach(root: bpy.types.Node, graph: dict) -> set[bpy.types.Node]:
-        seen = {root}
-        queue = deque([root])
-        while queue:
-            node = queue.popleft()
-            for nxt in graph.get(node, ()):
-                if nxt not in seen:
-                    seen.add(nxt)
-                    queue.append(nxt)
-        return seen
-
-    return (reach(start, forward) & reach(end, backward)) | {start, end}
+    seen = {start, end}
+    queue = deque([start])
+    while queue:
+        node = queue.popleft()
+        # bpy hands out a fresh wrapper per access, so compare by value.
+        if node == end:
+            continue
+        for nxt in forward.get(node, ()):
+            if nxt not in seen:
+                seen.add(nxt)
+                queue.append(nxt)
+    return seen
+
+
+def _convex_hull(points: list[tuple[float, float]]) -> list[tuple[float, float]]:
+    """Counter-clockwise convex hull (monotone chain)."""
+    pts = sorted(set(points))
+    if len(pts) <= 2:
+        return pts
+
+    def cross(o: tuple[float, float], a: tuple[float, float], b: tuple[float, float]):
+        return (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0])
+
+    lower: list[tuple[float, float]] = []
+    for pt in pts:
+        while len(lower) >= 2 and cross(lower[-2], lower[-1], pt) <= 0:
+            lower.pop()
+        lower.append(pt)
+    upper: list[tuple[float, float]] = []
+    for pt in reversed(pts):
+        while len(upper) >= 2 and cross(upper[-2], upper[-1], pt) <= 0:
+            upper.pop()
+        upper.append(pt)
+    return lower[:-1] + upper[:-1]
+
+
+def _rounded_offset(
+    hull: list[tuple[float, float]], radius: float, steps: int = 6
+) -> list[tuple[float, float]]:
+    """Outline of a convex polygon grown by *radius*: its edges pushed
+    outwards, its corners rounded (the Minkowski sum with a disc)."""
+    n = len(hull)
+    if n == 1:
+        cx, cy = hull[0]
+        return [
+            (cx + radius * math.cos(a), cy + radius * math.sin(a))
+            for a in (2 * math.pi * k / (4 * steps) for k in range(4 * steps))
+        ]
+    outline: list[tuple[float, float]] = []
+    for i, (x, y) in enumerate(hull):
+        (px, py), (nx, ny) = hull[i - 1], hull[(i + 1) % n]
+        # Outward normals of the incoming and outgoing edges (hull is CCW).
+        a_in = math.atan2(-(x - px), (y - py))
+        a_out = math.atan2(-(nx - x), (ny - y))
+        while a_out < a_in:
+            a_out += 2 * math.pi
+        for k in range(steps + 1):
+            a = a_in + (a_out - a_in) * k / steps
+            outline.append((x + radius * math.cos(a), y + radius * math.sin(a)))
+    return outline
 
 
 def _draw_zones(cv: _Canvas, tree: bpy.types.NodeTree) -> None:
+    from matplotlib.patches import Polygon
+
     for node in tree.nodes:
         attr = _ZONE_THEME_ATTR.get(node.bl_idname)
         if attr is None:
@@ -1101,24 +1151,23 @@ def _draw_zones(cv: _Canvas, tree: bpy.types.NodeTree) -> None:
         paired = getattr(node, "paired_output", None)
         if paired is None:
             continue
-        members = _zone_members(tree, node, paired)
-        bounds = [_node_bounds(n) for n in members]
-        x0 = min(b[0] for b in bounds) - _ZONE_PADDING
-        y0 = min(b[1] for b in bounds) - _ZONE_PADDING
-        x1 = max(b[2] for b in bounds) + _ZONE_PADDING
-        y1 = max(b[3] for b in bounds) + _ZONE_PADDING
+        corners: list[tuple[float, float]] = []
+        for member in _zone_members(tree, node, paired):
+            x0, y0, x1, y1 = _node_bounds(member)
+            corners += [(x0, y0), (x0, y1), (x1, y0), (x1, y1)]
+        outline = _rounded_offset(_convex_hull(corners), _ZONE_PADDING)
         color = cv.theme.zones[attr]
         border = (color[0], color[1], color[2], 0.9)
-        cv.rect(
-            x0,
-            y0,
-            x1 - x0,
-            y1 - y0,
-            face=color,
-            edge=border,
-            radius=10.0,
-            lw=1.0,
-            z=1.5,
+        cv.ax.add_patch(
+            Polygon(
+                outline,
+                closed=True,
+                facecolor=color,
+                edgecolor=border,
+                lw=1.0,
+                joinstyle="round",
+                zorder=1.5,
+            )
         )
 
 

{nodebpy-520.25.0 → nodebpy-520.27.0}/src/nodebpy/lib/nodearrange/VENDORED.md

@@ -44,6 +44,23 @@ break headless operation.
   working set is `list(ntree.nodes)` and the select gates are membership /
   always-true checks. Upstream patches touching `.select` need the same
   translation.
+- **Layout readability additions** (nodebpy-only, each behind a `Settings`
+  flag mirrored on `SugiyamaOptions`):
+  - `ranking.add_frame_sequence_edges()` (`sequential_frames`): ranks
+    frames as stages of the flow by constraining every node of a frame to
+    come after every node of the frame (or intermediate node) feeding it, so
+    successive frames line up left to right instead of stacking into a
+    staircase.
+  - `balancing.balance_column_heights()` (`balance_heights`,
+    `balance_aspect`): after ranking, promotes nodes of the tallest columns
+    together with their upstream into emptier columns while the drawing
+    gets closer to a screen-shaped box.
+  - `y_coords.vertical_gap()` (`reroute_margin_y_fac`): consecutive
+    reroutes / dummy nodes in a column pack at a fraction of the margin.
+  - `sugiyama.precompute_links()` keeps `is_hidden` links (links into a
+    collapsed panel's sockets), which still order the nodes; and
+    `x_coords.assign_x_coords()` skips a column left empty by dissolved
+    dummies.
 - `structs.py` uses explicit `_fields_` lists (upstream builds them from
   annotations, formerly via `eval`) and additionally binds `bNode` /
   `bNodeRuntime` / `rctf`, which upstream does not have.

nodebpy-520.27.0/src/nodebpy/lib/nodearrange/arrange/balancing.py

@@ -0,0 +1,182 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+"""Height-balanced ranking (nodebpy addition, not in upstream node-arrange).
+
+Network-simplex ranking minimises total edge length, so every feeder sits in
+the column right before its consumer. A node with many inputs — a big group
+node taking a dozen values, switches and math results — therefore gets all
+of its feeders stacked in one column, which grows far taller than any other
+column while the columns further left stay nearly empty: the tree becomes a
+tall sliver with dead space everywhere else.
+
+:func:`balance_column_heights` post-processes the ranks: while the tallest
+column can be made shorter without making the drawing larger overall, it
+moves a node of that column one column to the left together with
+everything upstream of it, which is always feasible (the moved set has no
+predecessor outside itself). Links from the moved set to the nodes left
+behind become one column longer and are routed through dummy nodes /
+reroutes, which the height estimate charges for.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterable
+
+import networkx as nx
+
+from ..config import LayoutState
+from ..utils import REROUTE_DIM
+from .graph import FROM_SOCKET, Cluster, Kind, Node, Socket
+
+_MAX_MOVES = 500
+
+
+def _upstream(G: nx.DiGraph[Node], v: Node) -> set[Node]:
+    """Every node *v* depends on. Moving *v* together with its upstream one
+    column to the left is always feasible: the set has no predecessor
+    outside itself, and links from it to nodes left behind only get
+    longer."""
+    return nx.ancestors(G, v)
+
+
+def _column_heights(
+    G: nx.DiGraph[Node], ranks: dict[Node, int], state: LayoutState
+) -> dict[int, float]:
+    """Estimated drawn height per rank: real nodes plus the dummy nodes of
+    the long edges passing through, each separated by the vertical margin.
+    Long edges leaving the same socket merge into one dummy chain."""
+    margin = state.margin.y
+    heights: defaultdict[int, float] = defaultdict(float)
+    counts: defaultdict[int, int] = defaultdict(int)
+    for v, r in ranks.items():
+        heights[r] += v.height
+        counts[r] += 1
+    crossings: defaultdict[int, set[Socket]] = defaultdict(set)
+    for u, w, from_socket in G.edges(data=FROM_SOCKET):
+        for r in range(ranks[u] + 1, ranks[w]):
+            crossings[r].add(from_socket)
+    dummy_gap = margin * state.settings.reroute_margin_y_fac
+    for r, sources in crossings.items():
+        # Dummy chains pack at the reduced reroute gap (see y_coords).
+        heights[r] += len(sources) * (REROUTE_DIM.y + dummy_gap)
+    return {r: heights[r] + margin * max(counts[r] - 1, 0) for r in heights}
+
+
+def _column_widths(ranks: dict[Node, int]) -> dict[int, float]:
+    widths: defaultdict[int, float] = defaultdict(float)
+    for v, r in ranks.items():
+        widths[r] = max(widths[r], v.width)
+    return widths
+
+
+def _frame_sequence_ok(
+    ranks: dict[Node, int],
+    sequence: Iterable[tuple[frozenset[Node], frozenset[Node]]],
+) -> bool:
+    """Whether every recorded frame-sequence constraint (all of unit *a*
+    before all of unit *b*) still holds under *ranks*."""
+    for before, after in sequence:
+        if max(ranks[v] for v in before) >= min(ranks[v] for v in after):
+            return False
+    return True
+
+
+def _overshoot(heights: dict[int, float], target: float) -> float:
+    return sum(max(0.0, h - target) for h in heights.values())
+
+
+def _fit_to_height(
+    G: nx.DiGraph[Node],
+    ranks: dict[Node, int],
+    target: float,
+    state: LayoutState,
+    upstream_of: dict[Node, set[Node]],
+) -> dict[Node, int] | None:
+    """Greedily move nodes (with their upstream) left until no column is
+    taller than *target*; None when the greedy gets stuck first."""
+    ranks = dict(ranks)
+    sequence = state.frame_sequence
+    for _ in range(_MAX_MOVES):
+        heights = _column_heights(G, ranks, state)
+        current = _overshoot(heights, target)
+        if current <= 0:
+            return ranks
+        best: tuple[float, dict[Node, int]] | None = None
+        for v, upstream in upstream_of.items():
+            if not upstream or heights.get(ranks[v], 0.0) <= target:
+                continue
+            trial = dict(ranks)
+            for w in upstream | {v}:
+                trial[w] -= 1
+            if not _frame_sequence_ok(trial, sequence):
+                continue
+            shoot = _overshoot(_column_heights(G, trial, state), target)
+            if shoot < current and (best is None or shoot < best[0]):
+                best = (shoot, trial)
+        if best is None:
+            return None
+        ranks = best[1]
+    return None
+
+
+_TARGET_STEP = 0.9
+
+
+def balance_column_heights(
+    G: nx.DiGraph[Node],
+    clusters: Iterable[Cluster],
+    state: LayoutState,
+) -> None:
+    """Shorten the tallest columns by promoting feeder chains left.
+
+    Lowers a target height step by step from the current tallest column and
+    for each target greedily moves nodes of over-tall columns — together
+    with their upstream — one column to the left until every column
+    fits (or gives up). Of the layouts found, the one needing the smallest
+    screen-shaped box (``balance_aspect`` wide for every unit of height) is
+    kept, so height is traded for width only while the drawing gets closer
+    to that shape; the descent stops once fitting fails or the box starts
+    growing again. Frame-sequence constraints are kept throughout.
+    """
+    nodes = [v for v in G if v.type != Kind.HORIZONTAL_BORDER]
+    if not nodes:
+        return
+    ranks = {v: v.rank for v in nodes}
+    margin_x = state.margin.x
+    upstream_of = {v: _upstream(G, v) for v in nodes}
+
+    aspect = state.settings.balance_aspect
+
+    def area(r: dict[Node, int]) -> float:
+        """Size of the drawing as the side of the screen-shaped box (of the
+        target aspect ratio) it needs: the taller of its height and its
+        width scaled down by the aspect ratio."""
+        heights = _column_heights(G, r, state)
+        widths = _column_widths(r)
+        width = sum(widths.values()) + margin_x * max(len(widths) - 1, 0)
+        return max(max(heights.values()), width / aspect)
+
+    best_ranks = ranks
+    best_area = area(ranks)
+    target = max(_column_heights(G, ranks, state).values()) * _TARGET_STEP
+    floor = max(v.height for v in nodes)
+    while target >= floor:
+        fitted = _fit_to_height(G, best_ranks, target, state, upstream_of)
+        if fitted is None:
+            break
+        fitted_area = area(fitted)
+        if fitted_area > best_area:
+            break
+        best_ranks, best_area = fitted, fitted_area
+        target = max(_column_heights(G, fitted, state).values()) * _TARGET_STEP
+
+    offset = min(best_ranks.values())
+    for v in nodes:
+        v.rank = best_ranks[v] - offset
+    # Frame borders follow their members (recomputed by insert_dummy_nodes);
+    # keep them consistent for anything reading them before that.
+    for c in clusters:
+        members = [v for v in nodes if v.cluster is c]
+        if members:
+            c.left.rank = min(v.rank for v in members) - 1
+            c.right.rank = max(v.rank for v in members) + 1

{nodebpy-520.25.0 → nodebpy-520.27.0}/src/nodebpy/lib/nodearrange/arrange/ranking.py

@@ -27,9 +27,75 @@ def get_nesting_graph(CG: ClusterGraph) -> nx.MultiDiGraph[Node]:
             else:
                 H.add_edges_from(((u.left, v.left), (v.right, u.right)))
 
+    if CG.state.settings.sequential_frames:
+        add_frame_sequence_edges(CG, H)
+
     return H
 
 
+def _top_level_unit(v: Node, root: Cluster) -> Node | Cluster:
+    """The outermost frame (a child of *root*) containing *v*, or *v* itself
+    when it sits directly in the root."""
+    unit: Node | Cluster = v
+    c = v.cluster
+    while c is not None and c is not root:
+        unit = c
+        c = c.cluster
+    return unit
+
+
+def add_frame_sequence_edges(CG: ClusterGraph, H: nx.MultiDiGraph[Node]) -> None:
+    """Rank frames as stages of the flow (nodebpy divergence).
+
+    With plain nesting constraints a frame only has to enclose its own
+    members, so a downstream frame's first nodes are ranked right next to the
+    upstream frame's last ones and the two frames share columns — which
+    forces them to be stacked vertically, producing a staircase of frames
+    instead of a left-to-right flow. This adds, for every link between two
+    top-level units (a frame, or a node outside every frame), a constraint
+    from the source unit's right border to the target unit's left border:
+    every node of a frame comes after every node of the frame (or the
+    intermediate node) feeding it. Nodes without predecessors (inputs and
+    values serving one consumer) and without successors are exempt so they
+    stay next to their consumer / producer; units on a cycle of the quotient
+    graph are left to the plain nesting constraints.
+    """
+    G = CG.G
+    root = next(c for c in CG.S if not CG.T.pred[c])
+    unit_of = {v: _top_level_unit(v, root) for v in G}
+
+    Q: nx.DiGraph[Node | Cluster] = nx.DiGraph()
+    Q.add_nodes_from(set(unit_of.values()))
+    for u, v in G.edges():
+        a, b = unit_of[u], unit_of[v]
+        if a is not b:
+            Q.add_edge(a, b)
+
+    scc_of = {
+        n: i for i, comp in enumerate(nx.strongly_connected_components(Q)) for n in comp
+    }
+    for a, b in Q.edges():
+        if scc_of[a] == scc_of[b]:
+            continue
+        a_is_frame = isinstance(a, Cluster)
+        b_is_frame = isinstance(b, Cluster)
+        if not a_is_frame and not b_is_frame:
+            continue
+        if not a_is_frame and not G.pred[a]:
+            continue
+        if not b_is_frame and not G.succ[b]:
+            continue
+        tail = a.right if isinstance(a, Cluster) else a
+        head = b.left if isinstance(b, Cluster) else b
+        H.add_edge(tail, head)
+        CG.state.frame_sequence.append(
+            (
+                frozenset(v for v in G if unit_of[v] is a),
+                frozenset(v for v in G if unit_of[v] is b),
+            )
+        )
+
+
 @cache
 def get_adj_edges_H(H: nx.MultiDiGraph[Node], v: Node) -> tuple[MultiEdge, ...]:
     return (*H.in_edges(v, keys=True), *H.out_edges(v, keys=True))

{nodebpy-520.25.0 → nodebpy-520.27.0}/src/nodebpy/lib/nodearrange/arrange/sugiyama.py

@@ -14,6 +14,7 @@ from mathutils import Vector
 
 from ..config import LayoutState, Settings
 from ..utils import abs_loc, group_by
+from .balancing import balance_column_heights
 from .graph import (
     FROM_SOCKET,
     TO_SOCKET,
@@ -102,8 +103,11 @@ def optimize_sizes(nodes: Iterable[BlenderNode]) -> None:
 def precompute_links(state: LayoutState) -> None:
     # Precompute links to ignore invalid/hidden links, and avoid `O(len(ntree.links))` time
 
+    # Headless divergence: links into a collapsed panel's sockets report
+    # ``is_hidden`` (Blender draws them to the panel header); they still
+    # carry data, so they still order the nodes.
     for link in state.ntree.links:
-        if not link.is_hidden and link.is_valid:
+        if link.is_valid:
             assert link.from_socket
             assert link.to_socket
             state.linked_sockets[link.to_socket].add(link.from_socket)
@@ -313,6 +317,8 @@ def sugiyama_layout(
         node_stacks = contracted_node_stacks(CG)
 
     compute_ranks(CG)
+    if state.settings.balance_heights:
+        balance_column_heights(G, CG.S, state)
     CG.merge_edges()
     CG.insert_dummy_nodes()
 

{nodebpy-520.25.0 → nodebpy-520.27.0}/src/nodebpy/lib/nodearrange/arrange/x_coords.py

@@ -60,6 +60,10 @@ def assign_x_coords(
     columns: list[list[Node]] = G.graph["columns"]
     x = 0
     for i, col in enumerate(columns):
+        if not col:
+            # nodebpy divergence: a rank whose only occupants were dummy
+            # nodes (dissolved when reroutes are not added) takes no space.
+            continue
         max_width = max([v.width for v in col])
 
         for v in col:

{nodebpy-520.25.0 → nodebpy-520.27.0}/src/nodebpy/lib/nodearrange/arrange/y_coords.py

@@ -135,6 +135,17 @@ def inner_shift(
             w.inner_shift = fmean(inner_shifts)
 
 
+def vertical_gap(u: Node, w: Node, state: LayoutState) -> float:
+    """Margin between two vertically adjacent nodes of a column (nodebpy
+    divergence): consecutive reroutes / dummy nodes — the bundles of long
+    links routed past a column — pack much tighter than nodes, as reroute
+    dots do in hand-made trees, so a fan-in of many long links no longer
+    costs a node's height per link."""
+    if u.is_reroute and w.is_reroute:
+        return state.margin.y * state.settings.reroute_margin_y_fac
+    return state.margin.y
+
+
 def place_block(v: Node, is_up: bool, state: LayoutState) -> None:
     if cast(float | None, v.y) is not None:
         return
@@ -155,7 +166,8 @@ def place_block(v: Node, is_up: bool, state: LayoutState) -> None:
             v.sink = u.sink
 
         if v.sink == u.sink:
-            delta_l = n.height + state.margin.y if is_up else w.height + state.margin.y
+            gap = vertical_gap(n, w, state)
+            delta_l = n.height + gap if is_up else w.height + gap
             s_b = u.y + n.inner_shift - w.inner_shift + delta_l
             v.y = s_b if initial else max(v.y, s_b)
             initial = False
@@ -183,7 +195,8 @@ def vertical_compaction(G: nx.DiGraph[Node], is_up: bool, state: LayoutState) ->
             col[0].sink.shift = 0
 
         for u, v in neighborings[tuple(col)]:
-            delta_l = u.height + state.margin.y if is_up else v.height + state.margin.y
+            gap = vertical_gap(u, v, state)
+            delta_l = u.height + gap if is_up else v.height + gap
             s_c = v.y + v.inner_shift - u.y - u.inner_shift - delta_l
             u.sink.shift = min(u.sink.shift, v.sink.shift + s_c)
 

{nodebpy-520.25.0 → nodebpy-520.27.0}/src/nodebpy/lib/nodearrange/config.py

@@ -11,7 +11,7 @@ from bpy.types import NodeSocket, NodeTree
 from mathutils import Vector
 
 if TYPE_CHECKING:
-    from .arrange.graph import Socket
+    from .arrange.graph import Node, Socket
 
 
 @dataclass
@@ -30,6 +30,17 @@ class Settings:
     recenter_mode = "NODES"
     origin: Literal["CENTER", "ACTIVE_OUTPUT", "ACTIVE_NODE"] = "CENTER"
     stack_margin_y_fac: float = 0.5
+    # nodebpy divergence: rank frames as sequential stages (see
+    # ranking.add_frame_sequence_edges).
+    sequential_frames: bool = True
+    # nodebpy divergence: promote private feeder chains out of the tallest
+    # column (see arrange.balancing).
+    balance_heights: bool = True
+    balance_aspect: float = 1.6
+    # nodebpy divergence: fraction of the vertical margin kept between
+    # consecutive reroutes / dummy nodes in a column (see
+    # y_coords.vertical_gap).
+    reroute_margin_y_fac: float = 0.35
 
 
 DEFAULT_MARGIN = (200.0, 20.0)
@@ -55,3 +66,8 @@ class LayoutState:
     multi_input_sort_ids: defaultdict[Socket, list[tuple[Socket, int]]] = field(
         default_factory=lambda: defaultdict(list)
     )
+    # Frame-sequence constraints applied by ranking.add_frame_sequence_edges:
+    # every node of the first set is ranked before every node of the second.
+    frame_sequence: list[tuple[frozenset[Node], frozenset[Node]]] = field(
+        default_factory=list
+    )