@jarenjs/calc 0.34.0

package/src/modes/scientific.js

@@ -0,0 +1,31 @@
+//@ts-check
+/**
+ * @file The scientific mode kernel: the standard keypad plus the
+ * A1 transcendentals as function-insert keys, constants, factorial and an
+ * angle-mode toggle. It binds the same float environment as standard —
+ * the transcendentals were already in it — so no formulas live here.
+ */
+
+import { defaultEnv } from '../env.js';
+import { format } from './standard.js';
+
+/** @type {Array<Array<{label:string,k:string,tone?:string,span?:number}>>} */
+export const KEYPAD = [
+  [{ label: 'sin', k: 'sin(', tone: 'fn' }, { label: 'cos', k: 'cos(', tone: 'fn' }, { label: 'tan', k: 'tan(', tone: 'fn' }, { label: 'C', k: 'clear', tone: 'clear' }, { label: '⌫', k: 'back', tone: 'clear' }],
+  [{ label: 'asin', k: 'asin(', tone: 'fn' }, { label: 'acos', k: 'acos(', tone: 'fn' }, { label: 'atan', k: 'atan(', tone: 'fn' }, { label: '(', k: '(' }, { label: ')', k: ')' }],
+  [{ label: 'ln', k: 'ln(', tone: 'fn' }, { label: 'log', k: 'log(', tone: 'fn' }, { label: '√', k: 'sqrt(', tone: 'fn' }, { label: '7', k: '7' }, { label: '8', k: '8' }],
+  [{ label: 'eˣ', k: 'exp(', tone: 'fn' }, { label: 'x!', k: '!', tone: 'op' }, { label: '^', k: '^', tone: 'op' }, { label: '9', k: '9' }, { label: '÷', k: '/', tone: 'op' }],
+  [{ label: 'π', k: 'pi', tone: 'const' }, { label: 'e', k: 'e', tone: 'const' }, { label: '4', k: '4' }, { label: '5', k: '5' }, { label: '6', k: '6' }],
+  [{ label: '×', k: '*', tone: 'op' }, { label: '1', k: '1' }, { label: '2', k: '2' }, { label: '3', k: '3' }, { label: '−', k: '-', tone: 'op' }],
+  [{ label: '0', k: '0' }, { label: '.', k: '.' }, { label: 'ans', k: 'ans' }, { label: '+', k: '+', tone: 'op' }, { label: '=', k: 'equals', tone: 'equals' }],
+];
+
+export const scientificMode = {
+  id: 'scientific',
+  label: 'Scientific',
+  env: defaultEnv(),
+  keypad: KEYPAD,
+  format,
+  /** angle modes offered by the toggle */
+  angleModes: ['rad', 'deg', 'grad'],
+};

package/src/modes/standard.js

@@ -0,0 +1,39 @@
+//@ts-check
+/**
+ * @file The standard mode kernel: a data-driven
+ * keypad descriptor, the function-binding environment the compiler uses,
+ * and a display formatter. A key is `{ label, k, tone?, span? }`; `k` is
+ * the token appended to the expression entry, or a command (`=`, `C`,
+ * `back`). Switching mode is just a patch of `$.calc.mode`.
+ */
+
+import { formatNumber } from '@jarenjs/core/math';
+import { defaultEnv } from '../env.js';
+
+/** @type {Array<Array<{label:string,k:string,tone?:string,span?:number}>>} */
+export const KEYPAD = [
+  [{ label: 'C', k: 'clear', tone: 'clear' }, { label: '⌫', k: 'back', tone: 'clear' }, { label: '(', k: '(' }, { label: ')', k: ')' }],
+  [{ label: '7', k: '7' }, { label: '8', k: '8' }, { label: '9', k: '9' }, { label: '÷', k: '/', tone: 'op' }],
+  [{ label: '4', k: '4' }, { label: '5', k: '5' }, { label: '6', k: '6' }, { label: '×', k: '*', tone: 'op' }],
+  [{ label: '1', k: '1' }, { label: '2', k: '2' }, { label: '3', k: '3' }, { label: '−', k: '-', tone: 'op' }],
+  [{ label: '0', k: '0' }, { label: '.', k: '.' }, { label: '%', k: '%' }, { label: '+', k: '+', tone: 'op' }],
+  [{ label: 'ans', k: 'ans' }, { label: '^', k: '^', tone: 'op' }, { label: '=', k: 'equals', tone: 'equals', span: 2 }],
+];
+
+/**
+ * Format a numeric result for the display.
+ * @param {number} value @param {any} [state]
+ * @returns {string}
+ */
+export function format(value, state) {
+  const group = state && state.group === true;
+  return formatNumber(value, { notation: 'auto', precision: 12, group });
+}
+
+export const standardMode = {
+  id: 'standard',
+  label: 'Standard',
+  env: defaultEnv(),
+  keypad: KEYPAD,
+  format,
+};

