teams-transcripts 0.5.0__py3-none-any.whl

legacy/transcript_download.py

@@ -0,0 +1,3969 @@
+#!/usr/bin/env python3
+"""Download .vtt transcript from Microsoft Teams meetings via CDP.
+
+This script automates the entire transcript download process using the
+Chrome DevTools Protocol (CDP). It connects to Teams' WebView2 instance,
+navigates to the specified meeting, and downloads the transcript as a .vtt
+file. An LLM agent (Claude on Vertex AI) assists with the two non-deterministic
+steps: selecting the correct search result and disambiguating iframe targets.
+
+Two download approaches are supported:
+  A) Native blob interception (when download permission exists)
+  B) DOM extraction from the virtualised transcript list (when blocked)
+
+The approach is auto-detected based on the Download button state.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import contextlib
+import json
+import os
+import re
+import signal
+import sys
+import tempfile
+import time
+import typing
+import urllib.request
+from collections import Counter
+from datetime import date
+
+import websockets
+
+# ---------------------------------------------------------------------------
+# Exit codes
+# ---------------------------------------------------------------------------
+
+EXIT_OK = 0
+EXIT_BAD_ARGS = 1  # Invalid CLI arguments or config
+EXIT_CDP_UNAVAILABLE = 2  # Teams/CDP not running or not responding
+EXIT_MEETING_NOT_FOUND = 3  # Meeting search failed after all retries
+EXIT_DOWNLOAD_FAILED = 4  # Transcript download or permission error
+EXIT_VERIFICATION_FAILED = 5  # Output file invalid
+EXIT_INTERRUPTED = 130  # SIGINT (128 + 2)
+EXIT_TERMINATED = 143  # SIGTERM (128 + 15)
+
+# Module-level output control flags, set by resolve_config().
+_quiet = False
+_verbose = False
+_format_json = False
+
+# Signal handling state.  Set by _handle_signal(); checked in loops.
+_shutdown_requested = False
+_shutdown_signal: int | None = None
+
+
+def _handle_signal(signum: int, _frame: object) -> None:
+    """Handle SIGINT/SIGTERM by setting the shutdown flag.
+
+    The first signal sets the flag so that the next loop iteration exits
+    cleanly.  A second signal (e.g. impatient Ctrl+C) terminates
+    immediately.
+    """
+    global _shutdown_requested, _shutdown_signal
+
+    if _shutdown_requested:
+        # Second signal — force exit.
+        sys.exit(128 + signum)
+
+    _shutdown_requested = True
+    _shutdown_signal = signum
+    sig_name = "SIGINT" if signum == signal.SIGINT else "SIGTERM"
+    print(
+        f"[{sig_name}] Shutdown requested, finishing current step...",
+        file=sys.stderr,
+        flush=True,
+    )
+
+
+def _check_shutdown() -> None:
+    """If a shutdown signal has been received, exit with the appropriate code.
+
+    Call this at the top of long-running loop iterations and between
+    pipeline stages.
+    """
+    if not _shutdown_requested:
+        return
+
+    signum = _shutdown_signal or signal.SIGINT
+    code = EXIT_INTERRUPTED if signum == signal.SIGINT else EXIT_TERMINATED
+    error_code = "INTERRUPTED" if signum == signal.SIGINT else "TERMINATED"
+    sig_name = "SIGINT" if signum == signal.SIGINT else "SIGTERM"
+
+    _exit_error(code, error_code, f"Process terminated by {sig_name}.")
+
+
+async def _interruptible_sleep(seconds: float) -> None:
+    """Sleep in 0.5 s increments, checking for shutdown between each."""
+    remaining = seconds
+    while remaining > 0:
+        chunk = min(remaining, 0.5)
+        await asyncio.sleep(chunk)
+        remaining -= chunk
+        if _shutdown_requested:
+            _check_shutdown()
+
+
+def _interruptible_sleep_sync(seconds: float) -> None:
+    """Synchronous equivalent of :func:`_interruptible_sleep`."""
+    remaining = seconds
+    while remaining > 0:
+        chunk = min(remaining, 0.5)
+        time.sleep(chunk)
+        remaining -= chunk
+        if _shutdown_requested:
+            _check_shutdown()
+
+
+def _install_signal_handlers() -> None:
+    """Register signal handlers for SIGINT and SIGTERM."""
+    signal.signal(signal.SIGINT, _handle_signal)
+    signal.signal(signal.SIGTERM, _handle_signal)
+
+
+# ---------------------------------------------------------------------------
+# Argument parsing and config resolution
+# ---------------------------------------------------------------------------
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        description=(
+            "Download a Microsoft Teams meeting transcript as a WebVTT (.vtt) file.\n"
+            "\n"
+            "Connects to the Teams desktop app via the Chrome DevTools Protocol (CDP),\n"
+            "navigates to the specified meeting's Recap > Transcript tab, and extracts\n"
+            "the transcript.  An LLM agent (Claude via Vertex AI) assists with\n"
+            "non-deterministic UI steps such as search result selection and iframe\n"
+            "disambiguation.\n"
+            "\n"
+            "Two download approaches are supported and auto-detected:\n"
+            "  A) Native blob interception -- used when you have download permission.\n"
+            "     The script clicks the Download button and intercepts the resulting\n"
+            "     blob URL to capture the VTT content byte-for-byte.\n"
+            "  B) React fibre tree extraction -- used when download is blocked.\n"
+            "     The script walks the React component tree to extract all transcript\n"
+            "     entries directly from the in-memory data structure.\n"
+            "\n"
+            "Speaker names are resolved using the Recap Speakers tab.  Vendor-prefixed\n"
+            "names (e.g. 'v-Jane Smith (Acme)') and synthetic placeholders (e.g. '@1')\n"
+            "are replaced with clean display names (e.g. 'Jane Smith', 'Speaker 1')."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "prerequisites:\n"
+            "  1. Microsoft Teams desktop app (macOS) must be running with CDP enabled.\n"
+            "     The script will set the required flags and relaunch Teams automatically\n"
+            "     if CDP is not responding on the configured port.  To launch manually:\n"
+            "       export WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS="
+            "'--remote-debugging-port=9333'\n"
+            "       open -a 'Microsoft Teams'\n"
+            "\n"
+            "  2. Google Cloud Application Default Credentials (ADC) must be configured\n"
+            "     for the Vertex AI project.  The simplest way:\n"
+            "       gcloud auth application-default login\n"
+            "     Or point --adc / GOOGLE_ADC at a service account key file.\n"
+            "\n"
+            "  3. Python dependencies (websockets, anthropic[vertex]) are managed\n"
+            "     by uv.  Run 'uv sync' to install from the lockfile.\n"
+            "\n"
+            "environment variables (used as fallbacks when CLI flags are omitted):\n"
+            "  GOOGLE_CLOUD_PROJECT  GCP project ID for Vertex AI (required if\n"
+            "                        --gcp-project is not provided)\n"
+            "  CLOUD_ML_REGION       Vertex AI region (default: 'global')\n"
+            "  MODEL_ID              Anthropic model ID (default: 'claude-haiku-4-5')\n"
+            "  GOOGLE_ADC            Path to ADC JSON credentials file\n"
+            "\n"
+            "examples:\n"
+            "  # Basic usage -- download a single-occurrence meeting transcript\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Project Kickoff' \\\n"
+            "    --datetime 2026-04-20 \\\n"
+            "    --output ./transcripts/kickoff.vtt \\\n"
+            "    --gcp-project my-vertex-project\n"
+            "\n"
+            "  # Recurring meeting -- the script finds the correct occurrence by date\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Weekly Standup' \\\n"
+            "    --datetime 2026-04-14 \\\n"
+            "    --output ./transcripts/standup-2026-04-14.vtt\n"
+            "\n"
+            "  # Disambiguate two meetings with the same name on the same day\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Weekly Standup' \\\n"
+            "    --datetime 2026-04-14T14:00 \\\n"
+            "    --output ./transcripts/standup-afternoon.vtt\n"
+            "\n"
+            "  # Pipe VTT to stdout (no file written)\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Project Kickoff' \\\n"
+            "    --datetime 2026-04-20 | less\n"
+            "\n"
+            "  # JSON summary with file path\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Project Kickoff' \\\n"
+            "    --datetime 2026-04-20 \\\n"
+            "    --output ./kickoff.vtt --format json\n"
+            "\n"
+            "  # JSON with embedded VTT (no file, agent-friendly)\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Project Kickoff' \\\n"
+            "    --datetime 2026-04-20 --format json\n"
+            "\n"
+            "  # Dry-run -- check meeting exists without downloading\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Weekly Standup' \\\n"
+            "    --datetime 2026-04-14 --dry-run --format json\n"
+            "\n"
+            "  # Quiet mode for cron or agent use\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Weekly Standup' \\\n"
+            "    --datetime 2026-04-14 \\\n"
+            "    --output ./standup.vtt -q\n"
+            "\n"
+            "  # Use a specific model and region\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Quarterly Review' \\\n"
+            "    --datetime 2026-03-31 \\\n"
+            "    --output ./review.vtt \\\n"
+            "    --model claude-sonnet-4-20250514 \\\n"
+            "    --gcp-region us-east5\n"
+            "\n"
+            "how it works:\n"
+            "  Step 1  Verify Teams is running with CDP enabled (relaunch if needed)\n"
+            "  Step 2  Confirm CDP is responding on the configured port\n"
+            "  Step 3  Discover Teams page targets via CDP\n"
+            "  Step 4  Search for the meeting by name and navigate to its chat\n"
+            "  Step 5  Open Recap, select the correct date occurrence, extract\n"
+            "          speaker names, then switch to the Transcript tab\n"
+            "  Step 6  Locate the transcript iframe target\n"
+            "  Step 7  Download the transcript (Approach A or B, auto-detected)\n"
+            "  Step 8  Validate the output VTT file\n"
+            "\n"
+            "notes:\n"
+            "  - The meeting name must match what appears in Teams search results.\n"
+            "    Partial matches work as long as the name is unambiguous.\n"
+            "  - For recurring meetings, the occurrence dropdown must contain the\n"
+            "    target date.  Teams typically retains the most recent ~5 occurrences.\n"
+            "    Older occurrences may no longer be available.\n"
+            "  - The script retries up to 4 times with different search results if\n"
+            "    the first result does not contain the target date.\n"
+            "  - Output file is overwritten if it already exists.\n"
+            "  - --force-restart bypasses the live-call safeguard and may interrupt\n"
+            "    an active call. Use it only when interruption is explicitly intended.\n"
+            "  - All diagnostic output goes to stderr.  stdout carries only data\n"
+            "    (VTT content, or JSON when --format json is set).\n"
+            "  - In JSON mode, the 'file' key is present when --output is given;\n"
+            "    the 'vtt' key is present when --output is omitted (containing the\n"
+            "    full VTT content as a string).  The two keys are mutually exclusive.\n"
+            "\n"
+            "exit codes:\n"
+            "  0    Success\n"
+            "  1    Invalid arguments or missing configuration (BAD_ARGS)\n"
+            "  2    Teams/CDP not running or not responding (CDP_UNAVAILABLE)\n"
+            "  3    Meeting not found after all retries (MEETING_NOT_FOUND)\n"
+            "  4    Transcript download failed (DOWNLOAD_FAILED)\n"
+            "  5    Output file verification failed (VERIFICATION_FAILED)\n"
+            "  130  Interrupted by SIGINT (Ctrl+C)\n"
+            "  143  Terminated by SIGTERM\n"
+            "\n"
+            "output modes:\n"
+            "  --output PATH  --format text   File written, nothing on stdout\n"
+            "  --output PATH  --format json   File written, JSON summary on stdout\n"
+            "  (no --output)  --format text   VTT content on stdout\n"
+            "  (no --output)  --format json   JSON with embedded VTT on stdout\n"
+            "  --dry-run      --format text   Summary logged to stderr\n"
+            "  --dry-run      --format json   JSON metadata on stdout (no VTT)\n"
+            "  --dry-run      --output PATH   Error (incompatible)\n"
+            "\n"
+            "error codes (machine-stable, used in text prefix and JSON 'code' field):\n"
+            "  BAD_ARGS              Invalid CLI arguments or missing config\n"
+            "  CDP_UNAVAILABLE       Teams/CDP not running or not responding\n"
+            "  RESTART_BLOCKED       Teams restart blocked by active/unknown call state\n"
+            "  NO_TARGETS            No Teams page targets found via CDP\n"
+            "  SEARCH_FAILED         Search results did not appear\n"
+            "  MEETING_NOT_FOUND     Meeting not found in search results\n"
+            "  RECAP_NOT_FOUND       Recap tab not found after navigation\n"
+            "  TRANSCRIPT_NOT_FOUND  Transcript tab not found\n"
+            "  IFRAME_NOT_FOUND      No transcript iframe target\n"
+            "  DOWNLOAD_FAILED       VTT download failed\n"
+            "  VERIFICATION_FAILED   Output file is invalid\n"
+            "  INTERRUPTED           Process interrupted by SIGINT\n"
+            "  TERMINATED            Process terminated by SIGTERM\n"
+        ),
+    )
+    p.add_argument(
+        "--meeting",
+        required=True,
+        metavar="NAME",
+        help=(
+            "Meeting name to search for in Teams.  This is typed into the Teams "
+            "search bar, so it should match the meeting title as it appears in the "
+            "Teams UI.  For best results use the full meeting title."
+        ),
+    )
+    p.add_argument(
+        "--datetime",
+        required=True,
+        metavar="YYYY-MM-DD[THH:MM]",
+        dest="datetime",
+        help=(
+            "Target meeting date, optionally with time, in ISO 8601 format. "
+            "Date only (e.g. 2026-04-22) selects the first occurrence on that "
+            "date.  Date with time (e.g. 2026-04-22T14:00) disambiguates when "
+            "there are multiple meetings with the same name on the same day.  "
+            "The time is matched against the start time shown in the Teams "
+            "occurrence dropdown (e.g. '22 April 2026 14:00 - 15:00')."
+        ),
+    )
+    p.add_argument(
+        "--output",
+        default=None,
+        metavar="PATH",
+        help=(
+            "Output file path for the WebVTT (.vtt) transcript.  The file is "
+            "created (or overwritten) at this path.  Parent directories must "
+            "already exist.  When omitted, the VTT content is written to "
+            "stdout (or embedded in the JSON object when --format json)."
+        ),
+    )
+    p.add_argument(
+        "--dry-run",
+        action="store_true",
+        default=False,
+        help=(
+            "Run steps 1-5 (find meeting, verify transcript exists, extract "
+            "roster) then exit without downloading the transcript.  Useful "
+            "for validating that a meeting can be found.  Incompatible with "
+            "--output."
+        ),
+    )
+    p.add_argument(
+        "--gcp-project",
+        default=None,
+        metavar="PROJECT_ID",
+        help=(
+            "Google Cloud project ID for Vertex AI API calls.  Falls back to "
+            "the GOOGLE_CLOUD_PROJECT environment variable.  A value must be "
+            "provided via either this flag or the environment variable."
+        ),
+    )
+    p.add_argument(
+        "--port",
+        type=int,
+        default=9333,
+        metavar="PORT",
+        help=(
+            "CDP remote debugging port that Teams is listening on "
+            "(default: %(default)s).  Must match the value passed to Teams via "
+            "WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS."
+        ),
+    )
+    p.add_argument(
+        "--force-restart",
+        action="store_true",
+        default=False,
+        help=(
+            "Allow Teams to be killed and relaunched even when an active call is "
+            "detected or call state cannot be determined. This may interrupt a live call."
+        ),
+    )
+    p.add_argument(
+        "--gcp-region",
+        default=None,
+        metavar="REGION",
+        help=(
+            "Vertex AI region for model inference (default: 'global').  Falls "
+            "back to the CLOUD_ML_REGION environment variable."
+        ),
+    )
+    p.add_argument(
+        "--model",
+        default=None,
+        metavar="MODEL_ID",
+        help=(
+            "Anthropic model ID for the LLM agent used in non-deterministic "
+            "navigation steps (default: 'claude-haiku-4-5').  Falls back to "
+            "the MODEL_ID environment variable.  Haiku is recommended for speed "
+            "and cost; the agent prompts are simple classification tasks."
+        ),
+    )
+    p.add_argument(
+        "--adc",
+        default=None,
+        metavar="PATH",
+        help=(
+            "Path to a Google Application Default Credentials JSON file.  "
+            "Falls back to the GOOGLE_ADC environment variable, then to "
+            "~/.config/gcloud/application_default_credentials.json."
+        ),
+    )
+
+    verbosity = p.add_mutually_exclusive_group()
+    verbosity.add_argument(
+        "--quiet",
+        "-q",
+        action="store_true",
+        default=False,
+        help="Suppress all diagnostic output on stderr.  Errors and "
+        "structured output (--format json) are still emitted.",
+    )
+    verbosity.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        default=False,
+        help="Emit additional diagnostic detail on stderr (CDP payloads, "
+        "agent prompts, React fibre data sizes).",
+    )
+
+    p.add_argument(
+        "--format",
+        dest="output_format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format on stdout.  'text' (default) emits nothing on "
+        "stdout when --output is given, or raw VTT content when --output "
+        "is omitted.  'json' emits a structured JSON summary.",
+    )
+
+    return p.parse_args()
+
+
+def resolve_config(args: argparse.Namespace) -> dict:
+    """Resolve all configuration from CLI args, env vars, and defaults."""
+    global _quiet, _verbose, _format_json
+
+    _quiet = args.quiet
+    _verbose = args.verbose
+    _format_json = args.output_format == "json"
+
+    project = args.gcp_project or os.environ.get("GOOGLE_CLOUD_PROJECT")
+    if not project:
+        _exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            "--gcp-project not provided and GOOGLE_CLOUD_PROJECT not set.",
+        )
+
+    model = args.model or os.environ.get("MODEL_ID") or "claude-haiku-4-5"
+    region = args.gcp_region or os.environ.get("CLOUD_ML_REGION") or "global"
+    adc = (
+        args.adc
+        or os.environ.get("GOOGLE_ADC")
+        or os.path.expanduser("~/.config/gcloud/application_default_credentials.json")
+    )
+
+    # Parse --datetime: accept YYYY-MM-DD or YYYY-MM-DDTHH:MM
+    dt_raw = args.datetime
+    target_time = None
+    if "T" in dt_raw:
+        date_part, time_part = dt_raw.split("T", 1)
+        # Validate date
+        try:
+            date.fromisoformat(date_part)
+        except ValueError:
+            _exit_error(
+                EXIT_BAD_ARGS,
+                "BAD_ARGS",
+                f"Invalid date '{date_part}'. Expected YYYY-MM-DD.",
+            )
+        # Validate time (HH:MM with valid ranges)
+        if not re.match(r"^\d{2}:\d{2}$", time_part):
+            _exit_error(
+                EXIT_BAD_ARGS,
+                "BAD_ARGS",
+                f"Invalid time format '{time_part}'. Expected HH:MM.",
+            )
+        hh, mm = time_part.split(":")
+        if not (0 <= int(hh) <= 23 and 0 <= int(mm) <= 59):
+            _exit_error(
+                EXIT_BAD_ARGS,
+                "BAD_ARGS",
+                f"Invalid time '{time_part}'. Hours must be 00-23, minutes 00-59.",
+            )
+        target_time = time_part
+        target_date = date_part
+    else:
+        try:
+            date.fromisoformat(dt_raw)
+        except ValueError:
+            _exit_error(
+                EXIT_BAD_ARGS,
+                "BAD_ARGS",
+                f"Invalid date '{dt_raw}'. Expected YYYY-MM-DD or YYYY-MM-DDTHH:MM.",
+            )
+        target_date = dt_raw
+
+    # Validate flag combinations
+    if args.dry_run and args.output:
+        _exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            "--dry-run and --output are incompatible. Dry-run does not produce a file.",
+        )
+
+    # When --output is omitted (and not --dry-run), use a temp file
+    # internally so the file-based pipeline works unchanged.  The temp
+    # file content is written to stdout (or embedded in JSON) at the end.
+    output_to_stdout = not args.dry_run and args.output is None
+    if output_to_stdout:
+        tmp_fd, output_path = tempfile.mkstemp(suffix=".vtt")
+        os.close(tmp_fd)
+    else:
+        output_path = args.output  # None when --dry-run
+
+    return {
+        "meeting": args.meeting,
+        "date": target_date,
+        "time": target_time,
+        "output": output_path,
+        "output_to_stdout": output_to_stdout,
+        "dry_run": args.dry_run,
+        "port": args.port,
+        "force_restart": args.force_restart,
+        "gcp_project": project,
+        "gcp_region": region,
+        "model": model,
+        "adc": adc,
+        "output_format": args.output_format,
+        "quiet": args.quiet,
+        "verbose": args.verbose,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Logging and structured error output
+# ---------------------------------------------------------------------------
+
+
+def log(step: str, msg: str) -> None:
+    """Print a structured log line to stderr.
+
+    Suppressed entirely when ``--quiet`` is active.  All diagnostic output
+    goes to stderr so that stdout is reserved for data (VTT content or JSON).
+    """
+    if not _quiet:
+        print(f"[{step}] {msg}", file=sys.stderr, flush=True)
+
+
+def _exit_error(
+    code: int,
+    error_code: str,
+    message: str,
+    *,
+    step: str | None = None,
+) -> typing.NoReturn:
+    """Emit an actionable error and terminate the process.
+
+    * Always prints a human-readable message to stderr.
+    * When ``--format json`` is active, also emits a JSON error object to
+      stdout so that calling agents can parse the failure without scraping
+      stderr.
+    * ``error_code`` is a short, machine-stable identifier (e.g.
+      ``MEETING_NOT_FOUND``).
+    """
+    # Human-readable on stderr
+    prefix = f"[{error_code}]"
+    print(f"{prefix} {message}", file=sys.stderr, flush=True)
+
+    # Machine-readable on stdout when JSON output is requested
+    if _format_json:
+        payload: dict[str, object] = {
+            "status": "error",
+            "code": error_code,
+            "message": message,
+        }
+        if step:
+            payload["step"] = step
+        print(json.dumps(payload, ensure_ascii=False), flush=True)
+
+    sys.exit(code)
+
+
+# ---------------------------------------------------------------------------
+# CDP HTTP helpers
+# ---------------------------------------------------------------------------
+
+
+def cdp_http_get(port: int, path: str) -> dict | list | None:
+    """GET a CDP HTTP endpoint, return parsed JSON or None on failure."""
+    url = f"http://localhost:{port}{path}"
+    try:
+        with urllib.request.urlopen(url, timeout=5) as resp:  # noqa: S310
+            return json.loads(resp.read())
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# CDP WebSocket helpers
+# ---------------------------------------------------------------------------
+
+
+class CDPConnection:
+    """Manages a CDP WebSocket connection with message ID tracking."""
+
+    def __init__(self, ws):
+        self._ws = ws
+        self._msg_id = 0
+
+    async def send(self, method: str, params: dict | None = None, timeout: float = 15):
+        """Send a CDP command and wait for the matching response."""
+        self._msg_id += 1
+        mid = self._msg_id
+        await self._ws.send(
+            json.dumps(
+                {
+                    "id": mid,
+                    "method": method,
+                    "params": params or {},
+                }
+            )
+        )
+        while True:
+            raw = await asyncio.wait_for(self._ws.recv(), timeout=timeout)
+            data = json.loads(raw)
+            if "id" in data and data["id"] == mid:
+                return data
+
+    async def evaluate(self, expression: str, timeout: float = 15):
+        """Shorthand for Runtime.evaluate, returns the result value."""
+        resp = await self.send(
+            "Runtime.evaluate",
+            {"expression": expression},
+            timeout=timeout,
+        )
+        return resp.get("result", {}).get("result", {}).get("value")
+
+    async def drain(self, timeout: float = 0.5):
+        """Drain any pending messages from the WebSocket."""
+        try:
+            while True:
+                await asyncio.wait_for(self._ws.recv(), timeout=timeout)
+        except (asyncio.TimeoutError, TimeoutError):
+            pass
+
+    async def screenshot(self) -> str:
+        """Take a screenshot via CDP, return base64 PNG data."""
+        resp = await self.send("Page.captureScreenshot", {"format": "png"})
+        return resp.get("result", {}).get("data", "")
+
+
+async def connect_to_target(port: int, target_id: str) -> tuple:
+    """Connect to a CDP target, return (websocket, CDPConnection)."""
+    ws_url = f"ws://localhost:{port}/devtools/page/{target_id}"
+    ws = await websockets.connect(ws_url, max_size=16 * 1024 * 1024)
+    return ws, CDPConnection(ws)
+
+
+# ---------------------------------------------------------------------------
+# Agent (LLM) helpers
+# ---------------------------------------------------------------------------
+
+
+def create_agent_client(config: dict):
+    """Create an AnthropicVertex client from resolved config."""
+    os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = config["adc"]
+    from anthropic import AnthropicVertex
+
+    return AnthropicVertex(
+        project_id=config["gcp_project"],
+        region=config["gcp_region"],
+    )
+
+
+def agent_vision_query(client, model: str, image_b64: str, prompt: str) -> dict | None:
+    """Send a single-turn vision query to the agent. Returns parsed JSON or None."""
+    try:
+        response = client.messages.create(
+            model=model,
+            max_tokens=512,
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "image",
+                            "source": {
+                                "type": "base64",
+                                "media_type": "image/png",
+                                "data": image_b64,
+                            },
+                        },
+                        {"type": "text", "text": prompt},
+                    ],
+                }
+            ],
+        )
+        text = response.content[0].text.strip()
+        # Extract JSON from response (may be wrapped in markdown code fences)
+        json_match = re.search(r"\{[^}]+\}", text)
+        if json_match:
+            return json.loads(json_match.group())
+        return None
+    except Exception as e:
+        log("agent", f"Vision query failed: {e}")
+        return None
+
+
+def agent_text_query(client, model: str, prompt: str) -> dict | None:
+    """Send a single-turn text query to the agent. Returns parsed JSON or None."""
+    try:
+        response = client.messages.create(
+            model=model,
+            max_tokens=512,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        text = response.content[0].text.strip()
+        json_match = re.search(r"\{[^}]+\}", text)
+        if json_match:
+            return json.loads(json_match.group())
+        return None
+    except Exception as e:
+        log("agent", f"Text query failed: {e}")
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Step 1: Ensure Teams is running with CDP enabled
+# ---------------------------------------------------------------------------
+
+
+def ensure_teams_running(port: int, *, force: bool = False) -> None:
+    """Use the shared guarded restart path when CDP is unavailable."""
+    from teams_transcripts.adapters.cdp.teams import ensure_teams_running as guarded_ensure
+
+    class LegacyLogger:
+        @staticmethod
+        def log(step: str, msg: str) -> None:
+            log(step, msg)
+
+    class LegacyShutdown:
+        interruptible_sleep_sync = staticmethod(_interruptible_sleep_sync)
+
+    guarded_ensure(
+        port,
+        logger=LegacyLogger(),
+        shutdown=LegacyShutdown(),
+        format_json=_format_json,
+        force=force,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Step 2: Verify CDP is responding
+# ---------------------------------------------------------------------------
+
+
+def verify_cdp(port: int) -> str:
+    """Verify CDP is responding and return the browser version string."""
+    for attempt in range(5):
+        _check_shutdown()
+        version = cdp_http_get(port, "/json/version")
+        if isinstance(version, dict) and "Browser" in version:
+            browser = version["Browser"]
+            log("step2", f"CDP verified: {browser}")
+            return browser
+        log("step2", f"Attempt {attempt + 1}/5 -- waiting...")
+        _interruptible_sleep_sync(3)
+
+    _exit_error(
+        EXIT_CDP_UNAVAILABLE,
+        "CDP_UNAVAILABLE",
+        "CDP did not respond after 5 attempts. Check Teams is running.",
+        step="step2",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Step 3: Find main Teams CDP target
+# ---------------------------------------------------------------------------
+
+
+def find_teams_targets(port: int) -> list[dict]:
+    """Return all CDP targets that are main Teams pages (not workers)."""
+    targets = cdp_http_get(port, "/json")
+    if not targets:
+        _exit_error(
+            EXIT_CDP_UNAVAILABLE,
+            "CDP_UNAVAILABLE",
+            "Could not list CDP targets.",
+            step="step3",
+        )
+
+    results = []
+    for t in targets:
+        url = t.get("url", "")
+        if "teams.microsoft.com/v2" in url and "worker" not in url:
+            results.append(t)
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Step 4: Navigate to meeting (agent-assisted)
+# ---------------------------------------------------------------------------
+
+
+async def find_search_target(port: int, targets: list[dict]) -> str | None:
+    """Find which CDP target has the Teams search input element."""
+    for t in targets:
+        try:
+            ws, cdp = await connect_to_target(port, t["id"])
+            async with ws:
+                result = await cdp.evaluate("!!document.querySelector('#ms-searchux-input')")
+                if result is True:
+                    log("step4", f"Search input found on target: {t['id'][:20]}...")
+                    return t["id"]
+        except Exception:  # noqa: S112, PERF203
+            continue
+    return None
+
+
+async def type_text_via_cdp(cdp: CDPConnection, text: str) -> None:
+    """Type text character by character using Input.dispatchKeyEvent."""
+    for char in text:
+        await cdp.send(
+            "Input.dispatchKeyEvent",
+            {
+                "type": "keyDown",
+                "text": char,
+                "key": char,
+                "code": f"Key{char.upper()}" if char.isalpha() else "",
+                "windowsVirtualKeyCode": ord(char.upper()) if char.isalpha() else ord(char),
+            },
+        )
+        await cdp.send(
+            "Input.dispatchKeyEvent",
+            {
+                "type": "keyUp",
+                "key": char,
+                "code": f"Key{char.upper()}" if char.isalpha() else "",
+                "windowsVirtualKeyCode": ord(char.upper()) if char.isalpha() else ord(char),
+            },
+        )
+        await asyncio.sleep(0.05)
+
+
+async def navigate_to_meeting(
+    port: int,
+    targets: list[dict],
+    config: dict,
+    agent_client,
+    result_index_override: int | None = None,
+) -> str | None:
+    """Navigate to the meeting chat. Returns the target ID used, or None
+    if the requested result_index_override is out of range.
+
+    If *result_index_override* is given, skip the agent call and click
+    the search result at that index directly (used for retries when the
+    first chat group turns out to be the wrong recurring-meeting instance).
+    """
+    # 4a: Find the target with the search input
+    search_target_id = await find_search_target(port, targets)
+    if not search_target_id:
+        _exit_error(
+            EXIT_CDP_UNAVAILABLE,
+            "NO_TARGETS",
+            "Could not find Teams search input on any CDP target.",
+            step="step4",
+        )
+
+    ws, cdp = await connect_to_target(port, search_target_id)
+    async with ws:
+        # 4b: Ensure we are in the Chat view (not Search results or a
+        # meeting chat) so the search suggestion popup works correctly.
+        # Use the Ctrl+3 keyboard shortcut (Teams: "Chat (Ctrl+3)").
+        log("step4", "Switching to Chat view (Ctrl+3)...")
+        await cdp.send(
+            "Input.dispatchKeyEvent",
+            {
+                "type": "keyDown",
+                "key": "3",
+                "code": "Digit3",
+                "windowsVirtualKeyCode": 51,
+                "modifiers": 2,  # Ctrl
+            },
+        )
+        await cdp.send(
+            "Input.dispatchKeyEvent",
+            {
+                "type": "keyUp",
+                "key": "3",
+                "code": "Digit3",
+                "windowsVirtualKeyCode": 51,
+            },
+        )
+        await _interruptible_sleep(2)
+
+        # Dismiss any open popups/dropdowns
+        await cdp.send(
+            "Input.dispatchKeyEvent",
+            {
+                "type": "keyDown",
+                "key": "Escape",
+                "code": "Escape",
+                "windowsVirtualKeyCode": 27,
+            },
+        )
+        await cdp.send(
+            "Input.dispatchKeyEvent",
+            {
+                "type": "keyUp",
+                "key": "Escape",
+                "code": "Escape",
+                "windowsVirtualKeyCode": 27,
+            },
+        )
+        await asyncio.sleep(0.5)
+
+        # Focus the search input and clear it using the React-compatible
+        # nativeInputValueSetter technique (setting .value directly
+        # doesn't update React-controlled inputs).
+        await cdp.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)
+
+        log("step4", f"Typing meeting name: {config['meeting']}")
+        await type_text_via_cdp(cdp, config["meeting"])
+
+        # 4c: Wait for search results to appear.
+        # Teams has TWO search UI modes:
+        #   Mode A (popup): Quick suggestions as ms-searchux-popup-N elements.
+        #   Mode B (panel): Expanded search panel with [role="option"] elements
+        #        that have random IDs (appears after first search or from
+        #        within a chat context). Shows filter tabs (Messages, Files,
+        #        etc.) plus result items.
+        # We wait until we see either:
+        #   - ms-searchux-popup-N items that aren't "Search Filters", OR
+        #   - [role="option"] elements whose text matches the meeting name.
+        log("step4", "Waiting for search results...")
+        meeting_name_lower = config["meeting"].lower()
+        search_mode = None
+        for _ in range(20):
+            await asyncio.sleep(0.5)
+            result = await cdp.evaluate(f"""
+                (function() {{
+                    // Mode A: popup suggestions
+                    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';
+                        }}
+                    }}
+                    // Mode B: expanded search panel option elements
+                    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_lower[:20]}') !== -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",
+            )
+
+        await _interruptible_sleep(1)  # let results fully render
+        log("step4", f"Search UI mode: {search_mode}")
+
+        # 4c-ii: Enumerate available results depending on mode.
+        # Build a list of result items as [{id, text, element_selector}].
+        if search_mode == "popup":
+            results_json = await cdp.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:
+            # Panel mode: get [role="option"] elements, excluding filter
+            # tabs (Messages, Files, Channels, etc.), "View all results",
+            # and search suggestions (items containing "in:" filter syntax).
+            filter_words = [
+                "Messages",
+                "Files",
+                "Channels",
+                "Group chats",
+                "Meetings",
+                "Images",
+                "View all results",
+                "Search Filters",
+            ]
+            results_json = await cdp.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;
+                            }
+                        }
+                        // Detect search suggestions: items that contain "in:"
+                        // filter syntax (e.g. "forin:Channel" or "textin:scope").
+                        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(results_json)
+        log("step4", f"Found {len(search_results)} search result(s):")
+        for sr in search_results:
+            log("step4", f"  [{sr['id'][:20]}] {sr['text'][:70]}")
+
+        # If panel mode returned no results (all were filter tabs or
+        # search suggestions), click the "Meetings" filter tab to get
+        # meeting-specific results, then re-extract.
+        if search_mode == "panel" and len(search_results) == 0:
+            log("step4", "No chat results in panel. Clicking 'Meetings' filter...")
+            meetings_bbox_json = await cdp.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(meetings_bbox_json)
+
+            if meetings_bbox.get("error"):
+                log("step4", "Could not find 'Meetings' filter tab.")
+            else:
+                await cdp.send(
+                    "Input.dispatchMouseEvent",
+                    {
+                        "type": "mousePressed",
+                        "x": meetings_bbox["x"],
+                        "y": meetings_bbox["y"],
+                        "button": "left",
+                        "clickCount": 1,
+                    },
+                )
+                await cdp.send(
+                    "Input.dispatchMouseEvent",
+                    {
+                        "type": "mouseReleased",
+                        "x": meetings_bbox["x"],
+                        "y": meetings_bbox["y"],
+                        "button": "left",
+                        "clickCount": 1,
+                    },
+                )
+                await _interruptible_sleep(3)
+
+                # Switch to "search_page" mode -- the full search results
+                # page shows results as listitem or article elements.
+                search_mode = "search_page"
+                results_json = await cdp.evaluate("""
+                    (function() {
+                        // On the search results page, results may be list items,
+                        // articles, or divs with data-tid attributes.
+                        var candidates = Array.from(document.querySelectorAll(
+                            '[role="listitem"], article, '
+                            + '[data-tid*="search-result"], '
+                            + '[data-tid*="meeting-result"]'
+                        ));
+                        // Also try any [role="option"] that appeared after filter
+                        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(results_json)
+                log("step4", f"After Meetings filter: {len(search_results)} result(s):")
+                for sr in search_results:
+                    log("step4", f"  [{sr['id'][:20]}] {sr['text'][:70]}")
+
+        # 4d: Determine which result to click
+        if result_index_override is not None:
+            result_index = result_index_override
+            log("step4", f"Using override result index: {result_index}")
+        elif search_mode == "panel":
+            # In panel mode we already have structured text for each result.
+            # Match by meeting name using word-overlap scoring.  Teams'
+            # search panel can inject filter annotations (e.g. "in:") into
+            # the textContent, garbling exact matches.  We also use
+            # substring matching to handle concatenated words (e.g.
+            # "CallAdrian" should match the word "Call").
+            name_words = set(re.findall(r"\w+", config["meeting"].lower()))
+            best_idx, best_score = 0, 0
+            for i, sr in enumerate(search_results):
+                result_text_lower = sr["text"].lower()
+                result_words = set(re.findall(r"\w+", result_text_lower))
+                # Exact word overlap
+                overlap = len(name_words & result_words)
+                # Substring match for words not in exact overlap
+                for nw in name_words - result_words:
+                    if nw in result_text_lower:
+                        overlap += 1
+                # Tiebreaker: prefer results that start with the meeting
+                # name (meeting chat entries) over messages about the
+                # meeting from individuals (which start with "Name:").
+                # Subtract 0.5 if the result text starts with a person's
+                # name followed by a colon (e.g. "Tim: Recap: ...").
+                score = overlap
+                if re.match(r"^[A-Z][a-z]+:", sr["text"]):
+                    score -= 0.5
+                if score > best_score:
+                    best_score = score
+                    best_idx = i
+            result_index = best_idx
+            log(
+                "step4",
+                f"Word-overlap match: index {result_index} (score {best_score}/{len(name_words)})",
+            )
+        else:
+            # Popup mode: use the agent to identify the correct result
+            log("step4", "Taking screenshot of search results...")
+            screenshot_b64 = await cdp.screenshot()
+
+            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 participant "
+                f"names but not dates) and calendar/meeting entries (showing dates). "
+                f"Chat entries are preferred for transcript downloads. "
+                f"If the exact date is not visible in the results, pick the first "
+                f"chat result whose name matches the meeting name. "
+                f"Count the results from top to bottom starting at 0. "
+                f"Return a JSON object with a single key 'index' set to the 0-based "
+                f"index of the correct result to click, or null if NO result matches "
+                f"the meeting name at all. "
+                f'For example: {{"index": 0}} or {{"index": null}}'
+            )
+            log("step4", "Asking agent to identify correct search result...")
+            agent_result = agent_vision_query(agent_client, config["model"], screenshot_b64, prompt)
+            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",
+                )
+
+            result_index = agent_result["index"]
+
+        # 4e: Check that the requested index exists
+        if result_index >= len(search_results):
+            if result_index_override is not None:
+                log(
+                    "step4",
+                    f"Search result index {result_index} out of range "
+                    f"(only {len(search_results)} results). No more results to try.",
+                )
+                return None
+            _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",
+            )
+
+        target_result = search_results[result_index]
+        target_id_attr = target_result.get("id", "")
+
+        # 4f: Get the bounding box of the result item and click it.
+        # Use getElementById (not querySelector with #id) because some
+        # Teams element IDs start with digits, which breaks CSS selectors.
+        log(
+            "step4",
+            f"Selecting result index {result_index}: {target_result['text'][:60]}...",
+        )
+        if target_id_attr and not target_id_attr.startswith("option-"):
+            # Use getElementById for elements with an actual ID
+            bbox_json = await cdp.evaluate(f"""
+                (function() {{
+                    var item = document.getElementById('{target_id_attr}');
+                    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:
+            # Fallback: use nth [role="option"] by optionIndex
+            oi = target_result.get("optionIndex", 0)
+            bbox_json = await cdp.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(bbox_json)
+
+        if bbox.get("error"):
+            log("step4", f"Could not find element for result at index {result_index}.")
+            return None
+
+        cx, cy = bbox["x"], bbox["y"]
+        log("step4", f"Clicking at ({cx}, {cy}) on {bbox['id']}...")
+
+        # CDP-level mouse click: mousePressed + mouseReleased
+        await cdp.send(
+            "Input.dispatchMouseEvent",
+            {
+                "type": "mousePressed",
+                "x": cx,
+                "y": cy,
+                "button": "left",
+                "clickCount": 1,
+            },
+        )
+        await cdp.send(
+            "Input.dispatchMouseEvent",
+            {
+                "type": "mouseReleased",
+                "x": cx,
+                "y": cy,
+                "button": "left",
+                "clickCount": 1,
+            },
+        )
+
+        # 4g: Wait for navigation to the meeting chat
+        log("step4", "Waiting for meeting chat to load...")
+        await _interruptible_sleep(5)
+
+        # Verify navigation reached a chat (not the Search results page
+        # or some other non-chat view).
+        new_title = await cdp.evaluate("document.title")
+        log("step4", f"Page title after navigation: {new_title}")
+
+        is_chat = (
+            "| Chat" in new_title
+            or "| Copilot" in new_title
+            or "| Communities" in new_title
+            or new_title.startswith(("Chat |", "Copilot |", "Communities"))
+        )
+        if "Search |" in new_title or not is_chat:
+            log(
+                "step4",
+                "Navigation did not reach a meeting chat. "
+                "Result may be a file, channel, or filter -- not a chat entry.",
+            )
+            return None
+
+    return search_target_id
+
+
+# ---------------------------------------------------------------------------
+# Step 5: Navigate to Recap > Transcript
+# ---------------------------------------------------------------------------
+
+
+def _parse_occurrence_duration(text: str) -> int | None:
+    """Parse meeting duration in seconds from occurrence dropdown text.
+
+    Expected format: '17 April 2026 19:30 -  20:00' or similar.
+    Returns duration in seconds, or None if unparseable.
+    """
+    m = re.search(r"(\d{1,2}):(\d{2})\s*-\s*(\d{1,2}):(\d{2})", text)
+    if not m:
+        return None
+    start_min = int(m.group(1)) * 60 + int(m.group(2))
+    end_min = int(m.group(3)) * 60 + int(m.group(4))
+    if end_min <= start_min:
+        end_min += 24 * 60  # crosses midnight
+    return (end_min - start_min) * 60
+
+
+async def navigate_to_transcript(port: int, target_id: str, config: dict, agent_client) -> bool:
+    """Navigate from meeting chat to the Transcript tab inside Recap.
+
+    For recurring meetings, uses the agent to select the correct
+    occurrence from the date dropdown.
+
+    Returns True if navigation succeeded, False if the target date
+    occurrence was not found (caller should try a different search result).
+    """
+    ws, cdp = await connect_to_target(port, target_id)
+    async with ws:
+        # Always attempt to click Recap first, even if Speakers tabs are
+        # visible -- they may be stale from a previous meeting. If a Recap
+        # tab exists (meaning we're at the chat-level tabs), click it.
+        # If only Recap-internal tabs are visible (Speakers, Transcript etc.)
+        # and no top-level Recap tab exists, we're already in the right view.
+        recap_result = await cdp.evaluate("""
+            (function() {
+                var tabs = Array.from(document.querySelectorAll('[role="tab"]'));
+                var tabNames = tabs.map(function(t) { return t.textContent.trim(); });
+                // Look for a top-level Recap tab to click
+                var recapTab = tabs.find(function(t) {
+                    return t.textContent.indexOf('Recap') !== -1;
+                });
+                if (recapTab) {
+                    recapTab.click();
+                    return 'clicked_recap';
+                }
+                // No Recap tab -- check if we're already inside Recap view
+                var inRecap = tabNames.some(function(n) {
+                    return n.indexOf('Speakers') !== -1;
+                });
+                if (inRecap) return 'already_in_recap';
+                return 'no_recap_tab';
+            })()
+        """)
+        log("step5", f"Recap navigation: {recap_result}")
+
+        if recap_result == "no_recap_tab":
+            _exit_error(
+                EXIT_DOWNLOAD_FAILED,
+                "RECAP_NOT_FOUND",
+                "Recap tab not found. The meeting may not have been recorded.",
+                step="step5",
+            )
+
+        if recap_result == "clicked_recap":
+            log("step5", "Waiting for Recap content to load...")
+            await _interruptible_sleep(3)
+
+        # Check if this is a recurring meeting and select the correct occurrence
+        occurrence_ok = await _select_correct_occurrence(cdp, config, agent_client)
+        if not occurrence_ok:
+            log("step5", "Target date not available in this chat group.")
+            return False
+
+        # Extract meeting date/time from the Recap header.
+        # Both recurring (dropdown button) and single-occurrence meetings
+        # show the date and time range in a leaf SPAN or DIV element
+        # matching "DD Month YYYY HH:MM - HH:MM".
+        meeting_time_text = await cdp.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:
+            config["meeting_time_text"] = meeting_time_text
+            log("step5", f"Meeting time: {meeting_time_text}")
+        else:
+            log("step5", "Meeting time text not found in Recap header.")
+
+        # Extract speaker mapping from the Recap Speakers section.
+        # This gives us the display names shown in the Teams UI (e.g.
+        # "Speaker 1" instead of the raw "@1" from the transcript data).
+        speaker_map = await _extract_speaker_mapping(cdp)
+        if speaker_map:
+            config["speaker_map"] = speaker_map
+            log("step5", f"Speaker mapping: {len(speaker_map)} speaker(s)")
+            for guid, name in speaker_map.items():
+                log("step5", f"  {guid[:12]}... -> {name}")
+        else:
+            log("step5", "No speaker mapping available (Speakers tab missing or empty).")
+
+        # Click the Transcript tab
+        transcript_result = await cdp.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');
+            })()
+        """)
+        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",
+            )
+
+        # Wait for transcript content to load
+        await _interruptible_sleep(3)
+
+    return True
+
+
+async def _extract_speaker_mapping(cdp: CDPConnection) -> dict[str, str]:
+    """Extract speaker GUID-to-displayName mapping from the Recap Speakers tab.
+
+    Clicks the Speakers sub-tab within Recap, then reads the React props
+    of each ``meeting-recap-speakers-list-item`` element to extract the
+    ``userId`` (format ``8:orgid:{GUID}``) and ``displayName``.
+
+    Returns a dict mapping bare GUID -> displayName (e.g.
+    ``{"1d678236-a80b-...": "Speaker 1"}``).  Returns an empty dict if
+    the Speakers tab is not present or has no items.
+    """
+    # Click the Speakers sub-tab
+    clicked = await cdp.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 _interruptible_sleep(1.5)
+
+    # Some meetings may show a truncated speaker list with a "Show more"
+    # button.  Click it if present so all speakers are rendered.
+    await cdp.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 of each speaker item
+    raw = await cdp.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(raw)
+    mapping = {}
+    for item in items:
+        # userId format: "8:orgid:{GUID}" -- extract the GUID
+        uid = item["userId"]
+        guid = uid.split(":")[-1] if ":" in uid else uid
+        mapping[guid] = item["displayName"]
+
+    return mapping
+
+
+async def _select_correct_occurrence(cdp: CDPConnection, config: dict, agent_client) -> bool:
+    """For recurring meetings, select the correct date occurrence.
+
+    Returns True if the correct occurrence is selected (or it's a single
+    occurrence meeting), False if the target date is not available.
+    """
+    # Check for the occurrence/date dropdown
+    occurrence_info = await cdp.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(occurrence_info)
+
+    if not info.get("has_dropdown"):
+        log("step5", "No occurrence dropdown found (single occurrence meeting).")
+        return True
+
+    current_text = info.get("current_text", "")
+    log("step5", f"Occurrence dropdown shows: {current_text}")
+
+    # Check if the target date is already displayed
+    target_date = config["date"]
+    target_time = config["time"]
+    dt = date.fromisoformat(target_date)
+    day_str = str(dt.day)
+    month_str = dt.strftime("%B")
+    year_str = str(dt.year)
+
+    def _occurrence_matches(text: str) -> bool:
+        """Check if an occurrence dropdown text matches the target date/time."""
+        if not (day_str in text and month_str in text and year_str in text):
+            return False
+        if target_time is None:
+            return True
+        # Match the start time in text like "22 April 2026 11:15 -  12:00".
+        # The target_time is "HH:MM" and must appear before the separator.
+        sep_idx = text.find("-")
+        if sep_idx == -1:
+            return target_time in text
+        return target_time in text[:sep_idx]
+
+    if _occurrence_matches(current_text):
+        log("step5", "Correct occurrence already selected.")
+        dur = _parse_occurrence_duration(current_text)
+        if dur:
+            log("step5", f"Meeting duration: {dur}s ({dur // 60}min)")
+        return True
+
+    target_label = f"{day_str} {month_str} {year_str}"
+    if target_time:
+        target_label += f" {target_time}"
+    log("step5", f"Need to switch to {target_label}. Opening dropdown...")
+
+    # Click the date dropdown button
+    bbox_json = await cdp.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(bbox_json)
+
+    if bbox.get("error"):
+        log("step5", "Could not find date dropdown button.")
+        return False
+
+    await cdp.send(
+        "Input.dispatchMouseEvent",
+        {
+            "type": "mousePressed",
+            "x": bbox["x"],
+            "y": bbox["y"],
+            "button": "left",
+            "clickCount": 1,
+        },
+    )
+    await cdp.send(
+        "Input.dispatchMouseEvent",
+        {
+            "type": "mouseReleased",
+            "x": bbox["x"],
+            "y": bbox["y"],
+            "button": "left",
+            "clickCount": 1,
+        },
+    )
+    await _interruptible_sleep(2)
+
+    # Check if the target date is in the dropdown items (text-based check
+    # before bothering the agent)
+    dropdown_check = await cdp.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(dropdown_check)
+    log(
+        "step5",
+        f"Dropdown items: {dropdown_info.get('count', 0)}, "
+        f"has target month: {dropdown_info.get('has_target_month', False)}",
+    )
+
+    # Coarse JS check found the target month/year -- now do a precise
+    # Python-side check that also validates day and optional time.
+    dropdown_items = dropdown_info.get("items", [])
+    has_precise_match = dropdown_info.get("has_target_month", False) and any(
+        _occurrence_matches(item) for item in dropdown_items
+    )
+
+    if not has_precise_match:
+        log(
+            "step5",
+            f"Target {target_label} not in dropdown. Available: {dropdown_items[:5]}",
+        )
+        # Close the dropdown
+        await cdp.send(
+            "Input.dispatchKeyEvent",
+            {
+                "type": "keyDown",
+                "key": "Escape",
+                "code": "Escape",
+                "windowsVirtualKeyCode": 27,
+            },
+        )
+        await cdp.send(
+            "Input.dispatchKeyEvent",
+            {
+                "type": "keyUp",
+                "key": "Escape",
+                "code": "Escape",
+                "windowsVirtualKeyCode": 27,
+            },
+        )
+        return False
+
+    # Target month is in the dropdown -- use the agent to pick the exact one
+    screenshot_b64 = await cdp.screenshot()
+
+    time_instruction = ""
+    if target_time:
+        time_instruction = (
+            f" The meeting must start at {target_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.'
+    )
+
+    log("step5", "Asking agent to identify correct occurrence...")
+    agent_result = agent_vision_query(agent_client, config["model"], screenshot_b64, prompt)
+    log("step5", f"Agent response: {agent_result}")
+
+    if not agent_result or agent_result.get("index") is None:
+        log("step5", "Agent could not identify occurrence.")
+        await cdp.send(
+            "Input.dispatchKeyEvent",
+            {
+                "type": "keyDown",
+                "key": "Escape",
+                "code": "Escape",
+                "windowsVirtualKeyCode": 27,
+            },
+        )
+        await cdp.send(
+            "Input.dispatchKeyEvent",
+            {
+                "type": "keyUp",
+                "key": "Escape",
+                "code": "Escape",
+                "windowsVirtualKeyCode": 27,
+            },
+        )
+        return False
+
+    occurrence_index = agent_result["index"]
+
+    # Click the correct dropdown option
+    opt_bbox_json = await cdp.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(opt_bbox_json)
+
+    if opt_bbox.get("error"):
+        log("step5", f"Could not find occurrence option at index {occurrence_index}.")
+        return False
+
+    log("step5", f"Clicking occurrence: {opt_bbox.get('text', '?')}")
+    await cdp.send(
+        "Input.dispatchMouseEvent",
+        {
+            "type": "mousePressed",
+            "x": opt_bbox["x"],
+            "y": opt_bbox["y"],
+            "button": "left",
+            "clickCount": 1,
+        },
+    )
+    await cdp.send(
+        "Input.dispatchMouseEvent",
+        {
+            "type": "mouseReleased",
+            "x": opt_bbox["x"],
+            "y": opt_bbox["y"],
+            "button": "left",
+            "clickCount": 1,
+        },
+    )
+
+    log("step5", "Waiting for occurrence content to load...")
+    await _interruptible_sleep(4)
+    dur = _parse_occurrence_duration(opt_bbox.get("text", ""))
+    if dur:
+        log("step5", f"Meeting duration: {dur}s ({dur // 60}min)")
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Step 6: Find the transcript iframe's CDP target (agent-assisted)
+# ---------------------------------------------------------------------------
+
+
+def find_xplatplugins_targets(port: int) -> list[dict]:
+    """Find all xplatplugins SharePoint iframe CDP targets."""
+    targets = cdp_http_get(port, "/json")
+    if not targets:
+        return []
+
+    matches = []
+    for t in targets:
+        url = t.get("url", "")
+        if "sharepoint" in url and "xplatplugins" in url:
+            matches.append(t)
+    return matches
+
+
+def find_iframe_target(
+    port: int, config: dict, agent_client, pre_nav_iframe_ids: set[str] | None = None
+) -> str:
+    """Find the correct xplatplugins iframe target. Uses agent if ambiguous.
+
+    If pre_nav_iframe_ids is provided, prefer targets that appeared AFTER
+    navigation (i.e., not in the pre-existing set).
+    """
+    log("step6", "Looking for transcript iframe target...")
+    pre_nav_iframe_ids = pre_nav_iframe_ids or set()
+
+    # Retry a few times as the iframe may still be loading
+    matches = []
+    new_matches = []
+    for attempt in range(10):
+        _check_shutdown()
+        matches = find_xplatplugins_targets(port)
+        new_matches = [t for t in matches if t["id"] not in pre_nav_iframe_ids]
+        if new_matches:
+            break
+        if matches and attempt >= 5:
+            # After 5 attempts, if we have targets but none are new,
+            # the meeting might reuse an existing iframe
+            log("step6", "No new iframe targets appeared. Using existing targets.")
+            new_matches = matches
+            break
+        label = "new iframe" if matches else "any iframe"
+        log("step6", f"Waiting for {label} target (attempt {attempt + 1}/10)...")
+        _interruptible_sleep_sync(2)
+
+    # Use new targets if available, otherwise fall back to all
+    candidates = new_matches or matches
+
+    if not candidates:
+        _exit_error(
+            EXIT_DOWNLOAD_FAILED,
+            "IFRAME_NOT_FOUND",
+            "No xplatplugins iframe target found. "
+            "Check that Step 5 completed and the Transcript tab loaded.",
+            step="step6",
+        )
+
+    if len(candidates) == 1:
+        tid = candidates[0]["id"]
+        is_new = tid not in pre_nav_iframe_ids
+        log("step6", f"{'New' if is_new else 'Existing'} iframe target: {tid[:20]}...")
+        return tid
+
+    # Multiple targets -- ask the agent
+    log("step6", f"{len(candidates)} iframe targets to choose from. Asking agent...")
+
+    target_list = "\n".join(
+        f"  [{i}] ID: {t['id']}, URL: {t['url'][:200]}" for i, t in enumerate(candidates)
+    )
+    prompt = (
+        f"Multiple SharePoint iframe targets were found in a Teams CDP session. "
+        f"I am looking for the transcript of the meeting "
+        f"'{config['meeting']}' on {config['date']}.\n\n"
+        f"Targets:\n{target_list}\n\n"
+        f"Which target most likely corresponds to this meeting? "
+        f"Look at the URL paths for clues (e.g., organiser name, meeting context). "
+        f'Return JSON: {{"target_id": "<full target ID>"}} '
+        f"for the best match."
+    )
+
+    result = agent_text_query(agent_client, config["model"], prompt)
+    log("step6", f"Agent response: {result}")
+
+    if result and result.get("target_id"):
+        # Validate the agent's choice is actually one of our targets
+        for t in candidates:
+            if t["id"] == result["target_id"]:
+                log("step6", f"Agent selected target: {t['id'][:20]}...")
+                return t["id"]
+        # Partial match (agent may have truncated)
+        for t in candidates:
+            if result["target_id"] in t["id"] or t["id"] in result["target_id"]:
+                log("step6", f"Agent selected target (partial match): {t['id'][:20]}...")
+                return t["id"]
+
+    # Fallback: use the last target (most recently created)
+    log("step6", "Agent could not disambiguate. Using most recent target.")
+    return candidates[-1]["id"]
+
+
+# ---------------------------------------------------------------------------
+# Step 7: Check download permission
+# ---------------------------------------------------------------------------
+
+
+async def check_permission(port: int, target_id: str) -> str:
+    """Check the Download button state. Returns 'has_permission',
+    'no_permission', or 'no_button'."""
+    ws, cdp = await connect_to_target(port, target_id)
+    async with ws:
+        for attempt in range(5):
+            _check_shutdown()
+            result_json = await cdp.evaluate("""
+                (function() {
+                    var btn = document.querySelector('button[aria-haspopup="true"]');
+                    if (!btn) return JSON.stringify({state: "no_button"});
+                    var text = btn.textContent || "";
+                    if (text.indexOf("permission") !== -1)
+                        return JSON.stringify({
+                            state: "no_permission",
+                            message: text.trim().substring(0, 100)
+                        });
+                    return JSON.stringify({state: "has_permission"});
+                })()
+            """)
+            if result_json:
+                result = json.loads(result_json)
+                log("step7", f"Permission state: {result['state']}")
+                if result.get("message"):
+                    log("step7", f"Message: {result['message']}")
+                return result["state"]
+            log("step7", f"Attempt {attempt + 1}/5 -- waiting for button...")
+            await _interruptible_sleep(2)
+
+    return "no_button"
+
+
+# ---------------------------------------------------------------------------
+# Step 7A: Native download via blob interception
+# ---------------------------------------------------------------------------
+
+
+async def download_native_vtt(port: int, target_id: str, output_path: str) -> bool:
+    """Download the transcript via blob interception. Returns True on success."""
+    ws, cdp = await connect_to_target(port, target_id)
+    async with ws:
+        # 1. Monkey-patch URL.createObjectURL to capture VTT blob content
+        patch_result = await cdp.evaluate("""
+            (function() {
+                window.__capturedVTT = null;
+                var origCreateObjectURL = URL.createObjectURL;
+                URL.createObjectURL = function(blob) {
+                    if (blob instanceof Blob) {
+                        blob.text().then(function(text) {
+                            if (text.indexOf('WEBVTT') !== -1) {
+                                window.__capturedVTT = text;
+                            }
+                        });
+                    }
+                    return origCreateObjectURL.call(URL, blob);
+                };
+                return 'interceptor installed';
+            })()
+        """)
+        log("step7a", f"Blob interceptor: {patch_result}")
+
+        # 2. Open the Download dropdown menu
+        menu_result_json = await cdp.evaluate("""
+            (function() {
+                var btn = document.querySelector('button[aria-haspopup="true"]');
+                if (!btn) return JSON.stringify({error: 'Download button not found'});
+                if (btn.getAttribute('aria-expanded') !== 'true') btn.click();
+                return JSON.stringify({ok: true});
+            })()
+        """)
+        menu_result = json.loads(menu_result_json)
+        if menu_result.get("error"):
+            log("step7a", f"Error: {menu_result['error']}")
+            return False
+        log("step7a", "Download menu opened")
+
+        # 3. Wait for menu to render, drain pending messages
+        await _interruptible_sleep(1)
+        await cdp.drain()
+
+        # 4. Click "Download as .vtt"
+        click_result_json = await cdp.evaluate("""
+            (function() {
+                var vttBtn = document.querySelector(
+                    'button[aria-label="Download as .vtt"]'
+                );
+                if (!vttBtn) {
+                    var allBtns = Array.from(
+                        document.querySelectorAll('button[role="menuitem"]')
+                    );
+                    vttBtn = allBtns.find(function(b) {
+                        return b.textContent && b.textContent.indexOf('.vtt') !== -1;
+                    });
+                }
+                if (!vttBtn) return JSON.stringify({error: 'VTT menu item not found'});
+                vttBtn.click();
+                return JSON.stringify({ok: true});
+            })()
+        """)
+        click_result = json.loads(click_result_json)
+        if click_result.get("error"):
+            log("step7a", f"Error: {click_result['error']}")
+            return False
+        log("step7a", "Clicked 'Download as .vtt'")
+
+        # 5. Wait for the blob to be captured
+        log("step7a", "Waiting for VTT blob capture...")
+        await _interruptible_sleep(3)
+        await cdp.drain()
+
+        # 6. Check if the VTT was captured
+        status_json = await cdp.evaluate("""
+            (function() {
+                if (window.__capturedVTT) {
+                    return JSON.stringify({
+                        captured: true,
+                        length: window.__capturedVTT.length
+                    });
+                }
+                return JSON.stringify({captured: false});
+            })()
+        """)
+        status = json.loads(status_json)
+
+        if not status.get("captured"):
+            log("step7a", "VTT blob was not captured.")
+            return False
+
+        length = status["length"]
+        log("step7a", f"Captured {length} chars of VTT content")
+
+        # 7. Retrieve content in chunks (large transcripts may exceed
+        #    the single-expression return limit)
+        chunks = []
+        chunk_size = 50000
+        for offset in range(0, length, chunk_size):
+            chunk = await cdp.evaluate(
+                f"window.__capturedVTT.substring({offset}, {offset + chunk_size})"
+            )
+            chunks.append(chunk)
+
+        vtt_content = "".join(chunks)
+
+        # 8. Write to output path
+        with open(output_path, "w") as f:
+            f.write(vtt_content)
+
+        file_size = os.path.getsize(output_path)
+        log("step7a", f"Written {file_size} bytes to {output_path}")
+        return True
+
+
+# ---------------------------------------------------------------------------
+# Step 7B: DOM extraction (when download is blocked by permissions)
+# ---------------------------------------------------------------------------
+
+
+async def _extract_via_react_props(
+    port: int,
+    target_id: str,
+    output_path: str,
+    speaker_map: dict[str, str] | None = None,
+) -> bool | None:
+    """Try to extract transcript data from the React fibre tree.
+
+    The TranscriptList component holds all entries in its ``entries``
+    prop, bypassing the virtualised list renderer entirely.  All Text
+    entries are extracted — no duration filtering is applied.
+
+    If *speaker_map* is provided (GUID -> display name), speaker names
+    are resolved using it before generating VTT.
+
+    Returns True if successful, None if the React props aren't
+    accessible (caller should fall back to DOM scrolling).
+    """
+    ws, cdp = await connect_to_target(port, target_id)
+    async with ws:
+        entries_json = await cdp.evaluate(r"""
+            (function() {
+                var el = document.querySelector('[role="list"]');
+                if (!el) return JSON.stringify({error: 'no list element'});
+                var fiberKey = Object.keys(el).find(function(k) {
+                    return k.startsWith('__reactFiber$');
+                });
+                if (!fiberKey) return JSON.stringify({error: 'no fiber key'});
+
+                // Walk up the fibre tree to find the component with
+                // an 'entries' prop (TranscriptList at ~depth 9).
+                var current = el[fiberKey];
+                var depth = 0;
+                var entries = null;
+                while (current && depth < 25) {
+                    var props = current.memoizedProps || {};
+                    if (props.entries && Array.isArray(props.entries)
+                        && props.entries.length > 0) {
+                        entries = props.entries;
+                        break;
+                    }
+                    current = current.return;
+                    depth++;
+                }
+                if (!entries)
+                    return JSON.stringify({error: 'entries not found'});
+
+                function parseDur(d) {
+                    if (!d) return null;
+                    var m = d.match(/PT(?:(\d+)H)?(?:(\d+)M)?(?:([\d.]+)S)?/);
+                    if (!m) return null;
+                    return (parseInt(m[1]||0)*3600)
+                         + (parseInt(m[2]||0)*60)
+                         + parseFloat(m[3]||0);
+                }
+
+                var result = [];
+                for (var i = 0; i < entries.length; i++) {
+                    var e = entries[i];
+                    if (e.type !== 'Text') continue;
+                    var ts = parseDur(e.timestamp);
+                    result.push({
+                        speaker: e.speakerDisplayName || 'Unknown',
+                        speakerId: e.speakerId || '',
+                        ts: ts,
+                        text: e.text || ''
+                    });
+                }
+                return JSON.stringify({ok: true, items: result});
+            })()
+        """)
+
+    data = json.loads(entries_json)
+
+    if data.get("error"):
+        log("step7b", f"React props extraction failed: {data['error']}")
+        return None
+
+    items = data["items"]
+    if not items:
+        log("step7b", "React props returned 0 text entries.")
+        return None
+
+    log("step7b", f"React props: extracted {len(items)} text entries")
+
+    # Resolve speaker names using the Recap Speakers mapping.
+    # Transcript entries have speakerId like "{GUID}@{tenant}" -- extract
+    # the GUID and look it up in the mapping for a better display name.
+    #
+    # The Recap Speakers section shows the canonical display name for
+    # each speaker (e.g. "Gabor Veres"), while the transcript data often
+    # has vendor-prefixed names (e.g. "v-Gabor Veres (Metosin)") or
+    # synthetic placeholders ("@1").  Always prefer the Recap name.
+    if speaker_map:
+        resolved_pairs = {}  # old_name -> new_name (for logging)
+        for item in items:
+            sid = item.get("speakerId", "")
+            guid = sid.split("@")[0] if "@" in sid else sid
+            if guid not in speaker_map:
+                continue
+            recap_name = speaker_map[guid]
+            transcript_name = item["speaker"]
+            if recap_name == transcript_name:
+                continue
+            item["speaker"] = recap_name
+            resolved_pairs[transcript_name] = recap_name
+        if resolved_pairs:
+            for old, new in resolved_pairs.items():
+                log("step7b", f"  Resolved speaker: {old!r} -> {new!r}")
+            total = sum(1 for it in items if it["speaker"] in resolved_pairs.values())
+            log(
+                "step7b",
+                f"Resolved {len(resolved_pairs)} speaker name(s) ({total} entries affected)",
+            )
+
+    # Filter out meta entries
+    segments = []
+    for item in items:
+        text = item["text"]
+        if "started transcription" in text or "stopped transcription" in text:
+            continue
+        segments.append(item)
+
+    # Generate VTT
+    def sec_to_vtt(s):
+        s = max(0, s)
+        h = int(s) // 3600
+        m = (int(s) % 3600) // 60
+        sec = int(s) % 60
+        ms = int((s % 1) * 1000)
+        return f"{h:02d}:{m:02d}:{sec:02d}.{ms:03d}"
+
+    vtt = ["WEBVTT", ""]
+    for i, seg in enumerate(segments):
+        ss = seg["ts"] if seg["ts"] is not None else 0
+        es = segments[i + 1]["ts"] if i + 1 < len(segments) else ss + 10
+        if es is None or es <= ss:
+            es = ss + 10
+        vtt.extend(
+            [
+                str(i + 1),
+                f"{sec_to_vtt(ss)} --> {sec_to_vtt(es)}",
+                f"<v {seg['speaker']}>{seg['text']}</v>",
+                "",
+            ]
+        )
+
+    content = "\n".join(vtt)
+    with open(output_path, "w") as f:
+        f.write(content)
+
+    log("step7b", f"Written {len(content)} bytes, {len(segments)} segments")
+    log("step7b", "Speakers:")
+    for sp, cnt in Counter(s["speaker"] for s in segments).most_common():
+        log("step7b", f"  {sp}: {cnt}")
+
+    return True
+
+
+async def extract_dom_vtt(port: int, target_id: str, output_path: str) -> bool:
+    """Extract transcript from the DOM and generate a .vtt file."""
+    headers = {}  # headerNum -> {speaker, timestamp}
+    texts = {}  # textNum -> {text, headerNum}
+    header_to_texts = {}  # headerNum -> set of textNums
+    orphaned_texts = []
+
+    ws, cdp = await connect_to_target(port, target_id)
+    async with ws:
+        # Scroll to top of transcript list
+        await cdp.evaluate("""
+            (function() {
+                var el = document.querySelector('[role="list"]');
+                var p = el;
+                while (p && p.scrollHeight <= p.clientHeight) p = p.parentElement;
+                if (p) p.scrollTop = 0;
+            })()
+        """)
+        await asyncio.sleep(0.5)
+
+        # Scroll through the virtualised list, extracting entries.
+        # Use scrollIntoView on the last visible item to advance.
+        # Use block:'center' to avoid overshooting at the end of the list.
+        consecutive_empty = 0
+        for scroll_pass in range(200):
+            items_json = await cdp.evaluate("""
+                (function() {
+                    var items = Array.from(
+                        document.querySelectorAll('[role="listitem"]')
+                    );
+                    var result = [];
+                    var currentHeaderNum = null;
+                    for (var i = 0; i < items.length; i++) {
+                        var id = items[i].id || '';
+                        var num = parseInt(id.replace(/[^0-9]/g, ''));
+                        if (id.startsWith('itemHeader')) {
+                            currentHeaderNum = num;
+                            result.push({
+                                type: 'h', n: num,
+                                s: items[i].querySelector(
+                                    '[class*="itemDisplayName"]'
+                                )?.textContent?.trim(),
+                                t: items[i].querySelector(
+                                    '[class*="baseTimestamp"] span[aria-hidden]'
+                                )?.textContent?.trim()
+                            });
+                        } else if (id.startsWith('sub-entry')) {
+                            result.push({
+                                type: 'e', n: num, hn: currentHeaderNum,
+                                x: items[i].textContent?.trim()
+                            });
+                        }
+                    }
+                    // Scroll the last item to viewport centre to advance
+                    if (items.length > 0) {
+                        items[items.length - 1].scrollIntoView(
+                            {behavior: 'instant', block: 'center'}
+                        );
+                    }
+                    return JSON.stringify(result);
+                })()
+            """)
+            items = json.loads(items_json)
+
+            new_count = 0
+            for item in items:
+                if item["type"] == "h" and item["n"] not in headers:
+                    headers[item["n"]] = {
+                        "speaker": item["s"],
+                        "timestamp": item["t"],
+                    }
+                    new_count += 1
+                elif item["type"] == "e" and item["n"] not in texts:
+                    texts[item["n"]] = {
+                        "text": item["x"],
+                        "headerNum": item.get("hn"),
+                    }
+                    new_count += 1
+                    hn = item.get("hn")
+                    if hn is None:
+                        orphaned_texts.append(item["n"])
+                    else:
+                        if hn not in header_to_texts:
+                            header_to_texts[hn] = set()
+                        header_to_texts[hn].add(item["n"])
+
+            if scroll_pass % 10 == 0:
+                log(
+                    "step7b",
+                    f"Pass {scroll_pass}: +{new_count} | headers={len(headers)} texts={len(texts)}",
+                )
+
+            if new_count == 0:
+                consecutive_empty += 1
+            else:
+                consecutive_empty = 0
+
+            if consecutive_empty >= 3 and scroll_pass >= 3:
+                log("step7b", f"Extraction complete at pass {scroll_pass}")
+                break
+
+            await asyncio.sleep(0.25)
+
+    # Diagnostic: log header/text number ranges and gaps
+    if headers:
+        h_nums = sorted(headers.keys())
+        t_nums = sorted(texts.keys())
+        log(
+            "step7b",
+            f"Header IDs: min={h_nums[0]} max={h_nums[-1]} count={len(h_nums)}",
+        )
+        log("step7b", f"Text IDs: min={t_nums[0]} max={t_nums[-1]} count={len(t_nums)}")
+        # Check for gaps in header numbering
+        h_gaps = []
+        for i in range(1, len(h_nums)):
+            gap = h_nums[i] - h_nums[i - 1]
+            if gap > 1:
+                h_gaps.append((h_nums[i - 1], h_nums[i], gap))
+        if h_gaps:
+            log("step7b", f"Header gaps: {h_gaps[:10]}")
+        # Check for gaps in text numbering
+        t_gaps = []
+        for i in range(1, len(t_nums)):
+            gap = t_nums[i] - t_nums[i - 1]
+            if gap > 1:
+                t_gaps.append((t_nums[i - 1], t_nums[i], gap))
+        if t_gaps:
+            log("step7b", f"Text gaps: {t_gaps[:10]}")
+
+    # Sort text lists per header
+    for hn in header_to_texts:
+        header_to_texts[hn] = sorted(header_to_texts[hn])
+
+    if orphaned_texts:
+        log(
+            "step7b",
+            f"WARNING: {len(orphaned_texts)} sub-entries had no header "
+            f"in view: {orphaned_texts[:5]}...",
+        )
+
+    # Convert to VTT
+    def ts_to_sec(ts):
+        if not ts:
+            return None
+        parts = ts.split(":")
+        if len(parts) == 2:
+            return int(parts[0]) * 60 + int(parts[1])
+        if len(parts) == 3:
+            return int(parts[0]) * 3600 + int(parts[1]) * 60 + int(parts[2])
+        return 0
+
+    def sec_to_vtt(s):
+        return f"{s // 3600:02d}:{(s % 3600) // 60:02d}:{s % 60:02d}.000"
+
+    # Build ordered segments
+    segments = []
+    null_ts_count = 0
+    for hn in sorted(header_to_texts.keys()):
+        h = headers.get(hn, {})
+        ts_raw = h.get("timestamp")
+        ts_sec = ts_to_sec(ts_raw)
+        if ts_sec is None:
+            null_ts_count += 1
+        for tn in header_to_texts[hn]:
+            t = texts.get(tn, {})
+            text = t.get("text", "")
+            # Skip meta-entries
+            if "started transcription" in text or "stopped transcription" in text:
+                continue
+            segments.append(
+                {
+                    "speaker": h.get("speaker", "Unknown"),
+                    "ts_sec": ts_sec,
+                    "text": text,
+                }
+            )
+
+    if null_ts_count > 0:
+        log(
+            "step7b",
+            f"WARNING: {null_ts_count} headers had null/empty timestamps.",
+        )
+
+    # Forward-fill null timestamps
+    last_good = None
+    for seg in segments:
+        if seg["ts_sec"] is not None:
+            last_good = seg["ts_sec"]
+        elif last_good is not None:
+            seg["ts_sec"] = last_good + 10
+            last_good = seg["ts_sec"]
+
+    # Backfill remaining nulls
+    next_good = None
+    for seg in reversed(segments):
+        if seg["ts_sec"] is not None:
+            next_good = seg["ts_sec"]
+        elif next_good is not None:
+            seg["ts_sec"] = max(0, next_good - 10)
+            next_good = seg["ts_sec"]
+
+    # Final fallback
+    for seg in segments:
+        if seg["ts_sec"] is None:
+            seg["ts_sec"] = 0
+
+    # Detect timestamp discontinuities caused by virtualised scroll
+    # artefacts.  If a timestamp jumps by more than 10 minutes from the
+    # previous segment AND the jump is to a timestamp more than 2x the
+    # running max, discard from that point onwards.
+    if len(segments) > 2:
+        running_max = 0
+        cut_at = None
+        for i, seg in enumerate(segments):
+            ts = seg["ts_sec"]
+            if i > 0 and ts is not None and running_max > 0:
+                gap = ts - running_max
+                if gap > 600 and ts > running_max * 2:
+                    log(
+                        "step7b",
+                        f"WARNING: Timestamp discontinuity at segment {i}: "
+                        f"{sec_to_vtt(running_max)} -> {sec_to_vtt(ts)} "
+                        f"(gap {gap:.0f}s). Truncating {len(segments) - i} "
+                        f"segment(s).",
+                    )
+                    cut_at = i
+                    break
+            if ts is not None and ts > running_max:
+                running_max = ts
+        if cut_at is not None:
+            segments = segments[:cut_at]
+
+    # Generate VTT content
+    vtt = ["WEBVTT", ""]
+    for i, seg in enumerate(segments):
+        ss = seg["ts_sec"]
+        es = segments[i + 1]["ts_sec"] if i + 1 < len(segments) else ss + 10
+        if es <= ss:
+            es = ss + 10
+        vtt.extend(
+            [
+                str(i + 1),
+                f"{sec_to_vtt(ss)} --> {sec_to_vtt(es)}",
+                f"<v {seg['speaker']}>{seg['text']}</v>",
+                "",
+            ]
+        )
+
+    content = "\n".join(vtt)
+    with open(output_path, "w") as f:
+        f.write(content)
+
+    log("step7b", f"Written {len(content)} bytes, {len(segments)} segments")
+    log("step7b", "Speakers:")
+    for sp, cnt in Counter(s["speaker"] for s in segments).most_common():
+        log("step7b", f"  {sp}: {cnt}")
+
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Step 8: Verify the output
+# ---------------------------------------------------------------------------
+
+
+# ---------------------------------------------------------------------------
+# Multi-part support helpers
+# ---------------------------------------------------------------------------
+
+
+async def _detect_part_tabs(port: int, target_id: str) -> int:
+    """Detect Part N tabs in the Recap view.
+
+    Returns the number of parts (1 if no Part tabs are present, meaning
+    a single-part meeting).
+    """
+    ws, cdp = await connect_to_target(port, target_id)
+    async with ws:
+        count_json = await cdp.evaluate(r"""
+            (function() {
+                var tabs = Array.from(document.querySelectorAll('[role="tab"]'));
+                var parts = tabs.filter(function(t) {
+                    return /^Part\s*\d/i.test(t.textContent.trim());
+                });
+                return JSON.stringify({count: parts.length});
+            })()
+        """)
+    data = json.loads(count_json)
+    return max(1, data.get("count", 0))
+
+
+async def _click_part_and_transcript(port: int, target_id: str, part_number: int) -> bool:
+    """Click the Part N tab and then the Transcript sub-tab.
+
+    Returns True if both clicks succeeded.
+    """
+    ws, cdp = await connect_to_target(port, target_id)
+    async with ws:
+        # Click the Part tab
+        part_result = await cdp.evaluate(rf"""
+            (function() {{
+                var tabs = Array.from(document.querySelectorAll('[role="tab"]'));
+                var partTab = tabs.find(function(t) {{
+                    return /^Part\s*{part_number}($|Part)/i.test(t.textContent.trim());
+                }});
+                if (!partTab) return 'no_part_tab';
+                partTab.click();
+                return 'clicked_part';
+            }})()
+        """)
+        log("multi-part", f"Part {part_number} tab: {part_result}")
+
+        if part_result == "no_part_tab":
+            return False
+
+        # Wait for the part content to load
+        await _interruptible_sleep(2)
+
+        # Click the Transcript sub-tab
+        transcript_result = await cdp.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';
+            })()
+        """)
+        log("multi-part", f"Transcript tab for Part {part_number}: {transcript_result}")
+
+        if transcript_result == "no_transcript_tab":
+            return False
+
+        # Wait for transcript iframe to load
+        await _interruptible_sleep(3)
+
+    return True
+
+
+def _parse_vtt_timestamp(ts: str) -> float:
+    """Parse a VTT timestamp (HH:MM:SS.mmm) to seconds."""
+    parts = ts.split(":")
+    h = int(parts[0])
+    m = int(parts[1])
+    s_ms = parts[2].split(".")
+    s = int(s_ms[0])
+    ms = int(s_ms[1]) if len(s_ms) > 1 else 0
+    return h * 3600 + m * 60 + s + ms / 1000
+
+
+def _format_vtt_timestamp(seconds: float) -> str:
+    """Format seconds as a VTT timestamp (HH:MM:SS.mmm)."""
+    seconds = max(0.0, seconds)
+    h = int(seconds) // 3600
+    m = (int(seconds) % 3600) // 60
+    s = int(seconds) % 60
+    ms = int((seconds % 1) * 1000)
+    return f"{h:02d}:{m:02d}:{s:02d}.{ms:03d}"
+
+
+def _merge_vtt_parts(vtt_contents: list[str]) -> str:
+    """Merge multiple VTT file contents into a single VTT.
+
+    Each part's timestamps are offset so that Part 2 continues from
+    Part 1's last cue end time, and so on.  Cues are renumbered
+    sequentially across all parts.
+
+    Args:
+        vtt_contents: list of VTT file contents (strings), one per part.
+
+    Returns:
+        Merged VTT content as a single string.
+    """
+    timestamp_re = re.compile(r"(\d{2}:\d{2}:\d{2}\.\d{3})\s*-->\s*(\d{2}:\d{2}:\d{2}\.\d{3})")
+
+    all_cues: list[tuple[float, float, list[str]]] = []
+    cumulative_offset = 0.0
+
+    for part_idx, vtt_text in enumerate(vtt_contents):
+        lines = vtt_text.split("\n")
+        part_cues: list[tuple[float, float, list[str]]] = []
+
+        i = 0
+        while i < len(lines):
+            line = lines[i].strip()
+            ts_match = timestamp_re.match(line)
+            if ts_match:
+                start = _parse_vtt_timestamp(ts_match.group(1))
+                end = _parse_vtt_timestamp(ts_match.group(2))
+                # Collect cue content lines (everything until next blank line)
+                content_lines = []
+                i += 1
+                while i < len(lines) and lines[i].strip():
+                    content_lines.append(lines[i])
+                    i += 1
+                part_cues.append(
+                    (start + cumulative_offset, end + cumulative_offset, content_lines)
+                )
+            else:
+                i += 1
+
+        # Update offset: next part starts after this part's last cue end
+        if part_cues:
+            last_end = max(end for _, end, _ in part_cues)
+            cumulative_offset = last_end
+            log(
+                "multi-part",
+                f"Part {part_idx + 1}: {len(part_cues)} cues, "
+                f"ends at {_format_vtt_timestamp(last_end)}",
+            )
+
+        all_cues.extend(part_cues)
+
+    # Build merged VTT
+    result = ["WEBVTT", ""]
+    for idx, (start, end, content_lines) in enumerate(all_cues, 1):
+        result.append(str(idx))
+        result.append(f"{_format_vtt_timestamp(start)} --> {_format_vtt_timestamp(end)}")
+        result.extend(content_lines)
+        result.append("")
+
+    return "\n".join(result)
+
+
+# ---------------------------------------------------------------------------
+# Chat message extraction
+# ---------------------------------------------------------------------------
+
+
+def _strip_html_to_text(html: str) -> str:
+    """Convert HTML message content to plain text.
+
+    Handles common Teams message markup: ``<p>``, ``<br>``, ``<div>``,
+    ``<a href="...">``, ``<span>``, and HTML entities.  Strips all other
+    tags.  Returns empty string for blank or whitespace-only content.
+    """
+    import html as html_mod
+
+    if not html:
+        return ""
+
+    text = html
+
+    # Convert block-level elements to newlines
+    text = re.sub(r"<br\s*/?>", "\n", text, flags=re.IGNORECASE)
+    text = re.sub(r"</p>", "\n", text, flags=re.IGNORECASE)
+    text = re.sub(r"</div>", "\n", text, flags=re.IGNORECASE)
+    text = re.sub(r"</li>", "\n", text, flags=re.IGNORECASE)
+
+    # Extract link text with URL: <a href="URL">text</a> -> text (URL)
+    text = re.sub(
+        r'<a\s[^>]*href="([^"]*)"[^>]*>([^<]*)</a>',
+        r"\2 (\1)",
+        text,
+        flags=re.IGNORECASE,
+    )
+
+    # Remove all remaining HTML tags
+    text = re.sub(r"<[^>]+>", "", text)
+
+    # Decode HTML entities
+    text = html_mod.unescape(text)
+
+    # Collapse multiple blank lines into a single newline
+    text = re.sub(r"\n{3,}", "\n\n", text)
+
+    return text.strip()
+
+
+def _resolve_chat_author(
+    from_user_id: str,
+    im_display_name: str,
+    speaker_map: dict[str, str] | None,
+) -> str:
+    """Resolve a chat message author name using the speaker mapping.
+
+    Extracts the bare GUID from ``fromUserId`` (format ``8:orgid:{GUID}``)
+    and checks the speaker_map for a cleaner display name.  Falls back to
+    ``imDisplayName`` from the message props.
+    """
+    if speaker_map and from_user_id and ":" in from_user_id:
+        guid = from_user_id.split(":")[-1]
+        mapped = speaker_map.get(guid)
+        if mapped:
+            return mapped
+
+    return im_display_name or "Unknown"
+
+
+async def _extract_roster_members(
+    port: int,
+    target_id: str,
+    speaker_map: dict[str, str] | None = None,
+) -> list[dict]:
+    """Extract the full meeting chat member list from the roster popover.
+
+    Opens the participant count button, reads member data from the React
+    fibre tree, and closes the popover.  Returns a list of dicts with
+    ``name`` (cleaned display name), ``email``, and ``role`` (``organiser``
+    if the member is marked as organiser, otherwise ``member``).
+
+    The ``speaker_map`` is used to resolve vendor-prefixed names
+    (e.g. ``v-Gabor Veres (Metosin)`` -> ``Gabor Veres``).  Names not
+    in the map have the ``v-`` prefix and parenthesised suffix stripped.
+    """
+    ws, cdp = await connect_to_target(port, target_id)
+    try:
+        # Click the participant count button to open the roster
+        result = await cdp.evaluate("""
+            (function() {
+                var btn = document.querySelector(
+                    '[data-tid="chat-header-participant-count"]'
+                );
+                if (!btn) return JSON.stringify({error: 'no_button'});
+                btn.click();
+                return JSON.stringify({ok: true});
+            })()
+        """)
+        data = json.loads(result) if result else {}
+        if data.get("error"):
+            log("roster", f"Could not open roster: {data['error']}")
+            return []
+
+        # Wait for the roster popover to render
+        await _interruptible_sleep(2)
+
+        # Extract member data from the grid
+        raw = await cdp.evaluate("""
+            (function() {
+                var grid = document.querySelector('[aria-label="grid"]');
+                if (!grid) return JSON.stringify({error: 'no_grid'});
+
+                var presentation = grid.querySelector('[role="presentation"]');
+                if (!presentation)
+                    return JSON.stringify({error: 'no_presentation'});
+
+                var items = presentation.children;
+                var results = [];
+
+                for (var i = 0; i < items.length; i++) {
+                    var item = items[i];
+                    var text = item.textContent.trim();
+
+                    // Skip the header row ("People (N)")
+                    if (/^People\\s*\\(/.test(text)) continue;
+
+                    var fk = Object.keys(item).find(
+                        function(k) { return k.startsWith('__reactFiber$'); }
+                    );
+                    if (!fk) continue;
+
+                    var fiber = item[fk];
+                    var c = fiber;
+                    var member = null;
+                    for (var d = 0; d < 10 && c; d++) {
+                        var p = c.memoizedProps || {};
+                        if (p.member && p.member.displayName) {
+                            member = {
+                                displayName: p.member.displayName,
+                                mri: p.member.mri || '',
+                                objectId: p.member.objectId || '',
+                                email: p.member.email || ''
+                            };
+                            break;
+                        }
+                        c = c.return;
+                    }
+
+                    if (member) {
+                        member.isOrganiser = /Organiser/i.test(text);
+                        results.push(member);
+                    }
+                }
+
+                return JSON.stringify({members: results});
+            })()
+        """)
+
+        # Close the popover with Escape
+        await cdp.send(
+            "Input.dispatchKeyEvent",
+            {
+                "type": "keyDown",
+                "key": "Escape",
+                "code": "Escape",
+                "windowsVirtualKeyCode": 27,
+            },
+        )
+        await cdp.send(
+            "Input.dispatchKeyEvent",
+            {
+                "type": "keyUp",
+                "key": "Escape",
+                "code": "Escape",
+                "windowsVirtualKeyCode": 27,
+            },
+        )
+
+        if not raw:
+            log("roster", "Failed to extract roster data.")
+            return []
+
+        data = json.loads(raw)
+        if data.get("error"):
+            log("roster", f"Roster extraction error: {data['error']}")
+            return []
+
+        raw_members = data.get("members", [])
+        if not raw_members:
+            log("roster", "No members found in roster.")
+            return []
+
+        # Clean names: prefer speaker_map lookup, then strip vendor prefix
+        members = []
+        for m in raw_members:
+            name = m["displayName"]
+            guid = m["objectId"]
+
+            # Try speaker_map first
+            if speaker_map and guid and guid in speaker_map:
+                name = speaker_map[guid]
+            else:
+                # Strip vendor prefix: "v-Name (Company)" -> "Name"
+                cleaned = re.sub(r"^v-", "", name)
+                cleaned = re.sub(r"\s*\([^)]+\)\s*$", "", cleaned)
+                if cleaned:
+                    name = cleaned
+
+            role = "organiser" if m.get("isOrganiser") else "member"
+            members.append(
+                {
+                    "name": name,
+                    "email": m["email"],
+                    "objectId": guid,
+                    "role": role,
+                }
+            )
+
+        log("roster", f"Extracted {len(members)} member(s)")
+        return members
+
+    finally:
+        await ws.close()
+
+
+def _utc_to_local_iso(utc_timestamp: str) -> str:
+    """Convert a UTC ISO 8601 timestamp to local time with UTC offset.
+
+    Accepts strings like ``2026-04-22T10:15:48.462Z`` and returns
+    ``2026-04-22T11:15:48.462+01:00`` (for BST).  If parsing fails
+    the original string is returned unchanged.
+    """
+    from datetime import datetime, timedelta
+
+    try:
+        dt = datetime.fromisoformat(utc_timestamp.replace("Z", "+00:00"))
+        local_dt = dt.astimezone(tz=None)
+        offset = local_dt.utcoffset() or timedelta(0)
+        total = int(offset.total_seconds())
+        sign = "+" if total >= 0 else "-"
+        a = abs(total)
+        offset_str = f"{sign}{a // 3600:02d}:{(a % 3600) // 60:02d}"
+        # Format with milliseconds if present in original
+        if "." in utc_timestamp:
+            ms = f"{local_dt.microsecond // 1000:03d}"
+            return f"{local_dt.strftime('%Y-%m-%dT%H:%M:%S')}.{ms}{offset_str}"
+        return local_dt.strftime(f"%Y-%m-%dT%H:%M:%S{offset_str}")
+    except (ValueError, OSError):
+        return utc_timestamp
+
+
+async def _extract_chat_messages(
+    port: int,
+    target_id: str,
+    config: dict,
+) -> list[dict]:
+    """Extract meeting chat messages from the Chat tab via React fibre tree.
+
+    Navigates to the Chat tab, walks the React fibre tree to find the
+    virtualised list's ``items`` array, and extracts user messages that
+    fall within the meeting time window.
+
+    The time window is determined from ``Event/Call`` control messages
+    (meeting start/end signals) which carry actual UTC timestamps.  This
+    avoids the ambiguity of the Recap header times which are in local
+    timezone.
+
+    Returns a list of dicts with keys: ``timestamp``, ``author``, ``text``,
+    ``reactions``.  Returns an empty list if no chat messages are found.
+    """
+    target_date = config["date"]  # YYYY-MM-DD
+
+    ws, cdp = await connect_to_target(port, target_id)
+    try:
+        # Click the Chat tab
+        chat_tab_result = await cdp.evaluate(r"""
+            (function() {
+                var tabs = Array.from(document.querySelectorAll('[role="tab"]'));
+                var chatTab = tabs.find(function(t) {
+                    return t.getAttribute('data-tid') ===
+                        'tab-item-com.microsoft.chattabs.chat';
+                });
+                if (!chatTab) return 'no_tab';
+                chatTab.click();
+                return 'clicked';
+            })()
+        """)
+
+        if chat_tab_result != "clicked":
+            log("chat", "Chat tab not found -- skipping chat extraction.")
+            return []
+
+        await _interruptible_sleep(2)
+
+        # Extract all messages from the React fibre tree.
+        # The virtualised list component at ~depth 21 (walking up from any
+        # chat-pane-item) holds the complete items array.
+        raw = await cdp.evaluate(r"""
+            (function() {
+                var els = document.querySelectorAll('[data-tid="chat-pane-item"]');
+                if (!els.length) return JSON.stringify({error: 'no_items'});
+
+                // Walk up the fibre tree from the first item to find the
+                // component whose props.items is an array of messages.
+                var el = els[0];
+                var fk = Object.keys(el).find(function(k) {
+                    return k.startsWith('__reactFiber$');
+                });
+                if (!fk) return JSON.stringify({error: 'no_fiber'});
+
+                var fiber = el[fk];
+                var c = fiber;
+                var itemsArr = null;
+                var loadPrev = null;
+                var loadNext = null;
+                for (var d = 0; d < 30 && c; d++) {
+                    var p = c.memoizedProps || {};
+                    if (p.items && Array.isArray(p.items) && p.items.length > 0
+                            && p.items[0] && p.items[0].originalArrivalTime) {
+                        itemsArr = p.items;
+                        loadPrev = p.loadPrev;
+                        loadNext = p.loadNext;
+                        break;
+                    }
+                    c = c.return;
+                }
+
+                if (!itemsArr) return JSON.stringify({error: 'no_items_array'});
+
+                // Extract relevant fields from each item
+                var messages = [];
+                for (var i = 0; i < itemsArr.length; i++) {
+                    var m = itemsArr[i];
+                    messages.push({
+                        id: m.id,
+                        time: m.originalArrivalTime,
+                        itemType: m.itemType,
+                        messageType: m.messageType,
+                        fromUserId: m.fromUserId || '',
+                        displayName: m.imDisplayName || '',
+                        content: m.content || '',
+                        emotions: m.emotions,
+                        emotionsSummary: m.emotionsSummary,
+                        files: m.files ? m.files.length : 0,
+                        mentions: m.mentions
+                    });
+                }
+
+                return JSON.stringify({
+                    total: itemsArr.length,
+                    hasPagination: !!(loadPrev || loadNext),
+                    messages: messages
+                });
+            })()
+        """)
+
+        if not raw:
+            log("chat", "Failed to extract chat data from React fibre tree.")
+            return []
+
+        data = json.loads(raw)
+
+        if "error" in data:
+            log("chat", f"Chat extraction error: {data['error']}")
+            return []
+
+        if data.get("hasPagination"):
+            log(
+                "chat",
+                f"WARNING: Chat has pagination ({data['total']} items loaded). "
+                "Some messages may be missing.",
+            )
+
+        log("chat", f"Total items in chat: {data['total']}")
+
+        # Determine the meeting time window from Event/Call control messages.
+        # These are the meeting start/end signals with actual UTC timestamps,
+        # avoiding the ambiguity of the Recap header which shows local time.
+        #
+        # The user-specified --datetime may differ from the actual meeting
+        # date shown in the Recap header (e.g. user says 2026-04-22 but
+        # meeting was 2026-04-21).  Try multiple candidate dates.
+        candidate_dates = [target_date]
+
+        # Extract the actual meeting date from the Recap header if available
+        time_text = config.get("meeting_time_text", "")
+        if time_text:
+            recap_start, _ = _parse_meeting_times(time_text, target_date)
+            recap_date = recap_start[:10]  # YYYY-MM-DD
+            if recap_date != target_date:
+                candidate_dates.insert(0, recap_date)
+
+        event_calls = []
+        matched_date = None
+        for cdate in candidate_dates:
+            event_calls = [
+                m
+                for m in data["messages"]
+                if m.get("messageType") == "Event/Call" and m.get("time", "").startswith(cdate)
+            ]
+            if event_calls:
+                matched_date = cdate
+                break
+
+        if event_calls:
+            # Sort by timestamp; first is meeting start, last is meeting end
+            event_calls.sort(key=lambda m: m["time"])
+            start_iso = event_calls[0]["time"]
+            end_iso = event_calls[-1]["time"]
+            # If only one Event/Call found (start or end only), expand the
+            # window by 2 hours in the missing direction to catch messages.
+            if start_iso == end_iso:
+                from datetime import datetime, timedelta
+
+                dt = datetime.fromisoformat(start_iso.replace("Z", "+00:00"))
+                start_iso = (dt - timedelta(hours=2)).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+                end_iso = (dt + timedelta(hours=2)).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+            log(
+                "chat",
+                f"Time window (from Event/Call on {matched_date}): {start_iso} to {end_iso}",
+            )
+        else:
+            # Fallback: use the best available date for a full-day window.
+            # Prefer the Recap header date over the user-specified date.
+            fallback_date = candidate_dates[0]
+            log("chat", f"No Event/Call markers found; falling back to {fallback_date}")
+            start_iso = f"{fallback_date}T00:00:00Z"
+            end_iso = f"{fallback_date}T23:59:59Z"
+            log("chat", f"Time window (full day fallback): {start_iso} to {end_iso}")
+        # Prefer member_map (roster + speakers) for resolving chat authors
+        # and reaction users; fall back to speaker_map if roster unavailable.
+        speaker_map = config.get("member_map") or config.get("speaker_map")
+        results = []
+
+        for msg in data["messages"]:
+            # Only user messages (itemType 3), text type
+            if msg["itemType"] != 3:
+                continue
+            if msg["messageType"] != "RichText/Html":
+                continue
+            # Skip messages with file attachments only (no text)
+            if msg["files"] and msg["files"] > 0:
+                text = _strip_html_to_text(msg["content"])
+                if not text:
+                    continue
+
+            # Filter by time window
+            msg_time = msg["time"]
+            if not msg_time:
+                continue
+            if msg_time < start_iso or msg_time > end_iso:
+                continue
+
+            # Build the chat message entry
+            text = _strip_html_to_text(msg["content"])
+            if not text:
+                continue
+
+            author = _resolve_chat_author(msg["fromUserId"], msg["displayName"], speaker_map)
+
+            # Parse reactions — use the detailed ``emotions`` array which
+            # includes per-user data, falling back to ``emotionsSummary``.
+            reactions = None
+            emotions_list = msg.get("emotions") or []
+            if emotions_list:
+                reactions = []
+                for emo in emotions_list:
+                    reaction_type = emo.get("key", "")
+                    users = []
+                    for u in emo.get("users") or []:
+                        uid = u.get("userId", "")
+                        display = u.get("displayName", "")
+                        name = _resolve_chat_author(uid, display, speaker_map)
+                        users.append(name)
+                    reactions.append({"type": reaction_type, "users": users})
+            elif msg.get("emotionsSummary"):
+                reactions = []
+                for r in msg["emotionsSummary"]:
+                    reactions.append(
+                        {
+                            "type": r.get("key", ""),
+                            "users": [],
+                        }
+                    )
+
+            results.append(
+                {
+                    "timestamp": _utc_to_local_iso(msg_time),
+                    "author": author,
+                    "text": text,
+                    "reactions": reactions,
+                }
+            )
+
+        # Sort chronologically (oldest first)
+        results.sort(key=lambda m: m["timestamp"])
+
+        log("chat", f"Extracted {len(results)} chat message(s) in meeting window")
+        return results
+
+    finally:
+        await ws.close()
+
+
+def _append_chat_to_vtt(output_path: str, messages: list[dict], meeting_start: str) -> None:
+    """Append meeting chat messages as a NOTE block in the VTT file.
+
+    The NOTE block is inserted after the metadata NOTE block (if present)
+    and before the first cue.  Chat messages are stored as a JSON array
+    for machine readability.
+
+    Each message's ``timestamp`` is converted from an absolute ISO 8601
+    datetime to a meeting-start-relative offset in ``HH:MM:SS.mmm``
+    format, matching the cue timestamp convention used elsewhere in the
+    VTT file.
+
+    Args:
+        output_path: Path to the VTT file to modify.
+        messages: Chat messages with absolute ``timestamp`` values.
+        meeting_start: Meeting start time as ISO 8601 (e.g.
+            ``2026-04-22T11:15+01:00``).
+    """
+    if not messages:
+        return
+
+    from datetime import datetime
+
+    try:
+        start_dt = datetime.fromisoformat(meeting_start)
+    except (ValueError, TypeError):
+        # Cannot compute offsets; fall back to absolute timestamps
+        start_dt = None
+
+    offset_messages = []
+    for msg in messages:
+        entry = dict(msg)
+        if start_dt is not None:
+            try:
+                msg_dt = datetime.fromisoformat(entry["timestamp"])
+                delta = msg_dt - start_dt
+                total_ms = int(delta.total_seconds() * 1000)
+                if total_ms < 0:
+                    total_ms = 0
+                hours = total_ms // 3_600_000
+                minutes = (total_ms % 3_600_000) // 60_000
+                seconds = (total_ms % 60_000) // 1000
+                millis = total_ms % 1000
+                entry["offset"] = f"{hours:02d}:{minutes:02d}:{seconds:02d}.{millis:03d}"
+            except (ValueError, TypeError):
+                entry["offset"] = entry["timestamp"]
+        else:
+            entry["offset"] = entry["timestamp"]
+        del entry["timestamp"]
+        offset_messages.append(entry)
+
+    with open(output_path) as f:
+        content = f.read()
+
+    chat_json = json.dumps(offset_messages, indent=2, ensure_ascii=False)
+    note_block = f"NOTE Chat\n{chat_json}"
+
+    # Insert after the existing NOTE block (metadata) if present.
+    # The metadata NOTE block ends at the first blank line after
+    # "NOTE Meeting Metadata\n".  We insert the chat NOTE block after it.
+    #
+    # Pattern: WEBVTT\n\nNOTE Meeting Metadata\n...\n\n
+    #       -> WEBVTT\n\nNOTE Meeting Metadata\n...\n\nNOTE Chat\n...\n\n
+    #
+    # Find the end of the first NOTE block.
+    note_end = content.find("\n\nNOTE")
+    if note_end != -1:
+        # Find the blank line after this NOTE block
+        after_note = content.find("\n\n", note_end + 2)
+        if after_note != -1:
+            insert_pos = after_note + 2
+            content = content[:insert_pos] + note_block + "\n\n" + content[insert_pos:]
+        else:
+            content += "\n\n" + note_block + "\n"
+    elif content.startswith("WEBVTT"):
+        # No existing NOTE block -- insert after WEBVTT header
+        content = content.replace("WEBVTT\n\n", f"WEBVTT\n\n{note_block}\n\n", 1)
+    else:
+        content = f"WEBVTT\n\n{note_block}\n\n{content}"
+
+    with open(output_path, "w") as f:
+        f.write(content)
+
+    log("chat", f"Added {len(messages)} chat message(s) to VTT")
+
+
+def _parse_meeting_times(text: str, fallback_date: str) -> tuple[str, str]:
+    """Parse occurrence text into ISO 8601 start and end datetime strings.
+
+    *text* has the form ``22 April 2026 11:15 -  12:00``.
+    *fallback_date* is ``YYYY-MM-DD`` used if the text cannot be parsed.
+
+    The Recap header displays times in the user's local timezone.  The
+    local UTC offset for the parsed date is appended so the output is a
+    fully-qualified ISO 8601 datetime (e.g. ``2026-04-22T11:15+01:00``).
+
+    Returns ``(start, end)`` where each is ``YYYY-MM-DDTHH:MM+HH:MM`` or
+    just ``YYYY-MM-DD`` if the time component is missing.
+    """
+    from datetime import datetime, timedelta, timezone
+
+    month_names = {
+        "january": "01",
+        "february": "02",
+        "march": "03",
+        "april": "04",
+        "may": "05",
+        "june": "06",
+        "july": "07",
+        "august": "08",
+        "september": "09",
+        "october": "10",
+        "november": "11",
+        "december": "12",
+    }
+
+    m = re.match(
+        r"(\d{1,2})\s+(\w+)\s+(\d{4})\s+(\d{1,2}:\d{2})\s*-\s*(\d{1,2}:\d{2})",
+        text.strip(),
+    )
+    if not m:
+        return fallback_date, fallback_date
+
+    day = int(m.group(1))
+    month = month_names.get(m.group(2).lower(), "01")
+    year = m.group(3)
+    start_time = m.group(4).zfill(5)  # ensure HH:MM
+    end_time = m.group(5).zfill(5)
+
+    date_str = f"{year}-{month}-{day:02d}"
+
+    # Determine the local UTC offset for this specific date.  The offset
+    # may differ from today's offset due to DST transitions, so we
+    # construct a datetime on the meeting date and ask the platform
+    # for the corresponding UTC offset.
+    sh, sm = (int(x) for x in start_time.split(":"))
+    try:
+        naive = datetime(int(year), int(month), day, sh, sm, tzinfo=timezone.utc)
+        local_dt = naive.astimezone(tz=None)  # convert to local tz
+        utc_offset = local_dt.utcoffset() or timedelta(0)
+    except (ValueError, OSError):
+        utc_offset = datetime.now(timezone.utc).astimezone().utcoffset() or timedelta(0)
+
+    total_seconds = int(utc_offset.total_seconds())
+    sign = "+" if total_seconds >= 0 else "-"
+    abs_seconds = abs(total_seconds)
+    offset_str = f"{sign}{abs_seconds // 3600:02d}:{(abs_seconds % 3600) // 60:02d}"
+
+    return f"{date_str}T{start_time}{offset_str}", f"{date_str}T{end_time}{offset_str}"
+
+
+def _prepend_vtt_metadata(output_path: str, config: dict) -> None:
+    """Insert a VTT NOTE block with meeting metadata after the WEBVTT header.
+
+    The NOTE block contains the meeting title, attendee names (from the
+    speaker mapping), and start/end times (from the Recap header).
+    """
+    with open(output_path) as f:
+        content = f.read()
+
+    # Build the NOTE block
+    lines = ["NOTE Meeting Metadata"]
+    lines.append(f"Meeting: {config['meeting']}")
+
+    # Members from roster (sorted alphabetically), falling back to speakers
+    roster = config.get("roster_members")
+    if roster:
+        organiser_names = sorted(m["name"] for m in roster if m["role"] == "organiser")
+        member_names = sorted(m["name"] for m in roster)
+        lines.append(f"Members: {', '.join(member_names)}")
+        if organiser_names:
+            lines.append(f"Organiser: {', '.join(organiser_names)}")
+
+        # Email addresses for all members that have one
+        email_entries = sorted((m["name"], m["email"]) for m in roster if m.get("email"))
+        if email_entries:
+            email_strs = [f"{name} <{email}>" for name, email in email_entries]
+            lines.append(f"Emails: {', '.join(email_strs)}")
+    else:
+        # Fallback: speakers only (from Recap)
+        speaker_map = config.get("speaker_map")
+        if speaker_map:
+            names = sorted(speaker_map.values())
+            lines.append(f"Speakers: {', '.join(names)}")
+
+    # Start/end times
+    time_text = config.get("meeting_time_text", "")
+    if time_text:
+        start_dt, end_dt = _parse_meeting_times(time_text, config["date"])
+    else:
+        start_dt = config["date"]
+        if config.get("time"):
+            start_dt = f"{config['date']}T{config['time']}"
+        end_dt = ""
+
+    lines.append(f"Start: {start_dt}")
+    if end_dt:
+        lines.append(f"End: {end_dt}")
+
+    note_block = "\n".join(lines)
+
+    # Insert after the WEBVTT header line (before the first blank line)
+    if content.startswith("WEBVTT"):
+        # Replace "WEBVTT\n\n" with "WEBVTT\n\nNOTE Meeting Metadata\n...\n\n"
+        content = content.replace("WEBVTT\n\n", f"WEBVTT\n\n{note_block}\n\n", 1)
+    else:
+        # Unexpected — prepend both header and note
+        content = f"WEBVTT\n\n{note_block}\n\n{content}"
+
+    with open(output_path, "w") as f:
+        f.write(content)
+
+    log("post", "Added VTT metadata comment block")
+
+
+def _apply_speaker_mapping_to_vtt(output_path: str, speaker_map: dict[str, str]) -> None:
+    """Post-process a VTT file to replace speaker names using the mapping.
+
+    Native VTT downloads (Approach A) contain speaker names in
+    ``<v SPEAKER_NAME>`` tags.  This function matches each VTT speaker
+    name to a Recap display name and replaces it.
+
+    The mapping keys are GUIDs, but VTT files don't contain GUIDs --
+    they contain display names.  Matching is done by:
+
+    1. ``@N`` pattern: Recap shows ``Speaker N``.
+    2. Substring match: VTT has ``v-Gabor Veres (Metosin)``, Recap has
+       ``Gabor Veres``.  The Recap name is a substring of the VTT name.
+    3. Exact match: names are already identical -- no replacement needed.
+    """
+    import re as _re
+
+    with open(output_path) as f:
+        content = f.read()
+
+    # Extract all unique speaker names from the VTT.
+    vtt_names = set(_re.findall(r"<v ([^>]+)>", content))
+    recap_names = set(speaker_map.values())
+
+    replacements = {}  # old_vtt_name -> recap_name
+
+    for vtt_name in vtt_names:
+        if vtt_name in recap_names:
+            # Already matches a Recap name exactly -- no change needed.
+            continue
+
+        # Try to find a matching Recap name.
+        # 1. @N pattern: look for "Speaker N" in Recap names.
+        at_match = _re.match(r"^@(\d+)$", vtt_name)
+        if at_match:
+            speaker_label = f"Speaker {at_match.group(1)}"
+            if speaker_label in recap_names:
+                replacements[vtt_name] = speaker_label
+                continue
+
+        # 2. Substring match: a Recap name is contained in the VTT name.
+        #    e.g. "Gabor Veres" in "v-Gabor Veres (Metosin)"
+        #    Pick the longest matching Recap name to avoid false positives.
+        best_match = None
+        best_len = 0
+        for recap_name in recap_names:
+            if recap_name in vtt_name and len(recap_name) > best_len:
+                best_match = recap_name
+                best_len = len(recap_name)
+        if best_match:
+            replacements[vtt_name] = best_match
+
+    if not replacements:
+        return
+
+    for old_name, new_name in replacements.items():
+        old_tag = f"<v {old_name}>"
+        new_tag = f"<v {new_name}>"
+        content = content.replace(old_tag, new_tag)
+        log("post", f"Replaced speaker: {old_name!r} -> {new_name!r}")
+
+    with open(output_path, "w") as f:
+        f.write(content)
+
+
+def _ensure_trailing_newline(output_path: str) -> None:
+    """Ensure the VTT file ends with a trailing newline."""
+    with open(output_path, "rb") as f:
+        f.seek(-1, 2)
+        if f.read(1) != b"\n":
+            with open(output_path, "a") as fa:
+                fa.write("\n")
+
+
+def _build_result_summary(
+    config: dict,
+    *,
+    num_parts: int = 1,
+    verification: dict | None = None,
+    chat_count: int = 0,
+) -> dict:
+    """Build a structured result summary from config and verification data.
+
+    Used for both ``--format json`` output and ``--dry-run`` summaries.
+    """
+    summary: dict[str, object] = {"status": "ok"}
+
+    # Meeting metadata
+    summary["meeting"] = config["meeting"]
+
+    time_text = config.get("meeting_time_text", "")
+    if time_text:
+        start_dt, end_dt = _parse_meeting_times(time_text, config["date"])
+        summary["start"] = start_dt
+        if end_dt:
+            summary["end"] = end_dt
+    else:
+        summary["start"] = config["date"]
+        if config.get("time"):
+            summary["start"] = f"{config['date']}T{config['time']}"
+
+    # Members and organiser
+    roster = config.get("roster_members", [])
+    if roster:
+        summary["members"] = sorted(m["name"] for m in roster)
+        organisers = sorted(m["name"] for m in roster if m["role"] == "organiser")
+        if organisers:
+            summary["organiser"] = organisers[0] if len(organisers) == 1 else organisers
+    else:
+        speaker_map = config.get("speaker_map")
+        if speaker_map:
+            summary["members"] = sorted(speaker_map.values())
+
+    summary["parts"] = num_parts
+
+    # Verification data (populated after download, absent for dry-run)
+    if verification and verification.get("valid"):
+        summary["cues"] = verification["cue_count"]
+        summary["speakers"] = verification["speakers"]
+        summary["file_size"] = verification["file_size"]
+    else:
+        # Dry-run: include speaker names with zero counts
+        speaker_map = config.get("speaker_map")
+        if speaker_map:
+            summary["speakers"] = dict.fromkeys(sorted(speaker_map.values()), 0)
+
+    if chat_count:
+        summary["chat_messages"] = chat_count
+
+    return summary
+
+
+def verify_output(output_path: str) -> dict:
+    """Verify the downloaded VTT file. Returns a summary dict."""
+    if not os.path.exists(output_path):
+        log("step8", f"ERROR: Output file does not exist: {output_path}")
+        return {"valid": False, "error": "file not found"}
+
+    with open(output_path) as f:
+        content = f.read()
+
+    if not content.startswith("WEBVTT"):
+        log("step8", "ERROR: File does not start with WEBVTT header.")
+        return {"valid": False, "error": "missing WEBVTT header"}
+
+    # Count cues
+    cue_count = len(re.findall(r"\d{2}:\d{2}:\d{2}\.\d{3} --> \d{2}:\d{2}:\d{2}\.\d{3}", content))
+
+    # Extract speakers
+    speaker_pattern = re.compile(r"^<v ([^>]+)>", re.MULTILINE)
+    speakers = speaker_pattern.findall(content)
+    speaker_counts = Counter(speakers)
+
+    file_size = os.path.getsize(output_path)
+
+    log("step8", f"File: {output_path}")
+    log("step8", f"Size: {file_size} bytes")
+    log("step8", f"Cues: {cue_count}")
+    log("step8", f"Speakers ({len(speaker_counts)}):")
+    for sp, cnt in speaker_counts.most_common():
+        log("step8", f"  {sp}: {cnt}")
+
+    return {
+        "valid": True,
+        "file_size": file_size,
+        "cue_count": cue_count,
+        "speakers": dict(speaker_counts),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Main orchestration
+# ---------------------------------------------------------------------------
+
+MAX_SEARCH_RETRIES = 4
+
+
+async def main() -> None:
+    _install_signal_handlers()
+    args = parse_args()
+    config = resolve_config(args)
+
+    log("main", f"Meeting: {config['meeting']}")
+    datetime_label = config["date"]
+    if config["time"]:
+        datetime_label += f"T{config['time']}"
+    log("main", f"Date: {datetime_label}")
+    log("main", f"Output: {config['output']}")
+    log("main", f"CDP port: {config['port']}")
+    log("main", f"Model: {config['model']}")
+    log("main", f"GCP project: {config['gcp_project']}")
+    log("main", f"GCP region: {config['gcp_region']}")
+
+    # Step 1: Ensure Teams is running
+    ensure_teams_running(config["port"], force=config["force_restart"])
+
+    # Step 2: Verify CDP
+    verify_cdp(config["port"])
+
+    # Step 3: Find main Teams targets
+    targets = find_teams_targets(config["port"])
+    if not targets:
+        _exit_error(
+            EXIT_CDP_UNAVAILABLE,
+            "NO_TARGETS",
+            "No Teams page targets found via CDP.",
+            step="step3",
+        )
+    log("step3", f"Found {len(targets)} Teams page target(s)")
+    for t in targets:
+        log("step3", f"  {t['id'][:20]}... {t.get('title', '')[:60]}")
+
+    # Create agent client (used in Steps 4 and 6)
+    agent_client = create_agent_client(config)
+
+    # Steps 4+5: Navigate to meeting and Recap > Transcript.
+    # For recurring meetings the first search result may be the wrong chat
+    # group (occurrence dropdown doesn't contain the target date).  In that
+    # case we retry with the next search result index, up to MAX_RETRIES.
+    search_target_id = None
+    result_index_override: int | None = None
+
+    for attempt in range(MAX_SEARCH_RETRIES):
+        _check_shutdown()
+        # Record existing iframe targets BEFORE each navigation so Step 6
+        # can distinguish new targets from stale ones
+        pre_nav_iframe_ids = {t["id"] for t in find_xplatplugins_targets(config["port"])}
+        if pre_nav_iframe_ids:
+            log("main", f"Pre-existing iframe targets: {len(pre_nav_iframe_ids)}")
+
+        # Step 4: Navigate to meeting
+        search_target_id = await navigate_to_meeting(
+            config["port"],
+            targets,
+            config,
+            agent_client,
+            result_index_override=result_index_override,
+        )
+
+        if search_target_id is None:
+            # Navigation failed (index out of range, or clicked a non-chat
+            # result).  Try the next search result index.
+            if result_index_override is None:
+                result_index_override = 1
+            else:
+                result_index_override += 1
+            log(
+                "main",
+                f"Attempt {attempt + 1}/{MAX_SEARCH_RETRIES} failed "
+                f"(navigation). Retrying with index {result_index_override}...",
+            )
+            continue
+
+        # Step 5: Navigate to Recap > Transcript
+        transcript_ok = await navigate_to_transcript(
+            config["port"], search_target_id, config, agent_client
+        )
+
+        if transcript_ok:
+            log("main", "Correct occurrence found and transcript tab loaded.")
+            break
+
+        # Occurrence not found -- try the next search result
+        if result_index_override is None:
+            # First attempt used the agent's pick (typically index 0).
+            # Start overriding from index 1.
+            result_index_override = 1
+        else:
+            result_index_override += 1
+
+        log(
+            "main",
+            f"Attempt {attempt + 1}/{MAX_SEARCH_RETRIES} failed. "
+            f"Retrying with search result index {result_index_override}...",
+        )
+    else:
+        _exit_error(
+            EXIT_MEETING_NOT_FOUND,
+            "MEETING_NOT_FOUND",
+            f"Could not find the target {datetime_label} in any "
+            f"of the first {MAX_SEARCH_RETRIES} search results.",
+            step="step5",
+        )
+
+    # Extract the full chat member list from the roster popover.
+    # This runs after step 5 so that we have the speaker_map for
+    # name resolution.
+    if search_target_id:
+        roster_members = await _extract_roster_members(
+            config["port"],
+            search_target_id,
+            config.get("speaker_map"),
+        )
+        config["roster_members"] = roster_members
+
+        # Build a combined GUID -> clean name map from both the roster
+        # and the speaker_map.  The roster covers all chat members
+        # (including non-speakers), which lets us resolve reaction
+        # authors and chat authors that the speaker_map alone cannot.
+        member_map: dict[str, str] = {}
+        for rm in roster_members:
+            oid = rm.get("objectId", "")
+            if oid and rm.get("name"):
+                member_map[oid] = rm["name"]
+        # Speaker map entries take priority (Recap canonical names).
+        if config.get("speaker_map"):
+            member_map.update(config["speaker_map"])
+        config["member_map"] = member_map
+
+    # Detect multi-part meetings (Part 1, Part 2, etc.)
+    num_parts = await _detect_part_tabs(config["port"], search_target_id)
+    log("main", f"Meeting parts detected: {num_parts}")
+
+    # --dry-run: emit meeting metadata and exit without downloading.
+    if config.get("dry_run"):
+        summary = _build_result_summary(config, num_parts=num_parts)
+        summary["dry_run"] = True
+        if _format_json:
+            print(json.dumps(summary, ensure_ascii=False, indent=2), flush=True)
+        else:
+            log("main", f"Dry-run summary: {json.dumps(summary, ensure_ascii=False)}")
+        sys.exit(EXIT_OK)
+
+    # Download each part's transcript.
+    # Part 1 is already loaded (navigate_to_transcript clicked Transcript).
+    # For subsequent parts we click the Part N tab, then Transcript.
+    part_vtt_contents: list[str] = []
+
+    for part_num in range(1, num_parts + 1):
+        _check_shutdown()
+        part_label = f"Part {part_num}/{num_parts}"
+
+        if part_num > 1:
+            # Navigate to Part N and its Transcript sub-tab
+            log("main", f"Navigating to {part_label}...")
+
+            # Record iframe targets BEFORE clicking the new Part tab so
+            # we can distinguish the new iframe from existing ones.
+            pre_part_iframe_ids = {t["id"] for t in find_xplatplugins_targets(config["port"])}
+
+            ok = await _click_part_and_transcript(config["port"], search_target_id, part_num)
+            if not ok:
+                log("main", f"WARNING: Could not navigate to {part_label}. Skipping.")
+                continue
+
+            # Use updated pre-nav set for iframe disambiguation
+            pre_nav_iframe_ids = pre_part_iframe_ids
+
+        log("main", f"Downloading transcript for {part_label}...")
+
+        # Determine output path: use temp files for multi-part, direct for single
+        if num_parts == 1:
+            part_output = config["output"]
+        else:
+            part_output = f"{config['output']}.part{part_num}.tmp"
+
+        # Step 6: Find iframe target (pass pre-existing IDs for disambiguation)
+        iframe_target_id = find_iframe_target(
+            config["port"], config, agent_client, pre_nav_iframe_ids
+        )
+
+        # Step 7: Check permission
+        permission = await check_permission(config["port"], iframe_target_id)
+
+        if permission == "no_button":
+            if num_parts == 1:
+                _exit_error(
+                    EXIT_DOWNLOAD_FAILED,
+                    "DOWNLOAD_FAILED",
+                    "Download button not found. The transcript may not have loaded.",
+                    step="step7",
+                )
+            log("main", f"WARNING: No download button for {part_label}. Skipping.")
+            continue
+
+        # Step 7A or 7B based on permission
+        success = False
+        if permission == "has_permission":
+            log("main", f"{part_label}: Using Approach A (native blob interception)")
+            success = await download_native_vtt(config["port"], iframe_target_id, part_output)
+        else:
+            log("main", f"{part_label}: Using Approach B (DOM extraction)")
+            success = await _extract_via_react_props(
+                config["port"],
+                iframe_target_id,
+                part_output,
+                speaker_map=config.get("speaker_map"),
+            )
+            if success is None:
+                log("main", f"{part_label}: React props unavailable, falling back to scroll")
+                success = await extract_dom_vtt(config["port"], iframe_target_id, part_output)
+
+        if not success:
+            if num_parts == 1:
+                _exit_error(
+                    EXIT_DOWNLOAD_FAILED,
+                    "DOWNLOAD_FAILED",
+                    "Transcript download failed.",
+                    step="step7",
+                )
+            log("main", f"WARNING: Download failed for {part_label}. Skipping.")
+            continue
+
+        # Apply speaker mapping to this part before merging
+        speaker_map = config.get("speaker_map")
+        if speaker_map:
+            _apply_speaker_mapping_to_vtt(part_output, speaker_map)
+
+        with open(part_output) as f:
+            part_vtt_contents.append(f.read())
+
+        log("main", f"{part_label}: downloaded successfully")
+
+    if not part_vtt_contents:
+        _exit_error(
+            EXIT_DOWNLOAD_FAILED,
+            "DOWNLOAD_FAILED",
+            "No transcript parts were downloaded.",
+            step="step7",
+        )
+
+    # Merge parts if multi-part meeting
+    if num_parts > 1:
+        log("main", f"Merging {len(part_vtt_contents)} parts...")
+        merged = _merge_vtt_parts(part_vtt_contents)
+        with open(config["output"], "w") as f:
+            f.write(merged)
+        log("main", f"Merged VTT written to {config['output']}")
+
+        # Clean up temp files
+        for part_num in range(1, num_parts + 1):
+            tmp_path = f"{config['output']}.part{part_num}.tmp"
+            if os.path.exists(tmp_path):
+                os.remove(tmp_path)
+
+    # Insert VTT metadata comment block (meeting title, attendees, times)
+    _prepend_vtt_metadata(config["output"], config)
+
+    _check_shutdown()
+
+    # Extract meeting chat messages and append to VTT
+    if search_target_id:
+        # Compute meeting start datetime for offset calculation
+        time_text = config.get("meeting_time_text", "")
+        if time_text:
+            meeting_start, _ = _parse_meeting_times(time_text, config["date"])
+        elif config.get("time"):
+            meeting_start = f"{config['date']}T{config['time']}"
+        else:
+            meeting_start = config["date"]
+
+        chat_messages = await _extract_chat_messages(config["port"], search_target_id, config)
+        if chat_messages:
+            _append_chat_to_vtt(config["output"], chat_messages, meeting_start)
+            chat_count = len(chat_messages)
+        else:
+            log("main", "No chat messages found for this meeting occurrence.")
+            chat_count = 0
+    else:
+        chat_count = 0
+
+    # Ensure file ends with a trailing newline (WebVTT spec recommendation).
+    _ensure_trailing_newline(config["output"])
+
+    # Step 8: Verify
+    result = verify_output(config["output"])
+    if result["valid"]:
+        log("main", "Transcript download complete.")
+    else:
+        _exit_error(
+            EXIT_VERIFICATION_FAILED,
+            "VERIFICATION_FAILED",
+            f"Output file verification failed: {result.get('error')}",
+            step="step8",
+        )
+
+    # --- Emit final output ---------------------------------------------------
+    # Behaviour matrix:
+    #   --output PATH  --format text  → file written, nothing on stdout
+    #   --output PATH  --format json  → file written, JSON summary on stdout
+    #   (no --output)  --format text  → VTT content on stdout
+    #   (no --output)  --format json  → JSON summary with embedded VTT on stdout
+
+    output_to_stdout = config.get("output_to_stdout", False)
+
+    if _format_json:
+        summary = _build_result_summary(
+            config,
+            num_parts=num_parts,
+            verification=result,
+            chat_count=chat_count,
+        )
+        if output_to_stdout:
+            # Embed full VTT content in JSON
+            with open(config["output"]) as f:
+                summary["vtt"] = f.read()
+        else:
+            summary["file"] = config["output"]
+        print(json.dumps(summary, ensure_ascii=False, indent=2), flush=True)
+    elif output_to_stdout:
+        # Raw VTT to stdout
+        with open(config["output"]) as f:
+            sys.stdout.write(f.read())
+        sys.stdout.flush()
+
+    # Clean up temp file when output was piped to stdout
+    if output_to_stdout:
+        with contextlib.suppress(OSError):
+            os.remove(config["output"])
+
+
+def main_sync() -> None:
+    """Synchronous entry point for console_scripts."""
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    main_sync()