feat(app): turn documents in the artifact gallery

This commit is contained in:
2026-10-22 03:24:40 +01:00
parent 4f684ba467
commit 3fa4657be7
18 changed files with 1365 additions and 168 deletions
+110
View File
@@ -0,0 +1,110 @@
# A4 — turn documents in the artifact gallery
## Scope
The run-detail Artifacts page now lists a visit's turn documents beside its
stage files: `input.md`, `memory.md`, `output.md` and `session.html`. They are
entries of the visit group, not a separate run-level list.
## Behaviour
- A recorded document is a normal gallery row with the server's exact recorded
name, MIME and byte size. Selecting it uses the same `ArtifactSelectionFacts`
and URL-state rules as a stage file.
- Markdown documents (`input.md`, `memory.md`, `output.md`) open in the existing
in-app artifact viewer and join its recorded paging order.
- `session.html` is external-only by name. It always takes the selection dialog
with the existing Open/Copy actions, even when the server sniffed it as
`text/plain`; it is never fetched or drawn in the renderer.
- A document the visit did not record keeps its row with the exact audit words:
`No input recorded.`, `No memory recorded for this visit.`,
`No output recorded.`, and the web session wording (for example
`This visit has no harness session.` or
`Session ses-42 is recorded. Its export is not yet available.`). The missing
row is not tappable.
- Nothing is synthesized: a document exists only when its exact recorded name is
in the step's artifact list. Step fields named `input`/`memory`/`output` are
ignored. An absent artifact capture yields no document slots, and a visit that
recorded none of the four documents shows no document section rather than four
fabricated absences.
- The run header count now counts stage files plus recorded documents; absent
slots are never counted. Stage-only grouping (`artifactGroups`) is unchanged.
## Files
| File | Lines | Responsibility |
| --- | ---: | --- |
| `lib/features/artifacts/domain/artifact_document.dart` | 153 | Document slots, exact absence wording, exact-name lookup, external-only/viewer eligibility |
| `lib/features/artifacts/domain/artifact_groups.dart` | 160 | `galleryGroups` merging stage groups with per-visit documents; recorded count |
| `lib/features/artifacts/domain/gallery_navigation.dart` | 91 | Viewer paging includes recorded markdown documents, excludes session exports |
| `lib/features/artifacts/domain/artifact_record.dart` | 85 | Turn-file vocabulary and recorded record model |
| `lib/features/artifacts/domain/artifact_summary.dart` | 81 | Header counts recorded gallery entries |
| `lib/features/artifacts/ui/artifact_row_labels.dart` | 32 | Shared group/name/facts labels and identity |
| `lib/features/artifacts/ui/artifact_record_row.dart` | 82 | Native Material/Cupertino recorded row |
| `lib/features/artifacts/ui/artifact_document_section.dart` | 124 | Per-visit document rows and exact absence rows |
| `lib/features/artifacts/ui/artifact_visit_list.dart` | 128 | Group list composing stage rows and document sections |
| `lib/features/artifacts/ui/artifact_gallery_page.dart` | 277 | Uses gallery groups; session export bypasses the viewer |
| `lib/features/artifacts/ui/artifact_selection_facts.dart` | 71 | Same facts panel with the recorded-entry count |
| `lib/features/artifacts/ui/artifact_viewer_body.dart` | 248 | Material pager wraps instead of clipping |
| `test/features/artifacts/domain/artifact_document_test.dart` | 281 | Exact records, all absence words, no synthesis, grouping, paging |
| `test/features/artifacts/ui/artifact_gallery_documents_test.dart` | 183 | Both hosts: entries, grouping, missing wording, row semantics, viewer, external-only session |
| `tool/artifact_gallery_probe.dart` | 385 | New isolated `documents` fixture state |
| `tool/artifact_gallery_probe.mjs` | 936 | Real-browser A4 checks, contrast, pager geometry and captures |
## Fixes after the review stages
- **Material absence rows use normal text contrast.** The absent-document row is
no longer a disabled `ListTile`. It keeps no `onTap` (still non-actionable) but
paints the explanation with the theme's `onSurfaceVariant`, like every other
secondary label. Measured from 3x rasterised pixels: **8.88:1** in light mode
and **10.91:1** in dark mode (previous: 2.67:1 and 3.64:1).
- **Material viewer pager no longer clips at 320 px/2x.** The fixed `Row` became a
`Wrap`, so at 320 px with 2× text `Previous artifact` (x=8, w=236.4) and
`Next artifact` (x=8, w=186.1) each take their own line and stay inside the
viewport (previous: Next ended at 430.6 px). This also fixes the pre-existing
stage-artifact pager case.
- Quality follow-ups from the code review: the changed files are `dart format`
clean; `turnDocumentNames` is aliased to `systemArtifactNames`; `visitDocuments`
parses the capture once; the external-only session is detected by its domain
name (`sessionExportDocumentName`) instead of object identity; the stale
`artifact_summary`/`artifact_record` comments now match the gallery surface.
- Tests now pin every `sessionDocumentAbsence` branch (skipped, canceled,
interrupted, running, failed with/without diagnostic, runtime error, pending
recovery, complete-inventory, evidence diagnostic), the absent row's
non-actionable but enabled Material tile and secondary colour, and the 320 px/2×
Material pager geometry.
## Checks
- `flutter analyze`: clean (`No issues found!`).
- `dart format --output=none --set-exit-if-changed` on every changed/new Dart
file: clean.
- `flutter test test/features/artifacts`: 148 pass.
- `flutter test` (integrated): 1049 pass.
- `flutter build web`: succeeds.
- Probe build: `flutter build web --target tool/artifact_gallery_probe.dart --output build/probe-a4-fix`.
- Real headless Chrome probe: 36 checks, 41 captures, 0 failures. A4 captures:
`a4-material-documents`, `a4-material-session`, `a4-material-document-viewer`,
the same three for Cupertino, `a4-material-light-absence-row`,
`a4-material-dark-absence-row` and `a4-material-320-2x-document-viewer`.
Inspected the light/dark absence pages (legible, no disabled dimming), the
320/2× document viewer (both pager controls whole, wrapped) and the Cupertino
document list (unchanged native grouped rows).
- Evidence: `public/a4-code-fix/evidence.json` plus the captures above.
The probe serves only its own loopback fixture. No server, operator run or
authenticated production data was touched.
## Known limits
- Not committed: this stage is read-only for history, so the candidate is left
in the worktree for the landing stage.
- Repaired session exports (`session-repair-*.html`) are still not resolved; the
web client prefers the verified repair, and `PARITY.md` still lists this as
deferred. A repaired visit can show `session.html` or the
"not available in the artifact inventory" wording instead of the repair.
- The dialog still offers Download/Share for an external-only session export;
external-only here means it cannot be rendered in-app, not that its bytes are
unavailable.
- Mobile (Android/iOS) rendering and OS behavior remain unverified; only web was
tested.