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

151 lines
8.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.