@graphty/graph-io 0.3.48 → 0.3.50

package/src/formats/dot/exporter.ts

@@ -36,11 +36,16 @@ import {
     LABEL_ATTRIBUTE,
     PARENT_COLUMN,
     POS_ATTRIBUTE,
+    RANK_COLUMN,
+    RANK_SET_COLUMN,
     SOURCE_PORT_COLUMN,
     TARGET_PORT_COLUMN,
 } from "./names.js";
 import { DOT_ATTRIBUTE_CLASH_CODE, DOT_STYLE_CAPABILITIES, dotStyledExport, isHtmlString } from "./styles.js";
 
+/** The node columns written as rank subgraphs rather than as node attributes. */
+const RANK_COLUMNS: ReadonlySet<string> = new Set([RANK_COLUMN, RANK_SET_COLUMN]);
+
 /** What the writer takes: the format's options, the common ones and the styles. */
 type DotWriteOptions = DotExportOptions & CommonExportOptions & ExporterStyleOptions;
 
@@ -611,7 +616,7 @@ class ExportPlan {
      */
     private writesNodeColumn(column: Column): boolean {
         const { name, role } = column.meta;
-        if (!isTextualDtype(column) || name === CLUSTER_COLUMN) {
+        if (!isTextualDtype(column) || name === CLUSTER_COLUMN || RANK_COLUMNS.has(name)) {
             return false;
         }
         if (role !== null && SKIPPED_NODE_ROLES.has(role)) {
@@ -875,10 +880,41 @@ class ExportPlan {
         for (let i = 0; i < snapshot.nodeCount; i++) {
             yield* this.writeNode(i, 1, emitted);
         }
+        yield* this.writeRanks();
         yield* this.writeEdges();
         yield "}\n";
     }
 
+    /**
+     * Write each rank subgraph the `graphty.rank` and `graphty.rankSet` columns hold, after the nodes: a named one
+     * under its name, an anonymous one (`%<n>`) as an anonymous subgraph.
+     * @yields the statements
+     * @returns nothing
+     */
+    private *writeRanks(): Generator<string> {
+        const { nodes } = this.snapshot;
+        const rank = nodes.get(RANK_COLUMN);
+        const set = nodes.get(RANK_SET_COLUMN);
+        if (rank === null || set === null) {
+            return;
+        }
+        const sets = new Map<string, { rank: string; members: string[] }>();
+        for (let i = 0; i < this.snapshot.nodeCount; i++) {
+            if (rank.isSet(i) && set.isSet(i)) {
+                const key = String(set.value(i));
+                const entry = sets.get(key) ?? { rank: String(rank.value(i)), members: [] };
+                entry.members.push(writeId(this.idText(i)));
+                sets.set(key, entry);
+            }
+        }
+        // anonymous ones in their number's order, so the file read back numbers them the same
+        const order = (key: string): number => (key.startsWith("%") ? Number(key.slice(1)) : -1);
+        for (const [key, entry] of [...sets].sort(([a], [b]) => order(a) - order(b))) {
+            const head = key.startsWith("%") ? "" : `subgraph ${quoteDotId(key)} `;
+            yield `${this.indent}${head}{ rank=${quoteDotId(entry.rank)}; ${entry.members.join("; ")}; }\n`;
+        }
+    }
+
     /**
      * Write one node (and, for a container, its cluster block with the members nested).
      * @param i - the node index

package/src/formats/dot/importer.ts

@@ -98,6 +98,8 @@ import {
     PIN_ATTRIBUTE,
     POS_ATTRIBUTE,
     POSITION_COLUMN,
+    RANK_COLUMN,
+    RANK_SET_COLUMN,
     SOURCE_PORT_COLUMN,
     TARGET_PORT_COLUMN,
 } from "./names.js";
@@ -177,8 +179,13 @@ export const DOT_ISSUE = Object.freeze({
     AMBIGUOUS_GRAPH_NAME: AMBIGUOUS_GRAPH_NAME_CODE,
     /** A badly delimited numeral (`1e3`) split into two tokens, as Graphviz does with a warning. */
     NUMERAL_AMBIGUITY: "W_DOT_NUMERAL_AMBIGUITY",
-    /** Attributes of a subgraph that is not a cluster (rank=same and the like) cannot be represented. */
+    /**
+     * Attributes of a subgraph that is not a cluster cannot be represented, except its `rank`, which is kept in the
+     * `graphty.rank` and `graphty.rankSet` node columns.
+     */
     SUBGRAPH_ATTRIBUTES_DROPPED: "W_DOT_SUBGRAPH_ATTRIBUTES_DROPPED",
+    /** A node in two rank subgraphs (`rank=same` and the like) keeps the first one's rank. */
+    RANK_CONFLICT: "W_DOT_RANK_CONFLICT",
     /** A port on a node statement has no meaning and was dropped. */
     NODE_PORT_DROPPED: "W_DOT_NODE_PORT_DROPPED",
     /** A plain node and a cluster share a name and were merged into one container node. */
@@ -262,8 +269,35 @@ const EXTENSIONS: readonly string[] = Object.freeze([".dot", ".gv"]);
 const MIME_TYPES: readonly string[] = Object.freeze(["text/vnd.graphviz"]);
 const CLUSTER_PREFIX = "cluster";
 const CLUSTER_ATTRIBUTE = "cluster";
+/** The subgraph attribute that puts its nodes on one rank, or on the first or last. */
+const RANK_ATTRIBUTE = "rank";
+/** The values of `rank` Graphviz knows (lib/common/const.h: SAMERANK ... SINKRANK). */
+const RANK_KINDS: ReadonlySet<string> = new Set(["same", "min", "max", "source", "sink"]);
 const STATEMENTS_PER_ABORT_CHECK = 64;
 const MAX_ANCESTOR_WALK = 4096;
+/**
+ * The graph attributes a cluster takes from the graphs around it when it sets none of its own: Graphviz gives a
+ * subgraph every graph attribute its enclosing graphs set before it opened (a root `label` set first labels every
+ * cluster). Only the attributes that decide how a cluster is drawn are copied.
+ */
+const INHERITED_GRAPH_ATTRIBUTES: ReadonlySet<string> = new Set([
+    "bgcolor",
+    "color",
+    "colorscheme",
+    "fillcolor",
+    "fontcolor",
+    "fontname",
+    "fontsize",
+    "gradientangle",
+    "label",
+    "labeljust",
+    "labelloc",
+    "pencolor",
+    "penwidth",
+    "peripheries",
+    "style",
+    "tooltip",
+]);
 
 /**
  * The header keyword, ended by what may follow it in DOT: space, `{`, a quoted ID or a comment.
@@ -320,6 +354,8 @@ interface Scope {
     readonly containers: number[];
     /** Subgraph attributes buffered until the subgraph closes (the root applies them at once). */
     readonly attributes: Map<string, DotAttribute>;
+    /** The drawing attributes a cluster opened in this scope inherits: the enclosing scopes' and this one's so far. */
+    readonly graphDefaults: Map<string, DotAttribute>;
     /** Whether the subgraph is a cluster (by name or by `cluster=true`). */
     cluster: boolean;
     /** The container node index once created, or INVALID_INDEX. */
@@ -734,6 +770,12 @@ class DotParser {
     /** The parent assigned to a node by this import. */
     private readonly parentOf = new Map<number, number>();
 
+    /** Each cluster container's inherited drawing attributes, as its scope saw them when the cluster first opened. */
+    private readonly inherited = new Map<number, Map<string, DotAttribute>>();
+
+    /** The attributes each cluster container sets itself, which its inherited ones never replace. */
+    private readonly ownAttributes = new Map<number, Set<string>>();
+
     /** Nodes already warned about a cluster conflict. */
     private readonly conflictWarned = new Set<number>();
 
@@ -761,6 +803,16 @@ class DotParser {
 
     private targetPortHandle: ColumnHandle = INVALID_INDEX as ColumnHandle;
 
+    private rankHandle: ColumnHandle = INVALID_INDEX as ColumnHandle; // NOSONAR(S2933): stringColumn assigns it through this[field]
+
+    private rankSetHandle: ColumnHandle = INVALID_INDEX as ColumnHandle; // NOSONAR(S2933): stringColumn assigns it through this[field]
+
+    /** The rank subgraph each node was put in first, by node index. */
+    private readonly rankSetOf = new Map<number, string>();
+
+    /** How many anonymous rank subgraphs were read, which names the next `%<n>`. */
+    private anonymousRanks = 0;
+
     /** The current subgraph nesting depth. */
     private depth = 0;
 
@@ -851,6 +903,7 @@ class DotParser {
         });
         const root = this.newScope(null, headerLine, true, null);
         this.statementList(root);
+        this.applyInherited();
         return lexer.next();
     }
 
@@ -873,6 +926,7 @@ class DotParser {
             memberSet: new Set(),
             containers: [],
             attributes: new Map(),
+            graphDefaults: new Map(parent?.graphDefaults),
             cluster: false,
             container: INVALID_INDEX,
         };
@@ -1113,42 +1167,10 @@ class DotParser {
      */
     private closeScope(scope: Scope, parent: Scope): void {
         const { container } = scope;
-        if (container !== INVALID_INDEX) {
-            for (const attribute of scope.attributes.values()) {
-                if (attribute.name !== CLUSTER_ATTRIBUTE) {
-                    this.setNodeAttribute(container, attribute.name, attribute.value, attribute.line);
-                }
-            }
-            for (const nested of scope.containers) {
-                if (nested !== container && !this.parentOf.has(nested)) {
-                    this.setParent(nested, container);
-                }
-            }
-            for (const member of scope.members) {
-                if (member === container) {
-                    continue;
-                }
-                const existing = this.parentOf.get(member);
-                if (existing === undefined) {
-                    this.setParent(member, container);
-                } else if (existing !== container && !this.isAncestor(container, existing)) {
-                    this.clusterConflict(member, existing, container, scope.line);
-                }
-            }
-            parent.containers.push(container);
+        if (container === INVALID_INDEX) {
+            this.closePlainSubgraph(scope, parent);
         } else {
-            if (scope.attributes.size > 0) {
-                const names = [...scope.attributes.keys()].join(", ");
-                this.report.warning(
-                    "unsupported",
-                    DOT_ISSUE.SUBGRAPH_ATTRIBUTES_DROPPED,
-                    `subgraph ${scope.name === null ? "(anonymous)" : JSON.stringify(scope.name)} is not a cluster; its attributes (${names}) cannot be represented and were dropped`,
-                    { line: scope.line, element: scope.name },
-                );
-            }
-            for (const nested of scope.containers) {
-                parent.containers.push(nested);
-            }
+            this.closeCluster(scope, parent, container);
         }
         if (!parent.root) {
             for (const member of scope.members) {
@@ -1160,6 +1182,88 @@ class DotParser {
         }
     }
 
+    /**
+     * Finish a cluster: apply its attributes to its container node, assign parents to its nested
+     * containers and its members, and hand the container to the enclosing scope.
+     * @param scope - the closed scope
+     * @param parent - the enclosing scope
+     * @param container - the cluster's container node
+     */
+    private closeCluster(scope: Scope, parent: Scope, container: number): void {
+        const own = this.ownAttributes.get(container) ?? new Set<string>();
+        this.ownAttributes.set(container, own);
+        for (const attribute of scope.attributes.values()) {
+            if (attribute.name !== CLUSTER_ATTRIBUTE) {
+                own.add(attribute.name);
+                this.setNodeAttribute(container, attribute.name, attribute.value, attribute.line);
+            }
+        }
+        for (const nested of scope.containers) {
+            if (nested !== container && !this.parentOf.has(nested)) {
+                this.setParent(nested, container);
+            }
+        }
+        for (const member of scope.members) {
+            if (member !== container) {
+                this.adoptMember(member, container, scope.line);
+            }
+        }
+        parent.containers.push(container);
+    }
+
+    /**
+     * Put a cluster's member in it, unless it is already in another cluster this one is not inside.
+     * @param member - the member node
+     * @param container - the cluster's container node
+     * @param line - the cluster's line
+     */
+    private adoptMember(member: number, container: number, line: number): void {
+        const existing = this.parentOf.get(member);
+        if (existing === undefined) {
+            this.setParent(member, container);
+        } else if (existing !== container && !this.isAncestor(container, existing)) {
+            this.clusterConflict(member, existing, container, line);
+        }
+    }
+
+    /**
+     * Finish a subgraph that is not a cluster: keep its rank, report its other attributes dropped, and hand its nested
+     * containers to the enclosing scope.
+     * @param scope - the closed scope
+     * @param parent - the enclosing scope
+     */
+    private closePlainSubgraph(scope: Scope, parent: Scope): void {
+        const ranked = this.recordRank(scope);
+        const dropped = [...scope.attributes.keys()].filter((name) => !(ranked && name === RANK_ATTRIBUTE));
+        if (dropped.length > 0) {
+            const names = dropped.join(", ");
+            this.report.warning(
+                "unsupported",
+                DOT_ISSUE.SUBGRAPH_ATTRIBUTES_DROPPED,
+                `subgraph ${scope.name === null ? "(anonymous)" : JSON.stringify(scope.name)} is not a cluster; its attributes (${names}) cannot be represented and were dropped`,
+                { line: scope.line, element: scope.name },
+            );
+        }
+        for (const nested of scope.containers) {
+            parent.containers.push(nested);
+        }
+    }
+
+    /**
+     * Give every cluster the drawing attributes it inherits and does not set itself (Graphviz's subgraph attribute
+     * inheritance), once the whole graph is read: a cluster reopened later can still set its own.
+     */
+    private applyInherited(): void {
+        for (const [container, attributes] of this.inherited) {
+            const own = this.ownAttributes.get(container);
+            for (const attribute of attributes.values()) {
+                if (own?.has(attribute.name) !== true) {
+                    this.setNodeAttribute(container, attribute.name, attribute.value, attribute.line);
+                }
+            }
+        }
+    }
+
     /**
      * Whether `candidate` is an ancestor of `node` through the parents assigned so far.
      * @param candidate - the possible ancestor
@@ -1244,6 +1348,7 @@ class DotParser {
             if (!this.containers.has(index)) {
                 this.containers.add(index);
                 this.sink.setNodeValue(this.clusterColumn(), index, true);
+                this.inherited.set(index, new Map(scope.graphDefaults));
             }
             scope.container = index;
         } catch (err) {
@@ -1261,6 +1366,9 @@ class DotParser {
      * @param attribute - the attribute
      */
     private scopeAttribute(scope: Scope, attribute: DotAttribute): void {
+        if (INHERITED_GRAPH_ATTRIBUTES.has(attribute.name)) {
+            scope.graphDefaults.set(attribute.name, attribute);
+        }
         if (scope.root) {
             this.setGraphAttribute(attribute);
             return;
@@ -1901,6 +2009,54 @@ class DotParser {
         return this.positionHandle;
     }
 
+    /**
+     * Keep a non-cluster subgraph's `rank` on its nodes: each gets the rank and the subgraph's name (`%<n>` for an
+     * anonymous one). A node already in another rank subgraph keeps that one, with a warning.
+     * @param scope - the closed subgraph
+     * @returns true when the subgraph has a rank Graphviz knows
+     */
+    private recordRank(scope: Scope): boolean {
+        const rank = scope.attributes.get(RANK_ATTRIBUTE)?.value.trim();
+        if (rank === undefined || !RANK_KINDS.has(rank)) {
+            return false;
+        }
+        const set = scope.name ?? `%${this.anonymousRanks++}`;
+        for (const member of scope.members) {
+            const held = this.rankSetOf.get(member);
+            const id = String(this.idOf.get(member) ?? member);
+            if (held === undefined) {
+                this.rankSetOf.set(member, set);
+                try {
+                    this.sink.setNodeValue(this.stringColumn("rankHandle", RANK_COLUMN), member, rank);
+                    this.sink.setNodeValue(this.stringColumn("rankSetHandle", RANK_SET_COLUMN), member, set);
+                } catch (err) {
+                    this.report.recordError(err, { element: id });
+                }
+            } else if (held !== set) {
+                this.report.warning(
+                    "coercion",
+                    DOT_ISSUE.RANK_CONFLICT,
+                    `node ${JSON.stringify(id)} is in rank subgraph ${JSON.stringify(held)} and in rank subgraph ${JSON.stringify(set)}; the first is kept`,
+                    { line: scope.line, element: id },
+                );
+            }
+        }
+        return true;
+    }
+
+    /**
+     * One of the importer's string node columns, declared on first use.
+     * @param field - the field holding its handle
+     * @param name - the column name
+     * @returns the handle
+     */
+    private stringColumn(field: "rankHandle" | "rankSetHandle", name: string): ColumnHandle {
+        if (this[field] === INVALID_INDEX) {
+            this[field] = this.declare("node", { name, dtype: "string", nullable: true, origin: DOT_ORIGIN });
+        }
+        return this[field];
+    }
+
     /**
      * The cluster marker column (bool).
      * @returns the handle

package/src/formats/dot/index.ts

@@ -4,6 +4,8 @@
  * @module @graphty/graph-io/dot
  */
 
+export type { BendPoint } from "../../styles/canon/bends.js";
 export { DOT_LOSS, dotExporter, type DotExportOptions } from "./exporter.js";
 export { DOT_ISSUE, dotImporter, type DotImportOptions } from "./importer.js";
-export { DOT_STYLE_BLOCK_ATTRIBUTE, DOT_STYLE_CAPABILITIES } from "./styles.js";
+export { RANK_COLUMN, RANK_SET_COLUMN } from "./names.js";
+export { DOT_STYLE_BLOCK_ATTRIBUTE, DOT_STYLE_CAPABILITIES, graphvizPosBends } from "./styles.js";

package/src/formats/dot/label-places.ts

@@ -0,0 +1,241 @@
+/**
+ * Where Graphviz puts an edge's labels: a stored `lp` (the label's center), and the head and tail labels at
+ * `head_lp` / `tail_lp` -- kept only with the edge's stored `pos` (`neato -n2` routes an edge without one again, and
+ * places its labels again) -- or where Graphviz's `place_portlabel` (lib/common/splines.c) puts them, when the edge's
+ * `labelangle` or `labeldistance` is not its default: `10 * labeldistance` points from the end of the line, turned
+ * `labelangle` degrees (default -25) from the line. With both at their defaults Graphviz places end labels as external
+ * labels, which graphty leaves to its own place beside the end. Read as offsets from where graphty puts each label:
+ * the edge label from the middle of its route, an end label from where the line meets its node.
+ */
+
+import type { GraphSnapshot } from "@graphty/graph-format";
+
+import { type BendPoint, flattenCubic } from "../../styles/canon/bends.js";
+import { num6 } from "../../styles/canon/number.js";
+import type { StyleValue } from "../../styles/types.js";
+
+/** Graphviz's `PORT_LABEL_DISTANCE`, in points. */
+const PORT_LABEL_DISTANCE = 10;
+
+/** Graphviz's `PORT_LABEL_ANGLE`, in degrees. */
+const PORT_LABEL_ANGLE = -25;
+
+/** Graphviz's default node size, in inches. */
+const DEFAULT_SIZE = { w: 0.75, h: 0.5 } as const;
+
+/** One attribute of an element as text, or null when it is unset. */
+type Attr = (name: string) => string | null;
+
+/** Receives one property's value. */
+type Put = (property: string, value: StyleValue | null) => void;
+
+/** What the label places of one graph's edges are read against. */
+export interface LabelPlaceContext {
+    /** A node's center from its position, in points, y up. */
+    readonly center: (n: number) => BendPoint | null;
+    /** A node's attribute. */
+    readonly node: (n: number, name: string) => string | null;
+    /**
+     * Whether the layout engine places an edge label it was not given as an external label (every engine but `dot`,
+     * which ranks a label as a node of its own): lib/common/postproc.c `addXLabels` takes each unplaced edge label as
+     * an xlabel of the edge's middle, and lib/label/xlabels.c puts it, where nothing else is drawn, up and to the left
+     * of that point, its box's lower right corner on it.
+     */
+    readonly external: boolean;
+}
+
+/**
+ * Reads an edge's stored label places and its head and tail label places as offsets.
+ * @param snapshot - the graph
+ * @param cx - the graph's label place context
+ * @param e - the edge
+ * @param get - the edge's attributes
+ * @param put - receives the values
+ */
+export function readLabelPlaces(snapshot: GraphSnapshot, cx: LabelPlaceContext, e: number, get: Attr, put: Put): void {
+    const s = snapshot.edgeSource(e);
+    const t = snapshot.edgeTarget(e);
+    const [source, target] = [cx.center(s), cx.center(t)];
+    const route = source === null || target === null ? null : edgeRoute(source, target, get("pos"));
+    const lp = (route?.start ?? null) === null ? null : point(get("lp"));
+    if (lp === null && cx.external && s !== t && (get("label") ?? get("xlabel")) !== null) {
+        // ponytail: the first place xlabels.c tries; one that would cover another label or node moves elsewhere
+        put("labelPosition", "center");
+        put("labelShiftX", -0.5);
+        put("labelShiftY", -0.5);
+    }
+    if (route === null || source === null || target === null || s === t) {
+        return;
+    }
+    if (lp !== null && get("label") !== null) {
+        const mid = routeMiddle(route.points);
+        put("labelOffsetX", num6(lp[0] - mid[0]));
+        put("labelOffsetY", num6(mid[1] - lp[1]));
+    }
+    readEndLabel(cx, route, { node: t, at: target, other: source }, "head", get, put);
+    readEndLabel(cx, route, { node: s, at: source, other: target }, "tail", get, put);
+}
+
+/** One end of an edge: its node, that node's center and the other end's center. */
+interface EdgeEnd {
+    readonly node: number;
+    readonly at: BendPoint;
+    readonly other: BendPoint;
+}
+
+/**
+ * Reads one end's label place as an offset from where its line meets its node.
+ * @param cx - the graph's label place context
+ * @param route - the edge's route
+ * @param end - the end's node and the two centers
+ * @param which - which end
+ * @param get - the edge's attributes
+ * @param put - receives the values
+ */
+function readEndLabel(
+    cx: LabelPlaceContext,
+    route: EdgeRoute,
+    end: EdgeEnd,
+    which: "head" | "tail",
+    get: Attr,
+    put: Put,
+): void {
+    if (get(`${which}label`) === null) {
+        return;
+    }
+    const head = which === "head";
+    const tip = (head ? route.end : route.start) ?? boundary(cx, end.node, end.at, end.other);
+    // the nearest route point back from the end that is not the end itself (a spline with no arrow ends at it);
+    // the route's last point is the node's center, past the end
+    const back = head ? route.points.slice(0, -1).reverse() : route.points.slice(1);
+    const toward = back.find((p) => Math.hypot(p[0] - tip[0], p[1] - tip[1]) > 1e-6) ?? end.other;
+    const stored = route.start === null ? null : point(get(`${which}_lp`));
+    const at = stored ?? portLabel(get, tip, toward);
+    if (at !== null) {
+        const prefix = head ? "target" : "source";
+        put(`${prefix}LabelOffset`, 0);
+        put(`${prefix}LabelOffsetX`, num6(at[0] - tip[0]));
+        put(`${prefix}LabelOffsetY`, num6(tip[1] - at[1]));
+    }
+}
+
+/**
+ * Where Graphviz's `place_portlabel` puts an end label's center: only when the edge's `labelangle` or
+ * `labeldistance` is not its default.
+ * @param get - the edge's attributes
+ * @param tip - the end of the line
+ * @param toward - a point back along the line from the end
+ * @returns the center, or null when Graphviz places the label as an external label
+ */
+function portLabel(get: Attr, tip: BendPoint, toward: BendPoint): BendPoint | null {
+    const turn = finite(get("labelangle"), PORT_LABEL_ANGLE, -180);
+    const distance = finite(get("labeldistance"), 1, 0);
+    if (turn === PORT_LABEL_ANGLE && distance === 1) {
+        return null;
+    }
+    const angle = Math.atan2(toward[1] - tip[1], toward[0] - tip[0]) + (turn * Math.PI) / 180;
+    const dist = PORT_LABEL_DISTANCE * distance;
+    return [tip[0] + dist * Math.cos(angle), tip[1] + dist * Math.sin(angle)];
+}
+
+/**
+ * A number attribute as Graphviz's `late_double` reads it: the default when unset or not a number, at least `low`.
+ * @param raw - the value
+ * @param fallback - the default
+ * @param low - the least value
+ * @returns the number
+ */
+function finite(raw: string | null, fallback: number, low: number): number {
+    const v = raw === null || raw.trim() === "" ? Number.NaN : Number(raw);
+    return Number.isFinite(v) ? Math.max(low, v) : fallback;
+}
+
+/**
+ * An "x,y" point (a trailing `!` allowed).
+ * @param raw - the text
+ * @returns the point, or null
+ */
+function point(raw: string | null): BendPoint | null {
+    const parts = (raw ?? "").replace(/!$/, "").split(",").map(Number);
+    return parts.length >= 2 && Number.isFinite(parts[0]) && Number.isFinite(parts[1]) ? [parts[0], parts[1]] : null;
+}
+
+/** An edge's route: its points from center to center, and the ends of its line when stored. */
+interface EdgeRoute {
+    readonly points: BendPoint[];
+    readonly start: BendPoint | null;
+    readonly end: BendPoint | null;
+}
+
+/**
+ * The route an edge is drawn along: its stored spline's points (flattened) between the two centers, and the ends of
+ * its line where `pos` gives arrow points (`s,` / `e,`) or its spline's own ends.
+ * @param source - the source's center
+ * @param target - the target's center
+ * @param pos - the edge's `pos`
+ * @returns the route
+ */
+function edgeRoute(source: BendPoint, target: BendPoint, pos: string | null): EdgeRoute {
+    const tokens = (pos ?? "").split(";")[0].trim().split(/\s+/).filter(Boolean);
+    const marked = (flag: string): BendPoint | null => {
+        const token = tokens.find((x) => x.startsWith(`${flag},`));
+        return token === undefined ? null : point(token.slice(2));
+    };
+    const controls = tokens.filter((x) => !/^[es],/.test(x)).map((x) => point(x));
+    const flat = controls.every((p) => p !== null) && controls.length >= 4 ? flattenCubic(controls) : null;
+    if (flat === null) {
+        return { points: [source, target], start: null, end: null };
+    }
+    return {
+        points: [source, ...flat, target],
+        start: marked("s") ?? flat[0],
+        end: marked("e") ?? flat.at(-1) ?? null,
+    };
+}
+
+/**
+ * The point halfway along a route.
+ * @param points - the route
+ * @returns the point
+ */
+function routeMiddle(points: readonly BendPoint[]): BendPoint {
+    // ponytail: halfway by length; graphty puts a bent edge's label at its middle segment, close to it
+    const lengths = points.slice(1).map((p, i) => Math.hypot(p[0] - points[i][0], p[1] - points[i][1]));
+    let left = lengths.reduce((a, b) => a + b, 0) / 2;
+    for (let i = 0; i < lengths.length; i++) {
+        if (left <= lengths[i] && lengths[i] > 0) {
+            const f = left / lengths[i];
+            return [
+                points[i][0] + f * (points[i + 1][0] - points[i][0]),
+                points[i][1] + f * (points[i + 1][1] - points[i][1]),
+            ];
+        }
+        left -= lengths[i];
+    }
+    return points[0];
+}
+
+/**
+ * Where the straight line from a node's center toward a point leaves the node, the node taken as the ellipse of its
+ * `width` and `height`.
+ * @param cx - the label place context
+ * @param n - the node
+ * @param center - its center
+ * @param toward - the point
+ * @returns the point on its outline
+ */
+function boundary(cx: LabelPlaceContext, n: number, center: BendPoint, toward: BendPoint): BendPoint {
+    // ponytail: every shape taken as its ellipse; exact for the circles and ellipses the end labels sit on
+    const inch = (name: "width" | "height", fallback: number): number => {
+        const v = Number(cx.node(n, name) ?? Number.NaN);
+        return (Number.isFinite(v) && v >= 0 ? v : fallback) * 72;
+    };
+    const [rx, ry] = [inch("width", DEFAULT_SIZE.w) / 2, inch("height", DEFAULT_SIZE.h) / 2];
+    const [dx, dy] = [toward[0] - center[0], toward[1] - center[1]];
+    const len = Math.hypot(dx, dy);
+    if (len === 0 || rx === 0 || ry === 0) {
+        return center;
+    }
+    const r = 1 / Math.hypot(dx / len / rx, dy / len / ry);
+    return [center[0] + (dx / len) * r, center[1] + (dy / len) * r];
+}

package/src/formats/dot/names.ts

@@ -77,3 +77,18 @@ export const PIN_ATTRIBUTE = "pin";
  * @category Plugin helpers
  */
 export const DOT_META_KEY = "dot";
+
+/**
+ * The string node column holding the `rank` of the non-cluster subgraph a node is in (`same`,
+ * `min`, `max`, `source` or `sink`): Graphviz's dot puts the subgraph's nodes on one rank, or on
+ * the first or last. Set only on nodes of such a subgraph.
+ * @category Plugin helpers
+ */
+export const RANK_COLUMN = "graphty.rank";
+
+/**
+ * The string node column naming the rank subgraph a node is in (`graphty.rank`): the subgraph's
+ * name, or `%<n>` for the n-th anonymous one, so the nodes of one subgraph share a value.
+ * @category Plugin helpers
+ */
+export const RANK_SET_COLUMN = "graphty.rankSet";