feat(web): rank chat mentions by recency (#3099)
This commit is contained in:
@@ -11,7 +11,7 @@ owners:
|
||||
|
||||
## Purpose
|
||||
|
||||
The UI system owns web presentation behavior for desktop and mobile surfaces.
|
||||
The UI system owns web presentation.
|
||||
|
||||
## Ownership
|
||||
|
||||
@@ -19,8 +19,8 @@ This system owns navigation, settings, boards, task/review surfaces,
|
||||
walkthroughs, chat controls, visual feedback, and responsive interaction
|
||||
contracts without backend-state ownership.
|
||||
|
||||
Controls that configure or display provider/task state remain owned by that
|
||||
system. The UI system owns only independent, reusable presentation contracts.
|
||||
Controls for provider/task state remain owned by that system.
|
||||
The UI system owns reusable contracts.
|
||||
|
||||
## Exclusions
|
||||
|
||||
@@ -55,6 +55,7 @@ system. The UI system owns only independent, reusable presentation contracts.
|
||||
- [Command-panel Sidebar Task Reveal](requirements/command-panel-sidebar-task-reveal.md)
|
||||
- [Compact Workflow Step Navigation](requirements/compact-workflow-step-navigation.md)
|
||||
- [Comment Markdown Rendering](requirements/comment-markdown.md)
|
||||
- [Mention recency](requirements/composer-mention-recency.md)
|
||||
- [Composer Suggestion Overlays](requirements/composer-suggestion-overlays.md)
|
||||
- [Context Compaction Count](requirements/context-compaction-count.md)
|
||||
- [Context Window Reset Freshness](requirements/context-window-reset-freshness.md)
|
||||
@@ -151,6 +152,7 @@ system. The UI system owns only independent, reusable presentation contracts.
|
||||
- [Agent Todo List Panel](system-design/agent-todo-list-panel.md)
|
||||
- [App Status Bar](system-design/app-status-bar.md)
|
||||
- [Changes File Row Containment](system-design/changes-file-row-containment.md)
|
||||
- [Mention recency](system-design/composer-mention-recency.md)
|
||||
- [Composer Suggestion Overlays](system-design/composer-suggestion-overlays.md)
|
||||
- [Compact Workflow Step Navigation](system-design/compact-workflow-step-navigation.md)
|
||||
- [Per-workflow column visibility on the kanban board System Design Part 1](system-design/board-step-visibility-filter-01.md)
|
||||
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
status: active
|
||||
system: ui
|
||||
created: 2026-08-27
|
||||
owners:
|
||||
- web
|
||||
---
|
||||
|
||||
# Composer Mention Recency Requirements
|
||||
|
||||
## Overview
|
||||
|
||||
Chat composers show tasks, saved prompts, files, and the Plan action in one
|
||||
`@` suggestion menu. The current menu ranks matches by text only. Users who
|
||||
mention the same items repeatedly must find them again for each message.
|
||||
|
||||
The UI system owns this behavior because the selection history is local
|
||||
presentation state. The task, settings, and workspace-file systems continue to
|
||||
own the available candidates.
|
||||
|
||||
## Terminology
|
||||
|
||||
- **Mention candidate:** A task, saved prompt, or file that the current chat
|
||||
composer can show in its `@` suggestion menu.
|
||||
- **Recent selection:** A mention candidate that the user selected from a chat
|
||||
composer on the current device.
|
||||
- **Baseline rank:** The existing text-match score and stable source order.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-UI-COMPOSER-MENTION-RECENCY-001: Rank chat mentions by recent selection
|
||||
|
||||
**Intent:** Make repeated mentions faster without changing candidate sources or
|
||||
the menu interaction.
|
||||
|
||||
**User story:** As a user, I want recent task, prompt, and file selections first,
|
||||
so that I can reuse them with less navigation.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-UI-COMPOSER-MENTION-RECENCY-001.1:** When the `@` menu contains recent
|
||||
and unselected mention candidates, the menu shall show recent candidates
|
||||
before unselected candidates.
|
||||
- **AC-UI-COMPOSER-MENTION-RECENCY-001.2:** When two recent candidates are
|
||||
available, the menu shall show the most recently selected candidate first.
|
||||
Text-match quality shall rank candidates only after selection recency.
|
||||
- **AC-UI-COMPOSER-MENTION-RECENCY-001.3:** When two unselected candidates have
|
||||
different text-match quality, the menu shall preserve the existing text
|
||||
ranking. Equal candidates shall preserve the existing stable source order.
|
||||
- **AC-UI-COMPOSER-MENTION-RECENCY-001.4:** When the user selects a task, prompt,
|
||||
or file by pointer, touch, Enter, or Tab, it shall become the newest recent
|
||||
selection. Selecting it again shall move it to the front.
|
||||
- **AC-UI-COMPOSER-MENTION-RECENCY-001.5:** When recency changes other results,
|
||||
the Plan action shall keep the position that the baseline rank assigned for
|
||||
the current query. The Plan action shall not enter selection history.
|
||||
- **AC-UI-COMPOSER-MENTION-RECENCY-001.6:** When the user reloads Kandev on the
|
||||
same device, the bounded selection history shall continue to rank chat
|
||||
suggestions. A missing, malformed, or unavailable history shall restore the
|
||||
baseline rank without blocking selection.
|
||||
- **AC-UI-COMPOSER-MENTION-RECENCY-001.7:** Task and saved-prompt identities
|
||||
shall use their stable IDs. File identities shall include the workspace, so
|
||||
equal paths in different workspaces do not share recency.
|
||||
- **AC-UI-COMPOSER-MENTION-RECENCY-001.8:** Task chat, Quick Chat, and
|
||||
passthrough chat shall use the same ranking on desktop and phone. The current
|
||||
popup, keyboard navigation, focus, insertion, and touch behavior shall not
|
||||
change.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Changing task, saved-prompt, or workspace-file search sources and limits.
|
||||
- Showing a recent file that the current file search did not return.
|
||||
- Applying recency to task creation, agent launch, `#` references, or `/`
|
||||
commands.
|
||||
- Server storage, user sync, device sync, frequency scoring, or time decay.
|
||||
- Adding a recent label, group, setting, clear action, or other menu copy.
|
||||
@@ -0,0 +1,139 @@
|
||||
---
|
||||
status: current
|
||||
system: ui
|
||||
created: 2026-08-27
|
||||
requirements:
|
||||
- REQ-UI-COMPOSER-MENTION-RECENCY-001
|
||||
---
|
||||
|
||||
# Composer Mention Recency System Design
|
||||
|
||||
## Purpose and boundaries
|
||||
|
||||
This design adds device-local selection recency to the chat composer `@` menu.
|
||||
It does not change the candidate sources or their search limits.
|
||||
|
||||
The chat composer receives tasks from the Kanban store, prompts from settings,
|
||||
and files from `workspace.files.search`. The UI system ranks these candidates
|
||||
after each source returns them.
|
||||
|
||||
## Requirement mapping
|
||||
|
||||
| Requirement | Design section |
|
||||
| --- | --- |
|
||||
| `REQ-UI-COMPOSER-MENTION-RECENCY-001` | [Ranking](#ranking), [Selection flow](#selection-flow), [Persistence](#persistence), [Responsive behavior](#responsive-behavior) |
|
||||
|
||||
## Components and responsibilities
|
||||
|
||||
- A new `apps/web/lib/chat-mention-recency.ts` module owns storage parsing,
|
||||
bounded MRU updates, candidate identity, and deterministic ranking.
|
||||
- `useMentionItems` in `apps/web/components/task/chat/tiptap-input.tsx` keeps
|
||||
candidate loading in its current order. It applies the shared rank after task,
|
||||
Plan, prompt, and file candidates are available.
|
||||
- `createMentionSuggestion` in
|
||||
`apps/web/components/task/chat/tiptap-suggestion.tsx` records a selection in
|
||||
the same command path for pointer, touch, Enter, and Tab.
|
||||
- `MentionMenu` and `PopupMenu` keep their current rendering, focus, geometry,
|
||||
accessibility, and selected-index behavior.
|
||||
|
||||
## Data and contracts
|
||||
|
||||
The browser key is `kandev.chatMentionRecency.v1`. Its value is a JSON array in
|
||||
newest-first order. The module limits the normalized array to 50 unique entries.
|
||||
|
||||
Each entry has this shape:
|
||||
|
||||
```ts
|
||||
type ChatMentionRecentEntry = {
|
||||
kind: "task" | "prompt" | "file";
|
||||
id: string;
|
||||
workspaceId?: string;
|
||||
};
|
||||
```
|
||||
|
||||
Task and prompt entries use their stable IDs. File entries require the active
|
||||
workspace ID and use the returned path as `id`. The module rejects unknown
|
||||
kinds, empty IDs, and file entries without a workspace ID. It removes duplicate
|
||||
identities and keeps the newest valid entry.
|
||||
|
||||
The stored data contains no task title or prompt content. File entries contain
|
||||
the path that is necessary to match a later file result.
|
||||
|
||||
## Ranking
|
||||
|
||||
The rank function accepts the candidates, query, workspace ID, and normalized
|
||||
MRU entries. It uses this sequence:
|
||||
|
||||
1. Apply the existing text filter and score to create the baseline rank.
|
||||
2. Record the Plan action's index in that baseline rank, then remove the action.
|
||||
3. Put known MRU candidates before candidates that are not in the MRU list.
|
||||
4. For known candidates, use the newest-first MRU index.
|
||||
5. Use the existing text score after recency.
|
||||
6. Use the baseline index as the final stable tie-breaker.
|
||||
7. Insert the Plan action at its recorded baseline index.
|
||||
|
||||
If the MRU list is empty, this process returns the exact baseline order. A
|
||||
candidate outside the current source results does not enter the menu.
|
||||
|
||||
## Selection flow
|
||||
|
||||
1. The user enters an `@` query in a chat composer.
|
||||
2. `useMentionItems` collects current tasks, Plan, saved prompts, and file search
|
||||
results.
|
||||
3. The rank module reads and normalizes the current device history.
|
||||
4. The composer shows the ranked candidates and selects index zero.
|
||||
5. The user selects one candidate with pointer, touch, Enter, or Tab.
|
||||
6. The TipTap command inserts the mention by using the existing behavior.
|
||||
7. The selection callback moves the candidate identity to the MRU front.
|
||||
|
||||
The callback does not record Plan. It records each successful command path once.
|
||||
The next query or menu open reads the updated list.
|
||||
|
||||
## Failure and recovery
|
||||
|
||||
- If browser storage is unavailable, reads return an empty history and writes do
|
||||
nothing. Mention insertion continues.
|
||||
- If JSON parsing or entry validation fails, the module ignores invalid data and
|
||||
ranks with the remaining valid entries.
|
||||
- If a stored candidate no longer exists, it has no rank effect. New selections
|
||||
remove stale entries through the fixed limit.
|
||||
- If the workspace ID is unavailable, file candidates use baseline rank and file
|
||||
selections do not enter history. Tasks and prompts continue to use recency.
|
||||
|
||||
## Persistence
|
||||
|
||||
The browser owns the MRU list in `localStorage`. No backend API, database
|
||||
migration, Zustand slice, boot payload, or WebSocket event changes.
|
||||
|
||||
MRU order defines recency. The design does not use wall-clock timestamps,
|
||||
frequency counters, or decay. Clearing browser data resets the ranking.
|
||||
|
||||
## Responsive behavior
|
||||
|
||||
Desktop and phone use the same `TipTapInput`, rank function, and selection
|
||||
callback. The current contextual popup remains the presentation on both
|
||||
viewports.
|
||||
|
||||
This change does not add a surface, scroll owner, touch control, or breakpoint.
|
||||
`PopupMenu` remains the nearest shipped mobile exemplar. Existing viewport
|
||||
containment, 44-pixel rows, touch selection, and focus behavior remain valid.
|
||||
|
||||
A desktop E2E proves selection, primary recency rank, and reload persistence. A
|
||||
phone E2E proves the same rank after touch selection in the existing popup.
|
||||
|
||||
## Security
|
||||
|
||||
The history remains inside the Kandev browser origin. The module stores only
|
||||
candidate identities and file paths. It does not store prompt content, task
|
||||
titles, queries, or message text.
|
||||
|
||||
## Observability
|
||||
|
||||
No production telemetry is added. Unit tests cover storage recovery, scope,
|
||||
bounded updates, ranking priority, stable ties, and Plan position. Browser tests
|
||||
cover the user-visible desktop and phone flows.
|
||||
|
||||
## Related decisions
|
||||
|
||||
None. The requirement and this design preserve the local ranking choice. The
|
||||
feature does not create a cross-system architecture boundary.
|
||||
Reference in New Issue
Block a user