package/src/parser/index.js

@@ -0,0 +1,220 @@
+//@ts-check
+/**
+ * @file `parseExpression(text, opts) → ExprAST`. A char-offset
+ * recursive-descent, precedence-climbing parser in the repository idiom
+ * (module-const sticky regexes for the number/identifier leaves, a
+ * `fail(msg, pos)` that raises `CalcParseError` with 1-based line/column).
+ * No `eval`, no per-parse `RegExp` allocation.
+ *
+ * Grammar (low → high precedence), all left-associative except power
+ * (right) and the prefix unaries:
+ *
+ *   or      := and    ('|' and)*
+ *   and     := shift  ('&' shift)*
+ *   shift   := add    (('<<'|'>>') add)*
+ *   add     := mul    (('+'|'-') mul)*
+ *   mul     := unary  (('*'|'/') unary)*
+ *   unary   := ('-'|'+'|'~') unary | power
+ *   power   := postfix ('^' unary)?           // right-assoc via unary
+ *   postfix := primary ('!' | '%')*
+ *   primary := number | const | ident | ident '(' args ')' | '(' or ')'
+ *
+ * Number bases (`0x`/`0o`/`0b`) and scientific notation are recognized at
+ * the leaf; the AST keeps only the numeric value.
+ */
+
+import { num, constant, variable, unary, postfix, binary, call, isConstant } from '../ast.js';
+import { CalcParseError } from '../errors.js';
+
+/** Sticky number matcher: hex / octal / binary / decimal-with-exponent. */
+const RE_NUMBER = /0[xX][0-9a-fA-F]+|0[oO][0-7]+|0[bB][01]+|(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/y;
+/** Sticky identifier matcher (ascii idents plus the greek constant glyphs). */
+const RE_IDENT = /[A-Za-z_][A-Za-z0-9_]*|[πφτ]/y;
+
+/** Binary operator precedences (higher binds tighter); power is separate. */
+const BINOPS = {
+  '|': 1, '&': 2, '<<': 3, '>>': 3, '+': 4, '-': 4, '*': 5, '/': 5,
+};
+
+class Parser {
+  /** @param {string} text */
+  constructor(text) {
+    this.s = text;
+    this.n = text.length;
+    this.p = 0;
+  }
+
+  /** @returns {never} */
+  fail(message, pos = this.p) {
+    let line = 1;
+    let col = 1;
+    for (let i = 0; i < pos && i < this.n; i++) {
+      if (this.s.charCodeAt(i) === 10) { line++; col = 1; } else col++;
+    }
+    throw new CalcParseError(message, line, col, pos);
+  }
+
+  skipWs() {
+    while (this.p < this.n) {
+      const c = this.s.charCodeAt(this.p);
+      if (c === 0x20 || c === 0x09 || c === 0x0a || c === 0x0d) this.p++;
+      else break;
+    }
+  }
+
+  /** Peek the operator at the cursor (no consume): returns its string or null. */
+  peekOp() {
+    const c = this.s.charCodeAt(this.p);
+    const c2 = this.p + 1 < this.n ? this.s.charCodeAt(this.p + 1) : 0;
+    if (c === 0x3c && c2 === 0x3c) return '<<';
+    if (c === 0x3e && c2 === 0x3e) return '>>';
+    if (c === 0x7c) return '|';
+    if (c === 0x26) return '&';
+    if (c === 0x2b) return '+';
+    if (c === 0x2d) return '-';
+    if (c === 0x2a) return '*';
+    if (c === 0x2f) return '/';
+    return null;
+  }
+
+  parse() {
+    this.skipWs();
+    if (this.p >= this.n) this.fail('empty expression');
+    const node = this.parseBinary(1);
+    this.skipWs();
+    if (this.p < this.n) this.fail(`unexpected '${this.s[this.p]}'`);
+    return node;
+  }
+
+  /** Precedence climbing over BINOPS (power/unary handled below). */
+  parseBinary(minPrec) {
+    let left = this.parseUnary();
+    for (;;) {
+      this.skipWs();
+      const op = this.peekOp();
+      if (op === null) break;
+      const prec = BINOPS[op];
+      if (prec === undefined || prec < minPrec) break;
+      this.p += op.length;
+      const right = this.parseBinary(prec + 1); // all these are left-assoc
+      left = binary(op, left, right);
+    }
+    return left;
+  }
+
+  parseUnary() {
+    this.skipWs();
+    const c = this.s.charCodeAt(this.p);
+    if (c === 0x2d || c === 0x2b || c === 0x7e) { // - + ~
+      const op = this.s[this.p];
+      this.p++;
+      return unary(op, this.parseUnary());
+    }
+    return this.parsePower();
+  }
+
+  parsePower() {
+    const base = this.parsePostfix();
+    this.skipWs();
+    if (this.s.charCodeAt(this.p) === 0x5e) { // ^
+      this.p++;
+      return binary('^', base, this.parseUnary()); // right-assoc
+    }
+    return base;
+  }
+
+  parsePostfix() {
+    let node = this.parsePrimary();
+    for (;;) {
+      this.skipWs();
+      const c = this.s.charCodeAt(this.p);
+      if (c === 0x21) { this.p++; node = postfix('!', node); } // !
+      else if (c === 0x25) { this.p++; node = postfix('%', node); } // %
+      else break;
+    }
+    return node;
+  }
+
+  parsePrimary() {
+    this.skipWs();
+    if (this.p >= this.n) this.fail('unexpected end of input');
+    const c = this.s.charCodeAt(this.p);
+
+    if (c === 0x28) { // (
+      this.p++;
+      const inner = this.parseBinary(1);
+      this.skipWs();
+      if (this.s.charCodeAt(this.p) !== 0x29) this.fail("expected ')'");
+      this.p++;
+      return inner;
+    }
+
+    // number
+    if ((c >= 0x30 && c <= 0x39) || c === 0x2e) { // digit or '.'
+      RE_NUMBER.lastIndex = this.p;
+      const m = RE_NUMBER.exec(this.s);
+      if (m === null || m.index !== this.p) this.fail('invalid number');
+      this.p += m[0].length;
+      return num(parseNumericLiteral(m[0]));
+    }
+
+    // identifier: constant, variable, or function call
+    RE_IDENT.lastIndex = this.p;
+    const mi = RE_IDENT.exec(this.s);
+    if (mi !== null && mi.index === this.p) {
+      const name = mi[0];
+      this.p += name.length;
+      this.skipWs();
+      if (this.s.charCodeAt(this.p) === 0x28) { // '(' → call
+        this.p++;
+        const args = this.parseArgs();
+        return call(name, args);
+      }
+      return isConstant(name) ? constant(name) : variable(name);
+    }
+
+    this.fail(`unexpected '${this.s[this.p]}'`);
+  }
+
+  parseArgs() {
+    const args = [];
+    this.skipWs();
+    if (this.s.charCodeAt(this.p) === 0x29) { this.p++; return args; } // empty
+    for (;;) {
+      args.push(this.parseBinary(1));
+      this.skipWs();
+      const c = this.s.charCodeAt(this.p);
+      if (c === 0x2c) { this.p++; continue; } // ,
+      if (c === 0x29) { this.p++; break; } // )
+      this.fail("expected ',' or ')'");
+    }
+    return args;
+  }
+}
+
+/**
+ * Interpret a matched numeric literal (respecting 0x/0o/0b prefixes).
+ * @param {string} lit
+ * @returns {number}
+ */
+function parseNumericLiteral(lit) {
+  if (lit.length > 1 && lit[0] === '0') {
+    const k = lit[1];
+    if (k === 'x' || k === 'X') return parseInt(lit.slice(2), 16);
+    if (k === 'o' || k === 'O') return parseInt(lit.slice(2), 8);
+    if (k === 'b' || k === 'B') return parseInt(lit.slice(2), 2);
+  }
+  return Number(lit);
+}
+
+/**
+ * Parse an expression string into an `ExprAST`.
+ * @param {string} text
+ * @param {{ [k: string]: any }} [opts]
+ * @returns {any}
+ */
+export function parseExpression(text, opts = {}) {
+  void opts; // reserved for future mode gating (see CALC-FORMAT.md)
+  if (typeof text !== 'string') throw new CalcParseError('expression must be a string');
+  return new Parser(text).parse();
+}

package/src/plot/plot2d.js

@@ -0,0 +1,221 @@
+//@ts-check
+/**
+ * @file The x·y plotter. `plot2d` compiles `f(x)`
+ * ONCE, samples the domain into `Float64Array` buffers, maps them to the
+ * viewport with a standard linear remap, and emits axes/grid/ticks plus one
+ * `<path>` polyline per series — breaking the path on NaN/±Inf and at
+ * asymptote jumps. The intermediate **scene** is geometry-as-plain-JSON
+ * (deterministic → golden-geometry tests); `scene2dToVnode` turns it into
+ * pure-vnode SVG.
+ */
+
+import { Float64, remap, niceStep } from '@jarenjs/core/math';
+import { svgRoot, line, path, textAt, polylinePath } from '@jarenjs/view/helpers';
+import { parseExpression } from '../parser/index.js';
+import { compileExpr } from '../compile.js';
+import { defaultEnv } from '../env.js';
+import { createTheme } from '../theme.js';
+import { contentKey } from '@jarenjs/core/object';
+
+const DEFAULTS = {
+  width: 480,
+  height: 320,
+  samples: 240,
+  padding: { left: 40, right: 12, top: 12, bottom: 24 },
+  domain: [-10, 10],
+  variable: 'x',
+};
+
+/**
+ * Evenly-spaced "nice" ticks spanning [min, max].
+ * @param {number} min @param {number} max @param {number} count
+ * @returns {number[]}
+ */
+function niceTicks(min, max, count) {
+  if (!(max > min)) return [min];
+  // A non-positive per-step span (a degenerate `count`) falls back to unit
+  // ticks rather than letting the ladder answer with NaN.
+  const raw = (max - min) / count;
+  const step = raw > 0 ? niceStep(raw) : 1;
+  const start = Math.ceil(min / step) * step;
+  const ticks = [];
+  for (let v = start; v <= max + step * 1e-9; v += step) {
+    ticks.push(Math.abs(v) < step * 1e-9 ? 0 : v);
+  }
+  return ticks;
+}
+
+/**
+ * @typedef {object} Plot2dConfig
+ * @property {string|string[]} [expr] one or more source expressions
+ * @property {[number,number]} [domain]
+ * @property {[number,number]} [range] omit for auto-range
+ * @property {number} [samples]
+ * @property {number} [width] @property {number} [height]
+ * @property {string} [variable] independent variable name (default 'x')
+ * @property {any} [scope] extra variables in scope
+ * @property {any} [env] evaluation environment (default float)
+ * @property {any} [theme]
+ */
+
+/**
+ * Build the geometry-as-JSON scene.
+ * @param {string|string[]|Plot2dConfig} exprOrConfig
+ * @param {Plot2dConfig} [options]
+ * @returns {any}
+ */
+export function buildScene2d(exprOrConfig, options = {}) {
+  /** @type {Plot2dConfig} */
+  const cfg = typeof exprOrConfig === 'string' || Array.isArray(exprOrConfig)
+    ? { ...options, expr: exprOrConfig }
+    : { ...options, ...exprOrConfig };
+
+  const width = cfg.width ?? DEFAULTS.width;
+  const height = cfg.height ?? DEFAULTS.height;
+  const pad = DEFAULTS.padding;
+  const plot = { left: pad.left, right: width - pad.right, top: pad.top, bottom: height - pad.bottom };
+  const [xmin, xmax] = cfg.domain ?? DEFAULTS.domain;
+  const samples = Math.max(2, cfg.samples ?? DEFAULTS.samples);
+  const varName = cfg.variable ?? DEFAULTS.variable;
+  const env = cfg.env ?? defaultEnv();
+  const exprs = Array.isArray(cfg.expr) ? cfg.expr : (cfg.expr != null ? [cfg.expr] : []);
+
+  // sample each series into typed-array buffers (compile once)
+  const xs = new Float64Array(samples);
+  for (let i = 0; i < samples; i++) xs[i] = remap(i, 0, samples - 1, xmin, xmax);
+
+  const rawSeries = [];
+  for (const src of exprs) {
+    let fn;
+    try {
+      fn = compileExpr(parseExpression(String(src)), { env });
+    }
+    catch {
+      rawSeries.push({ source: String(src), ys: null });
+      continue;
+    }
+    const ys = new Float64Array(samples);
+    const scope = { ...(cfg.scope ?? {}) };
+    for (let i = 0; i < samples; i++) {
+      scope[varName] = xs[i];
+      const v = +fn(scope);
+      ys[i] = v;
+    }
+    rawSeries.push({ source: String(src), ys });
+  }
+
+  // auto-range from finite samples
+  let [ymin, ymax] = cfg.range ?? [Infinity, -Infinity];
+  if (cfg.range === undefined) {
+    for (const s of rawSeries) {
+      if (s.ys === null) continue;
+      for (let i = 0; i < samples; i++) {
+        const y = s.ys[i];
+        if (Number.isFinite(y)) { if (y < ymin) ymin = y; if (y > ymax) ymax = y; }
+      }
+    }
+    if (!(ymax > ymin)) { ymin = -1; ymax = 1; }
+    const margin = (ymax - ymin) * 0.08;
+    ymin -= margin; ymax += margin;
+  }
+
+  const toScreen = (x, y) => ({
+    x: remap(x, xmin, xmax, plot.left, plot.right),
+    y: remap(y, ymin, ymax, plot.bottom, plot.top),
+  });
+
+  // build screen-space points, breaking on non-finite and asymptote jumps
+  const series = rawSeries.map((s) => {
+    if (s.ys === null) return { source: s.source, points: [], error: true };
+    const points = [];
+    let prevY = null;
+    for (let i = 0; i < samples; i++) {
+      const y = s.ys[i];
+      if (!Number.isFinite(y)) { points.push(null); prevY = null; continue; }
+      const p = toScreen(xs[i], y);
+      if (prevY !== null && Math.abs(p.y - prevY) > (plot.bottom - plot.top)) {
+        points.push(null); // discontinuity: full-height jump
+      }
+      points.push(p);
+      prevY = p.y;
+    }
+    return { source: s.source, points, error: false };
+  });
+
+  const xticks = niceTicks(xmin, xmax, 8).map((v) => ({ value: v, x: remap(v, xmin, xmax, plot.left, plot.right) }));
+  const yticks = niceTicks(ymin, ymax, 6).map((v) => ({ value: v, y: remap(v, ymin, ymax, plot.bottom, plot.top) }));
+  const axisX = (0 >= ymin && 0 <= ymax) ? remap(0, ymin, ymax, plot.bottom, plot.top) : null;
+  const axisY = (0 >= xmin && 0 <= xmax) ? remap(0, xmin, xmax, plot.left, plot.right) : null;
+
+  return {
+    kind: '2d',
+    width, height, plot,
+    domain: [xmin, xmax], range: [ymin, ymax],
+    series, xticks, yticks,
+    axes: { x: axisX, y: axisY },
+  };
+}
+
+/**
+ * Render a 2D scene into a pure-vnode SVG.
+ * @param {any} scene @param {{ theme?: any }} [options]
+ * @returns {any}
+ */
+export function scene2dToVnode(scene, options = {}) {
+  const theme = createTheme(options.theme ?? 'default');
+  const t = theme.tokens;
+  const children = [];
+
+  // grid
+  for (const tick of scene.xticks) {
+    children.push(line(tick.x, scene.plot.top, tick.x, scene.plot.bottom, { stroke: t.grid, 'stroke-width': 1, class: 'calc-grid' }));
+  }
+  for (const tick of scene.yticks) {
+    children.push(line(scene.plot.left, tick.y, scene.plot.right, tick.y, { stroke: t.grid, 'stroke-width': 1, class: 'calc-grid' }));
+  }
+  // axes
+  if (scene.axes.x !== null) {
+    children.push(line(scene.plot.left, scene.axes.x, scene.plot.right, scene.axes.x, { stroke: t.axis, 'stroke-width': 1.5, class: 'calc-axis' }));
+  }
+  if (scene.axes.y !== null) {
+    children.push(line(scene.axes.y, scene.plot.top, scene.axes.y, scene.plot.bottom, { stroke: t.axis, 'stroke-width': 1.5, class: 'calc-axis' }));
+  }
+  // tick labels
+  for (const tick of scene.xticks) {
+    children.push(textAt(tick.x, scene.plot.bottom + 14, formatTick(tick.value), 10, { fill: t.text, 'text-anchor': 'middle', class: 'calc-tick' }));
+  }
+  for (const tick of scene.yticks) {
+    children.push(textAt(scene.plot.left - 4, tick.y + 3, formatTick(tick.value), 10, { fill: t.text, 'text-anchor': 'end', class: 'calc-tick' }));
+  }
+  // series polylines
+  const colors = [t.series1, t.series2, t.series3];
+  scene.series.forEach((s, i) => {
+    const d = polylinePath(s.points);
+    if (d) children.push(path(d, { stroke: colors[i % colors.length], 'stroke-width': 2, fill: 'none', class: 'calc-series' }));
+  });
+
+  // contentKey stable-stringifies, so two structurally equal scenes
+  // share a key regardless of property order (the old JSON.stringify
+  // key was insertion-order fragile).
+  const key = 'p2:' + contentKey({ d: scene.domain, r: scene.range, s: scene.series.map((s) => s.source) });
+  return svgRoot('calc-plot', scene.width, scene.height, theme, children, key);
+}
+
+/** @param {number} v */
+function formatTick(v) {
+  if (v === 0) return '0';
+  const a = Math.abs(v);
+  if (a >= 1e4 || a < 1e-3) return v.toExponential(0);
+  return String(Float64.roundTo(v, 3));
+}
+
+/**
+ * Compile → sample → SVG vnode in one call.
+ * @param {string|string[]|Plot2dConfig} exprOrConfig
+ * @param {Plot2dConfig} [options]
+ * @returns {any}
+ */
+export function plot2d(exprOrConfig, options = {}) {
+  const scene = buildScene2d(exprOrConfig, options);
+  return scene2dToVnode(scene, { theme: options.theme });
+}

package/src/plot/plot3d.js

@@ -0,0 +1,177 @@
+//@ts-check
+/**
+ * @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.
+ */
+
+import { Float64, Vec3f64, Mat4, project3dTo2d, remap } from '@jarenjs/core/math';
+import { lerpColor } from '@jarenjs/core/color';
+import { svgRoot, polygon } from '@jarenjs/view/helpers';
+import { parseExpression } from '../parser/index.js';
+import { compileExpr } from '../compile.js';
+import { defaultEnv } from '../env.js';
+import { createTheme } from '../theme.js';
+import { contentKey } from '@jarenjs/core/object';
+
+const DEFAULTS = {
+  width: 420,
+  height: 360,
+  grid: 24,
+  domainX: [-3, 3],
+  domainY: [-3, 3],
+  yaw: 0.6,
+  pitch: 0.5,
+  variables: ['x', 'y'],
+  distance: 3.2,
+};
+
+/**
+ * @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 function buildScene3d(exprOrConfig, options = {}) {
+  /** @type {Plot3dConfig} */
+  const cfg = typeof exprOrConfig === 'string'
+    ? { ...options, expr: exprOrConfig }
+    : { ...options, ...exprOrConfig };
+
+  const width = cfg.width ?? DEFAULTS.width;
+  const height = cfg.height ?? DEFAULTS.height;
+  const N = Math.max(2, cfg.grid ?? DEFAULTS.grid);
+  const [xmin, xmax] = cfg.domainX ?? DEFAULTS.domainX;
+  const [ymin, ymax] = cfg.domainY ?? DEFAULTS.domainY;
+  const yaw = cfg.yaw ?? DEFAULTS.yaw;
+  const pitch = cfg.pitch ?? DEFAULTS.pitch;
+  const [vx, vy] = cfg.variables ?? DEFAULTS.variables;
+  const env = cfg.env ?? defaultEnv();
+
+  let fn;
+  try {
+    fn = compileExpr(parseExpression(String(cfg.expr ?? '0')), { env });
+  }
+  catch {
+    return { kind: '3d', width, height, quads: [], error: true };
+  }
+
+  // sample z on the grid, tracking z-range for normalization/shading
+  const zs = [];
+  let zmin = Infinity;
+  let zmax = -Infinity;
+  const scope = { ...(cfg.scope ?? {}) };
+  for (let i = 0; i <= N; i++) {
+    const row = [];
+    for (let j = 0; j <= N; j++) {
+      scope[vx] = remap(i, 0, N, xmin, xmax);
+      scope[vy] = remap(j, 0, N, ymin, ymax);
+      const z = +fn(scope);
+      row.push(z);
+      if (Number.isFinite(z)) { if (z < zmin) zmin = z; if (z > zmax) zmax = z; }
+    }
+    zs.push(row);
+  }
+  if (!(zmax > zmin)) { zmin = -1; zmax = 1; }
+
+  // model → view → projection
+  const model = Mat4.multiply(Mat4.rotationX(pitch), Mat4.rotationY(yaw));
+  const view = Mat4.translation(0, 0, -(cfg.distance ?? DEFAULTS.distance));
+  const proj = Mat4.perspective(Math.PI / 3.2, width / height, 0.1, 100);
+  const mvp = Mat4.multiply(proj, Mat4.multiply(view, model));
+  const viewport = { x: 0, y: 0, width, height };
+
+  const toModel = (i, j) => {
+    const nx = remap(i, 0, N, -1.2, 1.2);
+    const ny = remap(j, 0, N, -1.2, 1.2);
+    const nz = Number.isFinite(zs[i][j]) ? remap(zs[i][j], zmin, zmax, -0.7, 0.7) : NaN;
+    return new Vec3f64(nx, nz, ny); // z-height becomes the vertical (world Y)
+  };
+
+  // project every grid vertex once
+  const proj2d = [];
+  for (let i = 0; i <= N; i++) {
+    const row = [];
+    for (let j = 0; j <= N; j++) {
+      const m = toModel(i, j);
+      row.push(Number.isFinite(m.y) ? project3dTo2d(m, mvp, viewport) : null);
+    }
+    proj2d.push(row);
+  }
+
+  // build quads with average depth + height shade
+  const quads = [];
+  for (let i = 0; i < N; i++) {
+    for (let j = 0; j < N; j++) {
+      const a = proj2d[i][j], b = proj2d[i + 1][j], c = proj2d[i + 1][j + 1], d = proj2d[i][j + 1];
+      if (a === null || b === null || c === null || d === null) continue;
+      const depth = (a.z + b.z + c.z + d.z) / 4;
+      const avgZ = (zs[i][j] + zs[i + 1][j] + zs[i + 1][j + 1] + zs[i][j + 1]) / 4;
+      const shade = Float64.clamp(remap(avgZ, zmin, zmax, 0, 1), 0, 1);
+      quads.push({
+        points: [round(a), round(b), round(c), round(d)],
+        depth: Float64.roundTo(depth, 4),
+        shade: Float64.roundTo(shade, 3),
+      });
+    }
+  }
+  // painter's algorithm: farthest first (larger NDC z = farther)
+  quads.sort((p, q) => q.depth - p.depth);
+
+  return {
+    kind: '3d', width, height,
+    zrange: [zmin, zmax],
+    wireframe: cfg.wireframe ?? true,
+    quads,
+  };
+}
+
+/** @param {{x:number,y:number}} p */
+function round(p) {
+  return { x: Float64.roundTo(p.x, 2), y: Float64.roundTo(p.y, 2) };
+}
+
+/**
+ * Render a 3D scene into pure-vnode SVG.
+ * @param {any} scene @param {{ theme?: any }} [options]
+ * @returns {any}
+ */
+export function scene3dToVnode(scene, options = {}) {
+  const theme = createTheme(options.theme ?? 'default');
+  const t = theme.tokens;
+  const children = scene.quads.map((quad) => polygon(quad.points, {
+    fill: lerpColor(t.surfaceLo, t.surfaceHi, quad.shade),
+    stroke: scene.wireframe ? t.wire : 'none',
+    'stroke-width': scene.wireframe ? 0.4 : 0,
+    'stroke-linejoin': 'round',
+    class: 'calc-face',
+  }));
+  const key = 'p3:' + contentKey({ z: scene.zrange, n: scene.quads.length, q0: scene.quads[0] });
+  return svgRoot('calc-plot', scene.width, scene.height, theme, children, key);
+}
+
+/**
+ * Compile → sample → project → SVG vnode in one call.
+ * @param {string|Plot3dConfig} exprOrConfig
+ * @param {Plot3dConfig} [options]
+ * @returns {any}
+ */
+export function plot3d(exprOrConfig, options = {}) {
+  const scene = buildScene3d(exprOrConfig, options);
+  return scene3dToVnode(scene, { theme: options.theme });
+}