# stefnotch/aftermath-editor architecture

> Architecture diagram of the GitHub repository stefnotch/aftermath-editor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stefnotch/aftermath-editor
- Repository: https://github.com/stefnotch/aftermath-editor

## Overview

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: [`src/component/math-editor.ts`](https://github.com/stefnotch/aftermath-editor/blob/main/src/component/math-editor.ts) (Editor shell), [`aftermath-core/Cargo.toml`](https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/Cargo.toml) (Core workspace), [`aftermath-core/parser/src/lib.rs`](https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/parser/src/lib.rs) (Parser core), [`src/component/input/input-handler-element.ts`](https://github.com/stefnotch/aftermath-editor/blob/main/src/component/input/input-handler-element.ts) (Input layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["TypeScript app"]
  node_app_entry["App entry<br/>Vite bootstrap<br/>[main.ts]"]
  node_editor_shell["Editor shell<br/>component host<br/>[math-editor.ts]"]
  node_input_layer["Input layer<br/>DOM events"]
  node_caret_layer(("Caret layer<br/>cursor control"))
  node_autocomplete_layer["Autocomplete UI<br/>suggestion UI"]
  node_input_tree_ts["Input tree<br/>authoring model<br/>[input-offset.ts]"]
  node_parse_layer["Parser<br/>semantic parsing<br/>[parsing.ts]"]
  node_render_layer["MathML render<br/>browser renderer<br/>[renderer.ts]"]
  node_display_layer["Display layer<br/>viewport/selection"]
end

subgraph group_core["Rust core"]
  node_core_workspace["Core workspace<br/>Rust workspace<br/>[Cargo.toml]"]
  node_rust_input_tree["Input tree core<br/>editable model<br/>[lib.rs]"]
  node_rust_caret(("Caret core<br/>editing engine<br/>[lib.rs]"))
  node_rust_parser["Parser core<br/>syntax parser<br/>[lib.rs]"]
  node_rust_rules["Rule sets<br/>parse rules"]
  node_rust_autocomplete["Autocomplete core<br/>completion engine<br/>[autocomplete.rs]"]
  node_rust_web["Web bridge<br/>browser glue<br/>[lib.rs]"]
  node_serialization["Serialization<br/>persistence<br/>[lib.rs]"]
end

node_app_entry -->|"mounts"| node_editor_shell
node_editor_shell -->|"captures input"| node_input_layer
node_editor_shell -->|"drives caret"| node_caret_layer
node_editor_shell -->|"shows suggestions"| node_autocomplete_layer
node_input_layer -->|"edits model"| node_input_tree_ts
node_caret_layer -->|"navigates"| node_input_tree_ts
node_caret_layer -->|"requests hints"| node_autocomplete_layer
node_input_tree_ts -->|"feeds parse"| node_parse_layer
node_parse_layer -->|"renders"| node_render_layer
node_render_layer -->|"positions display"| node_display_layer
node_input_layer -.->|"bridges to core"| node_core_workspace
node_core_workspace -->|"includes model"| node_rust_input_tree
node_core_workspace -->|"includes editing"| node_rust_caret
node_core_workspace -->|"includes parser"| node_rust_parser
node_rust_parser -->|"applies rules"| node_rust_rules
node_rust_parser -->|"powers hints"| node_rust_autocomplete
node_rust_caret -->|"mutates tree"| node_rust_input_tree
node_rust_web -.->|"supports browser build"| node_render_layer
node_serialization -->|"persists state"| node_rust_input_tree
node_serialization -.->|"exports syntax"| node_rust_parser
node_rust_autocomplete -->|"feeds suggestions"| node_rust_caret

click node_app_entry "https://github.com/stefnotch/aftermath-editor/blob/main/src/main.ts"
click node_editor_shell "https://github.com/stefnotch/aftermath-editor/blob/main/src/component/math-editor.ts"
click node_input_layer "https://github.com/stefnotch/aftermath-editor/blob/main/src/component/input/input-handler-element.ts"
click node_caret_layer "https://github.com/stefnotch/aftermath-editor/blob/main/src/component/caret/single-caret-element.ts"
click node_autocomplete_layer "https://github.com/stefnotch/aftermath-editor/blob/main/src/component/autocomplete/autocomplete-element.ts"
click node_input_tree_ts "https://github.com/stefnotch/aftermath-editor/blob/main/src/input-tree/input-offset.ts"
click node_parse_layer "https://github.com/stefnotch/aftermath-editor/blob/main/src/mathml/parsing.ts"
click node_render_layer "https://github.com/stefnotch/aftermath-editor/blob/main/src/mathml/renderer.ts"
click node_display_layer "https://github.com/stefnotch/aftermath-editor/blob/main/src/rendering/rendered-selection.ts"
click node_core_workspace "https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/Cargo.toml"
click node_rust_input_tree "https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/input_tree/src/lib.rs"
click node_rust_caret "https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/caret/src/lib.rs"
click node_rust_parser "https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/parser/src/lib.rs"
click node_rust_rules "https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/parser/src/rule_collections.rs"
click node_rust_autocomplete "https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/parser/src/autocomplete.rs"
click node_rust_web "https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/web/src/lib.rs"
click node_serialization "https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/serialization/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_entry,node_editor_shell,node_input_layer,node_caret_layer,node_autocomplete_layer,node_input_tree_ts,node_parse_layer,node_render_layer,node_display_layer toneBlue
class node_core_workspace,node_rust_input_tree,node_rust_caret,node_rust_parser,node_rust_rules,node_rust_autocomplete,node_rust_web,node_serialization toneAmber
```

## Components

### TypeScript app

Browser-facing editor shell and MathML rendering pipeline

- [App entry](https://github.com/stefnotch/aftermath-editor/blob/main/src/main.ts): Vite bootstrap · Starts the browser editor runtime · `src/main.ts`
- [Editor shell](https://github.com/stefnotch/aftermath-editor/blob/main/src/component/math-editor.ts): component host · Top-level math editor component and styling boundary · `src/component/math-editor.ts`
- [Input layer](https://github.com/stefnotch/aftermath-editor/blob/main/src/component/input/input-handler-element.ts): DOM events · Captures keyboard and mouse input for editing · `src/component/input/input-handler-element.ts`
- [Caret layer](https://github.com/stefnotch/aftermath-editor/blob/main/src/component/caret/single-caret-element.ts): cursor control · Coordinates caret movement, selection, and edit intent · `src/component/caret/single-caret-element.ts`
- [Autocomplete UI](https://github.com/stefnotch/aftermath-editor/blob/main/src/component/autocomplete/autocomplete-element.ts): suggestion UI · Displays completion candidates and editor assistance · `src/component/autocomplete/autocomplete-element.ts`
- [Input tree](https://github.com/stefnotch/aftermath-editor/blob/main/src/input-tree/input-offset.ts): authoring model · Editing-friendly tree and row/index helpers · `src/input-tree/input-offset.ts`
- [Parser](https://github.com/stefnotch/aftermath-editor/blob/main/src/mathml/parsing.ts): semantic parsing · Transforms the editable structure into MathML-oriented semantics · `src/mathml/parsing.ts`
- [MathML render](https://github.com/stefnotch/aftermath-editor/blob/main/src/mathml/renderer.ts): browser renderer · Builds native MathML output from parsed math · `src/mathml/renderer.ts`
- [Display layer](https://github.com/stefnotch/aftermath-editor/blob/main/src/rendering/rendered-selection.ts): viewport/selection · Selection overlays and viewport coordinate handling · `src/rendering/rendered-selection.ts`

### Rust core

Reusable editing, parsing, and browser glue crates

- [Core workspace](https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/Cargo.toml): Rust workspace · Workspace boundary for reusable editor logic · `aftermath-core/Cargo.toml`
- [Input tree core](https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/input_tree/src/lib.rs): editable model · Editable structural model with focus, ranges, and grid positions · `aftermath-core/input_tree/src/lib.rs`
- [Caret core](https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/caret/src/lib.rs): editing engine · Cursor movement, selection, undo/redo, and primitive edits · `aftermath-core/caret/src/lib.rs`
- [Parser core](https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/parser/src/lib.rs): syntax parser · Rule-driven parser that builds concrete syntax trees · `aftermath-core/parser/src/lib.rs`
- [Rule sets](https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/parser/src/rule_collections.rs): parse rules · Arithmetic, calculus, logic, strings, collections, and core rules · `aftermath-core/parser/src/rule_collections.rs`
- [Autocomplete core](https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/parser/src/autocomplete.rs): completion engine · Parser-aware completion logic for editor assistance · `aftermath-core/parser/src/autocomplete.rs`
- [Web bridge](https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/web/src/lib.rs): browser glue · Rust-side web integration and MathML-facing support · `aftermath-core/web/src/lib.rs`
- [Serialization](https://github.com/stefnotch/aftermath-editor/blob/main/aftermath-core/serialization/src/lib.rs): persistence · State and structure serialization across boundaries · `aftermath-core/serialization/src/lib.rs`

## Connections

- 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
