111 lines
6.8 KiB
Markdown
111 lines
6.8 KiB
Markdown
# 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.
|