Files
alan 7eaab4b359 docs(app): record real dark-theme evidence for the stage-node probe
The fixture had no darkTheme, so its Material "dark" captures were the
default light theme. Supply the stock dark theme and themeMode.system, rerun
the probe in both schemes, and correct the note's test counts, capture names
and branch state.
2026-10-21 18:47:56 +01:00

11 KiB
Raw Permalink Blame History

P2-node — native content-sized stage-node control

This visit: both UI-review must-fixes

Finding Change
Material stadium outline cut into a wrapped 2x label Material no longer uses a stock button. It is a stock card body: Card.outlined when unselected, Card.filled when selected, wrapped in an InkWell with a 16 px content inset and the framework's kMinInteractiveDimension tap target. A card's painted shape is a rounded rectangle, so a long wrapped label stays inside the visible boundary at 1x and 2x.
Cupertino unselected stages and terminals were bare tinted text Unselected Cupertino nodes are CupertinoButton.tinted, so every node has a visible native surface; selected stays CupertinoButton.filled.

Both fixes use stock widgets and stock variants only: no shape override, no font, size, padding on a button, palette value or CSS token was added.

File Lines Responsibility
lib/features/graph/widgets/graph_stage_node.dart 126 one content-sized node as a native Material card or Cupertino button
test/features/graph/widgets/graph_stage_node_test.dart 235 key identity, semantics, keyboard, focus retention, wrap and terminal honesty
test/features/graph/widgets/graph_stage_node_render_test.dart 210 painted-boundary and painted-surface checks on real render objects/pixels
tool/graph_node_probe.dart 90 isolated browser fixture with stock light/dark themes, 1x and 2x narrow cases
tool/graph_node_probe.mjs 151 headless-Chrome runner: labels, click identity, aria-current, captures
notes/P2-node.md this page facts for review/landing

No existing app source, domain, layout, routing, shell, main.dart, pubspec, server, web client or platform file was modified.

Public API

GraphStageNode({
  required GraphNode node,
  String? recordedStatus,
  bool selected = false,
  required ValueChanged<String> onSelected,
})

Unchanged from the reviewed candidate. onSelected reports node.key verbatim, including #success / #failure; the display label is never used as identity.

Native mapping

State Material Cupertino
unselected Card.outlined + InkWell CupertinoButton.tinted
selected Card.filled + InkWell CupertinoButton.filled
  • The host is chosen with the existing usesCupertinoHost helper.
  • Material content sits in a Padding of 16 logical px inside the card, so wrapped glyphs stay clear of the rounded corners; the control is still content-sized (no fixed width or height) and grows with its label.
  • MergeSemantics + Semantics(button: true, selected: …, label: …) keep one accessibility node per stage: button role, tap action, exact label/status and selected state. The painted content stays ExcludeSemantics.
  • Selection keeps the same widget type on both hosts (Card / CupertinoButton), so keyboard focus survives activation; the previous Material OutlinedButton → FilledButton swap replaced the focus node (review note 1).
  • Break-anywhere parity. The web node uses overflow-wrap: anywhere; the painted lines get invisible U+200B break opportunities. The accessible label stays exact, with no invisible characters.
  • Recorded status only. recordedStatus is shown verbatim on a second line when non-blank; blank or whitespace-only status adds no line. Nothing is derived from terminal, stageIndex or the label, so a terminal reads only Success / Failure unless the caller supplies real run evidence.

Rendered checks (new)

graph_stage_node_render_test.dart closes the gap the previous 2x test had (line metrics versus paragraph width, not glyphs versus the painted boundary):

  • Painted-boundary containment. Reads the actual Material.shape and render rect of the Material control, builds its outer Path, converts every laid-out line box of the label to card-local coordinates with RenderParagraph.localToGlobal, and requires all four corners of every line box to be inside the painted path — at 1x and 2x in a 150 logical px box. A rounded rectangle is convex, so corner containment means the whole line box is inside; no padding/shape override can hide a crossing.
  • The check has teeth. Running the same test against the identical widget while a StadiumBorder is temporarily set on the card fails with at 1.0x a glyph box corner at Offset(16.1, 19.0) escapes the painted control boundary. The shape assertion (material node paints a rounded surface, not a stadium) fails too. The override was reverted before this page was written.
  • Cupertino container. Renders the unselected node over an opaque page, reads pixels back from a real RepaintBoundary.toImage, and requires the point just inside the control's left edge to differ from the page background by more than 24/255. Reverting to plain CupertinoButton fails this test.
  • Visible selection. The same pixel path requires the painted surface to change between unselected and selected in both hosts.
  • Focus retention. Tab + Enter on the Material node, then the primary focus must still be a descendant of the node's Card.

Checks actually run (landing, after merging main)

dart format --output=none --set-exit-if-changed lib/features/graph/widgets \
  test/features/graph/widgets tool/graph_node_probe.dart   # 0 changed, exit 0
