17 KiB
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:
import 'package:pipelines_app/features/changes/changes.dart';
Integration widgets:
ChangesViewer({Key? key, required List<JsonMap> steps})- The run detail's
stepsexactly as returned byget_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.
- The run detail's
FileDiffViewer({Key? key, required FileChange file, VoidCallback? onClose})- The reusable viewer for one recorded file. Without
onCloseit pops the enclosing route.
- The reusable viewer for one recorded file. Without
Future<void> showFileDiffViewer(BuildContext context, FileChange file)- Opens the platform modal:
showDialogwith a MaterialDialogon Android/desktop/web,showCupertinoDialogwithCupertinoPopupSurfaceon iOS/macOS.
- Opens the platform modal:
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.sequenceis the run-wide step ordinal (ordering and keys);visitis 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.runChangesForavoids 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:
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 == nullis 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-nullfile_changesvalue that is not an object is also unreadable evidence, so it is treated as unavailable withmalformedCaptureDetail; 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-filetruncated, or anyomittedcount makes the run partial;skipped,omitted, truncated-file count and the diagnostic are shown.scopeis shown per stage capture.- Files are grouped by stage/visit. The visit label is the recorded
control.visitwhen 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'sdisplayVisit; the run-wide stepsequenceis only the ordering/key, never shown as a visit number. - Kinds are
added,modified,deletedand the safechangedfallback. 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 newlinemarkers. - 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'swhite-space: prepane, 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
SegmentedButtonor CupertinoCupertinoSlidingSegmentedControl. Copy patch and Close are native Material buttons/icon button or Cupertino buttons with exact labels. - Copy patch writes the recorded
patchstring 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— builtbuild/websuccessfully.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.pngd1-changes-phone-raw.pngd1-changes-phone-copied.pngd1-changes-phone-filtered.pngd1-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.pngd1-changes-desktop-light-list.png,d1-changes-desktop-light-diff.pngd1-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
/servedtext/html; charset=utf-8. assets/FontManifest.jsonlists aRobotoMonofamily andassets/fonts/RobotoMono.ttfis served asfont/ttf(183,700 bytes), so the web build carries a real code face.- The body showed
Changes probeandCapture unavailable, and a file row whose semantics label starts withOpen 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 patchandClose difflabels appeared. Raw patchchanged the body and produced a different PNG from the rendered capture; the raw semantics value contains the recorded---/+++header.- Clipboard readback after
Copy patchstarted with--- "a/lib/features/changes/domain/unified_patch.dart"(540 bytes). - Filtering
unifiedleft both matching visit rows (unifiedRows: 2) and hidassets/pipelines-mark.png(binaryRows: 0); the counter read1 of 6 changed paths match. - The visits fixture rendered
implementerwithVisit 1andVisit 2, andreviewerwithVisit 1and the recordedcontrol.visitVisit 6; the probe fails if either list differs. Close diffreturned 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.visitis derived from positivecontrol.visitelse the stage position; sections render it instead of the run-widesequence. 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_changesis now unavailable withmalformedCaptureDetail, 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):
ChangesViewerderives captures/aggregate on init and when the steps list changes, not on filter keystrokes;runChangesForreuses those captures, andFileChange.withStepsreuses 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.yamldeclares the bundledRobotoMonofamily (assets/fonts/RobotoMono.ttf, SIL OFL 1.1, licence inassets/fonts/OFL.txt) andmonospaceTextuses it on every platform. The browser build'sFontManifest.jsonand 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.diffLineColorssupplies theme-aware green/red pairs (light#116B33on#E3F3E7,#B3261Eon#FBE7E5; dark#7FE0A8/#FF9E9Eon a 16% wash), the+N/-Mstat is split into those two hues, and every line tint spans the full hunk width (at least the dialog width) viaIntrinsicWidthinside 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 (
SelectionAreaover aTextwithsoftWrap: false), matching the web'sprepane. - 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;ChangesViewerrenders 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_changesalready carries status, scope, files, skipped, omitted, diagnostic, binary/truncated flags, modes and patches.