translation.rs

// Copyright (C) 2026 Bryan A. Jones.
//
// This file is part of the CodeChat Editor. The CodeChat Editor is free
// software: you can redistribute it and/or modify it under the terms of the GNU
// General Public License as published by the Free Software Foundation, either
// version 3 of the License, or (at your option) any later version.
//
// The CodeChat Editor is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
// FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
// details.
//
// You should have received a copy of the GNU General Public License along with
// the CodeChat Editor. If not, see
// [http://www.gnu.org/licenses](http://www.gnu.org/licenses).
//! `translation.rs` -- translate messages between the IDE and the Client
//! =====================================================================
//!
//! The IDE extension client (IDE for short) and the CodeChat Editor Client (or
//! Editor for short) exchange messages with each other, mediated by the
//! CodeChat Server. The Server forwards messages from one client to the other,
//! translating as necessary (for example, between source code and the Editor
//! format). This module implements the protocol for this forwarding and
//! translation logic; the actuation translation algorithms are implemented in
//! the processing module.
//!
//! Overview
//! --------
//!
//! ### Architecture
//!
//! It uses a set of queues to decouple websocket protocol activity from the
//! core processing needed to translate source code between a CodeChat Editor
//! Client and an IDE client. The following diagram illustrates this approach:
//!
//! ```graphviz
//! digraph {
//! ccc -> client_task [ label = "websocket" dir = "both" ]
//! ccc -> http_task [ label = "HTTP\nrequest/response" dir = "both"]
//! client_task -> from_client
//! http_task -> http_to_client
//! http_to_client -> processing
//! processing -> http_from_client
//! http_from_client -> http_task
//! from_client -> processing
//! processing -> to_client
//! to_client -> client_task
//! ide -> ide_task [ dir = "both" ]
//! ide_task -> from_ide
//! from_ide -> processing
//! processing -> to_ide
//! to_ide -> ide_task
//! { rank = same; client_task; http_task }
//! { rank = same; to_client; from_client; http_from_client; http_to_client }
//! { rank = same; to_ide; from_ide }
//! { rank = max; ide }
//! ccc [ label = "CodeChat Editor\nClient"]
//! client_task [ label = "Client websocket\ntask"]
//! http_task [ label = "HTTP endpoint"]
//! from_client [ label = "queue from client" shape="rectangle"]
//! processing [ label = "Processing task" ]
//! to_client [ label = "queue to client" shape="rectangle"]
//! http_to_client [ label = "http queue to client" shape = "rectangle"]
//! http_from_client [ label = "oneshot from client" shape = "box"]
//! ide [ label = "CodeChat Editor\nIDE plugin"]
//! ide_task [ label = "IDE task" ]
//! from_ide [ label = "queue from IDE" shape="rectangle" ]
//! to_ide [ label = "queue to IDE" shape="rectangle" ]
//! }
//! ```
//!
//! The queues use multiple-sender, single receiver (mpsc) types. The exception
//! to this pattern is the HTTP endpoint. This endpoint is invoked with each
//! HTTP request, rather than operating as a single, long-running task. It sends
//! the request to the processing task using an mpsc queue; this request
//! includes a one-shot channel which enables the request to return a response
//! to this specific request instance. The endpoint then returns the provided
//! response.
//!
//! ### Protocol
//!
//! The following diagrams formally define the forwarding and translation
//! protocol which this module implements.
//!
//! * The startup phase loads the Client framework into a browser:
//!
//!   ```mermaid
//!   sequenceDiagram
//!   participant IDE
//!   participant Server
//!   participant Client
//!   note over IDE, Client: Startup
//!   IDE ->> Server: Opened(IdeType)
//!   Server ->> IDE: Result(String: OK)
//!   Server ->> IDE: ClientHtml(String: HTML or URL)
//!   IDE ->> Server: Result(String: OK)
//!   note over IDE, Client: Open browser (Client framework HTML or URL)
//!   loop
//!     Client -> Server: HTTP request(/static URL)
//!     Server -> Client: HTTP response(/static data)
//!   end
//!   ```
//!
//! * If the current file in the IDE changes (including the initial startup,
//!   when the change is from no file to the current file), or a link is
//!   followed in the Client's iframe:
//!
//!   ```mermaid
//!   sequenceDiagram
//!   participant IDE
//!   participant Server
//!   participant Client
//!   alt IDE loads file
//!     IDE ->> Client: CurrentFile(String: Path of main.py)
//!     opt If Client document is dirty
//!         Client ->> IDE: Update(String: contents of main.py)
//!         IDE ->> Client: Response(OK)
//!     end
//!     Client ->> IDE: Response(OK)
//!   else Client loads file
//!     Client ->> IDE: CurrentFile(String: URL of main.py)
//!     IDE ->> Client: Response(OK)
//!   end
//!   Client ->> Server: HTTP request(URL of main.py)
//!   Server ->> IDE: LoadFile(String: path to main.py)
//!   IDE ->> Server: Response(LoadFile(String: file contents of main.py))
//!   alt main.py is editable
//!     Server ->> Client: HTTP response(contents of Client)
//!     Server ->> Client: Update(String: contents of main.py)
//!     Client ->> Server: Response(OK)
//!     loop
//!         Client ->> Server: HTTP request(URL of supporting file in main.py)
//!         Server ->> IDE: LoadFile(String: path of supporting file)
//!         alt Supporting file in IDE
//!             IDE ->> Server: Response(LoadFile(contents of supporting file)
//!             Server ->> Client: HTTP response(contents of supporting file)
//!         else Supporting file not in IDE
//!             IDE ->> Server: Response(LoadFile(None))
//!             Server ->> Client: HTTP response(contents of supporting file from /// filesystem)
//!         end
//!     end
//!   else main.py not editable and not a project
//!     Server ->> Client: HTTP response(contents of main.py)
//!   else main.py not editable and is a project
//!     Server ->> Client: HTTP response(contents of Client Simple Viewer)
//!     Client ->> Server: HTTP request (URL?raw of main.py)
//!     Server ->> Client: HTTP response(contents of main.py)
//!   end
//!   ```
//!
//! * If the current file's contents in the IDE are edited:
//!
//!   ```mermaid
//!   sequenceDiagram
//!   participant IDE
//!   participant Server
//!   participant Client
//!   IDE ->> Server: Update(String: new text contents)
//!   alt Main file is editable
//!     Server ->> Client: Update(String: new Client contents)
//!   else Main file is not editable
//!     Server ->> Client: Update(String: new text contents)
//!   end
//!   Client ->> IDE: Response(String: OK)
//!   ```
//!
//! * If the current file's contents in the Client are edited, the Client sends
//!   the IDE an `Update` with the revised contents.
//!
//! * When the PC goes to sleep then wakes up, the IDE client and the Editor
//!   client both reconnect to the websocket URL containing their assigned ID.
//!
//! * If the Editor client or the IDE client are closed, they close their
//!   websocket, which sends a `Close` message to the other websocket, causes it
//!   to also close and ending the session.
//!
//! * If the server is stopped (or crashes), both clients shut down after
//!   several reconnect retries.
//!
//! ### Editor-overlay filesystem
//!
//! When the Client displays a file provided by the IDE, that file may not exist
//! in the filesystem (a newly-created document), the IDE's content may be newer
//! than the filesystem content (an unsaved file), or the file may exist only in
//! the filesystem (for examples, images referenced by a file). The Client loads
//! files by sending HTTP requests to the Server with a URL which includes the
//! path to the desired file. Therefore, the Server must first ask the IDE if it
//! has the requested file; if so, it must deliver the IDE's file contents; if
//! not, it must load thee requested file from the filesystem. This process --
//! fetching from the IDE if possible, then falling back to the filesystem --
//! defines the editor-overlay filesystem.
//!
//! #### Message IDs
//!
//! The message system connects the IDE, Server, and Client; all three can serve
//! as the source or destination for a message. Any message sent should produce
//! a Response message in return. Therefore, we need globally unique IDs for
//! each message. To achieve this, the Server uses IDs that are multiples of 3
//! (0, 3, 6, ...), the Client multiples of 3 + 1 (1, 4, 7, ...) and the IDE
//! multiples of 3 + 2 (2, 5, 8, ...). A double-precision floating point number
//! (the standard
//! [numeric type](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type)
//! in JavaScript) has a 53-bit mantissa, meaning IDs won't wrap around for a
//! very long time.
// Imports
// -------
//
// ### Standard library
use std::{
    collections::HashMap,
    ffi::OsStr,
    fmt::Debug,
    path::{Path, PathBuf},
    rc::Rc,
    sync::LazyLock,
};

