summarum/ARCHITECTURE.md

Architecture

For people who want to read or change the code. The app is two parts: a TypeScript calculation engine + UI running in WebView2, and a thin Rust shell (Tauri 2) for everything OS-specific.

src/
  engine/          the calculator itself (pure TS, no DOM)
    lexer.ts         line → raw lexemes (numbers, words, symbols)
    vocab-data.ts    en+ru word tables: unit names, currencies, operators
    vocab.ts         merged lookup over the tables
    unitdata.ts      conversion ratios (base units per dimension)
    extraunits.ts    speed/pressure/energy/power/frequency/fuel + crypto list
    registry.ts      phrase → token payload; built once at startup
    tokenizer.ts     lexemes + registry → semantic tokens
    parser.ts        tokens → AST (noise-tolerant Pratt parser)
    evaluator.ts     AST + document context → values with units
    formatter.ts     values → display strings
    datetime.ts      timezone map, calendar arithmetic
    index.ts         SumEngine facade + extension API + sheet totals
  ui/
    editor.ts        CodeMirror 6 wiring: highlight, results overlay, copy
    search.ts        cross-sheet search overlay (text + result-value queries)
    export.ts        renders the sheet + results to a PNG (clipboard/file)
    sparkline.ts     SVG sparkline renderer for `chart` results
    app.css          themes (light/dark via CSS variables)
  main.ts            app bootstrap: documents, settings, status bar, dnd
  workspace.ts       cross-sheet references: exports cache, cycle detection
  storage.ts         Tauri commands / localStorage fallback
  extensions.ts      runs user .js files in a QuickJS/WASM sandbox, bridged
                     to the engine's numi.* API
  i18n.ts            interface strings (en/ru)
  updater.ts         checks tauri-plugin-updater, installs + relaunches
  logger.ts          thin console wrapper (info/warn/error)
src-tauri/
  src/main.rs        tray, hide-to-tray, storage commands, rates fetching
                     (open.er-api.com + CoinGecko + Yahoo Finance v8 chart)
                     with cache, historical rates (frankfurter.dev, permanent
                     per-date cache), backups, data-folder migration,
                     file drops, plugin registration (autostart,
                     global-shortcut, single-instance, opener, dialog,
                     updater, process)

How a line becomes a result

