.. _v4-explorer:

=============================================
Expression Explorer Updated and On by Default
=============================================

In version 3 of MathJax, the expression explorer was not active by
default, and so those with assistive needs had to turn it on
explicitly, and it was loaded dynamically at that time.  In its place,
the :ref:`assistive-mml-component` extension was used to generate a
hidden MathML expression that could be voiced by those screen readers
that can process MathML.  This was a stop-gap measure that was both
clunky and somewhat fragile, and changes in screen readers often
rendered it ineffective (e.g., the current VoiceOver version doesn't
read the mathematics and skips it entirely, while Windows screen
readers indicate clickable math, but then fail to read it).

Because of these problems, and because the Speech Rule Engine (SRE)
that underlies MathJax's assistive support has been substantially
rewritten to improve its performance (see the
:ref:`v4-explorer-details` section below), we are now packaging the
expression explorer and SRE as part of all the combined configuration
files, while the assistive MathML extension has been removed from them
(though it can still be turned on in the :data:`Options` sub-menu of
the MathJax contextual menu).  The SRE generates speech automatically
for the expressions in your page and makes these speech strings
available to screen readers using ``aria-label`` and
``aria-braille-label`` attributes so that a screen reader can voice
the math naturally as part of the page.  Moreover, the expressions are
focusable so that they can be explored interactively. These features
are available by default in version 4, and should provide smoother
interaction with screen readers on all platforms.


.. _v4-explorer-usage:

Exploring Expressions
=====================

Using the explorer remains largely the same in v4 as it was in v3:
tabbing to an expression activates the explorer, and arrow keys move
down into an expression, up to a higher level of an expression, or
left and right among neighboring terms.  New in version 4 are the
following features:

* Clicking on an expression will enter the explorer, highlight the
  clicked term, and cause a screen reader to speak that term;
  navigation via arrow keys can continue from that point.

..

* Double-clicking on an expression enters the explorer at the top level
  of the expression (just as tabbing to it would), rather than on the
  clicked term.

..

* In previous versions, the speech and/or braille subtitles were shown
  as well, but these have been turned off by default in this release,
  as they caused confusion for users not aware of the explorer
  features.  They can be re-enabled using the MathJax contextual menu.

..

* While exploring an expression, pressing ``h`` will open a dialog box
  that describes the explorer's features.  When an expression is first
  focused, a message informing the user of this feature is announced
  after the expression is read, but that can be disabled using the
  contextual menu.

..

* In v3, if an expression was explored and tabbing is used to leave
  the explorer, then when that expression is refocused, the selection
  would remain where it was when the expression was exited.  In this
  version, tabbing to an expression always starts at the top level of
  the expression, not the last selected term.  The reason for this is
  so that if the page is read, whether as a whole or by smaller
  chunks, the expression will be read in full rather than just the
  previously selected term.  There is a contextual menu item that can
  be used to select the older behavior, however, if a user wishes to
  be able to restart the explorer where they left off.

..

* MathJax now provides optional auto-voicing of expressions together
  with step-by-step highlighting of expression while a formula is
  spoken. This feature is primarily aimed at users who do not normally
  utilize a screen reader, and in particular, as support for dyslexic
  users.  Currently, it has to be switched on explicitly, either in
  the `Speech` sub-item of the MathJax contextual menu, or using the
  :data:`voicing` option in the :data:`a11y` sub-block of the
  :data:`options` configuration block.  Speech is generated by
  providing `SSML <https://www.w3.org/TR/speech-synthesis/>`__
  annotations to the browser's `speechSynthesis API
  <https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis>`__.
  While this makes use of the full range of prosody annotations
  available in SRE's speech rules, the feature is only available in
  browsers that come with an implementation of the ``speechSynthesis``
  API and with built-in voices.

The MathJax team tests the explorer with 13 browser/os/screen-reader
combinations: Chrome, Firefox, and Safari on MacOS with VoiceOver;
Chrome, Firefox, and Edge on Windows with NVDA and JAWS; and Chrome
and Firefox on Linux (Ubuntu 24 and 22) with Orca.  The new explorer
should give a much smoother experience to screen-reader users in all
these settings.

.. _v4-explorer-improvements:

Explorer Improvements
=====================

In addition to the performance enhancements and usage changes given
above, the following are improvements found in v4:

* There is a new Korean and Afrikaans locales for speech output.

* The explorer now handles expressions with line breaks better.

* There are new text heuristics to distinguish genuine text elements
  from expressions that only use text to enforce font changes to
  ``roman`` or ``mathvariant=normal``.

* The speech output for tensor expressions has been improved.

* A new Euro Braille output format is available that uses eight-dot
  Braille to output the original LaTeX for the whole expression, and
  during expression exploration, the LaTeX used in sub-expressions
  within the expression.

* Improvements in alphabet generation and symbol translations have
  reduced the size of the locale files in the distribution.


.. _v4-explorer-details:

Technical Details
=================

The generation of speech strings is a resource-intensive process.  In
the past, that was a source of performance slowdown for pages that
contain a lot of mathematics.  Version 4 has moved the speech
generation into a web-worker, which runs in a separate thread from the
main page, so the page will remain responsive to user interaction even
while speech strings are being created.

Web-workers are only available in browsers, not in node applications,
so MathJax is set up to use the worker-threads library in node, along
with some shim code to give it a corresponding interface to the
features that MathJax uses from web-workers in the browser.  This
allows the same code to be used in both browsers and node
applications.  Currently this requires the use of the LiteDOM in node,
but we may provide support in other DOM implementations in the
future.

Because node applications that include speech generation now use
worker-threads behind the scenes, the node application won't exit
until the MathJax worker thread is shut down, so applications may need
to tell MathJax that they are finished.  This is done by calling the
new :js:meth:`MathJax.done()` method in applications that use MathJax
components, or by calling the MathDocument's :js:meth:`done()` method
for those that use direct calls to MathJax's modules.

Aside from moving the speech generation into a web-worker or node
worker-thread, the speech-generation has been improved by adding more
sophisticated semantic analysis for complex user defined structures,
including improved disambiguation of function applications, ellipses,
and unusual large operators.  Additional locales supported are
Afrikaans and Korean as well as 8-dot Euro Braille output generated
from original LaTeX input formulas.


|-----|