@lofcz/tikz 0.0.0-stage → 0.2.0

package/runtime/dist/prerender.js

@@ -0,0 +1,106 @@
+/**
+ * prerender.ts — `mpost-wasm --prerender`: typeset the diagram elements of
+ * HTML pages in Node and save each result as figure-HASH.svg, the file the
+ * drop-in tags look for when the loader carries data-figures (auto.ts,
+ * figures.ts). A page whose figures are all saved loads them as small static
+ * files and never starts the engines in the visitor's browser.
+ *
+ * For each page the figures go to the directory its loader names in
+ * data-figures (default `figures/`), resolved against the page, unless a
+ * directory is given for all of them (or a base directory to resolve each
+ * page's data-figures against, for a rendered copy saved elsewhere). Each page's
+ * figures are typeset with the bundles its loader names in data-bundles, read
+ * exactly as auto.js reads them, so an opt-in bundle (`+classico`) is there as
+ * in the browser; pages wanting different bundles get separate engines. A file
+ * that already exists is kept —
+ * the name is the content, so it is current — unless `force` is set. The
+ * engine is created with the browser's defaults (deterministic, seed 42) so
+ * the bytes are the ones the tags would have produced.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { MetaPost } from './index.js';
+import { extractFigures, figureHash, figureName, loaderAttributes, renderFigure, bundleList } from './figures.js';
+import { DEFAULT_BUNDLES } from './bundles-config.js';
+/** The figures a page needs, with the directory they belong in. */
+export function planPage(page, figuresDir, baseDir) {
+    const html = fs.readFileSync(page, 'utf8');
+    const loader = loaderAttributes(html);
+    const named = loader.figures;
+    const dir = figuresDir ?? path.resolve(baseDir ?? path.dirname(page), named && named !== 'off' ? named : 'figures');
+    const figures = extractFigures(html).map((f) => { const hash = figureHash(f); return { ...f, hash, name: figureName(hash) }; });
+    return { dir, bundles: bundleList(loader.bundles, DEFAULT_BUNDLES), figures };
+}
+export async function prerender(pages, opts = {}) {
+    const report = opts.report ?? (() => { });
+    const entries = [];
+    const seen = new Set();
+    const todo = [];
+    for (const page of pages) {
+        const { dir, figures, bundles: pageBundles } = planPage(page, opts.figuresDir, opts.baseDir);
+        const bundles = [...new Set([...(opts.createOptions?.bundles ?? pageBundles ?? DEFAULT_BUNDLES), ...(opts.addBundles ?? [])])];
+        for (const f of figures) {
+            const file = path.join(dir, f.name);
+            if (seen.has(file))
+                continue; // the same figure on two pages (or twice on one) is one file
+            seen.add(file);
+            const entry = { page, file, name: f.name, hash: f.hash, kind: f.kind, status: 'pending' };
+            entries.push(entry);
+            if (!opts.force && fs.existsSync(file)) {
+                entry.status = 'exists';
+                report(line(entry));
+                continue;
+            }
+            todo.push({ entry, req: { kind: f.kind, source: f.source, attrs: f.attrs }, bundles });
+        }
+    }
+    if (opts.dryRun) {
+        for (const { entry } of todo)
+            report(line(entry));
+    }
+    else if (todo.length) {
+        // one engine per distinct bundle list, in first-use order (or the caller's engine for all)
+        const groups = new Map();
+        for (const t of todo) {
+            const k = opts.mp ? '' : t.bundles.join(',');
+            groups.set(k, [...(groups.get(k) ?? []), t]);
+        }
+        for (const group of groups.values()) {
+            const own = !opts.mp;
+            const mp = opts.mp ?? await MetaPost.create({ logLevel: 'warn', ...opts.createOptions, bundles: group[0].bundles });
+            try {
+                for (const { entry, req } of group) {
+                    const r = await renderFigure(mp, req, entry.hash);
+                    entry.ms = r.ms;
+                    if (r.ok) {
+                        fs.mkdirSync(path.dirname(entry.file), { recursive: true });
+                        fs.writeFileSync(entry.file, r.svg);
+                        entry.status = 'rendered';
+                    }
+                    else {
+                        entry.status = 'failed';
+                        entry.diagnostics = r.diagnostics;
+                    }
+                    report(line(entry));
+                }
+            }
+            finally {
+                if (own)
+                    mp.dispose();
+            }
+        }
+    }
+    const count = (s) => entries.filter((e) => e.status === s).length;
+    return { entries, rendered: count('rendered'), existing: count('exists'), failed: count('failed') };
+}
+/** `figures/figure-abc123.svg  tikz      rendered  312 ms  (tags.html)`, diagnostics indented under a failure. */
+export function line(e) {
+    const rel = path.relative(process.cwd(), e.file) || e.file;
+    const status = e.status === 'pending' ? 'to render' : e.status;
+    const ms = e.ms !== undefined ? `  ${Math.round(e.ms)} ms` : '';
+    let s = `${rel}  ${e.kind.padEnd(8)}  ${status.padEnd(9)}${ms}  (${path.basename(e.page)})`;
+    for (const d of e.diagnostics ?? [])
+        s += `\n    ${d.severity}: ${d.message}${d.line ? ` (line ${d.line})` : ''}`;
+    return s;
+}
+//# sourceMappingURL=prerender.js.map

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;