feat: extend math engine: currencies, timezones, finance, cooking (#715)

* feat(math): add workday calculations

- `workdays in 3 weeks` → 15 workdays
- `workdays from April 12 to June 15` → N workdays
- `March 3 to March 7 in workdays` → N workdays
- `2 workdays after March 3` → date

* feat(math): add timestamps and ISO 8601 support

- `date to timestamp` → unix timestamp
- `date as iso8601` → ISO 8601 string
- `2019-04-01T15:30:00 to date` → parsed date
- `1733823083000 to date` → millisecond timestamp auto-detection

* feat(math): add timezone extensions — airport codes, countries, date in, time difference

- Airport codes: LAX, JFK, SYD, NRT, CDG, FRA, etc.
- Country names: Japan, Germany, Thailand, etc.
- City aliases: Seattle, Boston, Miami, etc.
- `date in Vancouver` → date-only display in timezone
- `time difference between Seattle and Moscow` → hours
- `difference between PDT & AEST` → hours

* feat(math): add timespan, laptime formats and shorthand time input

- `5.5 minutes as timespan` → 5 min 30 s
- `72 days as timespan` → 10 weeks 2 days
- `5.5 minutes as laptime` → 00:05:30
- `3h 5m 10s` shorthand input → stacked time units
- `03:04:05` laptime input → parsed as hours + minutes + seconds
- Laptime arithmetic: `03:04:05 + 01:02:03 as laptime` → 04:06:08

* feat(math): add clock time intervals

- `7:30 to 20:45` → 13 hours 15 min
- `4pm to 3am` → 11 hours (wraps around midnight)
- `9am to 5pm` → 8 hours

* fix(math): use absolute value for 'time difference between' phrases

* fix(math): preserve sign in timezone difference (matches Soulver behavior)

* fix(math): correct timezone difference sign for 'between' phrases

* test(math): add timezone difference sign verification tests

* test(math): add comprehensive edge case tests from audit

- Rounding: negative numbers, to 0 dp, to nearest 1, pi to 10 digits
- Fix: 'to N dp' now preserves N digits in output (not capped by default precision)
- Percentages: 0%, 100%, 200%, edge cases
- Fractions: 0.25 as fraction, -0.5 as fraction
- Multipliers: 0x, fractional multiplier
- Currency: euros/rubles words, implicit rate with EUR, reverse order
- Format directives: 0 in hex/bin, 0.001 in sci, mixed hex+bin input
- Conditionals: if with and, expression in condition, expression in postfix if
- Calendar: Q1/Q2/Q4, 0 days between, months/years from now/ago
- Clock intervals: midnight crossing, 12am/12pm, same time
- Timespans: 0 seconds, 1.5 hours, singular form

* feat(math): add misc phrase functions

- min/max, half, midpoint, random, gcd/lcm
- permutations/combinations, clamp, proportions (rule of three)

* feat(math): add video timecode and frame rate support

- Timecode format HH:MM:SS:FF with `at/@ N fps` (default 24 fps)
- `frame`/`frames` and `fps` units registered in math.js
- Timecode → frames conversion: `00:30:10:00 @ 24 fps in frames`
- Timecode arithmetic: `03:10:20:05 at 30 fps + 50 frames`
- fps calculations: `30 fps * 3 minutes`

* feat(math): add financial calculations

- Compound interest: yearly/monthly/quarterly compounding
- Interest only, ROI, annual return, present value
- Mortgage: daily/monthly/annual/total repayment and interest

* feat(math): add base N conversion and Python-style hex/bin/int

- `0b101101 as base 8` → 0o55
- `0x2D as base 2` → 0b101101
- `hex(99)` → 0x63, `bin(0x73)` → 0b1110011, `int(0o55)` → 45

* feat(math): add large number symbols and comment extensions

- Large numbers: B/bn (billion), T/tn (trillion), trillion word
- Comments: parenthesis comments `$999 (for iPhone)`, end-of-line `// comment`
- Parenthesis stripping safely skips function calls like sin(x)

* feat(math): add cooking calculations with substance density database

- `density of yogurt` → 1.06 g/cm³
- `300g butter in cups` → mass-to-volume conversion
- `10 cups olive oil in grams` → volume-to-mass conversion
- ~120 cooking substances with densities

* feat(math): extend currencies to 166 fiat + 21 crypto + prefix symbols

- Expand fiat currencies from 27 to 166 (all from open.er-api.com)
- Add 21 cryptocurrencies via CoinGecko API (BTC, ETH, SOL, DOGE, etc.)
- Prefixed dollar symbols: US$, NZ$, CA$, AU$, HK$, S$, NT$
- Custom exchange rates: `50 EUR in USD at 1.05 USD/EUR`
- CoinGecko + fiat fetched in parallel with 1h cache

* test(math): add comprehensive fixture documents for visual testing

14 fixture files covering all math engine features:
- arithmetic, variables, percentages, aggregates, rounding
- math functions, conditionals, units, currency
- fractions/multipliers, calendar, timezones, timespans
- finance, misc functions, cooking
- 4 real-world scenarios: budget, travel, cooking, dev

* fix(math): use user locale for timezone date formatting

* feat(math): unify date formatting with configurable dateFormat setting

- Single formatMathDate() for all date outputs (timezone, calendar, arithmetic)
- DateFormatStyle: 'numeric' | 'short' | 'long' (configurable via setFormatSettings)
- Options: timeZone, timeZoneName, dateOnly for context-specific formatting
- Remove separate formatTimeZoneDate function
- All dates now respect user locale consistently

* feat(math): add date format setting and currency/crypto refresh buttons

- Date format preference: numeric, short, long
- Separate refresh buttons for fiat currencies and crypto rates
- IPC handlers for forced refresh (ignores cache)
- i18n keys for new preferences

* fix: use shadcn Button import in Math preferences

* fix: match Button style with other preferences (remove size=sm)

* fix: unify currency/crypto rate descriptions in preferences

* fix: restore rate limit info in crypto description

* fix: clean up currency/crypto rate descriptions

* fix(math): use fixed notation for unit formatting to avoid scientific notation

* feat(math): support total/sum for unit results (currency, same units)

- numericBlock stores value + unit name
- Aggregates sum only if all entries have same unit
- Mixed units → aggregate returns null (cannot sum)
- $100 + $200 + $50 → sum = 350 USD
- Unit info extracted from math.js rawResult for block tracking

* fix(math): set numericValue for unit results so TOTAL works in UI

* fix: address 5 review findings

- P1: merge partial rates with existing cache instead of overwriting
- P2: show error toast on fiat refresh failure (was showing success)
- P2: finance evaluator uses user locale for formatting
- P2: cooking evaluator uses user locale for formatting
- P2: cooking classifier supports all volume units (pints, quarts, etc.)

* fix(math): address review fixes for rates and cooking locale

* refactor(test): split useMathEngine tests into domain-based files

- useMathEngine.integration.test.ts (66) — multi-line, variables, aggregates, errors
- useMathEngine.math.test.ts (229) — arithmetic, rounding, percentages, conditionals
- useMathEngine.units.test.ts (59) — unit conversion, area/volume, css, rates
- useMathEngine.currency.test.ts (22) — currency symbols, prefixes, modifiers
- useMathEngine.timezones.test.ts (28) — timezone display, conversion, difference
- useMathEngine.calendar.test.ts (47) — calendar, workdays, timestamps, timespans
- useMathEngine.domain.test.ts (17) — finance, cooking
- Shared setup in mathEngineTestUtils.ts

* test: add real-world math engine scenarios

Author: antonreshetov

src/main/__tests__/currencyRates.test.ts

@@ -0,0 +1,88 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { getCurrencyRates, refreshFiatRatesForced } from '../currencyRates'
+
+const mocks = vi.hoisted(() => {
+  const state: {
+    cache: { rates: Record<string, number>, fetchedAt: number } | null
+  } = {
+    cache: null,
+  }
+
+  return {
+    state,
+    get: vi.fn(() => state.cache),
+    set: vi.fn(
+      (
+        _key: string,
+        value: { rates: Record<string, number>, fetchedAt: number },
+      ) => {
+        state.cache = value
+      },
+    ),
+  }
+})
+
+vi.mock('../store', () => ({
+  store: {
+    currencyRates: {
+      get: mocks.get,
+      set: mocks.set,
+    },
+  },
+}))
+
+describe('currencyRates', () => {
+  beforeEach(() => {
+    mocks.state.cache = null
+    mocks.get.mockClear()
+    mocks.set.mockClear()
+    vi.restoreAllMocks()
+  })
+
+  it('does not persist partial cold-start rates to cache', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi
+        .fn()
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => ({
+            result: 'success',
+            rates: {
+              EUR: 0.92,
+              GBP: 0.79,
+            },
+          }),
+        })
+        .mockResolvedValueOnce({
+          ok: false,
+          status: 429,
+        }),
+    )
+
+    const payload = await getCurrencyRates()
+
+    expect(payload.source).toBe('live')
+    expect(payload.rates).toMatchObject({
+      USD: 1,
+      EUR: 0.92,
+      GBP: 0.79,
+    })
+    expect(mocks.set).not.toHaveBeenCalled()
+    expect(mocks.state.cache).toBeNull()
+  })
+
+  it('throws when forced fiat refresh fails', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        ok: false,
+        status: 500,
+      }),
+    )
+
+    await expect(refreshFiatRatesForced()).rejects.toThrow(
+      'Currency rates request failed with status 500',
+    )
+  })
+})