// ### Third-party
use htmd::Node;
use log::{debug, error, warn};
use rand::random;
use regex::Regex;
use tokio::{
    fs::File,
    select,
    sync::mpsc::{self, Receiver, Sender},
};

// ### Local
use crate::{
    capture::{CaptureContext, CaptureEventType, capture_control_only},
    lexer::{CodeDocBlock, DocBlock, supported_languages::MARKDOWN_MODE},
    processing::{
        CodeChatForWeb, CodeMirror, CodeMirrorDiff, CodeMirrorDiffable, CodeMirrorDocBlock,
        CodeMirrorDocBlockVec, SourceFileMetadata, TranslationResultsString, UNICODE_CURSOR_MARKER,
        byte_index_of, cache::CacheMap, codechat_for_web_to_source, diff_code_mirror_doc_blocks,
        diff_str, doc_block_html_to_markdown, minify, remove_tinymce_data,
        source_to_codechat_for_web_string, transform_html,
    },
    queue_send, queue_send_func,
    webserver::{
        CursorPosition, EditorMessage, EditorMessageContents, INITIAL_MESSAGE_ID,
        MESSAGE_ID_INCREMENT, ProcessingTaskHttpRequest, ProcessingTaskHttpRequestFlags,
        ResultErrTypes, ResultOkTypes, SimpleHttpResponse, SimpleHttpResponseError,
        UpdateMessageContents, WebAppState, WebsocketQueues, file_to_response, log_capture_event,
        path_to_url, send_response, try_canonicalize, try_read_as_text, url_to_path,
    },
};

// Globals
// -------
//
// The max length of a message to show in the console.
const MAX_MESSAGE_LENGTH: usize = 50000;

/// A regex to determine the type of the first EOL. See 'PROCESSINGS\`.
pub static EOL_FINDER: LazyLock<Regex> = LazyLock::new(|| Regex::new("[^\r\n]*(\r?\n)").unwrap());

// Data structures
// ---------------
#[derive(Clone, Debug, PartialEq)]
pub enum EolType {
    Lf,
    Crlf,
}

// Code
// ----
#[must_use]
pub fn find_eol_type(s: &str) -> EolType {
    match EOL_FINDER.captures(s) {
        // Assume a line type for strings with no newlines.
        None => {
            if cfg!(windows) {
                EolType::Crlf
            } else {
                EolType::Lf
            }
        }
        Some(captures) => match captures.get(1) {
            None => panic!("No capture group!"),
            Some(match_) => {
                if match_.as_str() == "\n" {
                    EolType::Lf
                } else {
                    EolType::Crlf
                }
            }
        },
    }
}

#[derive(Debug, thiserror::Error)]
pub enum CreateTranslationQueuesError {
    #[error("Connection ID {0} already in use.")]
    IdInUse(String),
    #[error("IDE queue {0} already in use.")]
    IdeInUse(String),
}

pub struct CreatedTranslationQueues {
    pub from_ide_rx: Receiver<EditorMessage>,
    pub to_ide_tx: Sender<EditorMessage>,
    pub from_client_rx: Receiver<EditorMessage>,
    pub to_client_tx: Sender<EditorMessage>,
}

pub fn create_translation_queues(
    connection_id: String,
    app_state: &WebAppState,
) -> Result<CreatedTranslationQueues, CreateTranslationQueuesError> {
    // There are three cases for this `connection_id`:
    //
    // 1. It hasn't been used before. In this case, create the appropriate
    //    queues and start websocket and processing tasks.
    // 2. It's in use, but was disconnected. Return this as an error; the caller
    //    can resume the connection if appropriate.
    // 3. It's in use by another IDE. Return this as an error.
    //
    // Check case 3.
    if app_state
        .connection_id
        .lock()
        .unwrap()
        .contains(&connection_id)
    {
        return Err(CreateTranslationQueuesError::IdInUse(connection_id));
    }

    // Now case 2.
    if app_state
        .ide_queues
        .lock()
        .unwrap()
        .contains_key(&connection_id)
    {
        return Err(CreateTranslationQueuesError::IdeInUse(connection_id));
    }

    // Then this is case 1. Add the connection ID to the list of active
    // connections.
    let (from_ide_tx, from_ide_rx) = mpsc::channel(10);
    let (to_ide_tx, to_ide_rx) = mpsc::channel(10);
    assert!(
        app_state
            .ide_queues
            .lock()
            .unwrap()
            .insert(
                connection_id.clone(),
                WebsocketQueues {
                    from_websocket_tx: from_ide_tx,
                    to_websocket_rx: to_ide_rx,
                    pending_messages: HashMap::new(),
                },
            )
            .is_none()
    );
    let (from_client_tx, from_client_rx) = mpsc::channel(10);
    let (to_client_tx, to_client_rx) = mpsc::channel(10);
    assert!(
        app_state
            .client_queues
            .lock()
            .unwrap()
            .insert(
                connection_id.clone(),
                WebsocketQueues {
                    from_websocket_tx: from_client_tx,
                    to_websocket_rx: to_client_rx,
                    pending_messages: HashMap::new(),
                },
            )
            .is_none()
    );
    assert!(
        app_state
            .connection_id
            .lock()
            .unwrap()
            .insert(connection_id.clone())
    );

    Ok(CreatedTranslationQueues {
        from_ide_rx,
        to_ide_tx,
        from_client_rx,
        to_client_tx,
    })
}

/// This holds the state used by the main loop of the translation task; this
/// allows factoring out lengthy contents in the loop into subfunctions.
struct TranslationTask {
    // These parameters are passed to us.
    app_state: WebAppState,
    connection_id_raw: String,
    prefix: &'static [&'static str],
    allow_source_diffs: bool,
    to_ide_tx: Sender<EditorMessage>,
    from_ide_rx: Receiver<EditorMessage>,
    to_client_tx: Sender<EditorMessage>,
    from_client_rx: Receiver<EditorMessage>,
    from_http_rx: Receiver<ProcessingTaskHttpRequest>,
    cache: CacheMap,

    // These parameters are internal state.
    /// The file currently loaded in the Client.
    current_file: PathBuf,
    /// A map of `LoadFile` requests sent to the IDE, awaiting its response.
    load_file_requests: HashMap<u64, ProcessingTaskHttpRequest>,
    /// The id for messages created by the server. Leave space for a server
    /// message during the init phase.
    id: f64,
    /// The source code, provided by the IDE. It will use whatever the IDE
    /// provides for EOLs, which is stored in `eol` below.
    source_code: String,
    code_mirror_doc: String,
    eol: EolType,
    /// Some means this contains valid HTML; None means don't use it (since it
    /// would have contained Markdown).
    code_mirror_doc_blocks: Option<Vec<CodeMirrorDocBlock>>,
    prefix_str: String,
    /// To support sending diffs, we must provide a way to determine if the
    /// sender and receiver have the same file contents before applying a diff.
    /// File contents can become unsynced due to:
    ///
    /// 1. A dropped/lost message between the IDE and Client.
    /// 2. Edits to file contents in two locations before updates from one
    ///    location (the Client, for example) propagate to the other location
    ///    (the IDE).
    ///
    /// Therefore, assign each file a version number. All files are sent with a
    /// unique, randomly-generated version number which define the file's
    /// version after this update is applied. Diffs also include the version
    /// number of the file before applying the diff; the receiver's current
    /// version number must match with the sender's pre-diff version number in
    /// order to apply the diff. When the versions don't match, the IDE must
    /// send a full text file to the Server and Client to re-sync. When a file
    /// is first loaded, its version number is None, signaling that the sender
    /// must always provide the full text, not a diff.
    version: f64,
    /// Has the full (non-diff) version of the current file been sent? Don't
    /// send diffs until this is sent.
    sent_full: bool,
    /// Most recent capture metadata supplied by the IDE. Server-generated
    /// capture events reuse this so translated write events retain the same
    /// participant/session identity as the extension events.
    capture_context: CaptureContext,
}

