@jarenjs/calc 0.34.0

package/dist/types/plot/plot3d.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @file The x·y·z surface plotter. Samples
+ * `z = f(x, y)` on an N×N grid into `Vec3f64` model points, rotates them
+ * (yaw/pitch) and projects them with the `core` `mat4`/`project.js`
+ * kernel, builds quad faces, **depth-sorts back-to-front (painter's
+ * algorithm)**, shades each quad by height and emits `<polygon>`s with an
+ * optional wireframe. Deterministic and headless → golden-geometry tests.
+ */
+export type Plot3dConfig = {
+    /**
+     * the z = f(x,y) source
+     */
+    expr?: string;
+    domainX?: [number, number];
+    domainY?: [number, number];
+    /**
+     * samples per axis
+     */
+    grid?: number;
+    yaw?: number;
+    /**
+     * rotation, radians
+     */
+    pitch?: number;
+    width?: number;
+    height?: number;
+    /**
+     * independent variable names
+     */
+    variables?: [string, string];
+    scope?: any;
+    env?: any;
+    theme?: any;
+    wireframe?: boolean;
+};
+/**
+ * @typedef {object} Plot3dConfig
+ * @property {string} [expr] the z = f(x,y) source
+ * @property {[number,number]} [domainX] @property {[number,number]} [domainY]
+ * @property {number} [grid] samples per axis
+ * @property {number} [yaw] @property {number} [pitch] rotation, radians
+ * @property {number} [width] @property {number} [height]
+ * @property {[string,string]} [variables] independent variable names
+ * @property {any} [scope] @property {any} [env]
+ * @property {any} [theme] @property {boolean} [wireframe]
+ */
+/**
+ * Build the projected, depth-sorted scene (geometry as plain JSON).
+ * @param {string|Plot3dConfig} exprOrConfig
+ * @param {Plot3dConfig} [options]
+ * @returns {any}
+ */
+export declare function buildScene3d(exprOrConfig: string | Plot3dConfig, options?: Plot3dConfig): any;
+/**
+ * Render a 3D scene into pure-vnode SVG.
+ * @param {any} scene @param {{ theme?: any }} [options]
+ * @returns {any}
+ */
+export declare function scene3dToVnode(scene: any, options?: {
+    theme?: any;
+}): any;
+/**
+ * Compile → sample → project → SVG vnode in one call.
+ * @param {string|Plot3dConfig} exprOrConfig
+ * @param {Plot3dConfig} [options]
+ * @returns {any}
+ */
+export declare function plot3d(exprOrConfig: string | Plot3dConfig, options?: Plot3dConfig): any;

package/dist/types/render/error.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @file The error vnode. The render path is total — it emits this
+ * instead of throwing. A small standalone `<svg>` that
+ * states the parse/eval error with its line/column when known.
+ */
+/**
+ * @param {{ message: string, line?: number, column?: number }} error
+ * @param {{ theme?: any, width?: number, height?: number }} [options]
+ * @returns {any}
+ */
+export declare function errorToVnode(error: {
+    message: string;
+    line?: number;
+    column?: number;
+}, options?: {
+    theme?: any;
+    width?: number;
+    height?: number;
+}): any;

