From a8a2a571328ce8a1d6b98743428b6511be1bd5a2 Mon Sep 17 00:00:00 2001
From: Paul Lizer <paullizer@microsoft.com>
Date: Wed, 19 Aug 2026 11:51:34 -0400
Subject: [PATCH] Accept collaborative @ mentions with Tab

In multi-user conversations the chat composer's @ mention menu only accepted
the highlighted suggestion on Enter. Tab fell through to the browser default,
moving focus out of the message box and leaving the half-typed @name behind.
The agent-instruction mention menu already treated Tab and Enter the same way,
so the chat composer was the odd one out.

Extract the inline Enter selection logic into selectActiveMentionSuggestion()
so every accept key routes through one implementation of the participant tag,
ai_tag invocation target, and invite-confirmation branches, then add a Tab
branch that reuses it. Shift+Tab and the empty-results state are deliberately
left unhandled so normal focus movement still works, and the Enter guard is
unchanged.

Also fix the listbox semantics in the same code path: suggestions are now real
options with stable ids and aria-selected, and the composer references the
highlighted option via aria-activedescendant paired with aria-controls, which
ARIA 1.2 requires because the menu is a sibling of the textarea rather than a
descendant. Those attributes are applied only while the menu is open. The
highlighted option is scrolled into view inside the height-capped menu.

Fixes #1299

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 application/single_app/config.py              |   2 +-
 .../static/js/chat/chat-collaboration.js      | 122 ++++++++--
 ...LABORATION_MENTION_TAB_AUTOCOMPLETE_FIX.md |  80 +++++++
 docs/explanation/fixes/index.md               |   1 +
 docs/explanation/release_notes.md             |  16 ++
 ..._collaboration_mention_tab_autocomplete.py | 225 ++++++++++++++++++
 ...hat_collaboration_mention_tab_selection.py | 211 ++++++++++++++++
 7 files changed, 639 insertions(+), 18 deletions(-)
 create mode 100644 docs/explanation/fixes/COLLABORATION_MENTION_TAB_AUTOCOMPLETE_FIX.md
 create mode 100644 functional_tests/test_collaboration_mention_tab_autocomplete.py
 create mode 100644 ui_tests/test_chat_collaboration_mention_tab_selection.py

diff --git a/application/single_app/config.py b/application/single_app/config.py
index e3f9a3646..7a4b93be9 100644
--- a/application/single_app/config.py
+++ b/application/single_app/config.py
@@ -96,7 +96,7 @@
 EXECUTOR_TYPE = 'thread'
 EXECUTOR_MAX_WORKERS = 30
 SESSION_TYPE = 'filesystem'
-VERSION = "0.260.003"
+VERSION = "0.260.004"
 IS_DEVELOPMENT = is_development_env_enabled()
 
 SESSION_COOKIE_SAMESITE = os.getenv('SESSION_COOKIE_SAMESITE', 'Lax')
diff --git a/application/single_app/static/js/chat/chat-collaboration.js b/application/single_app/static/js/chat/chat-collaboration.js
index c6bcbfe4a..b0af42d42 100644
--- a/application/single_app/static/js/chat/chat-collaboration.js
+++ b/application/single_app/static/js/chat/chat-collaboration.js
@@ -24,6 +24,7 @@ const RECENT_COLLABORATORS_KEY = 'recentCollaborators';
 const MAX_RECENT_COLLABORATORS = 12;
 const DEFAULT_SUGGESTION_LIMIT = 8;
 const SEARCH_HIGHLIGHT_MAX_AGE_MS = 30000;
+const MENTION_OPTION_ID_PREFIX = 'collaboration-mention-option-';
 
 const mentionMenu = document.getElementById('collaboration-mention-menu');
 const participantModalEl = document.getElementById('collaboration-participant-modal');