/// This is the processing task for the Visual Studio Code IDE. It handles all
/// the core logic to moving data between the IDE and the client.
#[allow(clippy::too_many_arguments)]
#[allow(clippy::too_many_lines)]
pub async fn translation_task(
    connection_id_prefix: String,
    connection_id_raw: String,
    prefix: &'static [&'static str],
    app_state: WebAppState,
    shutdown_only: bool,
    allow_source_diffs: bool,
    to_ide_tx: Sender<EditorMessage>,
    mut from_ide_rx: Receiver<EditorMessage>,
    to_client_tx: Sender<EditorMessage>,
    mut from_client_rx: Receiver<EditorMessage>,
) {
    let connection_id = format!("{connection_id_prefix}{connection_id_raw}");
    if !shutdown_only {
        debug!("VSCode processing task started.");

        // Create a queue for HTTP requests to communicate with this task.
        let (from_http_tx, from_http_rx) = mpsc::channel(10);
        app_state
            .processing_task_queue_tx
            .lock()
            .unwrap()
            .insert(connection_id.clone(), from_http_tx);

        let mut continue_loop = true;
        let mut tt = TranslationTask {
            app_state: app_state.clone(),
            connection_id_raw,
            prefix,
            allow_source_diffs,
            to_ide_tx,
            from_ide_rx,
            to_client_tx,
            from_client_rx,
            from_http_rx,
            cache: app_state.cache.clone(),
            current_file: PathBuf::new(),
            load_file_requests: HashMap::new(),
            id: INITIAL_MESSAGE_ID + MESSAGE_ID_INCREMENT,
            source_code: String::new(),
            code_mirror_doc: String::new(),
            // The initial state will be overwritten by the first `Update` or
            // `LoadFile`, so this value doesn't matter.
            eol: EolType::Lf,
            // Some means this contains valid HTML; None means don't use it
            // (since it would have contained Markdown).
            code_mirror_doc_blocks: Some(Vec::new()),
            prefix_str: "/".to_string() + &prefix.join("/"),
            version: 0.0,
            // Don't send diffs until this is sent.
            sent_full: false,
            capture_context: CaptureContext::default(),
        };
        while continue_loop {
            select! {
                // Look for messages from the IDE.
                Some(ide_message) = tt.from_ide_rx.recv() => {
                    debug!("Received IDE message id = {}, message = {}", ide_message.id, debug_shorten(&ide_message.message));
                    match ide_message.message {
                        // Handle messages that the IDE must not send.
                        EditorMessageContents::Opened(_) |
                        EditorMessageContents::OpenUrl(_) |
                        EditorMessageContents::LoadFile(..) |
                        EditorMessageContents::ClientHtml(_) => {
                            let err = ResultErrTypes::IdeIllegalMessage;
                            error!("{err:?}");
                            send_response(&tt.to_ide_tx, ide_message.id, Err(err)).await;
                        },

                        // Handle messages that are simply passed through.
                        EditorMessageContents::Closed |
                        EditorMessageContents::RequestClose => {
                            debug!("Forwarding it to the Client.");
                            queue_send!(tt.to_client_tx.send(ide_message));
                        },

                        EditorMessageContents::Result(_) => continue_loop = tt.ide_result(ide_message).await,
                        EditorMessageContents::Update(_) => continue_loop = tt.ide_update(ide_message).await,
                        EditorMessageContents::Capture(capture_event) => {
                            // Capture messages affect both upload spooling and
                            // the translation-layer context used for future
                            // server-classified write events.
                            let control_only = capture_control_only(&capture_event);
                            tt.capture_context.update_from_wire(&capture_event);
                            if control_only {
                                debug!("Updated capture context from control-only IDE event.");
                            } else {
                                log_capture_event(&app_state, *capture_event);
                            }
                            send_response(&tt.to_ide_tx, ide_message.id, Ok(ResultOkTypes::Void)).await;
                        },

                        // Update the current file; translate it to a URL then
                        // pass it to the Client.
                        EditorMessageContents::CurrentFile(file_path, _is_text) => {
                            debug!("Translating and forwarding it to the Client.");
                            match try_canonicalize(&file_path) {
                                Ok(clean_file_path) => {
                                    queue_send!(tt.to_client_tx.send(EditorMessage {
                                        id: ide_message.id,
                                        message: EditorMessageContents::CurrentFile(
                                            path_to_url(&tt.prefix_str, Some(&tt.connection_id_raw), &clean_file_path), Some(true)
                                        )
                                    }));
                                    // Store the canonicalized path, not the
                                    // path the IDE sent: the comparisons
                                    // against `current_file` below assume every
                                    // path has one spelling.
                                    tt.current_file = clean_file_path;
                                    // Since this is a new file, mark it as
                                    // unsent in full.
                                    tt.sent_full = false;
                                }
                                Err(err) => {
                                    error!("{err:?}");
                                    send_response(&tt.to_client_tx, ide_message.id, Err(ResultErrTypes::TryCanonicalizeError(err.to_string()))).await;
                                }
                            }
                        }
                    }
                },

                // Handle HTTP requests.
                Some(http_request) = tt.from_http_rx.recv() => {
                    debug!("Received HTTP request for {} and sending LoadFile to IDE, id = {}.", http_request.file_path.display(), tt.id);
                    // Convert the request into a `LoadFile` message.
                    queue_send!(tt.to_ide_tx.send(EditorMessage {
                        id: tt.id,
                        message: EditorMessageContents::LoadFile
                            (http_request.file_path.clone(),
                            // Assign a version to this `LoadFile` request only
                            // if it's the current file and loaded as the file
                            // to edit, not as the sidebar TOC. We can use a
                            // simple comparison, since both file names have
                            // already been canonicalized.
                            http_request.file_path == tt.current_file &&
                            http_request.flags == ProcessingTaskHttpRequestFlags::None
                        )
                    }));
                    // Store the ID and request, which are needed to send a
                    // response when the `LoadFile` result is received.
                    tt.load_file_requests.insert(tt.id.to_bits(), http_request);
                    tt.id += MESSAGE_ID_INCREMENT;
                }

                // Handle messages from the client.
                Some(client_message) = tt.from_client_rx.recv() => {
                    debug!("Received Client message id = {}, message = {}", client_message.id, debug_shorten(&client_message.message));
                    match client_message.message {
                        // Handle messages that the client must not send.
                        EditorMessageContents::Opened(_) |
                        EditorMessageContents::LoadFile(..) |
                        EditorMessageContents::RequestClose |
                        EditorMessageContents::ClientHtml(_) => {
                            let err = ResultErrTypes::ClientIllegalMessage;
                            error!("{err:?}");
                            send_response(&tt.to_client_tx, client_message.id, Err(err)).await;
                        },

                        // Handle messages that are simply passed through.
                        EditorMessageContents::Closed => {
                            debug!("Forwarding it to the IDE.");
                            queue_send!(tt.to_ide_tx.send(client_message));
                        },

                        EditorMessageContents::Result(ref result) => {
                            debug!("Forwarding it to the IDE.");
                            // If the Client can't read our diff, send the full
                            // text next time.
                            if matches!(result, Err(ResultErrTypes::OutOfSync(..))) {
                                tt.sent_full = false;
                            }
                            queue_send!(tt.to_ide_tx.send(client_message));
                        },

                        // Open a web browser when requested.
                        EditorMessageContents::OpenUrl(url) => {
                            // This doesn't work in Codespaces. TODO: send this
                            // back to the VSCode window, then call
                            // `vscode.env.openExternal(vscode.Uri.parse(url))`.
                            if let Err(err) = webbrowser::open(&url) {
                                let err = ResultErrTypes::WebBrowserOpenFailed(err.to_string());
                                error!("{err:?}");
                                send_response(&tt.to_client_tx, client_message.id, Err(err)).await;
                            } else {
                                send_response(&tt.to_client_tx, client_message.id, Ok(ResultOkTypes::Void)).await;
                            }
                        },

                        EditorMessageContents::Update(_) => continue_loop = tt.client_update(client_message).await,
                        EditorMessageContents::Capture(capture_event) => {
                            // Same capture handling as IDE messages: update the
                            // context first, then store only non-control
                            // events.
                            let control_only = capture_control_only(&capture_event);
                            tt.capture_context.update_from_wire(&capture_event);
                            if control_only {
                                debug!("Updated capture context from control-only Client event.");
                            } else {
                                log_capture_event(&app_state, *capture_event);
                            }
                            send_response(&tt.to_client_tx, client_message.id, Ok(ResultOkTypes::Void)).await;
                        },

                        // Update the current file; translate it to a URL then
                        // pass it to the IDE.
                        EditorMessageContents::CurrentFile(url_string, _is_text) => {
                            debug!("Forwarding translated path to IDE.");
                            let result = match url_to_path(&url_string, tt.prefix) {
                                Err(err) => Err(ResultErrTypes::UrlToPathError(url_string.clone(), err.to_string())),
                                Ok(file_path) => {
                                    match file_path.to_str() {
                                        None => Err(ResultErrTypes::NoPathToString(file_path)),
                                        Some(file_path_string) => {
                                            // Use a
                                            // [binary file sniffer](#binary-file-sniffer)
                                            // to determine if the file is text or
                                            // binary.
                                            let is_text = if let Ok(mut fc) = File::open(&file_path).await {
                                                try_read_as_text(&mut fc).await.is_some()
                                            } else {
                                                false
                                            };
                                            queue_send!(tt.to_ide_tx.send(EditorMessage {
                                                id: client_message.id,
                                                message: EditorMessageContents::CurrentFile(file_path_string.to_string(), Some(is_text))
                                            }));
                                            tt.current_file = file_path;
                                            // Since this is a new file, the full text
                                            // hasn't been sent yet.
                                            tt.sent_full = false;
                                            Ok(())
                                        }
                                    }
                                }
                            };
                            if let Err(msg) = result {
                                error!("{msg}");
                                send_response(&tt.to_client_tx, client_message.id, Err(msg)).await;
                            }
                        }
                    }
                },

                else => break
            }
        }
        (from_ide_rx, from_client_rx) = (tt.from_ide_rx, tt.from_client_rx);
    }
    debug!("VSCode processing task shutting down.");
    if app_state
        .processing_task_queue_tx
        .lock()
        .unwrap()
        .remove(&connection_id)
        .is_none()
    {
        error!("Unable to remove connection ID {connection_id} from processing task queue.");
    }
    if app_state
        .client_queues
        .lock()
        .unwrap()
        .remove(&connection_id)
        .is_none()
    {
        error!("Unable to remove connection ID {connection_id} from client queues.");
    }
    if app_state
        .ide_queues
        .lock()
        .unwrap()
        .remove(&connection_id)
        .is_none()
    {
        error!("Unable to remove connection ID {connection_id} from IDE queues.");
    }

    from_ide_rx.close();
    from_client_rx.close();

    // Drain any remaining messages after closing the queue.
    while let Some(m) = from_ide_rx.recv().await {
        warn!("Dropped queued message {m:?}");
    }
    while let Some(m) = from_client_rx.recv().await {
        warn!("Dropped queued message {m:?}");
    }
    debug!("VSCode processing task exited.");
}

