Files
pipelines/app/notes/A1-list.md
T
alan 596365d914 feat(app): add read-only native artifact visit list
Render recorded artifact groups for the active host, with visit-scoped
selection and an explicit selection callback. Material uses ListTile,
Cupertino uses inset grouped sections with separate heading semantics.
Recorded names, MIME and size are shown verbatim with honest fallbacks;
nothing is resolved, fetched, previewed, downloaded or fabricated.

Adds widget, host and semantics regressions plus an isolated browser probe.
2026-10-21 18:46:18 +01:00

8.1 KiB
Raw Blame History

A1-list — read-only artifact visit list with selection

What changed

All files are new; no existing file was edited. Nothing under lib/main.dart, lib/shell/, another feature, pubspec.*, web/, the Go server or android/ was touched. No dependency was added and no network, url, preview, share, download, filter or gallery code was written.

File Lines Responsibility
lib/features/artifacts/ui/artifact_visit_list.dart 231 One public read-only widget, its selection callback, and the visit-scoped identity helper
test/features/artifacts/ui/artifact_visit_list_fixture.dart 85 Shared recorded fixtures and the native host composition used by the tests
test/features/artifacts/ui/artifact_visit_list_test.dart 230 Identity, Material/Cupertino rows, duplicate filename selection, 2x wrapping, honest fallbacks, empty wording
test/features/artifacts/ui/artifact_visit_list_semantics_test.dart 165 Header semantics, heading/row separation, read-only rows, selected state
tool/artifact_list_probe.dart 194 Isolated fixture entry for browser captures; never changes main.dart or the shell

API

typedef ArtifactSelected =
    void Function(ArtifactGroup group, ArtifactRecord artifact);

String artifactVisitIdentity(ArtifactGroup group, ArtifactRecord artifact);

ArtifactVisitList({
  required List<ArtifactGroup> groups,
  String? selectedIdentity,
  ArtifactSelected? onSelected,
})

artifactVisitIdentity combines the recorded stage key, the group's recorded display visit and the record's recorded url (or its name when no url was recorded). A filename alone is never an identity, so result.csv from visit 1 and visit 2 remain distinct even when both records carry the same url. The callback returns the exact ArtifactGroup and ArtifactRecord that was tapped.

Behaviour

  • Each group heading is the web client's vocabulary: stage · visit N, taken from the existing ArtifactGroup (displayVisit already owns the number).
  • Each row shows the recorded filename, the recorded MIME (parameters trimmed) and the recorded size via the existing humanBytes. An empty name renders (unnamed artifact) and an empty content type renders type not recorded; nothing is inferred from the extension, and no url is displayed or resolved.
  • The size value and unit are joined by a non-breaking space, so 120.6 KiB never splits across lines at narrow widths.
  • Material hosts get ListTile rows (title = name, subtitle = facts); Cupertino hosts get CupertinoListSection.insetGrouped with a native CupertinoButton row so the name can wrap (the stock CupertinoListTile title is forced to one line). Name uses the theme text style and facts use the platform secondaryLabel colour, so the recorded name leads the hierarchy. No custom font, palette or fixed row/button dimensions are declared; rows grow with content and text scale.
  • Cupertino rows set hasLeading: false, so the inter-row divider aligns with the text instead of an absent leading column.
  • Both hosts expose every group heading as its own header semantics node, and every Cupertino row as its own node. A heading can neither be read as part of a row nor activate one (see the regression tests).
  • A row without onSelected is read-only: Material has no tap action, and the Cupertino row is a plain padded row rather than a disabled CupertinoButton (which still exposes a button role). It never renders as a button; the semantics regression asserts both no tap action and no button role.
  • Empty input says No stage artifacts recorded., the web client's wording.
  • The only action is onSelected. No capture/visit facts are invented or masked.

