feat(calc): evaluate mixed unit expressions

AGENTS.md

@@ -123,6 +123,7 @@ Inside `packages/lingo/` the same scripts run directly (`bun run test`, etc.).
 - `fuzzy/` — fuzzy vocab ("hot", "a few") → ranges
 - `messages/` — default human-readable issue copy (`./core` ships copy-free)
 - `date/` — natural-language date/duration parsing + humanizing (entry `./date`)
+- `calc/` — closed quantity arithmetic (entry `./calc`)
 - `describe/` — opt-in rich/resource value + result views (entry `./describe`)
 - `catalog/` — read-only query API over unit/kind/currency data (entry `./catalog`)
 - `dom/` — headless input controller (entry `./dom`)

CONTEXT.md

@@ -45,6 +45,16 @@ latter two and absent on a slot — test it truthy, never `=== false`.
 (the normalizer keeps an offset map, hard rule 3). *Avoid: range, position,
 location.*
 
+**Expression:** a closed arithmetic tree over numbers and same-kind quantities,
+produced and evaluated by `calc()`. *Avoid: formula.*
+
+**Node:** one element of a calc expression (`CalcNode`). Its `span` is a span
+into the original input, never a range. *Avoid: AST.*
+
+**Calc:** the `@pascal-app/lingo/calc` entry and its `calc()` function.
+`lingo()` never evaluates expressions. Compact `"14m"` (million) round-trips
+through `calc()`, not `lingo()`.
+
 **Conversion:** a parsed conversion *request* ("72 in to cm") — a result type.
 The arithmetic itself is `convert()` / `convertDelta()`.
 
@@ -109,7 +119,10 @@ locale pack objects. *Avoid: profile (ambiguous with fuzzy Profile).*
 Humanize output re-parses within one grain.
 
 **Format vs humanize:** `format()` renders quantities; `humanize*()` renders
