Skip to content

CLAUDE.md

Latest commit

 

History

History
81 lines (54 loc) · 4.31 KB

CLAUDE.md

File metadata and controls

81 lines (54 loc) · 4.31 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

About

iosMath is a native iOS/macOS Objective-C library that renders LaTeX math equations using CoreText — no WebView required. It implements the TeX typesetting algorithm on top of OpenType math fonts.

Build & Test Commands

Swift Package Manager:

swift build
swift test

iOS tests (Xcode):

xcodebuild test -project iosMath.xcodeproj -scheme iosMath -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 16'

macOS tests (Xcode):

xcodebuild test -project MacOSMath.xcodeproj -scheme MacOSMath -sdk macosx

Run a single test class:

xcodebuild test -project iosMath.xcodeproj -scheme iosMath -sdk iphonesimulator \
  -destination 'platform=iOS Simulator,name=iPhone 16' \
  -only-testing:iosMathTests/MTMathListBuilderTest

Architecture

Rendering Pipeline

LaTeX string → MTMathListBuilder (parser) → MTMathList (atom tree) → MTTypesetter (layout engine) → MTMathListDisplay (positioned glyphs) → CoreText/CoreGraphics → UIView/NSView

Key Components

iosMath/lib/ — Parsing and data model:

  • MTMathListBuilder — Parses LaTeX strings into an MTMathList. This is the entry point for all LaTeX input.
  • MTMathList / MTMathAtom — The intermediate representation. Math is modeled as a linked list of typed atoms (fraction, radical, inner, accent, etc.).
  • MTMathAtomFactory — Maps LaTeX commands (e.g. \sin, \alpha, \frac) to their corresponding atoms and Unicode code points. Also owns the stack-command table that backs MTMathStack (the generic over/under atom used for \overrightarrow, \overbrace, and relatives).

iosMath/render/ — Layout and display:

  • MTMathUILabel — The public-facing UIView/NSView subclass. Users instantiate this and set its latex property.
  • MTTypesetter — The core layout engine (~80KB). Implements TeX's box-and-glue algorithm using the OpenType MATH table metrics. This is the most complex file in the codebase.
  • MTMathListDisplay — A tree of display objects produced by MTTypesetter, each positioned with a position point. draw: renders them via CoreText.
  • MTFont / MTFontManager — Wraps CoreText CTFont. Three math fonts are bundled: Latin Modern Math, Tex Gyre Termes, XITS Math.
  • MTFontMathTable — Reads the OpenType MATH table from font files (via .plist sidecar files in fonts/) to get metrics like italic corrections, kern values, and style script constants.

iosMath/render/internal/ — Private headers not exposed in the public API.

iosMath/render/MTConfig.h — Platform abstraction macros (TARGET_OS_IPHONE) that map UIView/NSView, UIColor/NSColor, UIFont/NSFont, etc. to a single set of macros used throughout the render layer.

Font System

Fonts are stored as .otf files under fonts/. Each font has a corresponding .plist file containing the pre-parsed OpenType MATH table data (generated by math_table_to_plist.py). MTFontMathTable reads from these plists at runtime rather than parsing the binary font table directly. When adding a new font, run the Python script to generate its plist.

Platform Support

The same source files compile for both iOS and macOS. Platform differences are handled via MTConfig.h macros and a small set of category files (NSColor+HexString, NSView+backgroundColor, NSBezierPath+addLineToPoint) that exist only for macOS to provide UIKit-compatible APIs.

Public API Surface

Defined by iosMath/module.modulemap. Exports: MTMathUILabel, MTMathListDisplay, MTMathList, MTMathListBuilder, MTFont, MTFontManager, MTMathAtomFactory, MTMathListIndex.

Tests

Test files are in iosMathTests/:

  • MTMathListBuilderTest.m — Parser correctness (LaTeX → atom type/value)
  • MTMathListTest.m — MTMathList data structure behavior
  • MTTypesetterTest.m — Layout output (position, glyph run) validation

Tests use XCTest. There are no third-party test dependencies.

Algorithm Reference

For a detailed mapping of TeX's Appendix G math typesetting algorithm onto iosMath's pipeline (rule-by-rule implementation status, font-parameter correspondence, known gaps, and an audit checklist), see ALGORITHM.md.