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.
This commit is contained in:
2026-11-12 02:25:09 +00:00
parent e4f3ebdcab
commit 746e23788d
10 changed files with 1013 additions and 65 deletions
@@ -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).