-dates and durations. Both are covered by the two-way guarantee (hard rule 4).
+dates and durations; `formatCalc()` / `CalcResult.format()` renders evaluated
+expression results (including words/compact/scientific). All three are covered
+by the two-way guarantee (hard rule 4), with one calc-specific note: compact
+`"14m"` re-parses through `calc()`, not `lingo()`.
 
 **Partial state:** the as-you-type classification — `empty | incomplete | valid
 | invalid`. "2 f" is *incomplete*, never invalid (the DOM layer never yells
@@ -120,7 +133,7 @@ its value. Fields never rewrite text while typing (D6).
 
 ## Infrastructure nouns
 
-**Entry:** a published subpath — `.`, `./core`, `./date`, `./dom`, `./element`,
+**Entry:** a published subpath — `.`, `./core`, `./date`, `./calc`, `./dom`, `./element`,
 `./describe`, `./catalog`, `./schema`, `./ai`, `./mcp`, `./react`,
 `./react-native`, `./complete`, `./locales/*`. *Avoid: subpackage, plugin.*
 
@@ -155,6 +168,9 @@ inline.
 
 - **"range" vs "span"** — the collision that bites. Values: range. Text
   offsets: span. No exceptions.
+- **"m" in calc** — glued `7m*2` is seven million times two; spaced `7 m` is
+  meters; `lingo('14m')` is fourteen meters. Compact `"14m"` round-trips
+  through `calc()` only.
 - **"error"** — fine as a severity or the `ok: false` state; the object is an
   issue.
 - **"unit"** in prose can mean id, symbol, or def — in code, use the precise

apps/site/public/llms-small.txt

@@ -4,7 +4,7 @@
 
 Agent fetch order (online): `https://lingo.pascal.app/llms.txt` (index) → `https://lingo.pascal.app/docs/<section>.md` (per-topic) or `https://lingo.pascal.app/llms-full.txt` (complete narrative). Offline: this file (`node_modules/@pascal-app/lingo/llms.txt`) is the compressed self-contained reference. Keep user measurements as strings in tool schemas; call lingo to convert, validate, surface spans, and handle ambiguity.
 
-Entries: `@pascal-app/lingo` (core+units+fuzzy), `@pascal-app/lingo/date`, `@pascal-app/lingo/dom`, `@pascal-app/lingo/element` (`<lingo-input>`), `@pascal-app/lingo/react`, `@pascal-app/lingo/react-native`, `@pascal-app/lingo/ai` (LLM tool fields), `@pascal-app/lingo/mcp` (MCP tool helper), `@pascal-app/lingo/describe` (rich value/result descriptions), `@pascal-app/lingo/catalog` (query units/kinds/currencies + ISO country codes), `@pascal-app/lingo/complete` (ranked autocomplete completions), `@pascal-app/lingo/schema` (JSON Schema + OpenAPI + enum reference), `@pascal-app/lingo/locales/{en,en-gb,es,fr,pt,zh,ja}` (tree-shakeable language packs), `@pascal-app/lingo/core`.
+Entries: `@pascal-app/lingo` (core+units+fuzzy), `@pascal-app/lingo/date`, `@pascal-app/lingo/calc`, `@pascal-app/lingo/dom`, `@pascal-app/lingo/element` (`<lingo-input>`), `@pascal-app/lingo/react`, `@pascal-app/lingo/react-native`, `@pascal-app/lingo/ai` (LLM tool fields), `@pascal-app/lingo/mcp` (MCP tool helper), `@pascal-app/lingo/describe` (rich value/result descriptions), `@pascal-app/lingo/catalog` (query units/kinds/currencies + ISO country codes), `@pascal-app/lingo/complete` (ranked autocomplete completions), `@pascal-app/lingo/schema` (JSON Schema + OpenAPI + enum reference), `@pascal-app/lingo/locales/{en,en-gb,es,fr,pt,zh,ja}` (tree-shakeable language packs), `@pascal-app/lingo/core`.
 
 ## Core (`@pascal-app/lingo`)
 
@@ -38,10 +38,10 @@ Kinds: length mass temperature duration volume area speed data data_rate flow_ra
 import { completions } from "@pascal-app/lingo/complete"
 
 const items = completions("10 kg to 16", { kind: "mass", limit: 8 })
-// [{ text, result, confidence, source }] — source: parse|alternative|unit-ambiguity|unit-prefix|implied-unit|range-implied|cross-kind|date
+// [{ text, result, confidence, source }] — source: parse|alternative|unit-ambiguity|unit-prefix|implied-unit|range-implied|cross-kind|date|calc
 ```
 
-Distinct from success `alternatives`, failure `candidate`, and issue `suggestions`. Wire into `lingoInput({ complete, onComplete })` or `useLingoInput({ complete })` for autocomplete dropdowns. The React hook exposes `completions`, `highlightedIndex`, `setHighlightedIndex()`, and `selectCompletion()` while keeping popup UI caller-owned. Pass `date: (text) => parseDate(text, { now })` to opt into date completions without bundling `@pascal-app/lingo/date` into `@pascal-app/lingo/complete`.
+Distinct from success `alternatives`, failure `candidate`, and issue `suggestions`. Wire into `lingoInput({ complete, onComplete })` or `useLingoInput({ complete })` for autocomplete dropdowns. The React hook exposes `completions`, `highlightedIndex`, `setHighlightedIndex()`, and `selectCompletion()` while keeping popup UI caller-owned. Pass `date: (text) => parseDate(text, { now })` to opt into date completions without bundling `@pascal-app/lingo/date` into `@pascal-app/lingo/complete`. Pass `calc: (text) => calc(text, { trigger: "=" })` the same way so `=2+3 kg` completes as `= 5 kg` without bundling `@pascal-app/lingo/calc`; bare `5-10 kg` stays a range.
 
 ## Locales (`@pascal-app/lingo/locales/*`)
 
@@ -111,6 +111,28 @@ humanizeDate(d, { now }) // "3 days ago" — always re-parses within one grain
 
 Not supported: quarters (`Q3`, `next quarter`), elliptical right sides (`Aug 3-9`), and dash-joined ISO dates with no spaces (`2026-08-01-2026-08-05`) — all return `UNSUPPORTED_DATE`. Use a spaced dash or `to` between ISO dates.
 
+## Calc (`@pascal-app/lingo/calc`)
+
+```ts
+import { calc } from "@pascal-app/lingo/calc"
+
+const r = calc("7m*2")
+r.ok && r.value                    // 14000000
+r.ok && r.format({ style: "words" })      // "14 million"
+r.ok && r.format({ style: "grouped" })    // "14,000,000"
+r.ok && r.format({ style: "scientific" }) // "14e6"
+r.ok && r.format({ style: "compact" })    // "14m"
+r.ok && r.expression               // "7e6 × 2"
+r.ok && r.latex                    // "7 \\times 10^{6} \\times 2"
+
+calc("9min x 4")                   // 36 min; format({ unit: "h" }) → "0.6 h"
+calc("half of 56kg+1700g")         // 28.85 kg
+calc("12 * 0.75 kg")               // 9 kg
+calc("10% off 50 kg")              // 45 kg
+```
+
+Closed calculator: no variables, functions, or dimensional algebra. `lingo()` never evaluates expressions — `2+3 kg` is `TRAILING_INPUT`, `5-10 kg` stays a range. `calc()` default `trigger` is `"always"`. Completions require a leading `=`; `quantityField({ calc })` evaluates `+`/`*`/`/`/`% of` without a prefix (never `-`; glued `5/10 kg` stays a fraction). Glued `m` at an operator boundary is million unless `kind` is `length` or `duration` (`SCALE_ASSUMED`); spaced `7 m` is meters; `1m80` stays 1.80 m. Compact `"14m"` round-trips through `calc()`, not `lingo()`. Same-kind `q / q` is a dimensionless ratio; cross-currency arithmetic is `RATE_REQUIRED`; `q * q` is `SCALAR_EXPECTED`. `formatExpression` is two-way; `formatLatex` is display-only.
+
 ## DOM (`@pascal-app/lingo/dom`)
 
 ```ts
@@ -334,12 +356,17 @@ The `/docs#forms-ux` section and `/docs/forms-ux.md` markdown mirror show the sa
 | RANGE_REVERSED | Bounds given high-to-low; parser swapped them | Emit low-to-high, or accept the swap |
 | UNSUPPORTED_DATE | Date/range shape not in the grammar (`Q3`, `Aug 3-9`) | Re-emit a supported shape or an explicit `start to end` pair |
 | RATE_REQUIRED | Cross-currency without rates | Call `convertCurrency` with injected rates |
+| AFFINE_DELTA_ASSUMED | Additive °C/°F used as a delta | Accept the delta reading, or convert absolutely first |
+| EXPRESSION_KIND_MISMATCH | Mixed kinds in `calc()` | Keep operands the same kind |
+| SCALAR_EXPECTED | `q * q` or `n / q` | Scale a quantity by a number, or divide two same-kind quantities |
+| DIVISION_BY_ZERO | Division by zero | Use a non-zero divisor |
+| SCALE_ASSUMED | Glued `m`/`b` read as million/billion | Pass `kind: "length"` for meters, or write `7 million` |
 
-Full list: EMPTY, NO_VALUE, UNKNOWN_UNIT, KIND_MISMATCH, RANGE_KIND_MISMATCH, CONVERSION_KIND_MISMATCH, RATE_REQUIRED, TRAILING_INPUT, SINGLE_VALUE_EXPECTED, APPROX_NOT_ALLOWED, UNIT_REQUIRED, CONVERSION_NOT_ALLOWED, NUMBER_FORMAT, NONFINITE, LOCALE_NOT_LOADED, RANGE_MIN, RANGE_MAX, RANGE_OPEN_BOUND_NOT_ALLOWED, REQUIRED, UNSUPPORTED_DATE, NOW_REQUIRED, TYPO_CORRECTED, AMBIGUOUS_NUMBER, AMBIGUOUS_UNIT, AMBIGUOUS_DATE, RANGE_REVERSED, COMPOUND_OVERFLOW, CIVIL_AVERAGE, UNIT_ASSUMED, WEEKDAY_ASSUMED_NEXT, SLANG_UNIT, TZ_IGNORED, AMBIGUOUS_TIMEZONE. Override copy via `messages` option map.
+Full list: EMPTY, NO_VALUE, UNKNOWN_UNIT, KIND_MISMATCH, RANGE_KIND_MISMATCH, CONVERSION_KIND_MISMATCH, RATE_REQUIRED, TRAILING_INPUT, SINGLE_VALUE_EXPECTED, APPROX_NOT_ALLOWED, UNIT_REQUIRED, CONVERSION_NOT_ALLOWED, NUMBER_FORMAT, NONFINITE, LOCALE_NOT_LOADED, RANGE_MIN, RANGE_MAX, RANGE_OPEN_BOUND_NOT_ALLOWED, REQUIRED, UNSUPPORTED_DATE, NOW_REQUIRED, TYPO_CORRECTED, AMBIGUOUS_NUMBER, AMBIGUOUS_UNIT, AMBIGUOUS_DATE, RANGE_REVERSED, COMPOUND_OVERFLOW, CIVIL_AVERAGE, UNIT_ASSUMED, WEEKDAY_ASSUMED_NEXT, SLANG_UNIT, TZ_IGNORED, AMBIGUOUS_TIMEZONE, AFFINE_DELTA_ASSUMED, EXPRESSION_KIND_MISMATCH, SCALAR_EXPECTED, DIVISION_BY_ZERO, SCALE_ASSUMED. Override copy via `messages` option map.
 
 ## Canonical examples (input → essence)
 
-"2 ft" → quantity length base 0.6096 m · "5'11\"" → 1.8034 m (parts ft+in) · "72 in to cm" → conversion, converted 182.88 cm · "60 miles an hour" → speed in m/s · "5 cubic feet" → volume in m³ · "approx. 5 kg" → approximate mass · "1m80" → 1.8 m · "1h30" → 5400 s · "2 lb 3 oz" → 0.9922 kg · "$5" → currency USD value/base 5 baseUnit USD + AMBIGUOUS_UNIT; pass `{currency:'CAD'}` to read bare "$" as CAD · "50 cents" → 0.5 USD + AMBIGUOUS_UNIT; pass `{currency:'EUR'}` to read as EUR · "five dollars and fifty cents" → 5.5 USD · "50p" → 0.5 GBP · "3 quid 50" → 3.5 GBP · "€5-€10" → currency range baseUnit EUR · "5 EUR to USD" → ok:false RATE_REQUIRED (use convertCurrency with injected rates) · "between 5 and 10 kg" → range 5..10 kg · "under 10 minutes" → range max 600 s exclusive · "no greater than 5 kg" → range max 5 kg inclusive · "10 ± 0.5 mm" → plusMinus center 10 mm/base 0.01 and delta 0.5 mm/base 0.0005 · "a few minutes" → range 120..240 s approximate · "it's hot" (kind temperature) → range 300.15..308.15 K fuzzy 'hot' · "1,5 kg" → 1.5 kg · "1,234" → 1234 + AMBIGUOUS_NUMBER (alt 1.234) · "5 meterz" (kind length) → 5 m + TYPO_CORRECTED; with strictness confirm → ok:false + candidate 5 m · "72" (kind length, unit cm, accept.bareNumbers false) → UNIT_REQUIRED + candidate 72 cm · "72 in to cm" with accept.conversions false → CONVERSION_NOT_ALLOWED + candidate conversion · "5m" (kind duration) → 300 s + SLANG_UNIT · "in 2d" → date two days from now · "3min from tmrw" → tomorrow, same time-of-day +3 min · "17h30" → 17:30 · "quarter past 5" → 05:15 · "3pm EST" → 15:00 civil + zone {abbrev, -300, ambiguous} + TZ_IGNORED/AMBIGUOUS_TIMEZONE; `{applyZone:true}` → the 20:00Z instant · "2pm to 4pm" → date-range 14:00..16:00 · "9-5" → date-range 09:00..17:00 (workday shift) · "Aug 3 - Aug 9" → dated date-range 2026-08-03..2026-08-09 · "August" → dated date-range 2026-08-01..2026-08-31 (whole month) · "next week" → Mon..Sun · "this weekend" → Sat..Sun (the one in progress on Sat/Sun) · "2026-08-09 to 2026-08-03" → swapped 08-03..08-09 + RANGE_REVERSED · "Q3" → ok:false UNSUPPORTED_DATE (quarters need a fiscal-year anchor; not supported) · "500 KB" → 500000 B · "5 Mb" → 625000 B (megabits) · "5 Mbps" → data_rate 5000000 bit/s; use "bit/s" for bits per second because bare "bps" stays basis points · "5 gpm" → flow_rate 0.000315451 m³/s · "250 mL/min" → flow_rate 0.000004167 m³/s · "10 inH₂O" → pressure 2490.8891 Pa · "1 kgf/cm²" → pressure 98.0665 kPa · "1 kg/cm²" → ok:false TRAILING_INPUT (kilogram-mass over area deferred; use kgf/cm²) · "5 psig" (kind pressure) → ok:false UNKNOWN_UNIT (gauge semantics deferred) · "9.8 m/s²" → acceleration 9.8 m/s² · "10 Nm" → torque 10 N⋅m (exact-case; lowercase "nm" remains nanometers) · "500 lux" → illuminance 500 lx · "100 nits" → luminance 100 cd/m² · "20 mSv" → radiation equivalent dose 0.02 Sv · "5 MBq" → radioactivity 5000000 Bq · "5 uM" → concentration 0.005 mol/m³ · "1 mol/L" and "1 mol per L" → concentration 1000 mol/m³; untyped glued "1M" fails, use "1 M" or `kind:'concentration'` · "-40°F" → 233.15 K · "3×10⁵ m" → 300000 m · "½ cup" → 118.29 mL · "15%" → percent 15 · "25 bps" → 0.25% (basis points; bare bps stays percent) · "500 mAh" → charge 1800 C · "4.7 kohm" → resistance 4700 Ω · "250 mmol" → substance 0.25 mol.
+"2 ft" → quantity length base 0.6096 m · "5'11\"" → 1.8034 m (parts ft+in) · "72 in to cm" → conversion, converted 182.88 cm · "7m*2" via `@pascal-app/lingo/calc` → 14000000 + SCALE_ASSUMED (compact "14m", words "14 million") · "9min x 4" via calc → 36 min · "half of 56kg+1700g" via calc → 28.85 kg · "2+3 kg" via lingo → ok:false TRAILING_INPUT (not a silent 2–3 kg range); via calc → 5 kg · "60 miles an hour" → speed in m/s · "5 cubic feet" → volume in m³ · "approx. 5 kg" → approximate mass · "1m80" → 1.8 m · "1h30" → 5400 s · "2 lb 3 oz" → 0.9922 kg · "$5" → currency USD value/base 5 baseUnit USD + AMBIGUOUS_UNIT; pass `{currency:'CAD'}` to read bare "$" as CAD · "50 cents" → 0.5 USD + AMBIGUOUS_UNIT; pass `{currency:'EUR'}` to read as EUR · "five dollars and fifty cents" → 5.5 USD · "50p" → 0.5 GBP · "3 quid 50" → 3.5 GBP · "€5-€10" → currency range baseUnit EUR · "5 EUR to USD" → ok:false RATE_REQUIRED (use convertCurrency with injected rates) · "between 5 and 10 kg" → range 5..10 kg · "under 10 minutes" → range max 600 s exclusive · "no greater than 5 kg" → range max 5 kg inclusive · "10 ± 0.5 mm" → plusMinus center 10 mm/base 0.01 and delta 0.5 mm/base 0.0005 · "a few minutes" → range 120..240 s approximate · "it's hot" (kind temperature) → range 300.15..308.15 K fuzzy 'hot' · "1,5 kg" → 1.5 kg · "1,234" → 1234 + AMBIGUOUS_NUMBER (alt 1.234) · "5 meterz" (kind length) → 5 m + TYPO_CORRECTED; with strictness confirm → ok:false + candidate 5 m · "72" (kind length, unit cm, accept.bareNumbers false) → UNIT_REQUIRED + candidate 72 cm · "72 in to cm" with accept.conversions false → CONVERSION_NOT_ALLOWED + candidate conversion · "5m" (kind duration) → 300 s + SLANG_UNIT · "in 2d" → date two days from now · "3min from tmrw" → tomorrow, same time-of-day +3 min · "17h30" → 17:30 · "quarter past 5" → 05:15 · "3pm EST" → 15:00 civil + zone {abbrev, -300, ambiguous} + TZ_IGNORED/AMBIGUOUS_TIMEZONE; `{applyZone:true}` → the 20:00Z instant · "2pm to 4pm" → date-range 14:00..16:00 · "9-5" → date-range 09:00..17:00 (workday shift) · "Aug 3 - Aug 9" → dated date-range 2026-08-03..2026-08-09 · "August" → dated date-range 2026-08-01..2026-08-31 (whole month) · "next week" → Mon..Sun · "this weekend" → Sat..Sun (the one in progress on Sat/Sun) · "2026-08-09 to 2026-08-03" → swapped 08-03..08-09 + RANGE_REVERSED · "Q3" → ok:false UNSUPPORTED_DATE (quarters need a fiscal-year anchor; not supported) · "500 KB" → 500000 B · "5 Mb" → 625000 B (megabits) · "5 Mbps" → data_rate 5000000 bit/s; use "bit/s" for bits per second because bare "bps" stays basis points · "5 gpm" → flow_rate 0.000315451 m³/s · "250 mL/min" → flow_rate 0.000004167 m³/s · "10 inH₂O" → pressure 2490.8891 Pa · "1 kgf/cm²" → pressure 98.0665 kPa · "1 kg/cm²" → ok:false TRAILING_INPUT (kilogram-mass over area deferred; use kgf/cm²) · "5 psig" (kind pressure) → ok:false UNKNOWN_UNIT (gauge semantics deferred) · "9.8 m/s²" → acceleration 9.8 m/s² · "10 Nm" → torque 10 N⋅m (exact-case; lowercase "nm" remains nanometers) · "500 lux" → illuminance 500 lx · "100 nits" → luminance 100 cd/m² · "20 mSv" → radiation equivalent dose 0.02 Sv · "5 MBq" → radioactivity 5000000 Bq · "5 uM" → concentration 0.005 mol/m³ · "1 mol/L" and "1 mol per L" → concentration 1000 mol/m³; untyped glued "1M" fails, use "1 M" or `kind:'concentration'` · "-40°F" → 233.15 K · "3×10⁵ m" → 300000 m · "½ cup" → 118.29 mL · "15%" → percent 15 · "25 bps" → 0.25% (basis points; bare bps stays percent) · "500 mAh" → charge 1800 C · "4.7 kohm" → resistance 4700 Ω · "250 mmol" → substance 0.25 mol.
 
 ## Docs (online)
 

apps/site/public/schema/dictionary.md

@@ -41,7 +41,7 @@ The compact wire JSON `JSON.stringify(lingo(...))` produces. Generated from
 
 `error`, `warning`, `info`
 
-## Issue codes (33)
+## Issue codes (38)
 
 | code | meaning |
 |---|---|
@@ -78,4 +78,9 @@ The compact wire JSON `JSON.stringify(lingo(...))` produces. Generated from
 | `SLANG_UNIT` | A slang unit spelling was interpreted. |
 | `TZ_IGNORED` | A time zone was detected but not applied (civil time kept; use applyZone). |
 | `AMBIGUOUS_TIMEZONE` | A time-zone abbreviation maps to more than one real zone. |
+| `AFFINE_DELTA_ASSUMED` | An affine unit was added as a delta, not an absolute temperature. |
+| `EXPRESSION_KIND_MISMATCH` | Expression operands are different kinds. |
+| `SCALAR_EXPECTED` | Arithmetic needed a plain number, not a second quantity. |
+| `DIVISION_BY_ZERO` | The expression divided by zero. |
+| `SCALE_ASSUMED` | A glued scale letter was read as million/billion, not a unit. |
 

apps/site/public/schema/lingo.openapi.json

@@ -96,7 +96,12 @@
               "WEEKDAY_ASSUMED_NEXT",
               "SLANG_UNIT",
               "TZ_IGNORED",
-              "AMBIGUOUS_TIMEZONE"
+              "AMBIGUOUS_TIMEZONE",
+              "AFFINE_DELTA_ASSUMED",
+              "EXPRESSION_KIND_MISMATCH",
+              "SCALAR_EXPECTED",
+              "DIVISION_BY_ZERO",
+              "SCALE_ASSUMED"
             ],
             "description": "Stable machine code — switch on this."
           },

apps/site/public/schema/lingo.schema.json

@@ -92,7 +92,12 @@
             "WEEKDAY_ASSUMED_NEXT",
             "SLANG_UNIT",
             "TZ_IGNORED",
-            "AMBIGUOUS_TIMEZONE"
+            "AMBIGUOUS_TIMEZONE",
+            "AFFINE_DELTA_ASSUMED",
+            "EXPRESSION_KIND_MISMATCH",
+            "SCALAR_EXPECTED",
+            "DIVISION_BY_ZERO",
+            "SCALE_ASSUMED"
           ],
           "description": "Stable machine code — switch on this."
         },