pict-section-flow 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pict-section-flow",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "description": "Pict Section Flow Diagram",
     "main": "source/Pict-Section-Flow.js",
     "scripts": {

package/source/providers/layouts/Layout-Layered.js

@@ -1,9 +1,10 @@
 const libCoerce = require('./Layout-Coerce.js');
+const libRank = require('./Layout-Rank.js');
 
 /**
  * Layout-Layered
  *
- * Topological-sort (Kahn's algorithm) left-to-right layered layout.
+ * Cycle-tolerant left-to-right layered layout.
  *
  * This is the original `autoLayout` behavior of pict-section-flow,
  * extracted into a layout-algorithm descriptor. Calling
@@ -34,100 +35,45 @@ module.exports =
 
 		let tmpConnections = Array.isArray(pConnections) ? pConnections : [];
 
-		// Build adjacency information
 		let tmpNodeMap = {};
-		let tmpInDegree = {};
-		let tmpOutEdges = {};
-
 		for (let i = 0; i < pNodes.length; i++)
 		{
-			let tmpNode = pNodes[i];
-			tmpNodeMap[tmpNode.Hash] = tmpNode;
-			tmpInDegree[tmpNode.Hash] = 0;
-			tmpOutEdges[tmpNode.Hash] = [];
-		}
-
-		for (let i = 0; i < tmpConnections.length; i++)
-		{
-			let tmpConn = tmpConnections[i];
-			if (tmpInDegree.hasOwnProperty(tmpConn.TargetNodeHash))
-			{
-				tmpInDegree[tmpConn.TargetNodeHash]++;
-			}
-			if (tmpOutEdges.hasOwnProperty(tmpConn.SourceNodeHash))
-			{
-				tmpOutEdges[tmpConn.SourceNodeHash].push(tmpConn.TargetNodeHash);
-			}
+			tmpNodeMap[pNodes[i].Hash] = pNodes[i];
 		}
 
-		// Topological sort (Kahn's algorithm)
-		let tmpLayers = [];
-		let tmpQueue = [];
-		let tmpAssigned = {};
-
-		for (let tmpHash in tmpInDegree)
+		// Rank the nodes into layers, left to right, with cycle breaking. The
+		// shared ranker keeps back-edged graphs (workflows, state machines) from
+		// collapsing into one tall column the way plain Kahn's topological sort
+		// would. See Layout-Rank.js.
+		let tmpLayers = libRank.toRanks(pNodes, tmpConnections);
+
+		// Measure each layer's stacked height so layers can be centered on one
+		// shared horizontal axis. Without centering every layer top-aligns at
+		// StartY, so a one-node layer beside a five-node layer reads as a
+		// diagonal drift down the page instead of a balanced band.
+		let tmpLayerHeights = [];
+		let tmpMaxLayerHeight = 0;
+		for (let l = 0; l < tmpLayers.length; l++)
 		{
-			if (tmpInDegree[tmpHash] === 0)
+			let tmpHeight = 0;
+			for (let i = 0; i < tmpLayers[l].length; i++)
 			{
-				tmpQueue.push(tmpHash);
+				let tmpNode = tmpNodeMap[tmpLayers[l][i]];
+				tmpHeight += (tmpNode && tmpNode.Height) ? tmpNode.Height : 80;
+				if (i > 0) tmpHeight += tmpVerticalSpacing;
 			}
+			tmpLayerHeights.push(tmpHeight);
+			if (tmpHeight > tmpMaxLayerHeight) tmpMaxLayerHeight = tmpHeight;
 		}
 
-		while (tmpQueue.length > 0)
-		{
-			let tmpCurrentLayer = [];
-			let tmpNextQueue = [];
-
-			for (let i = 0; i < tmpQueue.length; i++)
-			{
-				let tmpNodeHash = tmpQueue[i];
-				if (tmpAssigned[tmpNodeHash]) continue;
-
-				tmpAssigned[tmpNodeHash] = true;
-				tmpCurrentLayer.push(tmpNodeHash);
-
-				let tmpEdges = tmpOutEdges[tmpNodeHash] || [];
-				for (let j = 0; j < tmpEdges.length; j++)
-				{
-					let tmpTargetHash = tmpEdges[j];
-					tmpInDegree[tmpTargetHash]--;
-					if (tmpInDegree[tmpTargetHash] <= 0 && !tmpAssigned[tmpTargetHash])
-					{
-						tmpNextQueue.push(tmpTargetHash);
-					}
-				}
-			}
-
-			if (tmpCurrentLayer.length > 0)
-			{
-				tmpLayers.push(tmpCurrentLayer);
-			}
-
-			tmpQueue = tmpNextQueue;
-		}
-
-		// Handle cycles or disconnected nodes
-		let tmpRemainingNodes = [];
-		for (let i = 0; i < pNodes.length; i++)
-		{
-			if (!tmpAssigned[pNodes[i].Hash])
-			{
-				tmpRemainingNodes.push(pNodes[i].Hash);
-			}
-		}
-		if (tmpRemainingNodes.length > 0)
-		{
-			tmpLayers.push(tmpRemainingNodes);
-		}
-
-		// Assign positions based on layers
+		// Assign positions: one column per layer, each layer vertically centered.
 		let tmpCurrentX = tmpStartX;
 
 		for (let tmpLayerIndex = 0; tmpLayerIndex < tmpLayers.length; tmpLayerIndex++)
 		{
 			let tmpLayer = tmpLayers[tmpLayerIndex];
 			let tmpMaxWidth = 0;
-			let tmpCurrentY = tmpStartY;
+			let tmpCurrentY = tmpStartY + ((tmpMaxLayerHeight - tmpLayerHeights[tmpLayerIndex]) / 2);
 
 			for (let i = 0; i < tmpLayer.length; i++)
 			{

package/source/providers/layouts/Layout-Rank.js

@@ -0,0 +1,141 @@
+/**
+ * Layout-Rank
+ *
+ * Shared cycle-tolerant topological ranking for the directed layouts
+ * (Layered, Staggered).
+ *
+ * Plain Kahn's topological sort drops every node that participates in a cycle
+ * into a single trailing rank. Any graph with back-edges (workflows, state
+ * machines: rejections, retries, "send back") therefore collapses into one
+ * tall stripe of unranked nodes, which is the historical "auto-layout bunches
+ * everything together and is useless" behavior.
+ *
+ * `toRanks` instead breaks each cycle at its most-resolved node: when a round
+ * finds nothing dependency-free but nodes remain, it forces the unassigned
+ * node with the fewest unmet predecessors into the next rank and continues.
+ * Cyclic graphs then rank left to right the same way a DAG does.
+ *
+ * Returns an array of ranks; each rank is an array of node Hashes in stable
+ * source order. Self-loops are ignored for ranking (they cannot define an
+ * order). Callers map Hashes back to node objects themselves.
+ */
+function toRanks(pNodes, pConnections)
+{
+	let tmpRanks = [];
+	if (!pNodes || pNodes.length === 0)
+	{
+		return tmpRanks;
+	}
+
+	let tmpConnections = Array.isArray(pConnections) ? pConnections : [];
+
+	let tmpInDegree = {};
+	let tmpOutEdges = {};
+	for (let i = 0; i < pNodes.length; i++)
+	{
+		tmpInDegree[pNodes[i].Hash] = 0;
+		tmpOutEdges[pNodes[i].Hash] = [];
+	}
+
+	for (let i = 0; i < tmpConnections.length; i++)
+	{
+		let tmpConn = tmpConnections[i];
+		// A self-loop cannot define a rank order; skip it.
+		if (tmpConn.SourceNodeHash === tmpConn.TargetNodeHash)
+		{
+			continue;
+		}
+		if (tmpInDegree.hasOwnProperty(tmpConn.TargetNodeHash))
+		{
+			tmpInDegree[tmpConn.TargetNodeHash]++;
+		}
+		if (tmpOutEdges.hasOwnProperty(tmpConn.SourceNodeHash))
+		{
+			tmpOutEdges[tmpConn.SourceNodeHash].push(tmpConn.TargetNodeHash);
+		}
+	}
+
+	let tmpAssigned = {};
+	let tmpAssignedCount = 0;
+
+	while (tmpAssignedCount < pNodes.length)
+	{
+		let tmpRank = [];
+
+		for (let i = 0; i < pNodes.length; i++)
+		{
+			let tmpHash = pNodes[i].Hash;
+			if (!tmpAssigned[tmpHash] && tmpInDegree[tmpHash] <= 0)
+			{
+				tmpRank.push(tmpHash);
+			}
+		}
+
+		if (tmpRank.length === 0)
+		{
+			// Cycle break: nothing is dependency-free, so force the unassigned
+			// node with the fewest remaining predecessors (ties keep source
+			// order, which keeps the result stable across runs).
+			let tmpMinDegree = Infinity;
+			let tmpPick = null;
+			for (let i = 0; i < pNodes.length; i++)
+			{
+				let tmpHash = pNodes[i].Hash;
+				if (!tmpAssigned[tmpHash] && tmpInDegree[tmpHash] < tmpMinDegree)
+				{
+					tmpMinDegree = tmpInDegree[tmpHash];
+					tmpPick = tmpHash;
+				}
+			}
+			if (tmpPick === null)
+			{
+				break; // safety; every node is already assigned
+			}
+			tmpRank.push(tmpPick);
+		}
+
+		// Commit the whole rank, then relax its out-edges so the next round
+		// sees the successors it just freed.
+		for (let i = 0; i < tmpRank.length; i++)
+		{
+			tmpAssigned[tmpRank[i]] = true;
+			tmpAssignedCount++;
+		}
+		for (let i = 0; i < tmpRank.length; i++)
+		{
+			let tmpEdges = tmpOutEdges[tmpRank[i]] || [];
+			for (let j = 0; j < tmpEdges.length; j++)
+			{
+				tmpInDegree[tmpEdges[j]]--;
+			}
+		}
+
+		tmpRanks.push(tmpRank);
+	}
+
+	return tmpRanks;
+}
+
+/**
+ * Flatten ranks to a single ordered list of node Hashes (rank by rank, source
+ * order within a rank). Convenience for layouts that walk one sequence.
+ */
+function toOrder(pNodes, pConnections)
+{
+	let tmpRanks = toRanks(pNodes, pConnections);
+	let tmpOrder = [];
+	for (let i = 0; i < tmpRanks.length; i++)
+	{
+		for (let j = 0; j < tmpRanks[i].length; j++)
+		{
+			tmpOrder.push(tmpRanks[i][j]);
+		}
+	}
+	return tmpOrder;
+}
+
+module.exports =
+{
+	toRanks: toRanks,
+	toOrder: toOrder
+};

package/source/providers/layouts/Layout-Staggered.js

@@ -0,0 +1,131 @@
+const libCoerce = require('./Layout-Coerce.js');
+const libRank = require('./Layout-Rank.js');
+
+/**
+ * Layout-Staggered
+ *
+ * Serpentine "stairstep" layout for directed graphs. It ranks the nodes left
+ * to right by connection topology (the same cycle-tolerant ranking the Layered
+ * layout uses), then walks that ordered sequence along a band that steps down a
+ * few rows and back up, advancing horizontally at every node.
+ *
+ * The point is vertical-space efficiency: a long directed chain (a workflow, a
+ * delivery pipeline, a state machine) laid out purely left to right runs off
+ * the right edge of the canvas. Folding it into a stairstep band keeps the
+ * left-to-right reading order while using the height of the viewport, so the
+ * whole graph frames at a usable zoom.
+ *
+ * `Rows` sets how deep the band steps before folding back: 2 is a simple
+ * zigzag (odd nodes high, even nodes low); 3+ is a deeper stairstep. The row
+ * index follows a triangle wave so the band descends and then climbs rather
+ * than snapping back to the top between runs.
+ *
+ * Numeric parameters are typed `PreciseNumber` so they survive ExpressionParser
+ * solver chains; Layout-Coerce converts them back to JS floats at entry.
+ */
+module.exports =
+{
+	Name: 'Staggered',
+	Label: 'Staggered (Stairstep)',
+	Description: 'Topological order folded along a serpentine stairstep band.',
+	DefaultEdgeTheme: 'Perimeter',
+
+	Apply: function (pNodes, pConnections, pParameters)
+	{
+		if (!pNodes || pNodes.length === 0) return;
+
+		let tmpParams = pParameters || {};
+		let tmpSpacing       = libCoerce.toFloat(tmpParams.Spacing, 1.0);
+		let tmpRows          = Math.max(1, libCoerce.toInt(tmpParams.Rows, 2));
+		let tmpColumnSpacing = libCoerce.toFloat(tmpParams.ColumnSpacing, 80) * tmpSpacing;
+		let tmpRowOffset     = libCoerce.toFloat(tmpParams.RowOffset, 150) * tmpSpacing;
+		let tmpStartX        = libCoerce.toFloat(tmpParams.StartX, 80);
+		let tmpStartY        = libCoerce.toFloat(tmpParams.StartY, 80);
+
+		let tmpConnections = Array.isArray(pConnections) ? pConnections : [];
+
+		let tmpNodeMap = {};
+		for (let i = 0; i < pNodes.length; i++)
+		{
+			tmpNodeMap[pNodes[i].Hash] = pNodes[i];
+		}
+
+		let tmpOrder = libRank.toOrder(pNodes, tmpConnections);
+
+		// A uniform column pitch (the widest node plus the spacing) keeps the
+		// stairstep diagonal even regardless of individual node widths.
+		let tmpMaxWidth = 0;
+		for (let i = 0; i < pNodes.length; i++)
+		{
+			tmpMaxWidth = Math.max(tmpMaxWidth, pNodes[i].Width || 180);
+		}
+		let tmpColumnPitch = tmpMaxWidth + tmpColumnSpacing;
+
+		// Triangle wave: descend (Rows - 1) steps, then climb (Rows - 1) steps.
+		let tmpPeriod = (tmpRows > 1) ? (2 * (tmpRows - 1)) : 1;
+
+		for (let i = 0; i < tmpOrder.length; i++)
+		{
+			let tmpNode = tmpNodeMap[tmpOrder[i]];
+			if (!tmpNode) continue;
+
+			let tmpRow;
+			if (tmpRows <= 1)
+			{
+				tmpRow = 0;
+			}
+			else
+			{
+				let tmpPhase = i % tmpPeriod;
+				tmpRow = (tmpPhase < tmpRows) ? tmpPhase : (tmpPeriod - tmpPhase);
+			}
+
+			tmpNode.X = tmpStartX + (i * tmpColumnPitch);
+			tmpNode.Y = tmpStartY + (tmpRow * tmpRowOffset);
+		}
+	},
+
+	DefaultParameters:
+	{
+		Spacing: 1.0,
+		Rows: 2,
+		ColumnSpacing: 80,
+		RowOffset: 150,
+		StartX: 80,
+		StartY: 80
+	},
+
+	ParameterSchema:
+	{
+		Spacing:       { Type: 'PreciseNumber', Label: 'Spacing (multiplier)', Default: 1.0, Min: 0.1, Max: 5 },
+		Rows:          { Type: 'Number',        Label: 'Rows',          Default: 2,   Min: 1, Max: 12 },
+		ColumnSpacing: { Type: 'PreciseNumber', Label: 'Column spacing', Default: 80,  Min: 0, Max: 1000 },
+		RowOffset:     { Type: 'PreciseNumber', Label: 'Row offset',    Default: 150, Min: 0, Max: 1000 },
+		StartX:        { Type: 'PreciseNumber', Label: 'Start X',       Default: 80,  Min: -10000, Max: 10000 },
+		StartY:        { Type: 'PreciseNumber', Label: 'Start Y',       Default: 80,  Min: -10000, Max: 10000 }
+	},
+
+	ParameterManifest:
+	{
+		Scope: 'PictFlowLayout-Staggered',
+		Sections:
+		[
+			{ Name: 'Staggered Parameters', Hash: 'PFLStaggeredSection', Groups: [{ Name: 'Defaults', Hash: 'PFLStaggeredGroup' }] }
+		],
+		Descriptors:
+		{
+			'PictFlowLayoutEditor.Parameters.Spacing':
+			{ Name: 'Spacing (multiplier)', Hash: 'Spacing', DataType: 'PreciseNumber', Default: 1.0, PictForm: { Section: 'PFLStaggeredSection', Group: 'PFLStaggeredGroup', Row: 0, Width: 6, Min: 0.1, Max: 5 } },
+			'PictFlowLayoutEditor.Parameters.Rows':
+			{ Name: 'Rows', Hash: 'Rows', DataType: 'Number', Default: 2, PictForm: { Section: 'PFLStaggeredSection', Group: 'PFLStaggeredGroup', Row: 0, Width: 6, Min: 1, Max: 12 } },
+			'PictFlowLayoutEditor.Parameters.ColumnSpacing':
+			{ Name: 'Column spacing', Hash: 'ColumnSpacing', DataType: 'PreciseNumber', Default: 80, PictForm: { Section: 'PFLStaggeredSection', Group: 'PFLStaggeredGroup', Row: 1, Width: 6, Min: 0, Max: 1000 } },
+			'PictFlowLayoutEditor.Parameters.RowOffset':
+			{ Name: 'Row offset', Hash: 'RowOffset', DataType: 'PreciseNumber', Default: 150, PictForm: { Section: 'PFLStaggeredSection', Group: 'PFLStaggeredGroup', Row: 1, Width: 6, Min: 0, Max: 1000 } },
+			'PictFlowLayoutEditor.Parameters.StartX':
+			{ Name: 'Start X', Hash: 'StartX', DataType: 'PreciseNumber', Default: 80, PictForm: { Section: 'PFLStaggeredSection', Group: 'PFLStaggeredGroup', Row: 2, Width: 6, Min: -10000, Max: 10000 } },
+			'PictFlowLayoutEditor.Parameters.StartY':
+			{ Name: 'Start Y', Hash: 'StartY', DataType: 'PreciseNumber', Default: 80, PictForm: { Section: 'PFLStaggeredSection', Group: 'PFLStaggeredGroup', Row: 2, Width: 6, Min: -10000, Max: 10000 } }
+		}
+	}
+};

package/source/services/PictService-Flow-Layout.js

@@ -2,6 +2,7 @@ const libFableServiceProviderBase = require('fable-serviceproviderbase');
 
 const libLayoutCustom           = require('../providers/layouts/Layout-Custom.js');
 const libLayoutLayered          = require('../providers/layouts/Layout-Layered.js');
+const libLayoutStaggered        = require('../providers/layouts/Layout-Staggered.js');
 const libLayoutForcedFromCenter = require('../providers/layouts/Layout-ForcedFromCenter.js');
 const libLayoutGrid             = require('../providers/layouts/Layout-Grid.js');
 const libLayoutCircular         = require('../providers/layouts/Layout-Circular.js');
@@ -20,6 +21,7 @@ const _BUILTIN_ALGORITHMS =
 [
 	libLayoutCustom,
 	libLayoutLayered,
+	libLayoutStaggered,
 	libLayoutForcedFromCenter,
 	libLayoutGrid,
 	libLayoutCircular,

package/source/views/PictView-Flow-Node.js

@@ -529,8 +529,44 @@ class PictViewFlowNode extends libPictView
 	 * @param {number} pTitleBarHeight
 	 * @param {Object} pNodeTypeConfig
 	 */
+	// Append a CSS fragment to an SVG element's inline style (which wins over the stylesheet), keeping
+	// any existing inline style.
+	_appendElementStyle(pElement, pStyleFragment)
+	{
+		let tmpExisting = pElement.getAttribute('style') || '';
+		if (tmpExisting && tmpExisting.charAt(tmpExisting.length - 1) !== ';') { tmpExisting += ';'; }
+		pElement.setAttribute('style', tmpExisting + pStyleFragment);
+	}
+
+	/**
+	 * Height of the strip that squares off the bottom corners of the title bar. It must cover the
+	 * bottom rounded corners (so the title bar meets the body in a straight seam) but must never reach
+	 * the top ones, so it is capped at half the title bar height. Without the cap a corner radius
+	 * larger than the title bar (a capsule card: radius 24 on a 22px bar) yields a strip taller than
+	 * the whole title bar, which paints over the rounded TOP corners and makes the card read as square
+	 * on top and rounded only on the bottom.
+	 *
+	 * @param {number|null} pCornerRadius - the card corner radius, or null for the theme default
+	 * @param {number} pTitleBarHeight - the title bar height in user units
+	 * @returns {number}
+	 */
+	static titleBarBottomStripHeight(pCornerRadius, pTitleBarHeight)
+	{
+		let tmpRadius = (typeof pCornerRadius === 'number') ? pCornerRadius : 0;
+		return Math.min(Math.max(8, tmpRadius), Math.floor(pTitleBarHeight / 2));
+	}
+
 	_renderRectNodeBody(pGroup, pNodeData, pWidth, pHeight, pTitleBarHeight, pNodeTypeConfig)
 	{
+		// Per-card corner radius (a node-data or node-type override of the theme default), so a card
+		// type can read as a rounded rectangle, a capsule, or a sharp box. null leaves the
+		// theme/CSS default in place. Set as the --pf-node-body-radius custom property on the node
+		// group; the body and title-bar both read it through their `rx: var(--pf-node-body-radius)`,
+		// and it inherits to both, so one assignment rounds the whole card.
+		let tmpCornerRadius = (typeof pNodeData.CornerRadius === 'number') ? pNodeData.CornerRadius
+			: ((pNodeTypeConfig && typeof pNodeTypeConfig.CornerRadius === 'number') ? pNodeTypeConfig.CornerRadius : null);
+		if (tmpCornerRadius != null) { this._appendElementStyle(pGroup, '--pf-node-body-radius:' + tmpCornerRadius + 'px'); }
+
 		// Node body (main rectangle)
 		let tmpBody = this._FlowView._SVGHelperProvider.createSVGElement('rect');
 		tmpBody.setAttribute('class', 'pict-flow-node-body');
@@ -598,16 +634,17 @@ class PictViewFlowNode extends libPictView
 		{
 			tmpTitleBar.setAttribute('fill', pNodeData.TitleBarColor);
 		}
-
 		pGroup.appendChild(tmpTitleBar);
 
-		// Title bar bottom fill (to square off the rounded corners at the bottom of the title bar)
+		// Title bar bottom fill: squares off the rounded corners at the bottom of the title bar so it
+		// meets the body in a straight seam. See titleBarBottomStripHeight for why it is capped.
+		let tmpBottomStripHeight = PictViewFlowNode.titleBarBottomStripHeight(tmpCornerRadius, pTitleBarHeight);
 		let tmpTitleBarBottom = this._FlowView._SVGHelperProvider.createSVGElement('rect');
 		tmpTitleBarBottom.setAttribute('class', 'pict-flow-node-title-bar-bottom');
 		tmpTitleBarBottom.setAttribute('x', '0');
-		tmpTitleBarBottom.setAttribute('y', String(pTitleBarHeight - 8));
+		tmpTitleBarBottom.setAttribute('y', String(pTitleBarHeight - tmpBottomStripHeight));
 		tmpTitleBarBottom.setAttribute('width', String(pWidth));
-		tmpTitleBarBottom.setAttribute('height', '8');
+		tmpTitleBarBottom.setAttribute('height', String(tmpBottomStripHeight));
 		tmpTitleBarBottom.setAttribute('data-node-hash', pNodeData.Hash);
 		tmpTitleBarBottom.setAttribute('data-element-type', 'node-body');
 

package/test/Layout_tests.js

@@ -6,6 +6,8 @@ const libLayoutService = require('../source/services/PictService-Flow-Layout.js'
 
 const libLayoutCustom           = require('../source/providers/layouts/Layout-Custom.js');
 const libLayoutLayered          = require('../source/providers/layouts/Layout-Layered.js');
+const libLayoutStaggered        = require('../source/providers/layouts/Layout-Staggered.js');
+const libLayoutRank             = require('../source/providers/layouts/Layout-Rank.js');
 const libLayoutForcedFromCenter = require('../source/providers/layouts/Layout-ForcedFromCenter.js');
 const libLayoutGrid             = require('../source/providers/layouts/Layout-Grid.js');
 const libLayoutCircular         = require('../source/providers/layouts/Layout-Circular.js');
@@ -86,15 +88,15 @@ suite
 
 				test
 				(
-					'should register all seven built-in algorithms by default',
+					'should register all eight built-in algorithms by default',
 					function (fDone)
 					{
 						let tmpNames = _LayoutService.getAlgorithmNames();
 						libExpect(tmpNames).to.include.members([
-							'Custom', 'Layered', 'ForcedFromCenter',
+							'Custom', 'Layered', 'Staggered', 'ForcedFromCenter',
 							'Grid', 'Circular', 'Tabular', 'Columnar'
 						]);
-						libExpect(tmpNames.length).to.equal(7);
+						libExpect(tmpNames.length).to.equal(8);
 						fDone();
 					}
 				);
@@ -184,9 +186,10 @@ suite
 					function (fDone)
 					{
 						let tmpAll = _LayoutService.listAlgorithms();
-						libExpect(tmpAll.length).to.equal(7);
+						libExpect(tmpAll.length).to.equal(8);
 						let tmpNames = tmpAll.map((pA) => pA.Name);
 						libExpect(tmpNames).to.include('Custom');
+						libExpect(tmpNames).to.include('Staggered');
 						libExpect(tmpNames).to.include('ForcedFromCenter');
 						fDone();
 					}
@@ -315,6 +318,207 @@ suite
 						fDone();
 					}
 				);
+
+				test
+				(
+					'a back-edge cycle does NOT collapse into one column (regression)',
+					function (fDone)
+					{
+						// n0 -> n1 -> n2 -> n3 -> n4 with a back-edge n4 -> n1.
+						// Plain Kahn's would place n0, then dump n1..n4 into a single
+						// trailing layer (one tall column). The cycle-tolerant ranker
+						// must spread them across columns instead.
+						let tmpNodes = makeNodes(5);
+						let tmpConns = makeChain(5);
+						tmpConns.push({ Hash: 'c-back', SourceNodeHash: 'n-4', TargetNodeHash: 'n-1' });
+
+						libLayoutLayered.Apply(tmpNodes, tmpConns, libLayoutLayered.DefaultParameters);
+
+						let tmpColumns = {};
+						let tmpMaxPerColumn = 0;
+						for (let i = 0; i < tmpNodes.length; i++)
+						{
+							let tmpX = tmpNodes[i].X;
+							tmpColumns[tmpX] = (tmpColumns[tmpX] || 0) + 1;
+							tmpMaxPerColumn = Math.max(tmpMaxPerColumn, tmpColumns[tmpX]);
+						}
+						// Five distinct columns, one node each — no tower.
+						libExpect(Object.keys(tmpColumns).length).to.equal(5);
+						libExpect(tmpMaxPerColumn).to.equal(1);
+						fDone();
+					}
+				);
+
+				test
+				(
+					'a self-loop does not strand a node in a trailing column',
+					function (fDone)
+					{
+						// n0 -> n1 -> n2 with a self-loop on n1.
+						let tmpNodes = makeNodes(3);
+						let tmpConns = makeChain(3);
+						tmpConns.push({ Hash: 'c-self', SourceNodeHash: 'n-1', TargetNodeHash: 'n-1' });
+
+						libLayoutLayered.Apply(tmpNodes, tmpConns, libLayoutLayered.DefaultParameters);
+
+						// Clean chain: three columns left to right, one node each.
+						libExpect(tmpNodes[0].X).to.be.below(tmpNodes[1].X);
+						libExpect(tmpNodes[1].X).to.be.below(tmpNodes[2].X);
+						fDone();
+					}
+				);
+			}
+		);
+
+		// ── Rank (shared ranker) ──────────────────────────────────────
+
+		suite
+		(
+			'Layout-Rank ranker',
+			function ()
+			{
+				test
+				(
+					'a chain ranks one node per rank, in order',
+					function (fDone)
+					{
+						let tmpNodes = makeNodes(4);
+						let tmpRanks = libLayoutRank.toRanks(tmpNodes, makeChain(4));
+						libExpect(tmpRanks.length).to.equal(4);
+						libExpect(tmpRanks[0]).to.deep.equal(['n-0']);
+						libExpect(tmpRanks[3]).to.deep.equal(['n-3']);
+						fDone();
+					}
+				);
+
+				test
+				(
+					'unconnected nodes share the first rank',
+					function (fDone)
+					{
+						let tmpNodes = makeNodes(3);
+						let tmpRanks = libLayoutRank.toRanks(tmpNodes, []);
+						libExpect(tmpRanks.length).to.equal(1);
+						libExpect(tmpRanks[0].length).to.equal(3);
+						fDone();
+					}
+				);
+
+				test
+				(
+					'toOrder visits every node exactly once even with a cycle',
+					function (fDone)
+					{
+						let tmpNodes = makeNodes(5);
+						let tmpConns = makeChain(5);
+						tmpConns.push({ Hash: 'c-back', SourceNodeHash: 'n-4', TargetNodeHash: 'n-1' });
+						let tmpOrder = libLayoutRank.toOrder(tmpNodes, tmpConns);
+						libExpect(tmpOrder.length).to.equal(5);
+						let tmpSeen = {};
+						for (let i = 0; i < tmpOrder.length; i++) tmpSeen[tmpOrder[i]] = true;
+						libExpect(Object.keys(tmpSeen).length).to.equal(5);
+						fDone();
+					}
+				);
+
+				test
+				(
+					'empty input returns an empty rank list',
+					function (fDone)
+					{
+						libExpect(libLayoutRank.toRanks([], [])).to.deep.equal([]);
+						libExpect(libLayoutRank.toOrder(null, null)).to.deep.equal([]);
+						fDone();
+					}
+				);
+			}
+		);
+
+		// ── Staggered ─────────────────────────────────────────────────
+
+		suite
+		(
+			'Staggered algorithm',
+			function ()
+			{
+				test
+				(
+					'two rows zigzag: X strictly increases, Y alternates',
+					function (fDone)
+					{
+						let tmpNodes = makeNodes(4);
+						let tmpConns = makeChain(4);
+						libLayoutStaggered.Apply(tmpNodes, tmpConns, { Rows: 2, ColumnSpacing: 80, RowOffset: 150, StartX: 0, StartY: 0 });
+
+						// Topological order is n0..n3; column pitch = 180 + 80 = 260.
+						libExpect(tmpNodes[0].X).to.equal(0);
+						libExpect(tmpNodes[1].X).to.equal(260);
+						libExpect(tmpNodes[2].X).to.equal(520);
+						libExpect(tmpNodes[3].X).to.equal(780);
+						// Rows=2 → row pattern 0,1,0,1 → Y 0,150,0,150.
+						libExpect(tmpNodes[0].Y).to.equal(0);
+						libExpect(tmpNodes[1].Y).to.equal(150);
+						libExpect(tmpNodes[2].Y).to.equal(0);
+						libExpect(tmpNodes[3].Y).to.equal(150);
+						fDone();
+					}
+				);
+
+				test
+				(
+					'three rows make a triangle-wave stairstep (down then up)',
+					function (fDone)
+					{
+						let tmpNodes = makeNodes(6);
+						let tmpConns = makeChain(6);
+						libLayoutStaggered.Apply(tmpNodes, tmpConns, { Rows: 3, RowOffset: 100, StartX: 0, StartY: 0 });
+
+						// period = 4 → row phases 0,1,2,1,0,1 → Y 0,100,200,100,0,100.
+						let tmpRows = tmpNodes.map((pN) => pN.Y / 100);
+						libExpect(tmpRows).to.deep.equal([0, 1, 2, 1, 0, 1]);
+						fDone();
+					}
+				);
+
+				test
+				(
+					'column pitch follows the widest node',
+					function (fDone)
+					{
+						let tmpNodes = makeNodes(3);
+						tmpNodes[1].Width = 400; // widest
+						libLayoutStaggered.Apply(tmpNodes, makeChain(3), { ColumnSpacing: 50, StartX: 0 });
+						// pitch = 400 + 50 = 450
+						libExpect(tmpNodes[1].X).to.equal(450);
+						libExpect(tmpNodes[2].X).to.equal(900);
+						fDone();
+					}
+				);
+
+				test
+				(
+					'Rows=1 places every node on a single row',
+					function (fDone)
+					{
+						let tmpNodes = makeNodes(4);
+						libLayoutStaggered.Apply(tmpNodes, makeChain(4), { Rows: 1, StartY: 42 });
+						for (let i = 0; i < tmpNodes.length; i++)
+						{
+							libExpect(tmpNodes[i].Y).to.equal(42);
+						}
+						fDone();
+					}
+				);
+
+				test
+				(
+					'empty node list does not throw',
+					function (fDone)
+					{
+						libExpect(function () { libLayoutStaggered.Apply([], [], {}); }).to.not.throw();
+						fDone();
+					}
+				);
 			}
 		);
 

