How stefnotch/aftermath-editor works
1. Overall shape
- This is a monorepo for a browser-based math editor called Aftermath Editor.
- The architecture is split between a TypeScript frontend/component layer and a Rust core under aftermath-core.
- The browser ultimately renders formulas using native MathML Core rather than a custom canvas or SVG renderer.
2. Primary runtime boundary
- The user-facing runtime is the web app/component in src/, built with Vite and standard browser APIs.
- The Rust crates in aftermath-core/ contain the editor’s reusable core logic, parser, caret/input logic, and web-facing glue.
- The repo suggests a “core logic + browser shell” structure, with tests for both sides.
3. Input and editing subsystem
- src/component/input/ and src/component/caret/ handle keyboard/mouse interaction, caret placement, and autocomplete-triggered editing behavior.
- The Rust caret crate mirrors this responsibility with movement, selection, undo/redo, and primitive edit operations.
- This boundary is important: raw DOM events are translated into model edits rather than manipulating displayed math directly.
4. Editing tree / structural model
- src/input-tree/ and Rust input_tree are the editable tree representation of the formula.
- It is the “authoring” model: designed for cursor movement, row positions, focus, ranges, and localized edits.
- The tree is more editing-friendly than MathML or syntax trees, and it acts as the first durable model after user input.
5. Semantic parsing subsystem
- The parser lives in src/mathml/parsing.ts on the TypeScript side and in the Rust parser crate.
- The parser turns the editable structure into a concrete syntax tree with mathematical meaning.
- The parser is rule-driven: parse_rules and Rust rule_collections/* define arithmetic, calculus, comparison, logic, strings, collections, and core built-ins.
6. Parsing strategy and extensibility
- The Rust parser includes specialized parsing machinery such as pratt_parser, greedy_choice, parser_extensions, and autocomplete support.
- This indicates the editor is not just tokenizing text; it applies grammar/precedence rules and semantic disambiguation.
- The architecture supports domain-specific interpretation, which matches the project goal of understanding formulas rather than accepting arbitrary LaTeX-like text.
7. Autocomplete and editor intelligence
- Autocomplete exists at both editor and parser layers: src/component/autocomplete/, src/component/caret/caret-autocomplete.ts, and Rust autocomplete.rs.
- This is a cross-cutting concern tied to syntax knowledge and cursor position.
- The autocomplete boundary likely consumes parser metadata and rule collections, then feeds suggestions back into the input/caret layer.
8. Rendering pipeline
- After parsing, the formula is rendered into MathML in src/mathml/renderer/ and related files.
- Rendered nodes include containers, rows, tables, symbols, text, missing nodes, and root elements.
- The Rust web crate also contains MathML-related code, suggesting shared or mirrored rendering/support logic for the browser-facing build.
9. Display and layout concerns
- src/rendering/ handles rendered output concerns such as selection overlays and viewport coordinates.
- This layer is separate from semantic parsing: it deals with how the formula is shown, selected, and positioned in the browser.
- The presence of rendered-selection and coordinate types suggests visual feedback is computed against the rendered tree, not the raw input tree.
10. Shared utilities and support code
- src/utils/ contains low-level helpers for DOM, assertions, memoization, error handling, and pattern matching.
- These are supporting pieces rather than major architecture layers, but they stabilize the browser component and rendering logic.
- The root public/, index.html, and style.css indicate a conventional static frontend packaging path.
11. Rust crate layout
- aftermath-core is a multi-crate Rust workspace with distinct modules for input tree, caret, parser, parse rules, serialization, and web integration.
- This separation suggests the core logic is intended to be reusable and testable independently of the browser UI.
- The serialization crate likely provides persistence/export of editor state or syntax trees across boundaries.
12. Data flow to diagram
- The main flow is: browser events → input/caret handling → editable tree mutation → parsing into syntax tree → MathML rendering → browser display.
- A secondary flow is: cursor/focus changes → autocomplete/suggestions → tree edits.
- A third flow is: core model state → serialization/export, with tests validating each stage.
13. Testing and quality boundaries
- Both the TypeScript and Rust parts include tests, especially around input focus, row indices, parsing, autocomplete, and selection behavior.
- This is useful for architecture diagrams because the repo’s correctness is heavily enforced at the model boundaries rather than only at the UI boundary.
14. What is not present
- There is no evidence of a server backend, database, or remote API as a central runtime dependency.
- The core architecture is client-side and library-oriented, with browser-native rendering and local model transformations.
Main entry points: math-editor.ts Editor shell · Cargo.toml Core workspace · lib.rs Parser core · input-handler-element.ts Input layer
Components 17
TypeScript app
Browser-facing editor shell and MathML rendering pipeline
- App entry · Starts the browser editor runtime
src/main.ts - Editor shell · Top-level math editor component and styling boundary
src/component/math-editor.ts - Input layer · Captures keyboard and mouse input for editing
src/component/input/input-handler-element.ts - Caret layer · Coordinates caret movement, selection, and edit intent
src/component/caret/single-caret-element.ts - Autocomplete UI · Displays completion candidates and editor assistance
src/component/autocomplete/autocomplete-element.ts - Input tree · Editing-friendly tree and row/index helpers
src/input-tree/input-offset.ts - Parser · Transforms the editable structure into MathML-oriented semantics
src/mathml/parsing.ts - MathML render · Builds native MathML output from parsed math
src/mathml/renderer.ts - Display layer · Selection overlays and viewport coordinate handling
src/rendering/rendered-selection.ts
Rust core
Reusable editing, parsing, and browser glue crates
- Core workspace · Workspace boundary for reusable editor logic
aftermath-core/Cargo.toml - Input tree core · Editable structural model with focus, ranges, and grid positions
aftermath-core/input_tree/src/lib.rs - Caret core · Cursor movement, selection, undo/redo, and primitive edits
aftermath-core/caret/src/lib.rs - Parser core · Rule-driven parser that builds concrete syntax trees
aftermath-core/parser/src/lib.rs - Rule sets · Arithmetic, calculus, logic, strings, collections, and core rules
aftermath-core/parser/src/rule_collections.rs - Autocomplete core · Parser-aware completion logic for editor assistance
aftermath-core/parser/src/autocomplete.rs - Web bridge · Rust-side web integration and MathML-facing support
aftermath-core/web/src/lib.rs - Serialization · State and structure serialization across boundaries
aftermath-core/serialization/src/lib.rs
Connections 21
- App entry → Editor shell: mounts · Bootstraps the editor component in the browser
- Editor shell → Input layer: captures input · Hosts keyboard and mouse event handling
- Editor shell → Caret layer: drives caret · Coordinates caret and selection interactions
- Editor shell → Autocomplete UI: shows suggestions · Renders completion UI from editor state
- Input layer → Input tree: edits model · Converts raw DOM events into tree mutations
- Caret layer → Input tree: navigates · Uses row positions, focus, and ranges for movement
- Caret layer → Autocomplete UI: requests hints · Triggers completion based on cursor context
- Input tree → Parser: feeds parse · Authoring tree is transformed into semantic structure
- Parser → MathML render: renders · Produces MathML-oriented renderable output
- MathML render → Display layer: positions display · Selection and viewport data are applied to rendered output
- Input layer → Core workspace: bridges to core · Browser shell relies on shared Rust logic through the core workspace
- Core workspace → Input tree core: includes model · Workspace contains the editable tree crate
- Core workspace → Caret core: includes editing · Workspace contains caret and edit operations
- Core workspace → Parser core: includes parser · Workspace contains syntax parsing
- Parser core → Rule sets: applies rules · Parser is driven by rule collections and precedence machinery
- Parser core → Autocomplete core: powers hints · Parser metadata supports autocomplete suggestions
- Caret core → Input tree core: mutates tree · Caret layer performs primitive edits on the input model
- Web bridge → MathML render: supports browser build · Web crate contains MathML-facing glue for the browser runtime
- Serialization → Input tree core: persists state · Serializes editor model structures and exported state
- Serialization → Parser core: exports syntax · Supports persistence of parsed or derived structures
- Autocomplete core → Caret core: feeds suggestions · Core completion logic informs editing behavior