pi-better-math

---

Pi's built-in renderer flattens LaTeX to a single line. pi-better-math intercepts Markdown and typesets display math as real 2D Unicode art — stacked fractions, extended brackets, centered sum/integral limits, matrices — using libtexprintf (utftex, WASM).

Rendering is display-only. Session and model context stay unchanged. Any failure falls back to Pi's built-in LaTeX handling.

        ⎡             |xᵢ|² - 2ρ Re(xᵢ x̅ⱼ) ⎤
ℒ =  ∑  ⎢ log(1-ρ²) + ──────────────────── ⎥
    i<j ⎣                     1-ρ²         ⎦

Installation

Requires Pi 0.84.0 or newer (pi.registerMarkdownTransformer).

npm

pi install npm:pi-better-math

GitHub

pi install git:github.com/ZhenHuangLab/pi-better-math

Local checkout

git clone https://github.com/ZhenHuangLab/pi-better-math.git
pi install /absolute/path/to/pi-better-math

Restart Pi or run /reload after installing.

Usage

The extension is on by default once the render worker is ready.

Command	Effect
/better-math	Show status
/better-math on	Enable typesetting
/better-math off	Disable typesetting
/better-math toggle	Flip the current state

Status looks like better-math ON calls=12 hits=4. calls is how many Markdown transforms ran; hits is how many actually changed. stalls=N appears if a render blew the 250ms deadline and the worker was replaced.

What gets typeset

• Display math: $$...$$ and math-looking \[...\] become a fenced code block of multi-line Unicode art.
• Inline math: $...$ that Pi cannot handle well (\frac, \sin, \left/\right, \rm, \!, …) is replaced with a single-line Unicode substitution so table cells stay intact.
• Left alone: fenced code blocks, inline code, escaped prose \[optional\], and anything that fails to render.

How it works

1. A Markdown transformer walks non-code segments and hands TeX to libtexprintf.
2. Rendering happens on a worker thread, on a fresh WebAssembly instance every call. libtexprintf keeps global state in WASM memory; reusing an instance eventually returns garbage, and some inputs never terminate.
3. The TUI thread drives the worker through SharedArrayBuffer + Atomics.wait with a 250ms deadline. A missed deadline kills and respawns the worker, then falls back to Pi's built-in LaTeX — so a bad formula cannot freeze the session.
4. Output wider than the terminal, unknown TeX, or a worker error also falls back.

License

GPL-3.0-or-later. The runtime renderer is libtexprintf, which is GPL-3.0-or-later.