@lofcz/tikz 0.0.0-stage → 0.1.0

package/runtime/dist/render/svg.d.ts

@@ -0,0 +1,20 @@
+/**
+ * svg.ts — post-processing of MetaPost's SVG output (docs/07 §3.1). The C
+ * output is left byte-identical to upstream; everything here is optional
+ * polish applied on the string.
+ */
+import type { SvgPostOptions } from '../types.js';
+export declare function postProcessSvg(svg: string, opts?: SvgPostOptions, figureIndex?: number): string;
+/**
+ * A regular-expression allow-list over the markup: keeps the SVG elements
+ * MetaPost emits and drops everything else (scripts, event handlers,
+ * foreignObject, external references).
+ *
+ * @deprecated Not a security boundary, and too narrow for what the engines
+ * produce: it drops gradients (every PGF shading), patterns, `<style>` (the
+ * faces of `fonts: 'woff2'`) and the geometry of circles, ellipses and lines.
+ * Sanitise untrusted output with DOMPurify instead — the README's
+ * "Untrusted sources" has the configuration. Kept, unchanged, so existing
+ * callers do not break; to be removed at 1.0.
+ */
+export declare function sanitizeSvg(svg: string): string;

package/runtime/dist/render/svg.js

@@ -0,0 +1,96 @@
+const NUM = /-?\d+\.\d{4,}/g;
+export function postProcessSvg(svg, opts = {}, figureIndex = 0) {
+    let s = svg;
+    if (opts.precision !== false) {
+        const p = opts.precision ?? 3;
+        s = s.replace(NUM, (m) => {
+            const v = Number(m);
+            let r = v.toFixed(p);
+            if (r.includes('.'))
+                r = r.replace(/\.?0+$/, '');
+            if (r === '-0')
+                r = '0';
+            return r;
+        });
+    }
+    if (opts.idPrefix !== false) {
+        // MetaPost's ids (GLYPHcmr10_77, CLIP1, ...) are global per figure and
+        // collide when several figures are inlined on one page: url(#CLIP1) then
+        // resolves to the first CLIP1 in the document. Namespace every id and
+        // every reference to one.
+        // MetaPost's backend writes double-quoted attributes, dvisvgm single-quoted ones
+        const prefix = opts.idPrefix ?? `mp${figureIndex}-`;
+        s = s.replace(/\bid=(["'])([^"']+)\1/g, (_m, q, id) => `id=${q}${prefix}${id}${q}`)
+            .replace(/href=(["'])#([^"']+)\1/g, (_m, q, id) => `href=${q}#${prefix}${id}${q}`)
+            .replace(/url\(#([^)]+)\)/g, (_m, id) => `url(#${prefix}${id})`);
+        // fonts: 'woff2' has the same problem one level up. dvisvgm names each embedded
+        // face nf0, nf1, ... and styles the runs with `text.f0 {font-family:nf0}`. Once the
+        // SVG is inlined both the @font-face family names and the class selectors are
+        // document-global, so a second figure's nf0 wins and the first renders from the
+        // wrong subset — with a fallback glyph wherever that subset has no such character,
+        // which is how it shows up: a word half in one weight and half in another.
+        s = s.replace(/font-family:nf(\d+)/g, (_m, n) => `font-family:${prefix}nf${n}`)
+            .replace(/\btext\.f(\d+)\b/g, (_m, n) => `text.${prefix}f${n}`)
+            .replace(/\bclass=(["'])f(\d+)\1/g, (_m, q, n) => `class=${q}${prefix}f${n}${q}`);
+    }
+    if (opts.modernHref)
+        s = s.replace(/xlink:href=/g, 'href=');
+    if (opts.units === 'px') {
+        s = s.replace(/<svg([^>]*)width="([\d.]+)"([^>]*)height="([\d.]+)"/, (_m, a, w, b, h) => `<svg${a}width="${trim(Number(w) * 96 / 72)}"${b}height="${trim(Number(h) * 96 / 72)}"`);
+    }
+    else if (opts.units === 'none') {
+        s = s.replace(/<svg([^>]*)\swidth="[\d.]+"/, '<svg$1').replace(/<svg([^>]*)\sheight="[\d.]+"/, '<svg$1');
+    }
+    if (opts.title) {
+        const t = escapeXml(opts.title);
+        s = s.replace(/<svg([^>]*)>/, `<svg$1 role="img" aria-label="${t}"><title>${t}</title>`);
+    }
+    return s;
+}
+function trim(v) { let r = v.toFixed(3); r = r.replace(/\.?0+$/, ''); return r; }
+function escapeXml(s) { return s.replace(/[<>&"]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;' }[c])); }
+/**
+ * A regular-expression allow-list over the markup: keeps the SVG elements
+ * MetaPost emits and drops everything else (scripts, event handlers,
+ * foreignObject, external references).
+ *
+ * @deprecated Not a security boundary, and too narrow for what the engines
+ * produce: it drops gradients (every PGF shading), patterns, `<style>` (the
+ * faces of `fonts: 'woff2'`) and the geometry of circles, ellipses and lines.
+ * Sanitise untrusted output with DOMPurify instead — the README's
+ * "Untrusted sources" has the configuration. Kept, unchanged, so existing
+ * callers do not break; to be removed at 1.0.
+ */
+export function sanitizeSvg(svg) {
+    const allowedTags = new Set(['svg', 'g', 'path', 'defs', 'use', 'text', 'title', 'desc', 'clipPath', 'rect', 'circle', 'ellipse', 'line', 'polyline', 'polygon', 'tspan']);
+    const allowedAttr = /^(id|class|d|x|y|width|height|viewBox|version|xmlns|xmlns:xlink|xlink:href|href|transform|style|fill|fill-rule|stroke|stroke-width|stroke-linecap|stroke-linejoin|stroke-miterlimit|stroke-dasharray|stroke-dashoffset|clip-path|font-size|font-family|role|aria-label|opacity|fill-opacity|stroke-opacity)$/;
+    // comments are harmless but drop them to be safe; scripts and foreign
+    // content go with their contents, not just their tags
+    let out = svg.replace(/<!--[\s\S]*?-->/g, '');
+    out = out.replace(/<\?xml[^>]*\?>/, '');
+    out = out.replace(/<(script|style|foreignObject|iframe|object|embed)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, '');
+    out = out.replace(/<\/?([a-zA-Z:]+)([^>]*)>/g, (m, tag, attrs) => {
+        if (!allowedTags.has(tag))
+            return '';
+        if (m.startsWith('</'))
+            return `</${tag}>`;
+        const kept = (attrs.match(/([a-zA-Z:-]+)\s*=\s*("[^"]*"|'[^']*')/g) || []).filter((a) => {
+            const name = a.split('=')[0].trim();
+            if (!allowedAttr.test(name))
+                return false;
+            const val = a.slice(a.indexOf('=') + 1).trim().slice(1, -1);
+            if (/href/.test(name) && !val.startsWith('#'))
+                return false;
+            // only same-document url(#id) references (clip-path, fill patterns); nothing external
+            if (/url\(/i.test(val) && !/^url\(#[^)]+\)$/.test(val.trim()))
+                return false;
+            if (/javascript:|expression\(|@import|data:/i.test(val))
+                return false;
+            return true;
+        });
+        const selfClose = attrs.trim().endsWith('/') ? '/' : '';
+        return `<${tag}${kept.length ? ' ' + kept.join(' ') : ''}${selfClose}>`;
+    });
+    return out.trim();
+}
+//# sourceMappingURL=svg.js.map

package/runtime/dist/tex/bridge.d.ts

@@ -0,0 +1,93 @@
+/**
+ * bridge.ts — the TeX Bridge (docs/05): lift TeX out of the MetaPost run.
+ *
+ *   scan → keys → cache → batch TeX (tex.wasm) → dvitomp (mplib.wasm) → split
+ *
+ * The bridge never runs inside make_text; it fills the snippet cache before
+ * a MetaPost run and again between fixpoint iterations.
+ */
+import type { TexBlock } from './scanner.js';
+import { type TexFactory, type TexModule } from '../texengine.js';
+import { type MplibModule } from '../mplib.js';
+import type { Diagnostic, TexEngine } from '../types.js';
+export interface Snippet {
+    key: string;
+    chain: string[];
+    body: string;
+    line?: number;
+    file?: string;
+}
+export interface SnippetCache {
+    get(key: string): string | undefined;
+    set(key: string, chunk: string): void;
+    clear(): void;
+    readonly size: number;
+}
+export declare class MemorySnippetCache implements SnippetCache {
+    private m;
+    get(k: string): string | undefined;
+    set(k: string, v: string): void;
+    clear(): void;
+    get size(): number;
+}
+/** Canonical form of a snippet body for cache keys: whitespace runs collapsed,
+ *  trimmed. mplib hands make_text a trimmed, newline-to-space converted body
+ *  (texscriptmode=1) while the pre-scan sees the raw text; both map here. */
+export declare function canonicalBody(s: string): string;
+export type ResolvedEngine = 'plain' | 'etex' | 'latex';
+export interface EngineInfo {
+    engine: ResolvedEngine;
+    format: string;
+    progname: string;
+    formatId: string;
+    engineId: string;
+}
+export declare function resolveEngine(engine: TexEngine, blocks: TexBlock[], source: string): ResolvedEngine | 'none';
+export interface BridgeOptions {
+    texFactory: TexFactory;
+    mplib: MplibModule;
+    /** prepare a fresh tex.wasm FS: mount/install /texmf, create /work */
+    setupTexFS: (M: TexModule) => void;
+    cache: SnippetCache;
+    texPreamble?: string;
+    workDir?: string;
+    onLine?: (line: string) => void;
+    engineId: string;
+    formatIds: Record<ResolvedEngine, string>;
+}
+export interface TypesetResult {
+    texLog: string;
+    exitCode: number;
+    ms: number;
+    pages: number;
+    diagnostics: Diagnostic[];
+    resolved: number;
+}
+export declare class TexBridge {
+    private o;
+    constructor(o: BridgeOptions);
+    key(engine: ResolvedEngine, chain: string[], body: string): string;
+    /**
+     * Given the ordered blocks of a document, return the snippets whose chunk is
+     * not cached (with their verbatimtex chain), in source order.
+     */
+    misses(engine: ResolvedEngine, blocks: TexBlock[]): {
+        hits: number;
+        misses: Snippet[];
+        chainFor: Map<number, string[]>;
+    };
+    /**
+     * Typeset a list of snippets in ONE TeX run and store the resulting chunks.
+     * Snippets must be in source order; chains are emitted incrementally.
+     */
+    typeset(engine: ResolvedEngine, snippets: Snippet[]): Promise<TypesetResult>;
+}
+/**
+ * Map TeX errors back to btex blocks: the generated .tex has one
+ * `\mpxshipout% line N file` wrapper line per block; a TeX `l.<n>` line number
+ * inside [wrapper, \stopmpxshipout] belongs to that block.
+ */
+export declare function parseTexLog(log: string, tex: string, blocks: {
+    block: TexBlock;
+    snippet: Snippet;
+}[]): Diagnostic[];

package/runtime/dist/tex/bridge.js

@@ -0,0 +1,223 @@
+import { buildTexJob } from './mpto.js';
+import { splitMpx } from './mpx.js';
+import { snippetKey } from './cache-key.js';
+import { runTex } from '../texengine.js';
+import { dvitomp, mpxLastError } from '../mplib.js';
+import { writeFileDeep } from '../vfs/lazyfs.js';
+export class MemorySnippetCache {
+    m = new Map();
+    get(k) { return this.m.get(k); }
+    set(k, v) { this.m.set(k, v); }
+    clear() { this.m.clear(); }
+    get size() { return this.m.size; }
+}
+/** Canonical form of a snippet body for cache keys: whitespace runs collapsed,
+ *  trimmed. mplib hands make_text a trimmed, newline-to-space converted body
+ *  (texscriptmode=1) while the pre-scan sees the raw text; both map here. */
+export function canonicalBody(s) { return s.replace(/\s+/g, ' ').trim(); }
+export function resolveEngine(engine, blocks, source) {
+    if (engine === 'none' || engine === 'plain' || engine === 'etex' || engine === 'latex')
+        return engine;
+    // auto (docs/05 §8)
+    const first = source.split('\n', 1)[0] ?? '';
+    if (/^%&\s*latex\b/i.test(first))
+        return 'latex';
+    const firstVerb = blocks.find((b) => b.kind === 'verbatimtex');
+    if (firstVerb && /\\documentclass|\\documentstyle/.test(firstVerb.body))
+        return 'latex';
+    if (/%&\s*etex\b/i.test(first))
+        return 'etex';
+    return 'plain';
+}
+const PROG = {
+    plain: { fmt: 'plain', progname: 'tex' },
+    etex: { fmt: 'etex', progname: 'etex' },
+    latex: { fmt: 'latex', progname: 'latex' },
+};
+let jobCounter = 0;
+export class TexBridge {
+    o;
+    constructor(o) {
+        this.o = o;
+    }
+    key(engine, chain, body) {
+        return snippetKey({ engineId: this.o.engineId, formatId: this.o.formatIds[engine], chain: chain.map(canonicalBody), body: canonicalBody(body) });
+    }
+    /**
+     * Given the ordered blocks of a document, return the snippets whose chunk is
+     * not cached (with their verbatimtex chain), in source order.
+     */
+    misses(engine, blocks) {
+        const chain = [];
+        const misses = [];
+        let hits = 0;
+        const chainFor = new Map();
+        for (const b of blocks) {
+            if (b.kind === 'verbatimtex') {
+                chain.push(b.body);
+                continue;
+            }
+            const key = this.key(engine, chain, b.body);
+            chainFor.set(b.index, [...chain]);
+            if (this.o.cache.get(key) !== undefined) {
+                hits++;
+                continue;
+            }
+            misses.push({ key, chain: [...chain], body: b.body, line: b.line, file: b.file });
+        }
+        return { hits, misses, chainFor };
+    }
+    /**
+     * Typeset a list of snippets in ONE TeX run and store the resulting chunks.
+     * Snippets must be in source order; chains are emitted incrementally.
+     */
+    async typeset(engine, snippets) {
+        const blocks = [];
+        let emitted = [];
+        let idx = 0;
+        const lineOf = [];
+        for (const s of snippets) {
+            // emit any verbatimtex entries not yet emitted (chains normally extend each other)
+            let common = 0;
+            while (common < emitted.length && common < s.chain.length && emitted[common] === s.chain[common])
+                common++;
+            for (let i = common; i < s.chain.length; i++) {
+                blocks.push({ kind: 'verbatimtex', body: s.chain[i], raw: s.chain[i], line: s.line ?? 0, file: s.file ?? 'job.mp', index: idx++ });
+            }
+            emitted = [...s.chain];
+            const b = { kind: 'btex', body: s.body, raw: s.body, line: s.line ?? 0, file: s.file ?? 'job.mp', index: idx++ };
+            blocks.push(b);
+            lineOf.push({ block: b, snippet: s });
+        }
+        const tex = buildTexJob(blocks, { mode: 'tex', mptexpre: this.o.texPreamble });
+        const name = `mpx${(++jobCounter).toString(36)}`;
+        const { fmt, progname } = PROG[engine];
+        let dvi = null;
+        let logFile = '';
+        const r = await runTex(this.o.texFactory, {
+            args: [`-fmt=${fmt}`, `-progname=${progname}`, '-interaction=nonstopmode', '-parse-first-line', `${name}.tex`],
+            setup: (M) => {
+                this.o.setupTexFS(M);
+                writeFileDeep(M.FS, `/work/${name}.tex`, tex);
+                M.FS.chdir('/work');
+            },
+            collect: (M) => {
+                try {
+                    dvi = M.FS.readFile(`/work/${name}.dvi`, { encoding: 'binary' });
+                }
+                catch {
+                    dvi = null;
+                }
+                try {
+                    logFile = M.FS.readFile(`/work/${name}.log`, { encoding: 'utf8' });
+                }
+                catch {
+                    logFile = r?.log ?? '';
+                }
+            },
+            onLine: this.o.onLine,
+        });
+        const texLog = logFile || r.log;
+        const diagnostics = parseTexLog(texLog, tex, lineOf);
+        let pages = 0, resolved = 0;
+        if (dvi) {
+            const M = this.o.mplib;
+            const work = this.o.workDir ?? '/work';
+            writeFileDeep(M.FS, `${work}/${name}.dvi`, dvi);
+            const rc = dvitomp(M, `${work}/${name}.dvi`, `${work}/${name}.mpx`, '% Written by mp-tikz-wasm');
+            if (rc !== 0) {
+                let err = mpxLastError(M);
+                try {
+                    err += '\n' + M.FS.readFile(`${work}/mpxerr.log`, { encoding: 'utf8' });
+                }
+                catch { /* none */ }
+                diagnostics.push({ severity: 'error', source: 'tex', message: `dvitomp failed: ${err.trim()}` });
+            }
+            else {
+                const mpx = M.FS.readFile(`${work}/${name}.mpx`, { encoding: 'utf8' });
+                const chunks = splitMpx(mpx);
+                pages = chunks.length;
+                for (let i = 0; i < lineOf.length; i++) {
+                    const chunk = chunks[i];
+                    if (chunk !== undefined) {
+                        this.o.cache.set(lineOf[i].snippet.key, chunk);
+                        resolved++;
+                    }
+                    else {
+                        this.o.cache.set(lineOf[i].snippet.key, 'nullpicture');
+                        diagnostics.push({ severity: 'warning', source: 'tex', message: 'btex block produced no output; replaced by nullpicture', file: lineOf[i].snippet.file, line: lineOf[i].snippet.line, snippet: lineOf[i].snippet.body });
+                    }
+                }
+                try {
+                    M.FS.unlink(`${work}/${name}.mpx`);
+                }
+                catch { /* ignore */ }
+            }
+            try {
+                M.FS.unlink(`${work}/${name}.dvi`);
+            }
+            catch { /* ignore */ }
+        }
+        else {
+            // no DVI at all: every snippet becomes nullpicture so the run can proceed
+            for (const s of snippets)
+                this.o.cache.set(s.key, 'nullpicture');
+            if (!diagnostics.some((d) => d.severity === 'error')) {
+                diagnostics.push({ severity: 'error', source: 'tex', message: `TeX produced no DVI (exit ${r.exitCode})` });
+            }
+        }
+        return { texLog, exitCode: r.exitCode, ms: r.ms, pages, diagnostics, resolved };
+    }
+}
+/**
+ * Map TeX errors back to btex blocks: the generated .tex has one
+ * `\mpxshipout% line N file` wrapper line per block; a TeX `l.<n>` line number
+ * inside [wrapper, \stopmpxshipout] belongs to that block.
+ */
+export function parseTexLog(log, tex, blocks) {
+    const out = [];
+    const texLines = tex.split('\n');
+    // wrapper line index (0-based) for each btex block, in order of appearance
+    const starts = [];
+    texLines.forEach((l, i) => { if (l.startsWith('\\mpxshipout%'))
+        starts.push(i); });
+    const lines = log.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const m = /^! (.*)$/.exec(lines[i]);
+        if (!m)
+            continue;
+        let texLine;
+        const help = [];
+        let j = i + 1;
+        for (; j < lines.length && j < i + 40; j++) {
+            const lm = /^l\.(\d+)/.exec(lines[j]);
+            if (lm) {
+                texLine = Number(lm[1]);
+                break;
+            }
+            if (/^! /.test(lines[j]))
+                break;
+        }
+        // help paragraph follows the context lines
+        for (let k = (texLine !== undefined ? j + 2 : i + 1); k < lines.length && k < i + 40; k++) {
+            if (lines[k].trim() === '' || /^! /.test(lines[k]) || /^l\.\d+/.test(lines[k]))
+                break;
+            help.push(lines[k]);
+        }
+        let blockIdx = -1;
+        if (texLine !== undefined) {
+            for (let b = 0; b < starts.length; b++)
+                if (starts[b] < texLine)
+                    blockIdx = b;
+        }
+        const d = { severity: 'error', source: 'tex', message: m[1], help: help.length ? help : undefined };
+        if (blockIdx >= 0 && blocks[blockIdx]) {
+            d.file = blocks[blockIdx].snippet.file;
+            d.line = blocks[blockIdx].snippet.line;
+            d.snippet = blocks[blockIdx].snippet.body;
+        }
+        out.push(d);
+    }
+    return out;
+}
+//# sourceMappingURL=bridge.js.map

package/runtime/dist/tex/cache-key.d.ts

@@ -0,0 +1,33 @@
+/**
+ * cache-key.ts — content-addressed keys for the two TeX-bridge caches
+ * (docs/05 §6): L2 snippet keys and L1 document keys.
+ *
+ * Both are SHA-256 over a canonical, length-prefixed encoding, so no two
+ * distinct inputs can collide by concatenation ("ab"+"c" vs "a"+"bc"), and a
+ * snippet key can never equal a document key (each kind carries its own tag).
+ *
+ * The digest is computed by a small pure-TypeScript SHA-256 rather than
+ * `crypto.subtle.digest`, because the `make_text` hook that consults the
+ * snippet cache must answer synchronously and Web Crypto is Promise-only.
+ * Dependency-free and browser-safe.
+ */
+export interface SnippetKeyParts {
+    /** Build id of tex.wasm. */
+    engineId: string;
+    /** Hash of the format file (plain.fmt / latex.fmt). */
+    formatId: string;
+    /** The verbatimtex blocks that precede the snippet, in source order. */
+    chain: readonly string[];
+    /** The btex text as handed to make_text. */
+    body: string;
+    /** MetaPost's `texscriptmode` internal; defaults to 1 like MetaPost. */
+    texscriptmode?: number;
+}
+/** L2 key: H(engineId, formatId, verbatimtex chain, body, texscriptmode). */
+export declare function snippetKey(parts: SnippetKeyParts): string;
+/** L1 key: H(full generated .tex, engineId, formatId). */
+export declare function documentKey(texSource: string, engineId: string, formatId: string): string;
+/** SHA-256 of `data` (a string is UTF-8 encoded first) as lowercase hex. */
+export declare function sha256Hex(data: Uint8Array | string): string;
+/** SHA-256 of `msg`, as 32 bytes. */
+export declare function sha256(msg: Uint8Array): Uint8Array;

package/runtime/dist/tex/cache-key.js

@@ -0,0 +1,150 @@
+/**
+ * cache-key.ts — content-addressed keys for the two TeX-bridge caches
+ * (docs/05 §6): L2 snippet keys and L1 document keys.
+ *
+ * Both are SHA-256 over a canonical, length-prefixed encoding, so no two
+ * distinct inputs can collide by concatenation ("ab"+"c" vs "a"+"bc"), and a
+ * snippet key can never equal a document key (each kind carries its own tag).
+ *
+ * The digest is computed by a small pure-TypeScript SHA-256 rather than
+ * `crypto.subtle.digest`, because the `make_text` hook that consults the
+ * snippet cache must answer synchronously and Web Crypto is Promise-only.
+ * Dependency-free and browser-safe.
+ */
+/* ---- canonical encoding --------------------------------------------------- */
+class Encoder {
+    parts = [];
+    total = 0;
+    static utf8 = new TextEncoder();
+    push(bytes) {
+        this.parts.push(bytes);
+        this.total += bytes.length;
+    }
+    u32(n) {
+        if (!Number.isInteger(n) || n < 0 || n > 0xffffffff)
+            throw new RangeError(`u32 out of range: ${n}`);
+        this.push(new Uint8Array([(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff]));
+        return this;
+    }
+    /** A string as `u32 byteLength` + UTF-8 bytes. */
+    str(s) {
+        const b = Encoder.utf8.encode(s);
+        this.u32(b.length);
+        this.push(b);
+        return this;
+    }
+    /** A list of strings as `u32 count` + each string. */
+    list(items) {
+        this.u32(items.length);
+        for (const s of items)
+            this.str(s);
+        return this;
+    }
+    bytes() {
+        const out = new Uint8Array(this.total);
+        let o = 0;
+        for (const p of this.parts) {
+            out.set(p, o);
+            o += p.length;
+        }
+        return out;
+    }
+}
+/** Version the encodings so a change in layout can never alias an old key. */
+const SNIPPET_TAG = 'mp-tikz-wasm:snippet:1';
+const DOCUMENT_TAG = 'mp-tikz-wasm:document:1';
+/** L2 key: H(engineId, formatId, verbatimtex chain, body, texscriptmode). */
+export function snippetKey(parts) {
+    const mode = parts.texscriptmode ?? 1;
+    const enc = new Encoder()
+        .str(SNIPPET_TAG)
+        .str(parts.engineId)
+        .str(parts.formatId)
+        .list(parts.chain)
+        .str(parts.body)
+        .str(String(mode));
+    return sha256Hex(enc.bytes());
+}
+/** L1 key: H(full generated .tex, engineId, formatId). */
+export function documentKey(texSource, engineId, formatId) {
+    const enc = new Encoder().str(DOCUMENT_TAG).str(engineId).str(formatId).str(texSource);
+    return sha256Hex(enc.bytes());
+}
+/* ---- SHA-256 (FIPS 180-4), synchronous ------------------------------------ */
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+/** SHA-256 of `data` (a string is UTF-8 encoded first) as lowercase hex. */
+export function sha256Hex(data) {
+    const d = sha256(typeof data === 'string' ? new TextEncoder().encode(data) : data);
+    let hex = '';
+    for (let i = 0; i < d.length; i++)
+        hex += (d[i] < 16 ? '0' : '') + d[i].toString(16);
+    return hex;
+}
+/** SHA-256 of `msg`, as 32 bytes. */
+export function sha256(msg) {
+    const H = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const W = new Uint32Array(64);
+    // Padding: 0x80, zeros, then the 64-bit big-endian bit length.
+    const len = msg.length;
+    const padded = new Uint8Array(((len + 9 + 63) >> 6) << 6);
+    padded.set(msg);
+    padded[len] = 0x80;
+    const bitsHi = Math.floor(len / 0x20000000); // len * 8 / 2^32
+    const bitsLo = (len << 3) >>> 0;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 8, bitsHi);
+    view.setUint32(padded.length - 4, bitsLo);
+    for (let off = 0; off < padded.length; off += 64) {
+        for (let t = 0; t < 16; t++)
+            W[t] = view.getUint32(off + t * 4);
+        for (let t = 16; t < 64; t++) {
+            const w15 = W[t - 15];
+            const w2 = W[t - 2];
+            const s0 = ((w15 >>> 7) | (w15 << 25)) ^ ((w15 >>> 18) | (w15 << 14)) ^ (w15 >>> 3);
+            const s1 = ((w2 >>> 17) | (w2 << 15)) ^ ((w2 >>> 19) | (w2 << 13)) ^ (w2 >>> 10);
+            W[t] = (W[t - 16] + s0 + W[t - 7] + s1) >>> 0;
+        }
+        let a = H[0], b = H[1], c = H[2], d = H[3], e = H[4], f = H[5], g = H[6], h = H[7];
+        for (let t = 0; t < 64; t++) {
+            const S1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+            const ch = (e & f) ^ (~e & g);
+            const T1 = (h + S1 + ch + K[t] + W[t]) >>> 0;
+            const S0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const T2 = (S0 + maj) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + T1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (T1 + T2) >>> 0;
+        }
+        H[0] = (H[0] + a) >>> 0;
+        H[1] = (H[1] + b) >>> 0;
+        H[2] = (H[2] + c) >>> 0;
+        H[3] = (H[3] + d) >>> 0;
+        H[4] = (H[4] + e) >>> 0;
+        H[5] = (H[5] + f) >>> 0;
+        H[6] = (H[6] + g) >>> 0;
+        H[7] = (H[7] + h) >>> 0;
+    }
+    const out = new Uint8Array(32);
+    const ov = new DataView(out.buffer);
+    for (let i = 0; i < 8; i++)
+        ov.setUint32(i * 4, H[i]);
+    return out;
+}
+//# sourceMappingURL=cache-key.js.map

package/runtime/dist/tex/mpto.d.ts

@@ -0,0 +1,60 @@
+/**
+ * mpto.ts — builds the batched TeX job from scanned blocks (docs/05 §3.1, §4).
+ *
+ * `buildTexJob` reproduces byte for byte the file that upstream `mpx_mpto`
+ * (texk/web2c/mplibdir/mpxout.w) writes for the same input. The string
+ * tables below are copied verbatim from mpxout.w — including their printf
+ * escapes, which `cfmt` interprets — so a future upstream change can be
+ * diffed against them directly.
+ */
+import type { TexBlock } from './scanner.js';
+export type MptoMode = 'tex' | 'troff';
+/**
+ * How the C library rendered the malformed conversion `%\n` that upstream's
+ * `mpx_pretex1` contains twice (`\bgroup%\n` and `\bgroup}%\n` — a printf
+ * format with `%` followed by a newline). The C standard leaves it undefined
+ * and libcs differ, so `mpost` binaries differ too:
+ *
+ *  - `glibc` (Linux): `printf_unknown` prints the spec verbatim, so the `%`
+ *    survives as the TeX comment the author intended. The default.
+ *  - `bsd` (Apple libc, FreeBSD): "pretend it was %c with argument ch", so
+ *    the `%` vanishes and only the newline is printed.
+ *  - musl (Emscripten's libc) rejects the format and prints *nothing* for
+ *    that fprintf — the whole prologue and the first `\mpxshipout% line`
+ *    are missing — which is why the wasm build must not call the C mpto.
+ *
+ * TeX skips the end-of-line space after the control word `\bgroup`, so the
+ * DVI and the .mpx are identical for both renderings.
+ */
+export type PrintfLibc = 'glibc' | 'bsd';
+export interface BuildTexJobOptions {
+    /** TeX (default) or troff output. Index 0 / 1 of the string tables. */
+    mode?: MptoMode;
+    /** Contents of the MPTEXPRE file (docs/05 §9); prepended as-is in TeX mode
+     * only, exactly as upstream copies the file — no newline is added. */
+    mptexpre?: string;
+    /** Which libc's rendering of the `%\n` quirk to reproduce; default 'glibc'. */
+    libc?: PrintfLibc;
+}
+/**
+ * mpto's "put no % at end if it's only 1 line total, starting with %" rule
+ * (the `%&format` special case): after trimming, a btex body gets a `%`
+ * appended unless it is a single line that begins with `%`. An empty body
+ * gets one too.
+ */
+export declare function needsPercent(body: string): boolean;
+/**
+ * Emit the TeX (or troff) job for `blocks`, in source order. Blocks may come
+ * from several files (their `file` and `line` are used for the
+ * `% line N file` wrapper comments); the "first btex" / "first verbatimtex"
+ * bookkeeping is per job, as it is per mpto run upstream.
+ */
+export declare function buildTexJob(blocks: readonly TexBlock[], options?: BuildTexJobOptions): string;
+/**
+ * DVI page `pageIndex` (0-based) was produced by the `pageIndex`-th `btex`
+ * block of the job: every btex block ships out exactly one page, in source
+ * order, and verbatimtex blocks ship nothing (docs/05 §3.1). Blocks that
+ * mpto flagged with an error still get a (blank) page. Returns undefined
+ * when the DVI has more pages than the job has btex blocks.
+ */
+export declare function blockForPage(blocks: readonly TexBlock[], pageIndex: number): TexBlock | undefined;