1. Lexer splits "5 inches in cm" into lexemes: 5, inches, in, cm. The same lexer segments vocabulary phrases, so matching is consistent.
2. Registry holds every phrase the engine knows, keyed by first lexeme. Longest match wins; case-sensitive entries (m vs M, kB) are tried before case-insensitive ones, and an ambiguous lowercase form (mm vs Mm) simply doesn't get a case-insensitive fallback.
3. Tokenizer walks the lexemes, asks the registry, and emits typed tokens. A couple of context hacks live here, e.g. in right after a number at the end of a line means inches (6 ft 3 in).
4. Parser is a Pratt parser that tolerates noise: unknown words are dropped before parsing (that's why spent 20 on pizza plus 5 works) — except words right after a conversion operator, which may name a timezone. Precedence, loosest to tightest: line-level conversions (in cm applies to the merged line, so 2 hours 30 minutes in minutes works) → bitwise → additive → multiplicative (incl. 20% of x) → unary → postfix (units, %, !, ^) → primary.
5. Evaluator computes { value: Decimal, unit } triples. Same-dimension operands convert through base units (toBase/fromBase); temperatures carry an offset, fuel economy units can be reciprocal (mpg ↔ L/100km). The document context supplies variables and previous line results for sum/avg/prev.
6. Formatter renders the value with the unit's display format, precision and grouping from settings, or as hex/binary/fraction/roman/etc.

Numbers are decimal.js throughout — no binary float artifacts.

Adding things

A unit — add a row to UNIT_DATA in unitdata.ts (id, dimension, ratio to the dimension base) and its names to vocab-data.ts under the matching category ("myunit.variants": "name,names,имя", "myunit.format": "sym"). For a brand-new dimension, extend the Dimension union in types.ts and use extraunits.ts — phrases live inline there.

A currency — fiat codes come from the Currency table in vocab-data.ts; crypto goes in CRYPTO in extraunits.ts (code, CoinGecko id, phrases, snapshot price) plus the mirror list in src-tauri/src/main.rs.

An operator/function — register the phrase in buildRegistry() (registry.ts), add a token/AST case if it needs new syntax, implement in evaluator.ts. Most word-operators are data, not code.

A timezone city — one line in the Z map in datetime.ts.

Engine gotchas

• Phrase conflicts are real: single letters are case-sensitive by design (m meter / M million, k thousand / K kelvin). Prefix generation is filtered where it collides with words — e.g. seconds only get ms/µs/ns/ps because an "attosecond" symbol would shadow the word as.
• and/or are dual-purpose: and adds (5 and 3 = 8), or is bitwise. of/off/on only act on a percent left-hand side; otherwise they're prose. The same on token doubles as the historical-rate date separator (in EUR on 2024-01-01) — parseSeq checks for pctop(on) + datelit right after a currency conv target and consumes both when present.
• Currency rates are "units per USD"; a currency Unit's ratio is computed at evaluation time from the current rate map, so re-setting rates re-prices everything on the next evaluation. Historical rates live in a separate historicalRates: Map<date, Map<code, number>> on SumEngine and are passed through EvalCtx to evalConv.
• Live market data (stocks, commodities via Yahoo Finance) is merged into the same rate map as exchange rates via applyAllRates() in main.ts to avoid one setRates() call overwriting the other.
• Goal seek (? * 1.2 = 1000) tokenizes ? as { t: "unknown" }, parsed into { k: "unknown" } nodes. parseLine detects the presence of unknown
  • assign and builds a { k: "goalseek", lhs, rhs } node. The solver tries a linear probe (f(0), f(1) → exact root for affine expressions) and falls back to bisection for nonlinear ones.
• ChartValue (kind: "chart") is returned by evalAgg("chart", …) and bypasses formatValue — the results overlay renders an SVG sparkline instead of a text string.
• The registry is rebuilt never; extensions mutate it (add phrases/functions) at startup. buildRegistry() (registry.ts) is a thin orchestrator over registerCoreVocab / registerUnits / registerAreaVolume / registerCurrencies / registerExtraUnits / registerCrypto / registerCompletions — call order matters, since Registry.addPhrase keeps the first registration of an identical phrase and drops later ones (core vocab must win over unit/currency phrases that happen to collide).
• Multiplying two same-dimension quantities (2 kg * 500 g) converts the right operand into the left operand's unit before multiplying, so the result keeps a sane unit (1 kg, not 1000 in a kg label). Cross-dimension multiplication ($12 * 3, 5 hours * 2) is unaffected — the right side is treated as a plain scale factor there.
• A // only starts a comment at the start of a line or after whitespace (findCommentStart in index.ts), so a URL like see https://example.com isn't truncated at the double slash.
• Date literals and formats. Besides ISO (2024-01-01), the lexer accepts D.M.YYYY / M/D/YYYY (31.12.2024, 12/31/2024) with the same separator on both sides and a 4-digit year. Day/month order is disambiguated per literal: a component >12 fixes which side is the day; if both are ≤12, the engine's dateFormat setting decides. All three literal forms reject out-of-range components via a round-trip check (validDateMs in lexer.ts — new Date(y, mo-1, d) silently rolls over invalid dates like 2026-13-45 instead of erroring, so the constructed date's year/month/day are compared back against the input). SumEngine resolves dateFormat: "system" to an actual day/month order once via detectDateOrder() (datetime.ts, probes Intl.DateTimeFormat on a 2000-12-31 fixture) and passes it into tokenize() → lexLine() on every call; "dmy"/"mdy" settings skip detection. Display works the same way in reverse: formatter.ts either uses the OS-locale Intl formatting ("system") or builds a fixed YYYY-MM-DD / DD.MM.YYYY / MM/DD/YYYY string via Intl.DateTimeFormat(...).formatToParts() (needed to respect the value's own IANA timezone, which a hand-rolled ms-based formatter can't do). Intl.DateTimeFormat instances are cached by options key in formatter.ts (dtf()) since constructing one is comparatively expensive and every dated line rebuilds its format on every render.
• Timezone name parsing (time in Europe/Berlin) has two independent traps. First, parseLine's noise-filter only keeps word tokens that immediately follow a conv token (in/as/...); any other token type resets that state — a bare / between two timezone words would normally drop the second word before the parser ever sees it, so the filter special-cases a / that appears while collecting post-conv words. Second, parseTarget()'s word-collecting loop mirrors that same allowance so it keeps consuming past the / instead of stopping at the first word. Both places need the exception — fixing only one still drops Europe/Berlin down to Europe.

