Skip to content

fix: render math through a MathJax v2 and v4 compatible helper - #2454

Open
feanil wants to merge 3 commits into
masterfrom
feanil/mathjax-v4-compat
Open

feanil wants to merge 3 commits into
masterfrom
feanil/mathjax-v4-compat

Conversation

@feanil

@feanil feanil commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

TL;DR - ORA's two MathJax calls use the v2 MathJax.Hub API, which MathJax v4 removed. openedx/edx-platform#33555 upgrades the platform to 4.1.2, and when it lands those calls throw and math stops rendering in ORA prompts and submitted responses. This routes them through a helper that works on both v2 and v4, so it can merge now rather than being sequenced against the platform upgrade.

What changed?

  • New oa_mathjax.js exporting typesetMath(element). It prefers v4's MathJax.typesetPromise, falls back to v2's MathJax.Hub.Queue, and does nothing when the runtime provides no MathJax.
  • oa_server.js::renderLatex and lms/oa_base.js::bindLatexPreview now call it instead of MathJax.Hub.Queue directly.
  • Dropped the MathJax stub in oa_shared.js. It guarded on typeof window.MathJax === 'undefined', which is false under v4, so it never engaged where it was needed. The helper covers the no-MathJax case it existed for.
  • New spec covering all four states: v4, v2, v4-shaped-but-not-ready, and absent.
  • Rebuilt static assets, bumped to 7.1.2.

Testing Instructions

make test-js passes: 288 of 289, and the one failure is a pre-existing flake in the "unsubmitted assessments" specs that also fails on master (it moves between oa_self.js and oa_staff_area.js with Jasmine's random spec order). Note make test-js rather than npm test, since the fixtures come from the render-templates step.

The bug itself reproduces without the branch: with the global set to {}, which is what v4 presents, the old MathJax.Hub.Queue(['Typeset', MathJax.Hub, el]) raises TypeError: Cannot read properties of undefined (reading 'Queue'). The does not throw when MathJax is v4-shaped but not ready spec covers that state against the new helper.

To check it by hand, open an ORA with latex enabled and confirm math renders in the prompt, in the response preview, and in a submitted response, on a platform serving either MathJax version.

feanil and others added 3 commits September 22, 2026 11:52
openedx/openedx-platform#33555 upgrades the platform from MathJax 2.7.5 to
4.1.2. v4 removed the queue-based `MathJax.Hub` API in favour of
`MathJax.typesetPromise`, so the two `MathJax.Hub.Queue` calls in ORA
throw once that lands and math stops rendering in prompts and in
submitted responses.

The stub in oa_shared.js did not cover this. It only installed a no-op
`Hub` when `window.MathJax` was undefined, and under v4 the global is
defined, it just has no `Hub`.

Route both call sites through a `typesetMath` helper that prefers the v4
API, falls back to the v2 one, and does nothing when the runtime provides
no MathJax at all. That last case is what the stub was for, so the stub
goes away. Supporting both versions means this does not have to be
sequenced against the platform upgrade.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Regenerated with `make static` for the MathJax helper change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@codecov

codecov Bot commented Sep 22, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.46%. Comparing base (eee6b7b) to head (ce9044c).

Additional details and impacted files
@@           Coverage Diff           @@
##           master    #2454   +/-   ##
=======================================
  Coverage   95.46%   95.46%           
=======================================
  Files         198      198           
  Lines       22842    22842           
  Branches     1551     1551           
=======================================
  Hits        21807    21807           
  Misses        780      780           
  Partials      255      255           
Flag Coverage Δ
unittests 95.46% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@feanil
feanil marked this pull request as ready for review September 22, 2026 15:59
@feanil
feanil requested a review from navinkarkera September 22, 2026 15:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant