[Perf] TikZ/pgfplots 병렬 외부화 워커 풀

[akcorca]

배경

TeX 조판 자체는 순차적이지만 TikZ/pgfplots 그림은 서로 독립이다. 네이티브 환경의 tikzexternalize는 shell-escape가 필요해 브라우저에서 못 쓴다. TikZ 비중이 큰 문서에서 컴파일 시간의 대부분이 그림 조판이다.

제안

전처리 단계에서 외부화를 에뮬레이션한다.

1. 문법 스냅샷/토크나이저로 tikzpicture (및 \begin{axis} 포함) 환경을 추출한다.
2. 각 그림을 preamble(관련 \usepackage, \usetikzlibrary, \pgfplotsset, 매크로 정의) + standalone 클래스로 감싼 독립 문서로 만든다.
3. 워커 풀(코어 수 기반, 2~4개 pdfTeX 워커)에서 병렬 컴파일하고, 결과 PDF를 내용 해시로 캐시한다.
4. 본문의 그림을 \includegraphics{<hash>.pdf} 로 치환한 뒤 메인 컴파일을 돈다.
5. 그림 소스나 preamble 해시가 바뀐 그림만 재컴파일한다.

폴백: 추출 실패, 외부 매크로/카운터 의존(\ref 등), 컴파일 실패 시 해당 그림은 인라인으로 남긴다. 결과가 인라인과 달라질 수 있는 케이스(페이지 스타일 의존, remember picture/overlay)는 외부화 대상에서 제외한다.

측정

• 벤치 문서: TikZ 그림 10개 + pgfplots 5개짜리 article. cold/warm, 그림 1개 편집 시 지연.
• 워커 수 1/2/4 별 벽시계 시간과 메모리 피크.
• 외부화 결과와 인라인 결과의 시각 동일성(래스터 diff) 검사.

[akcorca]

Baseline + prototype measurements (2026-09-02, release engine 2025, pdflatex, preamble snapshot on)

Benchmark doc: 10 node/arrow tikzpictures + 5 pgfplots axes (200-sample plots), .scratch/tikz-doc.tex.

Case	warm recompile	full (preamble rebuilt)
inline (today)	1108 ms	1422 ms
same doc, pictures replaced by \rule placeholders (lower bound)	120 ms	436 ms
one pgfplots axis as standalone	264 ms	591 ms

→ pictures are ~89% of the warm compile.

Prototype: upstream external library, no engine patch

Main job gets \usetikzlibrary{external}\tikzexternalize[mode=list and make]; figure jobs run on a second WasmTexCompiler with the same preamble plus \def\tikzexternalrealjob{<realjob>}\def\jobname{wasmtex-figure} in front and \def\pgfactualjobname{<figure>} right after \begin{document} (so the figure worker's preamble snapshot is reused across figures; the external optimize path skips the non-matching pictures).

Step	ms
main warm, figures missing (placeholders)	132
figure job, node picture (warm)	139–146
figure job, pgfplots axis (warm)	262–682
all 15 figure jobs, serial	~3.6 s (parallel pool of 4 ≈ 1 s)
main warm with all 15 figure PDFs included	137 ms (vs 1108 inline, 8.1×)

Page 1 of the externalized build is pixel-identical to the inline build (qlmanage render). Final PDF is larger (136 KB vs 83 KB) because each figure PDF embeds its own resources.

Break-even: a text-only edit (all figures cached) goes 1108→137 ms; a single-figure edit ≈ 140–680 ms + 137 ms; changing the preamble invalidates everything (≈1 s with a 4-worker pool, same as today).

Next: implement in WasmTexCompiler (headless) — honor documents that already call \tikzexternalize (today those produce shell-escape errors) via figure jobs on a lazy worker pool, .md5-driven change detection from the library itself, optional auto-injection mode.

[akcorca]

Integrated path measured (headless tikzExternalization, 15-picture doc, 3 figure workers, release engine 2025):

case	inline (before)	externalized
warm text-only recompile	1130 ms	130 ms (8.7×)
10 node pictures edited	1130 ms	887 ms (figure jobs 640 ms)
5 pgfplots pictures edited	1130 ms	892 ms (figure jobs 648 ms)
first compile, cold, incl. spawning figure workers	22 s	12 s

Implementation PR: corca-ai/wasmtex perf/tikz-externalization. Default mode honours only documents that already call \tikzexternalize; mode: 'auto' (inject) measured identical on the text-edit path (133 ms).

[akcorca]

Cycle 2 landed: #93 (53fd56b) makes mode: 'auto' safe as a host default — blockers (beamer / remember picture / overlay / tikzmark / wrapped environments / <3 pictures), inline fallback on any figure-job failure, \ref inside pictures via aux hand-off, picture errors surfaced at source lines, % !WASMTEX tikz-externalization = off|document|auto per-document override, memory-aware worker count and idle release.

Corpus (graphs, pgfplots, body styles, \input/\include): auto vs inline pixel-identical (≤0.17 % anti-aliasing), zero errors; looped 15-picture doc text edit 128 ms vs 1150 ms inline. cortex switches its browser compiler to auto (cortex PR in flight).

Left for later: dynamic-import the figure pool in wasmtex if the cortex shell budget gets tight (504.6/505 KiB now); persistent (IndexedDB) figure cache across sessions.