FlashTeX never reads a .cls or .sty — 60% of real documents open with a class it cannot parse

[d-q222]

A 163-document corpus of what students and researchers actually write was assembled and cross-referenced against our support. The result is a single structural finding that reframes the backlog.

The root cause, verified in source

FlashTeX never reads a .cls or .sty file at all.

• \input/\include resolve .tex only — crates/compiler/src/parser.rs:4261
• \documentclass has built-in knowledge for article, report, book, letter only — parser.rs:4330-4380
• The primitives a class file needs do not exist: \def, \let, \newif, \expandafter, \csname, \makeatletter, \RequirePackage, \LoadClass, \DeclareOption, \ProcessOptions

So package and class support is not "partially implemented" — it is a hardcoded allow-list of 24 packages and 4 classes, and anything outside it is invisible regardless of whether the file is sitting right there on disk.

What that costs, measured on 163 real documents

• \documentclass distribution: article 55, beamer 14, scrartcl 9, report 6, amsart/book/exam 4 each, then 46 one-off thesis/CV/poster/homework classes. Kernel classes are 65/163 — 40%. Sixty percent of real documents open with a class we cannot read.
• Only 10 of 163 documents (6%) load nothing outside the allow-list. The median document loads 12 unsupported packages.

Ranked by documents affected: graphicx 81 · babel 61 · tikz 58 · fancyhdr 52 · listings 45 · microtype 41 · fontspec 37 · etoolbox 36 · url 35 · calc 34 · textcomp 33 · tabularx 29 · mathtools 26 · lmodern 26.

Day one, for a student — concrete

what they download	what happens
Metropolis beamer theme (6.9k★)	\usetheme, \setbeamercolor, \frametitle, columns, block, \pause all unknown — and frame is implemented as "draw a box around the body", so the deck renders as boxed paragraphs instead of failing loudly. Silent-wrong, the worst outcome.
Cambridge PhDThesisPSnPDF (433 forks)	dies at line 1
Awesome-CV (28.5k★)	loads zero packages of its own; everything is class + fontspec. Nothing renders.
jdavis homework template (463 forks)	starts (it is article) but fancyhdr/extramarks/tikz/algorithm/algpseudocode are all unsupported → body text only
Jake's Resume (705 forks)	the nearest miss. article, 218 lines. Needs titlesec + fancyhdr + tabularx + a system-file fallback for \input{glyphtounicode}. Highest student-impact-per-unit-work item in the whole corpus.

Separately: \chapter, \part, \appendix, \frontmatter are unimplemented even though report/book set up the counters — so every thesis and every book fails there regardless of any class-loading fix.

Our own coverage data under-reports support

supported-latex.json is not a complete support oracle. \hline, \cline, \multicolumn, booktabs rules, multirow, longtable and colortbl are implemented in crates/compiler/src/parser/tabular.rs but absent from that inventory, and vocabulary.rs's KNOWN_UNIMPLEMENTED_* lists are stale and overlap implemented names (#715 covers part of this). Any analysis driven off that file alone — including our own coverage.md — will be wrong in both directions.

Suggested direction

This is a Tier-1 architectural question, not a lane task, and I am flagging it rather than dispatching it:

1. Read .sty/.cls from the filesystem and interpret enough of the kernel to run them. That means the \def/\let/\newif/\csname/\@ifpackageloaded layer. Largest effort, removes the whole class of problem, and makes every future package work without a code change.
2. Or keep the allow-list and grow it by measured demand, accepting that 60% of documents will keep failing on their class.

Option 1 is the only one where "a student opens their existing document and it works" is reachable. Worth an explicit decision before more per-package lanes are spent.

Cheapest concrete win meanwhile

titlesec + tabularx + \input fallback to system files makes Jake's Resume — 705 forks — render. That is a self-contained lane.

Found by real-user corpus testing (163 documents: 100 student-facing templates, guides, package manuals and lecture notes; 63 papers and theses).

[d-q222]

Commander (daniel-parent): a note for whoever rules on this, because the ground is shifting under the question while it waits.

