Crate fmd_math 

fmd-math — the clean-room TeX-mathematics layout engine

A math-layout engine in the KaTeX/Typst class, not a TeX macro processor: the TeX mathematics grammar as actually used, TeX’s published layout rules (the eight atom classes, the inter-atom spacing table, display/text/script/scriptscript style propagation), and — with the placement beads — Appendix-G construction mathematics over metrics calibrated for the bundled faces.

This crate is contributed and consumed by the franken_manim program (its Scribe subsystem typesets Tex/TexText through it; see that repo’s UPSTREAM_LEDGER.md row 2) and serves fmd’s own native $…$ mathematics. The public API is frozen to the shape recorded in franken_manim’s docs/g0/G0-3-fmd-math-ratification.md until its G2 gate.

The pipeline

source &str
  → parse           tokens → Node tree; EVERY node carries its byte span
  → classify        the eight atom classes; Bin→Ord degradation in context
  → layout(Ctx)     style (D/T/S/SS × cramped) threaded top-down;
                    Appendix-G constructions build boxes bottom-up
  → Layout          positioned {glyphs, rules, drawn paths}, each glyph
                    naming its FACE and carrying its source span

This crate release carries the front of the pipeline: parse / parse_text, the atom engine (atom), the style machinery (style), and the fixed node model plus output types (Layout and friends). Engine::new(faces…) / typeset land with the placement bead on exactly these shapes.

Modes

parse reads a whole string as mathematics (the Tex surface; & and \\ are legal at top level because the Reference wraps whole strings in an align*-class environment). parse_text reads the TexText contract: a text mainland with $…$ math islands, \textbf/\emph/\underline, and the escape set.

Fragment tolerance (per-argument SingleStringTex semantics)

The Tex surface’s multi-argument idiom makes each literal argument its own string, so a string may legitimately be a piece of a balanced whole ("{a", "\over", "b}", "\left(", "a^"). The grammar therefore (a) lets end of input close whatever is open — groups, \left, $ islands, arguments still to come (they become empty lists) — and (b) accepts, at the top level, an unmatched }, a stray \right, or a redundant $ as an explicit node::FragmentKind marker, never silently. Mid-string structural faults (wrong closer, double scripts, & in prose) remain precise errors. In text mode, the Reference-era LaTeX missing-$ recovery is kept deliberately: a self-contained math command or a bare script in the mainland becomes an explicit implicit NodeKind::MathIsland, and $$…$$ display mathematics is recognized.

The span map (§11.3)

Every output primitive carries its source byte span, exactly: text-run characters per character, primes per ' token, command-produced glyphs the producing command’s span (the expansion site). The spanmap module turns that provenance into the consumption surface: spanmap::find_occurrences + Layout::select (containment semantics) is the native replacement for the Reference’s render-twice-and-align hack — isolate, tex_to_color_map, substring slicing, and TransformMatchingTex match by source identity.

The error contract (the coverage ratchet’s unit)

There is deliberately no fallback typesetter, so coverage discipline replaces fallback discipline: an unsupported construct is a precise, named error (MathError::UnsupportedCommand with the construct’s G0-4 table name and a tier tag in its message), and arbitrary input errors cleanly — never hangs, never garbles, never panics (the chaos suite locks this). construct_status answers, for any construct in the table’s naming scheme, whether the parse surface supports it.

Re-exports

pub use commands::ConstructStatus;

pub use commands::LAYOUT_PENDING_TRACKING;

pub use commands::TIER2_TRACKING;

pub use commands::Tier;

pub use commands::UNTIERED_TRACKING;

pub use commands::construct_status;

pub use faces::FaceSet;

pub use macros::MacroSet;

pub use mathml::mathml_well_formed;

pub use mathml::to_mathml;

pub use mathml::to_mathml_element;

pub use mathml::to_mathml_with_capacity;

pub use metrics::MathConstants;

pub use node::Node;

pub use node::NodeKind;

pub use node::Span;

pub use spanmap::Selection;

pub use spanmap::find_occurrences;

pub use style::Style;

pub use style::StyleCtx;

pub use style::style_walk;

Modules

atom

The atom engine: TeX’s eight atom classes, contextual Bin→Ord degradation, and the inter-atom spacing table.

commands

The command registry: every control word and environment the tier-1 surface knows, each with its parse behavior, plus the known tier-2 vocabulary so unsupported constructs fail as precise, named, tier-tagged errors (the coverage ratchet’s unit — G0-4’s normative counting rules).

faces

Face management: the engine’s face roster, character→glyph resolution with the TeX math-italic convention and the math-alphabet mappings, and glyph-metric queries in em units.

macros

User macros and preamble packs: \newcommand-tier non-recursive substitution, expanded at the token level before parsing (§11.4).

mathml

Node-tree → MathML Core serializer.

metrics

The math-metrics table: TeX’s Appendix-G parameter family, synthesized for the bundled faces.

node

The parse tree: Node and its supporting vocabulary.

paths

Output paths: resolve a Layout into pure quadratic contours, and dump them canonically for goldens.

spanmap

The span map (§11.3): querying a Layout by source provenance.

style

TeX’s four math styles, cramping, and the propagation rules.

Structs

Engine

The layout engine: a face roster plus the calibrated math constants.

FaceId

Identifies one of the faces handed to the engine (an index into the engine’s face list, in construction order). Multi-face layout is structural: face selection is data on every glyph, never a rendering afterthought.

Layout

The final layout of a formula: flat positioned primitives plus overall metrics. Everything is in ems of the base size, y-up, baseline at 0; width spans the whole formula, height rises above the baseline, depth extends below it (a positive number).

PathContour

One closed contour of a drawn path: a start point plus segments; the contour closes back to the start implicitly.

PlacedGlyph

A positioned glyph in the final layout. Units are ems of the base (text-style) size; y is the baseline-relative vertical position, positive up; size is the glyph’s own size factor (1.0 / 0.7 / 0.5 per style).

PlacedPath

A positioned drawn-path construction (parametric delimiters past the glyph-scaling threshold, the drawn radical, braces): quadratic contours in ems, y-up, the same path model franken_manim’s geometry kernel and fmd-font outlines share.

PlacedRule

A positioned rectangular rule (fraction bars, \overlines, radical overbars). x/y name the rule’s left-bottom corner in ems, y-up.

Enums

MathError

Why a source string failed to parse (or, later, to lay out).

PathSeg

One segment of a drawn-path contour.

Functions

parse

Parse a whole source string as mathematics (the Tex surface). The result is a NodeKind::List node spanning the whole input; every descendant carries its byte span.

parse_text

Parse a whole source string under the TexText contract: a text mainland with $…$ math islands.

parse_text_with_macros

parse_text, against a macro set.

parse_with_macros

parse, against a macro set (a preamble pack and/or caller definitions): calls expand at the token level before the grammar runs, with body-produced tokens carrying their call site’s span (see macros).