@vmz/plugin-mathjax 0.0.0 → 0.0.3

package/README.md

@@ -1,3 +1,32 @@
 # @vmz/plugin-mathjax
 
-Placeholder package (0.0.0). Reserved for the VMZ project.
+## Broad TeX support when mathematics is the product
+
+`@vmz/plugin-mathjax` connects MathJax to VMZ for applications whose mathematical content needs deeper TeX coverage,
+richer notation, or compatibility with existing scholarly material.
+
+## The tradeoff
+
+MathJax is the capability-first choice. It can handle cases that a lightweight typesetter may not, but it carries a
+higher cost than KaTeX. For a documentation-heavy or formula-intensive product, that trade can be exactly right. For
+common formulas on performance-sensitive pages, `@vmz/plugin-katex` is usually the better default.
+
+VMZ keeps that choice explicit. The formula engine changes the presentation capability, not the application's state,
+server, route, or deployment semantics. SSR and progressive interaction remain part of the VMZ application plan.
+
+Think of MathJax as the right specialist tool when formula fidelity is worth a heavier delivery budget. 📐
+
+## Where it earns its weight
+
+- Scholarly material imported from established TeX sources.
+- Products where advanced notation is central to the experience.
+- Documentation that cannot accept a smaller supported syntax surface.
+- Mathematical publishing that depends on the broader MathJax ecosystem.
+
+| Product priority                               | Better starting point |
+|------------------------------------------------|-----------------------|
+| Fast common formulas and compact delivery      | KaTeX                 |
+| Broad TeX compatibility and specialist content | MathJax               |
+
+The choice remains local to mathematical presentation. It does not force a different VMZ routing, state, testing, or
+deployment model.

package/components/Mathjax.vmz

@@ -0,0 +1,25 @@
+<template>
+  <div class="mathjax-host" html={html != null ? html : fallback(tex)}></div>
+</template>
+
+<script client>
+import { renderMathjax, renderMathjaxFallback } from '@vmz/plugin-mathjax/runtime';
+
+function fallback(tex) {
+  return renderMathjaxFallback(tex);
+}
+
+export default class Mathjax {
+  public tex: string = '';
+  public display: boolean = false;
+  html: string | null = null;
+
+  async onMount() {
+    try {
+      this.html = await renderMathjax(this.tex, this.display);
+    } catch {
+      this.html = renderMathjaxFallback(this.tex);
+    }
+  }
+}
+</script>

package/package.json

@@ -1,10 +1,38 @@
 {
   "name": "@vmz/plugin-mathjax",
-  "version": "0.0.0",
-  "description": "VMZ placeholder — not for production use.",
+  "version": "0.0.3",
+  "type": "module",
+  "description": "VMZ MathJax adapter - <Mathjax> + math engine",
   "license": "MIT",
-  "private": false,
-  "files": [
-    "README.md"
-  ]
+  "main": "./vmz.plugin.ts",
+  "types": "./vmz.plugin.ts",
+  "exports": {
+    ".": {
+      "types": "./vmz.plugin.ts",
+      "default": "./vmz.plugin.ts"
+    },
+    "./runtime": {
+      "types": "./runtime.ts",
+      "default": "./runtime.ts"
+    }
+  },
+  "dependencies": {
+    "@vmz/plugin": "0.0.3"
+  },
+  "peerDependencies": {
+    "mathjax-full": ">=3"
+  },
+  "keywords": [
+    "vmz",
+    "plugin",
+    "mathjax",
+    "math"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doki-land/vmz-framework.git"
+  }
 }

package/runtime.ts

@@ -0,0 +1,41 @@
+/**
+ * MathJax TeX → HTML/SVG helper.
+ * Prefer KaTeX for common docs; MathJax for heavier TeX coverage.
+ */
+
+type TexConvert = (tex: string, display: boolean) => string;
+
+let tex2svg: TexConvert | null = null;
+
+async function getConvert(): Promise<TexConvert> {
+    if (tex2svg) return tex2svg;
+    const { mathjax } = await import('mathjax-full/js/mathjax.js');
+    const { TeX } = await import('mathjax-full/js/input/tex.js');
+    const { SVG } = await import('mathjax-full/js/output/svg.js');
+    const { liteAdaptor } = await import('mathjax-full/js/adaptors/liteAdaptor.js');
+    const { RegisterHTMLHandler } = await import('mathjax-full/js/handlers/html.js');
+    const adaptor = liteAdaptor();
+    RegisterHTMLHandler(adaptor);
+    const html = mathjax.document('', {
+        InputJax: new TeX({ packages: ['base', 'ams'] }),
+        OutputJax: new SVG({ fontCache: 'none' }),
+    });
+    tex2svg = (tex, display) => {
+        const node = html.convert(tex ?? '', { display: !!display });
+        return adaptor.outerHTML(node);
+    };
+    return tex2svg;
+}
+
+export async function renderMathjax(tex: string, display = false): Promise<string> {
+    const convert = await getConvert();
+    return convert(tex, display);
+}
+
+export function renderMathjaxFallback(tex: string): string {
+    const escaped = String(tex ?? '')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+    return `<span class="mathjax-fallback">${escaped}</span>`;
+}

package/vmz.plugin.ts

@@ -0,0 +1,50 @@
+import { definePlugin, loadPluginSource } from '@vmz/plugin';
+
+const source = loadPluginSource(import.meta.url, 'components/Mathjax.vmz');
+
+export default definePlugin({
+    name: '@vmz/plugin-mathjax',
+    version: '0.1.0',
+    protocol: '0.1.0',
+    stages: ['workspace_resolve', 'analyzer'],
+    deterministic: true,
+    async contribute(ctx) {
+        if (ctx.stage === 'workspace_resolve') {
+            return {
+                stage: 'workspace_resolve',
+                cacheKey: `@vmz/plugin-mathjax:Mathjax.vmz:${source.contentHash.slice(0, 12)}`,
+                items: [
+                    {
+                        id: 'component-mathjax',
+                        kind: 'source',
+                        path: 'src/components/Mathjax.vmz',
+                        content: source.content,
+                        contentHash: source.contentHash,
+                        materialize: true,
+                        engine: 'mathjax',
+                        engineKind: 'math',
+                    },
+                ],
+            };
+        }
+        if (ctx.stage === 'analyzer') {
+            return {
+                stage: 'analyzer',
+                cacheKey: '@vmz/plugin-mathjax:analyzer',
+                items: [
+                    {
+                        id: 'engine-mathjax',
+                        kind: 'analyzer',
+                        path: 'src/components/Mathjax.vmz',
+                        severity: 'advice',
+                        message: 'math engine mathjax online',
+                        code: 'vmz.engine.mathjax',
+                        engine: 'mathjax',
+                        engineKind: 'math',
+                    },
+                ],
+            };
+        }
+        return { stage: ctx.stage, items: [] };
+    },
+});