Module macros 

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

The model

A MacroSet is a named table of substitution macros — either a preamble pack (the tex_templates.yml concept reborn: a macro/symbol bundle selected by config, looked up here by its stable content id) or definitions a consumer assembles. Source strings may additionally define macros inline with \newcommand{\name}[n]{body} / \renewcommand; inline definitions layer over the pack (\newcommand refuses to shadow an existing name, \renewcommand requires one — LaTeX’s own rules). An inline definition may supply [n][default]: the first argument is then optional at each call, and the remaining n - 1 are mandatory. Explicit [] is an empty argument, not a request to use the default.

Expansion is token-level, before the grammar: a macro call’s arguments are collected as balanced token groups (or single tokens, the TeX undelimited-argument rule), the body’s #k parameters splice the argument tokens in, and the result is rescanned so macros may reference other macros. Two disciplines make this safe under the parser-budget doctrine (§16.5):

• Recursion is refused, by name: a macro that re-enters its own expansion — directly, through another macro, or through an argument — is a precise MathError::Malformed naming the macro, never a hang.
• Expansion is budgeted: token-copy and substitution work, including intermediate replacements that disappear during rescanning, and nesting depth are capped. Visible and empty-output fan-out bombs error cleanly.

Provenance (§11.3)

Body-produced tokens carry the call site’s span (the expansion site — exactly the rule command-produced glyphs already follow), while argument tokens keep their own source spans (they are real source text). Omitted optional arguments come from the definition and are rebased to the call, just like body material. isolate and tex_to_color_map therefore keep working through macros.

Cache identity

MacroSet::canonical_bytes is a deterministic serialization of the whole table (sorted, delimited, versioned). Consumers fold it into their typeset cache keys, so a pack change re-typesets, correctly — the §14.4 requirement. Inline defaults are part of the source string; no optional-argument state persists between parse calls.

Structs

MacroSet

A named table of \newcommand-tier substitution macros. See the module docs for the expansion, provenance, and budget rules.