flutter pub get                                            # dependencies resolved
flutter test test/features/graph/widgets                   # 13 passed
flutter test test/features/graph                           # 113 passed
flutter test                                               # 526 passed
flutter analyze                                            # No issues found!
flutter build web -t tool/graph_node_probe.dart --release   # ✓ Built build/web
PROBE_VARIANT=material  PROBE_SCHEME=dark  node tool/graph_node_probe.mjs  # passed, 6 captures
PROBE_VARIANT=material  PROBE_SCHEME=light node tool/graph_node_probe.mjs  # passed, 6 captures
PROBE_VARIANT=cupertino PROBE_SCHEME=dark  node tool/graph_node_probe.mjs  # passed, 6 captures
PROBE_VARIANT=cupertino PROBE_SCHEME=light node tool/graph_node_probe.mjs  # passed, 6 captures
flutter build web --release                                 # ✓ app bundle restored

The whole-suite count is 526 after main brought in the changes viewer and routed-edge tests; the earlier figure of 460 was measured before that merge.

The runner asserts the initial labels (Selected: build, plan, build, running, Success, Failure), that exactly the build node carries aria-current="true" (Flutter web maps Semantics(selected:) to aria-current, not aria-selected — review note 5), that clicking plan and Success yields exactly Selected: plan and Selected: #success, and that the selected aria-current moves to plan.

Browser evidence (landing, current)

Real headless Chrome, loopback fixture only, 390×844 phone and 1280×800 desktop. The Material fixture now supplies a stock dark theme (darkTheme + themeMode.system), so PROBE_SCHEME=dark and =light are genuinely different renders (phone PNG SHA-256 ac6272fd… versus c603c119…); Cupertino follows the platform scheme (3e39555f… versus 1f40f8b5…). The runner writes material-nodes-*.png, light-material-nodes-*.png, cupertino-nodes-*.png and light-cupertino-nodes-*.png, plus -long-1x-crop.png / -long-2x-crop.png; the shared copies below use a land-p2-node- prefix.

  • /Users/alan/.local/share/pipelines/data/artifacts/64/public/land-p2-node-material-dark-phone.png
  • .../land-p2-node-material-light-phone.png
  • .../land-p2-node-material-dark-long-2x-crop.png
  • .../land-p2-node-cupertino-dark-phone.png
  • .../land-p2-node-cupertino-light-phone.png
  • .../land-p2-node-cupertino-dark-long-2x-crop.png
  • Runner: .../public/graph_node_probe.mjs (same file as tool/graph_node_probe.mjs)

The visit-2 p2-node-fix-material-dark-* captures were the default light theme with a "dark" name because the fixture had no dark theme; they are history only, as are the visit-1 material-nodes-*.png / cupertino-nodes-*.png set and the UI-review crops.

Pixel measurements of the current 2x crops (crops are 2x, 8 logical px margin):

Node Container (px) Glyph ink (px) Corner band
Material x 16–316, y 16–560 x 50–269, y 66–507 24 px (radius 12)
Cupertino x 16–316, y 16–640 x 60–268, y 63–590 16 px (radius 8)

At 1x the same nodes measure Material ink x 50–268, y 61–147 inside a x 16–316, y 16–200 container, and Cupertino ink x 59–264, y 59–164. No glyph ink enters a corner band or crosses the visible boundary in either scaling; the previous outline crossing is gone.

Inspected captures: Material shows outlined node bodies and a visibly filled selected node in real light and dark, running only on build, and no status on either terminal; Cupertino shows a tinted body for every unselected node and a filled selected node in both schemes.

Honest limits

  • Material selection is tonal. Card.filled (surfaceContainerHighest) versus Card.outlined (surface + border) is the strongest stock card pairing, but it is lighter than the previous primary-filled button. It is visible in the captures and asserted by pixels; if UI review wants a stronger accent, that needs an explicit theme-colour decision rather than a bespoke palette.
  • Stage vs terminal is label-driven. Both hosts give every node the same stock container; the web's terminal pill and outcome tints are styling the rules exclude. Terminals read Success / Failure (and no invented status). Composition can add a stock type affordance if it is still wanted.
  • Material content inset is a spacing choice. 16 logical px inside the card keeps wrapped glyphs clear of the 12 px corner radius; the framework's kMinInteractiveDimension keeps the tap target at the native minimum.
  • No measurement API yet. The control shrink-wraps; the caller imposes width (the fixture uses 150). The renderer still needs to measure this same control.
  • onSelected identity and wrapping are unchanged, but U+200B break opportunities would split exotic grapheme clusters (acceptable for stage keys).
  • Space activation is a framework default and is not exercised; only Tab + Enter is tested.
  • No composition. No canvas, layout invocation, edge painter, visit menu, shell registration or main.dart wiring: the widget is still not visible in the app.
  • State of the branch. The six paths are committed on flutter/p2-node-widget and main is merged in with no conflicts; the server performs the landing and the post-landing ancestry check.
  • Fixture-only browser evidence: no Pipelines server, real run, authentication change, deployment or production data.
  • Mobile unverified: web test/analyze/build only; no Android/iOS build, emulator, ADB or install.