This issue asks a Tier-1 question — should FlashTeX read .cls/.sty files, or keep growing a built-in allow-list? It is flagged to the owner and I have deliberately not dispatched it.

But the allow-list branch is being built anyway, one package at a time, by work that is individually reasonable:

• muse/jakes-resume implements \titleformat/\titlerule from titlesec and cites this issue (FlashTeX never reads a .cls or .sty — 60% of real documents open with a class it cannot parse #905).
• compiler: etoolbox toggle booleans (\newtoggle, \iftoggle, \toggletrue/false) #929 landed etoolbox's \newtoggle/\iftoggle family.
• muse/calc-package adds calc +/- dimension chains.
• compiler: iftex/ifxetex/ifluatex engine guards, fontspec vocabulary #920 added iftex/ifxetex/ifluatex shims.
• Merged earlier: csquotes (\enquote), cancel.

None of these is wrong, and I am not blocking any of them — each is a real user-facing gap, each was measured against pdflatex, and users benefit today regardless of how the architecture question resolves.

The thing to be aware of when ruling: every package implemented this way raises the switching cost of the read-the-.sty option, and none of them reduces it. If the eventual answer is "read the files", a good deal of this becomes redundant code we still have to maintain and keep consistent with the real package's semantics. If the answer is "keep the allow-list", then this is exactly the right work and should be accelerated, not merely tolerated.

What makes the question urgent rather than academic is the measurement in #837: 41 of 63 real documents open with a class that has zero measured class-macro coverage, and coverage.md reports tikz at 0/43 while tikz appears in 21 of 63. The allow-list is being extended in the direction of packages while the unmeasured gap is largely in classes — which is the part an allow-list scales worst against, since every class bundles its own \RequirePackage set.

I am not asking for a decision inside this comment, and I am not slowing the package work while it waits. I am recording that the cost of deferring is not zero and is accruing in a specific direction, so the ruling can be made with that visible rather than discovered afterwards.

🤖 Generated with Claude Code

[jay3332]

Owner's ruling (relayed verbatim from the user, 2026-09-19, by mac-claude-a):

Looking forward, there should be an elegant way for the following:

• packaging/library management, as well as creating your own libraries. It should be backwards compatible with standard LaTeX distributions but it should have modern packaging/build features such as .toml config, automatic package resolution (such as typst when it sees @Preview), etc.
• fonts. support using any font on the computer, including for math. have the same flexibility as typst.
  • having fonts has packages just makes no sense. it should still be backwards compatible, but it should just have a "good" font system like typst, where you can e.g. set font settings globally, locally, etc
• obviously, we fully support custom .sty and .cls files.

So the Tier-1 answer is read the files. The built-in package models stay as typesetting semantics and fast paths (a .sty cannot teach the layout engine to draw a tcolorbox); a project-local file of the same name wins, as in LaTeX. Direction, decisions and four slices with acceptance criteria are in docs/proposals/packages-fonts-manifest.md (main 4acae1c65):

• S1 read project-local .sty/.cls through the expansion engine (resolver + the package/class kernel macros: \ProvidesPackage, \DeclareOption, \ProcessOptions, \LoadClass, \RequirePackage, \PassOptionsToPackage, \@ifpackageloaded, …). Starting now on this machine (compiler + tex-expansion; will rebase over compiler + tex-expansion: scope user-defined environment bodies as real groups (#928) #950/tex-expansion: keep the invocation origin across \futurelet lookahead for optional-argument macros (#925) #946).
• S2 flashtex.toml manifest (entry, texinputs, fonts, package policy) — platform-free crate + CLI + Mac app.
• S3 package resolution into a per-user cache from a registry (CTAN layout first), consent-gated, project layer only.
• S4 fonts: discovery crate + fontspec/unicode-math-shaped commands; the OpenType MATH half is math-layout's — design contract first, then Daniel's queue.

Package-by-package work already in flight (titlesec, calc, etoolbox, iftex) stays useful as typesetting semantics; nothing there is blocked.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Y1nAv4pEnmMYXgteBoadHn