Fixes from UI review visit 1

  1. Cupertino heading semantics. CupertinoListSection does not create semantics for its header. The header is now wrapped in Semantics(container: true, header: true, …) and each Cupertino row is its own Semantics(container: true, …) node. Browser check: three <h2 role="heading"> nodes now exist, the review · visit 2 heading rect is [20, 482.5, 118.2, 23] and its row [20, 511.5, 350, 72]; the row label is result.csv / text/csv · 4.0 KiB without the heading. Clicking the heading centre leaves the selection at Selected: none.
  2. Cupertino grouped background seam. The probe composition now sets CupertinoPageScaffold(backgroundColor: CupertinoColors.systemGroupedBackground). At logical x=10 the whole 390×844 viewport is uniformly rgb(242,242,247) in light mode, before and after selection; no white band below the last section. Requirement for the future gallery: the composing page must set the same background, or paint the grouped background behind the list.

Advisories from both earlier reviews were addressed where they touch this slice: dangling selectedIdentity doc link, divider inset, name/metadata hierarchy, value/unit wrapping and read-only rows. Unit coverage now uses a record the server actually sent without a url, so the identity fallback to the recorded name is exercised directly, alongside the unnamed and missing-content-type fallbacks. The 2x wrap regression asserts a multi-line height rather than a single-line threshold.

Real browser evidence

Built with flutter build web -t tool/artifact_list_probe.dart and driven in an isolated headless Chrome (Chrome 155, DevTools protocol, prefers-color-scheme: light, 390×844 at DPR 2) against a loopback static server on an OS-assigned port. No production server, no real run data. The probe fixture contains two same-named result.csv records in different visits.

  • Initial: Selected: none; three heading nodes build · visit 1, review · visit 1, review · visit 2.
  • Heading review · visit 2 clicked: status stays Selected: none; no aria-current row.
  • Row review · visit 2 clicked: Selected: review · visit 2 · result.csv; only that row has aria-current="true".
  • Material host still exposes three <h2> headings and the same four rows.

Shared evidence:

  • /Users/alan/.local/share/pipelines/data/artifacts/65/public/a1-code-cupertino-390-initial.png
  • /Users/alan/.local/share/pipelines/data/artifacts/65/public/a1-code-cupertino-390-visit2.png
  • /Users/alan/.local/share/pipelines/data/artifacts/65/public/a1-code-material-390.png
  • /Users/alan/.local/share/pipelines/data/artifacts/65/public/a1-code-manifest.json

The capture driver is stage-private (04-Code/private/capture_a1_fix.mjs); Chrome and its temporary profile were removed after the run.

Checks actually run

On the branch after merging main (fast-forward, no conflicts):

flutter test test/features/artifacts/ui          # 11 passed
flutter test test/features/artifacts             # 71 passed
flutter test                                     # 524 passed (whole app)
flutter analyze                                  # No issues found! (1.4s)
dart format --set-exit-if-changed                # 5 files, 0 changed
flutter build web -t tool/artifact_list_probe.dart   # ✓ Built build/web (15.9s)

git status --short --untracked-files=all lists only the six new files above; pubspec.yaml/pubspec.lock are unchanged. The branch merges current main with no conflicts and nothing is pushed or deployed.

Honest limits

  • No gallery screen, shell registration, preview, viewer, share or download is part of this slice; the widget is ready for the manager to compose.
  • The list is scrollable and requires bounded height (a ListView); composition into the run detail is a later slice. The gallery must supply the grouped page background noted above.
  • The browser pass covered Cupertino light 390 (initial and visit 2) and a Material heading/row check; large-text Cupertino and dark-mode recaptures were not repeated this visit. The 2x wrapping regression runs in the widget tests. Full rendered acceptance belongs to the UI review stage.
  • Mobile is unverified: only web was built and captured; no Android/iOS build, emulator, ADB or device was used.
  • Handed to landing: committed on flutter/a1-visit-list after merging main; the manager owns integration into main and delivery.