// These provide translation for messages passing through the Server.
impl TranslationTask {
    fn capture_file_path(file_path: &Path) -> Option<String> {
        file_path.to_str().map(str::to_string)
    }

    fn log_server_capture_event(
        &mut self,
        event_type: CaptureEventType,
        file_path: &Path,
        data: serde_json::Value,
    ) {
        let Some(capture_event) = self.capture_context.capture_event(
            event_type,
            Self::capture_file_path(file_path),
            data,
        ) else {
            debug!("Skipping server-classified capture event; capture identity is not known yet.");
            return;
        };
        log_capture_event(&self.app_state, capture_event);
    }

    fn log_raw_write_event(&mut self, file_path: &Path, after: &str) {
        let before = self.source_code.as_str();
        if before == after {
            return;
        }
        let code_diff = diff_str(before, after);
        self.log_server_capture_event(
            CaptureEventType::WriteCode,
            file_path,
            serde_json::json!({
                "source": "server_translation",
                "classification_basis": "raw_text",
                "diff": &code_diff,
            }),
        );
    }

    fn log_code_mirror_write_events(
        &mut self,
        file_path: &Path,
        metadata: &SourceFileMetadata,
        after: &CodeMirror,
        after_source: Option<&str>,
        source: &str,
    ) {
        if metadata.mode == MARKDOWN_MODE {
            let markdown_diff = {
                let before_source = self.source_code.as_str();
                let after_source = after_source.unwrap_or(&after.doc);
                (before_source != after_source).then(|| diff_str(before_source, after_source))
            };
            if let Some(diff) = markdown_diff {
                self.log_server_capture_event(
                    CaptureEventType::WriteDoc,
                    file_path,
                    serde_json::json!({
                        "source": source,
                        "classification_basis": "markdown_source",
                        "mode": metadata.mode,
                        "diff": diff,
                    }),
                );
            }
            return;
        }

        let code_diff = {
            let before_doc = self.code_mirror_doc.as_str();
            (before_doc != after.doc).then(|| diff_str(before_doc, &after.doc))
        };
        let (doc_blocks_changed, doc_block_count_before, doc_block_diff) = {
            let before_doc_blocks = self.code_mirror_doc_blocks.as_ref();
            let doc_blocks_changed = match before_doc_blocks {
                Some(before) => !doc_blocks_compare(before, &after.doc_blocks),
                None => !after.doc_blocks.is_empty(),
            };
            let doc_block_diff = before_doc_blocks.map(|before| {
                serde_json::json!(diff_code_mirror_doc_blocks(before, &after.doc_blocks))
            });
            (
                doc_blocks_changed,
                before_doc_blocks.map_or(0, Vec::len),
                doc_block_diff,
            )
        };

        if let Some(diff) = code_diff {
            self.log_server_capture_event(
                CaptureEventType::WriteCode,
                file_path,
                serde_json::json!({
                    "source": source,
                    "classification_basis": "codemirror_code_text",
                    "mode": metadata.mode,
                    "diff": &diff,
                }),
            );
        }

        if doc_blocks_changed {
            self.log_server_capture_event(
                CaptureEventType::WriteDoc,
                file_path,
                serde_json::json!({
                    "source": source,
                    "classification_basis": "codemirror_doc_blocks",
                    "mode": metadata.mode,
                    "doc_block_count_before": doc_block_count_before,
                    "doc_block_count_after": after.doc_blocks.len(),
                    "doc_block_diff": doc_block_diff,
                }),
            );
        }
    }

