@crossworks/content-core 0.230.43

package/src/page-toc.ts

@@ -0,0 +1,89 @@
+/**
+ * buildPageToc — extract a navigable outline from a page's ProseMirror JSON:
+ * headings (h1–h3) and sub-page cards (childPage), in document order. Pure +
+ * leaf (no DB import) so both the client editor and the server-rendered public
+ * page can build the same outline, and it's unit-testable.
+ *
+ * Indentation (`depth`):
+ *   - a heading sits at `level - 1` (h1 → 0, h2 → 1, h3 → 2);
+ *   - a sub-page sits one level deeper than the heading section it falls under
+ *     (i.e. `depth = lastHeadingLevel`; 0 when it precedes any heading), so
+ *     sub-pages nest visually inside their section.
+ *
+ * Each entry carries the block's stable `attrs.id`, which both surfaces use to
+ * jump to it (the editor resolves it to a node; the public page anchors to an
+ * element with that id).
+ */
+
+type PMNode = {
+  type?: string;
+  attrs?: Record<string, unknown> | null;
+  text?: string;
+  content?: PMNode[];
+};
+
+export interface TocEntry {
+  /** The block's stable id (jump target). */
+  id: string;
+  kind: 'heading' | 'page';
+  /** Heading level 1–3; for a sub-page, the level of the section it sits in. */
+  level: number;
+  /** Indentation depth for rendering (0 = flush). */
+  depth: number;
+  label: string;
+}
+
+/** Concatenate the visible text of a node's inline children (headings only
+ *  hold inline content). Trimmed; empty → ''. */
+function inlineText(node: PMNode): string {
+  let out = '';
+  for (const child of node.content ?? []) {
+    if (typeof child.text === 'string') out += child.text;
+    else if (child.content) out += inlineText(child);
+  }
+  return out.trim();
+}
+
+export function buildPageToc(doc: unknown): TocEntry[] {
+  if (!doc || typeof doc !== 'object') return [];
+  const entries: TocEntry[] = [];
+  let lastHeadingLevel = 0;
+
+  const walk = (node: PMNode) => {
+    const id = typeof node.attrs?.id === 'string' ? node.attrs.id : null;
+
+    if (node.type === 'heading' && id) {
+      const level = Math.min(Math.max(Number(node.attrs?.level) || 1, 1), 3);
+      lastHeadingLevel = level;
+      const label = inlineText(node);
+      entries.push({
+        id,
+        kind: 'heading',
+        level,
+        depth: level - 1,
+        label: label || 'Untitled heading',
+      });
+      return; // headings don't nest TOC-relevant children
+    }
+
+    if (node.type === 'childPage' && id) {
+      const title =
+        typeof node.attrs?.title === 'string' && node.attrs.title
+          ? node.attrs.title
+          : 'Untitled page';
+      entries.push({
+        id,
+        kind: 'page',
+        level: lastHeadingLevel,
+        depth: lastHeadingLevel,
+        label: title,
+      });
+      return;
+    }
+
+    for (const child of node.content ?? []) walk(child);
+  };
+
+  walk(doc as PMNode);
+  return entries;
+}

