Make pass/fail edges the loudest lines in the run graph

Treat `success` and `error` as the emphasised outcomes so pass/fail is
obvious at a glance and from a distance. An executed pass/fail edge now
uses PASSFAIL_EDGE_STROKE=7f (was 3f), a same-hue, more saturated stroke
(PASSFAIL_SATURATION=1.6f via the new pure boostSaturation helper) and a
matched PASSFAIL_ARROW_HEAD_SIZE=20f arrowhead. Other executed outcomes
keep EDGE_STROKE=3f and not-executed routes the finer
INACTIVE_EDGE_STROKE=2.5f, so the two decisive outcomes dominate.

All widths, the arrowhead size and the saturation factor are named
tokens chosen by edgeStrokeWidth/edgeArrowHeadSize/edgeStrokeColor; the
old 12f arrowhead literal at the call site is gone (drawArrowHead now
takes the size as a parameter). Outcome hues are unchanged; the boosted
stroke keeps the original hue and value.

The run Graph tab help line notes that executed success and failure
routes are drawn thickest, and the definition-only view gets the same
emphasis since every route counts as executed there. New unit tests cover
the saturation maths (hue/value/alpha preserved, safe and clamped) and the
per-edge width/arrowhead/colour choices.
This commit is contained in:
2026-10-16 08:06:34 +01:00
parent 9c47527def
commit 1e7862e7c9
6 changed files with 353 additions and 19 deletions
@@ -94,6 +94,36 @@ internal fun graphNodeKind(terminal: Boolean, key: String, type: String?): Graph
else -> GraphNodeKind.Custom
}
/**
* A more vivid version of [color] with the same hue, value and alpha: the HSV
* saturation is scaled by [factor] and clamped to 1. Used to make an executed
* pass/fail edge stroke stronger without changing its outcome hue, so both
* terminal colours get more punch while staying recognisably success/failure.
*
* Pure sRGB maths. A non-finite/non-positive [factor], an achromatic colour or
* one already at full saturation returns [color] unchanged, so callers never get
* NaN and every input is safe.
*/
internal fun boostSaturation(color: Color, factor: Float): Color {
if (!factor.isFinite() || factor <= 0f) return color
val r = color.red
val g = color.green
val b = color.blue
val max = maxOf(r, g, b)
val min = minOf(r, g, b)
val delta = max - min
if (max <= 0f || delta <= 0f) return color
val current = delta / max
val saturation = (current * factor).coerceAtMost(1f)
if (saturation <= current) return color
val hue = (when (max) {
r -> ((g - b) / delta + 6f) % 6f
g -> (b - r) / delta + 2f
else -> (r - g) / delta + 4f
}) * 60f
return Color.hsv(hue, saturation, max, color.alpha)
}
/**
* WCAG relative luminance of [color] (sRGB), the building block of the WCAG
* contrast ratio. Pure so the palette's legibility is measured in a unit test
@@ -145,8 +145,11 @@ internal data class ZoomResult(val offset: Offset, val scale: Float)
* not-executed one is dashed and arrowless (nodes hollow with a muted, legible
* label), so the two states differ in shape, fill and border style rather than
* by a faded tint and survive a screenshot, a dim screen and a colour-blind
* reader; a one-line legend names both states. When [runState] is null the full
* definition is shown, unchanged.
* reader; a one-line legend names both states. An executed `success`/`error`
* edge is drawn noticeably heavier with a stronger, same-hue stroke and a larger
* arrowhead, so the two decisive outcomes are the loudest lines in the graph.
* When [runState] is null the full definition is shown, with the same pass/fail
* emphasis (every route counts as executed) and no legend.
*
* A tap that lands inside a node (stage or terminal) calls [onStageTap] with the
* node key; tapping empty space does nothing. Pan/zoom keep working because the
@@ -405,7 +408,7 @@ private fun LegendSwatch(executed: Boolean, colors: GraphColors) {
strokeWidth = EDGE_STROKE,
pathEffect = if (executed) null else INACTIVE_DASH_EFFECT,
)
if (executed) drawArrowHead(listOf(from, to), color)
if (executed) drawArrowHead(listOf(from, to), color, ARROW_HEAD_SIZE)
}
}
@@ -1074,16 +1077,25 @@ private fun DrawScope.drawEdgePaths(
// Executed = solid full-colour stroke plus an arrowhead; not executed =
// dashed muted stroke with no arrowhead. The difference is carried by line
// style and arrowhead presence, never by opacity alone, so it survives a
// screenshot, a dim screen and a colour-blind reader.
// screenshot, a dim screen and a colour-blind reader. An executed
// `success`/`error` edge uses the heavier pass/fail width, a stronger
// (same-hue) stroke and a matched arrowhead, so pass/fail dominates.
if (edgeIsExecuted(edge.edge, runState)) {
val color = outcomeColor(edge.edge.outcome, colors)
drawPath(path, color = color, style = Stroke(width = EDGE_STROKE))
drawArrowHead(points, color)
val color = edgeStrokeColor(edge.edge, runState, colors)
drawPath(
path,
color = color,
style = Stroke(width = edgeStrokeWidth(edge.edge, runState)),
)
drawArrowHead(points, color, edgeArrowHeadSize(edge.edge, runState))
} else {
drawPath(
path,
color = colors.labelText,
style = Stroke(width = EDGE_STROKE, pathEffect = INACTIVE_DASH_EFFECT),
style = Stroke(
width = edgeStrokeWidth(edge.edge, runState),
pathEffect = INACTIVE_DASH_EFFECT,
),
)
}
}
@@ -1128,17 +1140,18 @@ private fun DrawScope.drawEdgeLabels(
}
/**
* Draws an arrowhead at the tip of [points], oriented along the final segment's
* direction (see [arrowDirection]) instead of the from-to chord, so a route that
* turns a corner still gets an arrow pointing the way it actually travels.
* Draws an arrowhead of length [size] at the tip of [points], oriented along the
* final segment's direction (see [arrowDirection]) instead of the from-to chord,
* so a route that turns a corner still gets an arrow pointing the way it
* actually travels. [size] is passed by the caller from the matching named token
* (see [edgeArrowHeadSize]) rather than written here.
*/
private fun DrawScope.drawArrowHead(points: List<Offset>, color: Color) {
private fun DrawScope.drawArrowHead(points: List<Offset>, color: Color, size: Float) {
if (points.size < 2) return
val to = points.last()
val direction = arrowDirection(points)
if (direction.x == 0f && direction.y == 0f) return
val angle = kotlin.math.atan2(direction.y.toDouble(), direction.x.toDouble())
val size = 12f
val left = Offset(
x = to.x - size * kotlin.math.cos(angle - 0.5).toFloat(),
y = to.y - size * kotlin.math.sin(angle - 0.5).toFloat(),
@@ -1263,6 +1276,46 @@ internal fun stageIsExecuted(key: String, runState: RunGraphState?): Boolean =
internal fun edgeIsExecuted(edge: GraphEdge, runState: RunGraphState?): Boolean =
runState == null || GraphRoute(edge.source, edge.outcome, edge.target) in runState.takenRoutes
/**
* True for the two decisive outcomes the graph emphasises: `success` (pass) and
* `error` (fail). These are the protocol's terminal outcomes, the only two whose
* stroke is widened. Pure, so drawing and the tests share one definition.
*/
internal fun isPassFailOutcome(outcome: String): Boolean =
outcome == "success" || outcome == "error"
/** True for an executed pass/fail edge: the edges drawn heaviest. */
internal fun isEmphasizedEdge(edge: GraphEdge, runState: RunGraphState?): Boolean =
isPassFailOutcome(edge.outcome) && edgeIsExecuted(edge, runState)
/**
* The named stroke-width token for [edge]: the heavier pass/fail width for an
* executed `success`/`error`, the base width for any other executed outcome, and
* the finest width for a not-executed edge. Pure, so the widths are asserted in a
* unit test and no call site writes a stroke literal.
*/
internal fun edgeStrokeWidth(edge: GraphEdge, runState: RunGraphState?): Float = when {
!edgeIsExecuted(edge, runState) -> INACTIVE_EDGE_STROKE
isPassFailOutcome(edge.outcome) -> PASSFAIL_EDGE_STROKE
else -> EDGE_STROKE
}
/** The named arrowhead-size token for [edge], scaled to match [edgeStrokeWidth]. */
internal fun edgeArrowHeadSize(edge: GraphEdge, runState: RunGraphState?): Float =
if (isEmphasizedEdge(edge, runState)) PASSFAIL_ARROW_HEAD_SIZE else ARROW_HEAD_SIZE
/**
* The stroke colour for an executed [edge]: its outcome colour, made more
* saturated when pass/fail so it is stronger without changing its hue (see
* [boostSaturation]). A not-executed edge is drawn muted elsewhere.
*/
internal fun edgeStrokeColor(edge: GraphEdge, runState: RunGraphState?, colors: GraphColors): Color =
if (isEmphasizedEdge(edge, runState)) {
boostSaturation(outcomeColor(edge.outcome, colors), PASSFAIL_SATURATION)
} else {
outcomeColor(edge.outcome, colors)
}
/** A screen-reader description so meaning is never conveyed by colour alone. */
private fun graphDescription(graph: Graph, runState: RunGraphState?): String {
if (graph.stages.isEmpty()) return "Empty workflow graph"
@@ -1290,12 +1343,38 @@ private val FIT_PADDING = 16.dp
private val MIN_VISIBLE = 48.dp
/**
* Line-style tokens shared by the graph and its legend. An executed stroke is
* solid; a not-executed stroke is dashed with [INACTIVE_DASH_INTERVALS] on/off
* Line-style tokens shared by the graph and its legend. Widths and the arrowhead
* size are named here so no call site writes a stroke literal. An executed route
* is solid; a not-executed route is dashed with [INACTIVE_DASH_INTERVALS] on/off
* pixels, so the two states differ by shape, not by a faded tint.
*
* The two decisive outcomes (`success`/`error`) use the heavier
* [PASSFAIL_EDGE_STROKE] with the matching [PASSFAIL_ARROW_HEAD_SIZE] and a
* stronger [PASSFAIL_SATURATION] stroke, so pass/fail reads at a glance and from
* a distance, while every other outcome keeps the finer [EDGE_STROKE] and a
* not-executed route the finer still [INACTIVE_EDGE_STROKE].
*/
private const val EDGE_STROKE = 3f
/** Stroke width for an executed `success`/`error` edge; heavier than [EDGE_STROKE]. */
private const val PASSFAIL_EDGE_STROKE = 7f
/** Stroke width for a not-executed edge; finer than either executed width. */
private const val INACTIVE_EDGE_STROKE = 2.5f
/** Arrowhead length for a normal executed edge. */
private const val ARROW_HEAD_SIZE = 12f
/** Arrowhead length for an executed pass/fail edge, scaled with its heavier stroke. */
private const val PASSFAIL_ARROW_HEAD_SIZE = 20f
/**
* How much more saturated an executed pass/fail stroke is than its outcome
* colour: hue and value are preserved (see [boostSaturation]) so the meaning of
* the colour does not change.
*/
private const val PASSFAIL_SATURATION = 1.6f
/** The dash pattern (on/off, px) for every not-executed stroke; pure data. */
internal val INACTIVE_DASH_INTERVALS = floatArrayOf(14f, 10f)
@@ -385,7 +385,7 @@ private fun RunGraphTab(
Text("This server did not include the run graph.", style = text.meta)
} else {
Text(
"Executed stages and routes are solid; not-executed ones are dashed and outlined. Pinch to zoom, drag to pan, tap a stage for details.",
"Executed stages and routes are solid; not-executed ones are dashed and outlined. Executed success and failure routes are drawn thickest. Pinch to zoom, drag to pan, tap a stage for details.",
style = text.meta,
)
WorkflowGraph(
@@ -1,7 +1,10 @@
package net.awan.pipelines.ui.graph
import androidx.compose.ui.graphics.Color
import net.awan.pipelines.data.protocol.GraphEdge
import net.awan.pipelines.data.protocol.GraphRoute
import net.awan.pipelines.data.protocol.Protocol
import net.awan.pipelines.data.protocol.RunGraphState
import org.junit.Assert.assertEquals
import org.junit.Assert.assertFalse
import org.junit.Assert.assertTrue
@@ -98,6 +101,87 @@ class GraphPaletteTest {
assertTrue(contrastRatio(errorRole, darkSurface) >= 4.5)
}
/**
* The emphasis helper keeps the outcome hue and value and only raises
* saturation, so a stronger pass/fail stroke is still recognisably the same
* success/failure colour.
*/
@Test
fun boostSaturationRaisesSaturationButKeepsHueValueAndAlpha() {
val base = successRole
val boosted = boostSaturation(base, 1.6f)
assertTrue(saturationOf(boosted) > saturationOf(base))
assertEquals(hueOf(base), hueOf(boosted), 1f)
assertEquals(valueOf(base), valueOf(boosted), 0.001f)
assertEquals(base.alpha, boosted.alpha, 0.001f)
// A second hue is left on its own hue, not shifted toward the first.
val red = errorRole
assertEquals(hueOf(red), hueOf(boostSaturation(red, 1.6f)), 1f)
}
@Test
fun boostSaturationIsSafeAndClampedAtTheEdges() {
val base = successRole
// A no-op factor, and invalid factors, return the colour unchanged.
assertEquals(base, boostSaturation(base, 1f))
assertEquals(base, boostSaturation(base, 0f))
assertEquals(base, boostSaturation(base, -1f))
assertEquals(base, boostSaturation(base, Float.NaN))
// Achromatic colours have no saturation to raise.
assertEquals(Color.Gray, boostSaturation(Color.Gray, 2f))
// An already fully-saturated colour clamps at 1 instead of overshooting.
assertEquals(Color.Red, boostSaturation(Color.Red, 2f))
}
/**
* Only an executed pass/fail edge is emphasised: its stroke is the stronger
* same-hue colour, while a non-pass/fail edge and a not-executed edge keep
* their exact outcome colour.
*/
@Test
fun onlyExecutedPassFailStrokesAreSaturatedFurther() {
val colors = colors()
val success = GraphEdge(1, "a", "success", Protocol.SUCCESS_END, "success")
val blocked = GraphEdge(2, "a", "blocked", Protocol.FAILURE_END, "blocked")
val error = GraphEdge(3, "b", "error", Protocol.FAILURE_END, "error")
val executed = RunGraphState(
visitedStages = setOf("a"),
takenRoutes = setOf(GraphRoute("a", "success", Protocol.SUCCESS_END)),
currentStage = "a",
)
val baseSuccess = outcomeColor("success", colors)
val strokeSuccess = edgeStrokeColor(success, executed, colors)
assertEquals(hueOf(baseSuccess), hueOf(strokeSuccess), 1f)
assertTrue(saturationOf(strokeSuccess) > saturationOf(baseSuccess))
// A non-pass/fail edge and a not-executed pass/fail edge are untouched.
assertEquals(outcomeColor("blocked", colors), edgeStrokeColor(blocked, executed, colors))
assertEquals(outcomeColor("error", colors), edgeStrokeColor(error, executed, colors))
}
/** Hue in degrees, matching the conversion [boostSaturation] uses. */
private fun hueOf(color: Color): Float {
val max = maxOf(color.red, color.green, color.blue)
val min = minOf(color.red, color.green, color.blue)
val delta = max - min
if (delta == 0f) return 0f
val h = when (max) {
color.red -> ((color.green - color.blue) / delta + 6f) % 6f
color.green -> (color.blue - color.red) / delta + 2f
else -> (color.red - color.green) / delta + 4f
}
return h * 60f
}
private fun saturationOf(color: Color): Float {
val max = maxOf(color.red, color.green, color.blue)
val min = minOf(color.red, color.green, color.blue)
return if (max <= 0f) 0f else (max - min) / max
}
private fun valueOf(color: Color): Float = maxOf(color.red, color.green, color.blue)
@Test
fun nodeKindIsDeterministicAndCoversEveryKind() {
assertEquals(GraphNodeKind.Model, graphNodeKind(false, "planner", null))
@@ -518,6 +518,56 @@ class WorkflowGraphTest {
assertFalse(edgeIsExecuted(notTaken, runState))
}
/**
* The emphasis contract: an executed `success`/`error` edge uses the widest
* named stroke token, every other executed outcome a finer one and a
* not-executed edge the finest, with the arrowhead scaled to match. The
* definition-only view applies the same pass/fail emphasis.
*/
@Test
fun executedPassFailEdgesAreTheWidest() {
val graph = sampleGraph()
val success = graph.edges().first { it.outcome == "success" }
val error = graph.edges().first { it.outcome == "error" }
val other = graph.edges().first { it.outcome == "blocked" }
val untaken = graph.edges().first { it.outcome == "rejected" }
val runState = RunGraphState(
visitedStages = setOf("planner", "implementer", "reviewer"),
takenRoutes = setOf(
GraphRoute(success.source, success.outcome, success.target),
GraphRoute(error.source, error.outcome, error.target),
GraphRoute(other.source, other.outcome, other.target),
),
currentStage = "reviewer",
)
val passFailWidth = edgeStrokeWidth(success, runState)
assertEquals(passFailWidth, edgeStrokeWidth(error, runState), 0.001f)
assertTrue(edgeStrokeWidth(other, runState) < passFailWidth)
assertTrue(edgeStrokeWidth(untaken, runState) < edgeStrokeWidth(other, runState))
assertTrue(edgeStrokeWidth(untaken, runState) > 0f)
// The arrowhead scales with the heavier stroke.
assertEquals(edgeArrowHeadSize(success, runState), edgeArrowHeadSize(error, runState), 0.001f)
assertTrue(edgeArrowHeadSize(success, runState) > edgeArrowHeadSize(other, runState))
// The definition-only view emphasises the same pass/fail edges.
assertEquals(passFailWidth, edgeStrokeWidth(success, null), 0.001f)
assertTrue(isEmphasizedEdge(success, runState))
assertFalse(isEmphasizedEdge(other, runState))
assertFalse(isEmphasizedEdge(untaken, runState))
}
/** Only `success` and `error` are the decisive, emphasised outcomes. */
@Test
fun onlySuccessAndErrorArePassFailOutcomes() {
assertTrue(isPassFailOutcome("success"))
assertTrue(isPassFailOutcome("error"))
for (outcome in listOf("blocked", "rejected", "skipped", "exhausted", "approved", "done", "")) {
assertFalse(outcome, isPassFailOutcome(outcome))
}
}
/**
* The not-executed dash pattern is a real on/off rhythm, not a faded tint: a
* positive, even-length interval list so a dashed stroke reads differently