package/dist/types/theme.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @file Plot theme tokens (mirrors `@jarenjs/mermaid`'s theme). Resolves a
+ * name (or overrides) into concrete colors (written as SVG presentation
+ * attributes so `toSvgString()` is a valid standalone image) plus a
+ * matching `--calc-*` CSS variable set stamped inline on the root `<svg>`.
+ * The inline stamp beats every stylesheet rule, so the stamp itself is the
+ * re-theming hook: the `'host'` theme stamps linked variables as
+ * `var(--<host-token>, <concrete>)` (see `HOST_VARS`), making plots follow
+ * a host's light/dark tokens live without a re-render. Only the token
+ * tables live here; the resolution mechanics are shared
+ * (`@jarenjs/view/helpers` `resolveTheme`).
+ */
+/** @type {Record<string, Record<string, string>>} */
+declare const THEMES: Record<string, Record<string, string>>;
+/**
+ * Host custom-property links for the `'host'` theme: token key → the host
+ * token it should follow (the site token vocabulary, docs/DESIGN.md §2). The
+ * default theme's concrete colors remain as `var()` fallbacks, so the
+ * same SVG is standalone-valid outside any host. Tokens with no host
+ * equivalent (series2, the 3-D surface shades, wire) stay concrete.
+ * @type {Record<string, string>}
+ */
+export declare const HOST_VARS: Record<string, string>;
+/**
+ * Resolve a theme name or override object. The name `'host'` resolves the
+ * default tokens linked to the host token vocabulary via {@link HOST_VARS}.
+ * @param {string | Record<string, any>} [nameOrOverrides]
+ * @returns {{ name: string, tokens: Record<string, string>, cssVars: Record<string, string> }}
+ */
+export declare function createTheme(nameOrOverrides?: string | Record<string, any>): {
+    name: string;
+    tokens: Record<string, string>;
+    cssVars: Record<string, string>;
+};
+export { THEMES };

package/dist/types/to-expr.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @file `toExpression(ast)` — the canonical printer. It is a **round-trip
+ * fixed point**: `parseExpression(toExpression(ast))` deep-equals
+ * `ast` for every AST the parser can produce. Parentheses are emitted
+ * from operator precedence/associativity only where removing them would
+ * change the parse; numbers print in canonical decimal (the AST never
+ * carried their original radix).
+ */
+/**
+ * @param {any} node
+ * @returns {string}
+ */
+export declare function toExpression(node: any): string;

package/dist/types/utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @file Small shared helpers for the calc engine.
+ *
+ * The content hash is the suite's single fingerprint primitive, so calc
+ * re-exports the one implementation from `@jarenjs/core` rather than
+ * carrying its own copy: equal content hits the same O(1) fast path
+ * (vnode `key`, memo key) everywhere downstream.
+ */
+export { hashContent } from '@jarenjs/core/string';

package/docs/CALC-FORMAT.md

@@ -0,0 +1,79 @@
+# CALC-FORMAT — the `@jarenjs/calc` expression AST & mode contract
+
+`@jarenjs/calc` is a two-layer package: a pure
+**engine** (`src/*`, knows only `@jarenjs/core` + `@jarenjs/view`) and a
+**component** (`src/component/`, adds `@jarenjs/app` + `@jarenjs/forms`).
+This document is the engine contract.
+
+## Expression AST
+
+`parseExpression(text) → ExprAST` is a char-offset recursive-descent,
+precedence-climbing parser (no `eval`, no `new Function`). Nodes are
+monomorphic plain objects tagged by `type`; the AST is **geometry-free**
+and does not preserve a literal's radix or source spacing. Node kinds:
+
+| kind | shape |
+|------|-------|
+| `num` | `{ type:'num', value }` |
+| `const` | `{ type:'const', name }` — `pi`,`e`,`phi`,`tau`,`inf`,`nan` (+ `π φ τ`) |
+| `var` | `{ type:'var', name }` — free identifiers (`x`,`y`,`ans`,…) |
+| `unary` | `{ type:'unary', op, arg }` — `- + ~` (prefix) |
+| `postfix` | `{ type:'postfix', op, arg }` — `!` (factorial), `%` (percent) |
+| `binary` | `{ type:'binary', op, left, right }` — `+ - * / ^ & \| << >>` |
+| `call` | `{ type:'call', name, args }` |
+
+The schema `schemas/jaren-calc-ast.schema.json` (draft-neutral) validates it.
+
+### Grammar / precedence (low → high)
+
+`|` → `&` → `<< >>` → `+ -` → `* /` → prefix `- + ~` → `^` (right-assoc) →
+postfix `! %` → primary. Power binds tighter than unary minus
+(`-2^2 = -(2^2)`); `^` is exponentiation in **every** mode.
+
+### Round-trip fixed point
+
+`toExpression(ast)` is a canonical printer for which
+`parseExpression(toExpression(ast))` deep-equals `ast` across the fixture
+corpus, and `toExpression` is idempotent on its own output. Parentheses
+are emitted from precedence/associativity only where they change the parse.
+
+## Compilation & evaluation
+
+`compileExpr(ast, { env }) → (scope) => number` bakes every dispatch
+decision into a nested closure (second compiler stage). `evaluate(source,
+scope?, { env }?)` is the error-safe front door, returning
+`{ ok:true, value } | { ok:false, error:{ message, line?, column? } }` —
+it never throws into the app path. `scope` supplies variables (`x`, `y`,
+`ans`, …) and runtime flags (`angleMode`, `wordBits`, `signed`).
+
+**Environments** (the binding sets a mode resolves against): `defaultEnv()`
+is float/scientific (angle-aware trig, `^` = power); `programmerEnv()`
+overrides `& | << >> ~` with word-masked BigInt math from
+`@jarenjs/core/math/word.js` and adds `and/or/xor/not/shl/shr/rol/ror/mod`.
+
+> Bitwise **XOR** is the `xor(a, b)` function (not an infix operator), so
+> `^` stays exponentiation everywhere. Programmer results are surfaced as
+> `Number`; values beyond 2^53 lose precision when read back as a float —
+> the four-base display uses `word.js` on BigInt directly and stays exact.
+
+## Modes
+
+Each mode (`standard`, `scientific`, `programmer`, `financial`,
+`converter`) is a data-driven descriptor: a keypad/panel (`{ label, k,
+tone?, span? }` rows, where `k` is the token appended to the expression
+entry or a command `clear`/`back`/`equals`), a function-binding env, and a
+formatter. `financial` holds **no formulas** (it orchestrates
+`@jarenjs/core/finance` via `solveTvm`/`buildAmortization`/`npvOf`/`irrOf`);
+`converter` holds **no factors** (it orchestrates `@jarenjs/core/convert`
+via `convertValue`, currency included).
+
+## Plotting
+
+`plot2d`/`plot3d` (and `calcToVnode`) produce pure-vnode SVG rooted at
+`['svg', …]`. They build a deterministic **scene** (geometry as plain JSON
+— golden-testable) then render it. 2D compiles `f(x)` once, samples into a
+`Float64Array`, maps to the viewport and breaks the path on NaN/±Inf and
+asymptote jumps. 3D samples `z = f(x,y)` on a grid, rotates/projects with
+the core `mat4`/`project.js` kernel, builds quads, **depth-sorts
+back-to-front (painter's algorithm)** and shades by height.
+`toSvgString(vnode)` gives a standalone SSR string.

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@jarenjs/calc",
+  "private": false,
+  "version": "0.34.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./component": {
+      "types": "./dist/types/component/index.d.ts",
+      "default": "./src/component/index.js"
+    },
+    "./theme": {
+      "types": "./dist/types/theme.d.ts",
+      "default": "./src/theme.js"
+    },
+    "./styles/calc.css": "./styles/calc.css",
+    "./schemas/*": "./schemas/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/types/",
+    "src/",
+    "docs/",
+    "schemas/",
+    "styles/"
+  ],
+  "description": "A native, headless multi-mode calculator (standard / programmer / scientific / financial / converter) with x·y and x·y·z plotting rendered as pure-vnode SVG through @jarenjs/view — a two-stage expression compiler (parseExpression ⇄ toExpression), built on @jarenjs/core (math/finance/convert) and driven as an @jarenjs/app document.",
+  "author": "joham",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jklarenbeek/jarenjs.git",
+    "directory": "components/calc"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "jaren",
+    "json",
+    "calculator",
+    "expression",
+    "parser",
+    "plot",
+    "svg",
+    "headless",
+    "finance",
+    "units"
+  ],
+  "scripts": {
+    "build": "npm run build:types",
+    "build:types": "tsc -p tsconfig.json",
+    "prepack": "npm run build:types"
+  },
+  "dependencies": {
+    "@jarenjs/core": "^0.34.0",
+    "@jarenjs/view": "^0.34.0",
+    "@jarenjs/forms": "^0.34.0",
+    "@jarenjs/app": "^0.34.0"
+  }
+}

