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.
This commit is contained in:
2026-10-21 18:46:18 +01:00
parent 7b327f012b
commit 596365d914
6 changed files with 1062 additions and 0 deletions
+150
View File
@@ -0,0 +1,150 @@
# 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
```dart
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.