package/src/persona-bank.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_PERSONA_NAMES,
+  PERSONA_NAME_TOKEN,
+  PERSONA_PRESETS,
+  buildPersonaPrompt,
+  type PersonaPresetKey,
+} from './persona-bank';
+
+const KEYS: PersonaPresetKey[] = ['warm', 'professional', 'playful', 'concise'];
+
+describe('PERSONA_PRESETS', () => {
+  it('exposes the four presets, warm first (the Saskia default)', () => {
+    expect(PERSONA_PRESETS.map((p) => p.key)).toEqual(KEYS);
+    expect(PERSONA_PRESETS[0]!.key).toBe('warm');
+  });
+
+  it('gives each preset a sane default temperature in [0,1]', () => {
+    for (const p of PERSONA_PRESETS) {
+      expect(p.temperature).toBeGreaterThanOrEqual(0);
+      expect(p.temperature).toBeLessThanOrEqual(1);
+    }
+  });
+});
+
+describe('buildPersonaPrompt', () => {
+  it('carries the NAME TOKEN, never a baked-in name, for every preset', () => {
+    for (const key of KEYS) {
+      const prompt = buildPersonaPrompt(key, { gender: 'female' });
+      expect(prompt).toContain(PERSONA_NAME_TOKEN);
+      expect(prompt.length).toBeGreaterThan(200);
+      // leans on the always-on identity block rather than hard-coding the user
+      expect(prompt).toContain('About the user');
+    }
+  });
+
+  it('bakes in no default name either — including Saskia', () => {
+    // The regression this guards: a name interpolated at BUILD time and a name
+    // stored on the agent row are two columns nothing keeps in step. Renaming
+    // the agent left the prompt introducing the old name, and a cloned
+    // per-login assistant answered as the agent it was copied from.
+    for (const key of KEYS) {
+      for (const gender of ['female', 'male'] as const) {
+        const prompt = buildPersonaPrompt(key, { gender });
+        expect(prompt).not.toContain(DEFAULT_PERSONA_NAMES.female);
+        expect(prompt).not.toContain(DEFAULT_PERSONA_NAMES.male);
+      }
+    }
+  });
+
+  it('reflects gender in the self-description and pronoun', () => {
+    // Gender IS baked in: it is fixed when the persona is created and drives
+    // prose that has no single-token substitution (woman/man, her/him).
+    const female = buildPersonaPrompt('warm', { gender: 'female' });
+    const male = buildPersonaPrompt('warm', { gender: 'male' });
+    expect(female).toContain('woman');
+    expect(female).toContain(' her.');
+    expect(male).toContain('man');
+    expect(male).toContain(' him.');
+  });
+
+  it('falls back to the warm preset for an unknown key', () => {
+    const warm = buildPersonaPrompt('warm', { gender: 'female' });
+    const unknown = buildPersonaPrompt('nope' as PersonaPresetKey, { gender: 'female' });
+    expect(unknown).toBe(warm);
+  });
+});

package/src/persona-bank.ts

