Legacy Rule Contract

How to read this API

These are TypeScript APIs compiled into SnapTeX; a .tex project cannot load them at runtime.

• function name(...) is a helper that your rule imports and calls.
• apply(...), render(...), extract(...), and collect(...) are callbacks that your rule implements and SnapTeX calls.
• renderer.name(...), context.name(...), input.name(...), and deps.name(...) are methods SnapTeX supplies to callbacks; do not import or construct them.
• service.name(...) is an instance method called after your host or test constructs PreviewUpdateService.

Register extension declarations through SNAP_TEX_RULES in src/rules.ts. See Source API Scope for imports, value ownership, output safety, rebuilds, and testing.

A PreprocessRule transforms one block of LaTeX source before Markdown rendering. Use it when the legacy backend can recognize the feature from source text without structural AST traversal.

interface PreprocessRule {
    priority: number;
    apply(text: string, renderer: RenderContext): string;
}

Lifecycle

1. defineRuleRegistry sorts legacy rules by ascending priority.
2. SmartRenderer passes the current block through every apply callback.
3. Markdown-it renders the transformed text with raw HTML disabled.
4. SnapTeX restores HTML registered with renderer.protectHtml.

The callback's return value is therefore usually one of three forms:

Return shape	Use
Unchanged text	The rule does not apply
Transformed LaTeX/Markdown-compatible text	A later rule or Markdown should continue processing it
Text containing protected tokens	The rule generated trusted HTML that must survive Markdown

const RULE: PreprocessRule = {
    priority: 200,
    apply: (text, _renderer) => /* transformed text */ text
};

The _renderer parameter is present because SnapTeX always supplies the full apply(text, renderer) interface. Its underscore only says that this minimal example does not use the context.

RenderContext

Member	Purpose
currentMacros	Current KaTeX macro definitions
metadata	Parsed document metadata, when available
bibEntries	Current bibliography entries
PreprocessRule.apply	Transform one block in the legacy rule sequence
protectHtml	Hide trusted generated HTML from Markdown
renderInline	Run Markdown inline rendering
resolveCitation	Assign or reuse a citation number
getCitedKeys	Read citation keys seen so far

Legacy rules operate on source text and therefore commonly use the balanced source readers. They do not receive AST nodes and do not run in AST mode.

priority controls ordering; it does not select commands. Source matching belongs inside apply, normally through replaceLatexCommandCalls or another shared reader.

Related APIs

• Rendering Rules Tutorial
• replaceLatexCommandCalls
• renderInlineLatexHtml
• Call Relationships