Files
pipelines/app/notes/R4-session-export.md
T
alan 776afcacea fix(app): offer the session export repair only where the web does
Suppress the export-only repair for a legacy session.html with no recorded
evidence, narrow the identity check to the web's own, and keep the stricter
partial rule for an unverified complete status. Fix the analyzer findings,
add gating/legacy/Cupertino coverage, format, and correct the parity docs.
2026-10-22 10:52:36 +01:00

154 lines
8.2 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.
# R4 — visit Session export state
## Delivered
The Timeline visit pane's **Session** section reports the recorded export state
as native fact rows:
- **Export** — `complete`, `partial`, `missing`, `skipped`, `repair`, or the
server's exact unrecognised status word.
- **Reason** — the server-recorded diagnostic, verbatim, for a present export
that is not a repair; a missing export keeps its diagnostic in the recorded
sentence.
- **Repair / Repair option** — every recorded repair attempt in server order,
labelled `<status> · <n> messages.< diagnostic>`, with `Open repaired export`
where a non-selected attempt has a file. These are plain text: no control and
no request.
- The existing partial-export sentence and the single `Open <file>` action are
unchanged.
Completeness is not inferred: it requires `status == "complete"`, positive
`messages` and `html_bytes`, no truncation and no diagnostic. A complete status
without that evidence is `partial`; a legacy `session.html` with no evidence is
`unknown`, never `complete`. Repairs are shown even when the main export is
complete. This slice sent no request; the export-only `repair_session_export`
control landed later (see `notes/session-export-repair.md`).
## Review fixes (visit 2)
- Removed the analyzer-gate warning at
`lib/features/runs/ui/run_detail_visit_session.dart:77`
(`unnecessary_non_null_assertion`); `flutter analyze` is clean again.
- One completeness rule: `_evidenceComplete` now backs both
`VisitSessionExport.isComplete` and the evidence-selection check, so selection
and display cannot drift.
- One status classifier: `_exportState` backs both the present-export and
missing-file fact rows. `complete` without evidence is partial, known partial
statuses are partial, anything else is unknown with the server's own word.
- Split the 449-line session state file by responsibility: session wording and
state assembly (`run_detail_visit_session_state.dart`, 109 lines), export
model/resolution/classification (`run_detail_visit_export.dart`, 352 lines),
and shared recorded-field reading (`run_detail_visit_recorded.dart`, 31
lines). The state file re-exports the export file, so the pane and existing
tests keep one import.
- Added the three coverage gaps the review named: a non-skipped visit with no
session has no Export row; a selected repair suppresses the Reason row; an
evidence status whose named file is missing keeps the server word and puts
the diagnostic in the recorded sentence.
- Extended the existing real-browser visit probe with a complete-export visit
that carries a failed repair, and a partial-export visit with a diagnostic.
- Updated `PARITY.md` so the row no longer says "Missing UI".
## Theme render fix (visit 3)
The UI review found that `PROBE_SCHEME=dark` never painted dark: the driver sent
`theme=1`, while the fixture compares `params['theme'] == 'dark'`. Every earlier
`-dark-` capture was therefore light. Fixed in
`tool/run_detail_visit_probe.mjs`: the driver now passes the scheme name, and the
probe samples the painted page (mean luminance over the screenshot) before any
capture. A dark run must paint below 0.5 mean luminance and a light run above it,
so this mismatch fails loudly instead of silently labelling light captures dark.
A negative check with the old `theme=1` URL fails with
`PROBE_SCHEME=dark painted the other theme (mean luminance 0.970)`.
All four dark combinations were re-run and all their captures regenerated:
Material/Cupertino × 1280×900/1× and 320×568/2×. Measured mean luminance is
0.084 (Material 1280), 0.140 (Material 320), 0.081 (Cupertino 1280) and 0.116
(Cupertino 320). No test, check or page exception occurred.
## Files
Changed:
- `app/lib/features/runs/ui/run_detail_visit_session.dart` — one-line analyzer
fix; rendering unchanged.
- `app/lib/features/runs/ui/run_detail_visit_session_state.dart` — now session
wording/state assembly plus a re-export of the export module.
- `app/test/features/runs/ui/run_detail_visit_session_export_test.dart` — 11
tests (8 delivered + 3 review gaps).
- `app/tool/run_detail_visit_probe.dart` — two server-shaped export-state visits.
- `app/tool/run_detail_visit_probe.mjs` — export-row checks, narrow-layout
scrolling, two new captures per host/size, corrected scheme query parameter and
a painted-theme luminance gate.
- `app/PARITY.md` — session audit/export row updated to Source with the
remaining action/publication named.
Added:
- `app/lib/features/runs/ui/run_detail_visit_export.dart` — export state enum,
fact/repair/export models, evidence ordering, status classification,
completeness rule.
- `app/lib/features/runs/ui/run_detail_visit_recorded.dart` — recorded text,
count and artifact lookup shared by both modules.
- `app/notes/R4-session-export.md` — this note.
## Checks run
From `app/`, Flutter 3.44.6:
| Command | Result |
| --- | --- |
| `flutter analyze` | **No issues found** (was 1 warning, exit 1) |
| `dart format --output=none --set-exit-if-changed` on the 6 changed Dart files | 0 changed, exit 0 |
| `flutter test test/features/runs/ui` | 142 passed |
| `flutter test test/features/runs` | **205 passed** |
| `flutter test` | **1247 passed** |
| `flutter build web` | `Built build/web`, exit 0 |
| `flutter build web --target tool/run_detail_visit_probe.dart --output build/probe-run-detail-visit` | built, exit 0 |
| `node tool/run_detail_visit_probe.mjs` × 4 host/size combos | 12/12 checks true in each (includes the painted-theme check) |
## Browser evidence
The real `RunDetailView` was driven over the probe's fake `get_run` gateway with
a fourth and fifth recorded visit. The checks assert, for the audit visit,
`Export complete`, `Repair failed · 0 messages. The repair read failed.`,
`Repair option Open repaired export`, `Open session.html`, and no Reason row;
for the partial visit, `Export partial`, `Reason The native read was refused.`
and the sentence `This export is failed; full session evidence is not
available.` The existing pane/session/gallery checks still pass.
Under `/Users/alan/.local/share/pipelines/data/artifacts/110/public/r4-session-export/`:
| Host | Viewport | New captures |
| --- | --- | --- |
| Material | 1280×900, dark, 1x | `run-detail-visit-material-dark-1x-1280x900-{export-complete-repair,export-partial-reason}.png` |
| Material | 320×568, dark, 2x | `run-detail-visit-material-dark-2x-320x568-{export-complete-repair,export-partial-reason}.png` |
| Cupertino | 1280×900, dark, 1x | `run-detail-visit-cupertino-dark-1x-1280x900-{export-complete-repair,export-partial-reason}.png` |
| Cupertino | 320×568, dark, 2x | `run-detail-visit-cupertino-dark-2x-320x568-{export-complete-repair,export-partial-reason}.png` |
Each combo also re-captures the 8 existing states (40 PNGs total). Evidence
JSON: `evidence-{material,cupertino}-{1x-1280x900,2x-320x568}.json`, 12 true
checks each, including the measured page luminance.
The 1280×900 captures show every row on one screen in true dark. At 320×568 with
2x text the pre-existing 240px minimum tab body leaves a short scroll region: the
probe scrolls to reach and verify the rows (no overflow or exception), and the 2x
captures show the header plus the start of the facts rather than the whole
section. The rows are present and reachable, but the 320 capture is not proof of
legibility at rest; the UI review's scrolled captures cover that. This is the same
narrow-layout constraint recorded in `notes/R4-visit.md`, not new to this change.
## Not verified / preserved
- Web only. Android/iOS builds and device rendering were not run; the source
remains portable (Material/Cupertino theme roles and plain text layout only).
- No authenticated server or production run was touched; fixtures only. The
preview is not published to 8096.
- The export-only `repair_session_export` control landed later and is described
in `notes/session-export-repair.md`; full per-visit repair choices remain
unwired, and the repair-option label remains inert text by design.
- Artifact matching still selects by recorded name only, as it did before this
change; web additionally filters repairs by session/backend/directory and
checks `size_bytes == html_bytes`. Inherited, not changed here.
- No commit, push, merge or deployment.