    // Pass a `Result` message to the Client, unless it's a `LoadFile` result.
    #[allow(clippy::too_many_lines)]
    async fn ide_result(&mut self, ide_message: EditorMessage) -> bool {
        let EditorMessageContents::Result(ref result) = ide_message.message else {
            panic!("Should only be called with a result.");
        };
        let is_loadfile = match result {
            // See if this error was produced by a `LoadFile` result.
            Err(_) => self
                .load_file_requests
                .contains_key(&ide_message.id.to_bits()),
            Ok(result_ok) => match result_ok {
                ResultOkTypes::Void => false,
                ResultOkTypes::LoadFile(_) => true,
            },
        };
        // Pass the message to the client if this isn't a `LoadFile` result (the
        // only type of result which the Server should handle).
        if !is_loadfile {
            debug!("Forwarding it to the Client.");
            // If the Server can't read our diff, send the full text next time.
            if matches!(result, Err(ResultErrTypes::OutOfSync(..))) {
                self.sent_full = false;
            }
            queue_send_func!(self.to_client_tx.send(ide_message));
            return true;
        }
        // Ensure there's an HTTP request for this `LoadFile` result.
        let Some(http_request) = self.load_file_requests.remove(&ide_message.id.to_bits()) else {
            error!(
                "Error: no HTTP request found for LoadFile result ID {}.",
                ide_message.id
            );
            return true;
        };

        // Take ownership of the result after sending it above (which requires
        // ownership).
        let EditorMessageContents::Result(result) = ide_message.message else {
            panic!("Not a result.");
        };
        // Get the file contents from a `LoadFile` result; otherwise, this is
        // None.
        let file_contents_option = match result {
            Err(err) => {
                error!("{err:?}");
                None
            }
            Ok(result_ok) => match result_ok {
                ResultOkTypes::Void => panic!("LoadFile result should not be void."),
                ResultOkTypes::LoadFile(file_contents) => file_contents,
            },
        };

        // Process the file contents. Since VSCode doesn't have a PDF viewer,
        // determine if this is a PDF file. (TODO: look at the magic number also
        // -- "%PDF").
        let use_pdf_js = http_request.file_path.extension() == Some(OsStr::new("pdf"));
        let ((simple_http_response, option_update), file_contents) = match file_contents_option {
            Some((file_contents, new_version)) => {
                // Only pay attention to the version if this is an editable
                // Client file.
                if http_request.file_path == self.current_file
                    && http_request.flags == ProcessingTaskHttpRequestFlags::None
                {
                    self.version = new_version;
                }
                // The IDE just sent the full contents; we're sending full
                // contents to the Client.
                self.sent_full = true;
                (
                    file_to_response(
                        &http_request,
                        &self.cache,
                        new_version,
                        &self.current_file,
                        Some(&file_contents),
                        use_pdf_js,
                    )
                    .await,
                    file_contents,
                )
            }
            None => {
                // The file wasn't available in the IDE. Look for it in the
                // filesystem.
                match File::open(&http_request.file_path).await {
                    Err(err) => (
                        (
                            SimpleHttpResponse::Err(SimpleHttpResponseError::Io(err)),
                            None,
                        ),
                        // There's no file, so return empty contents, which will
                        // be ignored.
                        String::new(),
                    ),
                    Ok(mut fc) => {
                        let option_file_contents = try_read_as_text(&mut fc).await;
                        (
                            file_to_response(
                                &http_request,
                                &self.cache,
                                self.version,
                                &self.current_file,
                                option_file_contents.as_ref(),
                                use_pdf_js,
                            )
                            .await,
                            // If the file is binary, return empty contents,
                            // which will be ignored.
                            option_file_contents.unwrap_or(String::new()),
                        )
                    }
                }
            }
        };
        if let Some(update) = option_update {
            let Some(ref tmp) = update.contents else {
                panic!("Contents must always be provided.");
            };
            let CodeMirrorDiffable::Plain(ref plain) = tmp.source else {
                panic!("Diff not supported.");
            };
            self.source_code = file_contents;
            self.eol = find_eol_type(&self.source_code);
            // We must clone here, since the original is placed in the TX queue.
            self.code_mirror_doc.clone_from(&plain.doc);
            self.code_mirror_doc_blocks = Some(plain.doc_blocks.clone());

            debug!("Sending Update from LoadFile to Client, id = {}.", self.id);
            queue_send_func!(self.to_client_tx.send(EditorMessage {
                id: self.id,
                message: EditorMessageContents::Update(update)
            }));
            self.id += MESSAGE_ID_INCREMENT;
        }
        debug!("Sending HTTP response.");
        if let Err(err) = http_request.response_queue.send(simple_http_response) {
            error!("Unable to enqueue: {err:?}");
            return false;
        }

        true
    }