Cross-sheet references

@Sheet.key is lexed directly in lexer.ts (not through the phrase registry — sheet titles are arbitrary user text, not vocabulary), producing an xref lexeme carrying { sheet, key }. The engine only knows how to ask for a value: EvalCtx.resolveXRef?.(sheet, key) returns { ok: true; value } | { ok: false; reason }; when no resolver is supplied (tests, extensions, evaluateExpression) an xref is simply unresolved. Unresolved xrefs throw XRefError internally, caught in SumEngine.evaluateDocument and surfaced as LineResult.error (rendered as #ref? in the results column) — every other evaluation error still resolves to a silent blank line, unchanged.

The engine has no concept of "other sheets" — that lives entirely in src/workspace.ts. Workspace reads all sheet texts from the app's in-memory data.contents, caches each sheet's exports (its assigned variables, total, last) after first evaluating it, and invalidates a sheet's cache plus every transitive dependent (found via a text scan for @Name.) when it's edited or rates refresh. Workspace.evaluateSheet(id, text) pushes id onto a resolving-stack for the duration of the call, so a sheet that references itself — directly or through another sheet — hits an already-on-the-stack check and resolves to circular reference instead of recursing forever.

UI notes

• CodeMirror injects its base theme at runtime after app.css, so anything that must win (content padding for the results column, cursor color) lives in an EditorView.theme(...) extension, not the stylesheet.
• The results column is an absolutely-positioned overlay; each result is placed with view.lineBlockAt(...) screen coordinates and re-rendered on scroll/geometry changes. Click-to-copy reads data-value.
• Engine evaluation is synchronous on every keystroke — a full sheet parse is well under a millisecond, so there's no debounce or worker.
• Search-all-sheets (Ctrl+F) is a plain line scan over every open sheet's text, not a CodeMirror search extension — it has to cross documents, so it never touches the active editor until a result is clicked (editor.goToLine). It lives in src/ui/search.ts (initSearch()), which owns the #search-overlay DOM and its own 150 ms input debounce — a result-value query (>1000) re-evaluates every open sheet, so debouncing matters once there are more than a couple of sheets open.
• The settings popover is split into four tabs (General / Format / Data / Updates) in index.html, each a .settings-tabpanel toggled by a #settings-tabs .tab button in bindSettingsUI() (main.ts) — plain classList.toggle, no router. Tab styling reuses the sidebar's doc-item.active idiom (background: var(--sel) for the active pill) rather than introducing a new visual pattern.

Storage

• settings.json always sits in %APPDATA%/app.summarum.calc.
• documents.json (all sheets) + backups/ live either there or in the user-chosen data folder (the path is stored in settings).
• Daily snapshot at startup (backups/documents-YYYY-MM-DD.json, keep 14); deleted sheets become .numi files under backups/deleted/ and are pruned by age. Saving is debounced at 400 ms.

Platforms and packaging

• One codebase, three desktop targets. tauri.conf.json holds everything shared; the per-platform bits live in tauri.windows.conf.json, tauri.linux.conf.json and tauri.macos.conf.json, which Tauri merges over the base config (JSON Merge Patch) according to the target being built. Each one only sets bundle.targets and that platform's bundler options — NSIS on Windows, deb/rpm/AppImage on Linux, .app/.dmg on macOS.
• release.yml builds five artifacts on three runner families: Windows x64 and arm64, Linux x64 (ubuntu-22.04 — the oldest runner carrying webkit2gtk-4.1, which keeps the glibc floor low), macOS arm64 and x64. Two separate macOS targets rather than universal-apple-darwin: it matches how Windows already ships per-architecture, halves each download, and gives the updater the darwin-aarch64/darwin-x86_64 keys it looks up by default.
• The whole matrix stays max-parallel: 1. Every job hands its assets to the same GitHub Release object, and tauri-action's find-or-create check races if two jobs reach it at once — adding platforms did not change that constraint, it made it apply to more jobs.
• No OS code signing anywhere. Windows ships unsigned; macOS is ad-hoc signed (bundle.macOS.signingIdentity: "-"), which needs no Apple certificate but is required for Apple Silicon to run a downloaded binary at all — without it the arm64 build is rejected as damaged rather than merely warned about. Gatekeeper still asks the user to allow the app on first launch either way.
• bundle.fileAssociations covers .numi/.sum on Windows (NSIS registry entries) and macOS (CFBundleDocumentTypes). On Linux it writes nothing useful: registering an extension there also needs a shared-mime-info XML that Tauri does not generate, so .numi files are opened by dragging them into the window rather than from the file manager.
• icons/icon.icns is emitted by scripts/gen-icon.ts alongside the PNGs and the .ico, hand-rolled the same dependency-free way: icns magic + total length, then one [OSType][length][PNG] chunk per size, using the modern PNG-payload tags iconutil produces (icp4/icp5, ic07–ic14). Rerun it with npm run icons after touching the artwork.

Auto-update

• updater.ts calls tauri-plugin-updater's check() on boot; if a signed update is available the user is prompted, then downloadAndInstall() + tauri-plugin-process's relaunch(). checkForUpdate() returns AvailableUpdate | null | "error" — null means the check succeeded and found nothing newer, "error" means the check itself failed (offline, signature mismatch, etc.); the distinction only matters for the manual path below. Every outcome is now visible in devtools: failures via console.warn, and a successful "no update" result logs the running version alongside "that's the latest published release" via console.info — the most common false alarm is simply that the installed build already is the newest release (e.g. right after installing it), which used to be indistinguishable from a silently broken check.
• Closing the window hides it to the tray instead of exiting the process (see on_window_event in main.rs), so a boot-time-only check can go unnoticed for a long time on a machine that isn't restarted often. main.ts also reruns checkUpdate() on a setInterval (every 6 hours) so a long-lived tray process still notices new releases, and Settings → Updates has a manual "Check for updates" button (checkUpdate(true)) that reports "up to date" / "check failed" via toast — those toasts are suppressed on the automatic background checks so the app doesn't nag every few hours. A SettingsData.autoUpdateEnabled toggle turns off both the boot check and the periodic recheck (re-read from settings on every interval tick, so flipping it while the app is running takes effect immediately); the manual button ignores the toggle and always works.
• The update endpoint is latest.json published alongside each GitHub Release. release.yml signs every platform's updater artifact with a minisign keypair (this is Tauri's own update signing, unrelated to OS code signing): the public half is embedded in tauri.conf.json; the private half + its password live only as TAURI_SIGNING_PRIVATE_KEY(_PASSWORD) repo secrets (write-only — there is no durable copy in the repo). Losing that key means already-installed copies can never trust a future signed release again.

Storage (cache files)

All files below live in %APPDATA%/app.summarum.calc (or the user-chosen folder):

File	Contents	TTL
settings.json	app settings	persisted
documents.json	all sheets	persisted (400 ms debounce)
rates.json	live exchange rates (open.er-api.com + CoinGecko)	1 hour
market.json	stock/commodity prices (Yahoo Finance v8 chart, one request per symbol)	15 minutes
rates-YYYY-MM-DD.json	historical ECB rates for one date (frankfurter.dev)	permanent
backups/documents-YYYY-MM-DD.json	daily snapshots	14 days
backups/deleted/*.numi	soft-deleted sheets	configurable

Tests

npm test runs 373 vitest cases across 21 files: src/engine/*.test.ts covers every expression class, both languages, deterministic injected rates, goal seek, historical rates (injected), date-format literals/display (dedicated engines with an explicit dateFormat, since the default "system" format depends on the CI machine's locale), plus a regression suite covering all known-fixed bugs; src/workspace.test.ts covers cross-sheet references, caching and cycle detection. UI is exercised manually; the engine is where the complexity lives.