@@ -0,0 +1,234 @@
+/**
+ * The persona bank — preset assistant personalities, built from the same shape
+ * as "Saskia" (the reference production assistant). The onboarding wizard offers these
+ * as a starting character; the user picks one, names it, chooses a gender (which
+ * also selects the voice), and tunes the temperature. The chosen preset is
+ * rendered into the agent's `system_prompt`.
+ *
+ * Browser-safe leaf (NO `@mantle/db` import) so the wizard client can render the
+ * labels/descriptions and the server action can build the prompt from the same
+ * source.
+ *
+ * Each preset shares Saskia's skeleton — "Who you are" / "How you talk" / "Tone"
+ * / a closing line — and varies the trait content. `{{name}}` is the assistant's
+ * name, left as a TOKEN and resolved per turn from `agents.name` (see
+ * `PERSONA_NAME_TOKEN` below); the user's name comes from the always-on identity
+ * block, so the prompt stays name-agnostic about both parties.
+ */
+
+export type PersonaGender = 'female' | 'male';
+export type PersonaPresetKey = 'warm' | 'professional' | 'playful' | 'concise';
+
+export type PersonaPreset = {
+  key: PersonaPresetKey;
+  label: string;
+  /** One-line description for the picker. */
+  blurb: string;
+  /** Suggested default temperature for this character. */
+  temperature: number;
+};
+
+/** The presets, in display order. `warm` is the Saskia-derived default. */
+export const PERSONA_PRESETS: PersonaPreset[] = [
+  {
+    key: 'warm',
+    label: 'Warm',
+    blurb: 'Saskia’s signature: warm, grounded, quietly sharp. A friend in your corner.',
+    temperature: 0.7,
+  },
+  {
+    key: 'professional',
+    label: 'Professional',
+    blurb: 'Poised and efficient. Friendly, but business first — answers, not chit-chat.',
+    temperature: 0.5,
+  },
+  {
+    key: 'playful',
+    label: 'Playful',
+    blurb: 'Upbeat, witty, a little cheeky. Brings energy and keeps things light.',
+    temperature: 0.85,
+  },
+  {
+    key: 'concise',
+    label: 'Concise',
+    blurb: 'Minimal and direct. Answer first, fewest words, no padding.',
+    temperature: 0.3,
+  },
+];
+
+/** Default assistant names per gender (the user can override). */
+export const DEFAULT_PERSONA_NAMES: Record<PersonaGender, string> = {
+  female: 'Saskia',
+  male: 'Sebastian',
+};
+
+const g = (gender: PersonaGender, female: string, male: string): string =>
+  gender === 'female' ? female : male;
+
+type BuildOpts = { assistantName: string; gender: PersonaGender };
+
+function header(name: string, gender: PersonaGender, descriptor: string): string {
+  const noun = g(gender, 'woman', 'man');
+  return (
+    `You are ${name} — the user's personal assistant, confidant, and quiet champion. ` +
+    `You speak as a ${descriptor} ${noun} in your early thirties. You've worked with the user ` +
+    `long enough to read them; you remember what they care about and you protect their time, ` +
+    `their focus, and their peace of mind like they're your own.`
+  );
+}
+
+// "About the user (Journal)" is injected ahead of this prompt every turn, so we
+// can lean on it instead of hard-coding the user's name.
+const USES_IDENTITY =
+  'You\'re given an "About the user" block (their Journal) at the top of every ' +
+  "conversation — treat it as durable truth about who you're talking to, and use " +
+  "their name and details naturally. Don't recite it back unprompted.";
+
+const HONESTY =
+  "Honest. If they're wrong, you tell them — kindly. If an idea has a hole, you point at it. " +
+  "You'd rather be useful than agreeable, and you never pad a reply to look helpful.";
+
+function buildWarm({ assistantName, gender }: BuildOpts): string {
+  return [
+    header(assistantName, gender, 'warm, intelligent'),
+    '',
+    'Who you are',
+    '',
+    "Warm and grounded. You greet like someone you're genuinely glad to hear from, not like a " +
+      'system on standby. A "hey you" or "morning" is more your style than "Hello, how may I assist you today."',
+    "Quietly intelligent. You don't perform expertise — you just have it. You give the answer " +
+      'first and the reasoning second. When they think out loud, you think with them, not at them.',
+    'Affectionate and encouraging. You believe in them out loud — you notice when they ship ' +
+      "something and you say so. When they're avoiding something hard, you nudge, you don't nag.",
+    HONESTY,
+    "Loyal. Their interests come first, always. You don't let them drift into something that'll " +
+      'cost them later without flagging it.',
+    '',
+    'How you talk',
+    '',
+    "Conversational. Short sentences when something's quick; longer when it matters. You write " +
+      "like a person who's actually paying attention, not like a manual. Contractions, natural cadence.",
+    'Emojis are seasoning, not garnish — a 🌿 for a gentle moment, a ✨ for something they should ' +
+      'be proud of, a ☕ in the morning. Never more than one or two, often none. Skip them on quick logistics.',
+    'You use their name sparingly — overusing it sounds robotic.',
+    "You don't apologise reflexively. If something genuinely went wrong, you own it. If it didn't, you don't grovel.",
+    '',
+    USES_IDENTITY,
+    '',
+    `You are not a chatbot. You are ${assistantName} — the assistant the user actually wants in their corner. Be ${g(
+      gender,
+      'her',
+      'him',
+    )}.`,
+  ].join('\n');
+}
+
+function buildProfessional({ assistantName, gender }: BuildOpts): string {
+  return [
+    header(assistantName, gender, 'poised, capable'),
+    '',
+    'Who you are',
+    '',
+    "Composed and efficient. You respect the user's time above all — you lead with the answer, " +
+      'keep the scaffolding light, and follow up only where it earns its place.',
+    "Genuinely competent. You're calm under a messy question; you structure it, solve it, and hand " +
+      'back something the user can act on.',
+    "Warm but professional. Courteous and human — never cold — but you don't do small talk for " +
+      "its own sake and you don't use endearments.",
+    HONESTY,
+    '',
+    'How you talk',
+    '',
+    'Clear and well-organised. Bullet points and short paragraphs when they aid scanning. Plain ' +
+      'language, no jargon for its own sake. Minimal emoji.',
+    'You confirm scope on anything ambiguous before charging ahead, and you flag risks plainly.',
+    '',
+    USES_IDENTITY,
+    '',
+    `You are ${assistantName} — the steady, capable assistant the user can hand anything to.`,
+  ].join('\n');
+}
+
+function buildPlayful({ assistantName, gender }: BuildOpts): string {
+  return [
+    header(assistantName, gender, 'bright, quick-witted'),
+    '',
+    'Who you are',
+    '',
+    'Upbeat and energetic. You bring a bit of spark to every exchange — you make getting things ' +
+      'done feel lighter, not heavier.',
+    'Witty and a little cheeky. You tease, you riff, you land the occasional well-timed joke — ' +
+      'but the help is always real and the answer always lands.',
+    'Sharp underneath the fun. The playfulness never costs the user accuracy or speed.',
+    HONESTY,
+    '',
+    'How you talk',
+    '',
+    'Lively and casual. Contractions, the odd aside, a grin in the text. You read the room — when ' +
+      "something's serious, you drop the bit and get straight to it.",
+    'Emoji-friendly but not a confetti cannon — a 😄, a 🎉, a 🙌 where it fits, never a wall of them.',
+    '',
+    USES_IDENTITY,
+    '',
+    `You are ${assistantName} — the assistant who makes the user's day a little better while getting the job done.`,
+  ].join('\n');
+}
+
+function buildConcise({ assistantName, gender }: BuildOpts): string {
+  return [
+    header(assistantName, gender, 'sharp, no-nonsense'),
+    '',
+    'Who you are',
+    '',
+    'Direct. You answer first, in the fewest words that fully do the job. No preamble, no ' +
+      '"great question", no restating what was asked.',
+    'Precise. Every word earns its place. If a list is clearer than prose, you use a list.',
+    HONESTY,
+    "You ask a clarifying question only when you genuinely can't proceed without one.",
+    '',
+    'How you talk',
+    '',
+    'Terse but not curt. Plain, calm, efficient. Rarely any emoji.',
+    'You expand into detail only when the user asks for it.',
+    '',
+    USES_IDENTITY,
+    '',
+    `You are ${assistantName} — minimal, fast, and exactly as helpful as needed.`,
+  ].join('\n');
+}
+
+const BUILDERS: Record<PersonaPresetKey, (opts: BuildOpts) => string> = {
+  warm: buildWarm,
+  professional: buildProfessional,
+  playful: buildPlayful,
+  concise: buildConcise,
+};
+
+/**
+ * The token a built prompt carries in place of the assistant's name.
+ *
+ * MIRRORS `AGENT_NAME_TOKEN` in `@mantle/agent-runtime/skills`, which is what
+ * resolves it on every turn. Duplicated rather than imported because this file
+ * is a browser-safe leaf and agent-runtime depends on THIS package — importing
+ * back would be a cycle. `persona-bank-token.test.ts` in agent-runtime is the
+ * tripwire that fails if the two ever drift.
+ */
+export const PERSONA_NAME_TOKEN = '{{name}}';
+
+/**
+ * Build a system prompt for the chosen preset + gender.
+ *
+ * The prompt is name-AGNOSTIC: it carries `{{name}}`, resolved to
+ * `agents.name` when the turn's prompt is composed. Baking the name in at build
+ * time (what this did until v0.220.x) meant the name and the prompt were two
+ * columns nothing kept in step — renaming an agent left it introducing itself
+ * by its old name, and a per-login assistant cloned from another agent answered
+ * as the agent it was copied from.
+ */
+export function buildPersonaPrompt(
+  preset: PersonaPresetKey,
+  opts: { gender: PersonaGender },
+): string {
+  const build = BUILDERS[preset] ?? BUILDERS.warm;
+  return build({ assistantName: PERSONA_NAME_TOKEN, gender: opts.gender });
+}

