Files
pipelines/app/notes/chat-seen-only-after-interaction.md
T
alan ae5e00326c Keep unengaged open chats unread
Update the live-chat regression and note to reflect that replies received while a chat is merely open are not acknowledged as seen. This preserves phone notifications until the user actually interacts with the chat.
2026-11-12 03:21:38 +00:00

111 lines
6.8 KiB
Markdown

# 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, except one expectation (below).
- Land-gate fix: `test/features/chat/ui/sessions/chat_sessions_live_new_test.dart`
"a tool call and reply in the open chat stay read on leaving" failed in the
full `test/features test/shell test/ui test/core` run. The chat was open with
no user interaction, so under the new rule the reply is not seen. The test
was renamed to "...stay New on leaving without interaction" and now expects
the `chat-row-unread` dot and `isUnseen('s1')` after the chat is left. Its
open-chat assertion (no dot while open) is unchanged. This is the one
behaviour change the task asked for; no other expectation changed.
- Focused rerun after that fix: `chat_sessions_live_new_test.dart`,
`conversation/chat_seen_interaction_test.dart`,
`ui/sessions/chat_seen_interaction_test.dart`: 34 passed, 0 failed (memwatch
PASS, peak 1182 MB, names only those three paths). `tool/analyze.sh`: clean.
## 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).