Merge branch 'main' into flutter/p2-node-widget

This commit is contained in:
2026-10-21 18:44:19 +01:00
29 changed files with 5479 additions and 3 deletions
+323
View File
@@ -0,0 +1,323 @@
# D1 — run changes and the file diff viewer
New feature under `lib/features/changes/`; no server, legacy web/Android or
pubspec changes remain after manager acceptance corrections.
## Current manager acceptance (supersedes earlier presentation evidence below)
The pipeline's bundled font and fixed green/red palette were rejected against
the user's native-defaults requirement. Manager removed both and the font assets
without changing raw patch, capture or visit semantics. Typography inherits the
host; colours use native semantic roles and no row tint. The original candidate
and its review evidence remain referenced at15cca17; later font/palette evidence
in this note is historical, NOT evidence for the final native-defaults patch.
Updated regressions failed against the original overrides, then all47 focused
tests passed after correction; analyzer clean. Fresh fixture web build and
changes_probe passed (including absence of custom font), producing18 new captures
under approved temp/native-diff-manager-captures. Manager inspected both native
phone2x rendered views. Preview/shell integration and mobile remain unverified.
## Public API
Import the barrel:
```dart
import 'package:pipelines_app/features/changes/changes.dart';
```
Integration widgets:
- `ChangesViewer({Key? key, required List<JsonMap> steps})`
- The run detail's `steps` exactly as returned by `get_run`. Pass the same
list instance until the server reply changes: captures and the summary are
derived once per list identity, not on every rebuild or filter keystroke.
- It fills the available height, so place it in a bounded parent (Scaffold
body, tab body or `Expanded`). It does not open a socket or request data.
- `FileDiffViewer({Key? key, required FileChange file, VoidCallback? onClose})`
- The reusable viewer for one recorded file. Without `onClose` it pops the
enclosing route.
- `Future<void> showFileDiffViewer(BuildContext context, FileChange file)`
- Opens the platform modal: `showDialog` with a Material `Dialog` on
Android/desktop/web, `showCupertinoDialog` with `CupertinoPopupSurface` on
iOS/macOS.
Data and pure helpers exported for integration/tests:
- `FileChange` — `path`, `kind`, `patch` (server bytes or null), `binary`,
`truncated`, `beforeMode`, `afterMode`, `steps`; `FileChange.fromJson(JsonMap)`,
`FileChange.tryParse(dynamic)`.
- `ChangeCapture` — `status`, `scope`, `files`, `skipped`, `omitted`,
`diagnostic`; `ChangeCapture.fromJson(JsonMap)`.
- `StageCapture` / `StageCapture.fromStep(JsonMap)` / `stageCaptures(steps)` —
one stage visit per step, ordered by numeric sequence, including steps with no
capture. `sequence` is the run-wide step ordinal (ordering and keys); `visit`
is the display visit number within the stage.
- `RunChanges` / `runChanges(steps)` / `runChangesFor(captures)` — final-state
aggregate (last recorded visit wins per path; each path counted once) with the
same fields. `runChangesFor` avoids re-deriving captures a caller already has.
- `parseUnifiedPatch`, `PatchHunk`, `PatchLine`, `ChangeLineKind`, `gutterWidth`,
`gutterText`, `changeStat`, `changeKind`, `changeKindLabel`, `changeKindTitle`.
- Wording: `runChangesHeader`, `runChangesNote`, `changesListSummary`,
`noChangeDetail`, `patchUnavailableReason`, `changeEntryTags`, `changeRowMeta`,
`changeFileMeta`, `fileChangesSummary`, `filterFileChanges`,
`changePositionLabel`, `binaryDiffMessage`, `truncatedPatchNote`,
`noLineChangesMessage`, `missingCaptureDetail`, `unavailableCaptureDetail`,
`malformedCaptureDetail`, `emptyCaptureDetail`, `partialCaptureDetail`.
Example integration:
```dart
final steps = (detail['steps'] as List).cast<JsonMap>();
// ...
ChangesViewer(steps: steps)
```
The manager owns shell/run-detail registration; this item does not edit them.
## Recorded-evidence semantics (matches `web/src/changes.js`)
- `file_changes == null` is **missing evidence**, not “no changes”. A
running/waiting step is “pending”; any other missing capture is counted and
named. The UI says the capture is unavailable and explicitly says that does not
mean the workspace was unchanged.
- `status: "unavailable"` means the snapshots could not be compared. No change
list is fabricated; the server diagnostic is shown. A non-null `file_changes`
value that is not an object is also unreadable evidence, so it is treated as
unavailable with `malformedCaptureDetail`; it never becomes an empty capture.
- A present complete capture with `files: []` is the only “no changes observed”
state (“the captured snapshots were identical”).
- `status: "partial"`, any per-file `truncated`, or any `omitted` count makes the
run partial; `skipped`, `omitted`, truncated-file count and the diagnostic are
shown. `scope` is shown per stage capture.
- Files are grouped by stage/visit. The visit label is the recorded
`control.visit` when it is positive (a resumed run), otherwise the visit's
1-based position among the steps of its own stage, ordered by sequence and
stable for ties. This mirrors the web client's `displayVisit`; the run-wide
step `sequence` is only the ordering/key, never shown as a visit number.
- Kinds are `added`, `modified`, `deleted` and the safe `changed` fallback.
Binary, truncated and mode-only entries carry labels; a mode-only entry has no
text diff and says so.
- The run summary is final-state: a path recorded by several visits is one row,
keeping first-seen order and the last visit's kind/patch/stat/flags/modes, with
the stage names that touched it. Per-stage sections still show each visit's own
capture.
- Filtering matches changed filenames case-insensitively (substring) and keeps
missing/unavailable evidence sections visible. The counter names **paths**,
matching the summary's unit; the sections below still list one row per visit.
- A changed-file row's semantics label names the action, path, kind and visible
meta (`+N -M`, binary/truncated/mode), so the excluded icon and subtitle are
still announced.
## Diff rendering
- Only patch content is custom-drawn: `@@` hunk headers, old/new gutter numbers,
the shared `+`/`-`/space language, context and `\ No newline` markers.
- The recorded `---`/`+++` file headers stay in the Raw view, matching the web
rendered view; rendered content is the stat line and the hunks. Long lines
scroll horizontally; vertical content scrolls inside the dialog. The Raw view
keeps each recorded line on one line and scrolls sideways, like the web's
`white-space: pre` pane, so a wrapped continuation can never be mistaken for a
new patch line.
- Patch/path text inherits the native host typography without a font-family,
size or weight override. Manager removed the candidate's bundled code font:
a previous visual review requested it, but that contradicts the user's
explicit native-defaults requirement, which also applies to diffs. The web
default may be proportional; no monospace guarantee is claimed. Raw patch
bytes are unchanged. No bundled font or pubspec change remains.
- Rendered/Raw is a native Material `SegmentedButton` or Cupertino
`CupertinoSlidingSegmentedControl`. Copy patch and Close are native Material
buttons/icon button or Cupertino buttons with exact labels.
- Copy patch writes the recorded `patch` string byte-for-byte (trailing newline
and truncated final line included). Copy is disabled when no readable patch
exists.
- Binary uses the honest binary message; truncated-with-patch shows the note plus
the retained text; truncated-without-patch and mode-only show the recorded
reason, never an invented empty diff.
- Add/remove markers and stats use native semantic colours (Material primary/
error; Cupertino systemGreen/destructiveRed), with no bespoke palette or added
tint. +/- and recorded gutter numbers distinguish changes without colour.
Rows share the hunk width, at least the dialog width.
- A Cupertino list row lets its recorded path wrap instead of inheriting the
tile's single ellipsized line, and the Cupertino dialog surface is inset from
the window edge (16 on phones, 40 on wide windows) so its native rounded
corners are visible.
## Files
```
lib/features/changes/changes.dart
lib/features/changes/domain/change_capture.dart
lib/features/changes/domain/change_kind.dart
lib/features/changes/domain/change_wording.dart
lib/features/changes/domain/file_change.dart
lib/features/changes/domain/patch_models.dart
lib/features/changes/domain/run_changes.dart
lib/features/changes/domain/unified_patch.dart
lib/features/changes/widgets/change_style.dart
lib/features/changes/widgets/changes_viewer.dart
lib/features/changes/widgets/capture_section.dart
lib/features/changes/widgets/file_diff_viewer.dart
lib/features/changes/widgets/patch_view.dart
assets/fonts/RobotoMono.ttf
assets/fonts/OFL.txt
pubspec.yaml (fonts + assets declaration)
test/features/changes/fixtures.dart
test/features/changes/widget_hosts.dart
test/features/changes/unified_patch_test.dart
test/features/changes/run_changes_test.dart
test/features/changes/changes_viewer_test.dart
test/features/changes/diff_presentation_test.dart
tool/changes_probe_entry.dart
tool/changes_probe.mjs
```
Every path above is new except `pubspec.yaml`, which gains only the
`RobotoMono` family and the font licence asset declaration.
## Checks
Presentation revision (bundled code face, diff colours/tints, Cupertino rows and
dialog inset) re-ran the full set:
- `/Users/alan/development/flutter/bin/flutter test` — **76 tests passed**.
- `/Users/alan/development/flutter/bin/flutter test test/features/changes` —
**47 tests passed**.
- `/Users/alan/development/flutter/bin/flutter analyze` — **No issues found**.
- `/Users/alan/development/flutter/bin/dart format --output=none
--set-exit-if-changed lib/features/changes test/features/changes
tool/changes_probe_entry.dart` — 20 files, 0 changed.
- `/Users/alan/development/flutter/bin/flutter build web` — **built
`build/web`** successfully.
- `node --check tool/changes_probe.mjs` — passed.
- `/Users/alan/development/flutter/bin/flutter build web --target
tool/changes_probe_entry.dart --output build/probe-web-fix` — built.
- `node tool/changes_probe.mjs --root build/probe-web-fix --out <public>/d1` —
passed every check (11 checks, below).
`flutter pub get` resolved the existing lock; `pubspec.lock` is unchanged.
## Real browser evidence
Fixture entry `tool/changes_probe_entry.dart`, driven by `tool/changes_probe.mjs`
(loopback, OS-assigned port, headless Chrome, Flutter semantics enabled). The
fixture uses server-shaped captures for partial, complete, missing, unavailable
and empty states, plus binary, truncated, mode-only, deleted, added and
multi-hunk patches. `/?visits=1` is a compact second fixture that repeats stages
and records one explicit `control.visit`. It is rendering data only; no server or
operator run touched.
Captures (in the run's public artifacts `d1/`):
- `d1-changes-phone-list.png` (390×844, dark)
- `d1-changes-phone-diff.png`
- `d1-changes-phone-raw.png`
- `d1-changes-phone-copied.png`
- `d1-changes-phone-filtered.png`
- `d1-changes-phone-visits.png` (390×844, repeated-stage visit labels)
- `d1-changes-phone-light-list.png`, `d1-changes-phone-light-diff.png`,
`d1-changes-phone-light-diff-2x.png`, `d1-changes-phone-light-raw.png`
(light theme, 2x where glyphs and tints are inspected)
- `d1-changes-desktop-diff.png` (1280×800)
- `d1-changes-desktop-list.png`
- `d1-changes-desktop-light-list.png`, `d1-changes-desktop-light-diff.png`
- `d1-changes-cupertino-diff.png` (1280×800, Cupertino fixture)
- `d1-changes-cupertino-light-list.png` (390×844, wrapped paths),
`d1-changes-cupertino-light-diff.png`, `d1-changes-cupertino-light-diff-2x.png`
(390×844, inset popup)
Observed checks from `d1-probe.json`:
- Root `/` served `text/html; charset=utf-8`.
- `assets/FontManifest.json` lists a `RobotoMono` family and
`assets/fonts/RobotoMono.ttf` is served as `font/ttf` (183,700 bytes), so the
web build carries a real code face.
- The body showed `Changes probe` and `Capture unavailable`, and a file row whose
semantics label starts with
`Open diff for lib/features/changes/domain/unified_patch.dart` (the label now
also announces kind and meta).
- Opening the diff changed `document.body.innerText`; `Rendered`, `Raw patch`,
`Copy patch` and `Close diff` labels appeared.
- `Raw patch` changed the body and produced a different PNG from the rendered
capture; the raw semantics value contains the recorded `---`/`+++` header.
- Clipboard readback after `Copy patch` started with
`--- "a/lib/features/changes/domain/unified_patch.dart"` (540 bytes).
- Filtering `unified` left both matching visit rows (`unifiedRows: 2`) and hid
`assets/pipelines-mark.png` (`binaryRows: 0`); the counter read
`1 of 6 changed paths match`.
- The visits fixture rendered `implementer` with `Visit 1` and `Visit 2`, and
`reviewer` with `Visit 1` and the recorded `control.visit` `Visit 6`; the probe
fails if either list differs.
- `Close diff` returned to the list; the desktop and Cupertino viewers opened.
Measured from `d1-changes-phone-light-diff-2x.png` (Pillow): the light add tint is
`#E3F3E7` and the remove tint `#FBE7E5` (ΔR 24); every changed line paints a
618 px (309 logical px) band — the full dialog content width — and the two added
lines and one removed line are each 92/46 device px tall. Previously the tints
were `#FFD8E4`/`#F9DEDC` (Δ 6,6,8) and only as wide as each line's text. Dark
captures measure `#394643` (green) and `#4D3C42` (red) tints.
The screenshots show real Material and Cupertino controls, light and dark themes,
phone and desktop widths, wrapped Cupertino paths and an inset Cupertino popup.
Mobile targets were not built, installed or run.
## Review revision
- **B1 (blocking, visit labels):** `StageCapture.visit` is derived from positive
`control.visit` else the stage position; sections render it instead of the
run-wide `sequence`. Unit/widget tests cover repeated stages, a resumed visit
and sequence ties; the browser visits fixture and capture above show the result.
- **A1 (malformed capture):** a non-object `file_changes` is now unavailable with
`malformedCaptureDetail`, never an empty “no changes” capture.
- **A2 (rendered headers):** rendered view shows hunks only, matching the web
rendered view; the exact headers remain in Raw and Copy.
- **A3 (re-derivation):** `ChangesViewer` derives captures/aggregate on init and
when the steps list changes, not on filter keystrokes; `runChangesFor` reuses
those captures, and `FileChange.withSteps` reuses the parsed patch.
- **A4 (test fixtures):** the run-changes test helpers now delegate to
`test/features/changes/fixtures.dart`.
- **A5 (row semantics):** the row label includes kind and visible meta.
- **A6 (filter counter):** counts and names changed **paths**, matching the
summary; the list remains per visit.
- **A7 (paging):** unchanged; the one-file viewer API is the documented limit.
## Presentation revision (UI review)
- **M1 (monospace):** `pubspec.yaml` declares the bundled `RobotoMono` family
(`assets/fonts/RobotoMono.ttf`, SIL OFL 1.1, licence in `assets/fonts/OFL.txt`)
and `monospaceText` uses it on every platform. The browser build's
`FontManifest.json` and font response are checked by the probe, and the 2x
captures show even advances and aligned gutters.
- **M2 (add/remove colours and tints):** the diff no longer uses Material
`tertiaryContainer`/`errorContainer`. `diffLineColors` supplies theme-aware
green/red pairs (light `#116B33` on `#E3F3E7`, `#B3261E` on `#FBE7E5`; dark
`#7FE0A8`/`#FF9E9E` on a 16% wash), the `+N`/`-M` stat is split into those two
hues, and every line tint spans the full hunk width (at least the dialog width)
via `IntrinsicWidth` inside a width-bounded scroll view.
- **M3 (Cupertino):** list rows clear `CupertinoListTile`'s inherited single-line
cap so the recorded path wraps, and the Cupertino dialog is inset (16 on
phones, 40 on wide windows) so its rounded corners are visible.
- **Nonblocking raw wrap:** the Raw view now keeps one recorded line per line and
scrolls horizontally (`SelectionArea` over a `Text` with `softWrap: false`),
matching the web's `pre` pane.
- **Left as-is (nonblocking):** list-row stat strings stay neutral (Android/web
colour them), the unavailable diagnostic still appears in both the section meta
and the note (web parity), and the one-file viewer has no paging.
## Deliberate limits
- One file per `FileDiffViewer`; the browser viewer's previous/next gallery
paging is not implemented here. The task asked for a reusable one-file viewer.
- The shell/run-detail screen is not wired; that remains the manager's
integration step (feature lanes do not edit shell/main).
- Run status gating (`showRunChangesSummary`, succeeded-only in the browser) is
the caller's choice; `ChangesViewer` renders whatever steps it is given.
- The bundled font is Latin/Greek/Cyrillic: a patch containing CJK or symbol
glyphs outside that coverage falls back for those glyphs, so their advance may
not be monospaced. Copy and Raw bytes are unaffected.
- Android and iOS were not built, installed or run in this revision; the
Cupertino path is verified only through the fixture's browser rendering and
widget tests, so **mobile remains unverified**.
- No backend capability is missing for this item: `file_changes` already carries
status, scope, files, skipped, omitted, diagnostic, binary/truncated flags,
modes and patches.
+119
View File
@@ -0,0 +1,119 @@
# P2-edge — passive edge layer over landed routing
## What changed
App-only, new files. No existing routing, layout, domain, shell, `main.dart`,
pubspec, server, web client or platform source was edited. The Land stage
committed the candidate on `flutter/p2-edge-layer` and merged `main`.
| File | Lines | Responsibility |
| --- | --- | --- |
| `lib/features/graph/painting/graph_edge_layer.dart` | 160 | `GraphEdgeLayer` widget + `GraphEdgePainter` path/arrow painting |
| `test/features/graph/painting/edge_layer_fixtures.dart` | 41 | hand-built routes and arrival helper for the tests |
| `test/features/graph/painting/graph_edge_geometry_test.dart` | 240 | path and arrow geometry, routed forward/self-loop/cycle edges, a hand-built backward route and an off-port tip case |
| `test/features/graph/painting/graph_edge_layer_test.dart` | 190 | draw calls, clip, hit-test transparency, style colors, repaint rules, widget size |
| `tool/graph_edge_probe.dart` | 182 | isolated browser-capture entry (not wired into the app) |
## Public API
```dart
GraphEdgeLayer(
routes: List<EdgeRoute>, // from routing/route_models.dart
canvasSize: Size, // graph-space canvas supplied by the caller
color: Color, // caller's native outline color
strokeWidth: double, // caller's native stroke width
)
```
`GraphEdgePainter` is public so a compositor and its tests share the exact
geometry through `linePath(route)` and `arrowPath(route)`.
## Behavior
- **Passive and hit-test transparent:** a single `CustomPaint`; no child,
gesture, focus, semantics or label text. `GraphEdgePainter.hitTest` returns
`false` for every point, so the layer never becomes a full-canvas hit sink and
siblings below it keep their taps, including with `routes: const []` and on a
painted stroke. Default `CustomPainter.hitTest` returns `null`, which
`RenderCustomPaint.hitTestSelf` treats as a hit; the explicit `false` is the
fix and the regression covers it. Node boxes and measured extents are
caller-owned and are never read or changed here.
- **Same coordinates:** every `RoutePoint` is used verbatim. A route with fewer
than two points draws nothing. Painting clips to the `CustomPaint` size.
- **Orthogonal paths:** consecutive points are joined with straight segments,
so the landed orthogonal routes keep every bend; no smoothing or re-routing.
- **Direction arrows:** one filled triangle per route, tip exactly at
`targetPort.point`. The router guarantees `points.last == targetPort.point`;
`paint` asserts that invariant, while `arrowPath` reads the tip from the port
so a caller-supplied mismatch cannot move the arrow off the port. Direction is
the route's last non-degenerate segment, so forward, backward, same-rank and
self-loop edges keep their real arrival direction; a degenerate tail falls
back to the target port's inward normal.
- **Theme-owned style:** the caller supplies color and stroke width; the arrow
length is 6x and its half base 2x that stroke width, so it scales with the
caller's native thickness. No absolute palette, font or dimension is
hard-coded.
- **Repaint:** `shouldRepaint` compares color, stroke width and routes by value
(`listEquals` over `EdgeRoute ==`), so equal rebuilt lists do not repaint while
a moved route, color or stroke change does.
## Checks actually run
```
dart format lib/features/graph/painting test/features/graph/painting tool/graph_edge_probe.dart
flutter test test/features/graph/painting # 18 passed
flutter test test/features/graph/painting test/features/graph/routing # 38 passed
flutter test # 466 passed
flutter analyze # No issues found!
flutter build web -t tool/graph_edge_probe.dart -o build/graph_edge_probe
flutter build web # ✓ Built build/web
```
The hit-test regression was confirmed to fail (`taps` stayed `0`) when
`hitTest` returned `true`, and pass with the shipped `false`.
`public/P2-edge.patch` is the reviewed new-file diff. `public/P2-edge-land.patch`
is the landed `git diff main..HEAD`, which also carries the landing caption
correction and the 160-line trim; it reverse-applies cleanly to the merged tree.
## Rendered evidence
Three real Chrome captures of the isolated probe build, served from a temporary
loopback server on an OS-assigned port with a throwaway profile. No Pipelines
server, authentication, production data, device or preview service was touched.
| File | Bytes | Shows |
| --- | --- | --- |
| `public/graph-edge-layer-web.png` | 90,739 | light theme: three measured cards, Success/Failure terminals, same-rank cycle edges, forward terminal edges and a self-loop |
| `public/graph-edge-layer-web-dark.png` | 85,431 | the same graph in the native dark theme |
| `public/graph-edge-layer-web-same-rank.png` | 69,601 | `?case=same-rank`: a two-node cycle, both edges same-rank between distinct nodes |
All are 2700x2700 (900x900 CSS at 3x). Arrow tips land on target ports; the
layer uses `colorScheme.outline` and `dividerTheme.thickness`.
The caption wording was corrected at landing to name the actual routes
(same-rank cycle edges, forward terminal edges and a self-loop). Fresh captures
of the rebuilt probe are `public/land-edge-light.png`,
`public/land-edge-dark.png` and `public/land-edge-same-rank.png`. The earlier
`public/graph-edge-layer-*.png` and `public/ui-review-edge-*.png` captures
predate that text-only correction; their geometry is unchanged and remains valid
evidence for the rendered layout.
## Honest limits
- **No labels or nodes.** Edge labels are deliberately excluded for later
native widget composition (the router already returns measured
`EdgeLabelBox`es); this slice paints no text. The probe's cards are fixture-only,
not a node widget and not shell registration.
- **One style per layer.** `color`/`strokeWidth` are single values; the web run
graph's per-outcome colors and dashed/dotted not-executed/fallback styles are
not expressible yet. A run-graph compositor will need a per-route style input
or several layers.
- **No interaction.** Selection, focus, hover and semantics belong to callers.
If per-wire hover is added later it needs stroke-only hit testing, not a
canvas-wide sink.
- **Browser capture only on web.** The probe ran in Chrome; mobile was not
built, installed or verified.
- **Committed, not delivered.** The candidate is committed locally on
`flutter/p2-edge-layer` with `main` merged. Nothing was pushed, deployed or
installed.