package/schemas/financial-inputs.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jarenjs.dev/schemas/financial-inputs.schema.json",
+  "title": "Time Value of Money",
+  "type": "object",
+  "properties": {
+    "nper": { "type": "number", "title": "N — number of periods", "minimum": 0 },
+    "rate": { "type": "number", "title": "I/Y — interest % per period" },
+    "pv": { "type": "number", "title": "PV — present value" },
+    "pmt": { "type": "number", "title": "PMT — payment" },
+    "fv": { "type": "number", "title": "FV — future value" },
+    "solveFor": { "title": "Solve for", "enum": ["pmt", "pv", "fv", "nper", "rate"] }
+  },
+  "required": ["solveFor"]
+}

package/schemas/jaren-calc-ast.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jarenjs.dev/schemas/jaren-calc-ast.schema.json",
+  "title": "Jaren calc expression AST",
+  "description": "The geometry-free expression AST produced by parseExpression and consumed by compileExpr / toExpression. Draft-neutral (no $ref siblings, no unevaluated*, no $dynamic*).",
+  "$ref": "#/$defs/node",
+  "$defs": {
+    "node": {
+      "oneOf": [
+        { "$ref": "#/$defs/num" },
+        { "$ref": "#/$defs/const" },
+        { "$ref": "#/$defs/var" },
+        { "$ref": "#/$defs/unary" },
+        { "$ref": "#/$defs/postfix" },
+        { "$ref": "#/$defs/binary" },
+        { "$ref": "#/$defs/call" }
+      ]
+    },
+    "num": {
+      "type": "object",
+      "required": ["type", "value"],
+      "properties": {
+        "type": { "const": "num" },
+        "value": { "type": "number" }
+      },
+      "additionalProperties": false
+    },
+    "const": {
+      "type": "object",
+      "required": ["type", "name"],
+      "properties": {
+        "type": { "const": "const" },
+        "name": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "var": {
+      "type": "object",
+      "required": ["type", "name"],
+      "properties": {
+        "type": { "const": "var" },
+        "name": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "unary": {
+      "type": "object",
+      "required": ["type", "op", "arg"],
+      "properties": {
+        "type": { "const": "unary" },
+        "op": { "enum": ["-", "+", "~"] },
+        "arg": { "$ref": "#/$defs/node" }
+      },
+      "additionalProperties": false
+    },
+    "postfix": {
+      "type": "object",
+      "required": ["type", "op", "arg"],
+      "properties": {
+        "type": { "const": "postfix" },
+        "op": { "enum": ["!", "%"] },
+        "arg": { "$ref": "#/$defs/node" }
+      },
+      "additionalProperties": false
+    },
+    "binary": {
+      "type": "object",
+      "required": ["type", "op", "left", "right"],
+      "properties": {
+        "type": { "const": "binary" },
+        "op": { "enum": ["+", "-", "*", "/", "^", "&", "|", "<<", ">>"] },
+        "left": { "$ref": "#/$defs/node" },
+        "right": { "$ref": "#/$defs/node" }
+      },
+      "additionalProperties": false
+    },
+    "call": {
+      "type": "object",
+      "required": ["type", "name", "args"],
+      "properties": {
+        "type": { "const": "call" },
+        "name": { "type": "string" },
+        "args": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/node" }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/jaren-calc-state.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jarenjs.dev/schemas/jaren-calc-state.schema.json",
+  "title": "Jaren calc state slice",
+  "description": "The plain-JSON $.calc state slice. Draft-neutral.",
+  "type": "object",
+  "properties": {
+    "mode": { "enum": ["standard", "scientific", "programmer", "financial", "converter"] },
+    "entry": { "type": "string" },
+    "ans": { "type": "number" },
+    "memory": { "type": "number" },
+    "angleMode": { "enum": ["rad", "deg", "grad"] },
+    "base": { "enum": ["HEX", "DEC", "OCT", "BIN"] },
+    "wordBits": { "enum": [8, 16, 32, 64] },
+    "signed": { "type": "boolean" },
+    "tape": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": { "expr": { "type": "string" }, "result": { "type": "string" } }
+      }
+    },
+    "plot": {
+      "type": "object",
+      "properties": {
+        "expr": { "type": "string" },
+        "kind": { "enum": ["2d", "3d"] }
+      }
+    },
+    "fin": { "$ref": "financial-inputs.schema.json" },
+    "conv": {
+      "type": "object",
+      "properties": {
+        "dimension": { "type": "string" },
+        "from": { "type": "string" },
+        "to": { "type": "string" },
+        "value": { "type": "number" }
+      }
+    },
+    "rates": {
+      "type": "object",
+      "properties": {
+        "base": { "type": "string" },
+        "rates": { "type": "object" },
+        "at": { "type": "number" },
+        "stale": { "type": "boolean" },
+        "status": { "type": "string" }
+      }
+    }
+  },
+  "required": ["mode", "entry"]
+}

package/src/ast.js

@@ -0,0 +1,96 @@
+//@ts-check
+/**
+ * @file The expression AST. Monomorphic node
+ * constructors — one plain-object shape per kind — so the compiler and
+ * printer branch on a single `type` tag and the reconciler/`deepEqual`
+ * round-trip stays cheap. The AST is **geometry-free**: it carries no
+ * layout, no source formatting (not even a literal's original radix), so
+ * that `parseExpression(toExpression(ast))` deep-equals `ast`. Meaning is
+ * imposed later — by `compileExpr` (evaluation) or the plotter
+ * (projection), never by the parser.
+ */
+
+export const CALC_AST_VERSION = '0.13.0';
+
+/** Numeric literal (value only — the radix/format is not preserved). */
+export function num(value) {
+  return { type: 'num', value: +value };
+}
+
+/** A named constant (`pi`, `e`, `phi`, `tau`, `inf`, `nan`). */
+export function constant(name) {
+  return { type: 'const', name };
+}
+
+/** A variable / free identifier (`x`, `y`, `ans`, `mem`). */
+export function variable(name) {
+  return { type: 'var', name };
+}
+
+/** A prefix unary node (`-`, `+`, `~`). */
+export function unary(op, arg) {
+  return { type: 'unary', op, arg };
+}
+
+/** A postfix node (`!` factorial, `%` percent). */
+export function postfix(op, arg) {
+  return { type: 'postfix', op, arg };
+}
+
+/** A binary node (`+ - * / ^ & | << >>`). */
+export function binary(op, left, right) {
+  return { type: 'binary', op, left, right };
+}
+
+/** A function call (`sin(x)`, `log(2, 8)`, `xor(a, b)`). */
+export function call(name, args) {
+  return { type: 'call', name, args };
+}
+
+/**
+ * Free identifiers that always denote a constant rather than a variable.
+ * @type {Record<string, number>}
+ */
+export const CONSTANTS = {
+  pi: Math.PI,
+  π: Math.PI,
+  tau: Math.PI * 2,
+  τ: Math.PI * 2,
+  e: Math.E,
+  phi: (1 + Math.sqrt(5)) / 2,
+  φ: (1 + Math.sqrt(5)) / 2,
+  inf: Infinity,
+  nan: NaN,
+};
+
+/** Is `name` a known constant identifier? */
+export function isConstant(name) {
+  return Object.prototype.hasOwnProperty.call(CONSTANTS, name);
+}
+
+/**
+ * Structural equality for ASTs (used by the round-trip fixed-point
+ * tests). NaN compares equal to NaN so `nan` literals round-trip.
+ * @param {any} a @param {any} b
+ * @returns {boolean}
+ */
+export function astEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a === 'number' && typeof b === 'number') {
+    return a === b || (Number.isNaN(a) && Number.isNaN(b));
+  }
+  if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') return false;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) if (!astEqual(a[i], b[i])) return false;
+    return true;
+  }
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  for (const k of ka) {
+    if (!Object.prototype.hasOwnProperty.call(b, k)) return false;
+    if (!astEqual(a[k], b[k])) return false;
+  }
+  return true;
+}

package/src/compile.js

@@ -0,0 +1,119 @@
+//@ts-check
+/**
+ * @file `compileExpr(ast, opts) → (scope) => number`. The second stage of
+ * the two-stage compiler: every dispatch decision — which operator
+ * closure, which function, whether an identifier is a constant — is made
+ * once, here, and baked into a nested closure. Evaluation then does no
+ * lookups on the hot path. No `eval`, no `new Function` (CSP-safe).
+ *
+ * `evaluate(source, scope?, opts?)` is the error-safe front door: it
+ * parses, compiles and runs, returning a tagged `{ ok, value } | { ok:
+ * false, error }` result so the app/render path never throws.
+ */
+
+import { parseExpression } from './parser/index.js';
+import { defaultEnv } from './env.js';
+import { CalcParseError } from './errors.js';
+
+/**
+ * Compile an AST against an environment.
+ * @param {any} ast
+ * @param {{ env?: any }} [opts]
+ * @returns {(scope?: any) => number}
+ */
+export function compileExpr(ast, opts = {}) {
+  const env = opts.env ?? defaultEnv();
+  return build(ast, env);
+}
+
+/**
+ * @param {any} node
+ * @param {any} env
+ * @returns {(scope?: any) => number}
+ */
+function build(node, env) {
+  switch (node.type) {
+    case 'num': {
+      const v = node.value;
+      return () => v;
+    }
+    case 'const': {
+      const name = node.name;
+      const v = env.constants[name];
+      if (v === undefined) throw new CalcParseError(`unknown constant '${name}'`);
+      return () => v;
+    }
+    case 'var': {
+      const name = node.name;
+      return (scope) => {
+        const v = scope ? scope[name] : undefined;
+        return v === undefined ? NaN : +v;
+      };
+    }
+    case 'unary': {
+      const op = env.unops[node.op];
+      if (op === undefined) throw new CalcParseError(`unknown unary operator '${node.op}'`);
+      const arg = build(node.arg, env);
+      return (scope) => op(arg(scope), scope);
+    }
+    case 'postfix': {
+      const op = env.postops[node.op];
+      if (op === undefined) throw new CalcParseError(`unknown postfix operator '${node.op}'`);
+      const arg = build(node.arg, env);
+      return (scope) => op(arg(scope), scope);
+    }
+    case 'binary': {
+      const op = env.binops[node.op];
+      if (op === undefined) throw new CalcParseError(`unknown operator '${node.op}'`);
+      const l = build(node.left, env);
+      const r = build(node.right, env);
+      return (scope) => op(l(scope), r(scope), scope);
+    }
+    case 'call': {
+      const fn = env.funcs[node.name];
+      if (fn === undefined) throw new CalcParseError(`unknown function '${node.name}'`);
+      const args = node.args.map((a) => build(a, env));
+      return (scope) => fn(args.map((a) => a(scope)), scope);
+    }
+    default:
+      throw new CalcParseError(`cannot compile node '${node.type}'`);
+  }
+}
+
+/**
+ * @typedef {object} EvalOk
+ * @property {true} ok
+ * @property {number} value
+ */
+/**
+ * @typedef {object} EvalErr
+ * @property {false} ok
+ * @property {{ message: string, line?: number, column?: number }} error
+ */
+
+/**
+ * Parse + compile + evaluate a source expression, error-safe.
+ * @param {string} source
+ * @param {any} [scope]
+ * @param {{ env?: any }} [opts]
+ * @returns {EvalOk | EvalErr}
+ */
+export function evaluate(source, scope = {}, opts = {}) {
+  try {
+    const ast = parseExpression(source, opts);
+    const fn = compileExpr(ast, opts);
+    const value = fn(scope);
+    return { ok: true, value };
+  }
+  catch (err) {
+    const e = /** @type {any} */ (err);
+    return {
+      ok: false,
+      error: {
+        message: e && e.message ? e.message : String(err),
+        line: e instanceof CalcParseError ? e.line : undefined,
+        column: e instanceof CalcParseError ? e.column : undefined,
+      },
+    };
+  }
+}