From 746e23788d03e6b50a9ded2a68b465ec4702f5fd Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Thu, 12 Nov 2026 02:25:09 +0000 Subject: [PATCH] Mark chats seen after user interaction Prevent passive open, restored, or unfocused chats from clearing notifications. Track qualifying focused interactions and cover passive and active seen-watermark behavior with tests and notes. --- app/lib/application/pipelines_app.dart | 4 +- app/lib/features/chat/chat_pane_content.dart | 65 +-- .../conversation/chat_seen_interaction.dart | 128 ++++++ .../chat/ui/sessions/chat_seen_focus.dart | 46 +++ .../ui/sessions/chat_sessions_controller.dart | 98 ++++- .../ui/sessions/chat_sessions_screen.dart | 26 +- .../features/settings/server_connections.dart | 17 + app/notes/chat-seen-only-after-interaction.md | 98 +++++ .../chat_seen_interaction_test.dart | 220 ++++++++++ .../sessions/chat_seen_interaction_test.dart | 376 ++++++++++++++++++ 10 files changed, 1013 insertions(+), 65 deletions(-) create mode 100644 app/lib/features/chat/conversation/chat_seen_interaction.dart create mode 100644 app/lib/features/chat/ui/sessions/chat_seen_focus.dart create mode 100644 app/notes/chat-seen-only-after-interaction.md create mode 100644 app/test/features/chat/conversation/chat_seen_interaction_test.dart create mode 100644 app/test/features/chat/ui/sessions/chat_seen_interaction_test.dart diff --git a/app/lib/application/pipelines_app.dart b/app/lib/application/pipelines_app.dart index f3a52b45..88fbd3ef 100644 --- a/app/lib/application/pipelines_app.dart +++ b/app/lib/application/pipelines_app.dart @@ -374,7 +374,9 @@ class _PipelinesAppState extends State }, sessionTitle: _chatSessionTitle, openChat: (id) { - if (mounted) _delegate.goTo(AppRoute.chatSession(id)); + if (!mounted) return; + widget.servers?.requestChatOpen(id); + _delegate.goTo(AppRoute.chatSession(id)); }, bridge: _notifications.bridge, ); diff --git a/app/lib/features/chat/chat_pane_content.dart b/app/lib/features/chat/chat_pane_content.dart index 247dce96..b8d92bb8 100644 --- a/app/lib/features/chat/chat_pane_content.dart +++ b/app/lib/features/chat/chat_pane_content.dart @@ -5,6 +5,7 @@ import '../../core/servers/server_context.dart'; import '../../shell/destination.dart'; import '../../shell/detail_page.dart'; import 'chat_runtime.dart'; +import 'conversation/chat_seen_interaction.dart'; import 'conversation/chat_thread_view.dart'; import 'conversation/composer_focus_request.dart'; import 'workspace/chat_pane_commands.dart'; @@ -79,36 +80,42 @@ Widget buildChatPaneContent({ child: ServerContext.forServer( context, runtime.serverIdFor(sessionId), - ChatThreadView( - key: ValueKey('chat-session-$sessionId'), - gateway: runtime.gatewayFor(sessionId), + ChatSeenInteraction( sessionId: sessionId, - title: '${row?['title'] ?? ''}'.trim(), - session: row, - syncToken: placement.syncToken, - scrollPositions: runtime.scrollPositions, - transcripts: runtime.transcripts, - initialNotice: start != null && start.id == sessionId - ? start.notice - : null, - onBack: placement.onBack, - onModelChanged: (applied) => - runtime.modelChanged(sessionId, applied), - onModeChanged: (mode, name) => - runtime.acceptMode(sessionId, mode, name), - onEffortChanged: (state) => runtime.acceptEffort(sessionId, state), - onNewSession: placement.onNewSession, - onSessionRenamed: (title) => runtime.acceptRename(sessionId, title), - onSessionClosed: placement.onSessionClosed, - onColorSelected: (color) => - runtime.sessions.setColor(sessionId, color), - onNextChat: placement.onNextChat, - useNativeBack: placement.useNativeBack, - pasteTarget: placement.pasteTarget, - ownsPasteWhenFocused: placement.ownsPasteWhenFocused, - showBackButton: placement.showBackButton, - paneControls: placement.paneControls?.call(context) ?? const [], - paneCommands: placement.paneCommands, + onInteract: () => runtime.sessions.reportInteraction(sessionId), + child: ChatThreadView( + key: ValueKey('chat-session-$sessionId'), + gateway: runtime.gatewayFor(sessionId), + sessionId: sessionId, + title: '${row?['title'] ?? ''}'.trim(), + session: row, + syncToken: placement.syncToken, + scrollPositions: runtime.scrollPositions, + transcripts: runtime.transcripts, + initialNotice: start != null && start.id == sessionId + ? start.notice + : null, + onBack: placement.onBack, + onModelChanged: (applied) => + runtime.modelChanged(sessionId, applied), + onModeChanged: (mode, name) => + runtime.acceptMode(sessionId, mode, name), + onEffortChanged: (state) => + runtime.acceptEffort(sessionId, state), + onNewSession: placement.onNewSession, + onSessionRenamed: (title) => + runtime.acceptRename(sessionId, title), + onSessionClosed: placement.onSessionClosed, + onColorSelected: (color) => + runtime.sessions.setColor(sessionId, color), + onNextChat: placement.onNextChat, + useNativeBack: placement.useNativeBack, + pasteTarget: placement.pasteTarget, + ownsPasteWhenFocused: placement.ownsPasteWhenFocused, + showBackButton: placement.showBackButton, + paneControls: placement.paneControls?.call(context) ?? const [], + paneCommands: placement.paneCommands, + ), ), ), ); diff --git a/app/lib/features/chat/conversation/chat_seen_interaction.dart b/app/lib/features/chat/conversation/chat_seen_interaction.dart new file mode 100644 index 00000000..c8c340c3 --- /dev/null +++ b/app/lib/features/chat/conversation/chat_seen_interaction.dart @@ -0,0 +1,128 @@ +import 'package:flutter/rendering.dart' show ScrollDirection; +import 'package:flutter/services.dart' + show HardwareKeyboard, KeyDownEvent, KeyEvent; +import 'package:flutter/widgets.dart'; + +import '../../../core/servers/server_context.dart'; +import '../../settings/server_connections.dart'; + +/// Reports the user's own actions in one open chat, so the chat can be read. +/// +/// Counted: a pointer press anywhere in the pane (click or tap, which also +/// makes it the active pane), a user-driven scroll of its transcript, a key +/// press while focus is inside it (typing, Tab), focus arriving in it from a +/// key press outside it (Tab into the pane), and a notification tap that +/// opened it. Showing the pane, rebuilding it, receiving content, or focus +/// moved in code with no key press does not report anything. [onInteract] +/// decides whether the window is focused. +class ChatSeenInteraction extends StatefulWidget { + const ChatSeenInteraction({ + super.key, + required this.sessionId, + required this.onInteract, + required this.child, + }); + + final String sessionId; + final VoidCallback onInteract; + final Widget child; + + @override + State createState() => _ChatSeenInteractionState(); +} + +class _ChatSeenInteractionState extends State { + ServerConnections? _connections; + + /// True from a key-down until the next frame. Focus changes are applied in a + /// microtask queued by the key dispatch, which runs before that frame, so a + /// focus change caused by the key sees the flag. A focus change with no key + /// press (restoration, code-driven focus) never does. + bool _keyDownInProgress = false; + + @override + void initState() { + super.initState(); + HardwareKeyboard.instance.addHandler(_onKeyEvent); + } + + bool _onKeyEvent(KeyEvent event) { + if (event is KeyDownEvent && !_keyDownInProgress) { + _keyDownInProgress = true; + WidgetsBinding.instance.addPostFrameCallback((_) { + _keyDownInProgress = false; + }); + WidgetsBinding.instance.scheduleFrame(); + } + return false; + } + + void _onFocusChange(bool hasFocus) { + if (hasFocus && _keyDownInProgress) widget.onInteract(); + } + + @override + void didChangeDependencies() { + super.didChangeDependencies(); + final connections = ServerContext.maybeOf(context)?.notifier; + if (identical(connections, _connections)) return; + _connections?.removeListener(_takeNotificationOpen); + _connections = connections; + connections?.addListener(_takeNotificationOpen); + _takeNotificationOpen(); + } + + @override + void didUpdateWidget(covariant ChatSeenInteraction oldWidget) { + super.didUpdateWidget(oldWidget); + if (oldWidget.sessionId != widget.sessionId) _takeNotificationOpen(); + } + + @override + void dispose() { + HardwareKeyboard.instance.removeHandler(_onKeyEvent); + _connections?.removeListener(_takeNotificationOpen); + super.dispose(); + } + + /// A notification tap that named this chat is the user opening it. It is + /// reported after the frame, so the list has taken the chat as active first. + void _takeNotificationOpen() { + final connections = _connections; + if (connections == null || + !connections.takeChatOpenIntent(widget.sessionId)) { + return; + } + WidgetsBinding.instance.addPostFrameCallback((_) { + if (mounted) widget.onInteract(); + }); + } + + static bool _userScrolled(ScrollNotification notification) => + (notification is UserScrollNotification && + notification.direction != ScrollDirection.idle) || + (notification is ScrollStartNotification && + notification.dragDetails != null); + + @override + Widget build(BuildContext context) => Listener( + behavior: HitTestBehavior.translucent, + onPointerDown: (_) => widget.onInteract(), + child: NotificationListener( + onNotification: (notification) { + if (_userScrolled(notification)) widget.onInteract(); + return false; + }, + child: Focus( + canRequestFocus: false, + skipTraversal: true, + onFocusChange: _onFocusChange, + onKeyEvent: (node, event) { + if (event is KeyDownEvent) widget.onInteract(); + return KeyEventResult.ignored; + }, + child: widget.child, + ), + ), + ); +} diff --git a/app/lib/features/chat/ui/sessions/chat_seen_focus.dart b/app/lib/features/chat/ui/sessions/chat_seen_focus.dart new file mode 100644 index 00000000..76c5b52f --- /dev/null +++ b/app/lib/features/chat/ui/sessions/chat_seen_focus.dart @@ -0,0 +1,46 @@ +import 'package:flutter/widgets.dart'; + +/// Whether the app window is focused and visible: the only state in which a +/// chat can be read. A backgrounded or unfocused window never marks a chat +/// seen, so a reply that arrives there stays New until the user interacts. +class ChatSeenFocus extends ChangeNotifier { + ChatSeenFocus({bool focused = true}) { + _focused = focused; + } + + /// The app's own focus, driven by the framework's lifecycle state. A null + /// lifecycle state (before the first report) counts as focused, so a window + /// that starts visible is not stuck unread. + static final ChatSeenFocus app = ChatSeenFocus._observingApp(); + + factory ChatSeenFocus._observingApp() { + final focus = ChatSeenFocus( + focused: _isFocusedState(WidgetsBinding.instance.lifecycleState), + ); + WidgetsBinding.instance.addObserver(_LifecycleFocus(focus)); + return focus; + } + + late bool _focused; + bool get focused => _focused; + + set focused(bool value) { + if (value == _focused) return; + _focused = value; + notifyListeners(); + } + + static bool _isFocusedState(AppLifecycleState? state) => + state == null || state == AppLifecycleState.resumed; +} + +class _LifecycleFocus with WidgetsBindingObserver { + _LifecycleFocus(this._focus); + + final ChatSeenFocus _focus; + + @override + void didChangeAppLifecycleState(AppLifecycleState state) { + _focus.focused = ChatSeenFocus._isFocusedState(state); + } +} diff --git a/app/lib/features/chat/ui/sessions/chat_sessions_controller.dart b/app/lib/features/chat/ui/sessions/chat_sessions_controller.dart index 831bbb18..41c4366d 100644 --- a/app/lib/features/chat/ui/sessions/chat_sessions_controller.dart +++ b/app/lib/features/chat/ui/sessions/chat_sessions_controller.dart @@ -12,6 +12,7 @@ import '../../../attention/runtime/attention_ack_sync.dart'; import '../../data/chat_repository.dart'; import '../../domain/chat_list_activity.dart'; import '../../domain/chat_sessions.dart'; +import 'chat_seen_focus.dart'; import 'chat_session_local.dart'; import 'session_attention.dart'; @@ -23,8 +24,10 @@ import 'session_attention.dart'; /// read watermark are local. /// /// With an [AttentionAckSync] (bound to the gateway by the app, or passed in), -/// reading is shared: opening a chat acknowledges a `chat_seen` watermark to -/// every device, and a watermark acknowledged elsewhere that is newer than this +/// reading is shared: a user interaction with a chat (opening it, or acting in +/// its pane while the window is focused, see [reportInteraction]) acknowledges +/// a `chat_seen` watermark to every device. Being visible, restored or +/// receiving a reply never does. A watermark acknowledged elsewhere that is newer than this /// device's own clears the chat's New badge here. The local store remains the /// offline cache of both. class ChatSessionsController extends ChangeNotifier { @@ -33,8 +36,10 @@ class ChatSessionsController extends ChangeNotifier { ChatSessionLocalStore? localStore, AttentionAckSync? ackSync, int Function()? nowMillis, + ChatSeenFocus? seenFocus, this.activeAckDelay = const Duration(milliseconds: 1500), - }) : _localStore = + }) : _focus = seenFocus ?? ChatSeenFocus.app, + _localStore = localStore ?? (repository.gateway is FederatedChatGateway ? FederatedChatSessionLocalStore( @@ -46,12 +51,27 @@ class ChatSessionsController extends ChangeNotifier { ), )), _nowMillis = nowMillis ?? _wallClockMillis { + _focus.addListener(_focusChanged); _listenFrames(); _bindAckSync(ackSync ?? attentionAckSyncOf(repository.gateway)); } static int _wallClockMillis() => DateTime.now().millisecondsSinceEpoch; + final ChatSeenFocus _focus; + + /// The open chat the user has interacted with while the window was focused. + /// Only such a chat acknowledges new content as it arrives; any other reply + /// in the open chat stays New until the next interaction. Cleared when the + /// window loses focus or another chat becomes the open one. + final Set _engaged = {}; + + void _focusChanged() { + if (_focus.focused) return; + _engaged.clear(); + _cancelPendingActiveAck(); + } + /// How long the open chat stays quiet before its new content is /// acknowledged to the other devices; streaming text arrives in many frames. final Duration activeAckDelay; @@ -61,6 +81,8 @@ class ChatSessionsController extends ChangeNotifier { final int Function() _nowMillis; AttentionAckSync? _ackSync; Timer? _activeAck; + // The chat whose quiet-period acknowledgement [_activeAck] is waiting on. + String? _pendingAckId; ChatSessionLocal _local = const ChatSessionLocal(); final Map _actionErrors = {}; List _sessions = const []; @@ -78,7 +100,17 @@ class ChatSessionsController extends ChangeNotifier { // older snapshot that arrives later never replaces it. final Map _activity = {}; StreamSubscription? _frameSubscription; - String? activeSessionId; + String? _activeSessionId; + + /// The chat open above the list. Opening another chat ends the engagement + /// with the previous one; setting the same id changes nothing. + String? get activeSessionId => _activeSessionId; + set activeSessionId(String? id) { + if (id == _activeSessionId) return; + _activeSessionId = id; + _engaged.clear(); + _cancelPendingActiveAck(); + } void _listenFrames() { _frameSubscription?.cancel(); @@ -98,8 +130,14 @@ class ChatSessionsController extends ChangeNotifier { final row = session.first; if (row['closed_at'] != null || row['closed'] == true) return; if (effect.running != null) _setRunning(id, effect.running!); - if (effect.attention && id != activeSessionId) unawaited(_markUnseen(id)); - if (effect.attention && id == activeSessionId) _scheduleActiveAck(id); + if (!effect.attention) return; + if (id == activeSessionId && _focus.focused && _engaged.contains(id)) { + _scheduleActiveAck(id); + } else { + // Passive: the window is unfocused, or the chat was open with no + // interaction since, so the reply is New until the user acts. + unawaited(_markUnseen(id)); + } } /// Another device changed a chat's shared colour, star or title: the row @@ -210,12 +248,45 @@ class ChatSessionsController extends ChangeNotifier { void _scheduleActiveAck(String id) { if (_ackSync == null) return; _activeAck?.cancel(); + _pendingAckId = id; _activeAck = Timer(activeAckDelay, () { - if (_disposed || id != activeSessionId) return; + _activeAck = null; + _pendingAckId = null; + // Losing focus or the chat during the quiet period ends the engagement; + // [_cancelPendingActiveAck] has already marked the reply New by then. + if (_disposed || id != activeSessionId || !_engaged.contains(id)) return; unawaited(_acknowledgeSeen(id, 0)); }); } + /// Ends a quiet period that has not fired yet. The reply it was waiting on + /// arrived while the user was engaged, but the engagement ends before the + /// quiet period does, so that reply is marked New here rather than dropped. + void _cancelPendingActiveAck() { + final pending = _pendingAckId; + if (pending == null) return; + _activeAck?.cancel(); + _activeAck = null; + _pendingAckId = null; + unawaited(_markUnseen(pending)); + } + + /// The user acted in [id]: a click, tap, scroll, key press in its pane, or + /// opening it. Only while the window is focused; a passive state is ignored. + /// Everything up to the latest message is marked seen and acknowledged to + /// every device. Repeated interactions (every scroll tick) send nothing once + /// the chat is engaged and has no unread content. + void reportInteraction(String id) { + if (_disposed || id.isEmpty || !_focus.focused) return; + final firstInChat = id == activeSessionId && _engaged.add(id); + if (!firstInChat && !_local.isUnseen(id)) return; + final row = _sessions.where((row) => '${row['id'] ?? ''}' == id); + final updatedAt = row.isEmpty + ? 0 + : chatSessionMillis(row.first['updated_at']); + unawaited(_acknowledgeSeen(id, updatedAt)); + } + /// Applies watermarks acknowledged on any device: one newer than this /// device's own marks the chat read here (clearing its New badge) and raises /// the local watermark, so a later badge is not cleared by the same ack. @@ -265,9 +336,9 @@ class ChatSessionsController extends ChangeNotifier { Future _markUnseen(String id) async { await _ensureLocal(); - // Loading device preferences may race an operator opening this chat. The - // open is authoritative even when the triggering frame arrived first. - if (_disposed || id == activeSessionId) return; + // Loading device preferences may race an operator engaging this chat. The + // interaction is authoritative even when the triggering frame arrived first. + if (_disposed || (id == activeSessionId && _engaged.contains(id))) return; final next = _local.markUnseen(id); if (identical(next, _local)) return; _local = next; @@ -443,11 +514,15 @@ class ChatSessionsController extends ChangeNotifier { _notify(); } - /// Records that this device has read [session]'s current recency. + /// Records that this device has read [session]'s current recency. Called + /// only for the user's own open (a list row, a shortcut, a notification), so + /// it also engages the chat. Showing a chat that was already open, such as a + /// restored layout, never calls this. Future markOpened(JsonMap session) async { final id = '${session['id'] ?? ''}'; if (id.isEmpty) return; activeSessionId = id; + if (_focus.focused) _engaged.add(id); await _ensureLocal(); if (_disposed) return; final updatedAt = chatSessionMillis(session['updated_at']); @@ -564,6 +639,7 @@ class ChatSessionsController extends ChangeNotifier { unawaited(_frameSubscription?.cancel()); _activeAck?.cancel(); _ackSync?.removeListener(_ackChanged); + _focus.removeListener(_focusChanged); super.dispose(); } } diff --git a/app/lib/features/chat/ui/sessions/chat_sessions_screen.dart b/app/lib/features/chat/ui/sessions/chat_sessions_screen.dart index d74c905d..7f3c192e 100644 --- a/app/lib/features/chat/ui/sessions/chat_sessions_screen.dart +++ b/app/lib/features/chat/ui/sessions/chat_sessions_screen.dart @@ -112,7 +112,6 @@ class _ChatSessionsScreenState extends State { final _search = TextEditingController(); late final ChatSectionFolds _folds = widget.folds ?? ChatSectionFolds(); Timer? _undoTimer; - String? _markedActiveSessionId; @override void initState() { @@ -123,7 +122,6 @@ class _ChatSessionsScreenState extends State { /// Reports the loaded rows at the end of the frame: the destination learns a /// routed row without this screen calling back inside its own build. void _reportSessions() { - _markActiveSessionRead(); if (widget.onSessions == null) return; WidgetsBinding.instance.addPostFrameCallback((_) { if (!mounted) return; @@ -131,28 +129,10 @@ class _ChatSessionsScreenState extends State { }); } - void _markActiveSessionRead() { - final id = widget.activeSessionId; - if (id == null) { - _markedActiveSessionId = null; - return; - } - if (id == _markedActiveSessionId) return; - for (final session in _controller.sessions) { - if (_sessionId(session) != id) continue; - // Mark synchronously so row activation and subsequent list notifications - // cannot write the same read watermark twice. - _markedActiveSessionId = id; - unawaited(_controller.markOpened(session)); - return; - } - } - @override void didUpdateWidget(covariant ChatSessionsScreen oldWidget) { super.didUpdateWidget(oldWidget); _controller.activeSessionId = widget.activeSessionId; - _markActiveSessionRead(); if (oldWidget.gateway != widget.gateway) { _controller.replaceRepository(ChatRepository(widget.gateway)); } else if (oldWidget.syncToken != widget.syncToken) { @@ -252,10 +232,8 @@ class _ChatSessionsScreenState extends State { if (session != null && mounted) widget.onOpen(session); } - void _markOpened(JsonMap session) { - _markedActiveSessionId = _sessionId(session); - unawaited(_controller.markOpened(session)); - } + void _markOpened(JsonMap session) => + unawaited(_controller.markOpened(session)); void _openBeside(JsonMap session) { _markOpened(session); diff --git a/app/lib/features/settings/server_connections.dart b/app/lib/features/settings/server_connections.dart index 4160e915..ef485709 100644 --- a/app/lib/features/settings/server_connections.dart +++ b/app/lib/features/settings/server_connections.dart @@ -46,6 +46,23 @@ class ServerConnections extends ChangeNotifier { return true; } + String? _chatOpenId; + + /// A chat the user opened from a notification. The tap is the user's own + /// interaction, so the chat it opens is read; a route restored without a tap + /// never sets this. + void requestChatOpen(String sessionId) { + _chatOpenId = sessionId; + notifyListeners(); + } + + /// Consumes the notification open of [sessionId], once. + bool takeChatOpenIntent(String sessionId) { + if (sessionId.isEmpty || sessionId != _chatOpenId) return false; + _chatOpenId = null; + return true; + } + /// Keep the intent outside the app that selecting another machine disposes. Future requestNewChat(String id) async { if (_busy || _disposed) return false; diff --git a/app/notes/chat-seen-only-after-interaction.md b/app/notes/chat-seen-only-after-interaction.md new file mode 100644 index 00000000..1a046f83 --- /dev/null +++ b/app/notes/chat-seen-only-after-interaction.md @@ -0,0 +1,98 @@ +# Chat seen only after a real interaction + +A chat's `chat_seen` watermark (which clears its phone notifications on every +device) is now sent only after the user acts in that chat while the app window +is focused. Showing, restoring or receiving a reply in an open chat is no +longer enough. + +## Before + +- `ChatSessionsScreen` called `markOpened` for the open chat on every list + update and widget change, so a chat left open on one device (the Mac) was + marked seen within about a second. +- Any reply in the open chat scheduled an acknowledgement after a 1.5 s quiet + period, whether or not the user was there. + +## After + +| State | Seen sent? | Why | +| --- | --- | --- | +| Reply while the window is unfocused / backgrounded | no | `ChatSeenFocus` is not `resumed`; the chat is marked locally unread. | +| Layout restored on start with a chat open | no | The screen only sets the open id; it no longer calls `markOpened`. | +| Open chat, no interaction since, reply arrives | no | Not engaged; reply is marked locally unread. | +| Open chat idle for minutes | no | Same as above; nothing schedules an acknowledgement. | +| Engaged chat, window then unfocused, refocused without input, reply | no | Losing focus clears the engagement. | +| Engaged chat, reply still in its quiet period, then focus lost | no | The pending acknowledgement is cancelled and the reply is marked locally unread at once. | +| Engaged chat, reply still in its quiet period, then another chat opened | no | Same cancel path; the reply stays New. | +| Reply in a chat that is not open | no (New badge) | Unchanged behaviour. | +| Click / tap in the pane | yes | `ChatSeenInteraction` pointer listener. | +| User scroll (drag, wheel) of the transcript | yes | Scroll notifications. Programmatic scroll is ignored. | +| Key press with focus in the pane (typing, Tab) | yes | `Focus.onKeyEvent` on the pane. | +| Keyboard focus moved into the pane by a key press outside it (Tab) | yes | `HardwareKeyboard` flags the key-down; the pane's `Focus.onFocusChange` reports when focus arrives during it. | +| Focus moved into the pane in code, no key press (restore, autofocus) | no | No key-down in progress, so nothing is reported. | +| Opening from the list / shortcut | yes | `markOpened` (unchanged call site, now the only open path). | +| Notification tap that opened the chat | yes | `ServerConnections.requestChatOpen` / `takeChatOpenIntent`. | +| Engaged chat, reply arrives | yes, after 1.5 s quiet | Existing quiet-period ack, now gated on engagement. | + +Once the user interacts, the chat is marked seen up to now (the server lifts +it to the registry recency). Repeated interactions in an already-engaged, read +chat send nothing further. + +## Where + +- `lib/features/chat/ui/sessions/chat_seen_focus.dart`: window focus from the + framework lifecycle (`resumed` = focused). +- `lib/features/chat/ui/sessions/chat_sessions_controller.dart`: + `reportInteraction`, the engagement set (cleared on focus loss or when the + open chat changes), and the passive/active split in the frame path. A reply + waiting in its quiet period is tracked (`_pendingAckId`); focus loss or a + chat change cancels that wait and marks the reply New (`_cancelPendingActiveAck`) + instead of letting the timer drop it silently. +- `lib/features/chat/conversation/chat_seen_interaction.dart`: the region + wrapped around each open conversation pane. +- `lib/features/chat/chat_pane_content.dart`: wraps the pane. +- `lib/features/chat/ui/sessions/chat_sessions_screen.dart`: removed the + passive mark-read on rebuild and restore. +- `lib/features/settings/server_connections.dart` and + `lib/application/pipelines_app.dart`: the notification-open intent. + +No server or web change: the server is untouched and still clears app +notifications on the watermark. + +## Tests (focused) + +- `test/features/chat/ui/sessions/chat_seen_interaction_test.dart` (15 tests): + passive cases (unfocused reply, restored layout, idle open chat, + background then refocus, reply in another chat, reply after leaving an + engaged chat, interaction while unfocused, a reply still in its quiet period + when focus is lost or another chat is opened, and the restored layout through + `ChatSessionsScreen`) and interaction cases (interaction in an unread open + chat, opening from the list, reply after an interaction, repeated + interactions, interaction in a non-open chat). +- `test/features/chat/conversation/chat_seen_interaction_test.dart` (9 tests): + showing the pane, programmatic scroll, and code-driven focus into the pane + report nothing; click, user drag, mouse wheel, key press, Tab from outside + into the pane, and notification open each report. +- Last run: the two focused files above, 24 passed, 0 failed (memwatch PASS, + peak 943 MB, names only the two intended paths). `tool/analyze.sh`: clean. +- Existing suites that touch the list, controller or server connections + (`chat_seen_sync_test`, `chat_active_session_test`, `chat_active_selection_test`, + `chat_sessions_screen_test`, `chat_sessions_lifecycle_test`, + `chat_sessions_activity_test`, `chat_new_session_controller_test`, + `chat_runtime_test`, `chat_floating_pane_test`, `chat_windows_test`, + `chat_color_test`, `chat_star_optimistic_test`, `chat_state_legibility_test`, + `chat_visibility_marker_test`, `chat_add_pane_picker_test`, + `chat_session_local_state_test`, `server_connections_recovery_test`) pass + unchanged. No expectation was edited. + +## Limitations + +- Focus is `resumed` only. On web a backgrounded tab reports `hidden` and + should count as unfocused; an unfocused window with no lifecycle change is + not detected there. Verify on the device or in the browser. +- Only the chat-question notification path (`ChatQuestionNotices`) is wired as + a notification open. Run-level notifications do not name a chat. +- Interactions are reported at the pane level. A chat in a floating window + uses the same pane content, so it is covered, but this was not exercised on + a device. +- No browser or device capture was taken (ui-review owns that). diff --git a/app/test/features/chat/conversation/chat_seen_interaction_test.dart b/app/test/features/chat/conversation/chat_seen_interaction_test.dart new file mode 100644 index 00000000..69410d10 --- /dev/null +++ b/app/test/features/chat/conversation/chat_seen_interaction_test.dart @@ -0,0 +1,220 @@ +import 'package:flutter/gestures.dart'; +import 'package:flutter/material.dart'; +import 'package:flutter/services.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/servers/server_catalog.dart'; +import 'package:pipelines_app/core/servers/server_catalog_store.dart'; +import 'package:pipelines_app/core/servers/server_context.dart'; +import 'package:pipelines_app/features/chat/conversation/chat_seen_interaction.dart'; +import 'package:pipelines_app/features/settings/server_connections.dart'; + +/// One open chat's pane: a field and a long transcript, both inside the region. +Widget _pane({ + required VoidCallback onInteract, + ScrollController? scroll, + FocusNode? focus, +}) => MaterialApp( + home: Scaffold( + body: ChatSeenInteraction( + sessionId: 'ses_a', + onInteract: onInteract, + child: Column( + children: [ + TextField(focusNode: focus), + Expanded( + child: ListView.builder( + controller: scroll, + itemCount: 200, + itemBuilder: (context, index) => + SizedBox(height: 40, child: Text('row $index')), + ), + ), + ], + ), + ), + ), +); + +void main() { + testWidgets('showing the pane reports nothing', (tester) async { + var count = 0; + await tester.pumpWidget(_pane(onInteract: () => count++)); + await tester.pump(); + await tester.pump(const Duration(seconds: 2)); + + expect(count, 0); + }); + + testWidgets('a programmatic scroll reports nothing', (tester) async { + var count = 0; + final scroll = ScrollController(); + addTearDown(scroll.dispose); + await tester.pumpWidget(_pane(onInteract: () => count++, scroll: scroll)); + + scroll.jumpTo(600); + await tester.pump(); + + expect(count, 0); + }); + + testWidgets('a click or tap in the pane reports once per press', ( + tester, + ) async { + var count = 0; + await tester.pumpWidget(_pane(onInteract: () => count++)); + + await tester.tap(find.text('row 3')); + await tester.pump(); + + expect(count, greaterThanOrEqualTo(1)); + }); + + testWidgets('a user drag of the transcript reports', (tester) async { + var count = 0; + await tester.pumpWidget(_pane(onInteract: () => count++)); + + await tester.drag(find.text('row 0'), const Offset(0, -300)); + await tester.pumpAndSettle(); + + expect(count, greaterThanOrEqualTo(1)); + }); + + testWidgets('a mouse-wheel scroll of the transcript reports', (tester) async { + var count = 0; + final scroll = ScrollController(); + addTearDown(scroll.dispose); + await tester.pumpWidget(_pane(onInteract: () => count++, scroll: scroll)); + + final pointer = TestPointer(1, PointerDeviceKind.mouse); + await tester.sendEventToBinding( + pointer.hover(tester.getCenter(find.text('row 0'))), + ); + await tester.sendEventToBinding(pointer.scroll(const Offset(0, 200))); + await tester.pumpAndSettle(); + + expect(scroll.offset, greaterThan(0)); + expect(count, greaterThanOrEqualTo(1)); + }); + + testWidgets('a key press while focus is in the pane reports, with no click', ( + tester, + ) async { + var count = 0; + final focus = FocusNode(); + addTearDown(focus.dispose); + await tester.pumpWidget(_pane(onInteract: () => count++, focus: focus)); + + await tester.sendKeyEvent(LogicalKeyboardKey.keyA); + await tester.pump(); + expect(count, 0, reason: 'a key with no focus in the pane is not its input'); + + focus.requestFocus(); + await tester.pump(); + await tester.sendKeyEvent(LogicalKeyboardKey.keyA); + await tester.pump(); + + expect(count, 1); + }); + + testWidgets('code-driven focus into the pane reports nothing', (tester) async { + var count = 0; + final focus = FocusNode(); + addTearDown(focus.dispose); + await tester.pumpWidget(_pane(onInteract: () => count++, focus: focus)); + + focus.requestFocus(); + await tester.pump(); + await tester.pump(const Duration(seconds: 1)); + + expect(focus.hasFocus, isTrue); + expect(count, 0, reason: 'focus moved in code, with no key press, is passive'); + }); + + testWidgets('Tab from outside the pane into it reports once', (tester) async { + var count = 0; + final outside = FocusNode(); + final focus = FocusNode(); + addTearDown(outside.dispose); + addTearDown(focus.dispose); + await tester.pumpWidget( + MaterialApp( + home: Scaffold( + body: Column( + children: [ + TextField(focusNode: outside), + Expanded( + child: ChatSeenInteraction( + sessionId: 'ses_a', + onInteract: () => count++, + child: Column( + children: [ + TextField(focusNode: focus), + const Expanded(child: SizedBox()), + ], + ), + ), + ), + ], + ), + ), + ), + ); + outside.requestFocus(); + await tester.pump(); + + await tester.sendKeyEvent(LogicalKeyboardKey.tab); + await tester.pump(); + + expect(focus.hasFocus, isTrue, reason: 'Tab moved focus into the pane'); + expect(count, 1); + }); + + testWidgets('a notification tap that opened this chat reports once', ( + tester, + ) async { + var count = 0; + final connections = ServerConnections( + store: MemoryServerCatalogStore( + catalog: ServerCatalog( + servers: [ + SavedServer.validated( + id: 'mac', + name: 'Mac', + endpoints: const ['ws://mac.test/connect'], + ), + ], + selectedId: 'mac', + ), + ), + onSelected: (_) async {}, + ); + addTearDown(connections.dispose); + await connections.load(); + await tester.pumpWidget( + ServerContext( + connections: connections, + serverId: 'mac', + child: _pane(onInteract: () => count++), + ), + ); + await tester.pump(); + expect(count, 0); + + // Another chat's notification is not this pane's open. + connections.requestChatOpen('ses_other'); + await tester.pump(); + await tester.pump(); + expect(count, 0); + + connections.requestChatOpen('ses_a'); + await tester.pump(); + await tester.pump(); + expect(count, 1); + + // The tap is consumed: a later rebuild does not report it again. + connections.requestChatOpen('ses_other'); + await tester.pump(); + await tester.pump(); + expect(count, 1); + }); +} diff --git a/app/test/features/chat/ui/sessions/chat_seen_interaction_test.dart b/app/test/features/chat/ui/sessions/chat_seen_interaction_test.dart new file mode 100644 index 00000000..e22ab491 --- /dev/null +++ b/app/test/features/chat/ui/sessions/chat_seen_interaction_test.dart @@ -0,0 +1,376 @@ +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/attention/runtime/attention_ack_queue.dart'; +import 'package:pipelines_app/features/attention/runtime/attention_ack_sync.dart'; +import 'package:pipelines_app/features/chat/data/chat_repository.dart'; +import 'package:pipelines_app/features/chat/ui/sessions/chat_seen_focus.dart'; +import 'package:pipelines_app/features/chat/ui/sessions/chat_sessions_controller.dart'; +import 'package:pipelines_app/features/chat/ui/sessions/chat_sessions_screen.dart'; + +import '../../../attention/runtime/fake_ack_server.dart'; +import 'chat_test_harness.dart'; + +/// A chat reply in [id], as the server pushes it while the chat is live. +JsonMap _reply(String id) => { + 'type': 'chat_event', + 'chat_event': {'session_id': id, 'kind': 'text', 'delta': 'hello'}, +}; + +/// One device's chat list, its shared acknowledgements and its window focus. +class _Device { + _Device(this.server, {required this.clock, bool focused = true}) + : client = server.connect(), + local = MemoryChatSessionLocalStore(), + focus = ChatSeenFocus(focused: focused) { + sync = AttentionAckSync(gateway: client, queue: MemoryAttentionAckQueue()); + bindAttentionAckSync(client, sync); + list = ChatSessionsController( + ChatRepository(client), + localStore: local, + nowMillis: () => clock(), + seenFocus: focus, + // Short enough to test quiet periods, long enough to settle under load. + activeAckDelay: const Duration(milliseconds: 60), + ); + } + + final FakeAckServer server; + final FakeAckClient client; + final MemoryChatSessionLocalStore local; + final ChatSeenFocus focus; + final int Function() clock; + late final AttentionAckSync sync; + late final ChatSessionsController list; + + Future start() async { + await sync.connected(); + await list.refresh(); + await settle(); + } + + JsonMap row(String id) => list.sessions.firstWhere((row) => row['id'] == id); + + /// Whether [id] shows a New badge in the list (an open chat never does). + bool isNew(String id) => list.isUnseen(row(id)); + + /// Whether this device holds [id] as unread, whether or not it is open. + bool holdsUnread(String id) => local.state?.isUnseen(id) ?? false; + + void dispose() { + list.dispose(); + sync.dispose(); + focus.dispose(); + } +} + +/// Lets a pending quiet-period acknowledgement fire (60 ms here) and settle. +Future quietPeriod() async { + await Future.delayed(const Duration(milliseconds: 200)); + await settle(); +} + +void main() { + late FakeAckServer server; + var now = 5000; + + setUp(() { + now = 5000; + server = FakeAckServer() + ..chatSessions = [ + {'id': 'ses_a', 'title': 'A', 'directory': '/w', 'updated_at': 1000}, + {'id': 'ses_b', 'title': 'B', 'directory': '/w', 'updated_at': 1000}, + ]; + }); + + void pushToAll(JsonMap frame) { + for (final client in server.clients) { + client.pushed.add(frame); + } + } + + group('passive states never mark a chat seen', () { + test('a reply in an unfocused window stays New', () async { + final device = _Device(server, clock: () => now, focused: false); + addTearDown(device.dispose); + await device.start(); + // Restored as the open chat, then the window is in the background. + device.list.activeSessionId = 'ses_a'; + pushToAll(_reply('ses_a')); + await quietPeriod(); + + expect(server.state.chatSeen, isEmpty); + expect(device.holdsUnread('ses_a'), isTrue); + device.list.activeSessionId = null; + expect(device.isNew('ses_a'), isTrue); + }); + + test('a restored open chat with no interaction stays New', () async { + final device = _Device(server, clock: () => now); + addTearDown(device.dispose); + await device.start(); + // A layout restored on start sets the open chat without any open. + device.list.activeSessionId = 'ses_a'; + await settle(); + + pushToAll(_reply('ses_a')); + await quietPeriod(); + + expect(server.state.chatSeen, isEmpty); + expect(device.holdsUnread('ses_a'), isTrue); + }); + + testWidgets( + 'a layout restored with a chat open, then a reply, leaves it New', + (tester) async { + final device = _Device(server, clock: () => now); + addTearDown(device.dispose); + await tester.runAsync(device.start); + // The list screen is shown with the restored chat as its open conversation. + await tester.pumpWidget( + MaterialApp( + home: ChatSessionsScreen( + gateway: device.client, + onOpen: (_) {}, + controller: device.list, + activeSessionId: 'ses_a', + localStore: device.local, + ), + ), + ); + await tester.runAsync( + () => Future.delayed(const Duration(milliseconds: 20)), + ); + await tester.pump(); + + await tester.runAsync(() async { + pushToAll(_reply('ses_a')); + await quietPeriod(); + }); + await tester.pump(); + + expect(server.state.chatSeen, isEmpty); + expect(device.holdsUnread('ses_a'), isTrue); + }, + ); + + test('an open chat left idle long after a reply stays New', () async { + final device = _Device(server, clock: () => now); + addTearDown(device.dispose); + await device.start(); + device.list.activeSessionId = 'ses_a'; + await settle(); + + pushToAll(_reply('ses_a')); + now += 600000; // Ten minutes later, nothing touched it. + await quietPeriod(); + + expect(server.state.chatSeen, isEmpty); + expect(device.holdsUnread('ses_a'), isTrue); + }); + + test('a reply after backgrounding an engaged chat stays New, even ' + 'once the window is focused again without interaction', () async { + final device = _Device(server, clock: () => now); + addTearDown(device.dispose); + await device.start(); + device.list.activeSessionId = 'ses_a'; + device.list.reportInteraction('ses_a'); + await settle(); + expect(server.state.chatSeen['ses_a'], 5000); + + device.focus.focused = false; + now = 6000; + pushToAll(_reply('ses_a')); + await quietPeriod(); + expect(server.state.chatSeen['ses_a'], 5000); + + device.focus.focused = true; + now = 7000; + pushToAll(_reply('ses_a')); + await quietPeriod(); + expect(server.state.chatSeen['ses_a'], 5000); + expect(device.holdsUnread('ses_a'), isTrue); + }); + + test('a reply in another chat while this one is open stays New', () async { + final device = _Device(server, clock: () => now); + addTearDown(device.dispose); + await device.start(); + device.list.activeSessionId = 'ses_a'; + device.list.reportInteraction('ses_a'); + await settle(); + + now = 6000; + pushToAll(_reply('ses_b')); + await quietPeriod(); + + expect(server.state.chatSeen.containsKey('ses_b'), isFalse); + expect(device.isNew('ses_b'), isTrue); + }); + + test('a reply after leaving an engaged chat stays New', () async { + final device = _Device(server, clock: () => now); + addTearDown(device.dispose); + await device.start(); + device.list.activeSessionId = 'ses_a'; + device.list.reportInteraction('ses_a'); + await settle(); + + device.list.activeSessionId = 'ses_b'; + now = 6000; + pushToAll(_reply('ses_a')); + await quietPeriod(); + + expect(server.state.chatSeen['ses_a'], 5000); + expect(device.isNew('ses_a'), isTrue); + }); + + test('a reply still in its quiet period when the window loses focus ' + 'stays New, not seen', () async { + final device = _Device(server, clock: () => now); + addTearDown(device.dispose); + await device.start(); + device.list.activeSessionId = 'ses_a'; + device.list.reportInteraction('ses_a'); + await settle(); + expect(server.state.chatSeen['ses_a'], 5000); + + now = 6000; + pushToAll(_reply('ses_a')); + await settle(); // The reply is held in its quiet period, not yet acked. + device.focus.focused = false; + await quietPeriod(); + + expect(server.state.chatSeen['ses_a'], 5000); + expect(device.holdsUnread('ses_a'), isTrue); + }); + + test('a reply still in its quiet period when the user opens another ' + 'chat stays New, not seen', () async { + final device = _Device(server, clock: () => now); + addTearDown(device.dispose); + await device.start(); + device.list.activeSessionId = 'ses_a'; + device.list.reportInteraction('ses_a'); + await settle(); + + now = 6000; + pushToAll(_reply('ses_a')); + await settle(); + device.list.activeSessionId = 'ses_b'; + await quietPeriod(); + + expect(server.state.chatSeen['ses_a'], 5000); + expect(device.isNew('ses_a'), isTrue); + }); + + test('an interaction while the window is unfocused is ignored', () async { + final device = _Device(server, clock: () => now, focused: false); + addTearDown(device.dispose); + await device.start(); + device.list.activeSessionId = 'ses_a'; + + device.list.reportInteraction('ses_a'); + await quietPeriod(); + + expect(server.state.chatSeen, isEmpty); + }); + }); + + group('user interactions mark the chat seen', () { + test( + 'an interaction in an unread open chat marks it seen up to now', + () async { + final device = _Device(server, clock: () => now); + addTearDown(device.dispose); + await device.start(); + device.list.activeSessionId = 'ses_a'; + pushToAll(_reply('ses_a')); + await settle(); + expect(device.holdsUnread('ses_a'), isTrue); + + now = 6000; + device.list.reportInteraction('ses_a'); + await settle(); + + expect(server.state.chatSeen['ses_a'], 6000); + expect(device.holdsUnread('ses_a'), isFalse); + expect(device.sync.pending.chatSeen, isEmpty); + }, + ); + + test('opening a chat from the list marks it seen', () async { + final device = _Device(server, clock: () => now); + addTearDown(device.dispose); + await device.start(); + pushToAll(_reply('ses_a')); + await settle(); + + now = 6000; + await device.list.markOpened(device.row('ses_a')); + await settle(); + + expect(server.state.chatSeen['ses_a'], 6000); + expect(device.holdsUnread('ses_a'), isFalse); + }); + + test( + 'a reply after an interaction is marked seen once the chat is quiet', + () async { + final device = _Device(server, clock: () => now); + addTearDown(device.dispose); + await device.start(); + device.list.activeSessionId = 'ses_a'; + device.list.reportInteraction('ses_a'); + await settle(); + + now = 6000; + pushToAll(_reply('ses_a')); + await quietPeriod(); + + expect(server.state.chatSeen['ses_a'], 6000); + expect(device.holdsUnread('ses_a'), isFalse); + }, + ); + + test( + 'repeated interactions in an engaged, read chat send nothing more', + () async { + final device = _Device(server, clock: () => now); + addTearDown(device.dispose); + await device.start(); + device.list.activeSessionId = 'ses_a'; + device.list.reportInteraction('ses_a'); + await settle(); + final sent = device.client.count('ack_attention'); + + // Scroll ticks and clicks after the first engagement. + for (var i = 0; i < 5; i++) { + device.list.reportInteraction('ses_a'); + } + await settle(); + + expect(device.client.count('ack_attention'), sent); + }, + ); + + test('an interaction in a visible chat that is not the open one marks it ' + 'seen', () async { + final device = _Device(server, clock: () => now); + addTearDown(device.dispose); + await device.start(); + device.list.activeSessionId = 'ses_a'; + pushToAll(_reply('ses_b')); + await settle(); + expect(device.holdsUnread('ses_b'), isTrue); + + now = 6000; + device.list.reportInteraction('ses_b'); + await settle(); + + expect(server.state.chatSeen['ses_b'], 6000); + expect(device.holdsUnread('ses_b'), isFalse); + }); + }); +}