From 3fa4657be7c88c9b2d2c76d751386ea4bf5b1aa1 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Thu, 22 Oct 2026 03:24:40 +0100 Subject: [PATCH] feat(app): turn documents in the artifact gallery --- .../artifacts/domain/artifact_document.dart | 153 ++++++++++ .../artifacts/domain/artifact_groups.dart | 53 +++- .../artifacts/domain/artifact_record.dart | 4 +- .../artifacts/domain/artifact_summary.dart | 19 +- .../artifacts/domain/gallery_navigation.dart | 26 +- .../ui/artifact_document_section.dart | 124 ++++++++ .../artifacts/ui/artifact_gallery_page.dart | 17 +- .../artifacts/ui/artifact_record_row.dart | 82 +++++ .../artifacts/ui/artifact_row_labels.dart | 32 ++ .../ui/artifact_selection_facts.dart | 2 +- .../artifacts/ui/artifact_viewer_body.dart | 9 +- .../artifacts/ui/artifact_visit_list.dart | 178 +++-------- app/notes/A4-docs.md | 110 +++++++ .../domain/artifact_document_test.dart | 281 ++++++++++++++++++ .../ui/artifact_gallery_documents_test.dart | 183 ++++++++++++ .../ui/artifact_viewer_page_test.dart | 38 +++ app/tool/artifact_gallery_probe.dart | 58 ++++ app/tool/artifact_gallery_probe.mjs | 164 +++++++++- 18 files changed, 1365 insertions(+), 168 deletions(-) create mode 100644 app/lib/features/artifacts/domain/artifact_document.dart create mode 100644 app/lib/features/artifacts/ui/artifact_document_section.dart create mode 100644 app/lib/features/artifacts/ui/artifact_record_row.dart create mode 100644 app/lib/features/artifacts/ui/artifact_row_labels.dart create mode 100644 app/notes/A4-docs.md create mode 100644 app/test/features/artifacts/domain/artifact_document_test.dart create mode 100644 app/test/features/artifacts/ui/artifact_gallery_documents_test.dart diff --git a/app/lib/features/artifacts/domain/artifact_document.dart b/app/lib/features/artifacts/domain/artifact_document.dart new file mode 100644 index 00000000..66e7c958 --- /dev/null +++ b/app/lib/features/artifacts/domain/artifact_document.dart @@ -0,0 +1,153 @@ +import '../../../core/api_gateway.dart'; +import 'artifact_capture.dart'; +import 'artifact_kind.dart'; +import 'artifact_record.dart'; +import 'artifact_selection.dart'; + +/// The exact server-recorded name of a visit's session export. It is the one +/// turn document that only ever opens externally. +const String sessionExportDocumentName = 'session.html'; + +/// The turn-protocol documents a visit records, in the order the audit surface +/// presents them. These are the same files the stage-artifact filter treats as +/// turn-owned ([systemArtifactNames]), aliased so a rename cannot make the +/// gallery and the filter disagree. +const List turnDocumentNames = systemArtifactNames; + +/// The exact absence wording for a missing turn document. Session absence is +/// contextual and comes from [sessionDocumentAbsence]. +const String noInputDocument = 'No input recorded.'; +const String noOutputDocument = 'No output recorded.'; +const String noMemoryDocument = 'No memory recorded for this visit.'; + +/// One presented turn document of a visit. +/// +/// [record] is the server's exact recorded artifact, or null when the visit did +/// not record that document. A null record is never completed from a step field +/// or another document: the entry carries [absence] instead, so the gallery can +/// show why the document is missing. +class ArtifactDocument { + const ArtifactDocument({ + required this.name, + required this.record, + required this.absence, + }); + + final String name; + final ArtifactRecord? record; + + /// The exact wording shown when [record] is null; empty when recorded. + final String absence; + + /// The session export is read-only evidence: it only ever opens externally. + bool get externalOnly => name == sessionExportDocumentName; + + /// Whether selecting this document opens the existing in-app renderer. A + /// session export is excluded even if the server sniffed it as text. + bool get opensInViewer { + final recorded = record; + if (recorded == null || externalOnly) return false; + return isViewerArtifact(recorded.contentType, recorded.name); + } +} + +String? _text(dynamic value) { + if (value == null) return null; + final text = '$value'; + return text.isEmpty ? null : text; +} + +/// The web client's contextual session wording, used only when no exact +/// `session.html` artifact was recorded. A recorded session id and a missing +/// export are different facts and are never collapsed into "not recorded". +String sessionDocumentAbsence(JsonMap step) { + final export = step['session_export']; + final evidence = export is Map ? Map.from(export) : null; + final evidenceSessionId = _text(evidence?['session_id']); + final sessionId = _text(step['session_id']) ?? evidenceSessionId ?? ''; + if (sessionId.isNotEmpty) { + final recoveryValue = step['session_export_recovery']; + final recovery = recoveryValue is Map + ? Map.from(recoveryValue) + : null; + final recoveryStatus = _text(recovery?['status']); + final evidenceStatus = _text(evidence?['status']); + final status = recoveryStatus == 'pending' || recoveryStatus == 'running' + ? 'pending recovery' + : evidenceStatus == 'complete' + ? 'not available in the artifact inventory' + : evidenceStatus ?? 'not yet available'; + final diagnostic = _text(evidence?['diagnostic']); + return 'Session $sessionId is recorded. Its export is $status.' + '${diagnostic == null ? '' : ' $diagnostic'}'; + } + final model = _text(step['model']) != null || _text(step['provider']) != null; + final status = _text(step['status']); + final outcome = _text(step['outcome']); + if (status == 'skipped' || outcome == 'skipped') { + return 'This visit was skipped; no harness session was started.'; + } + if (status == 'canceled' || status == 'interrupted') { + return 'The stage stopped before a harness session was recorded.'; + } + if (model) { + if (status == 'running') return 'The stage session is being created.'; + if (status == 'failed') { + final diagnostic = _text(step['diagnostic']); + return diagnostic == null + ? 'The stage did not create a harness session.' + : 'The stage did not create a harness session. $diagnostic'; + } + return 'Runtime error: this model stage has no recorded session identity.'; + } + return 'This visit has no harness session.'; +} + +String _absenceFor(String name, JsonMap step) => switch (name) { + 'input.md' => noInputDocument, + 'output.md' => noOutputDocument, + 'memory.md' => noMemoryDocument, + _ => sessionDocumentAbsence(step), +}; + +/// Every turn document slot of one visit, recorded or absent. +/// +/// A capture whose `artifacts` field is absent yields no slots at all: a missing +/// capture is not evidence that the visit recorded no document. A visit that +/// recorded none of the four turn documents yields no slots either, so a stage +/// outside the turn protocol is never presented as four missing documents. Only +/// exact recorded names are presented; nothing is synthesized from other step +/// fields. +List visitDocuments(JsonMap step) { + final capture = ArtifactCapture.fromStep(step); + if (!capture.isAvailable) return const []; + final recorded = presentedArtifacts(capture.artifacts); + ArtifactRecord? firstNamed(String name) { + for (final artifact in recorded) { + if (artifact.name == name) return artifact; + } + return null; + } + + final records = {}; + for (final name in turnDocumentNames) { + final record = firstNamed(name); + if (record != null) records[name] = record; + } + if (records.isEmpty) return const []; + + final documents = []; + for (final name in turnDocumentNames) { + final record = records[name]; + documents.add( + record == null + ? ArtifactDocument( + name: name, + record: null, + absence: _absenceFor(name, step), + ) + : ArtifactDocument(name: name, record: record, absence: ''), + ); + } + return List.unmodifiable(documents); +} diff --git a/app/lib/features/artifacts/domain/artifact_groups.dart b/app/lib/features/artifacts/domain/artifact_groups.dart index f9d861f3..49ff4f9d 100644 --- a/app/lib/features/artifacts/domain/artifact_groups.dart +++ b/app/lib/features/artifacts/domain/artifact_groups.dart @@ -1,14 +1,17 @@ import '../../../core/api_gateway.dart'; import '../../graph/domain/stage_visits.dart'; +import 'artifact_document.dart'; import 'artifact_record.dart'; import 'artifact_selection.dart'; -/// One gallery group: the stage-produced artifacts of a recorded stage visit. +/// One gallery group: the stage-produced artifacts of a recorded stage visit +/// plus that visit's turn documents, recorded or explicitly absent. class ArtifactGroup { const ArtifactGroup({ required this.stageKey, required this.visit, required this.artifacts, + this.documents = const [], }); final String stageKey; @@ -18,6 +21,15 @@ class ArtifactGroup { final int visit; final List artifacts; + + /// The visit's turn-document slots. Empty when the capture was unavailable, + /// so an unknown capture is never presented as four missing documents. + final List documents; + + /// The count the gallery header reports: stage artifacts plus the turn + /// documents the server actually recorded, never an absent slot. + int get recordedCount => + artifacts.length + documents.where((doc) => doc.record != null).length; } int _sequenceOf(JsonMap step) { @@ -86,6 +98,45 @@ List artifactGroups(List steps) { return List.unmodifiable(groups); } +String _galleryKey(String stageKey, int visit) => '$stageKey\u0000$visit'; + +/// The gallery's per-visit groups: stage artifacts and turn documents in one +/// section per recorded visit. +/// +/// Stage-only grouping is unchanged ([artifactGroups]); this function adds the +/// turn-document slots a visit recorded and keeps a visit whose only recorded +/// files are turn documents. A visit with neither stage artifacts nor a +/// recorded document, or whose capture is unavailable, produces no group. +List galleryGroups(List steps) { + if (steps.isEmpty) return const []; + final stageGroups = { + for (final group in artifactGroups(steps)) + _galleryKey(group.stageKey, group.visit): group, + }; + final groups = []; + for (final entry in visitsByStage(steps).entries) { + for (var index = 0; index < entry.value.length; index += 1) { + final step = entry.value[index]; + final visit = displayVisit(step, index); + final base = stageGroups[_galleryKey(entry.key, visit)]; + final documents = visitDocuments(step); + final recordedDocuments = documents.where((doc) => doc.record != null); + if ((base?.artifacts.isEmpty ?? true) && recordedDocuments.isEmpty) { + continue; + } + groups.add( + ArtifactGroup( + stageKey: entry.key, + visit: visit, + artifacts: base?.artifacts ?? const [], + documents: documents, + ), + ); + } + } + return List.unmodifiable(groups); +} + /// One visit's stage artifacts, excluding shared public files that an earlier /// visit already recorded. A repeated non-public name in a later visit stays /// because it is a different recorded artifact, not the same shared file. diff --git a/app/lib/features/artifacts/domain/artifact_record.dart b/app/lib/features/artifacts/domain/artifact_record.dart index 6c6bc845..3faef2df 100644 --- a/app/lib/features/artifacts/domain/artifact_record.dart +++ b/app/lib/features/artifacts/domain/artifact_record.dart @@ -6,8 +6,8 @@ import '../../../core/api_gateway.dart'; const String legacySessionMarkdownArtifact = 'session.md'; /// The files the turn protocol itself writes for every visit. They are audit -/// evidence, not stage output, so the artifact gallery lists stage files first -/// and keeps these for an audit/debug surface. +/// evidence, not stage output: the artifact gallery presents them as the visit's +/// turn documents, and the stage-file list still excludes them. const List systemArtifactNames = [ 'input.md', 'memory.md', diff --git a/app/lib/features/artifacts/domain/artifact_summary.dart b/app/lib/features/artifacts/domain/artifact_summary.dart index 44161a86..58534cc2 100644 --- a/app/lib/features/artifacts/domain/artifact_summary.dart +++ b/app/lib/features/artifacts/domain/artifact_summary.dart @@ -16,14 +16,15 @@ String artifactsEmptyMessage(bool executing) => executing /// The run summary's Artifacts section header. /// -/// The recorded count is exactly the number of tiles [artifactGroups] yields; -/// the title takes its singular form for one. A run whose capture is unavailable -/// says so instead of claiming that nothing was recorded. Partial capture is -/// flagged when any visit excluded or omitted files. +/// The recorded count is the number of recorded entries [galleryGroups] yields: +/// stage files plus the turn documents the server actually recorded, never an +/// absent slot. The title takes its singular form for one. A run whose capture is +/// unavailable says so instead of claiming that nothing was recorded. Partial +/// capture is flagged when any visit excluded or omitted files. String artifactsHeader(List steps, {required bool executing}) { - final recorded = artifactGroups( + final recorded = galleryGroups( steps, - ).fold(0, (sum, group) => sum + group.artifacts.length); + ).fold(0, (sum, group) => sum + group.recordedCount); if (recorded == 0) { if (executing) return artifactsEmptyMessage(true); final unavailable = steps.any( @@ -44,8 +45,10 @@ String artifactsHeader(List steps, {required bool executing}) { /// /// A running visit says capture pending. A finished visit whose capture field was /// absent says capture unavailable rather than "not recorded"; only an explicitly -/// empty capture says "not recorded for this visit". Recorded counts exclude the -/// turn-owned files and the retired session markdown, so the words match tiles. +/// empty capture says "not recorded for this visit". Without [count] the recorded +/// number excludes the turn-owned files and the retired session markdown, so the +/// stage-artifact words match the stage tiles; a caller that presents the turn +/// documents too passes its own recorded entry count. String artifactsSummary(JsonMap step, {int? count}) { final capture = ArtifactCapture.fromStep(step); final recorded = count ?? stageArtifacts(step).length; diff --git a/app/lib/features/artifacts/domain/gallery_navigation.dart b/app/lib/features/artifacts/domain/gallery_navigation.dart index a5d519a9..856f31ee 100644 --- a/app/lib/features/artifacts/domain/gallery_navigation.dart +++ b/app/lib/features/artifacts/domain/gallery_navigation.dart @@ -36,21 +36,27 @@ String artifactVisitIdentityOf(ArtifactGroup group, ArtifactRecord artifact) { } /// The artifacts the viewer can page through, in gallery order: group by group, -/// each group's images, videos and markdown/text documents in recorded order. -/// Other artifacts open externally and are not part of this list. Pure: it only -/// filters and orders records the gallery already holds. +/// each group's images, videos and markdown/text documents in recorded order, +/// then the visit's recorded turn documents that open in the renderer. A session +/// export is external-only and never enters the page list. Pure: it only filters +/// and orders records the gallery already holds. List pagedArtifacts(List groups) { final pages = []; + void add(ArtifactGroup group, ArtifactRecord artifact) { + pages.add( + PagedArtifact(group: group, artifact: artifact, pageIndex: pages.length), + ); + } + for (final group in groups) { for (final artifact in group.artifacts) { if (!isViewerArtifact(artifact.contentType, artifact.name)) continue; - pages.add( - PagedArtifact( - group: group, - artifact: artifact, - pageIndex: pages.length, - ), - ); + add(group, artifact); + } + for (final document in group.documents) { + final artifact = document.record; + if (artifact == null || !document.opensInViewer) continue; + add(group, artifact); } } return List.unmodifiable(pages); diff --git a/app/lib/features/artifacts/ui/artifact_document_section.dart b/app/lib/features/artifacts/ui/artifact_document_section.dart new file mode 100644 index 00000000..003af5e9 --- /dev/null +++ b/app/lib/features/artifacts/ui/artifact_document_section.dart @@ -0,0 +1,124 @@ +import 'package:flutter/cupertino.dart'; +import 'package:flutter/material.dart'; + +import '../../../ui/adaptive/host.dart'; +import '../domain/artifact_document.dart'; +import '../domain/artifact_groups.dart'; +import 'artifact_record_row.dart'; +import 'artifact_row_labels.dart'; + +/// One visit's turn documents, shown below its stage artifacts. +/// +/// A recorded document is a normal gallery row with its recorded name, MIME and +/// size. A document the visit did not record is a non-actionable row carrying +/// the exact absence wording. The section never synthesizes a missing document +/// from another field and never offers an action for it. +class ArtifactDocumentSection extends StatelessWidget { + const ArtifactDocumentSection({ + super.key, + required this.group, + this.selectedIdentity, + this.onSelected, + }); + + final ArtifactGroup group; + final String? selectedIdentity; + final ArtifactSelected? onSelected; + + @override + Widget build(BuildContext context) { + final rows = [ + for (final document in group.documents) _row(document), + ]; + if (usesCupertinoHost(context)) { + return CupertinoListSection.insetGrouped( + header: Semantics( + container: true, + header: true, + child: const Text('Turn documents'), + ), + hasLeading: false, + children: rows, + ); + } + return Column( + crossAxisAlignment: CrossAxisAlignment.stretch, + children: [ + Padding( + padding: const EdgeInsetsDirectional.fromSTEB(16, 12, 16, 4), + child: Semantics( + container: true, + header: true, + child: const Text('Turn documents'), + ), + ), + ...rows, + ], + ); + } + + Widget _row(ArtifactDocument document) { + final record = document.record; + if (record == null) return _AbsentDocumentRow(document: document); + final key = ValueKey( + '${artifactVisitIdentity(group, record)}\u0000document', + ); + return ArtifactRecordRow( + key: key, + group: group, + artifact: record, + selected: selectedIdentity == artifactVisitIdentity(group, record), + onSelected: onSelected, + ); + } +} + +/// A document the visit did not record: the recorded name and its exact absence +/// wording, with no tap target. +class _AbsentDocumentRow extends StatelessWidget { + const _AbsentDocumentRow({required this.document}); + + final ArtifactDocument document; + + @override + Widget build(BuildContext context) { + if (!usesCupertinoHost(context)) { + // The absence line is informational product content, so it keeps the + // theme's normal secondary label colour. A disabled tile would paint both + // lines at the disabled colour (about 2.7:1 in light mode); no `onTap` + // keeps the row non-actionable without dimming it. + return ListTile( + title: Text(document.name), + subtitle: Text( + document.absence, + style: TextStyle( + color: Theme.of(context).colorScheme.onSurfaceVariant, + ), + ), + ); + } + final textTheme = CupertinoTheme.of(context).textTheme; + final absenceStyle = textTheme.textStyle.copyWith( + color: CupertinoColors.secondaryLabel.resolveFrom(context), + ); + return Semantics( + container: true, + child: SizedBox( + width: double.infinity, + child: Padding( + padding: kCupertinoButtonPadding[CupertinoButtonSize.large]!, + child: DefaultTextStyle.merge( + style: textTheme.textStyle, + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text(document.name), + Text(document.absence, style: absenceStyle), + ], + ), + ), + ), + ), + ); + } +} diff --git a/app/lib/features/artifacts/ui/artifact_gallery_page.dart b/app/lib/features/artifacts/ui/artifact_gallery_page.dart index e97c8b41..b2a2087e 100644 --- a/app/lib/features/artifacts/ui/artifact_gallery_page.dart +++ b/app/lib/features/artifacts/ui/artifact_gallery_page.dart @@ -7,6 +7,7 @@ import '../../../ui/adaptive/host.dart'; import '../../chat/ui/transcript/chat_markdown_view.dart'; import '../actions/artifact_file_actions.dart'; import '../actions/artifact_file_bridge.dart'; +import '../domain/artifact_document.dart'; import '../domain/artifact_groups.dart'; import '../domain/artifact_kind.dart'; import '../domain/artifact_record.dart'; @@ -76,9 +77,17 @@ class _ArtifactGalleryPageState extends State { String? _status; List _groupsOf(int? focusIndex) { - if (focusIndex == null) return artifactGroups(widget.steps); + if (focusIndex == null) return galleryGroups(widget.steps); final group = visitArtifactGroup(widget.steps, focusIndex); - return group == null ? const [] : [group]; + if (group == null) return const []; + // The visit pane sees the same document-enriched group the gallery shows for + // that visit, not only its recorded files. + for (final enriched in galleryGroups(widget.steps)) { + if (enriched.stageKey == group.stageKey && enriched.visit == group.visit) { + return [enriched]; + } + } + return [group]; } Future _select(ArtifactGroup group, ArtifactRecord artifact) async { @@ -86,11 +95,13 @@ class _ArtifactGalleryPageState extends State { final resolved = artifact.hasUrl ? resolveArtifactUrl(widget.configuredEndpoint, artifact.url) : null; + final externalOnly = artifact.name == sessionExportDocumentName; setState(() { _selectedIdentity = identity; _status = null; }); - if (resolved != null && + if (!externalOnly && + resolved != null && isViewerArtifact(artifact.contentType, artifact.name)) { await _openViewer(identity); return; diff --git a/app/lib/features/artifacts/ui/artifact_record_row.dart b/app/lib/features/artifacts/ui/artifact_record_row.dart new file mode 100644 index 00000000..2abd427c --- /dev/null +++ b/app/lib/features/artifacts/ui/artifact_record_row.dart @@ -0,0 +1,82 @@ +import 'package:flutter/cupertino.dart'; +import 'package:flutter/material.dart'; + +import '../../../ui/adaptive/host.dart'; +import '../domain/artifact_groups.dart'; +import '../domain/artifact_record.dart'; +import 'artifact_row_labels.dart'; + +/// One recorded artifact row in a gallery section. +/// +/// Material draws a standard [ListTile]; Cupertino draws the same content in a +/// grouped-row button. The row only reports the selection; it never resolves a +/// url, opens a preview, downloads, shares or filters. +class ArtifactRecordRow extends StatelessWidget { + const ArtifactRecordRow({ + super.key, + required this.group, + required this.artifact, + required this.selected, + required this.onSelected, + }); + + final ArtifactGroup group; + final ArtifactRecord artifact; + final bool selected; + final ArtifactSelected? onSelected; + + @override + Widget build(BuildContext context) { + if (!usesCupertinoHost(context)) { + return ListTile( + selected: selected, + title: Text(artifactDisplayName(artifact)), + subtitle: Text(artifactFactsLabel(artifact)), + trailing: selected ? const Icon(Icons.check) : null, + onTap: onSelected == null ? null : () => onSelected!(group, artifact), + ); + } + final textTheme = CupertinoTheme.of(context).textTheme; + final factsStyle = textTheme.textStyle.copyWith( + color: CupertinoColors.secondaryLabel.resolveFrom(context), + ); + final content = DefaultTextStyle.merge( + style: textTheme.textStyle, + child: Row( + children: [ + Expanded( + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text(artifactDisplayName(artifact)), + Text(artifactFactsLabel(artifact), style: factsStyle), + ], + ), + ), + if (selected) const Icon(CupertinoIcons.check_mark), + ], + ), + ); + // `container` makes this row its own semantics node, so the section + // heading stays a separate header node and never covers the row. + return Semantics( + container: true, + selected: selected, + child: SizedBox( + width: double.infinity, + // A read-only row is not a button: a disabled CupertinoButton would + // still expose a button role to assistive technology. + child: onSelected == null + ? Padding( + padding: kCupertinoButtonPadding[CupertinoButtonSize.large]!, + child: content, + ) + : CupertinoButton( + alignment: AlignmentDirectional.centerStart, + onPressed: () => onSelected!(group, artifact), + child: content, + ), + ), + ); + } +} diff --git a/app/lib/features/artifacts/ui/artifact_row_labels.dart b/app/lib/features/artifacts/ui/artifact_row_labels.dart new file mode 100644 index 00000000..89442343 --- /dev/null +++ b/app/lib/features/artifacts/ui/artifact_row_labels.dart @@ -0,0 +1,32 @@ +import '../domain/artifact_groups.dart'; +import '../domain/artifact_kind.dart'; +import '../domain/artifact_record.dart'; +import '../domain/gallery_navigation.dart'; + +/// A selection callback carrying the recorded group and the exact record the +/// operator chose, so the visit is never lost when two groups share a name. +typedef ArtifactSelected = + void Function(ArtifactGroup group, ArtifactRecord artifact); + +/// The identity of [artifact] inside [group], shared by rows and the viewer. +String artifactVisitIdentity(ArtifactGroup group, ArtifactRecord artifact) => + artifactVisitIdentityOf(group, artifact); + +/// The recorded group heading, matching the web client's group vocabulary. +String artifactGroupLabel(ArtifactGroup group) => + '${group.stageKey} · visit ${group.visit}'; + +/// The displayed artifact name: a missing server name stays explicit. +String artifactDisplayName(ArtifactRecord artifact) => + artifact.name.isEmpty ? '(unnamed artifact)' : artifact.name; + +/// The recorded MIME and byte size, never inferred from the name. +/// +/// The value and its unit are joined by a non-breaking space so a narrow row +/// never wraps `120.6` away from `KiB`. +String artifactFactsLabel(ArtifactRecord artifact) { + final type = artifact.contentType.split(';').first.trim(); + final mime = type.isEmpty ? 'type not recorded' : type; + final size = humanBytes(artifact.sizeBytes).replaceFirst(' ', '\u00a0'); + return '$mime · $size'; +} diff --git a/app/lib/features/artifacts/ui/artifact_selection_facts.dart b/app/lib/features/artifacts/ui/artifact_selection_facts.dart index 083a322e..391820c5 100644 --- a/app/lib/features/artifacts/ui/artifact_selection_facts.dart +++ b/app/lib/features/artifacts/ui/artifact_selection_facts.dart @@ -54,7 +54,7 @@ class ArtifactSelectionFacts extends StatelessWidget { Text(artifactGroupLabel(group)), if (recordedStep != null) ...[ const SizedBox(height: 8), - Text(artifactsSummary(recordedStep, count: group.artifacts.length)), + Text(artifactsSummary(recordedStep, count: group.recordedCount)), for (final note in artifactCaptureNotes(recordedStep)) Padding(padding: const EdgeInsets.only(top: 4), child: Text(note)), ], diff --git a/app/lib/features/artifacts/ui/artifact_viewer_body.dart b/app/lib/features/artifacts/ui/artifact_viewer_body.dart index f5ffdbfe..4014bb09 100644 --- a/app/lib/features/artifacts/ui/artifact_viewer_body.dart +++ b/app/lib/features/artifacts/ui/artifact_viewer_body.dart @@ -222,8 +222,13 @@ class _Pager extends StatelessWidget { top: false, child: Padding( padding: const EdgeInsetsDirectional.fromSTEB(8, 0, 8, 4), - child: Row( - mainAxisAlignment: MainAxisAlignment.spaceBetween, + // A `Row` clips the second labelled button once 2x text is wider than + // the viewport; a `Wrap` keeps both controls whole and lets them take + // separate lines, like the Cupertino pager. + child: Wrap( + alignment: WrapAlignment.spaceBetween, + spacing: 8, + runSpacing: 4, children: [ TextButton.icon( onPressed: hasPrevious ? onPrevious : null, diff --git a/app/lib/features/artifacts/ui/artifact_visit_list.dart b/app/lib/features/artifacts/ui/artifact_visit_list.dart index a134d250..38250b2f 100644 --- a/app/lib/features/artifacts/ui/artifact_visit_list.dart +++ b/app/lib/features/artifacts/ui/artifact_visit_list.dart @@ -3,50 +3,28 @@ import 'package:flutter/material.dart'; import '../../../ui/adaptive/host.dart'; import '../domain/artifact_groups.dart'; -import '../domain/artifact_kind.dart'; import '../domain/artifact_record.dart'; -import '../domain/gallery_navigation.dart'; +import 'artifact_document_section.dart'; +import 'artifact_record_row.dart'; +import 'artifact_row_labels.dart'; -/// A selection callback carrying the recorded group and the exact record the -/// operator chose, so the visit is never lost when two groups share a name. -typedef ArtifactSelected = - void Function(ArtifactGroup group, ArtifactRecord artifact); - -/// The identity of [artifact] inside [group], for -/// [ArtifactVisitList.selectedIdentity]. -/// -/// The recorded stage visit is part of the key, so two visits that both -/// recorded `result.csv` stay distinct even when their urls are identical. -/// A filename alone is never an identity. -String artifactVisitIdentity(ArtifactGroup group, ArtifactRecord artifact) => - artifactVisitIdentityOf(group, artifact); - -/// The recorded group heading, matching the web client's group vocabulary. -String artifactGroupLabel(ArtifactGroup group) => - '${group.stageKey} · visit ${group.visit}'; - -/// The displayed artifact name: a missing server name stays explicit. -String artifactDisplayName(ArtifactRecord artifact) => - artifact.name.isEmpty ? '(unnamed artifact)' : artifact.name; - -/// The recorded MIME and byte size, never inferred from the name. -/// -/// The value and its unit are joined by a non-breaking space so a narrow row -/// never wraps `120.6` away from `KiB`. -String artifactFactsLabel(ArtifactRecord artifact) { - final type = artifact.contentType.split(';').first.trim(); - final mime = type.isEmpty ? 'type not recorded' : type; - final size = humanBytes(artifact.sizeBytes).replaceFirst(' ', '\u00a0'); - return '$mime · $size'; -} +export 'artifact_row_labels.dart' + show + ArtifactSelected, + artifactDisplayName, + artifactFactsLabel, + artifactGroupLabel, + artifactVisitIdentity; /// A read-only, selectable list of recorded artifact groups. /// -/// Each group shows its recorded stage and visit, and each row its recorded -/// filename, content type and size. Rendering uses the host's own controls: -/// Material list tiles under [MaterialApp] and grouped Cupertino list sections -/// under [CupertinoApp]. It never resolves a url, opens a preview, downloads, -/// shares or filters; the only action is [onSelected]. +/// Each group shows its recorded stage and visit, its stage-produced artifacts, +/// then its turn documents. Every recorded row shows its recorded filename, +/// content type and size; a turn document the visit did not record stays a +/// non-actionable row with the exact absence wording. Rendering uses the host's +/// own controls: Material list tiles under [MaterialApp] and grouped Cupertino +/// list sections under [CupertinoApp]. It never resolves a url, opens a preview, +/// downloads, shares or filters. class ArtifactVisitList extends StatelessWidget { const ArtifactVisitList({ super.key, @@ -70,7 +48,7 @@ class ArtifactVisitList extends StatelessWidget { if (usesCupertinoHost(context)) { return ListView( children: [ - for (final group in groups) + for (final group in groups) ...[ CupertinoListSection.insetGrouped( // `container` keeps the heading a separate semantics node. Without // it the heading merges into the neighbouring row button, so it is @@ -83,15 +61,16 @@ class ArtifactVisitList extends StatelessWidget { hasLeading: false, children: [ for (var index = 0; index < group.artifacts.length; index += 1) - _CupertinoRow( - key: _rowKey(group, group.artifacts[index], index), - group: group, - artifact: group.artifacts[index], - selected: _isSelected(group, group.artifacts[index]), - onSelected: onSelected, - ), + _row(group, group.artifacts[index], index), ], ), + if (group.documents.isNotEmpty) + ArtifactDocumentSection( + group: group, + selectedIdentity: selectedIdentity, + onSelected: onSelected, + ), + ], ], ); } @@ -107,11 +86,11 @@ class ArtifactVisitList extends StatelessWidget { ), ), for (var index = 0; index < group.artifacts.length; index += 1) - _MaterialRow( - key: _rowKey(group, group.artifacts[index], index), + _row(group, group.artifacts[index], index), + if (group.documents.isNotEmpty) + ArtifactDocumentSection( group: group, - artifact: group.artifacts[index], - selected: _isSelected(group, group.artifacts[index]), + selectedIdentity: selectedIdentity, onSelected: onSelected, ), ], @@ -119,96 +98,15 @@ class ArtifactVisitList extends StatelessWidget { ); } - bool _isSelected(ArtifactGroup group, ArtifactRecord artifact) => - selectedIdentity == artifactVisitIdentity(group, artifact); - - static Key _rowKey(ArtifactGroup group, ArtifactRecord artifact, int index) => - ValueKey('${artifactVisitIdentity(group, artifact)}\u0000$index'); -} - -class _MaterialRow extends StatelessWidget { - const _MaterialRow({ - super.key, - required this.group, - required this.artifact, - required this.selected, - required this.onSelected, - }); - - final ArtifactGroup group; - final ArtifactRecord artifact; - final bool selected; - final ArtifactSelected? onSelected; - - @override - Widget build(BuildContext context) { - return ListTile( - selected: selected, - title: Text(artifactDisplayName(artifact)), - subtitle: Text(artifactFactsLabel(artifact)), - trailing: selected ? const Icon(Icons.check) : null, - onTap: onSelected == null ? null : () => onSelected!(group, artifact), - ); - } -} - -class _CupertinoRow extends StatelessWidget { - const _CupertinoRow({ - super.key, - required this.group, - required this.artifact, - required this.selected, - required this.onSelected, - }); - - final ArtifactGroup group; - final ArtifactRecord artifact; - final bool selected; - final ArtifactSelected? onSelected; - - @override - Widget build(BuildContext context) { - final textTheme = CupertinoTheme.of(context).textTheme; - final factsStyle = textTheme.textStyle.copyWith( - color: CupertinoColors.secondaryLabel.resolveFrom(context), - ); - final content = DefaultTextStyle.merge( - style: textTheme.textStyle, - child: Row( - children: [ - Expanded( - child: Column( - crossAxisAlignment: CrossAxisAlignment.start, - children: [ - Text(artifactDisplayName(artifact)), - Text(artifactFactsLabel(artifact), style: factsStyle), - ], - ), - ), - if (selected) const Icon(CupertinoIcons.check_mark), - ], - ), - ); - // `container` makes this row its own semantics node, so the section - // heading stays a separate header node and never covers the row. - return Semantics( - container: true, - selected: selected, - child: SizedBox( - width: double.infinity, - // A read-only row is not a button: a disabled CupertinoButton would - // still expose a button role to assistive technology. - child: onSelected == null - ? Padding( - padding: kCupertinoButtonPadding[CupertinoButtonSize.large]!, - child: content, - ) - : CupertinoButton( - alignment: AlignmentDirectional.centerStart, - onPressed: () => onSelected!(group, artifact), - child: content, - ), + Widget _row(ArtifactGroup group, ArtifactRecord artifact, int index) { + return ArtifactRecordRow( + key: ValueKey( + '${artifactVisitIdentity(group, artifact)}\u0000$index', ), + group: group, + artifact: artifact, + selected: selectedIdentity == artifactVisitIdentity(group, artifact), + onSelected: onSelected, ); } } diff --git a/app/notes/A4-docs.md b/app/notes/A4-docs.md new file mode 100644 index 00000000..c189ffe4 --- /dev/null +++ b/app/notes/A4-docs.md @@ -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. diff --git a/app/test/features/artifacts/domain/artifact_document_test.dart b/app/test/features/artifacts/domain/artifact_document_test.dart new file mode 100644 index 00000000..f0e1761a --- /dev/null +++ b/app/test/features/artifacts/domain/artifact_document_test.dart @@ -0,0 +1,281 @@ +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/features/artifacts/domain/artifact_document.dart'; +import 'package:pipelines_app/features/artifacts/domain/artifact_groups.dart'; +import 'package:pipelines_app/features/artifacts/domain/artifact_record.dart'; +import 'package:pipelines_app/features/artifacts/domain/artifact_summary.dart'; +import 'package:pipelines_app/features/artifacts/domain/gallery_navigation.dart'; + +import 'artifact_fixtures.dart'; + +Map _doc( + String name, { + String contentType = 'text/markdown', + int sizeBytes = 12, +}) => artifact(name, contentType: contentType, sizeBytes: sizeBytes); + +ArtifactGroup _docGroup(List recorded) { + final recordedStep = step( + stage: 'review', + visit: 1, + artifacts: [for (final name in recorded) _doc(name)], + ); + return ArtifactGroup( + stageKey: 'review', + visit: 1, + artifacts: const [], + documents: visitDocuments(recordedStep), + ); +} + +void main() { + group('visit documents', () { + test('a recorded document carries its exact recorded record', () { + final docs = visitDocuments( + step( + stage: 'review', + visit: 1, + artifacts: [ + _doc('input.md', sizeBytes: 12), + _doc('memory.md', sizeBytes: 34), + _doc('output.md', sizeBytes: 56), + _doc('session.html', contentType: 'text/html', sizeBytes: 78), + ], + ), + ); + expect(docs.map((doc) => doc.name), turnDocumentNames); + expect(docs.every((doc) => doc.record != null), isTrue); + expect(docs.every((doc) => doc.absence.isEmpty), isTrue); + expect(docs[0].record!.contentType, 'text/markdown'); + expect(docs[0].record!.sizeBytes, 12); + expect(docs[3].record!.contentType, 'text/html'); + expect(docs[3].record!.sizeBytes, 78); + }); + + test('only input and output absent messages use the audit words', () { + final docs = visitDocuments( + step( + stage: 'review', + visit: 1, + artifacts: [_doc('input.md'), _doc('output.md')], + ), + ); + expect(docs[1].record, isNull); + expect(docs[1].absence, 'No memory recorded for this visit.'); + expect(docs[3].record, isNull); + expect(docs[3].absence, 'This visit has no harness session.'); + }); + + test('a missing capture yields no slots, never four missing documents', () { + final docs = visitDocuments( + step(stage: 'review', visit: 1, includeArtifacts: false), + ); + expect(docs, isEmpty); + }); + + test('step fields never stand in for a missing document', () { + final docs = visitDocuments({ + 'stage': 'review', + 'sequence': 1, + 'status': 'completed', + 'input': 'looks like input', + 'memory': 'looks like memory', + 'output': 'looks like output', + 'artifacts': >[], + }); + expect(docs, isEmpty); + }); + + test('a recorded session id is not reported as no session', () { + final docs = visitDocuments({ + 'stage': 'review', + 'sequence': 1, + 'status': 'completed', + 'session_id': 'ses-42', + 'artifacts': >[_doc('input.md')], + }); + expect( + docs[3].absence, + 'Session ses-42 is recorded. Its export is not yet available.', + ); + }); + + test('the session export is external-only even when sniffed as text', () { + final docs = visitDocuments( + step( + stage: 'review', + visit: 1, + artifacts: [ + _doc('input.md'), + _doc('session.html', contentType: 'text/plain', sizeBytes: 99), + ], + ), + ); + expect(docs[3].externalOnly, isTrue); + expect(docs[3].opensInViewer, isFalse); + expect(docs[0].opensInViewer, isTrue); + }); + + test('the turn document names share the stage filter order', () { + expect(turnDocumentNames, systemArtifactNames); + }); + + // Every remaining branch of the contextual session wording is exact product + // copy, so each is pinned rather than reached only through the probe. + String sessionAbsence(Map fields) => + visitDocuments({ + 'stage': 'review', + 'sequence': 1, + 'artifacts': >[_doc('input.md')], + ...fields, + })[3].absence; + + test('a skipped or stopped stage never claims a harness session', () { + expect( + sessionAbsence({'status': 'skipped'}), + 'This visit was skipped; no harness session was started.', + ); + expect( + sessionAbsence({'outcome': 'skipped'}), + 'This visit was skipped; no harness session was started.', + ); + expect( + sessionAbsence({'status': 'canceled'}), + 'The stage stopped before a harness session was recorded.', + ); + expect( + sessionAbsence({'status': 'interrupted'}), + 'The stage stopped before a harness session was recorded.', + ); + }); + + test('a model stage states whether its session is running or failed', () { + expect( + sessionAbsence({'status': 'running', 'model': 'luna'}), + 'The stage session is being created.', + ); + expect( + sessionAbsence({'status': 'failed', 'model': 'luna'}), + 'The stage did not create a harness session.', + ); + expect( + sessionAbsence({ + 'status': 'failed', + 'model': 'luna', + 'diagnostic': 'provider rejected the request.', + }), + 'The stage did not create a harness session.' + ' provider rejected the request.', + ); + expect( + sessionAbsence({'provider': 'local'}), + 'Runtime error: this model stage has no recorded session identity.', + ); + }); + + test('a recorded session reports its export recovery state', () { + expect( + sessionAbsence({ + 'session_id': 'ses-9', + 'session_export_recovery': {'status': 'pending'}, + }), + 'Session ses-9 is recorded. Its export is pending recovery.', + ); + expect( + sessionAbsence({ + 'session_id': 'ses-9', + 'session_export_recovery': {'status': 'running'}, + }), + 'Session ses-9 is recorded. Its export is pending recovery.', + ); + expect( + sessionAbsence({ + 'session_export': { + 'session_id': 'ses-8', + 'status': 'complete', + }, + }), + 'Session ses-8 is recorded.' + ' Its export is not available in the artifact inventory.', + ); + expect( + sessionAbsence({ + 'session_export': { + 'session_id': 'ses-7', + 'status': 'failed', + 'diagnostic': 'Disk full.', + }, + }), + 'Session ses-7 is recorded. Its export is failed. Disk full.', + ); + }); + }); + + group('gallery groups', () { + test('groups documents per visit without changing stage grouping', () { + final steps = >[ + step( + stage: 'review', + sequence: 1, + visit: 1, + artifacts: [_doc('input.md'), _doc('output.md')], + ), + step( + stage: 'review', + sequence: 2, + visit: 2, + artifacts: [_doc('input.md'), _doc('memory.md')], + ), + ]; + expect(artifactGroups(steps), isEmpty); + final groups = galleryGroups(steps); + expect(groups.map((group) => group.visit), [1, 2]); + expect(groups[0].artifacts, isEmpty); + expect(groups[0].documents[0].record!.sizeBytes, 12); + expect(groups[1].documents[2].record, isNull); + expect(groups.map((group) => group.recordedCount), [2, 2]); + }); + + test('a visit with neither artifacts nor recorded documents is absent', () { + final steps = >[ + step(stage: 'a', sequence: 1, includeArtifacts: false), + step(stage: 'a', sequence: 2, artifacts: const []), + ]; + expect(galleryGroups(steps), isEmpty); + }); + + test('the header counts recorded documents and stage artifacts', () { + final steps = >[ + step( + stage: 'review', + sequence: 1, + visit: 1, + artifacts: [ + artifact('report.csv', contentType: 'text/csv'), + _doc('input.md'), + _doc('output.md'), + ], + ), + ]; + expect( + artifactsHeader(steps, executing: false), + 'Artifacts · 3 recorded', + ); + }); + + test( + 'markdown documents page in the viewer but session.html never does', + () { + final group = _docGroup([ + 'input.md', + 'output.md', + 'session.html', + ]); + final pages = pagedArtifacts([group]); + expect(pages.map((page) => page.artifact.name), [ + 'input.md', + 'output.md', + ]); + }, + ); + }); +} diff --git a/app/test/features/artifacts/ui/artifact_gallery_documents_test.dart b/app/test/features/artifacts/ui/artifact_gallery_documents_test.dart new file mode 100644 index 00000000..f8335281 --- /dev/null +++ b/app/test/features/artifacts/ui/artifact_gallery_documents_test.dart @@ -0,0 +1,183 @@ +import 'dart:typed_data'; + +import 'package:flutter/cupertino.dart'; +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/api_gateway.dart'; +import 'package:pipelines_app/features/artifacts/ui/artifact_external_open.dart'; +import 'package:pipelines_app/features/artifacts/ui/artifact_gallery_page.dart'; +import 'package:pipelines_app/features/artifacts/ui/artifact_viewer_fetch.dart'; +import 'package:pipelines_app/features/artifacts/ui/artifact_viewer_page.dart'; + +import '../domain/artifact_fixtures.dart'; + +enum _Platform { material, cupertino } + +const String _endpoint = 'ws://127.0.0.1:8081/connect'; + +JsonMap _recorded( + String name, { + required String contentType, + required int sizeBytes, +}) => artifact(name, contentType: contentType, sizeBytes: sizeBytes); + +/// Visit 1 records every turn document except memory. Visit 2 records input and +/// memory only, so both visits carry recorded and missing document slots. +List _steps() => [ + step( + stage: 'review', + sequence: 1, + visit: 1, + artifacts: [ + _recorded('report.csv', contentType: 'text/csv', sizeBytes: 23), + _recorded('input.md', contentType: 'text/markdown', sizeBytes: 120), + _recorded('output.md', contentType: 'text/markdown', sizeBytes: 240), + _recorded('session.html', contentType: 'text/plain', sizeBytes: 512), + ], + ), + step( + stage: 'review', + sequence: 2, + visit: 2, + artifacts: [ + _recorded('notes.md', contentType: 'text/markdown', sizeBytes: 64), + _recorded('input.md', contentType: 'text/markdown', sizeBytes: 130), + _recorded('memory.md', contentType: 'text/markdown', sizeBytes: 256), + ], + ), +]; + +Future _pump( + WidgetTester tester, + _Platform platform, { + List? steps, + ArtifactFetch? fetch, + ArtifactExternalOpen? openExternal, +}) async { + tester.view.physicalSize = const Size(900, 2600); + tester.view.devicePixelRatio = 1; + addTearDown(tester.view.resetPhysicalSize); + addTearDown(tester.view.resetDevicePixelRatio); + final page = ArtifactGalleryPage( + steps: steps ?? _steps(), + configuredEndpoint: _endpoint, + openExternal: openExternal ?? (_) async => true, + fetch: + fetch ?? + (_) async => ArtifactFetchResult( + status: 200, + bytes: Uint8List.fromList('# Recorded input'.codeUnits), + ), + markdownBuilder: (context, value) => Text(value), + ); + await tester.pumpWidget( + platform == _Platform.material + ? MaterialApp(home: page) + : CupertinoApp(home: page), + ); + await tester.pumpAndSettle(); +} + +Finder _dialog(_Platform platform, String text) => find.descendant( + of: find.byType( + platform == _Platform.material ? AlertDialog : CupertinoAlertDialog, + ), + matching: find.text(text), +); + +void main() { + for (final platform in _Platform.values) { + testWidgets('${platform.name}: every recorded document is an entry', ( + tester, + ) async { + await _pump(tester, platform); + expect(find.text('Turn documents'), findsNWidgets(2)); + expect(find.text('input.md'), findsNWidgets(2)); + expect(find.text('output.md'), findsNWidgets(2)); + expect(find.text('session.html'), findsNWidgets(2)); + expect(find.text('memory.md'), findsNWidgets(2)); + expect(find.text('text/markdown · 120\u00a0B'), findsOneWidget); + expect(find.text('text/plain · 512\u00a0B'), findsOneWidget); + }); + + testWidgets('${platform.name}: missing documents show exact wording', ( + tester, + ) async { + await _pump(tester, platform); + expect(find.text('No memory recorded for this visit.'), findsOneWidget); + expect(find.text('No output recorded.'), findsOneWidget); + expect(find.text('This visit has no harness session.'), findsOneWidget); + expect(find.text('No input recorded.'), findsNothing); + }); + + testWidgets('${platform.name}: markdown opens the existing renderer', ( + tester, + ) async { + await _pump(tester, platform); + await tester.tap(find.text('input.md').first); + await tester.pumpAndSettle(); + expect(find.byType(ArtifactViewerPage), findsOneWidget); + expect(find.text('# Recorded input'), findsOneWidget); + expect(find.text('review · visit 1'), findsOneWidget); + expect(find.text('text/markdown · 120\u00a0B'), findsOneWidget); + }); + + testWidgets( + '${platform.name}: absent rows are informational, not controls', + (tester) async { + await _pump(tester, platform); + final absence = find.text('No output recorded.'); + expect(absence, findsOneWidget); + if (platform == _Platform.material) { + // Not disabled: the absence line is content, not a skipped action, and + // is painted with the normal secondary label colour. + final tile = tester.widget( + find.ancestor(of: absence, matching: find.byType(ListTile)), + ); + expect(tile.enabled, isTrue); + expect(tile.onTap, isNull); + expect( + tester.widget(absence).style?.color, + Theme.of(tester.element(absence)).colorScheme.onSurfaceVariant, + ); + } else { + expect( + find.ancestor(of: absence, matching: find.byType(CupertinoButton)), + findsNothing, + ); + } + await tester.tap(absence); + await tester.pumpAndSettle(); + expect(find.byType(ArtifactViewerPage), findsNothing); + expect(find.byType(AlertDialog), findsNothing); + expect(find.byType(CupertinoAlertDialog), findsNothing); + }, + ); + + testWidgets('${platform.name}: session.html stays external-only', ( + tester, + ) async { + final opened = []; + await _pump( + tester, + platform, + openExternal: (uri) async { + opened.add(uri); + return true; + }, + fetch: (_) async => throw StateError('x'), + ); + await tester.tap(find.text('session.html').first); + await tester.pumpAndSettle(); + expect(find.byType(ArtifactViewerPage), findsNothing); + expect(_dialog(platform, 'session.html'), findsOneWidget); + expect(_dialog(platform, 'text/plain · 512\u00a0B'), findsOneWidget); + await tester.tap(_dialog(platform, 'Open')); + await tester.pumpAndSettle(); + expect(find.byType(ArtifactViewerPage), findsNothing); + expect(opened, [ + Uri.parse('http://127.0.0.1:8081/artifacts/1/1/session.html'), + ]); + }); + } +} diff --git a/app/test/features/artifacts/ui/artifact_viewer_page_test.dart b/app/test/features/artifacts/ui/artifact_viewer_page_test.dart index abd7915a..3a4b319a 100644 --- a/app/test/features/artifacts/ui/artifact_viewer_page_test.dart +++ b/app/test/features/artifacts/ui/artifact_viewer_page_test.dart @@ -515,4 +515,42 @@ void main() { // The viewer and its markdown add no Material control to a Cupertino host. expect(find.byType(Material), findsNothing); }); + + testWidgets('Material paging stays inside 320px at 2x text', (tester) async { + tester.view.physicalSize = const Size(640, 1200); + tester.view.devicePixelRatio = 2; + tester.platformDispatcher.textScaleFactorTestValue = 2; + addTearDown(tester.view.resetPhysicalSize); + addTearDown(tester.view.resetDevicePixelRatio); + addTearDown(tester.platformDispatcher.clearTextScaleFactorTestValue); + + final first = recordedArtifact( + 'a.png', + url: '/artifacts/1/1/a.png', + contentType: 'image/png', + ); + final second = recordedArtifact( + 'b.png', + url: '/artifacts/1/2/b.png', + contentType: 'image/png', + ); + final groups = [ + _group([first], visit: 1), + _group([second], visit: 2), + ]; + await _pumpViewer( + tester, + groups: groups, + selected: artifactVisitIdentity(groups[0], first), + ); + + expect(tester.takeException(), isNull); + // Both labelled controls are whole: a clipped Row overflowed the viewport. + for (final label in ['Previous artifact', 'Next artifact']) { + final rect = tester.getRect(find.text(label)); + expect(rect.left, greaterThanOrEqualTo(0), reason: label); + expect(rect.right, lessThanOrEqualTo(320), reason: label); + expect(rect.width, greaterThan(0), reason: label); + } + }); } diff --git a/app/tool/artifact_gallery_probe.dart b/app/tool/artifact_gallery_probe.dart index c16a24b9..df16c30a 100644 --- a/app/tool/artifact_gallery_probe.dart +++ b/app/tool/artifact_gallery_probe.dart @@ -121,6 +121,64 @@ List _steps(String origin, String state) { }, ]; } + if (state == 'documents') { + return [ + { + 'stage': 'reviewer', + 'sequence': 1, + 'status': 'completed', + 'control': {'visit': 1}, + 'artifacts': [ + _file( + 'report.csv', + url: '$origin/fixture/report.csv', + contentType: 'text/csv', + sizeBytes: 23, + ), + _file( + 'input.md', + url: '$origin/fixture/input.md', + contentType: 'text/markdown', + sizeBytes: 120, + ), + _file( + 'output.md', + url: '$origin/fixture/output.md', + contentType: 'text/markdown', + sizeBytes: 240, + ), + // Deliberately sniffed as text/plain: the session export must still + // stay external-only. + _file( + 'session.html', + url: '$origin/fixture/session.html', + contentType: 'text/plain', + sizeBytes: 512, + ), + ], + }, + { + 'stage': 'reviewer', + 'sequence': 2, + 'status': 'completed', + 'control': {'visit': 2}, + 'artifacts': [ + _file( + 'input.md', + url: '$origin/fixture/input-2.md', + contentType: 'text/markdown', + sizeBytes: 130, + ), + _file( + 'memory.md', + url: '$origin/fixture/memory.md', + contentType: 'text/markdown', + sizeBytes: 256, + ), + ], + }, + ]; + } if (state == 'files') { return [ { diff --git a/app/tool/artifact_gallery_probe.mjs b/app/tool/artifact_gallery_probe.mjs index 6903e981..c77a44ac 100644 --- a/app/tool/artifact_gallery_probe.mjs +++ b/app/tool/artifact_gallery_probe.mjs @@ -156,7 +156,7 @@ const waitFor = async (fn, what) => { throw new Error(`Timed out waiting for ${what}: ${stderr.slice(-1500)}`); }; -const evidence = { origin, captures: [], checks: [] }; +const evidence = { origin, captures: [], checks: [], contrast: [], pager: null }; let ws; try { const endpoint = await waitFor( @@ -366,6 +366,58 @@ try { return { max, width: img.width, height: img.height }; })()`); }; + // WCAG contrast of the explanatory (subtitle) line of a two-line row against + // its own background. Only the row's lower half is sampled, so the darker + // title glyphs cannot mask a dim absence line. The text luminance is the + // text-coloured extreme (p2 in light mode, p98 in dark); the background is + // the opposite extreme. + const subtitleContrast = async (prefix, dark) => { + const rect = await rectOfPrefix(prefix); + if (!rect) throw new Error(`No row starting ${JSON.stringify(prefix)}`); + const clip = { + x: rect.x, + y: rect.y + rect.height * 0.45, + width: rect.width, + height: rect.height * 0.55, + scale: 1, + }; + const shot = await send('Page.captureScreenshot', { format: 'png', clip }, session); + return evaluate(`(async () => { + const img = new Image(); + img.src = 'data:image/png;base64,${shot.result.data}'; + await img.decode(); + const canvas = document.createElement('canvas'); + canvas.width = img.width; + canvas.height = img.height; + const ctx = canvas.getContext('2d'); + ctx.drawImage(img, 0, 0); + const data = ctx.getImageData(0, 0, img.width, img.height).data; + const linear = (value) => { + const c = value / 255; + return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4); + }; + const lums = []; + for (let i = 0; i < data.length; i += 4) { + lums.push(0.2126 * linear(data[i]) + 0.7152 * linear(data[i + 1]) + 0.0722 * linear(data[i + 2])); + } + lums.sort((a, b) => a - b); + const at = (fraction) => lums[Math.min(lums.length - 1, Math.floor(lums.length * fraction))]; + const text = ${dark} ? at(0.98) : at(0.02); + const background = ${dark} ? at(0.02) : at(0.98); + const high = Math.max(text, background); + const low = Math.min(text, background); + return { + ratio: (high + 0.05) / (low + 0.05), + textLuminance: text, + backgroundLuminance: background, + p01: at(0.01), + p99: at(0.99), + pixels: lums.length, + width: img.width, + height: img.height, + }; + })()`); + }; const openGallery = async (query) => { await navigate(`${origin}/?${query}`); if (!(await hasLabel('Artifacts'))) { @@ -660,6 +712,116 @@ try { await openScaled('cupertino', 'a1w-cupertino-2x-320'); evidence.checks.push({ check: 'Cupertino 2x/320 keeps the recorded rows, facts and actions', value: true }); + // Turn documents: recorded input/memory/output/session.html are their own + // rows per visit, absent ones carry the exact wording, markdown opens in the + // renderer and the session export stays external-only even when sniffed as + // text/plain. + for (const platform of ['material', 'cupertino']) { + const prefix = `a4-${platform}`; + await navigate(galleryView('&state=documents', platform), 'Artifacts'); + const documentsBody = await bodyText(); + for (const fact of [ + 'Turn documents', + 'input.md', + 'output.md', + 'session.html', + 'memory.md', + 'text/markdown · 120\u00a0B', + 'text/plain · 512\u00a0B', + 'No memory recorded for this visit.', + 'No output recorded.', + 'This visit has no harness session.', + ]) { + if (!documentsBody.includes(fact)) { + throw new Error(`${platform} documents view is missing ${fact}: ${JSON.stringify(documentsBody)}`); + } + } + if (documentsBody.includes('No input recorded.')) { + throw new Error(`${platform} fabricated a missing input document: ${JSON.stringify(documentsBody)}`); + } + evidence.checks.push({ check: `${platform} presents recorded turn documents and exact absence wording`, value: true }); + await capture(`${prefix}-documents`); + + await clickExact('session.html'); + const sessionBody = await visibleText(); + if (!sessionBody.includes('text/plain · 512\u00a0B') || !(await hasLabel('Open'))) { + throw new Error(`${platform} session export lost its facts/Open: ${JSON.stringify(sessionBody)}`); + } + if (sessionBody.includes('Previous artifact') || sessionBody.includes('1 of ')) { + throw new Error(`${platform} opened session.html in the in-app renderer`); + } + evidence.checks.push({ check: `${platform} keeps session.html external-only`, value: true }); + await capture(`${prefix}-session`); + await clickExact('Close'); + await delay(300); + + await navigate(galleryView('&state=documents', platform), 'Artifacts'); + await clickExact('input.md'); + await delay(700); + const inputBody = await visibleText(); + if (!inputBody.includes('recorded artifact /fixture/input.md') || + !inputBody.includes('1 of 4 · text/markdown')) { + throw new Error(`${platform} markdown document did not render in the viewer: ${JSON.stringify(inputBody)}`); + } + evidence.checks.push({ check: `${platform} opens a recorded markdown document in the renderer`, value: true }); + await capture(`${prefix}-document-viewer`); + await clickExact('Back'); + await delay(400); + } + + // Absence rows are informational text, not disabled controls: the Material + // subtitle keeps readable contrast in both themes. + for (const theme of ['light', 'dark']) { + // Rasterise at 3x so a 14px subtitle stroke reaches its nominal colour; + // at 1x, antialiasing dilutes every text colour. + await send('Emulation.setDeviceMetricsOverride', { + width: 390, height: 844, deviceScaleFactor: 3, mobile: true, + }, session); + await navigate(galleryView(`&state=documents&theme=${theme}`), 'Artifacts'); + const sample = await subtitleContrast('memory.md', theme === 'dark'); + evidence.contrast.push({ + sample: `material ${theme} absence subtitle (memory.md)`, + ...sample, + }); + if (sample.ratio < 4.5) { + throw new Error(`Material ${theme} absence subtitle contrast is ${sample.ratio.toFixed(2)}:1`); + } + evidence.checks.push({ + check: `material ${theme} absence subtitle meets 4.5:1`, + value: true, + ratio: Number(sample.ratio.toFixed(2)), + }); + await capture(`a4-material-${theme}-absence-row`); + } + + // The Material pager must keep both labelled controls whole at 320 px with 2x + // text, not clip the second button at the viewport edge. + await send('Emulation.setDeviceMetricsOverride', { + width: 320, height: 720, deviceScaleFactor: 1, mobile: true, + }, session); + await navigate(galleryView('&state=documents&scale=2'), 'Artifacts'); + await clickExact('input.md'); + await delay(700); + if (!(await visibleText()).includes('1 of 4 · text/markdown')) { + throw new Error(`2x document viewer did not open: ${JSON.stringify(await visibleText())}`); + } + const pagerControls = {}; + for (const label of ['Previous artifact', 'Next artifact']) { + const rect = await rectOfPrefix(label); + if (!rect) throw new Error(`2x pager lost ${label}: ${JSON.stringify(await labels())}`); + if (rect.x < -0.5 || rect.x + rect.width > 320.5) { + throw new Error(`${label} leaves the 320px viewport: ${JSON.stringify(rect)}`); + } + pagerControls[label] = rect; + } + evidence.pager = { viewport: 320, textScale: 2, controls: pagerControls }; + evidence.checks.push({ + check: 'Material paging controls stay inside a 320px viewport at 2x text', + value: true, + controls: pagerControls, + }); + await capture('a4-material-320-2x-document-viewer', 320, 720, 1); + // File actions: a real same-origin artifact is fetched, then handed to the // host as a named file. Blob/anchor and navigator.share are intercepted above // so the evidence is the exact bytes, MIME type and download name, not a