teams-transcripts 0.5.0__py3-none-any.whl

teams_transcripts/services/navigation.py

@@ -0,0 +1,1721 @@
+"""Meeting navigation services.
+
+Functions that navigate through the Teams UI to reach the transcript:
+searching for the meeting, selecting the correct occurrence for recurring
+meetings, extracting speaker mappings, and clicking through to the
+Transcript tab.
+
+When the thread_id is already known (via MCPS resolution with
+``--meeting-id``), :func:`navigate_to_thread_direct` bypasses the
+search-click-verify cycle by clicking the chat directly in the sidebar.
+
+Each function takes a connected browser and manages its own connect/disconnect
+lifecycle.  Side-effectful config mutations (speaker_map, meeting_time_text)
+are returned as part of :class:`NavigationResult` rather than mutating state.
+
+Extracted from ``transcript_download.py`` lines 857--1889.
+
+Schema version: 1.2.0
+Created: 2026-04-25
+Last updated: 2026-05-02  -- direct thread navigation via sidebar fibre walk
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import typing
+from dataclasses import dataclass, field
+from datetime import date
+
+from teams_transcripts.domain.scoring import (
+    best_result_index,
+    occurrence_matches,
+)
+from teams_transcripts.domain.timestamps import parse_occurrence_duration
+from teams_transcripts.infrastructure.errors import (
+    EXIT_DOWNLOAD_FAILED,
+    EXIT_MEETING_NOT_FOUND,
+    exit_error,
+)
+
+if typing.TYPE_CHECKING:
+    from teams_transcripts.infrastructure.logging import Logger
+    from teams_transcripts.infrastructure.signals import ShutdownCoordinator
+    from teams_transcripts.ports.agent import AgentPort
+    from teams_transcripts.ports.browser import BrowserPort
+
+
+# ---------------------------------------------------------------------------
+# Result types
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class NavigationResult:
+    """Result of navigating to the transcript view.
+
+    Captures metadata discovered during navigation that the downloader
+    needs for subsequent steps.
+    """
+
+    success: bool
+    speaker_map: dict[str, str] = field(default_factory=dict)
+    meeting_time_text: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Non-Chat view keywords for stuck-state detection
+# ---------------------------------------------------------------------------
+
+_NON_CHAT_KEYWORDS: list[str] = [
+    "Calendar",
+    "Activity",
+    "Teams",  # generic Teams landing, not a chat
+    "Assignments",
+    "Files",
+    "Apps",
+    "Calls",
+    "OneDrive",
+]
+"""Page title keywords that indicate Teams is NOT on the Chat view.
+
+The ``is_chat`` check (below) looks for ``| Chat``, ``| Copilot``,
+or ``| Communities`` in the title.  If none of those are present AND
+one of these keywords *is* present, the view is stuck on a non-Chat
+page and recovery is needed.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Internal: Chat-view switching with recovery
+# ---------------------------------------------------------------------------
+
+
+async def _send_ctrl_3(browser: BrowserPort) -> None:
+    """Send the Ctrl+3 keyboard shortcut (Teams Chat view)."""
+    await browser.send_command(
+        "Input.dispatchKeyEvent",
+        {
+            "type": "keyDown",
+            "key": "3",
+            "code": "Digit3",
+            "windowsVirtualKeyCode": 51,
+            "modifiers": 2,
+        },
+    )
+    await browser.send_command(
+        "Input.dispatchKeyEvent",
+        {
+            "type": "keyUp",
+            "key": "3",
+            "code": "Digit3",
+            "windowsVirtualKeyCode": 51,
+        },
+    )
+
+
+async def _send_escape(browser: BrowserPort) -> None:
+    """Send an Escape key press to dismiss popups/overlays."""
+    await browser.send_command(
+        "Input.dispatchKeyEvent",
+        {
+            "type": "keyDown",
+            "key": "Escape",
+            "code": "Escape",
+            "windowsVirtualKeyCode": 27,
+        },
+    )
+    await browser.send_command(
+        "Input.dispatchKeyEvent",
+        {
+            "type": "keyUp",
+            "key": "Escape",
+            "code": "Escape",
+            "windowsVirtualKeyCode": 27,
+        },
+    )
+
+
+def _title_is_chat(title: str) -> bool:
+    """Return ``True`` if the page title indicates a Chat-family view.
+
+    Matches titles containing ``| Chat``, ``| Copilot``, or
+    ``| Communities``, as well as titles starting with those words.
+    """
+    return (
+        "| Chat" in title
+        or "| Copilot" in title
+        or "| Communities" in title
+        or title.startswith(("Chat |", "Copilot |", "Communities"))
+    )
+
+
+async def _dom_has_chat_content(browser: BrowserPort) -> bool:
+    """Check whether the DOM contains chat-specific elements.
+
+    Teams v2 is an SPA -- the page title can be stale (e.g. still
+    showing "Calendar") while the DOM actually contains a meeting
+    chat.  This function checks for reliable DOM indicators:
+
+    * ``[data-tid="chat-pane-item"]`` -- chat message items
+    * ``[data-tid="chat-title"]`` -- chat header title
+    * A tablist whose text includes "Recap" (meeting-specific tab)
+
+    Returns:
+        ``True`` if chat-specific DOM elements are present.
+    """
+    result = await browser.evaluate("""
+        (function() {
+            if (document.querySelector('[data-tid="chat-pane-item"]'))
+                return true;
+            if (document.querySelector('[data-tid="chat-title"]'))
+                return true;
+            var tabs = document.querySelectorAll('[role="tablist"]');
+            for (var i = 0; i < tabs.length; i++) {
+                if (tabs[i].textContent.indexOf('Recap') !== -1)
+                    return true;
+            }
+            return false;
+        })()
+    """)
+    return result is True
+
+
+async def _is_on_chat_view(browser: BrowserPort) -> bool:
+    """Determine whether the browser is on a Chat-family view.
+
+    Combines the page title check with DOM-based detection.  The
+    title alone is unreliable because Teams' SPA can show a stale
+    title (e.g. "Calendar") while the content is actually a chat.
+
+    Returns:
+        ``True`` if either the title or DOM indicates a Chat view.
+    """
+    title = str(await browser.evaluate("document.title") or "")
+    if _title_is_chat(title) or "Search |" in title:
+        return True
+    return await _dom_has_chat_content(browser)
+
+
+async def _click_chat_nav_item(browser: BrowserPort) -> bool:
+    """Try to click the Chat navigation item in the Teams left rail.
+
+    Uses the ``app-bar-Chat`` data-tid or falls back to matching
+    ``aria-label`` attributes.
+
+    Returns:
+        ``True`` if a clickable element was found and clicked.
+    """
+    result = await browser.evaluate("""
+        (function() {
+            // Primary: data-tid selector used by Teams for the Chat button
+            var chatBtn = document.querySelector(
+                '[data-tid="app-bar-Chat"]'
+            );
+            if (chatBtn) {
+                chatBtn.click();
+                return 'clicked_data_tid';
+            }
+            // Fallback: aria-label matching
+            var navBtns = Array.from(document.querySelectorAll(
+                'button[aria-label], a[aria-label]'
+            ));
+            for (var i = 0; i < navBtns.length; i++) {
+                var label = navBtns[i].getAttribute('aria-label') || '';
+                if (label === 'Chat' || label === 'Chats') {
+                    navBtns[i].click();
+                    return 'clicked_aria';
+                }
+            }
+            return 'not_found';
+        })()
+    """)
+    return str(result).startswith("clicked")
+
+
+async def _ensure_chat_view(
+    browser: BrowserPort,
+    logger: Logger,
+    shutdown: ShutdownCoordinator,
+    *,
+    max_attempts: int = 4,
+) -> None:
+    """Switch to Chat view, retrying if Teams is on a non-Chat page.
+
+    Strategy:
+        1. Send ``Ctrl+3`` and check the page title.
+        2. If the title indicates Chat, dismiss popups and return.
+        3. If stuck on Calendar/Activity/etc., try clicking the Chat
+           nav item via JS (DOM click on ``[data-tid="app-bar-Chat"]``).
+        4. Retry up to *max_attempts* times with increasing wait.
+
+    This handles the common case where a fresh Teams launch or tenant
+    switch opens on Calendar view instead of Chat.
+
+    Args:
+        browser: Connected browser port.
+        logger: Logger instance.
+        shutdown: Shutdown coordinator.
+        max_attempts: Maximum retry attempts (default 4).
+    """
+    for attempt in range(max_attempts):
+        # Send Ctrl+3 keyboard shortcut
+        logger.log(
+            "step4",
+            f"Switching to Chat view (Ctrl+3, attempt {attempt + 1}/{max_attempts})...",
+        )
+        await _send_ctrl_3(browser)
+        await shutdown.interruptible_sleep(2)
+
+        # Check current view -- first by title, then by DOM content.
+        # Teams v2 is an SPA whose page title can be stale (e.g. still
+        # "Calendar") while the DOM actually contains a meeting chat.
+        title = str(await browser.evaluate("document.title") or "")
+        logger.log("step4", f"Page title: {title}")
+
+        if _title_is_chat(title) or "Search |" in title:
+            # On Chat (or a search within Chat) -- dismiss popups and proceed
+            await _send_escape(browser)
+            await asyncio.sleep(0.5)
+            return
+
+        # Title doesn't confirm Chat -- check DOM indicators as fallback
+        if await _dom_has_chat_content(browser):
+            logger.log(
+                "step4",
+                "Title does not indicate Chat but DOM has chat content. "
+                "Proceeding (SPA title may be stale).",
+            )
+            await _send_escape(browser)
+            await asyncio.sleep(0.5)
+            return
+
+        # Not on Chat view -- try clicking the nav item directly
+        logger.log(
+            "step4",
+            "Not on Chat view (title contains non-Chat keyword). Trying Chat nav item click...",
+        )
+        clicked = await _click_chat_nav_item(browser)
+        if clicked:
+            logger.log("step4", "Clicked Chat nav item. Waiting for view switch...")
+            await shutdown.interruptible_sleep(3)
+
+            title = str(await browser.evaluate("document.title") or "")
+            logger.log("step4", f"Page title after nav click: {title}")
+            if _title_is_chat(title) or "Search |" in title:
+                await _send_escape(browser)
+                await asyncio.sleep(0.5)
+                return
+            # DOM fallback after nav click too
+            if await _dom_has_chat_content(browser):
+                logger.log(
+                    "step4",
+                    "DOM has chat content after nav click. Proceeding.",
+                )
+                await _send_escape(browser)
+                await asyncio.sleep(0.5)
+                return
+        else:
+            logger.log("step4", "Chat nav item not found in DOM.")
+
+        # Still not on Chat -- wait longer before retrying (Teams may be loading)
+        wait_secs = 3 + attempt * 2
+        logger.log("step4", f"Retrying in {wait_secs}s...")
+        await shutdown.interruptible_sleep(wait_secs)
+
+    # Final fallback: dismiss popups and proceed anyway -- the search
+    # input check downstream will catch a genuine failure.
+    logger.log(
+        "step4",
+        f"Could not confirm Chat view after {max_attempts} attempts. "
+        f"Proceeding anyway (search input check will catch failures).",
+    )
+    await _send_escape(browser)
+    await asyncio.sleep(0.5)
+
+
+# ---------------------------------------------------------------------------
+# Step 4: Navigate to meeting chat
+# ---------------------------------------------------------------------------
+
+
+async def navigate_to_meeting(
+    browser: BrowserPort,
+    agent: AgentPort,
+    target_id: str,
+    config_meeting: str,
+    config_date: str,
+    logger: Logger,
+    shutdown: ShutdownCoordinator,
+    *,
+    format_json: bool = False,
+    result_index_override: int | None = None,
+) -> bool:
+    """Navigate to the meeting chat via the Teams search UI.
+
+    The browser must be connected to the target containing the search
+    input (pre-discovered by the caller).
+
+    Args:
+        browser: Browser port.
+        agent: Agent port for vision queries.
+        target_id: CDP target ID for the search target.
+        config_meeting: Meeting name search string.
+        config_date: Target date as ``YYYY-MM-DD``.
+        logger: Logger instance.
+        shutdown: Shutdown coordinator.
+        format_json: Whether to emit JSON error output.
+        result_index_override: If set, skip agent and click the result
+            at this index directly (used for retries).
+
+    Returns:
+        ``True`` if navigation reached a meeting chat, ``False`` if it
+        failed (caller should retry with the next index).
+    """
+    await browser.connect(target_id)
+    try:
+        # Switch to Chat view -- with stuck-state detection and recovery.
+        # After a fresh launch or tenant switch, Teams may open on
+        # Calendar, Activity, or another non-Chat view.  Ctrl+3 is the
+        # keyboard shortcut for Chat, but it can fail if Teams hasn't
+        # finished loading.  We retry the shortcut and fall back to
+        # clicking the Chat nav item via JS.
+        await _ensure_chat_view(browser, logger, shutdown)
+
+        # Focus and clear search input
+        await browser.evaluate("""
+            (function() {
+                var input = document.querySelector('#ms-searchux-input');
+                if (!input) return;
+                input.focus();
+                var setter = Object.getOwnPropertyDescriptor(
+                    window.HTMLInputElement.prototype, 'value'
+                ).set;
+                setter.call(input, '');
+                input.dispatchEvent(new Event('input', {bubbles: true}));
+            })()
+        """)
+        await asyncio.sleep(0.5)
+
+        logger.log("step4", f"Typing meeting name: {config_meeting}")
+        await browser.type_text(config_meeting)
+
+        # Wait for search results
+        logger.log("step4", "Waiting for search results...")
+        meeting_name_probe = json.dumps(config_meeting.lower()[:20])
+        search_mode = None
+        for _ in range(20):
+            await asyncio.sleep(0.5)
+            result = await browser.evaluate(f"""
+                (function() {{
+                    for (var i = 0; i < 10; i++) {{
+                        var el = document.querySelector(
+                            '#ms-searchux-popup-' + i
+                        );
+                        if (el) {{
+                            var text = el.textContent.trim();
+                            if (text.indexOf('Search Filters') === -1)
+                                return 'popup';
+                        }}
+                    }}
+                    var opts = Array.from(
+                        document.querySelectorAll('[role="option"]')
+                    );
+                    for (var j = 0; j < opts.length; j++) {{
+                        var t = opts[j].textContent.trim().toLowerCase();
+                        if (t.indexOf({meeting_name_probe}) !== -1)
+                            return 'panel';
+                    }}
+                    return 'waiting';
+                }})()
+            """)
+            if result in ("popup", "panel"):
+                search_mode = result
+                break
+
+        if not search_mode:
+            exit_error(
+                EXIT_MEETING_NOT_FOUND,
+                "SEARCH_FAILED",
+                "Search results did not appear after 10 seconds.",
+                step="step4",
+                format_json=format_json,
+            )
+
+        await shutdown.interruptible_sleep(1)
+        logger.log("step4", f"Search UI mode: {search_mode}")
+
+        # Enumerate results
+        if search_mode == "popup":
+            results_json = await browser.evaluate("""
+                (function() {
+                    var items = [];
+                    for (var i = 0; i < 10; i++) {
+                        var el = document.querySelector(
+                            '#ms-searchux-popup-' + i
+                        );
+                        if (el) {
+                            var text = el.textContent.trim().substring(0, 120);
+                            if (text.indexOf('Search Filters') === -1) {
+                                items.push({
+                                    id: el.id,
+                                    text: text,
+                                    selector: '#' + el.id
+                                });
+                            }
+                        } else {
+                            break;
+                        }
+                    }
+                    return JSON.stringify(items);
+                })()
+            """)
+        else:
+            filter_words = [
+                "Messages",
+                "Files",
+                "Channels",
+                "Group chats",
+                "Meetings",
+                "Images",
+                "View all results",
+                "Search Filters",
+            ]
+            results_json = await browser.evaluate(
+                """
+                (function() {
+                    var filterWords = """
+                + json.dumps(filter_words)
+                + """;
+                    var opts = Array.from(
+                        document.querySelectorAll('[role="option"]')
+                    );
+                    var items = [];
+                    for (var i = 0; i < opts.length; i++) {
+                        var text = opts[i].textContent.trim().substring(0, 120);
+                        var isFilter = false;
+                        for (var f = 0; f < filterWords.length; f++) {
+                            if (text === filterWords[f]
+                                    || text.indexOf('Search Filters') !== -1) {
+                                isFilter = true;
+                                break;
+                            }
+                        }
+                        if (!isFilter && /in:/.test(text)) isFilter = true;
+                        if (!isFilter && text.length > 0) {
+                            var oid = opts[i].id || ('option-' + i);
+                            items.push({
+                                id: oid,
+                                text: text,
+                                selector: opts[i].id
+                                    ? ('#' + opts[i].id) : null,
+                                optionIndex: i
+                            });
+                        }
+                    }
+                    return JSON.stringify(items);
+                })()
+            """
+            )
+
+        search_results = json.loads(str(results_json))
+        logger.log("step4", f"Found {len(search_results)} search result(s):")
+        for sr in search_results:
+            logger.log("step4", f"  [{sr['id'][:20]}] {sr['text'][:70]}")
+
+        # Panel mode with no results: try Meetings filter
+        if search_mode == "panel" and len(search_results) == 0:
+            search_results, search_mode = await _try_meetings_filter(browser, logger, shutdown)
+
+        # Determine which result to click
+        if result_index_override is not None:
+            result_index = result_index_override
+            logger.log("step4", f"Using override result index: {result_index}")
+        elif search_mode == "panel":
+            result_index = best_result_index(config_meeting, [sr["text"] for sr in search_results])
+            logger.log("step4", f"Word-overlap match: index {result_index}")
+        else:
+            # Popup mode: use the agent
+            logger.log("step4", "Taking screenshot of search results...")
+            screenshot_bytes = await browser.screenshot()
+            screenshot_b64 = base64.b64encode(screenshot_bytes).decode()
+
+            prompt = (
+                f"This is a screenshot of Microsoft Teams search results. "
+                f"I am looking for the meeting called '{config_meeting}' "
+                f"from {config_date}. "
+                f"The search results may include chat entries (showing "
+                f"participant names but not dates) and calendar/meeting "
+                f"entries (showing dates). "
+                f"Chat entries are preferred for transcript downloads. "
+                f"If the exact date is not visible in the results, pick "
+                f"the first chat result whose name matches the meeting "
+                f"name. "
+                f"Count the results from top to bottom starting at 0. "
+                f"Return a JSON object with a single key 'index' set to "
+                f"the 0-based index of the correct result to click, or "
+                f"null if NO result matches the meeting name at all. "
+                f'For example: {{"index": 0}} or {{"index": null}}'
+            )
+            logger.log("step4", "Asking agent to identify correct search result...")
+            agent_result = agent.vision_query(screenshot_b64, prompt)
+            logger.log("step4", f"Agent response: {agent_result}")
+
+            if not agent_result or agent_result.get("index") is None:
+                exit_error(
+                    EXIT_MEETING_NOT_FOUND,
+                    "MEETING_NOT_FOUND",
+                    "Agent could not identify the meeting in search results.",
+                    step="step4",
+                    format_json=format_json,
+                )
+
+            result_index = agent_result["index"]
+
+        # Check index bounds
+        if (
+            not isinstance(result_index, int)
+            or result_index < 0
+            or result_index >= len(search_results)
+        ):
+            if result_index_override is not None:
+                logger.log(
+                    "step4",
+                    f"Search result index {result_index} out of range "
+                    f"(only {len(search_results)} results). "
+                    f"No more results to try.",
+                )
+                return False
+            exit_error(
+                EXIT_MEETING_NOT_FOUND,
+                "MEETING_NOT_FOUND",
+                f"Agent picked index {result_index} but only "
+                f"{len(search_results)} search results exist.",
+                step="step4",
+                format_json=format_json,
+            )
+
+        target_result = search_results[result_index]
+        target_id_attr = target_result.get("id", "")
+
+        logger.log(
+            "step4",
+            f"Selecting result index {result_index}: {target_result['text'][:60]}...",
+        )
+
+        # Get bounding box and click
+        if target_id_attr and not target_id_attr.startswith("option-"):
+            target_id_json = json.dumps(target_id_attr)
+            bbox_json = await browser.evaluate(f"""
+                (function() {{
+                    var item = document.getElementById({target_id_json});
+                    if (!item) return JSON.stringify({{error: 'not_found'}});
+                    var rect = item.getBoundingClientRect();
+                    return JSON.stringify({{
+                        x: Math.round(rect.left + rect.width / 2),
+                        y: Math.round(rect.top + rect.height / 2),
+                        id: item.id
+                    }});
+                }})()
+            """)
+        else:
+            oi = target_result.get("optionIndex", 0)
+            bbox_json = await browser.evaluate(f"""
+                (function() {{
+                    var opts = Array.from(
+                        document.querySelectorAll('[role="option"]')
+                    );
+                    if (opts.length <= {oi})
+                        return JSON.stringify({{error: 'not_found'}});
+                    var item = opts[{oi}];
+                    var rect = item.getBoundingClientRect();
+                    return JSON.stringify({{
+                        x: Math.round(rect.left + rect.width / 2),
+                        y: Math.round(rect.top + rect.height / 2),
+                        id: item.id || 'option-{oi}'
+                    }});
+                }})()
+            """)
+        bbox = json.loads(str(bbox_json))
+
+        if bbox.get("error"):
+            logger.log(
+                "step4",
+                f"Could not find element for result at index {result_index}.",
+            )
+            return False
+
+        cx, cy = bbox["x"], bbox["y"]
+        logger.log("step4", f"Clicking at ({cx}, {cy}) on {bbox['id']}...")
+
+        await browser.send_command(
+            "Input.dispatchMouseEvent",
+            {
+                "type": "mousePressed",
+                "x": cx,
+                "y": cy,
+                "button": "left",
+                "clickCount": 1,
+            },
+        )
+        await browser.send_command(
+            "Input.dispatchMouseEvent",
+            {
+                "type": "mouseReleased",
+                "x": cx,
+                "y": cy,
+                "button": "left",
+                "clickCount": 1,
+            },
+        )
+
+        # Wait for navigation
+        logger.log("step4", "Waiting for meeting chat to load...")
+        await shutdown.interruptible_sleep(5)
+
+        new_title = str(await browser.evaluate("document.title") or "")
+        logger.log("step4", f"Page title after navigation: {new_title}")
+
+        # "Search |" means we're still on the search results page --
+        # the click didn't navigate away.  Hard failure.
+        if "Search |" in new_title:
+            logger.log(
+                "step4",
+                "Navigation did not reach a meeting chat. "
+                "Result may be a file, channel, or filter -- "
+                "not a chat entry.",
+            )
+            return False
+
+        # Check via title first, then fall back to DOM indicators.
+        # Teams' SPA title can be stale (e.g. still "Calendar") while
+        # the DOM actually contains the meeting chat content.
+        is_chat = _title_is_chat(new_title)
+        if not is_chat:
+            dom_ok = await _dom_has_chat_content(browser)
+            if dom_ok:
+                logger.log(
+                    "step4",
+                    "Title does not indicate Chat but DOM has chat content. "
+                    "Proceeding (SPA title may be stale).",
+                )
+            else:
+                logger.log(
+                    "step4",
+                    "Navigation did not reach a meeting chat. "
+                    "Result may be a file, channel, or filter -- "
+                    "not a chat entry.",
+                )
+                return False
+    finally:
+        await browser.disconnect()
+
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Step 4a: Direct thread navigation (when thread_id is known)
+# ---------------------------------------------------------------------------
+
+# JavaScript that walks the chat sidebar's React fibre tree to find a
+# chat item whose ``props.chat.id`` matches the target thread_id.
+# Returns the bounding box of the matching element for clicking, or
+# ``{found: false}`` if no match is found.
+#
+# The sidebar in Teams v2 uses a virtualised list, so only visible
+# items have DOM elements.  This approach works best when the meeting
+# chat was recent and is therefore near the top of the sidebar.
+_JS_FIND_SIDEBAR_CHAT = r"""
+(function() {
+    var targetId = TARGET_THREAD_ID;
+
+    // Strategy 1: Walk elements with data-tid containing "chat" that
+    // are likely sidebar chat items (treeitem, listitem, or generic).
+    var selectors = [
+        '[role="treeitem"]',
+        '[role="listitem"]',
+        '[data-tid*="chat-list"]',
+        '[data-tid*="chat-pane-list"] [role="option"]'
+    ];
+    var seen = new Set();
+    var candidates = [];
+    for (var s = 0; s < selectors.length; s++) {
+        var els = document.querySelectorAll(selectors[s]);
+        for (var e = 0; e < els.length; e++) {
+            if (!seen.has(els[e])) {
+                seen.add(els[e]);
+                candidates.push(els[e]);
+            }
+        }
+    }
+
+    for (var i = 0; i < candidates.length; i++) {
+        var el = candidates[i];
+        var fiberKey = Object.keys(el).find(function(k) {
+            return k.startsWith('__reactFiber$');
+        });
+        if (!fiberKey) continue;
+
+        var current = el[fiberKey];
+        for (var d = 0; d < 30 && current; d++) {
+            var props = current.memoizedProps;
+            if (props && props.chat && props.chat.id === targetId) {
+                var rect = el.getBoundingClientRect();
+                if (rect.width === 0 || rect.height === 0) break;
+                return JSON.stringify({
+                    found: true,
+                    x: Math.round(rect.left + rect.width / 2),
+                    y: Math.round(rect.top + rect.height / 2),
+                    title: (props.chat.topic || '').substring(0, 80)
+                });
+            }
+            current = current['return'];
+        }
+    }
+
+    return JSON.stringify({found: false, candidateCount: candidates.length});
+})()
+"""
+
+
+async def navigate_to_thread_direct(
+    browser: BrowserPort,
+    target_id: str,
+    thread_id: str,
+    logger: Logger,
+    shutdown: ShutdownCoordinator,
+) -> str | None:
+    """Navigate directly to a meeting chat by clicking its sidebar item.
+
+    Switches to Chat view, then walks the sidebar's React fibre tree
+    to find the chat item whose ``props.chat.id`` matches *thread_id*.
+    If found, clicks it and verifies we landed on a chat.
+
+    This bypasses the search-type-wait-agent-click-verify cycle used
+    by :func:`navigate_to_meeting`, saving ~25 seconds when the chat
+    is visible in the sidebar.
+
+    Args:
+        browser: Browser port.
+        target_id: CDP target ID for the main Teams target.
+        thread_id: Full Teams thread identifier
+            (e.g. ``19:meeting_...@thread.v2``).
+        logger: Logger instance.
+        shutdown: Shutdown coordinator.
+
+    Returns:
+        The chat title (meeting subject) on success, or ``None`` if
+        the chat was not found in the sidebar (caller should fall back
+        to search-based navigation).
+    """
+    await browser.connect(target_id)
+    try:
+        # Switch to Chat view (same as navigate_to_meeting)
+        await _ensure_chat_view(browser, logger, shutdown)
+
+        # Inject the thread_id into the JS template and search the sidebar
+        thread_id_json = json.dumps(thread_id)
+        js = _JS_FIND_SIDEBAR_CHAT.replace("TARGET_THREAD_ID", thread_id_json)
+
+        logger.log("step4-direct", f"Searching sidebar for thread {thread_id[:40]}...")
+        raw = await browser.evaluate(js)
+
+        if not raw:
+            logger.log("step4-direct", "No response from sidebar search.")
+            return None
+
+        result = json.loads(str(raw))
+
+        if not result.get("found"):
+            candidate_count = result.get("candidateCount", 0)
+            logger.log(
+                "step4-direct",
+                f"Thread not found in sidebar ({candidate_count} items inspected). "
+                f"Falling back to search.",
+            )
+            return None
+
+        # Click the matching sidebar item
+        cx, cy = result["x"], result["y"]
+        title = result.get("title", "")
+        logger.log("step4-direct", f"Found chat '{title}' at ({cx}, {cy}). Clicking...")
+
+        await browser.send_command(
+            "Input.dispatchMouseEvent",
+            {
+                "type": "mousePressed",
+                "x": cx,
+                "y": cy,
+                "button": "left",
+                "clickCount": 1,
+            },
+        )
+        await browser.send_command(
+            "Input.dispatchMouseEvent",
+            {
+                "type": "mouseReleased",
+                "x": cx,
+                "y": cy,
+                "button": "left",
+                "clickCount": 1,
+            },
+        )
+
+        # Wait for the chat to load
+        logger.log("step4-direct", "Waiting for meeting chat to load...")
+        await shutdown.interruptible_sleep(3)
+
+        # Verify we landed on a chat view
+        new_title = str(await browser.evaluate("document.title") or "")
+        logger.log("step4-direct", f"Page title after click: {new_title}")
+
+        if _title_is_chat(new_title):
+            logger.log("step4-direct", "Direct navigation succeeded (title confirms chat).")
+            return title
+
+        if await _dom_has_chat_content(browser):
+            logger.log(
+                "step4-direct",
+                "Direct navigation succeeded (DOM has chat content, title may be stale).",
+            )
+            return title
+
+        logger.log(
+            "step4-direct",
+            "Clicked sidebar item but did not reach a chat view. Falling back to search.",
+        )
+        return None
+    finally:
+        await browser.disconnect()
+
+
+async def verify_meeting_thread_id(
+    browser: BrowserPort,
+    target_id: str,
+    expected_thread_id: str,
+    logger: Logger,
+) -> bool:
+    """Verify that the current chat's thread_id matches the expected value.
+
+    After ``navigate_to_meeting`` lands on a chat, this function reads the
+    thread_id from the React fibre tree of the ``chat-topic-menu`` element
+    and compares it against the expected value.  Used to disambiguate when
+    multiple meetings share the same subject.
+
+    Args:
+        browser: Browser port.
+        target_id: CDP target ID for the main Teams target.
+        expected_thread_id: The full thread_id to match.
+        logger: Logger instance.
+
+    Returns:
+        ``True`` if the thread_id matches or could not be read (permissive),
+        ``False`` if it explicitly does not match (caller should retry).
+    """
+    await browser.connect(target_id)
+    try:
+        raw = await browser.evaluate("""
+            (function() {
+                var menu = document.querySelector('[data-tid="chat-topic-menu"]');
+                if (!menu) return JSON.stringify({error: 'no_menu'});
+
+                var fiberKey = Object.keys(menu).find(function(k) {
+                    return k.startsWith('__reactFiber$');
+                });
+                if (!fiberKey) return JSON.stringify({error: 'no_fiber'});
+
+                var current = menu[fiberKey];
+                for (var i = 0; i < 25 && current; i++) {
+                    var props = current.memoizedProps;
+                    if (props && props.chat && props.chat.id) {
+                        return JSON.stringify({threadId: props.chat.id});
+                    }
+                    current = current.return;
+                }
+                return JSON.stringify({error: 'no_chat_id'});
+            })()
+        """)
+        if not raw:
+            logger.log("step4b", "Could not read chat fibre (no response). Proceeding.")
+            return True
+
+        data = json.loads(str(raw))
+        if data.get("error"):
+            logger.log("step4b", f"Could not read thread_id: {data['error']}. Proceeding.")
+            return True
+
+        actual_thread_id = data.get("threadId", "")
+        if actual_thread_id == expected_thread_id:
+            logger.log("step4b", "Thread ID verified.")
+            return True
+
+        # Fallback: compare extracted UUIDs (handles format variations in
+        # the thread_id encoding between build_thread_id and the actual
+        # Teams fibre tree value).
+        from teams_transcripts.domain.mcps import extract_meeting_id
+
+        expected_uuid = extract_meeting_id(expected_thread_id).lower()
+        actual_uuid = extract_meeting_id(actual_thread_id).lower()
+        if expected_uuid and actual_uuid and expected_uuid == actual_uuid:
+            logger.log("step4b", "Thread ID verified (UUID match).")
+            return True
+
+        logger.log(
+            "step4b",
+            f"Thread ID mismatch: expected {expected_thread_id[:40]}..., "
+            f"got {actual_thread_id[:40]}...",
+        )
+        return False
+    finally:
+        await browser.disconnect()
+
+
+# ---------------------------------------------------------------------------
+# Step 5: Navigate to Recap > Transcript
+# ---------------------------------------------------------------------------
+
+
+async def navigate_to_transcript(
+    browser: BrowserPort,
+    agent: AgentPort,
+    target_id: str,
+    config_date: str,
+    config_time: str | None,
+    config_model: str,
+    logger: Logger,
+    shutdown: ShutdownCoordinator,
+    *,
+    format_json: bool = False,
+    require_recap: bool = True,
+    require_transcript: bool = True,
+) -> NavigationResult:
+    """Navigate from meeting chat to the Transcript tab inside Recap.
+
+    For recurring meetings, selects the correct occurrence from the date
+    dropdown.  Extracts the speaker mapping and meeting time text.
+
+    Args:
+        browser: Browser port.
+        agent: Agent port for vision queries (occurrence selection).
+        target_id: CDP target ID for the main Teams target.
+        config_date: Target date as ``YYYY-MM-DD``.
+        config_time: Target time as ``HH:MM``, or ``None``.
+        config_model: LLM model identifier.
+        logger: Logger instance.
+        shutdown: Shutdown coordinator.
+        format_json: Whether to emit JSON error output.
+
+    Returns:
+        A :class:`NavigationResult` with success flag and metadata.
+    """
+    await browser.connect(target_id)
+    try:
+        # Click Recap tab -- check visible tabs first, then overflow menu
+        recap_result = await browser.evaluate("""
+            (function() {
+                var tabs = Array.from(
+                    document.querySelectorAll('[role="tab"]')
+                );
+                var tabNames = tabs.map(function(t) {
+                    return t.textContent.trim();
+                });
+                var recapTab = tabs.find(function(t) {
+                    return t.textContent.indexOf('Recap') !== -1;
+                });
+                if (recapTab) {
+                    recapTab.click();
+                    return 'clicked_recap';
+                }
+                var inRecap = tabNames.some(function(n) {
+                    return n.indexOf('Speakers') !== -1;
+                });
+                if (inRecap) return 'already_in_recap';
+                var overflow = document.querySelector('[data-tid="tab-overflow-button"]');
+                if (overflow) return 'check_overflow';
+                return 'no_recap_tab';
+            })()
+        """)
+        logger.log("step5", f"Recap navigation: {recap_result}")
+
+        # If Recap is hidden behind the overflow menu, click overflow and
+        # look for the Recap menu item.
+        if recap_result == "check_overflow":
+            logger.log("step5", "Recap not in visible tabs; checking overflow menu...")
+            overflow_rect = await browser.evaluate("""
+                JSON.stringify(
+                    document.querySelector('[data-tid="tab-overflow-button"]')
+                        .getBoundingClientRect()
+                )
+            """)
+            import json as _json
+
+            rect = _json.loads(str(overflow_rect))
+            ox = int(rect["x"] + rect["width"] / 2)
+            oy = int(rect["y"] + rect["height"] / 2)
+            await browser.send_command(
+                "Input.dispatchMouseEvent",
+                {
+                    "type": "mousePressed",
+                    "x": ox,
+                    "y": oy,
+                    "button": "left",
+                    "clickCount": 1,
+                },
+            )
+            await browser.send_command(
+                "Input.dispatchMouseEvent",
+                {
+                    "type": "mouseReleased",
+                    "x": ox,
+                    "y": oy,
+                    "button": "left",
+                    "clickCount": 1,
+                },
+            )
+            await shutdown.interruptible_sleep(1)
+
+            recap_result = await browser.evaluate("""
+                (function() {
+                    var menus = document.querySelectorAll('[role="menu"]');
+                    for (var i = 0; i < menus.length; i++) {
+                        var items = menus[i].querySelectorAll(
+                            '[role="menuitem"], [role="menuitemradio"]'
+                        );
+                        for (var j = 0; j < items.length; j++) {
+                            if (items[j].textContent.indexOf('Recap') !== -1) {
+                                items[j].click();
+                                return 'clicked_recap';
+                            }
+                        }
+                    }
+                    return 'no_recap_tab';
+                })()
+            """)
+            logger.log("step5", f"Overflow menu result: {recap_result}")
+
+        if recap_result == "no_recap_tab" and require_recap:
+            exit_error(
+                EXIT_DOWNLOAD_FAILED,
+                "RECAP_NOT_FOUND",
+                "Recap tab not found. The meeting may not have been recorded.",
+                step="step5",
+                format_json=format_json,
+            )
+        if recap_result == "no_recap_tab":
+            logger.log("step5", "Recap tab not found; continuing because Recap is optional.")
+            return NavigationResult(success=True)
+
+        if recap_result == "clicked_recap":
+            logger.log("step5", "Waiting for Recap content to load...")
+            await shutdown.interruptible_sleep(3)
+
+        # Select correct occurrence for recurring meetings
+        occurrence_ok = await _select_correct_occurrence(
+            browser,
+            agent,
+            config_date,
+            config_time,
+            config_model,
+            logger,
+            shutdown,
+            format_json=format_json,
+        )
+        if not occurrence_ok:
+            logger.log("step5", "Target date not available in this chat group.")
+            return NavigationResult(success=False)
+
+        # Extract meeting time text from Recap header
+        meeting_time_text = await browser.evaluate(r"""
+            (function() {
+                var months = 'January|February|March|April|May|June'
+                    + '|July|August|September|October|November|December';
+                var re = new RegExp(
+                    '\\d{1,2}\\s+(' + months + ')\\s+\\d{4}\\s+'
+                    + '\\d{1,2}:\\d{2}\\s*-\\s*\\d{1,2}:\\d{2}', 'i'
+                );
+                var els = document.querySelectorAll('button, span, div');
+                for (var i = 0; i < els.length; i++) {
+                    var t = els[i].textContent.trim();
+                    if (re.test(t) && t.length < 60
+                            && els[i].children.length === 0) {
+                        return t;
+                    }
+                }
+                return '';
+            })()
+        """)
+        if meeting_time_text:
+            logger.log("step5", f"Meeting time: {meeting_time_text}")
+        else:
+            logger.log("step5", "Meeting time text not found in Recap header.")
+
+        # Extract speaker mapping
+        speaker_map = await _extract_speaker_mapping(browser, logger, shutdown)
+        if speaker_map:
+            logger.log("step5", f"Speaker mapping: {len(speaker_map)} speaker(s)")
+            for guid, name in speaker_map.items():
+                logger.log("step5", f"  {guid[:12]}... -> {name}")
+        else:
+            logger.log(
+                "step5",
+                "No speaker mapping available (Speakers tab missing or empty).",
+            )
+
+        if require_transcript:
+            # Click Transcript tab
+            transcript_result = await browser.evaluate("""
+                (function() {
+                    var tabs = Array.from(
+                        document.querySelectorAll('[role="tab"]')
+                    );
+                    var transcriptTab = tabs.find(function(t) {
+                        return t.textContent.indexOf('Transcript') !== -1;
+                    });
+                    if (!transcriptTab) return 'no_transcript_tab';
+                    transcriptTab.click();
+                    return 'clicked_transcript:'
+                        + transcriptTab.getAttribute('aria-selected');
+                })()
+            """)
+            logger.log("step5", f"Transcript navigation: {transcript_result}")
+
+            if transcript_result == "no_transcript_tab":
+                exit_error(
+                    EXIT_DOWNLOAD_FAILED,
+                    "TRANSCRIPT_NOT_FOUND",
+                    "Transcript tab not found. Transcription may not have been enabled.",
+                    step="step5",
+                    format_json=format_json,
+                )
+
+            await shutdown.interruptible_sleep(3)
+        else:
+            logger.log("step5", "Transcript tab skipped because transcript output is disabled.")
+    finally:
+        await browser.disconnect()
+
+    return NavigationResult(
+        success=True,
+        speaker_map=speaker_map,
+        meeting_time_text=str(meeting_time_text or ""),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Internal: occurrence selection
+# ---------------------------------------------------------------------------
+
+
+async def _select_correct_occurrence(
+    browser: BrowserPort,
+    agent: AgentPort,
+    config_date: str,
+    config_time: str | None,
+    config_model: str,
+    logger: Logger,
+    shutdown: ShutdownCoordinator,
+    *,
+    format_json: bool = False,
+) -> bool:
+    """For recurring meetings, select the correct date occurrence.
+
+    Returns ``True`` if the correct occurrence is selected (or it is a
+    single-occurrence meeting), ``False`` if the target date is not
+    available in the dropdown.
+    """
+    occurrence_info = await browser.evaluate("""
+        (function() {
+            var months = 'January|February|March|April|May|June'
+                + '|July|August|September|October|November|December';
+            var dateRe = new RegExp(
+                '\\\\d{1,2}\\\\s+(' + months + ')\\\\s+\\\\d{4}', 'i'
+            );
+            var dateBtn = null;
+            var allBtns = Array.from(document.querySelectorAll('button'));
+            for (var i = 0; i < allBtns.length; i++) {
+                var text = allBtns[i].textContent.trim();
+                if (dateRe.test(text)) {
+                    dateBtn = allBtns[i];
+                    break;
+                }
+            }
+            if (!dateBtn) return JSON.stringify({has_dropdown: false});
+            return JSON.stringify({
+                has_dropdown: true,
+                current_text: dateBtn.textContent.trim().substring(0, 100)
+            });
+        })()
+    """)
+    info = json.loads(str(occurrence_info))
+
+    if not info.get("has_dropdown"):
+        logger.log(
+            "step5",
+            "No occurrence dropdown found (single occurrence meeting).",
+        )
+        return True
+
+    current_text = info.get("current_text", "")
+    logger.log("step5", f"Occurrence dropdown shows: {current_text}")
+
+    # When config_date is empty (speculative direct navigation without
+    # MCPS resolution), we cannot select the correct occurrence.
+    # Return False so the caller falls back to MCPS-based resolution.
+    if not config_date:
+        logger.log(
+            "step5",
+            "Recurring meeting detected but no target date available. "
+            "Falling back to MCPS resolution.",
+        )
+        return False
+
+    dt = date.fromisoformat(config_date)
+    day_str = str(dt.day)
+    month_str = dt.strftime("%B")
+    year_str = str(dt.year)
+
+    if occurrence_matches(current_text, config_date, config_time):
+        logger.log("step5", "Correct occurrence already selected.")
+        dur = parse_occurrence_duration(current_text)
+        if dur:
+            logger.log("step5", f"Meeting duration: {dur}s ({dur // 60}min)")
+        return True
+
+    target_label = f"{day_str} {month_str} {year_str}"
+    if config_time:
+        target_label += f" {config_time}"
+    logger.log(
+        "step5",
+        f"Need to switch to {target_label}. Opening dropdown...",
+    )
+
+    # Click the date dropdown button
+    bbox_json = await browser.evaluate("""
+        (function() {
+            var months = 'January|February|March|April|May|June'
+                + '|July|August|September|October|November|December';
+            var dateRe = new RegExp(
+                '\\\\d{1,2}\\\\s+(' + months + ')\\\\s+\\\\d{4}', 'i'
+            );
+            var allBtns = Array.from(document.querySelectorAll('button'));
+            for (var i = 0; i < allBtns.length; i++) {
+                var text = allBtns[i].textContent.trim();
+                if (dateRe.test(text)) {
+                    var rect = allBtns[i].getBoundingClientRect();
+                    return JSON.stringify({
+                        x: Math.round(rect.left + rect.width / 2),
+                        y: Math.round(rect.top + rect.height / 2)
+                    });
+                }
+            }
+            return JSON.stringify({error: 'not_found'});
+        })()
+    """)
+    bbox = json.loads(str(bbox_json))
+
+    if bbox.get("error"):
+        logger.log("step5", "Could not find date dropdown button.")
+        return False
+
+    await browser.send_command(
+        "Input.dispatchMouseEvent",
+        {
+            "type": "mousePressed",
+            "x": bbox["x"],
+            "y": bbox["y"],
+            "button": "left",
+            "clickCount": 1,
+        },
+    )
+    await browser.send_command(
+        "Input.dispatchMouseEvent",
+        {
+            "type": "mouseReleased",
+            "x": bbox["x"],
+            "y": bbox["y"],
+            "button": "left",
+            "clickCount": 1,
+        },
+    )
+    await shutdown.interruptible_sleep(2)
+
+    # Check if target date is in dropdown
+    dropdown_check = await browser.evaluate(f"""
+        (function() {{
+            var items = Array.from(document.querySelectorAll(
+                '[role="menuitem"], [role="option"], '
+                + '[role="listbox"] > *, [role="menu"] > *'
+            ));
+            var allText = items.map(function(el) {{
+                return el.textContent.trim();
+            }});
+            var hasTarget = allText.some(function(t) {{
+                return t.indexOf('{month_str}') !== -1
+                    && t.indexOf('{year_str}') !== -1;
+            }});
+            return JSON.stringify({{
+                count: items.length,
+                has_target_month: hasTarget,
+                items: allText.slice(0, 10)
+            }});
+        }})()
+    """)
+    dropdown_info = json.loads(str(dropdown_check))
+    logger.log(
+        "step5",
+        f"Dropdown items: {dropdown_info.get('count', 0)}, "
+        f"has target month: {dropdown_info.get('has_target_month', False)}",
+    )
+
+    dropdown_items = dropdown_info.get("items", [])
+    has_precise_match = dropdown_info.get("has_target_month", False) and any(
+        occurrence_matches(item, config_date, config_time) for item in dropdown_items
+    )
+
+    if not has_precise_match:
+        logger.log(
+            "step5",
+            f"Target {target_label} not in dropdown. Available: {dropdown_items[:5]}",
+        )
+        await _dismiss_dropdown(browser)
+        return False
+
+    # Use agent to pick exact occurrence
+    screenshot_bytes = await browser.screenshot()
+    screenshot_b64 = base64.b64encode(screenshot_bytes).decode()
+
+    time_instruction = ""
+    if config_time:
+        time_instruction = (
+            f" The meeting must start at {config_time} -- match both the date AND the start time."
+        )
+
+    prompt = (
+        f"This is a screenshot of a Microsoft Teams recurring meeting's "
+        f"occurrence selector dropdown. I need to select the meeting "
+        f"occurrence from {config_date} ({target_label}). "
+        f"Look at all visible dates and find the one matching "
+        f"{target_label}.{time_instruction} "
+        f"Count the dropdown items from top to bottom starting at 0. "
+        f'Return JSON: {{"index": <n>}} for the correct occurrence, '
+        f'or {{"index": null}} if none match.'
+    )
+
+    logger.log("step5", "Asking agent to identify correct occurrence...")
+    agent_result = agent.vision_query(screenshot_b64, prompt)
+    logger.log("step5", f"Agent response: {agent_result}")
+
+    if not agent_result or agent_result.get("index") is None:
+        logger.log("step5", "Agent could not identify occurrence.")
+        await _dismiss_dropdown(browser)
+        return False
+
+    occurrence_index = agent_result["index"]
+    if not isinstance(occurrence_index, int) or occurrence_index < 0:
+        logger.log("step5", f"Agent returned invalid occurrence index: {occurrence_index!r}")
+        await _dismiss_dropdown(browser)
+        return False
+
+    # Click the correct dropdown option
+    opt_bbox_json = await browser.evaluate(f"""
+        (function() {{
+            var items = Array.from(document.querySelectorAll(
+                '[role="menuitem"], [role="option"], '
+                + '[role="listbox"] > *, [role="menu"] > *'
+            ));
+            var dateItems = items.filter(function(el) {{
+                var months = 'January|February|March|April|May|June'
+                    + '|July|August|September|October|November|December';
+                var re = new RegExp(
+                    '\\\\d{{1,2}}\\\\s+(' + months + ')', 'i'
+                );
+                return re.test(el.textContent);
+            }});
+            if (dateItems.length > {occurrence_index}) {{
+                var rect = dateItems[{occurrence_index}].getBoundingClientRect();
+                return JSON.stringify({{
+                    x: Math.round(rect.left + rect.width / 2),
+                    y: Math.round(rect.top + rect.height / 2),
+                    text: dateItems[{occurrence_index}]
+                        .textContent.trim().substring(0, 80)
+                }});
+            }}
+            if (items.length > {occurrence_index}) {{
+                var rect = items[{occurrence_index}].getBoundingClientRect();
+                return JSON.stringify({{
+                    x: Math.round(rect.left + rect.width / 2),
+                    y: Math.round(rect.top + rect.height / 2),
+                    text: items[{occurrence_index}]
+                        .textContent.trim().substring(0, 80)
+                }});
+            }}
+            return JSON.stringify({{error: 'not_found'}});
+        }})()
+    """)
+    opt_bbox = json.loads(str(opt_bbox_json))
+
+    if opt_bbox.get("error"):
+        logger.log(
+            "step5",
+            f"Could not find occurrence option at index {occurrence_index}.",
+        )
+        return False
+
+    logger.log("step5", f"Clicking occurrence: {opt_bbox.get('text', '?')}")
+    await browser.send_command(
+        "Input.dispatchMouseEvent",
+        {
+            "type": "mousePressed",
+            "x": opt_bbox["x"],
+            "y": opt_bbox["y"],
+            "button": "left",
+            "clickCount": 1,
+        },
+    )
+    await browser.send_command(
+        "Input.dispatchMouseEvent",
+        {
+            "type": "mouseReleased",
+            "x": opt_bbox["x"],
+            "y": opt_bbox["y"],
+            "button": "left",
+            "clickCount": 1,
+        },
+    )
+
+    logger.log("step5", "Waiting for occurrence content to load...")
+    await shutdown.interruptible_sleep(4)
+    dur = parse_occurrence_duration(opt_bbox.get("text", ""))
+    if dur:
+        logger.log("step5", f"Meeting duration: {dur}s ({dur // 60}min)")
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Internal: speaker mapping extraction
+# ---------------------------------------------------------------------------
+
+
+async def _extract_speaker_mapping(
+    browser: BrowserPort,
+    logger: Logger,
+    shutdown: ShutdownCoordinator,
+) -> dict[str, str]:
+    """Extract speaker GUID-to-displayName mapping from the Recap Speakers tab.
+
+    Clicks the Speakers sub-tab, reads React props of each speaker item.
+    Returns a dict mapping bare GUID to display name.
+    """
+    clicked = await browser.evaluate(r"""
+        (function() {
+            var tabs = Array.from(document.querySelectorAll('[role="tab"]'));
+            var speakersTab = tabs.find(function(t) {
+                var txt = t.textContent.trim();
+                return txt === 'Speakers' || txt === 'SpeakersSpeakers';
+            });
+            if (!speakersTab) return 'no_tab';
+            speakersTab.click();
+            return 'clicked';
+        })()
+    """)
+
+    if clicked != "clicked":
+        return {}
+
+    await shutdown.interruptible_sleep(1.5)
+
+    # Click "Show more" if present
+    await browser.evaluate(r"""
+        (function() {
+            var btns = Array.from(document.querySelectorAll('button'));
+            var showMore = btns.find(function(b) {
+                return b.textContent.trim().toLowerCase().indexOf('show more') >= 0
+                    || b.textContent.trim().toLowerCase().indexOf('show all') >= 0;
+            });
+            if (showMore) showMore.click();
+        })()
+    """)
+    await asyncio.sleep(0.5)
+
+    # Extract userId + displayName from React props
+    raw = await browser.evaluate(r"""
+        (function() {
+            var items = document.querySelectorAll(
+                '[data-tid="meeting-recap-speakers-list-item"]'
+            );
+            if (!items.length) return JSON.stringify([]);
+
+            var results = [];
+            items.forEach(function(item) {
+                var fiberKey = Object.keys(item).find(function(k) {
+                    return k.startsWith('__reactFiber$');
+                });
+                if (!fiberKey) return;
+
+                var current = item[fiberKey];
+                var depth = 0;
+                var userId = null;
+                var displayName = null;
+
+                while (current && depth < 15) {
+                    var props = current.memoizedProps || {};
+                    if (props.userId && !userId) userId = props.userId;
+                    if (props.displayName && !displayName)
+                        displayName = props.displayName;
+                    if (userId && displayName) break;
+                    current = current.return;
+                    depth++;
+                }
+
+                if (userId && displayName) {
+                    results.push({
+                        userId: userId, displayName: displayName
+                    });
+                }
+            });
+            return JSON.stringify(results);
+        })()
+    """)
+
+    items = json.loads(str(raw))
+    mapping: dict[str, str] = {}
+    for item in items:
+        uid = item["userId"]
+        guid = uid.split(":")[-1] if ":" in uid else uid
+        mapping[guid] = item["displayName"]
+
+    return mapping
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+async def _dismiss_dropdown(browser: BrowserPort) -> None:
+    """Close an open dropdown by pressing Escape."""
+    await browser.send_command(
+        "Input.dispatchKeyEvent",
+        {
+            "type": "keyDown",
+            "key": "Escape",
+            "code": "Escape",
+            "windowsVirtualKeyCode": 27,
+        },
+    )
+    await browser.send_command(
+        "Input.dispatchKeyEvent",
+        {
+            "type": "keyUp",
+            "key": "Escape",
+            "code": "Escape",
+            "windowsVirtualKeyCode": 27,
+        },
+    )
+
+
+async def _try_meetings_filter(
+    browser: BrowserPort,
+    logger: Logger,
+    shutdown: ShutdownCoordinator,
+) -> tuple[list[dict], str]:
+    """Click the Meetings filter tab and re-extract search results.
+
+    Returns a tuple of ``(search_results, search_mode)``.
+    """
+    logger.log(
+        "step4",
+        "No chat results in panel. Clicking 'Meetings' filter...",
+    )
+    meetings_bbox_json = await browser.evaluate("""
+        (function() {
+            var opts = Array.from(
+                document.querySelectorAll('[role="option"]')
+            );
+            var meetingsOpt = opts.find(function(o) {
+                return o.textContent.trim() === 'Meetings';
+            });
+            if (!meetingsOpt)
+                return JSON.stringify({error: 'not_found'});
+            var rect = meetingsOpt.getBoundingClientRect();
+            return JSON.stringify({
+                x: Math.round(rect.left + rect.width / 2),
+                y: Math.round(rect.top + rect.height / 2)
+            });
+        })()
+    """)
+    meetings_bbox = json.loads(str(meetings_bbox_json))
+
+    if meetings_bbox.get("error"):
+        logger.log("step4", "Could not find 'Meetings' filter tab.")
+        return [], "panel"
+
+    await browser.send_command(
+        "Input.dispatchMouseEvent",
+        {
+            "type": "mousePressed",
+            "x": meetings_bbox["x"],
+            "y": meetings_bbox["y"],
+            "button": "left",
+            "clickCount": 1,
+        },
+    )
+    await browser.send_command(
+        "Input.dispatchMouseEvent",
+        {
+            "type": "mouseReleased",
+            "x": meetings_bbox["x"],
+            "y": meetings_bbox["y"],
+            "button": "left",
+            "clickCount": 1,
+        },
+    )
+    await shutdown.interruptible_sleep(3)
+
+    search_mode = "search_page"
+    results_json = await browser.evaluate("""
+        (function() {
+            var candidates = Array.from(document.querySelectorAll(
+                '[role="listitem"], article, '
+                + '[data-tid*="search-result"], '
+                + '[data-tid*="meeting-result"]'
+            ));
+            if (candidates.length === 0) {
+                candidates = Array.from(
+                    document.querySelectorAll('[role="option"]')
+                ).filter(function(o) {
+                    var t = o.textContent.trim();
+                    var filterRe = /^(Messages|Files|Channels|Group chats|Meetings|Images)$/;
+                    return t.length > 10
+                        && t !== 'View all results'
+                        && !filterRe.test(t)
+                        && t.indexOf('Search Filters') === -1
+                        && !/in:/.test(t);
+                });
+            }
+            var items = [];
+            for (var i = 0; i < candidates.length; i++) {
+                var text = candidates[i].textContent
+                    .trim().substring(0, 120);
+                if (text.length > 5) {
+                    items.push({
+                        id: candidates[i].id || ('result-' + i),
+                        text: text,
+                        optionIndex: i
+                    });
+                }
+            }
+            return JSON.stringify(items);
+        })()
+    """)
+    search_results = json.loads(str(results_json))
+    logger.log(
+        "step4",
+        f"After Meetings filter: {len(search_results)} result(s):",
+    )
+    for sr in search_results:
+        logger.log("step4", f"  [{sr['id'][:20]}] {sr['text'][:70]}")
+
+    return search_results, search_mode