Self-host MathJax via @prosemark/latex vite plugin (url-import) (#150)

* Use top-level static MathJax import in LaTeX webview

Replace deferred dynamic imports with a build-time side-effect import of
mathjax/tex-svg.js (peer dependency of @prosemark/latex) so Vite fully
bundles MathJax into webview.js before the webview loads.

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Keep latex setup handler async for readability

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Disable MathJax a11y speech worker in VS Code webview

The tex-svg combined component loads sre/speech-worker.js at runtime, but
Vite only emits webview.js. Turn off speech/enrichment for editor preview.

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Copy MathJax sre assets into webview dist via Vite plugin

The tex-svg bundle loads sre/speech-worker.js at runtime as a web worker.
Vite inlines the main IIFE but cannot bundle workers loaded via importScripts,
so copy mathjax/sre/ next to webview.js after each build.

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Add @prosemark/latex vite-plugin-mathjax and self-host MathJax

Export copyMathJaxAssets from @prosemark/latex/vite-plugin-mathjax with a
configurable copy list (default tex-svg.js + sre). The LaTeX VS Code webview
loads MathJax via url-import from dist/webview/mathjax/ instead of bundling
tex-svg into webview.js (~48 KB vs ~1.8 MB).

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Keep latex setup handler async

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Fix MathJax URL resolution when multiple webview scripts load

mathJaxPackageUrlFromWebviewScript used the last script tag, which was
cspell-integration's webview.js when both companions are installed.
Add scriptSrcIncludes and use latex-integration in the LaTeX webview.

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Pass MathJax package URL from extension host via asWebviewUri

Extend SubExtensionCallback with the webview instance so sub-extensions
can resolve local resource URLs with webview.asWebviewUri instead of
reverse-engineering script tags in the webview.

The LaTeX integration now passes mathJaxPackageUrl into setup from the
extension host, removing the scriptSrcIncludes workaround.

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Remove mathJaxPackageUrlFromWebviewScript from @prosemark/latex

VS Code integrations should pass mathJaxPackageUrl from the extension
host via webview.asWebviewUri; script-tag discovery is no longer needed.

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Pass SubExtensionCallback context as a single object

Sub-extension factories now receive { document, callProcAndForget,
callProcWithReturnValue, webview } so each integration can destructure
only what it needs without breaking when new fields are added.

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Document MathJax a11y/speech worker options for static-import

Explain that tex-svg loads sre/speech-worker.js separately, and that
static-import setups must either disable a11y or copy and serve sre/.

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Fix strict lint issues in latex package and extension

Use a type guard for the webview vscode API instead of an unsafe cast,
tighten the MathJax loader test helper, and include vite.config.mts in
eslint file patterns.

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Fix MathJax 4 config: use startup.typeset instead of skipStartupTypeset

MathJax 4 removed skipStartupTypeset; use startup.typeset: false to skip
automatic page typesetting. Update @prosemark/latex preconfiguration, docs,
and tests accordingly.

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Revert vite.config.mts in latex-integration eslint files list

vite.config.mts is git-tracked source, but sibling VS Code extensions do not
list their vite configs in eslint.config.ts and lint passes without it.

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Docs: drop unsupported claim that editor preview typically skips a11y

The VS Code extension keeps speech support via url-import and copied sre/.
Frame disabling a11y as a static-import tradeoff, not a preview default.

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Changeset: use patch bumps while packages are 0.x

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Changeset: drop startup.typeset note (introduced in this PR)

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Changeset: document pre-0.0.2 VS Code math rendering regression

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Changeset: split per package and fix VS Code regression wording

Describe the 0.0.2 bug as math failing when MathJax was bundled into
the extension; drop the speech-worker cause (introduced in this PR).

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Changeset: describe VS Code math bug as blocked CDN access

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Changeset: emphasize webview in integrator callback context

Co-authored-by: J. Simon Richard <jsimonrichard@gmail.com>

* Fix LaTeX math rendering in VS Code webview

Self-host MathJax in the extension to resolve rendering issues.

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>

Author: jsimonrichard

.changeset/integrator-sub-extension-context.md

@@ -0,0 +1,5 @@
+---
+'@prosemark/vscode-extension-integrator': patch
+---
+
+Pass sub-extension callback context as a single object including `webview`, so companion extensions can resolve webview resource URLs.

.changeset/latex-vite-plugin-mathjax.md

@@ -0,0 +1,5 @@
+---
+'@prosemark/latex': patch
+---
+
+Add `@prosemark/latex/vite-plugin-mathjax` to copy configurable paths from the `mathjax` npm package into a Vite build output.

.changeset/vscode-latex-mathjax-url-import.md

@@ -0,0 +1,5 @@
+---
+vscode-prosemark-latex-integration: patch
+---
+
+Fix LaTeX math rendering issue in the VS Code extension webview by self-hosting MathJax inside the extension instead of using a CDN.

apps/docs/src/content/docs/guides/latex-math.md

@@ -76,7 +76,7 @@ If you assemble markdown extensions yourself (without `prosemarkMarkdownSyntaxEx
 
 ## How MathJax is loaded
 
-In **`url-import`** mode (the default), this package sets `window.MathJax` with `skipStartupTypeset: true` and loader paths, then dynamically imports the startup bundle. Do not set conflicting `tex` / `svg` / `chtml` options on `window.MathJax` yourself before that runs.
+In **`url-import`** mode (the default), this package sets `window.MathJax` with `startup.typeset: false` and loader paths, then dynamically imports the startup bundle. Do not set conflicting `tex` / `svg` / `chtml` options on `window.MathJax` yourself before that runs.
 
 ### Runtime URL — `mathJaxLoadMode: 'url-import'` (default)
 
@@ -113,6 +113,27 @@ import 'mathjax/tex-svg.js';
 }),
 ```
 
+**Accessibility / speech worker:** the combined startup bundle includes MathJax a11y support and loads **`sre/speech-worker.js` as a web worker** at runtime. Your bundler typically only ships the main JS file, so the worker is missing unless you also copy `sre/` and configure MathJax’s loader paths, or use **`url-import`** with a self-hosted `mathjax/` folder (see [`@prosemark/latex/vite-plugin-mathjax`](https://www.npmjs.com/package/@prosemark/latex) on npm).
+
+If you do not need speech or enrichment and want to avoid shipping the `sre/` worker, configure `window.MathJax` **before** importing MathJax:
+
+```javascript
+window.MathJax = {
+  startup: {
+    typeset: false,
+  },
+  options: {
+    enableSpeech: false,
+    enableBraille: false,
+    enableEnrichment: false,
+    menuOptions: {
+      settings: { enrich: false, speech: false, braille: false },
+    },
+  },
+};
+import 'mathjax/tex-svg.js';
+```
+
 Use one load mode per page (`url-import` or `static-import`, not both).
 
 ## Block vs inline

apps/vscode-extensions/core/src/sub-extensions/core.ts

@@ -249,7 +249,7 @@ export class Core implements SubExtension<
 export function createCore(
   extensionUri: vscode.Uri,
 ): SubExtensionCallback<typeof extId, unknown, unknown> {
-  return (document, callProcAndForget, _callProcWithReturnValue) => {
+  return ({ document, callProcAndForget }) => {
     return new Core(extensionUri, document, callProcAndForget);
   };
 }

apps/vscode-extensions/core/src/sub-extensions/word-count-status-bar-item.ts

@@ -67,7 +67,7 @@ export const createWordCountStatusBarItem: SubExtensionCallback<
   typeof extId,
   Record<string, never>,
   WordCountVSCodeProcs
-> = (document) => {
+> = ({ document }) => {
   return new WordCountStatusBarItem(document);
 };
 

apps/vscode-extensions/cspell-integration/src/sub-extension.ts

@@ -151,7 +151,7 @@ export function createCSpellIntegration(
   extensionUri: vscode.Uri,
   cSpellApi: CSpell.ExtensionApi,
 ): SubExtensionCallback<typeof extId, WebviewProcMap, VSCodeExtensionProcMap> {
-  return (document, callProcAndForget, callProcWithReturnValue) => {
+  return ({ document, callProcAndForget, callProcWithReturnValue }) => {
     return new CSpellIntegration(
       extensionUri,
       cSpellApi,

apps/vscode-extensions/latex-integration/README.md

@@ -24,4 +24,35 @@ Please report bugs on the [GitHub issues page](https://github.com/jsimonrichard/
 
 ## Developing this extension
 
-After `bun install`, run `bun run build`. **Vite** produces `dist/webview/webview.js` with MathJax SVG output inlined into that bundle (see `src/webview/main.ts`). Bump the **`mathjax`** dependency when you want a different MathJax version.
+After `bun install`, run `bun run build`. **Vite** produces `dist/webview/webview.js` and copies `tex-svg.js` plus `sre/` from the **`mathjax`** npm package into `dist/webview/mathjax/` via `@prosemark/latex/vite-plugin-mathjax`. The webview loads MathJax with `url-import` from that folder. Bump the **`mathjax`** dependency when you want a different MathJax version.
+
+### MathJax load modes
+
+This extension uses **`url-import`**: the extension host passes a webview URL for `dist/webview/mathjax/`, and the webview dynamically imports `tex-svg.js` from there. That keeps `webview.js` small and lets MathJax load `sre/speech-worker.js` as a separate file (copied by the Vite plugin).
+
+If you switch to **`static-import`** (`import 'mathjax/tex-svg.js'` bundled into `webview.js`), note that the combined `tex-svg` startup includes MathJax **a11y** support. It tries to load **`sre/speech-worker.js` as a web worker** at runtime. A bundler usually only emits your main bundle, so the worker is missing unless you handle it explicitly.
+
+Pick one approach:
+
+1. **Disable a11y** (simplest with `static-import` when you are not copying `sre/`) — set options on `window.MathJax` **before** the static import:
+
+   ```ts
+   window.MathJax = {
+     startup: {
+       typeset: false,
+     },
+     options: {
+       enableSpeech: false,
+       enableBraille: false,
+       enableEnrichment: false,
+       menuOptions: {
+         settings: { enrich: false, speech: false, braille: false },
+       },
+     },
+   };
+   import 'mathjax/tex-svg.js';
+   ```
+
+2. **Keep a11y** — copy `sre/` from the `mathjax` npm package next to where `tex-svg.js` is served, and point MathJax at that root (for example with `preconfigureMathJaxLoader` and `loader.paths.mathjax`, or `@prosemark/latex/vite-plugin-mathjax` with `url-import`). The worker cannot be inlined into an IIFE the way the main startup script can.
+
+The shipped extension uses **url-import + copied `sre/`** so math renders without bundling ~1.8 MB of MathJax into `webview.js`.

apps/vscode-extensions/latex-integration/src/common.ts

@@ -1,6 +1,10 @@
 /** VS Code extension host: no procedures exposed to the webview for LaTeX. */
 export type VSCodeExtensionProcMap = Record<string, never>;
 
+export interface LatexSetupConfig {
+  mathJaxPackageUrl: string;
+}
+
 export interface WebviewProcMap {
-  setup: () => Promise<void>;
+  setup: (config: LatexSetupConfig) => Promise<void>;
 }

apps/vscode-extensions/latex-integration/src/global.d.ts

@@ -1,3 +1 @@
 declare module '*.css';
-
-declare module 'mathjax/tex-svg.js';