__FAVICON__ __FONTS__
__SITEBAR:guide__MetaPost and TikZ in the browser, with real LaTeX. John Hobby's MetaPost, pdfTeX, LuaTeX and dvisvgm are compiled to WebAssembly and wrapped in one TypeScript library: MetaPost source becomes SVG with real glyph outlines, EPS and structured JSON, and whole LaTeX/TikZ documents become one SVG per page — shadings, patterns, opacity, pgfplots and all. No server, no web fonts, and output that is byte-identical to TeX Live's own mpost and latex + dvisvgm.
Two ways. The prebuilt archive is what most people want: it contains the compiled engines, the JavaScript and the font, format and package bundles, and needs neither TeX Live nor Emscripten.
mp-tikz-wasm-__VERSION__.tar.gz (or .zip) from the releases page and unpack it.dist/ folder on any static web server (the files are plain; nothing needs special headers). To try it locally: node serve.mjs 8080 inside the unpacked folder, then open http://localhost:8080/site/.import { MetaPost } from '/path/to/dist/index.js'.git clone __REPO_URL__.git
cd mp-tikz-wasm
./scripts/extract-vendor.sh # fetch and verify the pinned TeX Live 2025 source (111 MB)
./scripts/verify-pin.sh # assert the mplib API the design relies on
npm install
make contract # native build + the L0 contract harness (46 checks)
./scripts/native-texlive.sh # native web2c pass: generates pdfTeX's C (once, ~5 min)
./scripts/native-dvisvgm.sh # native configure of dvisvgm: config.h (once)
npm run build # mplib.wasm, tex.wasm, dvisvgm.wasm, texmf tree, formats, bundles, TypeScript
npm test # unit + end-to-end tests
npm run demo # http://localhost:8080/site/
Prerequisites: a C compiler, Node ≥ 20, the Emscripten SDK (.emsdk-version pins 6.0.9) and a TeX Live 2025 installation, which is both the source of the bundled texmf files and the oracle the tests compare against. See Building for what each step produces.
This is the tikzjax-style integration: one script, and every diagram tag on the page is replaced by its SVG.
<script type="module" src="/path/to/dist/auto.js"></script>
<script type="text/tikz" data-libraries="arrows.meta,calc">
\begin{tikzpicture}
\draw[->,thick] (0,0) -- (2,1) node[right] {$x^2$};
\end{tikzpicture}
</script>
<script type="text/metapost">
draw fullcircle scaled 50 withpen pencircle scaled 1.2;
label.top(btex $\int_0^1 x\,dx$ etex, (0,25));
</script>
<tikz-diagram data-libraries="shadings">\shade[ball color=red] (0,0) circle (1);</tikz-diagram>
<metapost-diagram>input boxes; boxit.a("hello"); drawboxed(a);</metapost-diagram>
\documentclass is wrapped in a standalone document; a complete document is compiled as is. Path commands are put inside a tikzpicture; a body that is already one (tikzpicture, \tikz, axis) is not. A body that starts with a package's own picture — \begin{tikzcd}, \begin{circuitikz}, \chemfig, \schemestart — is not nested either, and gets \documentclass[border=…]{standalone} with TikZ loaded by hand, which crops whatever the body is (name the package in packages). A MetaPost body without beginfig becomes one figure; input lines are hoisted above it.data-* on script tags, plain on custom elements): libraries, packages, preamble, border, gdlibraries (graph drawing, implies LuaTeX) and engine (auto | latex | lualatex | plain) for TikZ; tex (auto | plain | latex | none) and prologues for MetaPost; fonts="woff2" for embedded fonts instead of outlines; cache="off"; show-console; alt.data-base (where bundles/ and the wasm files live, default next to the script), data-bundles="+opentype" (add the opt-in OpenType bundle to the defaults; a list without + replaces them), data-worker="off" (run the engines on the page's own thread instead of a Web Worker), data-observe="off", data-snapshot="on", data-prefetch="off" (by default the loader fetches, in parallel, the files the page's diagrams will need before the first render, so a slow host does not pay one round trip per file), data-figures="figures/" (where saved figures live; next bullet but one), data-log="debug" (what reaches the browser console: silent, error, warn (default), info, debug — the engines' output as it runs — or trace; mpTikzWasm.setLogLevel() changes it later).<tikz-diagram> and <metapost-diagram> are registered custom elements (web components): they render when they are connected to the document, so elements created later by a framework or by script work too. They are also live: set el.source (or el.textContent), or change an attribute that affects the output, and the diagram is typeset again. Edits are debounced (data-debounce, in ms, default 200), the old figure stays up dimmed until the new one is ready, and a result overtaken by a later edit is dropped, so an editor can set source on every keystroke. The two <script> forms are picked up by a MutationObserver instead, because script elements cannot be custom elements, and render once.data-replace on a custom element replaces it, once rendered, by the <svg> itself; see Ids, classes and slides below.mp-tikz-wasm:rendered event; window.mpTikzWasm.render() renders programmatically.npx mpost-wasm --prerender page.html typesets every diagram element in Node and writes figures/figure-HASH.svg next to the page (HASH is six characters of the hash of the element's source and attributes); or open the page and call mpTikzWasm.saveFigures() in the console, which writes the same files into a folder you pick (Chrome, Edge) or downloads them as a zip. With data-figures="figures/" on the loader, each element loads its file if it exists and the engines start only for the figures that are missing — a page whose figures are all saved loads no engine at all. The name is the content: a changed diagram gets a new file, so --prerender keeps the files that exist (--force re-renders). mpTikzWasm.figures() lists them. The tags page is served this way.< for <; script tags are raw.The bundled TikZ library svg.attributes puts attributes on the SVG a scope, path or node produces. Load it with \usetikzlibrary{svg.attributes}, or data-libraries="svg.attributes" on a tag; it is in the default bundles.
svg class=<classes> — added to the class list; repeatable.svg id=<id> — the element's id (the last one wins).svg attributes={name="value", …} — any other attributes, separated by commas or spaces; a comma inside a quoted value stays, and unbalanced quotes are a TeX error.The attributes land on the <g> PGF itself opens for that scope, path or node, so nothing has to be balanced by hand, and a nested scope does not inherit them. Under a driver that is not SVG (pdfTeX, dvips) the keys do nothing, so the same source still builds with pdflatex. A clip path gets no group of its own, so its attributes are dropped. Classes arrive as written; ids are prefixed per figure by the tags (id="box" becomes mpwHASH-box, so two figures cannot collide), so select by class, or by [id$="-box"].
data-replace on a <tikz-diagram> or <metapost-diagram> replaces the element, once it has rendered, by the <svg> itself; the element's id, class and style move to the SVG root. The figure is then ordinary SVG in the page, and static: it no longer re-typesets. A failed render keeps the element and its diagnostics. The mp-tikz-wasm:rendered event is dispatched from the SVG after the swap, with replaced: true.
Together they give reveal.js fragments inside a diagram:
<section>
<tikz-diagram data-replace data-libraries="svg.attributes" class="r-stretch">
\draw[thick] (0,0) rectangle (4,3);
\begin{scope}[svg class=fragment]\fill[red!60] (1,1) circle (0.5);\end{scope}
\begin{scope}[svg class={fragment fade-up}]\fill[blue!60] (3,1) circle (0.5);\end{scope}
\node[svg class=fragment, svg attributes={data-fragment-index="0"}] at (2,2.5) {first};
</tikz-diagram>
</section>
Checked with reveal.js 5: the three parts step in order, data-fragment-index honoured, with no Reveal.sync() — reveal looks fragments up as it navigates, and its stylesheet hides a .fragment as soon as the SVG arrives.
The engines run in a Web Worker, so the page never blocks; there is a 20 s watchdog per run.
import { MetaPost } from './dist/index.js'; // browser (a Worker) or Node (in-process)
const mp = await MetaPost.create(); // loads the engines and the bundle manifests
// MetaPost -> SVG / EPS / JSON
const r = await mp.run(`
beginfig(1);
draw fullcircle scaled 100;
label.top(btex $\\int_0^\\infty e^{-x^2}dx$ etex, (0,50));
endfig; end.`, { format: ['svg', 'eps', 'json'] });
r.status // 'ok' | 'warning' | 'error' | 'fatal' (MetaPost's own history)
r.figures[0].svg // glyph outlines, self-contained
r.figures[0].eps // what mpost writes, byte for byte
r.figures[0].json // typed knots, pens, colours, dashes, text runs, clips
r.diagnostics // [{ severity, source, message, help[], file, line }]
r.stats // metapostMs, texMs, texRuns, snippetCacheHits ...
// LaTeX / TikZ -> one SVG per page
const t = await mp.latex(String.raw`
\documentclass[tikz,border=2pt]{standalone}
\begin{document}\begin{tikzpicture}
\shade[ball color=blue!60] (0,0) circle (1);
\end{tikzpicture}\end{document}`);
t.pages[0] // SVG
t.diagnostics // TeX errors with document line numbers, package warnings
(await mp.latex(doc, { output: 'pdf' })).pdf // or a PDF (Uint8Array), from the engine's own PDF back end
t.stats // texMs, dvisvgmMs, format ('latex', 'tikz', 'dvilualatex' …)
// TikZ graph drawing needs LuaTeX: engine 'auto' switches to luatex.wasm by itself
const g = await mp.latex(String.raw`
\documentclass[tikz]{standalone}
\usetikzlibrary{graphs,graphdrawing} \usegdlibrary{layered}
\begin{document}\tikz\graph[layered layout]{a -> {b, c} -> d};\end{document}`, { engine: 'auto' });
| Option | Where | Meaning |
|---|---|---|
| bundles, bundleBaseUrl | create | which texmf bundles to load and from where (default: DEFAULT_BUNDLES, next to the script; add 'opentype' and 'otf-fonts' for fontspec and unicode-math, 'ghostscript' for PostScript: PSTricks, EPS, graphicx's rotation and scaling) |
| numberSystem | create | scaled (mpost's default), double, decimal |
| tex | create / run | label engine for btex: auto (LaTeX when the preamble says so), plain, etex, latex, none |
| deterministic | create | fixed random seed and frozen date, so two runs are byte-identical (default on) |
| runScript, makeText, onFindFile | create | JavaScript hooks for runscript, for overriding label typesetting, and for last-chance file lookup (in-process mode) |
| worker, timeoutMs, snapshot, prefetch | create | Worker vs in-process; stall watchdog (a run is killed only when nothing happens for timeoutMs, so a slow first load is not cut short); prefetch: ['latex'] fetches a first run's files in parallel; default snapshot policy |
| logLevel, logger | create | what each run writes to the console: silent, error, warn (default: errors and warnings, a MetaPost error with its help text), info (one line per run and per engine pass, with timings), debug (the engines' own terminal output, live) or trace (every file looked up or fetched); mp.logLevel changes it at any time; logger receives the records instead of the console, mp.on('record') as well |
| format, prologues, internals, files, jobName | run | outputs; prologues (3 for SVG outlines); -s name=value internals; extra files placed next to the job |
| engine, fonts, pages, bbox, dvisvgmArgs, snapshot, files | latex | latex | lualatex | luatex | plain | tex | auto; outlines or woff2; page selection; dvisvgm's bbox; extra arguments; the pre-warmed format |
| output | latex | svg (default) or pdf: pdfTeX's or LuaTeX's own PDF back end, returned as result.pdf (a Uint8Array); fonts embedded, PNG and JPEG images included; byte-identical to TeX Live's latex -output-format=pdf apart from the version string. One pass per call: hand artifacts back as files for cross-references |
Also exported: MetaPostPool for batch work across several workers, postProcessSvg (numeric compaction, id namespacing), scanTexBlocks, splitMpx, parseMetaPostLog.
Untrusted sources. MetaPost's special and dvisvgm's raw specials put arbitrary markup into the SVG, so a diagram written by someone else can carry <script> or event handlers. The tags insert SVG as is, which is right for a page's own diagrams. For anyone else's, sanitise with DOMPurify (USE_PROFILES: { svg: true, svgFilters: true }, ADD_TAGS: ['use'], then drop any <use> whose href is not #…); the README has the function. The old sanitizeSvg export is deprecated: it strips shadings, patterns and web fonts.
The same API runs in-process in Node with the bundles read from disk; nothing is fetched. MetaPost.create({ texmfDir }) can point at a texmf tree in the flattened layout instead of bundles.
npx mpost-wasm figure.mp # figure.1, figure.2 … like mpost
npx mpost-wasm -s 'outputformat="svg"' -s prologues=3 figure.mp
npx mpost-wasm -tex=latex -numbersystem=double -jobname=out figure.mp
npx mpost-wasm --latex figure.tex # figure-1.svg, figure-2.svg …
npx mpost-wasm --latex --plain --fonts=woff2 figure.tex
npx mpost-wasm --latex --engine=lualatex graph.tex # or --engine=auto (the default)
npx mpost-wasm -vv figure.mp # the engines' output on stderr as it runs (-v timings, -vvv every file, -q silence)
npx mpost-wasm --prerender page.html # figures/figure-HASH.svg for every diagram tag on the page
mpost-wasm accepts the usual mpost flags (-interaction, -jobname, -tex, -s, -halt-on-error, -recorder; -troff with a warning), writes output files with mpost's outputtemplate naming, prints the transcript, and exits 1 on error. -v, -vv, -vvv and -q (or --log-level=) set how much goes to stderr.
Everything below was rendered by the wasm engines when this page was built; open “source” under any figure for the exact input. The output of the MetaPost side is byte-identical to native mpost on the golden corpus, because it is MetaPost: the C output is left untouched.
Also supported: all number systems mplib builds without GMP (scaled, double, decimal); withprescript/withpostscript and special; TFM output; write … to files (returned as artifacts); runscript bridged to a JavaScript function when you opt in; the structured JSON figure model for canvas rendering, hit testing or export; and the classic .mpx route (extensions: false) for byte-parity with mpost's own file handling.
A TikZ document is not a label but a whole page, so it takes a different road: pdfTeX writes a DVI whose specials carry PGF's drawing commands, and dvisvgm — the reference converter, with its PGF special handlers, FreeType and potrace, also compiled to WebAssembly — turns each page into SVG. The library selects PGF's dvisvgm driver automatically, so nothing needs Ghostscript.
All of PGF/TikZ's libraries are bundled, and so is spath3, whose knots and calligraphy libraries pgf does not ship. A few more of them, each a complete document; the same sources are in the gallery, where they can be edited.
The TikZ road is a real LaTeX road: the engine typesets the entire document, so paragraphs, fonts, hyphenation, amsmath and TeX's low-level primitives all come along. These two examples use \parshape, the primitive that gives every line of a paragraph its own indent and width, with inline TikZ pictures and displayed mathematics flowing through the shape.
Nothing about \parshape needs LaTeX. The same primitive in plain TeX, with a loop computing the 21 line widths:
A second engine, luatex.wasm, runs the same DVI pipeline with LuaTeX 1.21 in DVI mode (TeX Live's dvilualatex and dviluatex). It exists for the parts of TikZ that are written in Lua, above all the graphdrawing library with its layered, force-directed, tree, circular and phylogenetic layouts, plus \directlua, luacode and pgfplots' Lua backends. engine: 'auto' and the drop-in tags choose it whenever a document uses any of these; nothing else changes, and the 4.4 MB module and its 6.5 MB format are only fetched then. By default text is set in the same Type 1 fonts as the pdfTeX route; with the opt-in OpenType bundle it can use fontspec as well (next section). engine: 'lualatex' and engine: 'luatex' ask for LuaTeX explicitly, for LaTeX or plain TeX.
\usepackage{fontspec} with real OpenType faces works under lualatex, and \input luaotfload.sty under plain luatex, through luaotfload shaping in Lua (mode=node). It is opt-in, because LaTeX under LuaTeX probes for luaotfload at start-up and, once it can find it, initialises it on every run — about 200 ms more for a document that never asks for it. Load the opentype bundle (and otf-fonts for unicode-math's maths font):
import { MetaPost, DEFAULT_BUNDLES } from './dist/index.js';
const mp = await MetaPost.create({ bundles: [...DEFAULT_BUNDLES, 'opentype', 'otf-fonts'] });
await mp.latex(doc, { engine: 'lualatex' }); // glyph outlines, as always
await mp.latex(doc, { engine: 'lualatex', fonts: 'woff2' }); // or embedded web fonts and real <text>
await mp.addFiles({ 'Charter.ttf': bytes }); // a face the host supplies: \setmainfont{Charter.ttf}[Path=./]
From the tags, data-bundles="+opentype" on the loader and data-engine="lualatex" on the diagram; from the command line, --opentype. The bundle carries luaotfload, fontspec, unicode-math and the whole Latin Modern OpenType family, every optical size the class options and size commands can select, each face fetched when a document first uses it. The bundle also carries luaotfload's font-name database, prebuilt against the bundled tree, so a fresh engine opens only the faces a document uses (a 12pt article: four faces, 0.44 MB) instead of scanning all 72 first. A face looked up by a name the database does not know — one supplied with addFiles(), say — makes luaotfload rescan, once per engine.
How the files reach the engine: at start-up the loader fetches one small manifest per bundle (a list of paths, sizes and hashes, fourteen in all, four of them opt-in), builds a virtual filesystem inside the Web Worker with a lazy placeholder for every one of the 4,200 files, and writes kpathsea's ls-R index from the manifests, so TeX's file lookups resolve without touching the network. When TeX actually opens a file, its placeholder fetches that one file with a synchronous request, which is why the worker is the default: a page without a worker has to prefetch everything up front. Formats and even the LuaTeX engine arrive the same way, on first use, and the browser's HTTP cache keeps every fetched file across runs and visits. Adding a package that is not bundled means rebuilding the bundles from a local TeX Live (two scripts, a couple of minutes); there is no installation from CTAN at run time. A single document can also be given extra files, such as a .sty from its own project, through the API's files option without rebuilding anything.
The bundles contain LaTeX 2025 with expl3, PGF/TikZ with every library, pgfplots, tikz-cd, amsmath, amssymb, amscls, mathtools, tools, graphics, xcolor, geometry, booktabs, standalone, hyperref, url, listings, fp, imakeidx, todonotes, the Latin Modern fonts in T1/TS1 encodings, Computer Modern, the AMS fonts, Euler, and the 35 standard PostScript fonts (Times, Helvetica, Courier, Palatino and the rest, as URW Type 1). spath3 (the knots and calligraphy libraries) rides along with PGF, as do chemfig, circuitikz (its current release; the rollback copies of old versions are left out) and tikz-3dplot, and this project's own svg.attributes library (above); the opt-in classico bundle adds URW Classico, an Optima (\usepackage{classico}; its fonts are under the Aladdin Free Public License, non-commercial distribution only), and the opt-in opentype and otf-fonts bundles add luaotfload, fontspec, unicode-math, the Latin Modern OpenType family and Latin Modern Math. The opt-in ghostscript bundle adds dvips's PostScript headers and the PSTricks family (every pst-* package but three data-heavy ones), and turns on the Ghostscript module for documents whose PostScript needs it. Adding a package is one line in scripts/build-texmf.sh; the loader fetches files per file, on demand, so bundle size costs nothing until a document uses a file.
| Module | Size | What it is |
|---|---|---|
| mplib.wasm | __MPLIB_MB__ MB | MetaPost 2.11: interpreter, PostScript and SVG backends, Type 1 font machinery, TFM reader, scaled/double/decimal arithmetic, mpto and dvitomp |
| tex.wasm | __TEX_MB__ MB | pdfTeX 1.40.27 in DVI mode, or PDF mode on request (= tex, etex, latex) with kpathsea, zlib, libpng |
| dvisvgm.wasm | __DVISVGM_MB__ MB | dvisvgm 3.4.3 with FreeType, potrace, clipper, woff2/brotli; PostScript specials through the optional Ghostscript module |
| luatex.wasm | __LUATEX_MB__ MB | LuaTeX 1.21 with Lua 5.3, pplib, zziplib, the fontforge-derived font loader, kpathsea and our patched mplib; loaded on demand for graphdrawing and Lua documents |
| ghostscript/gs.wasm | __GS_MB__ MB | Ghostscript 10.08.0 (AGPL): the PostScript and PDF interpreters with their fonts, a separate module (and release archive) that dvisvgm reaches through a bridge; loaded on demand, only for documents whose PostScript needs it (the opt-in ghostscript bundle) |
Native MetaPost shells out to TeX from the middle of its scanner, which WebAssembly cannot do. The TeX step is lifted out of the run instead:
input-ed file are scanned for btex/verbatimtex blocks with a TypeScript port of mpto's lexer, tested byte-for-byte against the C original.dvitomp turns the DVI into .mpx picture expressions, split per block and cached by a hash of engine, format, preceding verbatimtex chain and body.extensions=1; its make_text callback answers each btex synchronously from the cache.scantokens) misses, comes back as nullpicture, and the run repeats once it has been typeset.Forty labels cost one TeX run; editing one label costs one TeX run with one page; an unchanged document costs none.
plain.fmt, etex.fmt and latex.fmt are built by the wasm engine itself at bundle-build time, so they match it byte for byte. tikz.fmt is the optional pre-warmed snapshot: latex.fmt with PGF, its definitional libraries, pgfplots and tikz-cd already loaded, the equivalent of tikzjax's memory image. It saves 50–160 ms per TikZ document and produces byte-identical pages (the test suite checks), but as a 5.8 MB file that does not compress it costs more to download than the 2.5 MB it replaces, so it is the default in Node and opt-in in browsers.
| What a page downloads | raw | gzipped |
|---|---|---|
| the three engines and the JavaScript, once | 5.2 MB | 2.2 MB |
| Ghostscript, once, for the first document with PostScript (opt-in) | __GS_MB__ MB | __GS_GZ_MB__ MB |
| a MetaPost figure, geometry only | 0.07 MB | 0.01 MB |
a MetaPost figure with label() text | 0.16 MB | 0.05 MB |
a MetaPost figure with plain-TeX btex | 0.37 MB | 0.25 MB |
a MetaPost figure with LaTeX btex | 2.4 MB | 2.2 MB |
a TikZ figure (latex.fmt) | 3.8 MB | 2.5 MB |
| a TikZ figure with the snapshot | 5.9 MB | 5.5 MB |
| the first LuaTeX figure (luatex.wasm + dvilualatex.fmt) | + 10.4 MB | + 4.9 MB |
Everything is fetched once and cached by the browser; rendered figures are cached in IndexedDB as well. The whole bundle tree is 47 MB on the server, and no page downloads all of it.
latex, and all 1181 SVG pages match native dvisvgm's. (The one normalisation resolves dvisvgm's own run-to-run choice of which size of a font becomes the base glyph, which makes two native runs of the same DVI differ as well.) node scripts/stress-pgfmanual.mjs reproduces it in about fifteen minutes.mpost from TeX Live 2025 run with the same frozen date.\directlua under LuaTeX — byte-identical to latex / dvilualatex + dvisvgm, with and without the snapshot.mtrap half of MetaPost's official trap test produces the same figures as native MetaPost 2.11; tex.wasm reproduces the oracle's DVI byte for byte; the .mpx round trip through our mpto and dvitomp matches the committed sample.mpto on a 24-case corpus and 60 fuzz inputs, and a native contract harness of 46 checks that would catch a TeX Live bump changing mplib's API.patches/): a process-global flag that crashed the second MetaPost instance in a process; two defects in the extensions=1 scanner (an etex at the end of a line was never matched, and TeX Live's own texnum.mp writes btex$-$etex); stroke-miterlimit for filldraw read from uninitialised memory; a printf format with a bare % in mpto's prologue; font subset tags that differed between 32- and 64-bit builds; and two memory leaks in the instance lifecycle (319 KB per MetaPost instance, found when an animation ran one instance per frame; now zero) that only an embedder creating many instances could see.| mp-tikz-wasm | tikzjax | |
|---|---|---|
| Engine | pdfTeX in DVI mode with a real latex.fmt built by the engine; LuaTeX for graph drawing and Lua | Knuth TeX with a plain-TeX memory snapshot; \documentclass and \usepackage shimmed or ignored |
| Documents | any LaTeX document: standalone, article, multi-page, any bundled package | a TikZ picture body and curated preloaded packages |
| DVI to SVG | dvisvgm itself with PGF's dvisvgm driver: gradients, patterns, opacity, clipping, decorations, markers, pgfplots | a JavaScript re-implementation of the special language; no shadings or patterns |
| Text | glyph outlines in the SVG (self-contained), or woff2 on request | <text> runs plus a CSS font sheet |
| Fonts | Computer Modern, AMS, Euler, Latin Modern in T1/TS1, the 35 standard PostScript fonts; OpenType through fontspec under LuaTeX | Computer Modern |
| MetaPost | yes — the same script also renders <script type="text/metapost"> | no |
| Loading | per-file lazy fetch through real kpathsea; optional pre-warmed format | one snapshot plus a file archive |
| Verification | byte-identical to TeX Live on the corpora | none published |
| Errors | structured diagnostics with line numbers, full logs | the TeX log |
| Isolation | Web Worker with a watchdog; deterministic output | page thread |
\special{ps: …}, graphicx's \rotatebox/\scalebox under its default dvips driver) needs the opt-in ghostscript bundle, which loads Ghostscript as a separate module only for documents that carry PostScript; without it, latex() warns when PostScript was lost. No external image inclusion in SVG output beyond EPS (PDF output includes PNG and JPEG, not PDF images).mode=node, not HarfBuzz (this is luatex, not luahbtex), so mode=harf and Graphite features are out. The bundled faces are Latin Modern; other faces are supplied by the host with addFiles(). TrueType Collections (.ttc) work from 0.4.0 when each face is named by its FontIndex (BoldFeatures={FontIndex=1} and so on); 0.3.1 and earlier draw every face of a collection as one, so with those hand over one .ttf/.otf per face.binary/interval number systems (they need cairo and GMP/MPFR, which are not built).runScript, makeText and onFindFile callbacks; providing one selects in-process mode.mplib library does not write figure files during a run, so a document cannot readfrom its own output; and it exits on a few hard limits (such as an input-stack overflow, which native mpost hits too) rather than raising an error — reported as a fatal diagnostic.siunitx option does not work). chemfig, circuitikz and tikz-3dplot are bundled; circuitikz's rollback releases are not.The build is reproducible from the pinned TeX Live 2025 source tarball (vendor/SOURCES.lock records its SHA-256). It never modifies the vendored tree: patches are applied to a copy, ctangle is built from the vendored CWEB, and every generated file lands under build/ or dist/.
| Step | Produces |
|---|---|
| make tangle / make native / make contract | the tangled C, build/native/libmplib.a, and the native contract harness |
| make wasm | dist/mplib.mjs + mplib.wasm (-O3 -flto); make wasm-debug for an ASSERTIONS/SAFE_HEAP variant |
| scripts/native-texlive.sh | the web2c-generated C for pdfTeX and the native config headers (needs autotools' output, once) |
| scripts/build-tex-wasm.sh | dist/tex.mjs + tex.wasm from that C plus kpathsea, with Emscripten's zlib and libpng ports |
| scripts/native-luatex.sh, scripts/build-luatex-wasm.sh | dist/luatex.mjs + luatex.wasm: the native LuaTeX build's compile commands are recorded and replayed with emcc (Lua 5.3, pplib, zziplib compiled from the vendored sources; the C FFI stubbed) |
| scripts/native-dvisvgm.sh, scripts/build-dvisvgm-wasm.sh | dist/dvisvgm.mjs + dvisvgm.wasm (FreeType and zlib ports, -Oz) |
| scripts/build-texmf.sh | build/texmf: the flattened texmf tree copied from the local TeX Live, with the patches in patches/texmf/ applied, plus tikz.ini and the files in bundles/tex/ |
| node scripts/make-formats.mjs | plain.fmt, etex.fmt, latex.fmt, tikz.fmt, built by tex.wasm; dviluatex.fmt, dvilualatex.fmt by luatex.wasm |
| npm run build:ts | dist/*.js: the library, the worker, the CLI, auto.js (before the bundles: the next step runs through it) |
| npm run build:fontdb | luaotfload's font-name database, built by luatex.wasm against build/texmf, for the opentype bundle |
| node scripts/build-bundles.mjs | dist/bundles/*: manifests and files per bundle |
| npm run build:hot | dist/bundles/hot.json: the files a first run of each kind touches, prefetched in parallel (after any bundle rebuild, which deletes it) |
| npm run package | release/mp-tikz-wasm-__VERSION__.tar.gz and .zip: the prebuilt distribution for a GitHub release |
| npm run build:guide, build:standalone | this page, and the single-file demo with everything inlined |
The design documents in docs/ record every decision; docs/14-implementation-notes.md records what was learned building it, including the upstream defects.
The licence texts are in the repository (LICENSE, NOTICE.md, licenses/). MetaPost itself is public domain. mplib.wasm also contains avl.c (LGPL-3.0-or-later) and decNumber (ICU), so it is distributed under the LGPL-3.0-or-later with the sources, the patches and a reproducible build in the repository. pdfTeX and kpathsea are GPL, so tex.wasm is GPL; LuaTeX is GPL-2.0-or-later (Lua, pplib and zziplib carry MIT-style licences), so luatex.wasm is GPL; dvisvgm is GPL-3.0-or-later, so dvisvgm.wasm is too (it embeds FreeType, potrace, clipper, woff2, brotli and the URW base-14 fonts). The fonts and macro packages in the bundles keep their own free licences. This project's own code is LGPL-3.0-or-later. See LICENSE.md.