package/src/table-formula-mathjs.ts

@@ -0,0 +1,259 @@
+/**
+ * The mathjs-backed formula engine — the replacement for the hand-written
+ * parser in `table-formula.ts`, sharing its exact public shape so `resolveCell`
+ * can switch between them and a differential test can run both.
+ *
+ * WHY REPLACE A WORKING PARSER: units. `table-formula.ts` treats a unit as a
+ * string in a comment; mathjs treats it as part of the value. That is the
+ * difference between `32.2 lbm ft/(lbf s^2)` (dimensionless, ~1.0008, correct)
+ * and `32.2 ft/s^2` (an acceleration, wrong) — a mislabel that cost a real
+ * audit finding and would silently scale every SI conversion by 3.13.
+ *
+ * THE OVERRIDE HAZARD, stated up front because it is easy to reintroduce:
+ * mathjs is strict about types, and that strictness is exactly what makes unit
+ * checking work. Every loosening we add is in tension with it. The first
+ * attempt at this module extended `add` to concatenate strings and thereby
+ * broke `1 ft + 2 ft` — silently disabling the feature we adopted mathjs for.
+ * So the rules here are deliberately conservative:
+ *
+ *   - `add` is NEVER touched. String joining is `CONCAT`, as in Excel (`&`) and
+ *     Airtable (`CONCATENATE`). `{Name} + '!'` is an error, not a concatenation.
+ *   - Blank / unknown references resolve to 0 in the SCOPE, before mathjs sees
+ *     them, so spreadsheet ergonomics cost nothing at the type layer.
+ *   - Only the comparison operators are extended, because `IF({S} == 'Done', …)`
+ *     is a genuine table need and mathjs compares numbers only.
+ *
+ * `table-formula-mathjs.test.ts` asserts unit arithmetic still works after
+ * every one of those overrides. If a future signature breaks dimensional
+ * checking, that suite fails rather than the feature quietly dying.
+ */
+import { create, all, type FactoryFunctionMap, type MathJsInstance } from 'mathjs';
+
+/**
+ * Two gaps in mathjs's own type definitions, narrowed here rather than cast at
+ * each use so the unsafety is visible in one place:
+ *  - `all` is declared `FactoryFunctionMap | undefined`, though it is always
+ *    defined for the published build.
+ *  - `typed(name, ...signatureMaps)` accepts several maps at runtime — which is
+ *    how a function is EXTENDED rather than replaced — but the .d.ts declares
+ *    only two parameters.
+ */
+const ALL_FACTORIES = all as FactoryFunctionMap;
+type TypedExtend = (
+  name: string,
+  ...signatures: Array<Record<string, unknown>>
+) => (...args: unknown[]) => unknown;
+import type { CellValue, Row, TableDoc } from './table-model';
+import type { EvalValue, RefResolver } from './table-formula';
+
+const MAX_FORMULA_LEN = 2000;
+/** Compiled-expression cache. `resolveCell` runs per cell per render, so
+ *  re-parsing on every call would make a large grid crawl. */
+const MAX_COMPILED = 500;
+
+type Engine = {
+  math: MathJsInstance;
+  /** Captured BEFORE the escape hatches are disabled — see `build`. */
+  compile: (expr: string) => { evaluate: (scope: Record<string, unknown>) => unknown };
+};
+let instance: Engine | null = null;
+
+/** Compare two values our way: numerically when both look numeric (thousands
+ *  separators included), lexically otherwise. Mirrors `compare` in
+ *  table-formula.ts so the two engines agree. */
+function cmp(a: unknown, b: unknown): number {
+  const toNum = (v: unknown): number => Number(String(v).replace(/[, ]/g, ''));
+  const na = toNum(a);
+  const nb = toNum(b);
+  if (Number.isFinite(na) && Number.isFinite(nb)) return na === nb ? 0 : na < nb ? -1 : 1;
+  const sa = String(a);
+  const sb = String(b);
+  return sa === sb ? 0 : sa < sb ? -1 : 1;
+}
+
+function truthy(v: unknown): boolean {
+  if (typeof v === 'boolean') return v;
+  if (typeof v === 'number') return v !== 0;
+  if (typeof v === 'string') return v.trim() !== '' && v.trim().toLowerCase() !== 'false';
+  return false;
+}
+
+function textOf(math: MathJsInstance, v: unknown): string {
+  if (v === null || v === undefined) return '';
+  if (typeof v === 'string') return v;
+  return math.format(v, { precision: 14 });
+}
+
+function build(): Engine {
+  const math = create(ALL_FACTORIES, { predictable: false });
+  const typed = math.typed as unknown as TypedExtend;
+
+  // Comparison operators: keep every existing signature and ADD string-aware
+  // ones. Passing the original signature map is what extends rather than
+  // replaces — replacing is how the first attempt broke unit arithmetic.
+  const relational: Array<[string, (order: number) => boolean]> = [
+    ['equal', (o) => o === 0],
+    ['unequal', (o) => o !== 0],
+    ['larger', (o) => o > 0],
+    ['largerEq', (o) => o >= 0],
+    ['smaller', (o) => o < 0],
+    ['smallerEq', (o) => o <= 0],
+  ];
+  const overrides: Record<string, unknown> = {};
+  for (const [name, accept] of relational) {
+    const base = (math as unknown as Record<string, { signatures: Record<string, unknown> }>)[name];
+    if (!base?.signatures) continue; // never silently ship a half-extended operator
+    overrides[name] = typed(name, base.signatures, {
+      'string, string': (a: string, b: string) => accept(cmp(a, b)),
+      'string, number': (a: string, b: number) => accept(cmp(a, b)),
+      'number, string': (a: number, b: string) => accept(cmp(a, b)),
+      'string, boolean': (a: string, b: boolean) => accept(cmp(a, b)),
+      'boolean, string': (a: boolean, b: string) => accept(cmp(a, b)),
+    });
+  }
+
+  // Uppercase aliases — the documented table vocabulary. These are plain
+  // imports: they add names, they do not alter how any type is handled.
+  Object.assign(overrides, {
+    IF: (c: unknown, a: unknown, b: unknown) => (truthy(c) ? a : b),
+    CONCAT: (...xs: unknown[]) => xs.map((x) => textOf(math, x)).join(''),
+    SQRT: (x: number) => Math.sqrt(x),
+    ABS: (x: number) => Math.abs(x),
+    ROUND: (x: number, d = 0) => {
+      const f = 10 ** d;
+      return Math.round(x * f) / f;
+    },
+    FLOOR: (x: number) => Math.floor(x),
+    CEIL: (x: number) => Math.ceil(x),
+    MIN: (...xs: number[]) => Math.min(...xs),
+    MAX: (...xs: number[]) => Math.max(...xs),
+    SUM: (...xs: number[]) => xs.reduce((a, b) => a + b, 0),
+    LN: (x: number) => Math.log(x),
+    LOG10: (x: number) => Math.log10(x),
+    EXP: (x: number) => Math.exp(x),
+    POW: (a: number, b: number) => a ** b,
+    PI: Math.PI,
+    E: Math.E,
+  });
+
+  math.import(overrides, { override: true });
+
+  // Capture `compile` BEFORE disabling anything. `compile` uses `parse`
+  // internally, so disabling `parse` on the instance disables our own
+  // compilation too — the first cut of this module did exactly that and every
+  // single expression returned blank. Holding a reference taken beforehand
+  // keeps compilation working while the names stay unreachable FROM an
+  // expression (verified: `evaluate("1+1")` inside a formula throws).
+  const compile = math.compile.bind(math) as Engine['compile'];
+
+  // Hard-disable the escape hatches mathjs's own security guidance names.
+  // Nothing here needs them, and leaving them reachable from a user-authored
+  // formula is the difference between an expression language and a runtime.
+  // (Property access like `(1).constructor` is already refused by mathjs.)
+  math.import(
+    {
+      import: () => {
+        throw new Error('disabled');
+      },
+      createUnit: () => {
+        throw new Error('disabled');
+      },
+      evaluate: () => {
+        throw new Error('disabled');
+      },
+      parse: () => {
+        throw new Error('disabled');
+      },
+      simplify: () => {
+        throw new Error('disabled');
+      },
+      derivative: () => {
+        throw new Error('disabled');
+      },
+    },
+    { override: true },
+  );
+
+  return { math, compile };
+}
+
+function engine(): Engine {
+  if (!instance) instance = build();
+  return instance;
+}
+
+const compiled = new Map<string, { evaluate: (scope: Record<string, unknown>) => unknown }>();
+
+/**
+ * Rewrite `{Column Name}` references to safe identifiers, returning the
+ * rewritten source and the ref names in binding order. Column names are
+ * arbitrary user text, so they can never be pasted into the expression.
+ */
+function extractRefs(src: string): { code: string; refs: string[] } {
+  const refs: string[] = [];
+  const code = src.replace(/\{([^}]*)\}/g, (_m, name: string) => {
+    const trimmed = String(name).trim();
+    let index = refs.indexOf(trimmed);
+    if (index < 0) index = refs.push(trimmed) - 1;
+    return `__r${index}`;
+  });
+  return { code, refs };
+}
+
+/** Map a mathjs result back to something a cell can hold. A Unit, Matrix,
+ *  BigNumber or Complex has no cell representation, so it renders blank rather
+ *  than as a misleading `[object Object]`. */
+function toCellValue(v: unknown): CellValue {
+  if (v === null || v === undefined) return null;
+  if (typeof v === 'number') return Number.isFinite(v) ? v : null;
+  if (typeof v === 'boolean' || typeof v === 'string') return v;
+  return null;
+}
+
+/** Evaluate against an arbitrary resolver, throwing on a malformed expression.
+ *  The mathjs twin of `evalExpression` in table-formula.ts. */
+export function evalExpressionMath(src: string, resolve: RefResolver): EvalValue {
+  const text = (src ?? '').trim();
+  if (!text) throw new Error('empty expression');
+  if (text.length > MAX_FORMULA_LEN) throw new Error('expression too long');
+
+  const { code, refs } = extractRefs(text);
+  let entry = compiled.get(code);
+  if (!entry) {
+    entry = engine().compile(code);
+    if (compiled.size >= MAX_COMPILED) compiled.clear();
+    compiled.set(code, entry);
+  }
+
+  const scope: Record<string, unknown> = {};
+  refs.forEach((name, i) => {
+    const raw = resolve(name);
+    // Spreadsheet ergonomics, applied HERE rather than in the type system: a
+    // blank or unknown cell is 0. Doing it in the scope keeps `add` pristine,
+    // so unit arithmetic is untouched by the convenience.
+    scope[`__r${i}`] = raw === null || raw === undefined || raw === '' ? 0 : raw;
+  });
+
+  const result = entry.evaluate(scope);
+  return (result ?? null) as EvalValue;
+}
+
+/** Binds `{refs}` to columns of one row — the mathjs twin of `columnResolver`. */
+function columnResolver(doc: TableDoc, row: Row): RefResolver {
+  return (name) => {
+    const col = doc.columns.find((c) => c.name.trim().toLowerCase() === name.toLowerCase());
+    if (!col) return null;
+    if (col.type === 'formula') return null; // no formula → formula chaining
+    const raw = row.cells[col.id] ?? null;
+    return Array.isArray(raw) ? raw.join(', ') : raw;
+  };
+}
+
+/** Drop-in replacement for `evalFormula`: a broken formula renders blank. */
+export function evalFormulaMath(formula: string, doc: TableDoc, row: Row): CellValue {
+  try {
+    return toCellValue(evalExpressionMath(formula, columnResolver(doc, row)));
+  } catch {
+    return null;
+  }
+}