From acf74116d74ca66dd3d186acc91e6df66b12f60f Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sat, 31 Oct 2026 12:56:16 +0000 Subject: [PATCH] feat(app): separate turn documents from artifacts --- .../artifacts/ui/artifact_gallery_page.dart | 153 +++++++++++++++--- .../artifacts/ui/artifact_visit_list.dart | 54 ++++--- .../ui/artifact_gallery_documents_test.dart | 113 +++++++++++++ .../ui/run_detail_visit_sections_test.dart | 6 +- 4 files changed, 279 insertions(+), 47 deletions(-) diff --git a/app/lib/features/artifacts/ui/artifact_gallery_page.dart b/app/lib/features/artifacts/ui/artifact_gallery_page.dart index b3b06c1f..06bc5c5a 100644 --- a/app/lib/features/artifacts/ui/artifact_gallery_page.dart +++ b/app/lib/features/artifacts/ui/artifact_gallery_page.dart @@ -7,12 +7,15 @@ import 'package:flutter/services.dart'; import '../../../core/api_gateway.dart'; import '../../../ui/adaptive/host.dart'; import '../../chat/ui/transcript/chat_markdown_view.dart'; +import '../../graph/domain/stage_visits.dart'; import '../actions/artifact_file_actions.dart'; import '../actions/artifact_file_bridge.dart'; +import '../domain/artifact_capture.dart'; import '../domain/artifact_document.dart'; import '../domain/artifact_groups.dart'; import '../domain/artifact_kind.dart'; import '../domain/artifact_record.dart'; +import '../domain/artifact_selection.dart'; import '../domain/artifact_summary.dart'; import '../domain/artifact_url.dart'; import 'artifact_external_open.dart'; @@ -89,31 +92,88 @@ class _ArtifactGalleryPageState extends State { String? _status; List _groupsOf(int? focusIndex) { - if (focusIndex == null) return galleryGroups(widget.steps); - final group = visitArtifactGroup(widget.steps, focusIndex); - 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) { - // The visit pane's own Session section opens session.html, so the - // per-visit Artifacts drill-down keeps only stage output and the other - // turn documents; the run-wide gallery still shows every document. - final documents = enriched.documents - .where((doc) => doc.record?.name != sessionExportDocumentName) - .toList(growable: false); - return [ + final allGroups = _withRepairDocuments(galleryGroups(widget.steps)); + if (focusIndex == null) return allGroups; + if (focusIndex < 0 || focusIndex >= widget.steps.length) { + return const []; + } + final step = widget.steps[focusIndex]; + final stageKey = '${step['stage'] ?? ''}'; + final visits = visitsByStage(widget.steps)[stageKey]; + if (visits == null) return const []; + final visitIndex = visits.indexOf(step); + if (visitIndex < 0) return const []; + final visit = displayVisit(step, visitIndex); + // Find the enriched gallery group directly rather than deriving it from the + // generated-artifact-only group. This retains document-only visits, including + // session.html, in the per-stage Artifacts section. + return [ + for (final group in allGroups) + if (group.stageKey == stageKey && group.visit == visit) group, + ]; + } + + /// Repaired session exports are also turn-owned debugging evidence, despite + /// living outside the four named document slots. + List _withRepairDocuments(List groups) { + final enriched = [ + for (final group in groups) + ArtifactGroup( + stageKey: group.stageKey, + visit: group.visit, + artifacts: group.artifacts, + documents: [ + ...group.documents, + for (final artifact in systemArtifacts( + _stepsByGroup[artifactGroupKey(group.stageKey, group.visit)] ?? + const {}, + )) + if (!group.documents.any( + (document) => + document.record?.url == artifact.url && + document.record?.name == artifact.name, + )) + ArtifactDocument( + name: artifact.name, + record: artifact, + absence: '', + ), + ], + ), + ]; + final keys = { + for (final group in enriched) + artifactGroupKey(group.stageKey, group.visit), + }; + // `galleryGroups` intentionally only creates document-only groups for the + // four standard slots. A repair can be the only recorded evidence, so give + // it the same reachable secondary section. + for (final entry in visitsByStage(widget.steps).entries) { + for (var index = 0; index < entry.value.length; index += 1) { + final step = entry.value[index]; + final visit = displayVisit(step, index); + final key = artifactGroupKey(entry.key, visit); + if (keys.contains(key)) continue; + final documents = systemArtifacts(step); + if (documents.isEmpty) continue; + enriched.add( ArtifactGroup( - stageKey: enriched.stageKey, - visit: enriched.visit, - artifacts: enriched.artifacts, - documents: documents, + stageKey: entry.key, + visit: visit, + artifacts: const [], + documents: [ + for (final artifact in documents) + ArtifactDocument( + name: artifact.name, + record: artifact, + absence: '', + ), + ], ), - ]; + ); } } - return [group]; + return enriched; } Future _select(ArtifactGroup group, ArtifactRecord artifact) async { @@ -129,19 +189,40 @@ class _ArtifactGalleryPageState extends State { if (!externalOnly && resolved != null && isViewerArtifact(artifact.contentType, artifact.name)) { - await _openViewer(identity); + await _openViewer(group, artifact); return; } await _showSelected(group, artifact, resolved); } - Future _openViewer(String identity) async { + Future _openViewer( + ArtifactGroup selectedGroup, + ArtifactRecord artifact, + ) async { + final identity = artifactVisitIdentity(selectedGroup, artifact); + final isDocument = selectedGroup.documents.any( + (document) => + document.record?.url == artifact.url && + document.record?.name == artifact.name, + ); + final viewerGroups = isDocument + ? [ + for (final group in _groups) + ArtifactGroup( + stageKey: group.stageKey, + visit: group.visit, + artifacts: [ + for (final document in group.documents) ?document.record, + ], + ), + ] + : _groups; final previousFocus = FocusManager.instance.primaryFocus; await Navigator.of(context).push( usesCupertinoHost(context) ? CupertinoPageRoute( builder: (_) => ArtifactViewerPage( - groups: _groups, + groups: viewerGroups, selectedIdentity: identity, configuredEndpoint: widget.configuredEndpoint, openExternal: widget.openExternal, @@ -152,7 +233,7 @@ class _ArtifactGalleryPageState extends State { ) : MaterialPageRoute( builder: (_) => ArtifactViewerPage( - groups: _groups, + groups: viewerGroups, selectedIdentity: identity, configuredEndpoint: widget.configuredEndpoint, openExternal: widget.openExternal, @@ -303,10 +384,30 @@ class _ArtifactGalleryPageState extends State { 0, (total, group) => total + group.artifacts.length, ); + if (count == 0 && groups.any((group) => group.documents.isNotEmpty)) { + return 'No artifacts recorded for this visit.'; + } return artifactsSummary(focused, count: count); } if (widget.steps.isEmpty) return 'No steps recorded for this run.'; - return artifactsHeader(widget.steps, executing: widget.executing); + final count = groups.fold( + 0, + (total, group) => total + group.artifacts.length, + ); + if (count == 0) { + if (widget.executing) return 'Artifacts · capture pending'; + if (widget.steps.any( + (step) => !ArtifactCapture.fromStep(step).isAvailable, + )) { + return 'Artifacts · capture unavailable'; + } + return 'No artifacts recorded for this run.'; + } + var label = '${count == 1 ? 'Artifact' : 'Artifacts'} · $count recorded'; + if (widget.steps.any((step) => ArtifactCapture.fromStep(step).isPartial)) { + label += ' · partial capture'; + } + return label; } /// The partial-capture notes shown under the page's summary. diff --git a/app/lib/features/artifacts/ui/artifact_visit_list.dart b/app/lib/features/artifacts/ui/artifact_visit_list.dart index be9ed1ea..93aa2869 100644 --- a/app/lib/features/artifacts/ui/artifact_visit_list.dart +++ b/app/lib/features/artifacts/ui/artifact_visit_list.dart @@ -56,9 +56,8 @@ class ArtifactVisitList extends StatefulWidget { final String configuredEndpoint; final ArtifactFetch fetch; - /// Whether the artifact sections begin closed. Run artifact galleries use - /// the default; this remains configurable for composed hosts that explicitly - /// want to restore their own open state. + /// Whether generated-artifact sections begin closed. Turn documents always + /// begin closed because they are debugging evidence. final bool initiallyCollapsed; /// The layout last chosen, kept for the app's lifetime. @@ -78,16 +77,15 @@ class _ArtifactVisitListState extends State { @override void initState() { super.initState(); - _closed = widget.initiallyCollapsed - ? { - for (final group in widget.groups) - if (group.artifacts.isNotEmpty) - '${group.stageKey}\u0000${group.visit}\u0000artifacts', - for (final group in widget.groups) - if (group.documents.isNotEmpty) - '${group.stageKey}\u0000${group.visit}\u0000documents', - } - : {}; + _closed = { + if (widget.initiallyCollapsed) + for (final group in widget.groups) + if (group.artifacts.isNotEmpty) + '${group.stageKey}\u0000${group.visit}\u0000artifacts', + for (final group in widget.groups) + if (group.documents.isNotEmpty) + '${group.stageKey}\u0000${group.visit}\u0000documents', + }; } void _toggle(String key) => setState(() { @@ -132,11 +130,17 @@ class _ArtifactVisitListState extends State { key: key, title: '${artifactGroupLabel(group)} · Turn documents', count: group.documents.length, - body: ArtifactDocumentSection( - group: group, - selectedIdentity: widget.selectedIdentity, - onSelected: widget.onSelected, - showHeader: false, + body: Column( + crossAxisAlignment: CrossAxisAlignment.stretch, + children: [ + _debugHint(context), + ArtifactDocumentSection( + group: group, + selectedIdentity: widget.selectedIdentity, + onSelected: widget.onSelected, + showHeader: false, + ), + ], ), ), ); @@ -220,6 +224,20 @@ class _ArtifactVisitListState extends State { ); } + Widget _debugHint(BuildContext context) { + final style = usesCupertinoHost(context) + ? CupertinoTheme.of(context).textTheme.textStyle.copyWith( + color: CupertinoColors.secondaryLabel.resolveFrom(context), + ) + : Theme.of(context).textTheme.bodySmall?.copyWith( + color: Theme.of(context).colorScheme.onSurfaceVariant, + ); + return Padding( + padding: const EdgeInsetsDirectional.fromSTEB(16, 8, 16, 4), + child: Text('For debugging.', style: style), + ); + } + /// The list view: one row per artifact with a small thumbnail beside it. Widget _list(ArtifactGroup group) => Column( crossAxisAlignment: CrossAxisAlignment.stretch, diff --git a/app/test/features/artifacts/ui/artifact_gallery_documents_test.dart b/app/test/features/artifacts/ui/artifact_gallery_documents_test.dart index 368bd496..258f351a 100644 --- a/app/test/features/artifacts/ui/artifact_gallery_documents_test.dart +++ b/app/test/features/artifacts/ui/artifact_gallery_documents_test.dart @@ -53,6 +53,7 @@ Future _pump( List? steps, ArtifactFetch? fetch, ArtifactExternalOpen? openExternal, + int? focusIndex, }) async { tester.view.physicalSize = const Size(900, 2600); tester.view.devicePixelRatio = 1; @@ -60,6 +61,7 @@ Future _pump( addTearDown(tester.view.resetDevicePixelRatio); final page = ArtifactGalleryPage( steps: steps ?? _steps(), + focusIndex: focusIndex, configuredEndpoint: _endpoint, openExternal: openExternal ?? (_) async => true, fetch: @@ -78,6 +80,14 @@ Future _pump( await tester.pumpAndSettle(); } +Future _expandTurnDocuments(WidgetTester tester) async { + final headings = find.textContaining('Turn documents'); + for (var index = 0; index < headings.evaluate().length; index += 1) { + await tester.tap(headings.at(index)); + await tester.pumpAndSettle(); + } +} + Finder _dialog(_Platform platform, String text) => find.descendant( of: find.byType( platform == _Platform.material ? AlertDialog : CupertinoAlertDialog, @@ -92,6 +102,11 @@ void main() { ) async { await _pump(tester, platform); expect(find.textContaining('Turn documents'), findsNWidgets(2)); + // The generated artifact grid remains primary; debugging evidence is + // deliberately hidden until its own section is opened. + expect(find.text('input.md'), findsNothing); + expect(find.text('For debugging.'), findsNothing); + await _expandTurnDocuments(tester); expect(find.text('input.md'), findsNWidgets(2)); expect(find.text('output.md'), findsNWidgets(2)); expect(find.text('session.html'), findsNWidgets(2)); @@ -104,6 +119,7 @@ void main() { tester, ) async { await _pump(tester, platform); + await _expandTurnDocuments(tester); 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); @@ -114,6 +130,7 @@ void main() { tester, ) async { await _pump(tester, platform); + await _expandTurnDocuments(tester); await tester.tap(find.text('input.md').first); await tester.pumpAndSettle(); expect(find.byType(ArtifactViewerPage), findsOneWidget); @@ -128,6 +145,7 @@ void main() { '${platform.name}: absent rows are informational, not controls', (tester) async { await _pump(tester, platform); + await _expandTurnDocuments(tester); final absence = find.text('No output recorded.'); expect(absence, findsOneWidget); if (platform == _Platform.material) { @@ -169,6 +187,7 @@ void main() { }, fetch: (_) async => throw StateError('x'), ); + await _expandTurnDocuments(tester); await tester.tap(find.text('session.html').first); await tester.pumpAndSettle(); expect(find.byType(ArtifactViewerPage), findsNothing); @@ -181,5 +200,99 @@ void main() { Uri.parse('http://127.0.0.1:8081/artifacts/1/1/session.html'), ]); }); + + testWidgets('${platform.name}: documents do not count as artifacts and ' + 'viewer paging stays within documents', (tester) async { + await _pump( + tester, + platform, + steps: [ + step( + stage: 'review', + visit: 1, + artifacts: [ + _recorded('report.csv', contentType: 'text/csv', sizeBytes: 23), + _recorded('input.md', contentType: 'text/markdown', sizeBytes: 1), + _recorded( + 'output.md', + contentType: 'text/markdown', + sizeBytes: 1, + ), + ], + ), + ], + ); + + expect(find.text('Artifact · 1 recorded'), findsOneWidget); + expect(find.text('report.csv'), findsOneWidget); + expect(find.text('input.md'), findsNothing); + await _expandTurnDocuments(tester); + expect(find.text('For debugging.'), findsOneWidget); + await tester.tap(find.text('input.md')); + await tester.pumpAndSettle(); + expect(find.byType(ArtifactViewerPage), findsOneWidget); + expect(find.text('1 of 2 · text/markdown'), findsOneWidget); + }); + + testWidgets('${platform.name}: document-only visits retain an honest empty ' + 'artifact state', (tester) async { + await _pump( + tester, + platform, + steps: [ + step( + stage: 'review', + visit: 1, + artifacts: [ + _recorded('input.md', contentType: 'text/markdown', sizeBytes: 1), + ], + ), + ], + ); + + expect(find.text('No artifacts recorded for this run.'), findsOneWidget); + expect(find.text('input.md'), findsNothing); + await _expandTurnDocuments(tester); + expect(find.text('input.md'), findsOneWidget); + expect(find.text('For debugging.'), findsOneWidget); + }); + + testWidgets('${platform.name}: focused document-only visits retain turn ' + 'documents', (tester) async { + await _pump( + tester, + platform, + focusIndex: 0, + steps: [ + step( + stage: 'review', + visit: 1, + artifacts: [ + _recorded('input.md', contentType: 'text/markdown', sizeBytes: 1), + ], + ), + ], + ); + + expect( + find.text('No artifacts recorded for this visit.'), + findsOneWidget, + ); + expect(find.text('input.md'), findsNothing); + await _expandTurnDocuments(tester); + expect(find.text('input.md'), findsOneWidget); + expect(find.text('For debugging.'), findsOneWidget); + }); + + testWidgets('${platform.name}: focused visits retain session documents', ( + tester, + ) async { + await _pump(tester, platform, focusIndex: 0); + + expect(find.text('session.html'), findsNothing); + await _expandTurnDocuments(tester); + expect(find.text('session.html'), findsOneWidget); + expect(find.text('For debugging.'), findsOneWidget); + }); } } diff --git a/app/test/features/runs/ui/run_detail_visit_sections_test.dart b/app/test/features/runs/ui/run_detail_visit_sections_test.dart index 72b156fb..08758d06 100644 --- a/app/test/features/runs/ui/run_detail_visit_sections_test.dart +++ b/app/test/features/runs/ui/run_detail_visit_sections_test.dart @@ -79,12 +79,12 @@ void main() { expect(find.text('ok'), findsOneWidget); await openVisitTab(tester, RunVisitSection.artifacts); - // The section is the run's gallery, focused on this visit: exactly the - // stage's files, without the session evidence file. + // The focused gallery keeps generated files primary and makes the session + // evidence reachable in its secondary turn-documents section. await _expandArtifactGroup(tester); expect(find.byType(ArtifactGalleryPage), findsOneWidget); expect(find.text('plan.csv'), findsOneWidget); - expect(find.text('session.html'), findsNothing); + expect(find.text('session.html'), findsOneWidget); await openVisitTab(tester, RunVisitSection.session); expect(find.text('Session'), findsWidgets);