latexml-oxide CLAUDE.md

CLAUDE.md

This is a Perl-to-Rust translation project. Every translated entry must follow tightly the original semantics and nuances of the Perl source. Read the Perl source first, translate precisely; do not invent new abstractions, rename concepts, or simplify behavior unless documented as an intentional divergence in docs/parity/OXIDIZED_DESIGN.md. The Perl code is the ground truth.

Active priorities: faithful parity + beyond-Perl arXiv runs

Two co-equal targets drive current work:

1. Faithful translation of the original Perl LaTeXML. Strict parity at the format/dump and package-loading boundary is maintained — the strict-LoadFormat dump-parity mission is complete (zero-error inits, dumps match Perl; audit archived at docs/archive/PERL_LOADFORMAT_AUDIT.md, the ~72-CS Perl-only long-tail residual tracked in SYNC_STATUS.md "Engine file open gaps"). Ongoing parity work is corpus-driven: mine fatal/error clusters from live runs, classify vs same-host Perl (canvas-triage skill), fix GENUINE-RUST-ONLY divergences faithfully.
2. Beyond-Perl improvement runs over arXiv. The production cortex_worker fleet converts the full ~2.8M-doc arXiv corpus. Beyond-Perl levers: performance (docs/performance/PERFORMANCE.md / ARXIV_PERFORMANCE.md), reliability (STABILITY_WITNESSES.md), and the source-provenance showcase (issues #47/#92, SOURCE_PROVENANCE.md).

Test counts, gate status, and corpus throughput live in docs/SYNC_STATUS.md, which is commit-tracked. Do not copy those numbers here — the copy drifts.

Two traps when reading a test run:

• A fully green suite still prints Error: lines to stderr. Several tests deliberately raise diagnostics to prove they get reported (the graphics.rs worker-thread fold emits failed_to_convert for a nonexistent w0.pdf; the Rhai script-binding tests emit boom). Judge a test run by its test result: lines and exit code, never by grepping its output for Error: — that heuristic belongs to conversion logs (below), and here it inverts.
• The two latexml_post vector-SVG tests self-skip silently and green unless mutool or pdftocairo is on PATH, so a green local run does not by itself prove that branch ran. CI installs poppler/mupdf.