src/main/currencyRates.ts

@@ -14,6 +14,30 @@ export interface CurrencyRatesPayload {
   source: 'live' | 'cache' | 'unavailable'
 }
 
+const CRYPTO_IDS: Record<string, string> = {
+  BTC: 'bitcoin',
+  ETH: 'ethereum',
+  SOL: 'solana',
+  DOGE: 'dogecoin',
+  XRP: 'ripple',
+  ADA: 'cardano',
+  DOT: 'polkadot',
+  LTC: 'litecoin',
+  AVAX: 'avalanche-2',
+  SHIB: 'shiba-inu',
+  BNB: 'binancecoin',
+  USDT: 'tether',
+  USDC: 'usd-coin',
+  XLM: 'stellar',
+  XMR: 'monero',
+  EOS: 'eos',
+  TRX: 'tron',
+  DASH: 'dash',
+  NEO: 'neo',
+  BCH: 'bitcoin-cash',
+  ETC: 'ethereum-classic',
+}
+
 function normalizeRates(rates: Record<string, number>) {
   const normalized: Record<string, number> = { USD: 1 }
 
@@ -28,6 +52,58 @@ function normalizeRates(rates: Record<string, number>) {
   return normalized
 }
 
+function createPayload(rates: Record<string, number>): CurrencyRatesPayload {
+  return {
+    rates: normalizeRates(rates),
+    fetchedAt: Date.now(),
+    source: 'live',
+  }
+}
+
+async function fetchFiatRates(): Promise<Record<string, number>> {
+  const response = await fetch('https://open.er-api.com/v6/latest/USD')
+  if (!response.ok) {
+    throw new Error(
+      `Currency rates request failed with status ${response.status}`,
+    )
+  }
+
+  const data = (await response.json()) as CurrencyRatesApiResponse
+  if (data.result !== 'success' || !data.rates) {
+    throw new Error('Currency rates response is invalid')
+  }
+
+  return data.rates
+}
+
+async function fetchCryptoRates(): Promise<Record<string, number>> {
+  const ids = Object.values(CRYPTO_IDS).join(',')
+  const response = await fetch(
+    `https://api.coingecko.com/api/v3/simple/price?ids=${ids}&vs_currencies=usd`,
+  )
+
+  if (!response.ok) {
+    if (response.status === 429) {
+      throw new Error('rate_limit')
+    }
+    throw new Error(
+      `Crypto rates request failed with status ${response.status}`,
+    )
+  }
+
+  const data = (await response.json()) as Record<string, { usd?: number }>
+  const rates: Record<string, number> = {}
+
+  for (const [code, coinId] of Object.entries(CRYPTO_IDS)) {
+    const usdPrice = data[coinId]?.usd
+    if (usdPrice && usdPrice > 0) {
+      rates[code] = 1 / usdPrice
+    }
+  }
+
+  return rates
+}
+
 export async function getCurrencyRates(): Promise<CurrencyRatesPayload> {
   const cached = store.currencyRates.get('cache')
 
@@ -39,31 +115,41 @@ export async function getCurrencyRates(): Promise<CurrencyRatesPayload> {
   }
 
   try {
-    const response = await fetch('https://open.er-api.com/v6/latest/USD')
-    if (!response.ok) {
-      throw new Error(
-        `Currency rates request failed with status ${response.status}`,
-      )
-    }
+    const [fiatRates, cryptoRates] = await Promise.allSettled([
+      fetchFiatRates(),
+      fetchCryptoRates(),
+    ])
 
-    const data = (await response.json()) as CurrencyRatesApiResponse
-    if (data.result !== 'success' || !data.rates) {
-      throw new Error('Currency rates response is invalid')
+    const freshRates: Record<string, number> = {}
+
+    if (fiatRates.status === 'fulfilled') {
+      Object.assign(freshRates, fiatRates.value)
     }
 
-    const payload = {
-      rates: normalizeRates(data.rates),
-      fetchedAt: data.time_last_update_unix
-        ? data.time_last_update_unix * 1000
-        : Date.now(),
+    if (cryptoRates.status === 'fulfilled') {
+      Object.assign(freshRates, cryptoRates.value)
     }
 
-    store.currencyRates.set('cache', payload)
+    if (Object.keys(freshRates).length === 0) {
+      throw new Error('No rates fetched')
+    }
 
-    return {
-      ...payload,
-      source: 'live',
+    if (
+      !cached
+      && (fiatRates.status !== 'fulfilled' || cryptoRates.status !== 'fulfilled')
+    ) {
+      return createPayload(freshRates)
     }
+
+    const previousRates = cached?.rates || {}
+    const payload = createPayload({ ...previousRates, ...freshRates })
+
+    store.currencyRates.set('cache', {
+      rates: payload.rates,
+      fetchedAt: payload.fetchedAt,
+    })
+
+    return payload
   }
   catch {
     if (cached) {
@@ -80,3 +166,37 @@ export async function getCurrencyRates(): Promise<CurrencyRatesPayload> {
     }
   }
 }
+
+export async function refreshFiatRatesForced(): Promise<CurrencyRatesPayload> {
+  const fiatRates = await fetchFiatRates()
+  const cached = store.currencyRates.get('cache')
+
+  if (!cached) {
+    return createPayload(fiatRates)
+  }
+
+  const payload = createPayload({ ...cached.rates, ...fiatRates })
+  store.currencyRates.set('cache', {
+    rates: payload.rates,
+    fetchedAt: payload.fetchedAt,
+  })
+
+  return payload
+}
+
+export async function refreshCryptoRatesForced(): Promise<CurrencyRatesPayload> {
+  const cryptoRates = await fetchCryptoRates()
+  const cached = store.currencyRates.get('cache')
+
+  if (!cached) {
+    return createPayload(cryptoRates)
+  }
+
+  const payload = createPayload({ ...cached.rates, ...cryptoRates })
+  store.currencyRates.set('cache', {
+    rates: payload.rates,
+    fetchedAt: payload.fetchedAt,
+  })
+
+  return payload
+}

src/main/i18n/locales/en_US/preferences.json

@@ -124,6 +124,26 @@
     "decimalPlaces": {
       "label": "Decimal Places",
       "description": "Maximum decimal places in results (0\u201314)."
+    },
+    "dateFormat": {
+      "label": "Date Format",
+      "description": "How dates are displayed in results."
+    },
+    "currencyRates": {
+      "label": "Currency Rates",
+      "description": "Cached for 1 hour.",
+      "refresh": "Refresh",
+      "refreshing": "Refreshing...",
+      "refreshed": "Currency rates updated",
+      "refreshError": "Failed to update currency rates"
+    },
+    "cryptoRates": {
+      "label": "Crypto Rates",
+      "description": "Cached for 1 hour. Rate limit: 10-30 req/min.",
+      "refresh": "Refresh",
+      "refreshing": "Refreshing...",
+      "refreshed": "Crypto rates updated",
+      "rateLimited": "Rate limit exceeded. Try again later."
     }
   },
   "api": {

src/main/ipc/handlers/system.ts

@@ -1,6 +1,10 @@
 import path from 'node:path'
 import { app, ipcMain, shell } from 'electron'
-import { getCurrencyRates } from '../../currencyRates'
+import {
+  getCurrencyRates,
+  refreshCryptoRatesForced,
+  refreshFiatRatesForced,
+} from '../../currencyRates'
 import {
   findNoteById,
   getNotesFolderPathById,
@@ -14,6 +18,14 @@ export function registerSystemHandlers() {
     return getCurrencyRates()
   })
 
+  ipcMain.handle('system:currency-rates-refresh', () => {
+    return refreshFiatRatesForced()
+  })
+
+  ipcMain.handle('system:crypto-rates-refresh', () => {
+    return refreshCryptoRatesForced()
+  })
+
   ipcMain.handle('system:reload', () => {
     app.relaunch()
     app.quit()

src/main/store/module/preferences.ts

@@ -24,6 +24,7 @@ const storagePath = isWin ? `${homedir()}\\massCode` : `${homedir()}/massCode`
 const MATH_DEFAULTS: MathSettings = {
   locale: 'en-US',
   decimalPlaces: 6,
+  dateFormat: 'numeric',
 }
 
 const PREFERENCES_DEFAULTS: PreferencesStore = {
@@ -153,13 +154,19 @@ function sanitizeMarkdownSettings(value: unknown): MarkdownSettings {
 function sanitizeMathSettings(value: unknown): MathSettings {
   const source = asRecord(value)
 
+  const dateFormat = readString(source, 'dateFormat', MATH_DEFAULTS.dateFormat)
+  const validDateFormats = ['numeric', 'short', 'long']
+
   return {
     locale: readString(source, 'locale', MATH_DEFAULTS.locale),
     decimalPlaces: readNumber(
       source,
       'decimalPlaces',
       MATH_DEFAULTS.decimalPlaces,
     ),
+    dateFormat: validDateFormats.includes(dateFormat)
+      ? (dateFormat as MathSettings['dateFormat'])
+      : MATH_DEFAULTS.dateFormat,
   }
 }
 

src/main/store/types/index.ts

@@ -81,6 +81,7 @@ export interface NotesEditorSettings {
 export interface MathSettings {
   locale: string
   decimalPlaces: number
+  dateFormat: 'numeric' | 'short' | 'long'
 }
 
 export interface PreferencesStore {

src/main/types/ipc.ts

@@ -34,6 +34,8 @@ type DBAction = 'migrate-to-markdown'
 
 type SystemAction =
   | 'currency-rates'
+  | 'currency-rates-refresh'
+  | 'crypto-rates-refresh'
   | 'reload'
   | 'open-external'
   | 'show-notes-folder-in-file-manager'

src/renderer/components/math-notebook/Workspace.vue

@@ -20,13 +20,21 @@ const {
 
 const mathSettings = reactive(store.preferences.get('math') as MathSettings)
 
-setFormatSettings(mathSettings.locale, mathSettings.decimalPlaces)
+setFormatSettings(
+  mathSettings.locale,
+  mathSettings.decimalPlaces,
+  mathSettings.dateFormat,
+)
 
 watch(
   mathSettings,
   () => {
     store.preferences.set('math', JSON.parse(JSON.stringify(mathSettings)))
-    setFormatSettings(mathSettings.locale, mathSettings.decimalPlaces)
+    setFormatSettings(
+      mathSettings.locale,
+      mathSettings.decimalPlaces,
+      mathSettings.dateFormat,
+    )
   },
   { deep: true },
 )