math-core 0.5.4 → 0.6.0

package/README.md

@@ -0,0 +1,212 @@
+# math-core
+
+A Node.js library for converting LaTeX math expressions to MathML Core.
+
+## Overview
+
+`math-core` converts LaTeX mathematical expressions into MathML Core, a streamlined subset of MathML that is supported by all major web browsers. It lets you render mathematical content on the web without requiring JavaScript libraries or polyfills.
+
+## Features
+
+- Convert LaTeX math expressions to MathML Core
+- Support for both inline and display (block) math
+- Define custom LaTeX macros for extended functionality
+- Global and local counter for numbered equations
+- Pretty-printing option for readable MathML output
+- Comprehensive error handling with descriptive error messages
+
+## Installation
+
+```bash
+npm i math-core
+```
+
+> **Note:** This package is for Node.js (and compatible runtimes like Bun) only. It cannot be used in the browser, because it uses `readFileSync` from `node:fs` to load the underlying WASM module.
+
+## Quick Start
+
+```javascript
+import { LatexToMathML } from "math-core";
+
+const converter = new LatexToMathML({});
+
+// Convert inline math
+const inline = converter.convert_with_local_counter("x^2 + y^2 = z^2", false);
+console.log(inline);
+// Output: <math><msup><mi>x</mi><mn>2</mn></msup><mo>+</mo><msup><mi>y</mi><mn>2</mn></msup><mo>=</mo><msup><mi>z</mi><mn>2</mn></msup></math>
+
+// Convert display math
+const display = converter.convert_with_local_counter("\\frac{1}{2}", true);
+console.log(display);
+// Output: <math display="block"><mfrac><mn>1</mn><mn>2</mn></mfrac></math>
+```
+
+## Usage
+
+### Basic Usage
+
+```javascript
+import { LatexToMathML } from "math-core";
+
+const converter = new LatexToMathML({ prettyPrint: "always" });
+
+try {
+  const mathml = converter.convert_with_local_counter("\\sqrt{x^2 + 1}", false);
+  console.log(mathml);
+} catch (e) {
+  console.error(`Conversion error: ${e.message}`);
+}
+```
+
+### Custom LaTeX Macros
+
+Define custom macros to extend or modify LaTeX command behavior:
+
+```javascript
+const macros = new Map();
+macros.set("d", "\\mathrm{d}");    // Differential d
+macros.set("R", "\\mathbb{R}");    // Real numbers
+macros.set("vec", "\\mathbf{#1}"); // Vector notation
+
+const converter = new LatexToMathML({ macros });
+const mathml = converter.convert_with_local_counter("\\d x", false);
+```
+
+### Numbered Equations with Global Counter
+
+For documents with multiple numbered equations:
+
+```javascript
+const converter = new LatexToMathML({});
+
+// First equation gets (1)
+const eq1 = converter.convert_with_global_counter(
+  "\\begin{align}E = mc^2\\end{align}",
+  true,
+);
+
+// Second equation gets (2)
+const eq2 = converter.convert_with_global_counter(
+  "\\begin{align}F = ma\\end{align}",
+  true,
+);
+
+// Reset counter when starting a new chapter/section
+converter.reset_global_counter();
+
+// This equation gets (1) again
+const eq3 = converter.convert_with_global_counter(
+  "\\begin{align}p = mv\\end{align}",
+  true,
+);
+```
+
+### Local Counter for Independent Numbering
+
+Use local counters when equation numbers should restart within each conversion:
+
+```javascript
+const converter = new LatexToMathML({});
+
+// Each conversion has independent numbering
+const doc1 = converter.convert_with_local_counter(
+  "\\begin{align}a &= b\\\\c &= d\\end{align}",
+  true,
+); // Contains (1) and (2)
+
+const doc2 = converter.convert_with_local_counter(
+  "\\begin{align}x &= y\\\\z &= w\\end{align}",
+  true,
+); // Also contains (1) and (2)
+```
+
+### Error Handling
+
+By default, conversion errors throw a `LatexError` with detailed diagnostics:
+
+```javascript
+const converter = new LatexToMathML({});
+
+try {
+  converter.convert_with_local_counter("\\begin{foobar}", false);
+} catch (e) {
+  console.log(e.message); // 'Unknown environment "foobar".'
+  console.log(e.report);  // Formatted diagnostic with source spans
+  console.log(e.context); // The relevant LaTeX source
+  console.log(e.start);   // Start offset of the error
+  console.log(e.end);     // End offset of the error
+}
+```
+
+Set `throwOnError: false` to return an HTML error snippet instead of throwing:
+
+```javascript
+const converter = new LatexToMathML({ throwOnError: false });
+const result = converter.convert_with_local_counter("\\invalid", false);
+// Returns: <span class="math-core-error" title="..."><code>\invalid</code></span>
+```
+
+## API Reference
+
+### `LatexToMathML`
+
+The main converter class.
+
+**Constructor:**
+
+```typescript
+new LatexToMathML(options: MathCoreOptions)
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `prettyPrint` | `"never" \| "always" \| "auto"` | `"never"` | Whether to pretty-print the MathML output. `"auto"` pretty-prints block equations only. |
+| `macros` | `Map<string, string>` | — | Custom LaTeX macros. |
+| `xmlNamespace` | `boolean` | `false` | Include `xmlns="http://www.w3.org/1998/Math/MathML"` in the `<math>` tag. |
+| `throwOnError` | `boolean` | `true` | Throw `LatexError` on conversion errors. If `false`, returns an HTML error snippet instead. |
+| `ignoreUnknownCommands` | `boolean` | `false` | Render unknown commands as red text instead of erroring. |
+| `annotation` | `boolean` | `false` | Include the original LaTeX as an annotation in the MathML output. |
+
+**Methods:**
+
+- `convert_with_global_counter(latex: string, displaystyle: boolean): string` — Convert LaTeX to MathML using a global equation counter.
+- `convert_with_local_counter(latex: string, displaystyle: boolean): string` — Convert LaTeX to MathML using a local equation counter.
+- `reset_global_counter(): void` — Reset the global equation counter to zero.
+
+### `LatexError`
+
+Error thrown when LaTeX parsing or conversion fails.
+
+**Properties:**
+
+| Property | Type | Description |
+|---|---|---|
+| `message` | `string` | Description of the error. |
+| `report` | `string \| undefined` | Formatted diagnostic report with source spans. |
+| `context` | `string \| undefined` | The relevant LaTeX source. |
+| `start` | `number` | Start offset of the error in the source. |
+| `end` | `number` | End offset of the error in the source. |
+
+## Why MathML Core?
+
+MathML Core is a carefully selected subset of MathML 4 that focuses on essential mathematical notation while ensuring consistent rendering across browsers. Unlike full MathML or JavaScript-based solutions:
+
+- **Native browser support**: No JavaScript required
+- **Accessibility**: Better screen reader support
+- **Performance**: Faster rendering than JS solutions
+- **SEO-friendly**: Search engines can index mathematical content
+- **Future-proof**: Part of web standards with ongoing browser support
+
+## Browser Support
+
+Firefox currently has the most complete support for MathML Core, with Chrome close behind. Safari has the least support and some rendering issues exist when using MathML Core, but it is improving with each release.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

package/dist/math_core.d.ts

@@ -8,6 +8,7 @@ interface MathCoreOptions {
     throwOnError?: boolean;
     ignoreUnknownCommands?: boolean;
     annotation?: boolean;
+    allowUnreliableRendering?: boolean;
 }
 
 

package/dist/math_core.js

@@ -167,7 +167,11 @@ function __wbg_get_imports() {
         __wbg___wbindgen_throw_be289d5034ed271b: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
-        __wbg_annotation_0f240a9bc62ef511: function(arg0) {
+        __wbg_allowUnreliableRendering_b5f73be018b1a1f7: function(arg0) {
+            const ret = arg0.allowUnreliableRendering;
+            return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
+        },
+        __wbg_annotation_13d93d90da1897e4: function(arg0) {
             const ret = arg0.annotation;
             return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
         },
@@ -187,7 +191,7 @@ function __wbg_get_imports() {
             const ret = arg0[arg1 >>> 0];
             return ret;
         },
-        __wbg_ignoreUnknownCommands_e2f38f95235accd2: function(arg0) {
+        __wbg_ignoreUnknownCommands_243d0f7135c2947f: function(arg0) {
             const ret = arg0.ignoreUnknownCommands;
             return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
         },
@@ -199,7 +203,7 @@ function __wbg_get_imports() {
             const ret = LatexError.__wrap(arg0);
             return ret;
         },
-        __wbg_macros_4d915c0571da66e0: function(arg0) {
+        __wbg_macros_10ee7add3368cc46: function(arg0) {
             const ret = arg0.macros;
             return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
         },
@@ -207,7 +211,7 @@ function __wbg_get_imports() {
             const ret = arg0.next();
             return ret;
         }, arguments); },
-        __wbg_prettyPrint_50b3da85527dbcc4: function(arg0, arg1) {
+        __wbg_prettyPrint_4613329951709336: function(arg0, arg1) {
             const ret = arg1.prettyPrint;
             var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
             var len1 = WASM_VECTOR_LEN;
@@ -218,7 +222,7 @@ function __wbg_get_imports() {
             const ret = arg0.size;
             return ret;
         },
-        __wbg_throwOnError_48cbacea44678108: function(arg0) {
+        __wbg_throwOnError_3140ddd7aadfd89a: function(arg0) {
             const ret = arg0.throwOnError;
             return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
         },
@@ -226,7 +230,7 @@ function __wbg_get_imports() {
             const ret = arg0.value;
             return ret;
         },
-        __wbg_xmlNamespace_87aeb5924c1bbfbe: function(arg0) {
+        __wbg_xmlNamespace_d5ce6698d3af3315: function(arg0) {
             const ret = arg0.xmlNamespace;
             return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "math-core",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Convert LaTeX to MathML Core",
   "homepage": "https://github.com/tmke8/math-core#readme",
   "bugs": {