    #[allow(clippy::too_many_lines)]
    async fn ide_update(&mut self, ide_message: EditorMessage) -> bool {
        let EditorMessageContents::Update(update) = ide_message.message else {
            panic!("Expected update message.");
        };
        // Normalize the provided file name.
        let result = match try_canonicalize(&update.file_path) {
            Err(err) => Err(ResultErrTypes::TryCanonicalizeError(err.to_string())),
            Ok(clean_file_path) => {
                match update.contents {
                    None => {
                        queue_send_func!(self.to_client_tx.send(EditorMessage {
                            id: ide_message.id,
                            message: EditorMessageContents::Update(UpdateMessageContents {
                                file_path: clean_file_path.to_str().expect("Since the path started as a string, assume it losslessly translates back to a string.").to_string(),
                                cursor_position: update.cursor_position,
                                scroll_position: update.scroll_position,
                                is_re_translation: false,
                                contents: None,
                            }),
                        }));
                        Ok(ResultOkTypes::Void)
                    }

                    Some(contents) => {
                        match contents.source {
                            CodeMirrorDiffable::Diff(_diff) => Err(ResultErrTypes::TodoDiffSupport),
                            CodeMirrorDiffable::Plain(code_mirror) => {
                                // If there are Windows newlines, replace with
                                // Unix; this is reversed when the file is sent
                                // back to the IDE.
                                self.eol = find_eol_type(&code_mirror.doc);
                                let doc_normalized_eols = code_mirror.doc.replace("\r\n", "\n");
                                // Translate the file.
                                match source_to_codechat_for_web_string(
                                    &doc_normalized_eols,
                                    &self.current_file,
                                    contents.version,
                                    false,
                                    &self.cache,
                                ) {
                                    Err(err) => {
                                        Err(ResultErrTypes::CannotTranslateSource(err.to_string()))
                                    }
                                    Ok((translation_results_string, _path_to_toc)) => {
                                        match translation_results_string {
                                            TranslationResultsString::CodeChat(ccfw) => {
                                                // Send the new translated contents.
                                                debug!("Sending translated contents to Client.");
                                                let CodeMirrorDiffable::Plain(
                                                    ref code_mirror_translated,
                                                ) = ccfw.source
                                                else {
                                                    panic!("Unexpected diff value.");
                                                };
                                                if self.capture_context.is_active() {
                                                    self.log_code_mirror_write_events(
                                                        &clean_file_path,
                                                        &ccfw.metadata,
                                                        code_mirror_translated,
                                                        Some(&code_mirror.doc),
                                                        "ide",
                                                    );
                                                }
                                                // Send a diff if possible.
                                                let client_contents = if self.sent_full {
                                                    self.diff_code_mirror(
                                                        ccfw.metadata.clone(),
                                                        self.version,
                                                        ccfw.version,
                                                        code_mirror_translated,
                                                    )
                                                } else {
                                                    self.sent_full = true;
                                                    ccfw.clone()
                                                };
                                                queue_send_func!(self.to_client_tx.send(EditorMessage {
                                                    id: ide_message.id,
                                                    message: EditorMessageContents::Update(UpdateMessageContents {
                                                        file_path: clean_file_path.to_str().expect("Since the path started as a string, assume it losslessly translates back to a string.").to_string(),
                                                        cursor_position: update.cursor_position,
                                                        scroll_position: update.scroll_position,
                                                        is_re_translation: false,
                                                        contents: Some(client_contents),
                                                    }),
                                                }));
                                                // Update to the latest code after
                                                // computing diffs. To avoid ownership
                                                // problems, re-define `ccfw_source_plain`.
                                                let CodeMirrorDiffable::Plain(
                                                    code_mirror_translated,
                                                ) = ccfw.source
                                                else {
                                                    panic!("{}", "Unexpected diff value.");
                                                };
                                                self.source_code = code_mirror.doc;
                                                self.code_mirror_doc = code_mirror_translated.doc;
                                                self.code_mirror_doc_blocks =
                                                    Some(code_mirror_translated.doc_blocks);
                                                // Update to the version of the file just
                                                // sent.
                                                self.version = contents.version;
                                                Ok(ResultOkTypes::Void)
                                            }
                                            // TODO
                                            TranslationResultsString::Binary => {
                                                Err(ResultErrTypes::TodoBinarySupport)
                                            }
                                            TranslationResultsString::Unknown => {
                                                if self.capture_context.is_active() {
                                                    self.log_raw_write_event(
                                                        &clean_file_path,
                                                        &code_mirror.doc,
                                                    );
                                                }
                                                // Send the new raw contents.
                                                debug!("Sending translated contents to Client.");
                                                queue_send_func!(self.to_client_tx.send(EditorMessage {
                                                    id: ide_message.id,
                                                    message: EditorMessageContents::Update(UpdateMessageContents {
                                                        file_path: clean_file_path.to_str().expect("Since the path started as a string, assume it losslessly translates back to a string.").to_string(),
                                                        cursor_position: update.cursor_position,
                                                        scroll_position: update.scroll_position,
                                                        is_re_translation: false,
                                                        contents: Some(CodeChatForWeb {
                                                            metadata: SourceFileMetadata {
                                                                // Since this is raw data, `mode` doesn't
                                                                // matter.
                                                                mode: String::new(),
                                                            },
                                                            source: CodeMirrorDiffable::Plain(CodeMirror {
                                                                doc: code_mirror.doc.clone(),
                                                                doc_blocks: vec![]
                                                            }),
                                                            version: contents.version
                                                        }),
                                                    }),
                                                }));
                                                self.source_code = code_mirror.doc;
                                                self.code_mirror_doc.clone_from(&self.source_code);
                                                self.code_mirror_doc_blocks = Some(vec![]);
                                                Ok(ResultOkTypes::Void)
                                            }
                                            TranslationResultsString::Toc(_) => {
                                                Err(ResultErrTypes::NotToc)
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        };
        // If there's an error, then report it; otherwise, the message is passed
        // to the Client, which will provide the result.
        if let Err(err) = &result {
            error!("{err:?}");
            send_response(&self.to_ide_tx, ide_message.id, result).await;
        }

        true
    }

    /// Return a `CodeChatForWeb` struct containing a diff between
    /// `self.code_mirror_doc` / `self.code_mirror_doc_blocks` and
    /// `code_mirror_translated`.
    fn diff_code_mirror(
        &self,
        // The `metadata` and `version` fields will be copied from this to the
        // returned `CodeChatForWeb` struct.
        metadata: SourceFileMetadata,
        // The version number of the previous (before) data. Typically,
        // `self.version`.
        before_version: f64,
        // The version number for the resulting return struct.
        version: f64,
        // This provides the after data for the diff; before data comes from
        // `self.code_mirror` / `self.code_mirror_doc`.
        code_mirror_after: &CodeMirror,
    ) -> CodeChatForWeb {
        assert!(self.sent_full);
        let doc_diff = diff_str(&self.code_mirror_doc, &code_mirror_after.doc);
        let Some(ref cmdb) = self.code_mirror_doc_blocks else {
            panic!("Should have diff of doc blocks!");
        };
        let doc_blocks_diff = diff_code_mirror_doc_blocks(cmdb, &code_mirror_after.doc_blocks);
        CodeChatForWeb {
            // Clone needed here, so we can copy it later.
            metadata,
            source: CodeMirrorDiffable::Diff(CodeMirrorDiff {
                doc: doc_diff,
                doc_blocks: doc_blocks_diff,
                // The diff was made between the before version (this) and the
                // after version (`ccfw.version`).
                version: before_version,
            }),
            version,
        }
    }

    #[allow(clippy::too_many_lines)]
    async fn client_update(&mut self, client_message: EditorMessage) -> bool {
        let EditorMessageContents::Update(update_message_contents) = client_message.message else {
            panic!("Expected update message.");
        };
        debug!("Forwarding translation of it to the IDE.");
        match try_canonicalize(&update_message_contents.file_path) {
            Err(err) => {
                let err = ResultErrTypes::TryCanonicalizeError(err.to_string());
                error!("{err:?}");
                send_response(&self.to_client_tx, client_message.id, Err(err)).await;
                return true;
            }
            Ok(clean_file_path) => {
                let codechat_for_web = match update_message_contents.contents {
                    None => None,
                    Some(cfw) => match codechat_for_web_to_source(&cfw) {
                        Ok(new_source_code) => {
                            // Update the stored CodeMirror data structures with
                            // what we just received. This must be updated
                            // before we can translate back to check for changes
                            // (the next step).
                            let CodeMirrorDiffable::Plain(ref code_mirror) = cfw.source else {
                                // TODO: support diffable!
                                panic!("Diff not supported.");
                            };
                            if self.capture_context.is_active() {
                                self.log_code_mirror_write_events(
                                    &clean_file_path,
                                    &cfw.metadata,
                                    code_mirror,
                                    Some(&new_source_code),
                                    "client",
                                );
                            }
                            self.code_mirror_doc.clone_from(&code_mirror.doc);
                            self.code_mirror_doc_blocks = Some(code_mirror.doc_blocks.clone());
                            // We may need to change this version if we send a
                            // diff back to the Client.
                            let mut cfw_version = cfw.version;

                            // Translate back to the Client to see if there are
                            // any changes after this conversion.
                            if let Ok(ccfws) = source_to_codechat_for_web_string(
                                &new_source_code,
                                &clean_file_path,
                                cfw.version,
                                false,
                                &self.cache,
                            ) && let TranslationResultsString::CodeChat(ccfw) = ccfws.0
                                && let CodeMirrorDiffable::Plain(code_mirror_translated) =
                                    ccfw.source
                                && self.sent_full
                            {
                                // Determine if the re-translation includes
                                // changes (such as line wrapping in doc blocks
                                // which changes line numbering, creation of a
                                // new doc block from previous code block text,
                                // insertion of math, or updates from future
                                // document intelligence such as renamed
                                // headings, etc.). Note that strict HTML
                                // comparison fails, since TinyMCE modifies
                                // whitespace and some characters; for example,
                                // `👨‍👦` becomes `👨&zwj;👦` after processing by
                                // TinyMCE. Therefore, HTML processed by TinyMCE
                                // needs to be normalized before it can be
                                // compared.
                                //
                                // 1. Document-only: HTML is stored in `.doc`;
                                //    ignore `.doc_blocks`.
                                // 2. Normal mode: HTML is stored in
                                //    `.doc_blocks`; perform a binary compare of
                                //    `.doc`, then an HTML comparison of
                                //    `.doc_blocks`.
                                //
                                // It looks like comparing HTML is risky, since
                                // TinyMCE (or something) store emojis
                                // differently. Perhaps we need to compare
                                // Markdown instead of HTML? Or HTML after
                                // processing? The second seems easier.
                                let is_markdown_mode = cfw.metadata.mode == MARKDOWN_MODE;
                                if (is_markdown_mode
                                    && !compare_html(
                                        &code_mirror_translated.doc,
                                        &self.code_mirror_doc,
                                    ))
                                    || (!is_markdown_mode
                                        && (code_mirror_translated.doc != self.code_mirror_doc
                                            || !doc_blocks_compare(
                                                &code_mirror_translated.doc_blocks,
                                                self.code_mirror_doc_blocks.as_ref().unwrap(),
                                            )))
                                {
                                    // Use a whole number to avoid encoding
                                    // differences with fractional values.
                                    // Precision loss from the u64 -> f64 cast
                                    // is fine, since we just need a unique-ish
                                    // version number.
                                    cfw_version = {
                                        #[allow(clippy::cast_precision_loss)]
                                        let v = random::<u64>() as f64;
                                        v
                                    };
                                    // The Client needs an update.
                                    let client_contents = self.diff_code_mirror(
                                        cfw.metadata.clone(),
                                        cfw.version,
                                        cfw_version,
                                        &code_mirror_translated,
                                    );
                                    debug!(
                                        "Sending re-translation update id = {} back to the Client.",
                                        self.id
                                    );
                                    queue_send_func!(self.to_client_tx.send(EditorMessage {
                                        id: self.id,
                                        message: EditorMessageContents::Update(
                                            UpdateMessageContents {
                                                file_path: update_message_contents.file_path,
                                                // Don't change the current position, since
                                                // the Client editing position should be
                                                // left undisturbed.
                                                cursor_position: None,
                                                scroll_position: None,
                                                is_re_translation: true,
                                                contents: Some(client_contents),
                                            }
                                        )
                                    }));
                                    self.id += MESSAGE_ID_INCREMENT;
                                    // Update with what was just sent to the
                                    // client.
                                    self.code_mirror_doc = code_mirror_translated.doc;
                                    self.code_mirror_doc_blocks =
                                        Some(code_mirror_translated.doc_blocks);
                                }
                            }
                            // Correct EOL endings for use with the IDE.
                            let new_source_code_eol = eol_convert(new_source_code, &self.eol);
                            let new_cfw = if self.sent_full && self.allow_source_diffs {
                                Some(CodeChatForWeb {
                                    metadata: cfw.metadata,
                                    source: CodeMirrorDiffable::Diff(CodeMirrorDiff {
                                        // Diff with correct EOLs, so that (for
                                        // CRLF files as well as LF files) offsets
                                        // are correct.
                                        doc: diff_str(&self.source_code, &new_source_code_eol),
                                        doc_blocks: vec![],
                                        version: self.version,
                                    }),
                                    version: cfw_version,
                                })
                            } else {
                                Some(CodeChatForWeb {
                                    metadata: cfw.metadata,
                                    source: CodeMirrorDiffable::Plain(CodeMirror {
                                        // We must clone here, so that it can be
                                        // placed in the TX queue.
                                        doc: new_source_code_eol.clone(),
                                        doc_blocks: vec![],
                                    }),
                                    version: cfw_version,
                                })
                            };
                            self.version = cfw_version;
                            self.source_code = new_source_code_eol;
                            new_cfw
                        }
                        Err(message) => {
                            let err = ResultErrTypes::CannotTranslateCodeChat(message.to_string());
                            error!("{err:?}");
                            send_response(&self.to_client_tx, client_message.id, Err(err)).await;
                            return true;
                        }
                    },
                };

                // Translate the cursor position from `DomLocation` (the
                // Client's DOM-based coordinate) to `Line` (the IDE's
                // line-number coordinate) before forwarding to the IDE, which
                // only understands line numbers.
                let cursor_position = if let Some(CursorPosition::DomLocation {
                    from,
                    dom_path,
                    dom_offset,
                }) = update_message_contents.cursor_position
                {
                    // Use a closure to allow early returns on error (returning
                    // `None` so the IDE receives no cursor position).
                    (|| {
                        // Detect Markdown mode: Markdown documents store all
                        // HTML in `code_mirror_doc` with an empty doc-blocks
                        // list; CodeChat documents have non-empty doc blocks.
                        // We can't rely on the lexer name in
                        // `CodeChatForWeb::SourceFileMetaData`, since the
                        // message `contents` may be None. This won't confuse a
                        // CodeChat document with no doc blocks, since the
                        // Client won't send a `DomLocation` in this case.
                        let is_markdown = self
                            .code_mirror_doc_blocks
                            .as_ref()
                            .is_none_or(std::vec::Vec::is_empty);

                        // 1. Find the HTML (for a Markdown document) or the doc
                        //    block the cursor is in. Create a temporary
                        //    one-element `Vec<CodeDocBlock>` from this
                        //    containing only the relevant doc block.
                        let (preceding_newlines, doc_block) = if is_markdown {
                            // 1. For Markdown, there are zero preceding
                            //    newlines and the relevant HTML is in
                            //    `self.code_mirror_doc`.
                            (
                                0,
                                DocBlock {
                                    indent: String::new(),
                                    delimiter: String::new(),
                                    contents: self.code_mirror_doc.clone(),
                                    lines: 0,
                                },
                            )
                        } else {
                            // 1. Locate the relevant doc block, identified by
                            //    its starting offset matching `from`. If not
                            //    found, abort and return `None`.
                            let blocks = self.code_mirror_doc_blocks.as_ref().unwrap();
                            let block = blocks.iter().find(|b| b.from == from)?;

                            // 2. Count all newlines in `self.code_mirror_doc`
                            //    which precede `from`. `from` is in UTF-16 code
                            //    units; convert to a byte index first.
                            let byte_idx = byte_index_of(&self.code_mirror_doc, from);
                            let preceding_newlines = self.code_mirror_doc[..byte_idx]
                                .chars()
                                .filter(|&c| c == '\n')
                                .count();

                            (
                                preceding_newlines,
                                DocBlock {
                                    indent: block.indent.clone(),
                                    delimiter: block.delimiter.clone(),
                                    contents: block.contents.clone(),
                                    lines: 0,
                                },
                            )
                        };

                        // 2. Insert a `UNICODE_CURSOR_MARKER` at the cursor
                        //    location specified by `dom_offsets`, then convert
                        //    the HTML to Markdown.
                        let translated = doc_block_html_to_markdown(
                            vec![CodeDocBlock::DocBlock(doc_block)],
                            Some(&(dom_path, dom_offset)),
                        )
                        .ok()?;
                        let CodeDocBlock::DocBlock(db) = &translated[0] else {
                            return None;
                        };

                        // 3. Count newlines before the marker and add them to
                        //    the preceding-newlines total for the final line
                        //    number. If the marker is absent, treat its
                        //    position as 0 (contributing zero newlines), even
                        //    if an existing marker precedes the inserted one.
                        let marker_byte = db.contents.find(UNICODE_CURSOR_MARKER).unwrap_or(0);
                        let newlines_before_marker = db.contents[..marker_byte]
                            .chars()
                            .filter(|&c| c == '\n')
                            .count();

                        // CodeMirror uses 1-based line numbers.
                        Some(CursorPosition::Line(
                            u32::try_from(preceding_newlines + newlines_before_marker + 1).ok()?,
                        ))
                    })()
                } else {
                    update_message_contents.cursor_position
                };

                debug!("Sending update id = {}", client_message.id);
                queue_send_func!(self.to_ide_tx.send(EditorMessage {
                    id: client_message.id,
                    message: EditorMessageContents::Update(UpdateMessageContents {
                        file_path: clean_file_path.to_str().expect("Since the path started as a string, assume it losslessly translates back to a string.").to_string(),
                        cursor_position,
                        scroll_position: update_message_contents.scroll_position,
                        is_re_translation: false,
                        contents: codechat_for_web,
                    })
                }));
            }
        }

        true
    }
}

// Given a string using LF-only (Unix style) line endings, convert it to CRLF
// (Windows style) line endings if `eol_type` requests it.
fn eol_convert(s: String, eol_type: &EolType) -> String {
    if eol_type == &EolType::Crlf {
        // There shouldn't be any Windows-style CRLFs -- but if there are,
        // handle this nicely.
        s.replace("\r\n", "\n").replace('\n', "\r\n")
    } else {
        s
    }
}

fn compare_html_walker(node: &Rc<Node>) {
    let mut index = 0;
    while index < node.children.borrow().len() {
        if let Some(child) = remove_tinymce_data(node, index) {
            compare_html_walker(&child);
            index += 1;
        }
        // If remove\_tinymce\_data returned None, the node was removed with no
        // replacement; the next child is now at the same index.
    }
}

// TinyMCE replaces newlines inside paragraphs with a space and (I think) avoids
// surrogate pairs by breaking them into a series of UTF-16 characters.
// Therefore, to compare HTML, normalize HTML touched by TinyMCE first.
fn compare_html(
    // A string containing HTML that's been normalized by html5ever.
    normalized_html: &str,
    // A string containing HTML that's not normalized; for example, data after
    // processing by TinyMCE.
    raw_html: &str,
) -> bool {
    // Remove TinyMCE temp data before comparison; this also normalizes the
    // characters via html5ever. Order here in very important: the
    // `source_to_codechat_for_web()` function transforms, then minifies, since
    // both transform and minify tend to rearrange attributes in their own
    // preferred order. Use the same order to make comparisons work.
    if let Ok(raw_html) = transform_html(raw_html, compare_html_walker)
        && let Ok(raw_html) = minify(&raw_html)
    {
        // pulldown-cmark puts a newline after a `<br>`, which `minify` doesn't
        // remove but TinyMCE does.
        let normalized_html = normalized_html.replace("<br> ", "<br>");
        // TinyMCE wraps an `<iframe>` in paragraph tags: for example,
        // `<p>Previous paragraph</p><p><iframe>...</iframe></p>`, which
        // minifies to `<p>Previous paragraph<p><iframe>...</iframe>`. The IDE
        // doesn't wrap the `<iframe>`; for example, `<p>Previous
        // paragraph</p><iframe>...</iframe>`, which minifies to `<p>Previous
        // paragraph</p><iframe>...</iframe>`. Fix up this difference.
        let raw_html = raw_html.replace("<p><iframe ", "</p><iframe ");

        normalized_html == raw_html
    } else {
        false
    }
}

/// Given vectors of two doc blocks, compare them, ignoring newlines.
fn doc_blocks_compare(a: &CodeMirrorDocBlockVec, b: &CodeMirrorDocBlockVec) -> bool {
    if a.len() != b.len() {
        return false;
    }

    a.iter().zip(b).all(|el| {
        let a = el.0;
        let b = el.1;
        a.from == b.from
            && a.to == b.to
            && a.indent == b.indent
            && a.delimiter == b.delimiter
            // Most doc blocks haven't been touched by TinyMCE. Try a fast
            // binary compare first.
            && (a.contents == b.contents ||
            compare_html(&a.contents, &b.contents))
    })
}

// Provide a simple debug function that prints only the first
// `MAX_MESSAGE_LENGTH` characters of the provided value.
fn debug_shorten<T: Debug>(val: T) -> String {
    if cfg!(debug_assertions) {
        let msg = format!("{val:?}");
        let max_index = msg
            .char_indices()
            .nth(MAX_MESSAGE_LENGTH)
            .unwrap_or((msg.len(), 'x'))
            .0;
        msg[..max_index].to_string()
    } else {
        String::new()
    }
}

// Tests
// -----
#[cfg(test)]
mod tests {
    use crate::{
        capture::{CaptureContext, CaptureEventType, CaptureEventWire, capture_control_only},
        processing::CodeMirrorDocBlock,
        translation::doc_blocks_compare,
    };

    /// Minimal test helper for feeding lifecycle/control messages into the
    /// translation-layer capture context.
    fn capture_wire(
        event_type: crate::capture::CaptureEventType,
        data: serde_json::Value,
    ) -> CaptureEventWire {
        CaptureEventWire {
            event_id: None,
            sequence_number: None,
            schema_version: Some(2),
            user_id: "participant".to_string(),
            session_id: Some("session".to_string()),
            event_source: Some("vscode_extension".to_string()),
            language_id: None,
            file_path: None,
            file_hash: None,
            event_type,
            client_tz_offset_min: Some(360),
            data: Some(data),
        }
    }

    #[test]
    fn capture_context_only_generates_events_while_active() {
        let mut context = CaptureContext::default();
        // Without an active capture session, translated writes must be skipped.
        assert!(
            context
                .capture_event(CaptureEventType::WriteCode, None, serde_json::json!({}))
                .is_none()
        );

        context.update_from_wire(&capture_wire(
            CaptureEventType::SessionStart,
            serde_json::json!({
                "capture_active": true,
            }),
        ));
        // A session\_start activates server-side translated write capture.
        assert!(
            context
                .capture_event(CaptureEventType::WriteCode, None, serde_json::json!({}))
                .is_some()
        );

        context.update_from_wire(&capture_wire(
            CaptureEventType::SessionEnd,
            serde_json::json!({
                "capture_active": false,
            }),
        ));
        // A session\_end deactivates translated write capture so stale context
        // cannot continue generating spooled capture events.
        assert!(
            context
                .capture_event(CaptureEventType::WriteCode, None, serde_json::json!({}))
                .is_none()
        );
    }

    #[test]
    fn capture_control_only_is_detected_from_data() {
        // Control-only events are the extension's way to update server capture
        // state without storing the stop signal as a normal event row.
        let wire = capture_wire(
            CaptureEventType::SessionEnd,
            serde_json::json!({
                "capture_active": false,
                "capture_control_only": true,
            }),
        );

        assert!(capture_control_only(&wire));
    }

    #[test]
    fn server_generated_capture_events_have_session_sequence_numbers() {
        let mut context = CaptureContext::default();
        context.update_from_wire(&capture_wire(
            CaptureEventType::SessionStart,
            serde_json::json!({
                "capture_active": true,
            }),
        ));
        let first = context
            .capture_event(CaptureEventType::WriteCode, None, serde_json::json!({}))
            .expect("active context should generate a capture event");
        let second = context
            .capture_event(CaptureEventType::WriteDoc, None, serde_json::json!({}))
            .expect("active context should generate a capture event");

        assert_eq!(first.sequence_number, Some(1));
        assert_eq!(second.sequence_number, Some(2));
        assert_eq!(first.event_source.as_deref(), Some("server_translation"));
        assert_eq!(second.event_source.as_deref(), Some("server_translation"));
    }

    #[test]
    fn test_x1() {
        let ide = vec![CodeMirrorDocBlock {
            from: 0,
            to: 20,
            indent: String::new(),
            delimiter: "//".to_string(),
            contents: "<ul><li><input checked type=checkbox>Task list</ul><p>Line<br> break<p>Non-breaking\u{a0} space.</p><iframe allowfullscreen frameborder=0 height=314 src=https://www.youtube.com/embed/Hp076_dxuVU width=560></iframe>".to_string(),
        }];
        let client = vec![CodeMirrorDocBlock {
            from: 0,
            to: 20,
            indent: String::new(),
            delimiter: "//".to_string(),
            contents: "<ul><li><input type=\"checkbox\" checked=\"checked\">Task list</li></ul><p>Line<br>break</p><p>Non-breaking&nbsp; space.</p><p><span contenteditable=\"false\" data-mce-object=\"iframe\" class=\"mce-preview-object mce-object-iframe\" data-mce-p-allowfullscreen=\"allowfullscreen\" data-mce-p-src=\"https://www.youtube.com/embed/Hp076_dxuVU\" data-mce-p-frameborder=\"0\"><iframe width=\"560\" height=\"314\" src=\"https://www.youtube.com/embed/Hp076_dxuVU\" allowfullscreen=\"allowfullscreen\" frameborder=\"0\"></iframe><span class=\"mce-shim\"></span></span></p>".to_string(),
        }];
        assert!(doc_blocks_compare(&ide, &client));
    }

    #[test]
    fn test_x2() {
        let ide = vec![CodeMirrorDocBlock {
            from: 0,
            to: 20,
            indent: String::new(),
            delimiter: "//".to_string(),
            contents: "<ol><li><ol><li>1</ol></ol>".to_string(),
        }];
        let client = vec![CodeMirrorDocBlock {
            from: 0,
            to: 20,
            indent: String::new(),
            delimiter: "//".to_string(),
            contents: "<ol> <li> <ol> <li> 1 </ol> </li> </ol> </li>".to_string(),
        }];
        assert!(doc_blocks_compare(&ide, &client));
    }
}