libmathcat/

interface.rs

//! The interface module provides functionality both for calling from an API and also running the code from `main`.
//!
#![allow(non_snake_case)]
#![allow(clippy::needless_return)]
use std::cell::RefCell;
use std::sync::LazyLock;

use crate::canonicalize::{as_text, create_mathml_element};
use crate::errors::*;
use phf::phf_map;
use regex::{Captures, Regex};
use sxd_document_no_unsafe::dom::{Element, Document, ChildOfRoot, ChildOfElement, Attribute};
use sxd_document_no_unsafe::parser;
use sxd_document_no_unsafe::Package;
use sxd_document_no_unsafe::{as_str, as_qname};

use crate::canonicalize::{as_element, name};
use crate::shim_filesystem::{find_all_dirs_shim, find_files_in_dir_that_ends_with_shim};
use log::{debug, error};

use crate::navigate::*;
use crate::pretty_print::mml_to_string;
use crate::xpath_functions::{is_leaf, IsNode};
use std::panic::{catch_unwind, AssertUnwindSafe};

/// Maximum depth to prevent stack overflow on deeply nested MathML
pub const MAX_DEPTH: usize = 512;

#[cfg(feature = "enable-logs")]
use std::sync::Once;
#[cfg(feature = "enable-logs")]
static INIT: Once = Once::new();

fn enable_logs() {
    #[cfg(feature = "enable-logs")]
    INIT.call_once(||{
        #[cfg(target_os = "android")]
        {
            use log::*;
            use android_logger::*;
        
            android_logger::init_once(
                Config::default()
                .with_max_level(LevelFilter::Trace)
                .with_tag("MathCat")
            );    
            trace!("Activated Android logger!");  
        }    
    });
}

// For getting a message from a panic
thread_local! {
    // Stores (Message, File, Line)
    static PANIC_INFO: RefCell<Option<(String, String, u32)>> = const { RefCell::new(None) };
}

/// Initialize the panic handler to catch panics and store the message, file, and line number in `PANIC_INFO`.
///
/// Installed once. Under `#[cfg(test)]` the previous hook (cargo's) is chained so assert failures
/// still print normally; production stays silent and relies on [`report_any_panic`].
pub fn init_panic_handler() {
    use std::panic;
    use std::sync::Once;

    static INSTALL: Once = Once::new();
    INSTALL.call_once(|| {
        let previous = panic::take_hook();
        panic::set_hook(Box::new(move |info| {
            let location = info.location()
                .map(|l| format!("{}:{}", l.file(), l.line()))
                .unwrap_or_else(|| "unknown".to_string());

            let payload = info.payload();
            let msg = if let Some(s) = payload.downcast_ref::<&'static str>() {
                s.to_string()
            } else if let Some(s) = payload.downcast_ref::<String>() {
                s.clone()
            } else {
                "Unknown panic payload".to_string()
            };

            // Use try_with/try_borrow_mut to ensure the hook never panics itself
            let _ = PANIC_INFO.try_with(|cell| {
                if let Ok(mut slot) = cell.try_borrow_mut() {
                    *slot = Some((msg, location, 0));
                }
            });

            // cargo test (and other previous hooks) still print; production ATs do not want that spam.
            if cfg!(test) {
                previous(info);
            }
        }));
    });
}

pub fn report_any_panic<T>(result: Result<Result<T, Error>, Box<dyn std::any::Any + Send>>) -> Result<T, Error> {
    match result {
        Ok(val) => val,
        Err(payload) => {
            // Prefer details captured by the hook (includes file:line).
            if let Some((msg, file, line)) = PANIC_INFO.with(|cell| cell.borrow_mut().take()) {
                return Err(anyhow::anyhow!(
                    "MathCAT crash! Please report the following information: '{}' at {}:{}",
                    msg, file, line
                ));
            }
            // Fallback: catch_unwind always provides the payload even if the hook did not run.
            let msg = if let Some(s) = payload.downcast_ref::<&'static str>() {
                (*s).to_string()
            } else if let Some(s) = payload.downcast_ref::<String>() {
                s.clone()
            } else {
                return Err(anyhow::anyhow!("MathCAT crash! -- please report"));
            };
            Err(anyhow::anyhow!(
                "MathCAT crash! Please report the following information: '{}'",
                msg
            ))
        }
    }
} 

// wrap up some common functionality between the call from 'main' and AT
fn cleanup_mathml(mathml: Element) -> Result<Element> {
    trim_element(mathml, false);
    let mathml = crate::canonicalize::canonicalize(mathml)?;
    let mathml = add_ids(mathml);
    return Ok(mathml);
}

thread_local! {
    /// The current node being navigated (also spoken and brailled) is stored in `MATHML_INSTANCE`.
    pub static MATHML_INSTANCE: RefCell<Package> = init_mathml_instance();
}

fn init_mathml_instance() -> RefCell<Package> {
    let package = parser::parse("<math></math>")
        .expect("Internal error in 'init_mathml_instance;: didn't parse initializer string");
    return RefCell::new(package);
}

/// Set the Rules directory
/// IMPORTANT: this should be the very first call to MathCAT. If 'dir' is an empty string, the environment var 'MathCATRulesDir' is tried.
pub fn set_rules_dir(dir: impl AsRef<str>) -> Result<()> {
    enable_logs();
    init_panic_handler();
    let dir = dir.as_ref().to_string();
    let result = catch_unwind(AssertUnwindSafe(|| {
        use std::path::PathBuf;
        let dir_os = if dir.is_empty() {
            std::env::var_os("MathCATRulesDir").unwrap_or_default()
        } else {
            std::ffi::OsString::from(&dir)
        };
        let pref_manager = crate::prefs::PreferenceManager::get();
        pref_manager.borrow_mut().initialize(PathBuf::from(dir_os))
    }));
    return report_any_panic(result);
}

/// Returns the version number (from Cargo.toml) of the build
pub fn get_version() -> String {
    enable_logs();
    const VERSION: &str = env!("CARGO_PKG_VERSION");
    return VERSION.to_string();
}