package/test/NodeView_tests.js

@@ -0,0 +1,49 @@
+const libChai = require('chai');
+const libExpect = libChai.expect;
+
+const libPictViewFlowNode = require('../source/views/PictView-Flow-Node.js');
+
+suite('PictView-Flow-Node',
+function ()
+{
+	// The title-bar bottom strip squares off the title bar's lower corners. The regression it guards
+	// against: a corner radius larger than the title bar made the strip taller than the whole title
+	// bar, so it painted over the rounded TOP corners and the card read as square on top (only the
+	// bottom rounded). See titleBarBottomStripHeight.
+	suite('titleBarBottomStripHeight',
+	function ()
+	{
+		test('never exceeds half the title bar height, even for a capsule radius',
+		function ()
+		{
+			// radius 24 on a 22px title bar must not produce a 24px strip (which would cover the top)
+			libExpect(libPictViewFlowNode.titleBarBottomStripHeight(24, 22)).to.equal(11);
+			libExpect(libPictViewFlowNode.titleBarBottomStripHeight(100, 30)).to.equal(15);
+		});
+
+		test('covers small radii with the 8px floor',
+		function ()
+		{
+			libExpect(libPictViewFlowNode.titleBarBottomStripHeight(5, 22)).to.equal(8);
+			libExpect(libPictViewFlowNode.titleBarBottomStripHeight(0, 22)).to.equal(8);
+		});
+
+		test('treats a null/absent radius as no override (8px floor)',
+		function ()
+		{
+			libExpect(libPictViewFlowNode.titleBarBottomStripHeight(null, 22)).to.equal(8);
+			libExpect(libPictViewFlowNode.titleBarBottomStripHeight(undefined, 22)).to.equal(8);
+		});
+
+		test('the strip is always at most the title bar height for any radius',
+		function ()
+		{
+			let tmpTitleBarHeight = 22;
+			for (let tmpRadius = 0; tmpRadius <= 60; tmpRadius++)
+			{
+				let tmpStrip = libPictViewFlowNode.titleBarBottomStripHeight(tmpRadius, tmpTitleBarHeight);
+				libExpect(tmpStrip).to.be.at.most(Math.floor(tmpTitleBarHeight / 2));
+			}
+		});
+	});
+});