Rule API Reference

This section documents the supported extension surface assembled through src/rules.ts. Use it as a lookup after choosing an extension point; the Rendering Rules Tutorial is the guided starting point.

These are contributor APIs compiled into SnapTeX, not commands imported by a .tex project and not a published npm plugin surface. Read Source API Scope first for exact code location, import paths, callback ownership, output safety, and the minimum test harness. Then use Call Relationships to see where an API runs.

Find the API by task

Goal	Start here
Understand where API code belongs and who supplies callback values	Source API Scope
Assemble a complete custom registry	defineRuleRegistry
Add a source-text rendering rule	Legacy rule contract
Add a structural AST rendering rule	AST rule contract
Handle a selected command nested inside AST math	defineAstMathRule
Read balanced LaTeX commands or groups	replaceLatexCommandCalls or readLatexCommandAt
Produce safe inline HTML	renderInlineLatexHtml
Extract custom preamble metadata	Metadata contract
Re-render a block when external state changes	BlockDependencyRule
Change block splitting behavior	Splitter contract
Test a registry through the real document pipeline	PreviewUpdateService

Recognize who owns a function

The spelling of a signature tells you how it reaches your code:

Signature shape	What you do	Who supplies the arguments
function escapeHtml(text)	Import and call the helper	Your code supplies every argument
apply(text, renderer)	Implement this property on a PreprocessRule	SmartRenderer calls it
(input, context) => result	Pass this function to defineAstRenderRule	The AST walker calls it
apply(input, context) on AstMathRule	Pass the object to defineAstMathRule	The AST math renderer calls it for matching commands
renderer.protectHtml(...)	Call a method on the received legacy context	SmartRenderer created renderer
input.renderChildren(...)	Call a method on the received AST input	The AST walker created input
context.renderMath(...)	Call a method on the received AST context	The AST renderer created context

A declaration helper such as defineAstRenderRule(...) provides typing but does not register or execute the rule. Execution starts only after the returned callback appears in the matching SNAP_TEX_RULES array.

Follow values through the pipeline

src/rules.ts declaration
  -> SNAP_TEX_RULES registration
  -> parser/renderer calls your callback
  -> callback uses imported helpers and injected context methods
  -> callback returns transformed source, HTML, metadata, or dependencies
  -> the owning service consumes that return value

Each API page identifies the caller and the next consumer under Call relationships. This distinction matters: returning HTML from an AST rule is final, while returning HTML-looking text from a legacy rule is unsafe unless it has first passed through renderer.protectHtml.

API categories

• Registry functions assemble and type-check extension definitions.
• Legacy context exposes output protection, inline rendering, and citation state to PreprocessRule.
• Source readers safely read balanced LaTeX syntax without ad hoc regular expressions.
• Rendering functions escape output and render inline LaTeX or KaTeX.
• AST functions inspect structural nodes and render their source or children.
• Metadata and dependency functions extract document state and declare block invalidation inputs.
• Testing API exercises a registry through parsing, diffing, scanning, and rendering.

Function index

Category	Functions and methods
Registry	defineRuleRegistry, defineAstRenderRule, defineAstMathRule, defineBlockDependencyRule
Legacy	apply, protectHtml, renderInline, resolveCitation, getCitedKeys
Source	replaceLatexCommandCalls, readLatexGroup, readLatexCommandAt, skipLatexWhitespace, stripLatexComments
Rendering	escapeHtml, renderMath, renderInlineLatexHtml
AST	render, readAstCommandArguments, node readers, context methods
Metadata and dependencies	extract, readMetadataCommand, collect, deps.metadata, deps.citedKeys
Testing	PreviewUpdateService, render, renderBlockByIndex, query methods

Supported boundary

The reference intentionally covers the APIs used to extend SNAP_TEX_RULES. Internal exports used only by SnapTeX implementation modules are not presented as stable extension contracts.

The legacy and AST backends are independent execution paths. A custom rule may target either backend; developers are not required to implement the same feature twice.

If an exported helper is absent from this reference, treat it as internal implementation rather than a supported extension contract. Internal APIs may still be reused by built-in modules, but extension documentation and compatibility promises do not follow them automatically.

Definition locations

Area	Source
Registry and default rules	src/rules.ts
Shared rule types	src/types.ts
Balanced source readers	src/utils.ts
Rendering helpers	src/rule-helpers.ts
AST rule contracts	src/ast/rules/index.ts
AST node readers	src/ast/visit-utils.ts
Metadata extraction	src/metadata.ts
End-to-end update service	src/preview-update-service.ts

Continue with the Rendering Rules Tutorial for a guided implementation.