@@ -1509,7 +1510,32 @@ function buildSuggestionItemHtml(suggestion) {
     `;
 }
 
+function applyMentionComboboxState(activeItemId) {
+    if (!userInput || !mentionMenu) {
+        return;
+    }
+
+    // ARIA 1.2 lets a focused textbox point aria-activedescendant at a descendant
+    // of the element named by aria-controls, which is how the composer announces
+    // the highlighted suggestion without moving focus out of the message box.
+    userInput.setAttribute('aria-controls', mentionMenu.id);
+    userInput.setAttribute('aria-autocomplete', 'list');
+    userInput.setAttribute('aria-activedescendant', activeItemId);
+}
+
+function clearMentionComboboxState() {
+    if (!userInput) {
+        return;
+    }
+
+    userInput.removeAttribute('aria-activedescendant');
+    userInput.removeAttribute('aria-autocomplete');
+    userInput.removeAttribute('aria-controls');
+}
+
 function hideMentionMenu() {
+    clearMentionComboboxState();
+
     if (!mentionMenu) {
         return;
     }
@@ -1525,13 +1551,14 @@ function renderMentionMenu(results, mentionState) {
     }
 
     if (!Array.isArray(results) || results.length === 0) {
-        mentionMenu.innerHTML = '<div class="list-group-item text-muted small">No matching participants, agents, models, or collaborators found.</div>';
+        mentionMenu.innerHTML = '<div class="list-group-item text-muted small" role="option" aria-disabled="true" aria-selected="false">No matching participants, agents, models, or collaborators found.</div>';
         mentionMenu.classList.remove('d-none');
         activeMentionState = {
             ...mentionState,
             results: [],
             activeIndex: -1,
         };
+        clearMentionComboboxState();
         return;
     }
 
@@ -1545,7 +1572,10 @@ function renderMentionMenu(results, mentionState) {
     results.forEach((result, index) => {
         const button = document.createElement('button');
         button.type = 'button';
+        button.id = `${MENTION_OPTION_ID_PREFIX}${index}`;
         button.className = `list-group-item list-group-item-action collaboration-mention-item${index === 0 ? ' active' : ''}`;
+        button.setAttribute('role', 'option');
+        button.setAttribute('aria-selected', index === 0 ? 'true' : 'false');
         button.innerHTML = buildSuggestionItemHtml(result);
         button.setAttribute('data-index', String(index));
         button.addEventListener('mousedown', event => {
@@ -1569,17 +1599,39 @@ function renderMentionMenu(results, mentionState) {
         mentionMenu.appendChild(button);
     });
     mentionMenu.classList.remove('d-none');
+    updateMentionMenuActiveItem({ scrollActiveIntoView: false });
 }
 
-function updateMentionMenuActiveItem() {
+function updateMentionMenuActiveItem({ scrollActiveIntoView = true } = {}) {
     if (!mentionMenu || !activeMentionState) {
         return;
     }
 
     const items = mentionMenu.querySelectorAll('.collaboration-mention-item');
+    let activeItemId = '';
     items.forEach((item, index) => {
-        item.classList.toggle('active', index === activeMentionState.activeIndex);
+        const isActive = index === activeMentionState.activeIndex;
+        item.classList.toggle('active', isActive);
+        item.setAttribute('aria-selected', isActive ? 'true' : 'false');
+        if (isActive) {
+            activeItemId = item.id || '';
+            // The menu is height-capped and scrollable, so keep the highlighted
+            // suggestion visible while the user arrows through the list.
+            if (scrollActiveIntoView && typeof item.scrollIntoView === 'function') {
+                item.scrollIntoView({ block: 'nearest' });
+            }
+        }
     });
+
+    if (!userInput) {
+        return;
+    }
+
+    if (activeItemId) {
+        applyMentionComboboxState(activeItemId);
+    } else {
+        clearMentionComboboxState();
+    }
 }
 
 async function refreshMentionSuggestions() {
@@ -1885,6 +1937,42 @@ function handleComposerInput() {
     void refreshMentionSuggestions();
 }
 
+function selectActiveMentionSuggestion() {
+    if (!activeMentionState || !Array.isArray(activeMentionState.results)) {
+        return false;
+    }
+
+    const mentionState = activeMentionState;
+    const collaborator = mentionState.results[mentionState.activeIndex];
+    if (!collaborator) {
+        return false;
+    }
+
+    if (collaborator.action === 'tag') {
+        insertParticipantMention(collaborator, mentionState);
+    } else if (collaborator.action === 'ai_tag') {
+        insertInvocationTargetMention(collaborator, mentionState);
+    } else {
+        openParticipantConfirmation(collaborator, {
+            conversationId: window.chatConversations?.getCurrentConversationId?.(),
+            source: 'mention',
+            mentionState,
+        });
+    }
+
+    return true;
+}
+
+function hasActiveMentionSuggestion() {
+    return Boolean(
+        activeMentionState
+        && Array.isArray(activeMentionState.results)
+        && activeMentionState.results.length > 0
+        && activeMentionState.activeIndex >= 0
+        && activeMentionState.results[activeMentionState.activeIndex],
+    );
+}
+
 function handleComposerKeydown(event) {
     if (!activeMentionState || mentionMenu?.classList.contains('d-none')) {
         if (event.key === 'Escape' && activeReplyContext) {
@@ -1908,22 +1996,22 @@ function handleComposerKeydown(event) {
         return true;
     }
 
+    // Tab accepts the highlighted suggestion the same way Enter does. Shift+Tab is
+    // deliberately left alone so it keeps moving focus backwards, and Tab falls
+    // through whenever there is nothing highlighted to accept.
+    if (event.key === 'Tab' && !event.shiftKey) {
+        if (!hasActiveMentionSuggestion()) {
+            return false;
+        }
+
+        event.preventDefault();
+        selectActiveMentionSuggestion();
+        return true;
+    }
+
     if (event.key === 'Enter' && activeMentionState.activeIndex >= 0) {
         event.preventDefault();
-        const collaborator = activeMentionState.results[activeMentionState.activeIndex];
-        if (collaborator) {
-            if (collaborator.action === 'tag') {
-                insertParticipantMention(collaborator, activeMentionState);
-            } else if (collaborator.action === 'ai_tag') {
-                insertInvocationTargetMention(collaborator, activeMentionState);
-            } else {
-                openParticipantConfirmation(collaborator, {
-                    conversationId: window.chatConversations?.getCurrentConversationId?.(),
-                    source: 'mention',
-                    mentionState: activeMentionState,
-                });
-            }
-        }
+        selectActiveMentionSuggestion();
         return true;
     }
 
diff --git a/docs/explanation/fixes/COLLABORATION_MENTION_TAB_AUTOCOMPLETE_FIX.md b/docs/explanation/fixes/COLLABORATION_MENTION_TAB_AUTOCOMPLETE_FIX.md
new file mode 100644
index 000000000..b8f02d8ed
--- /dev/null
+++ b/docs/explanation/fixes/COLLABORATION_MENTION_TAB_AUTOCOMPLETE_FIX.md
@@ -0,0 +1,80 @@
+# Collaboration Mention Tab Autocomplete Fix
+
+Fixed in version: **0.260.004**
+
+Related issue: [#1299](https://github.com/microsoft/simplechat/issues/1299)
+
+## Issue Description
+
+In multi-user (collaborative) conversations, typing `@` in the chat composer opens the participant and AI target suggestion menu. Arrow keys moved the highlight and <kbd>Enter</kbd> accepted the highlighted entry, but <kbd>Tab</kbd> did nothing to the menu.
+
+Because <kbd>Tab</kbd> fell through to the browser default, pressing it moved focus out of the message box, the menu closed on blur, and the partially typed `@par` text was left behind. Most users expect <kbd>Tab</kbd> to complete an autocomplete entry, so the mention menu felt broken even though <kbd>Enter</kbd> worked.
+
+The behavior was also inconsistent with the agent-instruction mention menu (`static/js/agent_instruction_mentions.js`), which already treated <kbd>Tab</kbd> and <kbd>Enter</kbd> as the same "accept" action.
+
+## Root Cause Analysis
+
+- `handleComposerKeydown()` in `application/single_app/static/js/chat/chat-collaboration.js` only branched on `ArrowDown`, `ArrowUp`, `Enter`, and `Escape`. There was no `Tab` branch, so the function returned `false`.
+- The `#user-input` keydown listener in `chat-messages.js` only short-circuits when `window.chatCollaboration.handleComposerKeydown(e)` returns `true`. A `false` return meant the browser applied its default focus-movement behavior for <kbd>Tab</kbd>.
+- The selection logic (participant tag vs. AI invocation target vs. invite confirmation) was written inline inside the `Enter` branch, so there was no reusable entry point another key could call.
+
+A related accessibility gap surfaced in the same code path: `#collaboration-mention-menu` is declared `role="listbox"` in `templates/chats.html`, but `renderMentionMenu()` created plain `<button>` elements with no `role="option"` or `aria-selected`. Assistive technology could not announce which suggestion was highlighted during keyboard navigation.
+
+## Technical Details
+
+### Files Modified
+
+- `application/single_app/static/js/chat/chat-collaboration.js`
+- `application/single_app/config.py`
+- `functional_tests/test_collaboration_mention_tab_autocomplete.py`
+- `ui_tests/test_chat_collaboration_mention_tab_selection.py`
+
+### Code Changes Summary
+
+- Extracted the inline `Enter` selection logic into a shared `selectActiveMentionSuggestion()` helper so every "accept" key routes through one implementation of the participant tag, `ai_tag` invocation target, and invite-confirmation branches.
+- Added a `hasActiveMentionSuggestion()` guard that reports whether there is a real highlighted suggestion to accept.
+- Added a `Tab` branch to `handleComposerKeydown()` that accepts the highlighted suggestion, calls `event.preventDefault()` so focus stays in the composer, and returns `true`.
+- Left <kbd>Shift</kbd>+<kbd>Tab</kbd> unhandled so it keeps the browser's normal focus-backwards behavior, and left <kbd>Tab</kbd> unhandled in the empty-results state so focus movement still works when there is nothing to complete.
+- Kept the `Enter` guard (`activeMentionState.activeIndex >= 0`) unchanged so unrelated <kbd>Enter</kbd> presses still send the message.
+- Exposed each suggestion as a listbox option with a stable id (`collaboration-mention-option-{index}`), `role="option"`, and `aria-selected`, and pointed the composer at the highlighted option through `aria-activedescendant`.
+- Paired `aria-activedescendant` with `aria-controls` and `aria-autocomplete="list"` on `#user-input`. ARIA 1.2 only resolves `aria-activedescendant` from a focused textbox when the referenced option is a descendant of the element named by `aria-controls`, and `#collaboration-mention-menu` is a sibling of the composer rather than a descendant. All three attributes are applied only while the menu is open and removed when it closes, so the composer stays a plain textbox the rest of the time.
+- Kept `aria-selected` and `aria-activedescendant` in sync during arrow-key navigation, cleared the combobox attributes when the menu closes or shows the empty state, and scrolled the highlighted option into view inside the height-capped (`max-height: 240px`) menu.
+- Marked the "No matching participants..." row as a disabled option so the `role="listbox"` container keeps only valid children.
+- Updated `config.py` to version `0.260.004` for this fix.
+
+### Behavior Matrix
+
+| Key | Menu open with results | Menu open, no results | Menu closed |
+| --- | --- | --- | --- |
+| <kbd>Tab</kbd> | Accepts the highlighted suggestion, focus stays in the composer | Normal focus movement | Normal focus movement |
+| <kbd>Shift</kbd>+<kbd>Tab</kbd> | Normal focus movement | Normal focus movement | Normal focus movement |
+| <kbd>Enter</kbd> | Accepts the highlighted suggestion (unchanged) | Sends the message (unchanged) | Sends the message (unchanged) |
+| <kbd>ArrowUp</kbd> / <kbd>ArrowDown</kbd> | Moves the highlight (unchanged) | No-op | No-op |
+| <kbd>Escape</kbd> | Closes the menu (unchanged) | Closes the menu | Clears an active reply target |
+
+## Validation
+
+### Test Results
+
+- `functional_tests/test_collaboration_mention_tab_autocomplete.py` — 5/5 tests passed. It parses the real `handleComposerKeydown()`, `selectActiveMentionSuggestion()`, `renderMentionMenu()`, `updateMentionMenuActiveItem()`, and `hideMentionMenu()` bodies out of the module and asserts the Tab branch, the `shiftKey` guard, the guard-before-`preventDefault()` ordering, the shared selection path, and the listbox ARIA wiring.
+- The same test was run against the pre-fix source and failed 3/5 as expected, confirming it is a real regression test rather than a tautology.
+- `ui_tests/test_chat_collaboration_mention_tab_selection.py` — new Playwright regression test that seeds deterministic agent mention targets, opens the menu on `/chats`, and asserts <kbd>Tab</kbd> inserts the highlighted mention while focus stays on `#user-input`, that <kbd>ArrowDown</kbd> plus <kbd>Tab</kbd> inserts the second suggestion, that <kbd>Enter</kbd> is unchanged, and that <kbd>Shift</kbd>+<kbd>Tab</kbd> inserts nothing and moves focus away.
+
+### Before and After
+
+| Observation | Before | After |
+| --- | --- | --- |
+| Mention menu handles <kbd>Tab</kbd> | `false` | `true` |
+| <kbd>Tab</kbd> prevents default focus movement | No | Yes |
+| Suggestions inserted on <kbd>Tab</kbd> | 0 | 1 |
+| Suggestions inserted on <kbd>Enter</kbd> | 1 | 1 (unchanged) |
+| Suggestions exposed with `role="option"` | 0 | 1 per suggestion |
+| `aria-activedescendant` on the composer | absent | tracks the highlighted option |
+| `aria-controls` / `aria-autocomplete` on the composer | absent | applied while the menu is open, removed when it closes |
+
+### User Experience Improvements
+
+- <kbd>Tab</kbd> now completes an `@` mention the way users expect from other editors and chat clients.
+- Focus no longer jumps out of the message box mid-sentence, so the typed `@` fragment is not left behind.
+- The chat mention menu now matches the agent-instruction mention menu, which already accepted <kbd>Tab</kbd>.
+- Screen reader users hear which suggestion is highlighted while arrowing through the list, and the highlighted suggestion stays scrolled into view.
diff --git a/docs/explanation/fixes/index.md b/docs/explanation/fixes/index.md
index e80b770e4..10dabaf40 100644
--- a/docs/explanation/fixes/index.md
+++ b/docs/explanation/fixes/index.md
@@ -32,3 +32,4 @@ category: Version History
 - [Workflow Task Document Picker Fix](WORKFLOW_TASK_DOCUMENT_PICKER_FIX.md)
 - [Workflow File Sync Prompt Context Fix](WORKFLOW_FILE_SYNC_PROMPT_CONTEXT_FIX.md)
 - [Chat Citation Whitespace Collapse Fix](CHAT_CITATION_WHITESPACE_COLLAPSE_FIX.md)
+- [Collaboration Mention Tab Autocomplete Fix](COLLABORATION_MENTION_TAB_AUTOCOMPLETE_FIX.md)
diff --git a/docs/explanation/release_notes.md b/docs/explanation/release_notes.md
index 2c9f83afd..1982b8426 100644
--- a/docs/explanation/release_notes.md
+++ b/docs/explanation/release_notes.md
@@ -2,6 +2,22 @@
 
 For feature-focused and fix-focused drill-downs by version, see [Features by Version](/explanation/features/) and [Fixes by Version](/explanation/fixes/).
 
+### **(v0.260.004)**
+
+#### User Interface Enhancements
+
+*   **Tab Now Completes an @ Mention in Shared Conversations**
+    *   In multi-user conversations, pressing **Tab** while the `@` suggestion menu is open now accepts the highlighted participant, agent, model, or invite suggestion, exactly like **Enter** already did.
+    *   Previously **Tab** moved focus out of the message box and left the half-typed `@par` text behind, which broke the autocomplete habit most people bring from other editors and chat clients.
+    *   **Shift+Tab** is deliberately unchanged and still moves focus backwards, and **Tab** still moves focus normally when the menu is showing "No matching participants...".
+    *   The chat mention menu now matches the agent instruction mention menu, which already accepted **Tab**.
+    *   (Ref: `chat-collaboration.js`, `handleComposerKeydown`, `selectActiveMentionSuggestion`, [#1299](https://github.com/microsoft/simplechat/issues/1299))
+
+*   **Mention Menu Is Now Announced Correctly By Screen Readers**
+    *   Each `@` suggestion is now exposed as a proper listbox option with `aria-selected`, and the message box references the highlighted suggestion through `aria-activedescendant` paired with `aria-controls` so assistive technology can resolve it.
+    *   The highlighted suggestion is also scrolled into view while arrowing through a long list, so keyboard navigation no longer highlights an off-screen entry.
+    *   (Ref: `chat-collaboration.js`, `renderMentionMenu`, `updateMentionMenuActiveItem`, `applyMentionComboboxState`, `chats.html`)
+
 ### **(v0.260.003)**
 
 #### Bug Fixes
diff --git a/functional_tests/test_collaboration_mention_tab_autocomplete.py b/functional_tests/test_collaboration_mention_tab_autocomplete.py
new file mode 100644
index 000000000..d4f2268d5
--- /dev/null
+++ b/functional_tests/test_collaboration_mention_tab_autocomplete.py
@@ -0,0 +1,225 @@
+# test_collaboration_mention_tab_autocomplete.py
+"""
+Functional test for Tab autocomplete in the collaborative @ mention menu.
+Version: 0.260.004
+Implemented in: 0.260.004
+
+This test ensures the chat composer's @ mention menu accepts the highlighted
+suggestion when the user presses Tab, that Shift+Tab and the empty-results state
+still fall through to normal browser focus movement, that Enter keeps its
+existing behavior, and that the menu exposes proper listbox semantics so
+assistive technology can announce the highlighted suggestion.
+
+Refs: https://github.com/microsoft/simplechat/issues/1299
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.append(str(Path(__file__).resolve().parent))
+
+from test_support.versioning import assert_app_version_at_least
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+CHAT_COLLABORATION_FILE = REPO_ROOT / 'application' / 'single_app' / 'static' / 'js' / 'chat' / 'chat-collaboration.js'
+CHAT_MESSAGES_FILE = REPO_ROOT / 'application' / 'single_app' / 'static' / 'js' / 'chat' / 'chat-messages.js'
+CHATS_TEMPLATE_FILE = REPO_ROOT / 'application' / 'single_app' / 'templates' / 'chats.html'
+
+
+def read_text(path):
+    return path.read_text(encoding='utf-8')
+
+
+def extract_function_source(source, function_name):
+    """Return the source text of a top-level function declaration."""
+    marker = f'function {function_name}('
+    start = source.find(marker)
+    assert start != -1, f'Expected to find function {function_name} in the module source.'
+
+    paren_depth = 0
+    body_start = -1
+    for index in range(start + len(marker) - 1, len(source)):
+        char = source[index]
+        if char == '(':
+            paren_depth += 1
+        elif char == ')':
+            paren_depth -= 1
+            if paren_depth == 0:
+                body_start = source.find('{', index)
+                break
+
+    assert body_start != -1, f'Could not locate the body of {function_name}.'
+
+    depth = 0
+    for index in range(body_start, len(source)):
+        char = source[index]
+        if char == '{':
+            depth += 1
+        elif char == '}':
+            depth -= 1
+            if depth == 0:
+                return source[start:index + 1]
+
+    raise AssertionError(f'Unbalanced braces while extracting {function_name}.')
+
+
+def test_mention_menu_accepts_tab():
+    """Tab accepts the highlighted suggestion, Shift+Tab does not."""
+    print('Testing Tab autocomplete in the collaborative mention menu...')
+    collaboration_source = read_text(CHAT_COLLABORATION_FILE)
+    keydown_source = extract_function_source(collaboration_source, 'handleComposerKeydown')
+
+    assert "event.key === 'Tab'" in keydown_source, \
+        'handleComposerKeydown must handle the Tab key so users can complete a mention.'
+    assert '!event.shiftKey' in keydown_source, \
+        'Shift+Tab must fall through so it keeps moving focus backwards.'
+    assert 'hasActiveMentionSuggestion()' in keydown_source, \
+        'Tab must only be captured when there is a highlighted suggestion to accept.'
+    assert 'selectActiveMentionSuggestion()' in keydown_source, \
+        'Tab and Enter must share the same selection path.'
+
+    tab_branch_start = keydown_source.find("event.key === 'Tab'")
+    tab_branch = keydown_source[tab_branch_start:]
+    guard_index = tab_branch.find('hasActiveMentionSuggestion()')
+    prevent_index = tab_branch.find('event.preventDefault()')
+    assert -1 < guard_index < prevent_index, \
+        'The Tab branch must bail out before calling preventDefault when nothing is highlighted.'
+
+    print('Test passed!')
+    return True
+
+
+def test_enter_and_tab_share_one_selection_path():
+    """Enter keeps working and reuses the shared selection helper."""
+    print('Testing shared mention selection helper...')
+    collaboration_source = read_text(CHAT_COLLABORATION_FILE)
+    keydown_source = extract_function_source(collaboration_source, 'handleComposerKeydown')
+    select_source = extract_function_source(collaboration_source, 'selectActiveMentionSuggestion')
+
+    assert "event.key === 'Enter' && activeMentionState.activeIndex >= 0" in keydown_source, \
+        'Enter must keep its existing guard so unrelated Enter presses still send the message.'
+
+    assert "collaborator.action === 'tag'" in select_source, \
+        'The shared helper must still tag existing participants.'
+    assert "collaborator.action === 'ai_tag'" in select_source, \
+        'The shared helper must still route agent and model invocation targets.'
+    assert 'openParticipantConfirmation(collaborator' in select_source, \
+        'The shared helper must still open the invite confirmation for new collaborators.'
+    assert "source: 'mention'" in select_source, \
+        'The invite confirmation must still record the mention source.'
+
+    # The old inline Enter implementation must be gone so the two keys cannot drift apart.
+    assert 'insertParticipantMention(collaborator, activeMentionState)' not in keydown_source, \
+        'handleComposerKeydown must delegate selection instead of inlining it.'
+
+    print('Test passed!')
+    return True
+
+
+def test_mention_menu_exposes_listbox_semantics():
+    """The mention menu announces which suggestion is highlighted."""
+    print('Testing mention menu listbox semantics...')
+    collaboration_source = read_text(CHAT_COLLABORATION_FILE)
+    template_source = read_text(CHATS_TEMPLATE_FILE)
+    render_source = extract_function_source(collaboration_source, 'renderMentionMenu')
+    update_source = extract_function_source(collaboration_source, 'updateMentionMenuActiveItem')
+    hide_source = extract_function_source(collaboration_source, 'hideMentionMenu')
+    apply_source = extract_function_source(collaboration_source, 'applyMentionComboboxState')
+    clear_source = extract_function_source(collaboration_source, 'clearMentionComboboxState')
+
+    assert 'role="listbox"' in template_source, \
+        'The mention menu container is expected to remain a listbox.'
+    assert 'id="collaboration-mention-menu"' in template_source, \
+        'The mention menu needs a stable id so aria-controls can reference it.'
+
+    assert "setAttribute('role', 'option')" in render_source, \
+        'Every mention suggestion must be exposed as a listbox option.'
+    assert "setAttribute('aria-selected'" in render_source, \
+        'Mention suggestions must report their selected state.'
+    assert 'MENTION_OPTION_ID_PREFIX' in render_source, \
+        'Mention suggestions need stable ids so aria-activedescendant can reference them.'
+    assert 'role="option" aria-disabled="true"' in render_source, \
+        'The empty-results row must stay a valid, non-selectable listbox child.'
+
+    assert "item.setAttribute('aria-selected', isActive ? 'true' : 'false')" in update_source, \
+        'Keyboard navigation must keep aria-selected in sync with the highlighted item.'
+    assert 'applyMentionComboboxState(activeItemId)' in update_source, \
+        'The composer must point at the highlighted option while the menu is open.'
+    assert 'clearMentionComboboxState()' in update_source, \
+        'The composer must drop the option reference when nothing is highlighted.'
+    assert 'scrollActiveIntoView' in update_source, \
+        'The highlighted option must be scrolled into view inside the height-capped menu.'
+
+    # ARIA 1.2 only resolves aria-activedescendant from a textbox when the referenced
+    # option lives inside the element named by aria-controls. The mention menu is a
+    # sibling of #user-input, so aria-controls is required for the reference to work.
+    assert "userInput.setAttribute('aria-controls', mentionMenu.id)" in apply_source, \
+        'aria-activedescendant on the composer is only valid alongside aria-controls.'
+    assert "userInput.setAttribute('aria-autocomplete', 'list')" in apply_source, \
+        'The composer must advertise its list popup while the mention menu is open.'
+    assert "userInput.setAttribute('aria-activedescendant', activeItemId)" in apply_source, \
+        'The composer must reference the highlighted option.'
+
+    for attribute in ('aria-activedescendant', 'aria-autocomplete', 'aria-controls'):
+        assert f"userInput.removeAttribute('{attribute}')" in clear_source, \
+            f'Closing the mention menu must drop the stale {attribute} reference.'
+
+    assert 'clearMentionComboboxState()' in hide_source, \
+        'Closing the mention menu must reset the composer combobox state.'
+    assert 'clearMentionComboboxState()' in render_source, \
+        'The empty-results state must reset the composer combobox state.'
+
+    print('Test passed!')
+    return True
+
+
+def test_composer_keydown_is_wired_to_the_chat_input():
+    """The chat composer still delegates keydown handling to collaboration."""
+    print('Testing composer keydown wiring...')
+    messages_source = read_text(CHAT_MESSAGES_FILE)
+
+    assert 'window.chatCollaboration?.handleComposerKeydown?.(e)' in messages_source, \
+        'The chat composer must delegate keydown handling to the collaboration module.'
+
+    collaboration_source = read_text(CHAT_COLLABORATION_FILE)
+    assert 'handleComposerKeydown,' in collaboration_source, \
+        'handleComposerKeydown must remain exported on window.chatCollaboration.'
+
+    print('Test passed!')
+    return True
+
+
+def test_version_is_at_least_implementation_version():
+    """The fix ships in 0.260.004 or later."""
+    print('Testing application version...')
+    assert_app_version_at_least(
+        '0.260.004',
+        reason='Tab autocomplete for collaborative @ mentions shipped in 0.260.004.',
+    )
+    print('Test passed!')
+    return True
+
+
+if __name__ == '__main__':
+    tests = [
+        test_mention_menu_accepts_tab,
+        test_enter_and_tab_share_one_selection_path,
+        test_mention_menu_exposes_listbox_semantics,
+        test_composer_keydown_is_wired_to_the_chat_input,
+        test_version_is_at_least_implementation_version,
+    ]
+
+    results = []
+    for test in tests:
+        print(f'\nRunning {test.__name__}...')
+        try:
+            results.append(test())
+        except Exception as error:
+            print(f'Test failed: {error}')
+            import traceback
+            traceback.print_exc()
+            results.append(False)
+
+    print(f'\nResults: {sum(1 for result in results if result)}/{len(results)} tests passed')
+    sys.exit(0 if all(results) else 1)
diff --git a/ui_tests/test_chat_collaboration_mention_tab_selection.py b/ui_tests/test_chat_collaboration_mention_tab_selection.py
new file mode 100644
index 000000000..3f32ca52d
--- /dev/null
+++ b/ui_tests/test_chat_collaboration_mention_tab_selection.py
@@ -0,0 +1,211 @@
+# test_chat_collaboration_mention_tab_selection.py
+"""
+UI test for Tab autocomplete in the collaborative @ mention menu.
+
+Version: 0.260.004
+Implemented in: 0.260.004
+
+This test ensures that pressing Tab while the chat composer's @ mention menu is
+open accepts the highlighted suggestion and keeps focus in the message box, that
+Shift+Tab still moves focus backwards without inserting a mention, and that the
+menu exposes listbox semantics so the highlighted suggestion is announced.
+
+Refs: https://github.com/microsoft/simplechat/issues/1299
+"""
+
+import os
+from pathlib import Path
+
+import pytest
+from playwright.sync_api import expect
+
+
+BASE_URL = os.getenv('SIMPLECHAT_UI_BASE_URL', '').rstrip('/')
+STORAGE_STATE = os.getenv('SIMPLECHAT_UI_STORAGE_STATE', '')
+
+MOCK_CONVERSATION_ID = 'mock-mention-tab-conversation'
+
+# Seeds two deterministic agent mention targets and points the composer at a mock
+# conversation. The mock conversation item deliberately omits `data-chat-type` so
+# `canUseParticipantFlow()` returns false and the suggestion lookup stays offline.
+SETUP_SCRIPT = """
+    () => {
+        const conversationId = 'mock-mention-tab-conversation';
+
+        window.appSettings = window.appSettings || {};
+        window.__mentionTabPreviousCollaborationFlag = window.appSettings.enable_collaborative_conversations;
+        window.appSettings.enable_collaborative_conversations = true;
+
+        const agentSelect = document.getElementById('agent-select');
+        const modelSelect = document.getElementById('model-select');
+        window.__mentionTabPreviousAgentOptions = agentSelect ? agentSelect.innerHTML : null;
+        window.__mentionTabPreviousModelOptions = modelSelect ? modelSelect.innerHTML : null;
+        if (agentSelect) {
+            agentSelect.innerHTML = '';
+        }
+        if (modelSelect) {
+            modelSelect.innerHTML = '';
+        }
+
+        window.chatAgentOptions = [
+            { id: 'ui-test-agent-alpha', name: 'UiTestAgentAlpha', display_name: 'UiTestAgentAlpha' },
+            { id: 'ui-test-agent-bravo', name: 'UiTestAgentBravo', display_name: 'UiTestAgentBravo' },
+        ];
+        window.chatModelOptions = [];
+
+        const conversationItem = document.createElement('div');
+        conversationItem.className = 'conversation-item';
+        conversationItem.id = 'mention-tab-mock-conversation-item';
+        conversationItem.dataset.conversationId = conversationId;
+        document.body.appendChild(conversationItem);
+
+        window.__mentionTabPreviousGetCurrentConversationId = window.chatConversations.getCurrentConversationId;
+        window.chatConversations.getCurrentConversationId = () => conversationId;
+    }
+"""
+
+TEARDOWN_SCRIPT = """
+    () => {
+        if (window.__mentionTabPreviousGetCurrentConversationId) {
+            window.chatConversations.getCurrentConversationId = window.__mentionTabPreviousGetCurrentConversationId;
+        }
+
+        const agentSelect = document.getElementById('agent-select');
+        const modelSelect = document.getElementById('model-select');
+        if (agentSelect && window.__mentionTabPreviousAgentOptions !== null) {
+            agentSelect.innerHTML = window.__mentionTabPreviousAgentOptions;
+        }
+        if (modelSelect && window.__mentionTabPreviousModelOptions !== null) {
+            modelSelect.innerHTML = window.__mentionTabPreviousModelOptions;
+        }
+
+        if (window.appSettings) {
+            window.appSettings.enable_collaborative_conversations = window.__mentionTabPreviousCollaborationFlag;
+        }
+
+        document.getElementById('mention-tab-mock-conversation-item')?.remove();
+
+        const userInput = document.getElementById('user-input');
+        if (userInput) {
+            userInput.value = '';
+        }
+    }
+"""
+
+
+def open_mention_menu(page, query='@UiTest'):
+    """Clear the composer, type a mention query, and wait for suggestions."""
+    page.fill('#user-input', '')
+    page.click('#user-input')
+    page.keyboard.type(query)
+    expect(page.locator('#collaboration-mention-menu')).to_be_visible()
+    expect(page.locator('#collaboration-mention-menu [role="option"]').first).to_be_visible()
+
+
+@pytest.mark.ui
+def test_chat_collaboration_mention_tab_selection(playwright):
+    """Validate Tab, Shift+Tab, and listbox semantics for the @ mention menu."""
+    if not BASE_URL:
+        pytest.skip('Set SIMPLECHAT_UI_BASE_URL to run this UI test.')
+    if not STORAGE_STATE or not Path(STORAGE_STATE).exists():
+        pytest.skip('Set SIMPLECHAT_UI_STORAGE_STATE to a valid authenticated Playwright storage state file.')
+
+    browser = playwright.chromium.launch()
+    context = browser.new_context(
+        storage_state=STORAGE_STATE,
+        viewport={'width': 1440, 'height': 900},
+    )
+    page = context.new_page()
+    page_errors = []
+    console_errors = []
+
+    page.on('pageerror', lambda error: page_errors.append(str(error)))
+    page.on('console', lambda message: console_errors.append(message.text) if message.type == 'error' else None)
+
+    try:
+        response = page.goto(f'{BASE_URL}/chats', wait_until='domcontentloaded')
+
+        assert response is not None, 'Expected a navigation response when loading /chats.'
+        assert response.ok, f'Expected /chats to load successfully, got HTTP {response.status}.'
+
+        expect(page.locator('#user-input')).to_be_visible()
+        expect(page.locator('#collaboration-mention-menu')).to_have_count(1)
+
+        page.evaluate(SETUP_SCRIPT)
+
+        # The mention menu must expose listbox options with the first one highlighted.
+        open_mention_menu(page)
+        options = page.locator('#collaboration-mention-menu [role="option"]')
+        assert options.count() >= 2, (
+            'Expected the seeded agent targets to produce at least two mention suggestions, '
+            f'found {options.count()}.'
+        )
+        expect(options.nth(0)).to_have_attribute('aria-selected', 'true')
+        expect(options.nth(1)).to_have_attribute('aria-selected', 'false')
+
+        first_option_id = options.nth(0).get_attribute('id')
+        assert first_option_id, 'Mention suggestions need stable ids for aria-activedescendant.'
+        expect(page.locator('#user-input')).to_have_attribute('aria-activedescendant', first_option_id)
+        # ARIA 1.2 only resolves aria-activedescendant from a textbox when the option
+        # lives inside the element named by aria-controls.
+        expect(page.locator('#user-input')).to_have_attribute('aria-controls', 'collaboration-mention-menu')
+        expect(page.locator('#user-input')).to_have_attribute('aria-autocomplete', 'list')
+        assert page.locator(f'#collaboration-mention-menu #{first_option_id}').count() == 1, \
+            'The referenced option must live inside the controlled mention menu.'
+
+        # Tab accepts the highlighted suggestion and keeps focus in the composer.
+        page.keyboard.press('Tab')
+        expect(page.locator('#user-input')).to_have_value('@UiTestAgentAlpha ')
+        expect(page.locator('#collaboration-mention-menu')).to_be_hidden()
+        assert page.evaluate('() => document.activeElement?.id') == 'user-input', \
+            'Tab must accept the suggestion instead of moving focus out of the composer.'
+        assert page.evaluate(
+            "() => document.getElementById('user-input').hasAttribute('aria-activedescendant')"
+        ) is False, 'Closing the mention menu must drop the stale option reference.'
+
+        # Arrow keys still move the highlight, and Tab accepts whatever is highlighted.
+        open_mention_menu(page)
+        page.keyboard.press('ArrowDown')
+        options = page.locator('#collaboration-mention-menu [role="option"]')
+        expect(options.nth(0)).to_have_attribute('aria-selected', 'false')
+        expect(options.nth(1)).to_have_attribute('aria-selected', 'true')
+
+        second_option_id = options.nth(1).get_attribute('id')
+        expect(page.locator('#user-input')).to_have_attribute('aria-activedescendant', second_option_id)
+
+        page.keyboard.press('Tab')
+        expect(page.locator('#user-input')).to_have_value('@UiTestAgentBravo ')
+
+        # Enter keeps working exactly as before.
+        open_mention_menu(page)
+        page.keyboard.press('Enter')
+        expect(page.locator('#user-input')).to_have_value('@UiTestAgentAlpha ')
+
+        # Shift+Tab is left alone so it keeps moving focus backwards.
+        open_mention_menu(page)
+        page.keyboard.press('Shift+Tab')
+        expect(page.locator('#user-input')).to_have_value('@UiTest')
+        assert page.evaluate('() => document.activeElement?.id') != 'user-input', \
+            'Shift+Tab must keep its normal focus-backwards behavior.'
+
+        page.evaluate(TEARDOWN_SCRIPT)
+
+        syntax_errors = [message for message in page_errors if 'SyntaxError' in message]
+        mention_page_errors = [message for message in page_errors if 'mention' in message.lower()]
+        mention_console_errors = [message for message in console_errors if 'mention' in message.lower()]
+
+        assert not syntax_errors, (
+            'Expected /chats to boot without JavaScript syntax errors. '
+            f'Observed: {syntax_errors}'
+        )
+        assert not mention_page_errors, (
+            'Expected the mention menu workflow to run without page errors. '
+            f'Observed: {mention_page_errors}'
+        )
+        assert not mention_console_errors, (
+            'Expected the mention menu workflow to run without console errors. '
+            f'Observed: {mention_console_errors}'
+        )
+    finally:
+        context.close()
+        browser.close()