@lofcz/tikz 0.0.0-stage → 0.1.0

package/runtime/dist/figures.js

@@ -0,0 +1,250 @@
+import { sha256 } from './tex/cache-key.js';
+/** Is this TikZ text a complete document (LaTeX with \documentclass, or plain TeX ending in \bye) rather than a body to wrap? */
+export function isCompleteDocument(source) {
+    return /\\documentclass|\\bye\b/.test(source);
+}
+/** Wrap a TikZ body in a standalone document unless it already is one. */
+export function wrapTikz(source, attrs = {}) {
+    if (isCompleteDocument(source))
+        return source;
+    const libs = (attrs.libraries ?? '').split(/[,\s]+/).filter(Boolean);
+    const gd = (attrs.gdlibraries ?? '').split(/[,\s]+/).filter(Boolean);
+    // graph drawing is used through \graph, which the graphs library provides
+    for (const l of ['graphs', 'graphdrawing'])
+        if (gd.length && !libs.includes(l))
+            libs.push(l);
+    const pkgs = (attrs.packages ?? '').split(/[,\s]+/).filter(Boolean);
+    // A body that is already a picture is not wrapped in another. Environments that
+    // draw their own tikzpicture -- tikzcd, circuitikz, chemfig's \chemfig and
+    // \schemestart -- break when nested in a second one: the page keeps its size but
+    // the drawing collapses to its edge, or vanishes. Standalone's `tikz` option,
+    // though, crops only tikzpicture environments, and left bare under it a circuitikz
+    // comes out as a whole letter page; so such a body gets the plain class, which
+    // crops whatever the body is, with TikZ loaded by hand. Only a body that *starts*
+    // with one is treated so (`\node {\chemfig{...}};` is TikZ code), and every
+    // other body keeps the document -- hence the figure hash -- it always had.
+    const ownPicture = /^\s*(\\begin\{(tikzcd|circuitikz)\}|\\chemfig\b|\\schemestart\b)/.test(source);
+    const isPicture = ownPicture || /\\begin\{tikzpicture\}|\\tikz\b|\\begin\{axis\}/.test(source);
+    const body = isPicture ? source : `\\begin{tikzpicture}\n${source}\n\\end{tikzpicture}`;
+    const border = attrs.border ?? '2pt';
+    return [
+        ...(ownPicture ? [`\\documentclass[border=${border}]{standalone}`, '\\usepackage{tikz}'] : [`\\documentclass[tikz,border=${border}]{standalone}`]),
+        ...(pkgs.length ? [`\\usepackage{${pkgs.join(',')}}`] : []),
+        ...(libs.length ? [`\\usetikzlibrary{${libs.join(',')}}`] : []),
+        ...(gd.length ? [`\\usegdlibrary{${gd.join(',')}}`] : []),
+        ...(attrs.preamble ? [attrs.preamble] : []),
+        '\\begin{document}',
+        body,
+        '\\end{document}',
+    ].join('\n');
+}
+/**
+ * Wrap a MetaPost body in one figure unless it already has beginfig/endfig.
+ * `input` statements are hoisted out of the figure: `input boxes` inside a
+ * figure group makes MetaPost (native mpost too) recurse until its input stack
+ * overflows, and macro packages are meant to be loaded at top level anyway.
+ */
+export function wrapMetaPost(source, attrs = {}) {
+    const prologues = attrs.prologues ?? '3';
+    if (/\bbeginfig\s*\(/.test(source))
+        return `prologues:=${prologues};\n${source}`;
+    const inputs = [];
+    const body = source.split('\n').filter((line) => {
+        const m = /^\s*(input\s+[^;%]+;?)\s*(%.*)?$/.exec(line);
+        if (m) {
+            inputs.push(m[1].endsWith(';') ? m[1] : m[1] + ';');
+            return false;
+        }
+        return true;
+    }).join('\n');
+    return `prologues:=${prologues};\n${inputs.join('\n')}${inputs.length ? '\n' : ''}beginfig(1);\n${body}\nendfig;\nend.`;
+}
+/** The document the engines are given for an element. */
+export function figureDocument(req) {
+    return req.kind === 'tikz' ? wrapTikz(req.source, req.attrs) : wrapMetaPost(req.source, req.attrs);
+}
+const HASH_SPACE = 2176782336n; // 36^6
+/** Six lowercase base-36 characters identifying a figure (see the header). */
+export function figureHash(req) {
+    const a = req.attrs;
+    const d = sha256(new TextEncoder().encode(`${req.kind}\0${a.fonts ?? ''}\0${a.tex ?? ''}\0${a.engine ?? ''}\0${figureDocument(req)}`));
+    let n = 0n;
+    for (let i = 0; i < 8; i++)
+        n = (n << 8n) | BigInt(d[i]);
+    return (n % HASH_SPACE).toString(36).padStart(6, '0');
+}
+/** `figure-HASH.svg`. */
+export function figureName(hash) { return `figure-${hash}.svg`; }
+/** Matches a saved figure's file name; group 1 is the hash. */
+export const FIGURE_FILE = /^figure-([0-9a-z]{6})\.svg$/;
+/** Does this text start like an SVG document (a server that answers every path with its index page does not)? */
+export function isSvg(text) {
+    return /^\s*(?:<\?xml[^>]*\?>\s*)?(?:<!--[\s\S]*?-->\s*)*(?:<!DOCTYPE[^>]*>\s*)?<svg[\s>]/i.test(text);
+}
+/** Typeset one figure with the engine; the ids are prefixed with its hash so the SVG stands alone. */
+export async function renderFigure(mp, req, hash = figureHash(req)) {
+    const doc = figureDocument(req);
+    const idPrefix = `mpw${hash}-`;
+    if (req.kind === 'tikz') {
+        const engine = req.attrs.engine ?? 'auto';
+        // A wrapped body is a standalone page with a border, and the SVG must be
+        // that page: dvisvgm's default box is the tight one PGF reports, which is
+        // the page minus the border — and not always all of the ink. PGF's
+        // classic arrow tips (`>=latex`, `stealth`, ...) declare no hull, so TikZ
+        // leaves them out of its bounding box (TeX Live 2025); natively the
+        // border is what keeps them on the page, and the tight crop cut them off
+        // (a `->` on a horizontal line rendered as a line with no head).
+        // `papersize` is the page standalone lays out, so the SVG is the PDF
+        // page. A complete document keeps the default: an article is not a page.
+        const bbox = isCompleteDocument(req.source) ? undefined : 'papersize';
+        const r = await mp.latex(doc, { fonts: req.attrs.fonts === 'woff2' ? 'woff2' : 'paths', engine, bbox, svg: { idPrefix, precision: false } });
+        return { svg: r.pages.join('\n'), log: r.log, diagnostics: r.diagnostics, ok: r.status === 'ok' && r.pages.length > 0, ms: r.stats.totalMs };
+    }
+    const tex = (req.attrs.tex ?? 'auto');
+    const r = await mp.run(doc, { format: 'svg', tex, svg: { idPrefix } });
+    // several beginfig blocks give several <svg> roots joined by newlines: exactly what the tags inject
+    return { svg: r.figures.map((f) => f.svg ?? '').join('\n'), log: r.log, diagnostics: r.diagnostics, ok: r.history < 2 && r.figures.length > 0, ms: r.stats.totalMs };
+}
+const SCRIPT_RE = /<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi;
+const ELEMENT_RE = /<(tikz-diagram|metapost-diagram)\b([^>]*)>([\s\S]*?)<\/\1\s*>/gi;
+const ATTR_RE = /([^\s"'<>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'<>`]+)))?/g;
+const ENTITY_RE = /&(?:#(\d+)|#x([0-9a-f]+)|(lt|gt|amp|quot|apos|nbsp));/gi;
+const ENTITIES = { lt: '<', gt: '>', amp: '&', quot: '"', apos: "'", nbsp: ' ' };
+/** Decode the entities an HTML parser would in text and attribute values. */
+export function decodeEntities(s) {
+    if (!s.includes('&'))
+        return s;
+    return s.replace(ENTITY_RE, (_m, dec, hex, name) => dec ? String.fromCodePoint(Number(dec)) : hex ? String.fromCodePoint(parseInt(hex, 16)) : ENTITIES[name.toLowerCase()]);
+}
+/** Attributes of an opening tag, `data-` stripped, as the tags see them (`attrsOf` in auto.ts). */
+export function parseAttributes(s) {
+    const out = {};
+    for (const m of s.matchAll(ATTR_RE))
+        out[m[1].toLowerCase().replace(/^data-/, '')] = decodeEntities(m[2] ?? m[3] ?? m[4] ?? '');
+    return out;
+}
+/** The text of an element as `textContent` gives it, then trimmed as the tags trim it. */
+function normalize(text) { return text.replace(/^\s*\n/, '').replace(/\s+$/, ''); }
+/** Every diagram element in a page, in document order. */
+export function extractFigures(html) {
+    const found = [];
+    for (const m of html.matchAll(SCRIPT_RE)) {
+        const attrs = parseAttributes(m[1]);
+        const type = (attrs.type ?? '').trim().toLowerCase();
+        if (type !== 'text/tikz' && type !== 'text/metapost')
+            continue;
+        found.push({ kind: type === 'text/metapost' ? 'metapost' : 'tikz', source: normalize(m[2]), attrs, tag: 'script', offset: m.index });
+    }
+    for (const m of html.matchAll(ELEMENT_RE)) {
+        const tag = m[1].toLowerCase();
+        found.push({ kind: tag === 'metapost-diagram' ? 'metapost' : 'tikz', source: normalize(decodeEntities(m[3])), attrs: parseAttributes(m[2]), tag, offset: m.index });
+    }
+    return found.sort((a, b) => a.offset - b.offset);
+}
+/** The `data-*` attributes of the page's auto.js loader tag (`data-figures` → `figures`), or {} if there is none. */
+/**
+ * A loader's data-bundles as a bundle list: names prefixed with + are added to the
+ * defaults (`+opentype`), a bare list replaces them; mixing the two is a replace
+ * with the +names appended. undefined when the attribute is absent or empty. The
+ * one parser for auto.js and the pre-renderer, so they can never load different sets.
+ */
+export function bundleList(spec, defaults) {
+    const names = (spec ?? '').split(/[,\s]+/).filter(Boolean);
+    if (!names.length)
+        return undefined;
+    const added = names.filter((n) => n.startsWith('+')).map((n) => n.slice(1));
+    const listed = names.filter((n) => !n.startsWith('+'));
+    return [...(listed.length ? listed : defaults), ...added];
+}
+export function loaderAttributes(html) {
+    const m = /<script\b([^>]*\bsrc\s*=\s*["'][^"']*auto\.js["'][^>]*)>/i.exec(html);
+    if (!m)
+        return {};
+    const out = {};
+    for (const a of m[1].matchAll(ATTR_RE))
+        if (a[1].toLowerCase().startsWith('data-'))
+            out[a[1].slice(5).toLowerCase()] = decodeEntities(a[2] ?? a[3] ?? a[4] ?? '');
+    return out;
+}
+// ----------------------------------------------------------------- a zip file
+// Store-only (SVG compresses well, but the browsers that need the zip are the
+// ones without a directory picker, and a dependency is not worth a few
+// hundred kilobytes). Timestamps are fixed at 1980-01-01 so the archive is
+// reproducible.
+let crcTable = null;
+export function crc32(data) {
+    if (!crcTable) {
+        crcTable = new Uint32Array(256);
+        for (let n = 0; n < 256; n++) {
+            let c = n;
+            for (let k = 0; k < 8; k++)
+                c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+            crcTable[n] = c >>> 0;
+        }
+    }
+    let c = 0xffffffff;
+    for (let i = 0; i < data.length; i++)
+        c = crcTable[(c ^ data[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+export function makeZip(files) {
+    const enc = new TextEncoder();
+    const parts = [], central = [];
+    let offset = 0;
+    for (const f of files) {
+        const name = enc.encode(f.name), data = typeof f.data === 'string' ? enc.encode(f.data) : f.data, crc = crc32(data);
+        const local = new Uint8Array(30 + name.length), l = new DataView(local.buffer);
+        l.setUint32(0, 0x04034b50, true);
+        l.setUint16(4, 20, true);
+        l.setUint16(6, 0x0800, true);
+        l.setUint16(8, 0, true);
+        l.setUint16(10, 0, true);
+        l.setUint16(12, 0x0021, true);
+        l.setUint32(14, crc, true);
+        l.setUint32(18, data.length, true);
+        l.setUint32(22, data.length, true);
+        l.setUint16(26, name.length, true);
+        l.setUint16(28, 0, true);
+        local.set(name, 30);
+        const cd = new Uint8Array(46 + name.length), c = new DataView(cd.buffer);
+        c.setUint32(0, 0x02014b50, true);
+        c.setUint16(4, 20, true);
+        c.setUint16(6, 20, true);
+        c.setUint16(8, 0x0800, true);
+        c.setUint16(10, 0, true);
+        c.setUint16(12, 0, true);
+        c.setUint16(14, 0x0021, true);
+        c.setUint32(16, crc, true);
+        c.setUint32(20, data.length, true);
+        c.setUint32(24, data.length, true);
+        c.setUint16(28, name.length, true);
+        c.setUint16(30, 0, true);
+        c.setUint16(32, 0, true);
+        c.setUint16(34, 0, true);
+        c.setUint16(36, 0, true);
+        c.setUint32(38, 0, true);
+        c.setUint32(42, offset, true);
+        cd.set(name, 46);
+        parts.push(local, data);
+        central.push(cd);
+        offset += local.length + data.length;
+    }
+    const cdSize = central.reduce((n, c) => n + c.length, 0);
+    const end = new Uint8Array(22), e = new DataView(end.buffer);
+    e.setUint32(0, 0x06054b50, true);
+    e.setUint16(4, 0, true);
+    e.setUint16(6, 0, true);
+    e.setUint16(8, files.length, true);
+    e.setUint16(10, files.length, true);
+    e.setUint32(12, cdSize, true);
+    e.setUint32(16, offset, true);
+    e.setUint16(20, 0, true);
+    const out = new Uint8Array(offset + cdSize + 22);
+    let p = 0;
+    for (const part of [...parts, ...central, end]) {
+        out.set(part, p);
+        p += part.length;
+    }
+    return out;
+}
+//# sourceMappingURL=figures.js.map

package/runtime/dist/ghostscript.d.ts

@@ -0,0 +1,92 @@
+/**
+ * ghostscript.ts — Ghostscript for dvisvgm, as a module of its own.
+ *
+ * dvisvgm interprets PostScript specials (PSTricks, EPS images, `ps:` code,
+ * graphicx's rotation and scaling under its dvips driver) through Ghostscript's
+ * C API. dvisvgm.wasm asks for "libgs" with dlopen, and src/c/gs-bridge.c
+ * answers with gsapi_* proxies that call Module.gsBridge, the object built
+ * here. It forwards each call to a separate Ghostscript wasm module
+ * (vendor/GHOSTSCRIPT.lock, served from dist/ghostscript/), copying buffers
+ * between the two heaps. Ghostscript is never linked into dvisvgm.wasm, and it
+ * is loaded only by a document whose DVI carries PostScript worth running
+ * (postscript.ts), only when the `ghostscript` bundle is enabled.
+ *
+ * Ghostscript opens files itself (an EPS goes in as `(fig.eps) run`), so for
+ * each dvisvgm run its /work and /texmf are mounted into the Ghostscript
+ * module with Emscripten's PROXYFS. One module serves every document in turn:
+ * gsapi_new_instance ... gsapi_delete_instance per dvisvgm run, never two at
+ * once (a non-threaded Ghostscript refuses a second live instance).
+ */
+/** The Emscripten module of the Ghostscript port (its gs.js), as far as it is used here. */
+export interface GhostscriptModule {
+    HEAPU8: Uint8Array;
+    FS: any;
+    PROXYFS: any;
+    _malloc(n: number): number;
+    _free(p: number): void;
+    addFunction(fn: (...args: number[]) => number, sig: string): number;
+    stringToUTF8(s: string, ptr: number, max: number): void;
+    lengthBytesUTF8(s: string): number;
+    _gsapi_revision(p: number, len: number): number;
+    _gsapi_new_instance(pinstance: number, caller: number): number;
+    _gsapi_delete_instance(instance: number): void;
+    _gsapi_set_stdio(instance: number, stdin: number, stdout: number, stderr: number): number;
+    _gsapi_init_with_args(instance: number, argc: number, argv: number): number;
+    _gsapi_run_string_begin(instance: number, userErrors: number, pexit: number): number;
+    _gsapi_run_string_continue(instance: number, str: number, length: number, userErrors: number, pexit: number): number;
+    _gsapi_run_string_end(instance: number, userErrors: number, pexit: number): number;
+    _gsapi_exit(instance: number): number;
+}
+export type GhostscriptFactory = (moduleArg: Record<string, unknown>) => Promise<GhostscriptModule>;
+/** What gs-bridge.js calls, on Module.gsBridge of a dvisvgm instance. */
+export interface GsBridge {
+    available(): boolean;
+    revision(): [number, number];
+    newInstance(): number;
+    init(args: string[]): number;
+    run(op: 0 | 1 | 2, bytes: Uint8Array | null, userErrors: number): [number, number];
+    exit(): number;
+    deleteInstance(): void;
+    take(stream: 1 | 2, max: number): Uint8Array | null;
+}
+export declare class Ghostscript {
+    private readonly M;
+    private instance;
+    private readonly out;
+    private readonly cell;
+    private buf;
+    private bufSize;
+    private readonly fns;
+    private mounted;
+    /** set when the module trapped: it is not used again, and the engine loads a fresh one */
+    broken: boolean;
+    private constructor();
+    /** Instantiate the module from a compiled gs.wasm. */
+    static create(factory: GhostscriptFactory, wasm: WebAssembly.Module): Promise<Ghostscript>;
+    private view;
+    /** Give Ghostscript dvisvgm's files: its /work (the cwd) and its /texmf. */
+    mount(dvisvgmFS: any, dirs: string[]): void;
+    unmount(): void;
+    /** Run fn against the module; a trap marks it broken and becomes a Ghostscript fatal error. */
+    private guard;
+    bridge(): GsBridge;
+}
+export declare function compileGhostscript(key: string, bytes: () => Promise<Uint8Array>): Promise<WebAssembly.Module>;
+/**
+ * A lazy loader for one engine: nothing is fetched until a document needs
+ * Ghostscript; then the glue is imported, gs.wasm compiled (once per process)
+ * and a module instantiated, which serves later documents too. A module that
+ * trapped is replaced. If loading fails, it says so once and returns null, so
+ * documents still render, with a warning, as without Ghostscript.
+ */
+export declare function ghostscriptLoader(o: {
+    glueUrl: string;
+    wasmUrl: string;
+    fetch: (url: string) => Promise<Uint8Array>;
+    factory?: GhostscriptFactory;
+    log?: (message: string) => void;
+}): () => Promise<Ghostscript | null>;
+/** Whether these options turn Ghostscript on: the option itself, or the `ghostscript` bundle in the list. */
+export declare function ghostscriptWanted(ghostscript: boolean | undefined, bundles: (string | {
+    name: string;
+})[]): boolean;

package/runtime/dist/ghostscript.js

@@ -0,0 +1,218 @@
+/**
+ * ghostscript.ts — Ghostscript for dvisvgm, as a module of its own.
+ *
+ * dvisvgm interprets PostScript specials (PSTricks, EPS images, `ps:` code,
+ * graphicx's rotation and scaling under its dvips driver) through Ghostscript's
+ * C API. dvisvgm.wasm asks for "libgs" with dlopen, and src/c/gs-bridge.c
+ * answers with gsapi_* proxies that call Module.gsBridge, the object built
+ * here. It forwards each call to a separate Ghostscript wasm module
+ * (vendor/GHOSTSCRIPT.lock, served from dist/ghostscript/), copying buffers
+ * between the two heaps. Ghostscript is never linked into dvisvgm.wasm, and it
+ * is loaded only by a document whose DVI carries PostScript worth running
+ * (postscript.ts), only when the `ghostscript` bundle is enabled.
+ *
+ * Ghostscript opens files itself (an EPS goes in as `(fig.eps) run`), so for
+ * each dvisvgm run its /work and /texmf are mounted into the Ghostscript
+ * module with Emscripten's PROXYFS. One module serves every document in turn:
+ * gsapi_new_instance ... gsapi_delete_instance per dvisvgm run, never two at
+ * once (a non-threaded Ghostscript refuses a second live instance).
+ */
+/** gs_error_Fatal: what the proxies report when the module itself failed. */
+const FATAL = -100;
+export class Ghostscript {
+    M;
+    instance = 0;
+    out = [[], [], []]; // index 1 stdout, 2 stderr
+    cell; // 16 scratch bytes: instance pointer, exit code, revision
+    buf = 0;
+    bufSize = 0;
+    fns;
+    mounted = [];
+    /** set when the module trapped: it is not used again, and the engine loads a fresh one */
+    broken = false;
+    constructor(M) {
+        this.M = M;
+        this.cell = M._malloc(16);
+        const collect = (stream) => (_caller, ptr, len) => {
+            if (len > 0)
+                this.out[stream].push(this.M.HEAPU8.slice(ptr, ptr + len));
+            return len;
+        };
+        this.fns = [M.addFunction(() => 0, 'iiii'), M.addFunction(collect(1), 'iiii'), M.addFunction(collect(2), 'iiii')];
+    }
+    /** Instantiate the module from a compiled gs.wasm. */
+    static async create(factory, wasm) {
+        const M = await factory({
+            print: () => { }, printErr: () => { },
+            instantiateWasm(imports, receive) {
+                WebAssembly.instantiate(wasm, imports).then((inst) => receive(inst, wasm));
+                return {};
+            },
+        });
+        return new Ghostscript(M);
+    }
+    view() { return new DataView(this.M.HEAPU8.buffer); }
+    /** Give Ghostscript dvisvgm's files: its /work (the cwd) and its /texmf. */
+    mount(dvisvgmFS, dirs) {
+        const FS = this.M.FS;
+        for (const dir of dirs) {
+            if (!dvisvgmFS.analyzePath(dir).exists)
+                continue;
+            try {
+                FS.mkdirTree(dir);
+            }
+            catch { /* exists */ }
+            FS.mount(this.M.PROXYFS, { root: dir, fs: dvisvgmFS }, dir);
+            this.mounted.push(dir);
+        }
+        if (this.mounted.includes('/work'))
+            FS.chdir('/work');
+    }
+    unmount() {
+        const FS = this.M.FS;
+        try {
+            FS.chdir('/');
+        }
+        catch { /* ignore */ }
+        for (const dir of this.mounted.splice(0)) {
+            try {
+                FS.unmount(dir);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    /** Run fn against the module; a trap marks it broken and becomes a Ghostscript fatal error. */
+    guard(fallback, fn) {
+        if (this.broken)
+            return fallback;
+        try {
+            return fn();
+        }
+        catch {
+            this.broken = true;
+            return fallback;
+        }
+    }
+    bridge() {
+        const M = this.M;
+        return {
+            available: () => !this.broken,
+            revision: () => this.guard([0, 0], () => {
+                M._gsapi_revision(this.cell, 16); // wasm32: product, copyright (pointers), revision, revisiondate (longs)
+                const v = this.view();
+                return [v.getInt32(this.cell + 8, true), v.getInt32(this.cell + 12, true)];
+            }),
+            newInstance: () => this.guard(FATAL, () => {
+                this.out[1] = [];
+                this.out[2] = [];
+                // *pinstance must be null: a non-null value asks to share that (existing) instance
+                this.view().setUint32(this.cell, 0, true);
+                const code = M._gsapi_new_instance(this.cell, 0);
+                if (code < 0)
+                    return code;
+                this.instance = this.view().getUint32(this.cell, true);
+                return M._gsapi_set_stdio(this.instance, ...this.fns);
+            }),
+            init: (args) => this.guard(FATAL, () => {
+                const enc = new TextEncoder();
+                const strs = args.map((a) => enc.encode(a));
+                const block = M._malloc(4 * strs.length + strs.reduce((n, s) => n + s.length + 1, 0));
+                let p = block + 4 * strs.length;
+                strs.forEach((s, i) => {
+                    this.view().setUint32(block + 4 * i, p, true);
+                    M.HEAPU8.set(s, p);
+                    M.HEAPU8[p + s.length] = 0;
+                    p += s.length + 1;
+                });
+                try {
+                    return M._gsapi_init_with_args(this.instance, strs.length, block);
+                }
+                finally {
+                    M._free(block);
+                }
+            }),
+            run: (op, bytes, userErrors) => this.guard([FATAL, FATAL], () => {
+                const exit = this.cell + 4;
+                let code;
+                if (op === 0)
+                    code = M._gsapi_run_string_begin(this.instance, userErrors, exit);
+                else if (op === 2)
+                    code = M._gsapi_run_string_end(this.instance, userErrors, exit);
+                else {
+                    const n = bytes.length;
+                    if (n > this.bufSize) {
+                        if (this.buf)
+                            M._free(this.buf);
+                        this.buf = M._malloc(n);
+                        this.bufSize = n;
+                    }
+                    M.HEAPU8.set(bytes, this.buf);
+                    code = M._gsapi_run_string_continue(this.instance, this.buf, n, userErrors, exit);
+                }
+                return [code, this.view().getInt32(exit, true)];
+            }),
+            exit: () => this.guard(FATAL, () => M._gsapi_exit(this.instance)),
+            deleteInstance: () => this.guard(undefined, () => {
+                if (this.instance)
+                    M._gsapi_delete_instance(this.instance);
+                this.instance = 0;
+            }),
+            take: (stream, max) => {
+                const q = this.out[stream];
+                if (!q.length)
+                    return null;
+                const head = q[0];
+                if (head.length <= max) {
+                    q.shift();
+                    return head;
+                }
+                q[0] = head.subarray(max);
+                return head.subarray(0, max);
+            },
+        };
+    }
+}
+/** One compile of gs.wasm per process, whoever asks. */
+const compiled = new Map();
+export function compileGhostscript(key, bytes) {
+    let p = compiled.get(key);
+    if (!p) {
+        p = bytes().then((b) => WebAssembly.compile(b));
+        p.catch(() => compiled.delete(key));
+        compiled.set(key, p);
+    }
+    return p;
+}
+/**
+ * A lazy loader for one engine: nothing is fetched until a document needs
+ * Ghostscript; then the glue is imported, gs.wasm compiled (once per process)
+ * and a module instantiated, which serves later documents too. A module that
+ * trapped is replaced. If loading fails, it says so once and returns null, so
+ * documents still render, with a warning, as without Ghostscript.
+ */
+export function ghostscriptLoader(o) {
+    let current = null;
+    let failed = false;
+    return async () => {
+        if (failed)
+            return null;
+        if (current && !current.broken)
+            return current;
+        try {
+            const factory = o.factory ?? (await import(/* @vite-ignore */ o.glueUrl)).default;
+            const wasm = await compileGhostscript(o.wasmUrl, () => o.fetch(o.wasmUrl));
+            current = await Ghostscript.create(factory, wasm);
+            return current;
+        }
+        catch (e) {
+            failed = true;
+            o.log?.(`Ghostscript could not be loaded from ${o.wasmUrl}: ${e?.message ?? e}`);
+            return null;
+        }
+    };
+}
+/** Whether these options turn Ghostscript on: the option itself, or the `ghostscript` bundle in the list. */
+export function ghostscriptWanted(ghostscript, bundles) {
+    return ghostscript ?? bundles.some((b) => (typeof b === 'string' ? b : b.name) === 'ghostscript');
+}
+//# sourceMappingURL=ghostscript.js.map

package/runtime/dist/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * mp-tikz-wasm — public API (docs/08). `MetaPost.create()` starts a Web
+ * Worker in browsers and runs in-process in Node (or when `worker: false`).
+ */
+import type { MetaPostOptions, RunOptions, RunResult, ProgressEvent, BundleName, LatexRunOptions, LatexResult, PrefetchKind, LogLevel, LogRecord, BibtexOptions, MakeindexOptions, ToolResult } from './types.js';
+export * from './types.js';
+export { sanitizeSvg, postProcessSvg } from './render/svg.js';
+export { scanTexBlocks, scanInputs } from './tex/scanner.js';
+export { parseMetaPostLog } from './diagnostics.js';
+export { splitMpx } from './tex/mpx.js';
+export { LOG_LEVELS, formatRecord, consoleSink } from './logger.js';
+export { DEFAULT_BUNDLES } from './bundles-config.js';
+export { figureHash, figureName, figureDocument, extractFigures, renderFigure, wrapTikz, wrapMetaPost, makeZip, FIGURE_FILE } from './figures.js';
+export type { FigureKind, FigureRequest, FigureResult, SavedFigure, FoundFigure } from './figures.js';
+export declare class MetaPost {
+    private backend;
+    private options;
+    private listeners;
+    private queue;
+    private readonly t0;
+    readonly version: {
+        metapost: string;
+        tex: string;
+        build: string;
+    };
+    private constructor();
+    static create(options?: MetaPostOptions): Promise<MetaPost>;
+    /**
+     * The stall watchdog (worker only): the run is killed when `timeoutMs` pass without a progress
+     * event or a line of engine output. Every engine phase and every on-demand file fetch is progress,
+     * so a first run on a slow host that spends a minute fetching files one after another is left
+     * alone, and so is a long TeX run that is still printing; a silent, hung engine is not.
+     */
+    private watchdog;
+    /** Events from either backend: log records reach the console (or the `logger` option), raw lines the `log` option, then any listeners. */
+    private handleEvent;
+    /** A record from this side of the worker boundary (a failed call, the watchdog), subject to the same level. */
+    private hostRecord;
+    private failing;
+    /** How much reaches the console (see `MetaPostOptions.logLevel`); can be changed at any time, also mid-run. */
+    get logLevel(): LogLevel;
+    set logLevel(level: LogLevel);
+    /** Compile MetaPost source. Calls are serialised on this instance. */
+    run(source: string, options?: RunOptions): Promise<RunResult>;
+    /** Typeset a whole LaTeX/TikZ (or plain TeX) document to one SVG per page. */
+    latex(source: string, options?: LatexRunOptions): Promise<LatexResult>;
+    /**
+     * BibTeX on the .aux a latex() run wrote (`files: result.artifacts`, plus the .bib databases):
+     * doc.bbl and doc.blg come back in `artifacts`, for the next latex() run. TeX Live's styles
+     * are in the `latex-doc` bundle. Serialised with run() and latex() on this instance.
+     */
+    bibtex(options?: BibtexOptions): Promise<ToolResult>;
+    /** makeindex on the .idx a latex() run wrote: doc.ind and doc.ilg come back in `artifacts`. */
+    makeindex(options?: MakeindexOptions): Promise<ToolResult>;
+    private serialise;
+    addFiles(files: Record<string, string | Uint8Array>): Promise<void>;
+    /**
+     * Take off this instance files that addFiles or a run's `files` put there, named as they were
+     * given (all of them with no names). Passed files otherwise stay for the instance's lifetime:
+     * a host typesetting several documents should remove one document's .aux, .toc, .bbl before
+     * the next, or the next one reads them.
+     */
+    removeFiles(names?: string[]): Promise<void>;
+    preload(bundles: BundleName[]): Promise<void>;
+    /** Fetch in parallel the files a first run of these kinds needs (see `MetaPostOptions.prefetch`). Resolves to the number fetched. */
+    prefetch(kinds: PrefetchKind[]): Promise<number>;
+    clearCache(): Promise<void>;
+    on(event: 'progress', fn: (e: ProgressEvent) => void): () => void;
+    on(event: 'log', fn: (line: string) => void): () => void;
+    on(event: 'record', fn: (r: LogRecord) => void): () => void;
+    private emit;
+    dispose(): void;
+}
+/** A pool of independent instances for batch work (docs/10 §2.3). */
+export declare class MetaPostPool {
+    private all;
+    private idle;
+    private waiters;
+    private constructor();
+    static create(options?: MetaPostOptions & {
+        size?: number;
+    }): Promise<MetaPostPool>;
+    private acquire;
+    private release;
+    run(source: string, options?: RunOptions): Promise<RunResult>;
+    dispose(): void;
+}