/// This will override any previous MathML that was set.
/// This returns canonical MathML with 'id's set on any node that doesn't have an id.
/// The ids can be used for sync highlighting if the `Bookmark` API preference is true.
pub fn set_mathml(mathml_str: impl AsRef<str>) -> Result<String> {
    enable_logs();
    // if these are present when resent to MathJaX, MathJaX crashes (https://github.com/mathjax/MathJax/issues/2822)
    static MATHJAX_V2: LazyLock<Regex> = LazyLock::new(|| Regex::new(r#"class *= *['"]MJX-.*?['"]"#).unwrap());
    static MATHJAX_V3: LazyLock<Regex> = LazyLock::new(|| Regex::new(r#"class *= *['"]data-mjx-.*?['"]"#).unwrap());

    // Strip out processing instructions and comments -- these are not MathML and can cause DOS problems in the parser
    static PROCESSING_INSTRUCTION: LazyLock<Regex> = LazyLock::new(|| Regex::new(r#"<\?[\s\S]{1,2048}\?>"#).unwrap());
    static XML_COMMENT: LazyLock<Regex> = LazyLock::new(|| Regex::new(r#"(?s)"#).unwrap());

    // These have some length limits to avoid DOS attacks via long strings
    static NAMESPACE_DECL: LazyLock<Regex> = LazyLock::new(|| Regex::new(r#"xmlns:[[:alpha:]]{1,32}"#).unwrap());
    static PREFIX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r#"(</?)[[:alpha:]]{1,32}:"#).unwrap());
    static HTML_ENTITIES: LazyLock<Regex> = LazyLock::new(|| Regex::new(r#"&([a-zA-Z]{2,10});"#).unwrap());
    let result = catch_unwind(AssertUnwindSafe(|| {
        NAVIGATION_STATE.with(|nav_stack| {
            nav_stack.borrow_mut().reset();
        });

        // We need the main definitions files to be read in so canonicalize can work.
        // This call reads all of them for the current preferences, but that's ok since they will likely be used
        crate::speech::SPEECH_RULES.with(|rules| rules.borrow_mut().read_files())?;

        let mathml_str = mathml_str.as_ref();
        // Safety guard: Reject strings > 1MB to prevent DoS/Stack issues
        if mathml_str.len() > 1024 * 1024 {
            bail!("MathML string of size {} bytes exceeds length limit of 1MB", mathml_str.len());
        }

        return MATHML_INSTANCE.with(|old_package| {
            static HTML_ENTITIES_MAPPING: phf::Map<&str, &str> = include!("entities.in");

            let mut error_message = "".to_string(); // can't return a result inside the replace_all, so we do this hack of setting the message and then returning the error
                                                                     
            let mathml_str = XML_COMMENT.replace_all(mathml_str, "");
            let mathml_str = PROCESSING_INSTRUCTION.replace_all(&mathml_str, "");
            // FIX: need to deal with character data and convert to something the parser knows
            let mathml_str = HTML_ENTITIES.replace_all(&mathml_str, |cap: &Captures| match HTML_ENTITIES_MAPPING.get(&cap[1]) {
                    None => {
                        error_message = format!("No entity named '{}'", &cap[0]);
                        cap[0].to_string()
                    }
                    Some(&ch) => ch.to_string(),
                });

            if !error_message.is_empty() {
                // Clear stale state so subsequent API calls do not return previous user's data (security issue)
                old_package.replace(parser::parse("<math></math>").unwrap());
                bail!(error_message);
            }
            let mathml_str = MATHJAX_V2.replace_all(&mathml_str, "");
            let mathml_str = MATHJAX_V3.replace_all(&mathml_str, "");

            // the speech rules use the xpath "name" function and that includes the prefix
            // getting rid of the prefix properly probably involves a recursive replacement in the tree
            // if the prefix is used, it is almost certainly something like "m" or "mml", so this cheat will work.
            let mathml_str = NAMESPACE_DECL.replace(&mathml_str, "xmlns"); // do this before the PREFIX replace!
            let mathml_str = PREFIX.replace_all(&mathml_str, "$1");

            let new_package = parser::parse(&mathml_str);
            if let Err(e) = new_package {
                // Clear stale state so subsequent API calls do not return previous user's data (security issue)
                old_package.replace(parser::parse("<math></math>").unwrap());
                bail!("Invalid MathML input:\n{}\nError is: {}", mathml_str, e);
            }

            let new_package = new_package.unwrap();
            let mathml = get_element(&new_package);
            let mathml = cleanup_mathml(mathml)?;
            let mathml_string = mml_to_string(mathml);
            old_package.replace(new_package);

            return Ok(mathml_string);
        });
    }));

    return report_any_panic(result);
}

/// Get the spoken text of the MathML that was set.
/// The speech takes into account any AT or user preferences.
pub fn get_spoken_text() -> Result<String> {
    enable_logs();
    let result = catch_unwind(AssertUnwindSafe(|| {
        MATHML_INSTANCE.with(|package_instance| {
            let package_instance = package_instance.borrow();
            let mathml = get_element(&package_instance);
            let new_package = Package::new();
            let intent = crate::speech::intent_from_mathml(mathml, new_package.as_document())?;
            debug!("Intent tree:\n{}", mml_to_string(intent));
            let speech = crate::speech::speak_mathml(intent, "", 0)?;
            return Ok(speech);
        })
    }));
    return report_any_panic(result);
}

/// Get the spoken text for an overview of the MathML that was set.
/// The speech takes into account any AT or user preferences.
/// Note: this implementation for is currently minimal and should not be used.
pub fn get_overview_text() -> Result<String> {
    enable_logs();
    let result = catch_unwind(AssertUnwindSafe(|| {
        MATHML_INSTANCE.with(|package_instance| {
            let package_instance = package_instance.borrow();
            let mathml = get_element(&package_instance);
            let speech = crate::speech::overview_mathml(mathml, "", 0)?;
            return Ok(speech);
        })
    }));
    return report_any_panic(result);
}

/// Get the value of the named preference.
/// None is returned if `name` is not a known preference.
pub fn get_preference(name: impl AsRef<str>) -> Result<String> {
    enable_logs();
    let name = name.as_ref().to_string();
    let result = catch_unwind(AssertUnwindSafe(|| {
        use crate::prefs::NO_PREFERENCE;
        crate::speech::SPEECH_RULES.with(|rules| {
            let rules = rules.borrow();
            let pref_manager = rules.pref_manager.borrow();
            let mut value = pref_manager.pref_to_string(&name);
            if value == NO_PREFERENCE {
                value = pref_manager.pref_to_string(&name);
            }
            if value == NO_PREFERENCE {
                bail!("No preference named '{}'", name);
            } else {
                return Ok(value);
            }
        })
    }));
    return report_any_panic(result);
}

/// Set a MathCAT preference. The preference name should be a known preference name.
/// The value should either be a string or a number (depending upon the preference being set)
/// The list of known user preferences is in the MathCAT user documentation.
/// Here are common preferences set by programs (not settable by the user):
/// * TTS -- SSML, SAPI5, None
/// * Pitch -- normalized at '1.0'
/// * Rate -- words per minute (should match current speech rate).
///   There is a separate "MathRate" that is user settable that causes a relative percentage change from this rate.
/// * Volume -- default 100
/// * Voice -- set a voice to use (not implemented)
/// * Gender -- set pick any voice of the given gender (not implemented)
/// * Bookmark -- set to `true` if a `mark`/`bookmark` should be part of the returned speech (used for sync highlighting)
///
/// Important: both the preference name and value are case-sensitive
///
/// This function can be called multiple times to set different values.
/// The values are persistent and extend beyond calls to [`set_mathml`].
/// A value can be overwritten by calling this function again with a different value.
///
/// Be careful setting preferences -- these potentially override user settings, so only preferences that really need setting should be set.
pub fn set_preference(name: impl AsRef<str>, value: impl AsRef<str>) -> Result<()> {
    enable_logs();
    let name = name.as_ref().to_string();
    let value = value.as_ref().to_string();
    let result = catch_unwind(AssertUnwindSafe(|| {
        set_preference_impl(&name, &value)
    }));
    return report_any_panic(result);
}

fn set_preference_impl(name: &str, value: &str) -> Result<()> {
    let mut value = value.to_string();
    if name == "Language" || name == "LanguageAuto" {
        // check the format
        if value != "Auto" {
            // could get es, es-419, or en-us-nyc ...  we only care about the first two parts so we clean it up a little
            let mut lang_country_split = value.split('-');
            let language = lang_country_split.next().unwrap_or("");
            let country = lang_country_split.next().unwrap_or("");
            if language.len() != 2 {
                bail!(
                    "Improper format for 'Language' preference '{}'. Should be of form 'en' or 'en-gb'",
                    value
                );
            }
            let mut new_lang_country = language.to_string(); // need a temp value because 'country' is borrowed from 'value' above
            if !country.is_empty() {
                new_lang_country.push('-');
                new_lang_country.push_str(country);
            }
            value = new_lang_country;
        }
        if name == "LanguageAuto" && value == "Auto" {
            bail!("'LanguageAuto' can not have the value 'Auto'");
        }
    }

    crate::speech::SPEECH_RULES.with(|rules| -> Result<()> {
        if let Some(error_string) = rules.borrow().get_error() {
            bail!("{}", error_string);
        }
        Ok(())
    })?;

    // Do not hold a SpeechRules borrow while updating preferences: invalidation clears rule caches.
    let pref_manager = crate::prefs::PreferenceManager::get();
    let mut pref_manager = pref_manager.borrow_mut();
    if name == "LanguageAuto" {
        let language_pref = pref_manager.pref_to_string("Language");
        if language_pref != "Auto" {
            bail!(
                "'LanguageAuto' can only be used when 'Language' has the value 'Auto'; Language={}",
                language_pref
            );
        }
    }
    let lower_case_value = value.to_lowercase();
    if lower_case_value == "true" || lower_case_value == "false" {
        pref_manager.set_api_boolean_pref(name, value.to_lowercase() == "true");
    } else {
        match name {
            "Pitch" | "Rate" | "Volume" | "CapitalLetters_Pitch" | "MathRate" | "PauseFactor" => {
                pref_manager.set_api_float_pref(name, to_float(name, &value)?)
            }
            _ => {
                pref_manager.set_string_pref(name, &value)?;
            }
        }
    };

    return Ok(());
}

fn to_float(name: &str, value: &str) -> Result<f64> {
    return match value.parse::<f64>() {
        Ok(val) => Ok(val),
        Err(_) => bail!("SetPreference: preference'{}'s value '{}' must be a float", name, value),
    };
}

/// Get the braille associated with the MathML that was set by [`set_mathml`].
/// The braille returned depends upon the preference for the `code` preference (default `Nemeth`).
/// If 'nav_node_id' is given, it is highlighted based on the value of `BrailleNavHighlight` (default: `EndPoints`)
pub fn get_braille(nav_node_id: impl AsRef<str>) -> Result<String> {
    enable_logs();
    let nav_node_id = nav_node_id.as_ref().to_string();
    let result = catch_unwind(AssertUnwindSafe(|| {
        MATHML_INSTANCE.with(|package_instance| {
            let package_instance = package_instance.borrow();
            let mathml = get_element(&package_instance);
            let braille = crate::braille::braille_mathml(mathml, &nav_node_id)?.0;
            return Ok(braille);
        })
    }));
    return report_any_panic(result);
}

/// Get the braille associated with the current navigation focus of the MathML that was set by [`set_mathml`].
/// The braille returned depends upon the preference for the `code` preference (default `Nemeth`).
/// The returned braille is brailled as if the current navigation focus is the entire expression to be brailled.
pub fn get_navigation_braille() -> Result<String> {
    enable_logs();
    let result = catch_unwind(AssertUnwindSafe(|| {
        MATHML_INSTANCE.with(|package_instance| {
            let package_instance = package_instance.borrow();
            let mathml = get_element(&package_instance);
            let new_package = Package::new(); // used if we need to create a new tree
            let new_doc = new_package.as_document();
            let nav_mathml = NAVIGATION_STATE.with(|nav_stack| {
                return match nav_stack.borrow_mut().get_navigation_mathml(mathml) {
                    Err(e) => Err(e),
                    Ok((found, offset)) => {
                        // get the MathML node and wrap it inside of a <math> element
                        // if the offset is given, we need to get the character it references
                        if offset == 0 {
                            if name(found) == "math" {
                                Ok(found)
                            } else {
                                let new_mathml = create_mathml_element(&new_doc, "math");
                                new_mathml.append_child(copy_mathml(found));
                                new_doc.root().append_child(new_mathml);
                                Ok(new_mathml)
                            }
                        } else if !is_leaf(found) {
                            bail!(
                                "Internal error: non-zero offset '{}' on a non-leaf element '{}'",
                                offset,
                                name(found)
                            );
                        } else if let Some(ch) = as_text(found).chars().nth(offset) {
                            let internal_mathml = create_mathml_element(&new_doc, as_str!(name(found)));
                            internal_mathml.set_text(&ch.to_string());
                            let new_mathml = create_mathml_element(&new_doc, "math");
                            new_mathml.append_child(internal_mathml);
                            new_doc.root().append_child(new_mathml);
                            Ok(new_mathml)
                        } else {
                            bail!(
                                "Internal error: offset '{}' on leaf element '{}' doesn't exist",
                                offset,
                                mml_to_string(found)
                            );
                        }
                    }
                };
            })?;

            let braille = crate::braille::braille_mathml(nav_mathml, "")?.0;
            return Ok(braille);
        })
    }));
    return report_any_panic(result);
}

/// Given a key code along with the modifier keys, the current node is moved accordingly (or value reported in some cases).
/// `key` is the [keycode](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode#constants_for_keycode_value) for the key (in JavaScript, `ev.key_code`)
/// The spoken text for the new current node is returned.
pub fn do_navigate_keypress(
    key: usize,
    shift_key: bool,
    control_key: bool,
    alt_key: bool,
    meta_key: bool,
) -> Result<String> {
    enable_logs();
    let result = catch_unwind(AssertUnwindSafe(|| {
        MATHML_INSTANCE.with(|package_instance| {
            let package_instance = package_instance.borrow();
            let mathml = get_element(&package_instance);
            return do_mathml_navigate_key_press(mathml, key, shift_key, control_key, alt_key, meta_key);
        })
    }));
    return report_any_panic(result);
}

/// Given a navigation command, the current node is moved accordingly.
/// This is a higher level interface than `do_navigate_keypress` for applications that want to interpret the keys themselves.
/// The valid commands are:
/// * Standard move commands:
///   `MovePrevious`, `MoveNext`, `MoveStart`, `MoveEnd`, `MoveLineStart`, `MoveLineEnd`
/// * Movement in a table or elementary math:
///   `MoveCellPrevious`, `MoveCellNext`, `MoveCellUp`, `MoveCellDown`, `MoveColumnStart`, `MoveColumnEnd`
/// * Moving into children or out to parents:
///   `ZoomIn`, `ZoomOut`, `ZoomOutAll`, `ZoomInAll`
/// * Undo the last movement command:
///   `MoveLastLocation`
/// * Read commands (standard speech):
///   `ReadPrevious`, `ReadNext`, `ReadCurrent`, `ReadCellCurrent`, `ReadStart`, `ReadEnd`, `ReadLineStart`, `ReadLineEnd`
/// * Describe commands (overview):
///   `DescribePrevious`, `DescribeNext`, `DescribeCurrent`
/// * Location information:
///   `WhereAmI`, `WhereAmIAll`
/// * Change navigation modes (circle up/down):
///   `ToggleZoomLockUp`, `ToggleZoomLockDown`
/// * Speak the current navigation mode
///   `ToggleSpeakMode`
///
/// There are 10 place markers that can be set/read/described or moved to.
/// * Setting:
///   `SetPlacemarker0`, `SetPlacemarker1`, `SetPlacemarker2`, `SetPlacemarker3`, `SetPlacemarker4`, `SetPlacemarker5`, `SetPlacemarker6`, `SetPlacemarker7`, `SetPlacemarker8`, `SetPlacemarker9`
/// * Reading:
///   `Read0`, `Read1`, `Read2`, `Read3`, `Read4`, `Read5`, `Read6`, `Read7`, `Read8`, `Read9`
/// * Describing:
///   `Describe0`, `Describe1`, `Describe2`, `Describe3`, `Describe4`, `Describe5`, `Describe6`, `Describe7`, `Describe8`, `Describe9`
/// * Moving:
///   `MoveTo0`, `MoveTo1`, `MoveTo2`, `MoveTo3`, `MoveTo4`, `MoveTo5`, `MoveTo6`, `MoveTo7`, `MoveTo8`, `MoveTo9`
///
/// When done with Navigation, call with `Exit`
pub fn do_navigate_command(command: impl AsRef<str>) -> Result<String> {
    enable_logs();
    let command = command.as_ref().to_string();
    let result = catch_unwind(AssertUnwindSafe(|| {
        let cmd = NAV_COMMANDS.get_key(&command); // gets a &'static version of the command
        if cmd.is_none() {
            bail!("Unknown command in call to DoNavigateCommand()");
        };
        let cmd = *cmd.unwrap();
        MATHML_INSTANCE.with(|package_instance| {
            let package_instance = package_instance.borrow();
            let mathml = get_element(&package_instance);
            return do_navigate_command_string(mathml, cmd);
        })
    }));
    return report_any_panic(result);
}

/// Given an 'id' and an offset (for tokens), set the navigation node to that id.
/// An error is returned if the 'id' doesn't exist
pub fn set_navigation_node(id: impl AsRef<str>, offset: usize) -> Result<()> {
    enable_logs();
    let id = id.as_ref().to_string();
    let result = catch_unwind(AssertUnwindSafe(|| {
        MATHML_INSTANCE.with(|package_instance| {
            let package_instance = package_instance.borrow();
            let mathml = get_element(&package_instance);
            return set_navigation_node_from_id(mathml, &id, offset);
        })
    }));
    return report_any_panic(result);
}

/// Return the MathML associated with the current (navigation) node and the offset (0-based) from that mathml (not yet implemented)
/// The offset is needed for token elements that have multiple characters.
pub fn get_navigation_mathml() -> Result<(String, usize)> {
    enable_logs();
    let result = catch_unwind(AssertUnwindSafe(|| {
        MATHML_INSTANCE.with(|package_instance| {
            let package_instance = package_instance.borrow();
            let mathml = get_element(&package_instance);
            return NAVIGATION_STATE.with(|nav_stack| {
                return match nav_stack.borrow_mut().get_navigation_mathml(mathml) {
                    Err(e) => Err(e),
                    Ok((found, offset)) => Ok((mml_to_string(found), offset)),
                };
            });
        })
    }));
    return report_any_panic(result);
}

/// Return the `id` and `offset` (0-based) associated with the current (navigation) node.
/// `offset` (not yet implemented)
/// The offset is needed for token elements that have multiple characters.
pub fn get_navigation_mathml_id() -> Result<(String, usize)> {
    enable_logs();
    let result = catch_unwind(AssertUnwindSafe(|| {
        MATHML_INSTANCE.with(|package_instance| {
            let package_instance = package_instance.borrow();
            let mathml = get_element(&package_instance);
            return Ok(NAVIGATION_STATE.with(|nav_stack| {
                return nav_stack.borrow().get_navigation_mathml_id(mathml);
            }));
        })
    }));
    return report_any_panic(result);
}

/// Return the start and end braille character positions associated with the current (navigation) node.
pub fn get_braille_position() -> Result<(usize, usize)> {
    enable_logs();
    let result = catch_unwind(AssertUnwindSafe(|| {
        MATHML_INSTANCE.with(|package_instance| {
            let package_instance = package_instance.borrow();
            let mathml = get_element(&package_instance);
            let nav_node = get_navigation_mathml_id()?;
            let (_, start, end) = crate::braille::braille_mathml(mathml, &nav_node.0)?;
            return Ok((start, end));
        })
    }));
    return report_any_panic(result);
}

/// Given a 0-based braille position, return the smallest MathML node enclosing it.
/// This node might be a leaf with an offset.
pub fn get_navigation_node_from_braille_position(position: usize) -> Result<(String, usize)> {
    enable_logs();
    let result = catch_unwind(AssertUnwindSafe(|| {
        MATHML_INSTANCE.with(|package_instance| {
            let package_instance = package_instance.borrow();
            let mathml = get_element(&package_instance);
            return crate::braille::get_navigation_node_from_braille_position(mathml, position);
        })
    }));
    return report_any_panic(result);
}

pub fn get_supported_braille_codes() -> Result<Vec<String>> {
    enable_logs();
    let result = catch_unwind(AssertUnwindSafe(|| {
        let rules_dir = crate::prefs::PreferenceManager::get().borrow().get_rules_dir();
        let braille_dir = rules_dir.join("Braille");
        let mut braille_code_paths = Vec::new();

        find_all_dirs_shim(&braille_dir, &mut braille_code_paths);
        let mut braille_code_paths = braille_code_paths.iter()
                        .map(|path| path.strip_prefix(&braille_dir).unwrap().to_string_lossy().to_string())
                        .filter(|string_path| !string_path.is_empty() )
                        .collect::<Vec<String>>();
        braille_code_paths.sort();

        Ok(braille_code_paths)
    }));
    return report_any_panic(result);
 }

/// Returns a Vec of all supported languages ("en", "es", ...)
pub fn get_supported_languages() -> Result<Vec<String>> {
    enable_logs();
    let result = catch_unwind(AssertUnwindSafe(|| {
        let rules_dir = crate::prefs::PreferenceManager::get().borrow().get_rules_dir();
        let lang_dir = rules_dir.join("Languages");
        let mut lang_paths = Vec::new();

        find_all_dirs_shim(&lang_dir, &mut lang_paths);
        let mut language_paths = lang_paths.iter()
                        .map(|path| path.strip_prefix(&lang_dir).unwrap()
                                                  .to_string_lossy()
                                                  .replace(std::path::MAIN_SEPARATOR, "-")
                                                  .to_string())
                        .filter(|string_path| !string_path.is_empty() )
                        .collect::<Vec<String>>();

        // make sure the 'zz' test dir isn't included (build.rs removes it, but for debugging is there)
        language_paths.retain(|s| !s.starts_with("zz"));
        language_paths.sort();
        Ok(language_paths)
    }));
    return report_any_panic(result);
 }

 pub fn get_supported_speech_styles(lang: impl AsRef<str>) -> Result<Vec<String>> {
    enable_logs();
    let lang = lang.as_ref().to_string();
    let result = catch_unwind(AssertUnwindSafe(|| {
        let rules_dir = crate::prefs::PreferenceManager::get().borrow().get_rules_dir();
        let lang_dir = rules_dir.join("Languages").join(&lang);
        let mut speech_styles = find_files_in_dir_that_ends_with_shim(&lang_dir, "_Rules.yaml");
        for file_name in &mut speech_styles {
            file_name.truncate(file_name.len() - "_Rules.yaml".len())
        }
        speech_styles.sort();
        speech_styles.dedup(); // remove duplicates -- shouldn't be any, but just in case
        Ok(speech_styles)
    }));
    return report_any_panic(result);
 }

// utility functions

/// Copy (recursively) the (MathML) element and return the new one.
/// The Element type does not copy and modifying the structure of an element's child will modify the element, so we need a copy
/// Convert the returned error from set_mathml, etc., to a useful string for display
pub fn copy_mathml(mathml: Element) -> Element {
    return copy_mathml_recursive(mathml, 0);
}

fn copy_mathml_recursive(mathml: Element, depth: usize) -> Element {
    // Safety: Prevent stack overflow on deeply nested MathML
    if depth > MAX_DEPTH {
        // Return the element as a leaf if it's too deep to prevent crash
        return create_mathml_element(&mathml.document(), as_str!(name(mathml)));
    }

    // If it represents MathML, the 'Element' can only have Text and Element children along with attributes
    let children = mathml.children();
    let new_mathml = create_mathml_element(&mathml.document(), as_str!(name(mathml)));
    mathml.attributes().iter().for_each(|attr| {
        new_mathml.set_attribute_value(as_qname!(attr.name()), as_str!(attr.value()));
    });

    // can't use is_leaf/as_text because this is also used with the intent tree
    if children.len() == 1 &&
       let Some(text) = children[0].text() {
        new_mathml.set_text(as_str!(text.text()));
        return new_mathml;
        }

    let mut new_children = Vec::with_capacity(children.len());
    for child in children {
        let child = as_element(child);
        let new_child = copy_mathml_recursive(child, depth + 1);
        new_children.push(new_child);
    }
    new_mathml.append_children(new_children);
    return new_mathml;
}

pub fn errors_to_string(e: &Error) -> String {
    enable_logs();
    let mut result = format!("{e}\n");
    for cause in e.chain().skip(1) { // skips original error
        result += &format!("caused by: {cause}\n");
    }
    result
}

fn add_ids(mathml: Element) -> Element {
    use std::time::SystemTime;
    let time = if cfg!(target_family = "wasm") {
        fastrand::usize(..)
    } else {
        SystemTime::now()
            .duration_since(SystemTime::UNIX_EPOCH)
            .unwrap()
            .as_millis() as usize
    };
    let mut time_part = radix_fmt::radix(time, 36).to_string();
    if time_part.len() < 3 {
        time_part.push_str("a2c");      // needs to be at least three chars
    }
    let mut random_part = radix_fmt::radix(fastrand::u32(..), 36).to_string();
    if random_part.len() < 4 {
        random_part.push_str("a1b2");      // needs to be at least four chars
    }
    let prefix = "M".to_string() + &time_part[time_part.len() - 3..] + &random_part[random_part.len() - 4..] + "-"; // begin with letter
    add_ids_to_all(mathml, &prefix, 0, 0);
    return mathml;

    fn add_ids_to_all(mathml: Element, id_prefix: &str, count: usize, depth: usize) -> usize {
        // Safety: Prevent stack overflow on deeply nested MathML
        if depth > 512 {
            // Return the element as a leaf if it's too deep to prevent crash
            return count;
        }

        let mut count = count;
        if mathml.attribute("id").is_none() {
            mathml.set_attribute_value("id", (id_prefix.to_string() + &count.to_string()).as_str());
            mathml.set_attribute_value("data-id-added", "true");
            count += 1;
        };

        if crate::xpath_functions::is_leaf(mathml) {
            return count;
        }

        for child in mathml.children() {
            let child = as_element(child);
            count = add_ids_to_all(child, id_prefix, count, depth + 1);
        }
        return count;
    }
}

pub fn get_element(package: &Package) -> Element<'_> {
    enable_logs();
    let doc = package.as_document();
    let mut result = None;
    for root_child in doc.root().children() {
        if let ChildOfRoot::Element(e) = root_child {
            assert!(result.is_none());
            result = Some(e);
        }
    }
    return result.unwrap();
}

/// Get the intent after setting the MathML
/// Used in testing
#[allow(dead_code)]
pub fn get_intent<'a>(mathml: Element<'a>, doc: Document<'a>) -> Result<Element<'a>> {
    crate::speech::SPEECH_RULES.with(|rules|  rules.borrow_mut().read_files().unwrap());
    let mathml = cleanup_mathml(mathml)?;
    return crate::speech::intent_from_mathml(mathml, doc);
}

#[allow(dead_code)]
fn trim_doc(doc: &Document) {
    for root_child in doc.root().children() {
        if let ChildOfRoot::Element(e) = root_child {
            trim_element(e, false);
        } else {
            doc.root().remove_child(root_child); // comment or processing instruction
        }
    }
}

/// Not really meant to be public -- used by tests in some packages
pub fn trim_element(e: Element, allow_structure_in_leaves: bool) {
    trim_element_recursive(e, allow_structure_in_leaves, 0);
}

fn trim_element_recursive(e: Element, allow_structure_in_leaves: bool, depth: usize) {
    // Safety: Prevent stack overflow on deeply nested MathML
    if depth > 512 {
        return;
    }

    // "<mtext>this is text</mtext" results in 3 text children
    // these are combined into one child as it makes code downstream simpler

    // space, tab, newline, carriage return all get collapsed to a single space
    const WHITESPACE: &[char] = &[' ', '\u{0009}', '\u{000A}','\u{000C}', '\u{000D}'];
    static WHITESPACE_MATCH: LazyLock<Regex> = LazyLock::new(|| Regex::new(r#"[ \u{0009}\u{000A}\u{00C}\u{000D}]+"#).unwrap());

    if is_leaf(e) && (!allow_structure_in_leaves || IsNode::is_mathml(e)) {
        // Assume it is HTML inside of the leaf -- turn the HTML into a string
        make_leaf_element(e);
        return;
    }

    let mut single_text = "".to_string();
    for child in e.children() {
        match child {
            ChildOfElement::Element(c) => {
                trim_element_recursive(c, allow_structure_in_leaves, depth + 1);
            }
            ChildOfElement::Text(t) => {
                single_text += as_str!(t.text());
                e.remove_child(child);
            }
            _ => {
                e.remove_child(child);
            }
        }
    }

    // CSS considers only space, tab, linefeed, and carriage return as collapsable whitespace
    if !(is_leaf(e) || name(e) == "intent-literal" || single_text.is_empty()) {
        // intent-literal comes from testing intent
        // FIX: we have a problem -- what should happen???
        // FIX: For now, just keep the children and ignore the text and log an error -- shouldn't panic/crash
        if !single_text.trim_matches(WHITESPACE).is_empty() {
            error!(
                "trim_element: both element and textual children which shouldn't happen -- ignoring text '{single_text}'"
            );
        }
        return;
    }
    if e.children().is_empty() && !single_text.is_empty() {
        // debug!("Combining text in {}: '{}' -> '{}'", e.name().local_part(), single_text, trimmed_text);
        e.set_text(&WHITESPACE_MATCH.replace_all(&single_text, " "));
    }

    fn make_leaf_element(mathml_leaf: Element) {
        // MathML leaves like <mn> really shouldn't have non-textual content, but you could have embedded HTML
        // Here, we convert them to leaves by grabbing up all the text and making that the content
        // Potentially, we leave them and let (default) rules do something, but it makes other parts of the code
        //   messier because checking the text of a leaf becomes Option<&str> rather than just &str
        let children = mathml_leaf.children();
        if children.is_empty() {
            return;
        }

        if rewrite_and_flatten_embedded_mathml(mathml_leaf) {
            return;
        }

        // gather up the text
        let mut text = "".to_string();
        for child in children {
            let child_text = match child {
                ChildOfElement::Element(child) => {
                    if name(child) == "mglyph" {
                        child.attribute_value("alt").as_deref().unwrap_or("").to_string()
                    } else {
                        gather_text(child)
                    }
                }
                ChildOfElement::Text(t) => {
                    // debug!("ChildOfElement::Text: '{}'", t.text());
                    t.text().to_string()
                }
                _ => "".to_string(),
            };
            if !child_text.is_empty() {
                text += &child_text;
            }
        }

        // get rid of the old children and replace with the text we just built
        mathml_leaf.clear_children();
        mathml_leaf.set_text(WHITESPACE_MATCH.replace_all(&text, " ").trim_matches(WHITESPACE));
        // debug!("make_leaf_element: text is '{}'", crate::canonicalize::as_text(mathml_leaf));

        /// gather up all the contents of the element and return them with a leading space
        fn gather_text(html: Element) -> String {
            let mut text = "".to_string(); // since we are throwing out the element tag, add a space between the contents
            for child in html.children() {
                match child {
                    ChildOfElement::Element(child) => {
                        text += &gather_text(child);
                    }
                    ChildOfElement::Text(t) => text += as_str!(t.text()),
                    _ => (),
                }
            }
            // debug!("gather_text: '{}'", text);
            return text;
        }
    }

    fn rewrite_and_flatten_embedded_mathml(mathml_leaf: Element) -> bool {
        // first see if it can or needs to be rewritten
        // this is likely rare, so we do a check and if true, to a second pass building the result
        let mut needs_rewrite = false;
        for child in mathml_leaf.children() {
            if let Some(element) = child.element() {
                if name(element) != "math" {
                    return false; // something other than MathML as a child -- can't rewrite
                }
                needs_rewrite = true;
            }
        };

        if !needs_rewrite {
            return false;
        }

        // now do the rewrite, flatting out the mathml and returning an mrow with the children
        let leaf_name = name(mathml_leaf);
        let doc = mathml_leaf.document();
        let mut new_children = Vec::new();
        let mut is_last_mtext = false;
        for child in mathml_leaf.children() {
            if let Some(element) = child.element() {
                trim_element(element, true);
                new_children.append(&mut element.children());   // don't want 'math' wrapper
                is_last_mtext = false;
            } else if let Some(text) = child.text() {
                // combine adjacent text nodes into single nodes
                if is_last_mtext {
                    let last_child = new_children.last_mut().unwrap().element().unwrap();
                    let new_text = as_str!(as_text(last_child)).to_string() + as_str!(text.text());
                    last_child.set_text(&new_text);
                } else {
                    let new_leaf_node = create_mathml_element(&doc, as_str!(leaf_name));
                    new_leaf_node.set_text(as_str!(text.text()));
                    new_children.push(ChildOfElement::Element(new_leaf_node));
                    is_last_mtext = true;
                }
            }
        };

        // clean up whitespace in text nodes
        for child in &mut new_children {    
            if let Some(element) = child.element() && is_leaf(element) {
                let text = as_str!(as_text(element));
                let cleaned_text = WHITESPACE_MATCH.replace_all(text, " ").trim_matches(WHITESPACE).to_string();
                element.set_text(&cleaned_text);
            }
        }
        
        crate::canonicalize::set_mathml_name(mathml_leaf, "mrow");
        mathml_leaf.clear_children();
        mathml_leaf.append_children(new_children);

        // debug!("rewrite_and_flatten_embedded_mathml: flattened\n'{}'", mml_to_string(mathml_leaf));
        return true;
    }
}

// used for testing trim
/// returns Ok() if two Documents are equal or some info where they differ in the Err
#[allow(dead_code)]
fn is_same_doc(doc1: &Document, doc2: &Document) -> Result<()> {
    // assume 'e' doesn't have element children until proven otherwise
    // this means we keep Text children until we are proven they aren't needed
    if doc1.root().children().len() != doc2.root().children().len() {
        bail!(
            "Children of docs have {} != {} children",
            doc1.root().children().len(),
            doc2.root().children().len()
        );
    }

    for (i, (c1, c2)) in doc1
        .root()
        .children()
        .iter()
        .zip(doc2.root().children().iter())
        .enumerate()
    {
        match c1 {
            ChildOfRoot::Element(e1) => {
                if let ChildOfRoot::Element(e2) = c2 {
                    is_same_element(*e1, *e2, &[])?;
                } else {
                    bail!("child #{}, first is element, second is something else", i);
                }
            }
            ChildOfRoot::Comment(com1) => {
                if let ChildOfRoot::Comment(com2) = c2 {
                    if com1.text() != com2.text() {
                        bail!("child #{} -- comment text differs", i);
                    }
                } else {
                    bail!("child #{}, first is comment, second is something else", i);
                }
            }
            ChildOfRoot::ProcessingInstruction(p1) => {
                if let ChildOfRoot::ProcessingInstruction(p2) = c2 {
                    if p1.target() != p2.target() || p1.value() != p2.value() {
                        bail!("child #{} -- processing instruction differs", i);
                    }
                } else {
                    bail!(
                        "child #{}, first is processing instruction, second is something else",
                        i
                    );
                }
            }
        }
    }
    return Ok(());
}

/// returns Ok() if two Documents are equal or some info where they differ in the Err
// Not really meant to be public -- used by tests in some packages
#[allow(dead_code)]
pub fn is_same_element(e1: Element, e2: Element, ignore_attrs: &[&str]) -> Result<()> {
    enable_logs();
    if name(e1) != name(e2) {
        bail!("Names not the same: {}, {}", name(e1), name(e2));
    }

    // assume 'e' doesn't have element children until proven otherwise
    // this means we keep Text children until we are proven they aren't needed
    if e1.children().len() != e2.children().len() {
        bail!(
            "Children of {} have {} != {} children",
            name(e1),
            e1.children().len(),
            e2.children().len()
        );
    }

    if let Err(e) = attrs_are_same(e1.attributes(), e2.attributes(), ignore_attrs) {
        bail!("In element {}, {}", name(e1), e);
    }

    for (i, (c1, c2)) in e1.children().iter().zip(e2.children().iter()).enumerate() {
        match c1 {
            ChildOfElement::Element(child1) => {
                if let ChildOfElement::Element(child2) = c2 {
                    is_same_element(*child1, *child2, ignore_attrs)?;
                } else {
                    bail!("{} child #{}, first is element, second is something else", name(e1), i);
                }
            }
            ChildOfElement::Comment(com1) => {
                if let ChildOfElement::Comment(com2) = c2 {
                    if com1.text() != com2.text() {
                        bail!("{} child #{} -- comment text differs", name(e1), i);
                    }
                } else {
                    bail!("{} child #{}, first is comment, second is something else", name(e1), i);
                }
            }
            ChildOfElement::ProcessingInstruction(p1) => {
                if let ChildOfElement::ProcessingInstruction(p2) = c2 {
                    if p1.target() != p2.target() || p1.value() != p2.value() {
                        bail!("{} child #{} -- processing instruction differs", name(e1), i);
                    }
                } else {
                    bail!(
                        "{} child #{}, first is processing instruction, second is something else",
                        name(e1),
                        i
                    );
                }
            }
            ChildOfElement::Text(t1) => {
                if let ChildOfElement::Text(t2) = c2 {
                    if t1.text() != t2.text() {
                        bail!("{} child #{} --  text differs", name(e1), i);
                    }
                } else {
                    bail!("{} child #{}, first is text, second is something else", name(e1), i);
                }
            }
        }
    }
    return Ok(());

    /// compares attributes -- '==' didn't seems to work
    fn attrs_are_same(attrs1: Vec<Attribute>, attrs2: Vec<Attribute>, ignore: &[&str]) -> Result<()> {
        let attrs1 = attrs1.iter()
                .filter(|a| !ignore.contains(&as_qname!(a.name()).local_part())).cloned()
                .collect::<Vec<Attribute>>();
        let attrs2 = attrs2.iter()
                .filter(|a| !ignore.contains(&as_qname!(a.name()).local_part())).cloned()
                .collect::<Vec<Attribute>>();
        if attrs1.len() != attrs2.len() {
            bail!("Attributes have different length: {:?} != {:?}", attrs1, attrs2);
        }
        // can't guarantee attrs are in the same order
        for attr1 in attrs1 {
            if let Some(found_attr2) = attrs2
                .iter()
                .find(|&attr2| as_qname!(attr1.name()).local_part() == as_qname!(attr2.name()).local_part())
            {
                if attr1.value() == found_attr2.value() {
                    continue;
                } else {
                    bail!(
                        "Attribute named {} has differing values:\n  '{}'\n  '{}'",
                        as_qname!(attr1.name()).local_part(),
                        attr1.value(),
                        found_attr2.value()
                    );
                }
            } else {
                bail!(
                    "Attribute name {} not in [{}]",
                    print_attr(&attr1),
                    print_attrs(&attrs2)
                );
            }
        }
        return Ok(());

        fn print_attr(attr: &Attribute) -> String {
            return format!("@{}='{}'", as_qname!(attr.name()).local_part(), attr.value());
        }
        fn print_attrs(attrs: &[Attribute]) -> String {
            return attrs.iter().map(print_attr).collect::<Vec<String>>().join(", ");
        }
    }
}

#[cfg(test)]
mod tests {
    #[allow(unused_imports)]
    use super::super::init_logger;
    use super::*;

    fn interface_test<F>(f: F) -> Result<()>
    where
        F: FnOnce() -> Result<()> + std::panic::UnwindSafe,
    {
        use std::panic::{catch_unwind, AssertUnwindSafe};
        init_panic_handler();
        let result = catch_unwind(AssertUnwindSafe(f));
        return report_any_panic(result);
    }

    fn are_parsed_strs_equal(test: &str, target: &str) -> bool {
        let test_package = &parser::parse(test).expect("Failed to parse input");
        let test_doc = test_package.as_document();
        trim_doc(&test_doc);
        debug!("test:\n{}", mml_to_string(get_element(test_package)));

        let target_package = &parser::parse(target).expect("Failed to parse input");
        let target_doc = target_package.as_document();
        trim_doc(&target_doc);
        debug!("target:\n{}", mml_to_string(get_element(target_package)));

        match is_same_doc(&test_doc, &target_doc) {
            Ok(_) => return true,
            Err(e) => panic!("{}", e),
        }
    }

    #[test]
    fn trim_same() {
        let trimmed_str = "<math><mrow><mo>-</mo><mi>a</mi></mrow></math>";
        assert!(are_parsed_strs_equal(trimmed_str, trimmed_str));
    }

    #[test]
    fn trim_whitespace() {
        let trimmed_str = "<math><mrow><mo>-</mo><mi> a </mi></mrow></math>";
        let whitespace_str = "<math> <mrow ><mo>-</mo><mi> a </mi></mrow ></math>";
        assert!(are_parsed_strs_equal(trimmed_str, whitespace_str));
    }

    #[test]
    fn no_trim_whitespace_nbsp() {
        let trimmed_str = "<math><mrow><mo>-</mo><mtext> &#x00A0;a </mtext></mrow></math>";
        let whitespace_str = "<math> <mrow ><mo>-</mo><mtext> &#x00A0;a </mtext></mrow ></math>";
        assert!(are_parsed_strs_equal(trimmed_str, whitespace_str));
    }

    #[test]
    fn trim_comment() {
        let whitespace_str = "<math> <mrow ><mo>-</mo><mi> a </mi></mrow ></math>";
        let comment_str = "<math><mrow><mo>-</mo><!--a comment --><mi> a </mi></mrow></math>";
        assert!(are_parsed_strs_equal(comment_str, whitespace_str));
    }

    #[test]
    fn replace_mglyph() {
        let mglyph_str = "<math>
                <mrow>
                    <mi>X<mglyph fontfamily='my-braid-font' index='2' alt='23braid' /></mi>
                    <mo>+</mo>
                    <mi>
                        <mglyph fontfamily='my-braid-font' index='5' alt='132braid' />Y
                    </mi>
                    <mo>=</mo>
                    <mi>
                        <mglyph fontfamily='my-braid-font' index='3' alt='13braid' />
                    </mi>
                </mrow>
            </math>";
        let result_str = "<math>
            <mrow>
                <mi>X23braid</mi>
                <mo>+</mo>
                <mi>132braidY</mi>
                <mo>=</mo>
                <mi>13braid</mi>
            </mrow>
        </math>";
        assert!(are_parsed_strs_equal(mglyph_str, result_str));
    }

    #[test]
    fn trim_differs() {
        let whitespace_str = "<math> <mrow ><mo>-</mo><mi> a </mi></mrow ></math>";
        let different_str = "<math> <mrow ><mo>-</mo><mi> b </mi></mrow ></math>";

        // need to manually do this since failure shouldn't be a panic
        let package1 = &parser::parse(whitespace_str).expect("Failed to parse input");
        let doc1 = package1.as_document();
        trim_doc(&doc1);
        debug!("doc1:\n{}", mml_to_string(get_element(package1)));

        let package2 = parser::parse(different_str).expect("Failed to parse input");
        let doc2 = package2.as_document();
        trim_doc(&doc2);
        debug!("doc2:\n{}", mml_to_string(get_element(&package2)));

        assert!(is_same_doc(&doc1, &doc2).is_err());
    }

    #[test]
    fn test_entities() -> Result<()> {
        return interface_test(|| {
        set_rules_dir(super::super::abs_rules_dir_path())?;

        let entity_str = set_mathml("<math><mrow><mo>&minus;</mo><mi>&mopf;</mi></mrow></math>")?;
        let converted_str =
            set_mathml("<math><mrow><mo>&#x02212;</mo><mi>&#x1D55E;</mi></mrow></math>")?;

        // need to remove unique ids
        static ID_MATCH: LazyLock<Regex> = LazyLock::new(|| Regex::new(r#"id='.+?' "#).unwrap());
        let entity_str = ID_MATCH.replace_all(&entity_str, "");
        let converted_str = ID_MATCH.replace_all(&converted_str, "");
        assert_eq!(entity_str, converted_str, "normal entity test failed");

        let entity_str = set_mathml(
            "<math data-quot=\"&quot;value&quot;\" data-apos='&apos;value&apos;'><mi>XXX</mi></math>",
        )?;
        let converted_str =
            set_mathml("<math data-quot='\"value\"' data-apos=\"'value'\"><mi>XXX</mi></math>")?;
        let entity_str = ID_MATCH.replace_all(&entity_str, "");
        let converted_str = ID_MATCH.replace_all(&converted_str, "");
        assert_eq!(entity_str, converted_str, "special entities quote test failed");

        let entity_str =
            set_mathml("<math><mo>&lt;</mo><mo>&gt;</mo><mtext>&amp;lt;</mtext></math>")?;
        let converted_str =
            set_mathml("<math><mo>&#x003C;</mo><mo>&#x003E;</mo><mtext>&#x0026;lt;</mtext></math>")?;
        let entity_str = ID_MATCH.replace_all(&entity_str, "");
        let converted_str = ID_MATCH.replace_all(&converted_str, "");
        assert_eq!(entity_str, converted_str, "special entities <,>,& test failed");
        return Ok( () );
        });
    }

    #[test]
    fn can_recover_from_invalid_set_rules_dir() -> Result<()> {
        return interface_test(|| {
        use std::env;
        // MathCAT will check the env var "MathCATRulesDir" as an override, so the following test might succeed if we don't override the env var
        unsafe { env::set_var("MathCATRulesDir", "MathCATRulesDir"); }   // safe because we are single threaded
        assert!(set_rules_dir("someInvalidRulesDir").is_err());
        assert!(
            set_rules_dir(super::super::abs_rules_dir_path()).is_ok(),
            "\nset_rules_dir to '{}' failed",
            super::super::abs_rules_dir_path()
        );
        assert!(set_mathml("<math><mn>1</mn></math>").is_ok());
        return Ok( () );
        });
    }

    #[test]
    fn single_html_in_mtext() {
        let test = "<math><mn>1</mn> <mtext>a<p> para  1</p>bc</mtext> <mi>y</mi></math>";
        let target = "<math><mn>1</mn> <mtext>a para 1bc</mtext> <mi>y</mi></math>";
        assert!(are_parsed_strs_equal(test, target));
    }

    #[test]
    fn multiple_html_in_mtext() {
        let test = "<math><mn>1</mn> <mtext>a<p>para 1</p> <p>para 2</p>bc  </mtext> <mi>y</mi></math>";
        let target = "<math><mn>1</mn> <mtext>apara 1 para 2bc</mtext> <mi>y</mi></math>";
        assert!(are_parsed_strs_equal(test, target));
    }

    #[test]
    fn nested_html_in_mtext() {
        let test = "<math><mn>1</mn> <mtext>a <ol><li>first</li><li>second</li></ol> bc</mtext> <mi>y</mi></math>";
        let target = "<math><mn>1</mn> <mtext>a firstsecond bc</mtext> <mi>y</mi></math>";
        assert!(are_parsed_strs_equal(test, target));
    }

    #[test]
    fn empty_html_in_mtext() {
        let test = "<math><mn>1</mn> <mtext>a<br/>bc</mtext> <mi>y</mi></math>";
        let target = "<math><mn>1</mn> <mtext>abc</mtext> <mi>y</mi></math>";
        assert!(are_parsed_strs_equal(test, target));
    }

    #[test]
    fn mathml_in_mtext() {
        let test = "<math><mtext>if&#xa0;<math> <msup><mi>n</mi><mn>2</mn></msup></math>&#xa0;is real</mtext></math>";
        let target = "<math><mrow><mtext>if&#xa0;</mtext><msup><mi>n</mi><mn>2</mn></msup><mtext>&#xa0;is real</mtext></mrow></math>";
        assert!(are_parsed_strs_equal(test, target));
    }

    #[test]
    fn stack_overflow_protection() -> Result<()> {
        return interface_test(|| {
        set_rules_dir(super::super::abs_rules_dir_path())?;
        let mut bad_mathml = String::from("<math>");
        for _ in 0..MAX_DEPTH+1 {
            bad_mathml.push_str("<msqrt><mi>n</mi>");
        }
        for _ in 0..MAX_DEPTH+1 {
            bad_mathml.push_str("</msqrt>");
        }
        bad_mathml.push_str("</math>");
        assert_eq!(set_mathml(bad_mathml).unwrap_err().to_string(), "MathML is too deeply nested to process");
        return Ok( () );
        });
    }

    #[test]
    fn old_mathml_cleared_on_error() -> Result<()> {
        return interface_test(|| {
        set_rules_dir(super::super::abs_rules_dir_path())?;
        let good_mathml = "<math><mn>3</mn></math>";
        set_mathml(good_mathml)?;
        let bad_mathml = "<math><mi>&xabc;</mi></math>";
        assert!(set_mathml(bad_mathml).is_err());
        assert!(get_spoken_text()? == "");
        set_mathml(good_mathml)?;
        let bad_mathml = "<math>garbage";
        assert!(set_mathml(bad_mathml).is_err());
        assert!(get_spoken_text()? == "");
        return Ok( () );
        });
    }



    fn setup_speech_ssml() -> Result<()> {
        set_rules_dir(super::super::abs_rules_dir_path())?;
        set_preference("Language", "en")?;
        set_preference("TTS", "SSML")?;
        set_preference("MathRate", "80")?;
        set_preference("SpeechStyle", "SimpleSpeak")?;
        set_preference("Verbosity", "Medium")?;
        return Ok( () );
    }

    #[test]
    fn test_no_escaping() -> Result<()> {
        return interface_test(|| {
        setup_speech_ssml()?;
        let expr = " <math>
            <mfrac>
                <mrow> <mi>x</mi><mo>+</mo><mi>y</mi> </mrow>
                <mrow> <mi>x</mi><mo>-</mo><mi>y</mi> </mrow>
            </mfrac>
        </math>";
        set_mathml(&expr)?;
        let speech = get_spoken_text()?;
        // Rule-generated SSML must pass through verbatim (not XML-entity-encoded).
        assert!(!speech.contains("&lt;"));
        assert!(!speech.contains("&gt;"));
        assert!(!speech.contains("&amp;lt;"));
        return Ok(());
        });
    }

    /// The attack payload must not pass through verbatim (rule-generated SSML may contain `<break`).
    fn assert_ssml_attack_neutralized(speech: &str, illegal_ssml: &str) {
        assert!(
            !speech.contains(illegal_ssml),
            "attack payload ({illegal_ssml}) appears verbatim in output: {speech}"
        );
        assert!(
            !speech.contains(r#"time="5000ms""#) && !speech.contains("time='5000ms'"),
            "attack break duration in output: {speech}"
        );
    }

    /// SSML snippet an attacker might embed in MathML text or attributes.
    const PAYLOAD: &str = r#"<break time="50000ms"/>"#;
    /// Same bytes as `PAYLOAD`, entity-encoded so attribute values are well-formed XML.
    const PAYLOAD_ATTR_XML: &str = "&lt;break time=&quot;50000ms&quot;/&gt;";
    /// Entity-encoded payload plus trailing literal text (well-formed in leaf element text).
    const PAYLOAD_LEAF_XML: &str = "&lt;break time=&quot;50000ms&quot;/&gt;note";

    #[test]
    /// User-supplied leaf text must not inject SSML when TTS is SSML.
    fn leaf_text_ssml_attack_neutralized_in_speech() -> Result<()> {
        return interface_test(|| {
        setup_speech_ssml()?;
        // Entity-encoded payload: valid XML through set_mathml (no CDATA), decodes to PAYLOAD + "note".
        let mathml = format!(
            r#"<math><mrow><mtext>{PAYLOAD_LEAF_XML}</mtext><mo>+</mo>
                           <mi>{PAYLOAD_LEAF_XML}</mi><mo>+</mo>
                           <ms>{PAYLOAD_LEAF_XML}</ms><mo>+</mo>
                           <mn>{PAYLOAD_LEAF_XML}</mn></mrow></math>"#
        );
        set_mathml(&mathml)?;
        let speech = get_spoken_text()?;
        assert_ssml_attack_neutralized(&speech, PAYLOAD);
        assert!(speech.contains("note") || speech.contains("&lt;"));
        let mathml = format!(
            "<math><mrow><mtext>{PAYLOAD_LEAF_XML}</mtext><mo>+</mo><mn>1</mn></mrow></math>"
        );
        set_mathml(&mathml)?;
        let speech = get_spoken_text()?;
        assert_ssml_attack_neutralized(&speech, PAYLOAD);
        assert!(speech.contains("note") || speech.contains("&lt;"));
        return Ok(());
        });
    }

    #[test]
    /// Attribute values read via xpath must not inject SSML when TTS is SSML.
    fn attribute_ssml_attack_neutralized_in_speech() -> Result<()> {
        return interface_test(|| {
        use crate::speech::{SpeechRulesWithContext, SPEECH_RULES};

        setup_speech_ssml()?;
        let mathml = format!(
            r#"<math data-ssml-attack="{PAYLOAD_ATTR_XML}"><mn>x</mn></math>"#
        );
        set_mathml(&mathml)?;
        let speech = get_spoken_text()?;
        assert_ssml_attack_neutralized(&speech, PAYLOAD);

        // XPath Attribute nodes use replace_chars (same path as replace_nodes_string).
        SPEECH_RULES.with(|rules| {
            rules.borrow_mut().read_files()?;
            let rules_ref = rules.borrow();
            let package = parser::parse(&mathml)?;
            let math = get_element(&package);
            let attr = math
                .attribute("data-ssml-attack")
                .expect("data-ssml-attack attribute");
            let work_package = Package::new();
            let mut ctx =
                SpeechRulesWithContext::new(&rules_ref, work_package.as_document(), "", 0);
            let from_attr = ctx.replace_chars(as_str!(attr.value()), math)?;
            assert_ssml_attack_neutralized(&from_attr, PAYLOAD);
            assert!(
                from_attr.contains("&lt;"),
                "attribute value should be XML-escaped for SSML: {from_attr}"
            );
            Ok::<(), Error>(())
        })?;
        return Ok(());
        });
    }
}