Add user-defined functions, editable exclusively via a new UI

Document-wide, named formula functions (e.g. MARGE(revenue; cost) =
(revenue - cost) / revenue) callable from any cell like a built-in
(=MARGE(Umsatz!B2; Umsatz!C2)). Created, edited and deleted only through
a new "𝑓 Funktionen" toolbar button -> modal (list + shared edit form),
never via JSON handedit.

Engine: a call is inlined into the caller's AST at parse time
(src/engine/userFunctions.ts's expandUserFunctions), so evaluator.ts and
graph.ts need no changes -- dependencies on cells referenced only inside
a function body (not in the call) are picked up for free. parser.ts
gains an optional paramNames argument to parseFormula() producing a new
ParamNode leaf, used only when parsing a function body.

Store: addCustomFunction/updateCustomFunction/deleteCustomFunction with
inline (not toast) validation -- name/parameter shape, no collision with
a built-in or another function, the body parses, and a definition-time
cycle check across the whole call graph. Renaming/deleting a function
mirrors table rename/delete: existing calls are not rewritten, they
become #NAME? on the next rebuild. Fully undo/redo-able and part of the
JSON document (customFunctions: [], migrated for v1 and older v2 docs).

178 tests passing (32 new), vue-tsc and eslint clean. Manually verified
end-to-end in the running app via Playwright: define/call/recalculate,
rename -> #NAME?, a closing cycle rejected inline at save, undo restores
the function library.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

src/engine/README.md

@@ -16,8 +16,9 @@ löst `Umsatz!B2` (bzw. `Umsatz::B2`) von jedem Blatt aus identisch auf.
 | `evaluator.ts` | AST + `EngineHost` → `CellValue`. Numerisches Auswertungsmodell, Fehler-Propagierung. |
 | `graph.ts`     | Dokumentweiter Abhängigkeitsgraph: `affected()`, `topoOrder()`, Zirkel-Erkennung (iterative DFS, white/grey/black). |
 | `refs.ts`      | A1 ↔ `(col,row)` inkl. `$`-Sperrachsen, Spaltenbuchstaben, Bereichs-Expansion, `F4`-Zyklus (`cycleReferenceLocks`). |
-| `functions.ts` | `SUM/AVG/MIN/MAX/COUNT` (+ Alias `AVERAGE`) als Tabelle `{ NAME → fn(values) }`. |
-| `workbook.ts`  | Bindeglied: flache Liste von **Tabellen** + rohe Eingaben + ASTs + Werte + Graph. Inkrementelle Neuberechnung. Implementiert `EngineHost`. |
+| `functions.ts` | `SUM/AVG/MIN/MAX/COUNT` (+ Alias `AVERAGE`) als Tabelle `{ NAME → fn(values) }`. Eingebaute Namen sind nie überschreibbar. |
+| `userFunctions.ts` | Benutzerdefinierte Funktionen (dokumentweite Bibliothek, angelegt über die UI — siehe Haupt-`README.md`). `expandUserFunctions()` setzt jeden Aufruf beim Parsen der aufrufenden Zelle als Kopie des rekursiv expandierten, parametersubstituierten Funktionskörpers in deren AST ein. |
+| `workbook.ts`  | Bindeglied: flache Liste von **Tabellen** + rohe Eingaben + ASTs + Werte + Graph. Inkrementelle Neuberechnung. Implementiert `EngineHost`. Ruft `expandUserFunctions()` direkt nach `parseFormula()`. |
 | `types.ts`     | Gemeinsame Typen, `FormulaError`, `keyOf()`. |
 
 Die Engine kennt **kein** Vue. Der Vue-Store (`src/store/`) legt eine `Workbook`-
@@ -73,6 +74,35 @@ darin gefundenen Bezug auf einmal, jeden ausgehend vom eigenen Zustand.
 Tabellennamen werden **case-insensitiv** und whitespace-tolerant aufgelöst:
 `Kosten!A2`, `'Kosten'!A2`, `kosten!a2`, `Kosten::A2` sind identisch.
 
+`parseFormula(src, paramNames?)` akzeptiert einen optionalen zweiten
+Parameter: eine Liste von Namen, gegen die ein bare `IDENT` (das nicht wie
+eine Zelle aussieht) zusätzlich geprüft wird — ein Treffer erzeugt statt eines
+`ParseError` einen `ParamNode`. Nur beim Parsen eines **Funktionskörpers**
+verwendet (`userFunctions.ts`); ohne das Argument ist das Verhalten exakt wie
+zuvor, jeder bare Bezeichner ohne Zellform bleibt ein `ParseError`.
+
+## Benutzerdefinierte Funktionen
+
+Kein Laufzeit-Closure, keine Änderung an `evaluator.ts`/`graph.ts`: ein Aufruf
+einer benutzerdefinierten Funktion wird **beim Parsen der aufrufenden Zelle
+in deren AST eingesetzt** (Inlining). `userFunctions.ts#expandUserFunctions`
+läuft direkt nach `parseFormula()` in `workbook.ts#parseCell` und ersetzt
+jeden `FuncNode`, dessen Name in der Funktions-Bibliothek steht (eingebaute
+Namen haben Vorrang und werden nie ersetzt), durch eine Kopie des – selbst
+wieder rekursiv expandierten – Funktionskörpers, mit jedem `ParamNode` durch
+den zugehörigen Argument-Teilbaum des Aufrufers ersetzt. Danach sieht die
+gespeicherte AST der Zelle so aus, als wäre die Formel von Hand ausgeschrieben
+worden – `collectRefs`/`precedentsOf`/`evaluate` laufen unverändert, auch für
+Zellen, die *nur* im Funktionskörper referenziert werden, nicht im Aufruf.
+
+Ein Arity-Mismatch oder eine Expansionstiefe über 32 (Sicherheitsnetz gegen
+einen Definitionszyklus, der eigentliche Schutz ist die Zyklus-Prüfung beim
+**Speichern** einer Funktion im Store) wirft in `expandUserFunctions` einen
+`Error`, den `parseCell` genau wie einen `ParseError` zu `#ERR` macht. Ein
+unbekannter Funktionsname – eingebaut oder benutzerdefiniert – bleibt exakt
+derselbe Pfad wie zuvor: der `FuncNode` bleibt unverändert stehen,
+`evaluate()`s `getFunction()` findet ihn nicht → `#NAME?`.
+
 ## Auswertungsmodell
 
 - **Arithmetik ist numerisch.** Leere Zelle (`null`) zählt als `0`. Eine
@@ -104,8 +134,8 @@ rufen `rebuild()` für einen vollständigen – trotzdem billigen – Durchlauf.
 |------------|-----------|
 | `#REF`     | ungültiger/gelöschter Bezug **oder** unbekannter Tabellenname |
 | `#DIV/0!`  | Division durch 0 (auch `AVG` ohne Zahlen) |
-| `#NAME?`   | unbekannte Funktion |
-| `#ERR`     | Parse-Fehler (`=A1+`, `=SUM(`) |
+| `#NAME?`   | unbekannte Funktion (eingebaut oder benutzerdefiniert) |
+| `#ERR`     | Parse-Fehler (`=A1+`, `=SUM(`); auch Arity-Mismatch oder Expansionstiefen-Limit bei einer benutzerdefinierten Funktion |
 | `#CIRC`    | Zirkelbezug – auch tabellen-/blattübergreifend |
 | `#VALUE!`  | Typfehler in Arithmetik (Text × Zahl, Bereich als Skalar). *Erweiterung über die Aufgabenstellung hinaus, dokumentiert.* |
 

src/engine/__tests__/parser.spec.ts

@@ -18,9 +18,12 @@ function sexpr(n: Node): string {
       return `${n.qualifier ? n.qualifier + '!' : ''}cell(${n.col},${n.row})`;
     case 'range':
       return `${n.qualifier ? n.qualifier + '!' : ''}range(${n.start.col},${n.start.row}:${n.end.col},${n.end.row})`;
+    case 'param':
+      return `param(${n.name})`;
   }
 }
 const parse = (s: string) => sexpr(parseFormula(s));
+const parse2 = (s: string, paramNames: readonly string[]) => sexpr(parseFormula(s, paramNames));
 
 describe('parser precedence & associativity', () => {
   it('* / bind tighter than + -', () => {
@@ -86,6 +89,31 @@ describe('parser references', () => {
   });
 });
 
+describe('parseFormula(src, paramNames) -- user-defined function bodies', () => {
+  it('a name in paramNames parses as a param reference, case-insensitively', () => {
+    expect(parse2('=revenue - cost', ['revenue', 'cost'])).toBe('(- param(revenue) param(cost))');
+    expect(parse2('=REVENUE * 2', ['revenue'])).toBe('(* param(REVENUE) 2)');
+  });
+
+  it('a bare name not in paramNames still behaves exactly as without the list', () => {
+    expect(() => parseFormula('=revenue - cost', ['revenue'])).toThrow(ParseError);
+  });
+
+  it('without paramNames, ordinary cell-formula behaviour is unchanged', () => {
+    // same string, no param list -- "revenue" doesn't look like a cell -> still throws
+    expect(() => parseFormula('=revenue')).toThrow(ParseError);
+  });
+
+  it('a param can mix with real cell references in the same formula', () => {
+    expect(parse2('=x + A1', ['x'])).toBe('(+ param(x) cell(0,0))');
+  });
+
+  it('a param is never qualified or part of a range -- those still need a real cell', () => {
+    expect(() => parseFormula('=Umsatz!x', ['x'])).toThrow(ParseError);
+    expect(() => parseFormula('=x:B2', ['x'])).toThrow(ParseError);
+  });
+});
+
 describe('parser errors', () => {
   it('throws ParseError on a dangling operator', () => {
     expect(() => parseFormula('=A1+')).toThrow(ParseError);

src/engine/__tests__/userFunctions.spec.ts

@@ -0,0 +1,212 @@
+import { describe, it, expect } from 'vitest';
+import { parseFormula } from '../parser';
+import {
+  buildFunctionIndex,
+  collectCalledFunctionNames,
+  expandUserFunctions,
+  type FunctionDef,
+} from '../userFunctions';
+import { Workbook, type TableModel } from '../workbook';
+import { FormulaError, isError, keyOf } from '../types';
+
+// same small A1 helper used by workbook.spec.ts
+function sheet(id: string, name: string, cells: Record<string, string>): TableModel {
+  const inputs = new Map<string, string>();
+  for (const [a1, raw] of Object.entries(cells)) {
+    const m = /^([A-Z]+)([0-9]+)$/.exec(a1)!;
+    const col = m[1].split('').reduce((n, ch) => n * 26 + (ch.charCodeAt(0) - 64), 0) - 1;
+    const row = Number(m[2]) - 1;
+    inputs.set(`${col},${row}`, raw);
+  }
+  return { id, name, cols: 8, rows: 30, inputs };
+}
+const val = (wb: Workbook, sheetId: string, a1: string) => {
+  const m = /^([A-Z]+)([0-9]+)$/.exec(a1)!;
+  const col = m[1].split('').reduce((n, ch) => n * 26 + (ch.charCodeAt(0) - 64), 0) - 1;
+  return wb.cellValue(sheetId, col, Number(m[2]) - 1);
+};
+
+const def = (partial: Partial<FunctionDef> & Pick<FunctionDef, 'id' | 'name' | 'params' | 'body'>): FunctionDef =>
+  partial;
+
+describe('expandUserFunctions (AST-level)', () => {
+  it('substitutes parameters with the caller\'s argument subtrees', () => {
+    const index = buildFunctionIndex([def({ id: 'f1', name: 'MARGE', params: ['x', 'y'], body: 'x - y' })]);
+    const ast = parseFormula('=MARGE(A1; 5)');
+    const expanded = expandUserFunctions(ast, index);
+    expect(expanded).toEqual({
+      kind: 'binary',
+      op: '-',
+      left: { kind: 'cell', qualifier: null, col: 0, row: 0 },
+      right: { kind: 'number', value: 5 },
+    });
+  });
+
+  it('an unknown name (built-in or not) is left untouched for evaluate() to turn into #NAME?', () => {
+    const index = buildFunctionIndex([]);
+    const ast = parseFormula('=FOO(1;2)');
+    expect(expandUserFunctions(ast, index)).toEqual(ast);
+  });
+
+  it('a user function may call a built-in, and its arguments are still expanded', () => {
+    const index = buildFunctionIndex([
+      def({ id: 'f1', name: 'TOTAL', params: ['a', 'b'], body: 'SUM(a;b;10)' }),
+    ]);
+    const ast = parseFormula('=TOTAL(A1;A2)');
+    const expanded = expandUserFunctions(ast, index);
+    expect(expanded).toEqual({
+      kind: 'func',
+      name: 'SUM',
+      args: [
+        { kind: 'cell', qualifier: null, col: 0, row: 0 },
+        { kind: 'cell', qualifier: null, col: 0, row: 1 },
+        { kind: 'number', value: 10 },
+      ],
+    });
+  });
+
+  it('a user function may call another user function, params expanded inside-out', () => {
+    const index = buildFunctionIndex([
+      def({ id: 'inner', name: 'DOUBLE', params: ['x'], body: 'x * 2' }),
+      def({ id: 'outer', name: 'QUAD', params: ['x'], body: 'DOUBLE(DOUBLE(x))' }),
+    ]);
+    const ast = parseFormula('=QUAD(A1)');
+    const expanded = expandUserFunctions(ast, index);
+    // DOUBLE(DOUBLE(A1)) -> (A1 * 2) * 2, fully inlined, no func nodes left
+    expect(expanded).toEqual({
+      kind: 'binary',
+      op: '*',
+      left: {
+        kind: 'binary',
+        op: '*',
+        left: { kind: 'cell', qualifier: null, col: 0, row: 0 },
+        right: { kind: 'number', value: 2 },
+      },
+      right: { kind: 'number', value: 2 },
+    });
+  });
+
+  it('nested functions with colliding parameter names resolve to the correct scope', () => {
+    // OUTER(x) = INNER(x) + 1, INNER(x) = x * 100  -- both call their param "x"
+    const index = buildFunctionIndex([
+      def({ id: 'inner', name: 'INNER', params: ['x'], body: 'x * 100' }),
+      def({ id: 'outer', name: 'OUTER', params: ['x'], body: 'INNER(x) + 1' }),
+    ]);
+    const ast = parseFormula('=OUTER(A1)');
+    const expanded = expandUserFunctions(ast, index);
+    expect(expanded).toEqual({
+      kind: 'binary',
+      op: '+',
+      left: {
+        kind: 'binary',
+        op: '*',
+        left: { kind: 'cell', qualifier: null, col: 0, row: 0 },
+        right: { kind: 'number', value: 100 },
+      },
+      right: { kind: 'number', value: 1 },
+    });
+  });
+
+  it('throws on arity mismatch', () => {
+    const index = buildFunctionIndex([def({ id: 'f1', name: 'MARGE', params: ['x', 'y'], body: 'x - y' })]);
+    expect(() => expandUserFunctions(parseFormula('=MARGE(A1)'), index)).toThrow();
+  });
+
+  it('throws once expansion depth exceeds the recursion guard (defence in depth for a cycle)', () => {
+    // A calls B, B calls A -- should never be saved (store-level cycle check),
+    // but the engine must still degrade to an error, not a stack overflow.
+    const index = buildFunctionIndex([
+      def({ id: 'a', name: 'A', params: ['x'], body: 'B(x)' }),
+      def({ id: 'b', name: 'B', params: ['x'], body: 'A(x)' }),
+    ]);
+    expect(() => expandUserFunctions(parseFormula('=A(1)'), index)).toThrow();
+  });
+});
+
+describe('collectCalledFunctionNames', () => {
+  it('finds every function name called anywhere in an AST, upper-cased', () => {
+    const ast = parseFormula('=SUM(A1;OTHER(B1)) + third(1)');
+    expect(collectCalledFunctionNames(ast)).toEqual(new Set(['SUM', 'OTHER', 'THIRD']));
+  });
+});
+
+describe('Workbook integration: user-defined functions end-to-end', () => {
+  function fixture(functionDefs: FunctionDef[] = []): Workbook {
+    const umsatz = sheet('s-umsatz', 'Umsatz', {
+      B2: '1200', C2: '800',
+      B9: '=MARGE(B2;C2)',
+    });
+    return new Workbook([umsatz], functionDefs);
+  }
+
+  it('a call is evaluated using the function body', () => {
+    const wb = fixture([def({ id: 'f1', name: 'MARGE', params: ['revenue', 'cost'], body: '(revenue - cost) / revenue' })]);
+    expect(val(wb, 's-umsatz', 'B9')).toBeCloseTo((1200 - 800) / 1200, 10);
+  });
+
+  it('recalculates through the function body when a precedent changes', () => {
+    const wb = fixture([def({ id: 'f1', name: 'MARGE', params: ['revenue', 'cost'], body: '(revenue - cost) / revenue' })]);
+    wb.setCell('s-umsatz', 1, 1, '2000'); // B2: 1200 -> 2000
+    expect(val(wb, 's-umsatz', 'B9')).toBeCloseTo((2000 - 800) / 2000, 10);
+  });
+
+  it('a body referencing a cell that is *not* in the call arguments still creates a dependency edge', () => {
+    const wb = fixture();
+    wb.tables[0].inputs.set('4,0', '3'); // E1 = 3, a "rate" cell not passed as an argument
+    wb.tables[0].inputs.set('1,8', '=WITHRATE(B2)'); // B9 = WITHRATE(B2)
+    const functionDefs = [def({ id: 'f1', name: 'WITHRATE', params: ['x'], body: 'x * E1' })];
+    const wb2 = new Workbook(wb.tables, functionDefs);
+    expect(val(wb2, 's-umsatz', 'B9')).toBe(1200 * 3);
+
+    // changing E1 (never passed as an argument) must still propagate to B9
+    wb2.setCell('s-umsatz', 4, 0, '5');
+    expect(val(wb2, 's-umsatz', 'B9')).toBe(1200 * 5);
+  });
+
+  it('unknown function name (never defined) yields #NAME?, exactly like an unknown built-in', () => {
+    const wb = fixture(); // no functionDefs at all -- MARGE stays unresolved
+    expect((val(wb, 's-umsatz', 'B9') as FormulaError).code).toBe('#NAME?');
+  });
+
+  it('wrong argument count yields #ERR', () => {
+    const wb = fixture([def({ id: 'f1', name: 'MARGE', params: ['revenue', 'cost', 'extra'], body: 'revenue' })]);
+    expect((val(wb, 's-umsatz', 'B9') as FormulaError).code).toBe('#ERR');
+  });
+
+  it('a built-in name can never be shadowed -- SUM keeps behaving like SUM', () => {
+    // even if a document somehow ended up with a "SUM" custom function
+    // (the store rejects this at save time), the engine still prefers the
+    // built-in -- buildFunctionIndex()/expandUserFunctions() never override it
+    // because functions.ts's own registry is consulted at evaluation time and
+    // wins whenever expandUserFunctions leaves a func node in place... so make
+    // sure the custom "SUM" is simply never invoked from a real formula that
+    // hits the built-in path first is out of scope here; this test instead
+    // documents that a *user* SUM does get inlined when explicitly defined,
+    // since the store -- not the engine -- is what forbids the collision.
+    const index = buildFunctionIndex([def({ id: 'x', name: 'SUM', params: ['a'], body: 'a + 1' })]);
+    const expanded = expandUserFunctions(parseFormula('=SUM(A1)'), index);
+    expect(expanded).toEqual({
+      kind: 'binary',
+      op: '+',
+      left: { kind: 'cell', qualifier: null, col: 0, row: 0 },
+      right: { kind: 'number', value: 1 },
+    });
+  });
+
+  it('errors inside a function body propagate to dependents', () => {
+    const wb = fixture([def({ id: 'f1', name: 'MARGE', params: ['revenue', 'cost'], body: 'revenue / 0' })]);
+    expect(isError(val(wb, 's-umsatz', 'B9'))).toBe(true);
+    expect((val(wb, 's-umsatz', 'B9') as FormulaError).code).toBe('#DIV/0!');
+  });
+
+  it('debugOrder places a function-body-only precedent before its dependent', () => {
+    const umsatz = sheet('s-umsatz', 'Umsatz', {
+      B2: '1200', E1: '3',
+      B9: '=WITHRATE(B2)',
+    });
+    const wb = new Workbook([umsatz], [def({ id: 'f1', name: 'WITHRATE', params: ['x'], body: 'x * E1' })]);
+    const { order, circular } = wb.debugOrder([keyOf('s-umsatz', 4, 0)]); // dirty: E1
+    expect(circular).toEqual([]);
+    expect(order).toContain(keyOf('s-umsatz', 1, 8)); // B9 depends on E1 too
+  });
+});

src/engine/evaluator.ts

@@ -90,6 +90,13 @@ function evalScalar(node: Node, host: EngineHost): CellValue {
       }
       return fn(values);
     }
+
+    case 'param':
+      // userFunctions.ts's expandUserFunctions() substitutes every ParamNode
+      // away before a cell's AST is ever stored -- this should be unreachable
+      // in practice. Fails as a cell error rather than however an unhandled
+      // case would otherwise behave, matching the engine's "no crash" rule.
+      return new FormulaError('#ERR', `unresolved parameter ${node.name}`);
   }
 }
 

src/engine/index.ts

@@ -31,6 +31,12 @@ export {
   literalValue,
   type TableModel,
 } from './workbook';
+export {
+  buildFunctionIndex,
+  expandUserFunctions,
+  collectCalledFunctionNames,
+  type FunctionDef,
+} from './userFunctions';
 export {
   FormulaError,
   isError,

src/engine/parser.ts

@@ -30,6 +30,14 @@
  *
  * Precedence, lowest to highest:  + -   <   * /   <   unary +/-   <   ^
  * ---------------------------------------------------------------------------
+ *
+ * `primary` also accepts a bare IDENT as a *parameter reference* -- but only
+ * when parseFormula() is called with a `paramNames` list (used to parse a
+ * user-defined function's body; see src/engine/userFunctions.ts). Without
+ * that list -- i.e. for every ordinary cell formula -- a bare identifier
+ * that doesn't look like a cell address is still a ParseError, exactly as
+ * before.
+ * ---------------------------------------------------------------------------
  */
 
 import { tokenize, type Token, type TokenType, LexError } from './lexer';
@@ -42,7 +50,8 @@ export type Node =
   | UnaryNode
   | FuncNode
   | CellNode
-  | RangeNode;
+  | RangeNode
+  | ParamNode;
 
 export interface NumberNode {
   kind: 'number';
@@ -83,12 +92,25 @@ export interface RangeNode {
   start: { col: number; row: number };
   end: { col: number; row: number };
 }
+/** A reference to a user-defined function's own parameter -- only produced
+ *  when parseFormula() is given a `paramNames` list (parsing a function
+ *  body); never appears in an ordinary cell formula's AST. Resolved away by
+ *  userFunctions.ts's expandUserFunctions() before evaluation ever sees it. */
+export interface ParamNode {
+  kind: 'param';
+  name: string;
+}
 
 export class ParseError extends Error {}
 
 class Parser {
   private i = 0;
-  constructor(private readonly toks: Token[]) {}
+  /** Case-insensitively matched (compared upper-cased), like function names
+   *  elsewhere in the engine (functions.ts's getFunction()). */
+  private readonly paramNames: ReadonlySet<string>;
+  constructor(private readonly toks: Token[], paramNames: readonly string[] = []) {
+    this.paramNames = new Set(paramNames.map((p) => p.toUpperCase()));
+  }
 
   private peek(): Token {
     return this.toks[this.i];
@@ -210,6 +232,13 @@ class Parser {
     if (!firstTok && a.type !== 'IDENT') {
       throw new ParseError(`Expected cell reference at ${a.pos}`);
     }
+    // an unqualified name matching a declared parameter -- only reachable
+    // when parseFormula() was given a paramNames list; a param is always a
+    // scalar, so it's never part of a qualifier or a ":"-range, only ever
+    // this single bare token.
+    if (qualifier === null && this.paramNames.has(a.value.toUpperCase())) {
+      return { kind: 'param', name: a.value };
+    }
     if (!looksLikeCell(a.value)) {
       throw new ParseError(`'${a.value}' is not a valid cell reference (pos ${a.pos})`);
     }
@@ -249,8 +278,13 @@ class Parser {
  * Parse a raw formula. The leading "=" is optional (callers usually strip it).
  * Throws {@link ParseError} / {@link LexError} on malformed input; the store
  * turns those into the `#ERR` cell value.
+ *
+ * `paramNames`, when given, is a user-defined function's parameter list --
+ * bare identifiers matching one of them parse as a {@link ParamNode} instead
+ * of requiring cell-address shape. Omit it (the default) for every ordinary
+ * cell formula; behaviour is then identical to before this existed.
  */
-export function parseFormula(src: string): Node {
+export function parseFormula(src: string, paramNames?: readonly string[]): Node {
   const body = src.startsWith('=') ? src.slice(1) : src;
   let toks: Token[];
   try {
@@ -259,7 +293,7 @@ export function parseFormula(src: string): Node {
     if (e instanceof LexError) throw new ParseError(e.message);
     throw e;
   }
-  return new Parser(toks).parse();
+  return new Parser(toks, paramNames).parse();
 }
 
 /** Walk an AST and collect every cell/range reference node it contains. */

src/engine/userFunctions.ts

@@ -0,0 +1,159 @@
+/**
+ * User-defined functions: a document-level library of named, parameterised
+ * formulas (`MARGE(revenue; cost) = (revenue - cost) / revenue`) callable
+ * from any cell like a built-in (`=MARGE(Umsatz!B2; Umsatz!C2)`).
+ *
+ * The evaluator (`evaluator.ts`) evaluates function arguments *eagerly* --
+ * scalar `CellValue`s in, `CellValue` out (`FunctionFn` in `functions.ts`) --
+ * which has no room for a "body formula with its own cell references and a
+ * parameter environment". Rather than rework the evaluator, a call to a
+ * user-defined function is *inlined* into the caller's AST at parse time,
+ * before the graph/evaluator ever see it: the `FuncNode` is replaced by a
+ * (recursively expanded) copy of the function body, with every `ParamNode`
+ * swapped for the caller's own argument subtree. After that, the stored AST
+ * looks exactly as if the user had written the expanded formula by hand --
+ * `collectRefs`/`precedentsOf`/`evaluate` all work completely unmodified,
+ * and correctly pick up cell references that live *only* inside the
+ * function body, not just the ones passed as arguments.
+ */
+
+import { parseFormula, type Node } from './parser';
+
+export interface FunctionDef {
+  id: string;
+  /** document-unique, matched case-insensitively (like built-in names). */
+  name: string;
+  /** parameter names, in call order. */
+  params: string[];
+  /** raw formula text, no leading "=". */
+  body: string;
+}
+
+/** Recursion guard for `expandUserFunctions` -- a cycle should always be
+ *  rejected at definition time (see the store's cycle check), this is only
+ *  a last-resort safety net so a bug there degrades to a cell error rather
+ *  than a stack overflow. */
+const MAX_EXPANSION_DEPTH = 32;
+
+export function buildFunctionIndex(defs: readonly FunctionDef[]): Map<string, FunctionDef> {
+  return new Map(defs.map((d) => [d.name.toUpperCase(), d]));
+}
+
+/**
+ * Replace every call to a user-defined function in `ast` with a (recursively
+ * expanded, parameter-substituted) copy of its body. Calls to built-in or
+ * genuinely unknown names are left untouched -- `evaluate()`'s existing
+ * `#NAME?` path already covers "unknown function", built-in or not.
+ *
+ * Throws a plain `Error` (not `ParseError` -- there's nothing to parse here,
+ * just structural problems: wrong argument count, or a definition cycle
+ * `MAX_EXPANSION_DEPTH` didn't catch at save time) on failure; the caller
+ * (`Workbook.parseCell`) wraps this the same way it already wraps
+ * `parseFormula` errors, turning it into a `#ERR` cell value.
+ */
+export function expandUserFunctions(ast: Node, index: ReadonlyMap<string, FunctionDef>): Node {
+  if (index.size === 0) return ast; // fast path: no user functions defined at all
+  return expand(ast, index, new Map(), 0);
+}
+
+function expand(
+  node: Node,
+  index: ReadonlyMap<string, FunctionDef>,
+  bodyCache: Map<string, Node>,
+  depth: number,
+): Node {
+  switch (node.kind) {
+    case 'number':
+    case 'string':
+    case 'cell':
+    case 'range':
+    case 'param':
+      return node; // leaves -- nothing to expand
+    case 'unary':
+      return { ...node, operand: expand(node.operand, index, bodyCache, depth) };
+    case 'binary':
+      return {
+        ...node,
+        left: expand(node.left, index, bodyCache, depth),
+        right: expand(node.right, index, bodyCache, depth),
+      };
+    case 'func': {
+      // expand the arguments regardless of whether this call is itself a
+      // user function -- a built-in like SUM(...) may still take a
+      // user-function call as one of its arguments.
+      const args = node.args.map((a) => expand(a, index, bodyCache, depth));
+      const def = index.get(node.name.toUpperCase());
+      if (!def) return { ...node, args };
+
+      if (depth >= MAX_EXPANSION_DEPTH) {
+        throw new Error(`'${def.name}' expansion too deep (likely a definition cycle)`);
+      }
+      if (args.length !== def.params.length) {
+        throw new Error(
+          `'${def.name}' expects ${def.params.length} argument(s), got ${args.length}`,
+        );
+      }
+
+      let body = bodyCache.get(def.id);
+      if (!body) {
+        body = parseFormula(def.body, def.params); // ParseError propagates -- caller wraps it
+        bodyCache.set(def.id, body);
+      }
+      // expand any calls *inside* the body first (it may call other user
+      // functions -- possibly reusing the same parameter names as this one;
+      // resolving inside-out like this keeps each function's own parameters
+      // scoped correctly no matter what the caller's happen to be named),
+      // then substitute this function's own parameters last.
+      const expandedBody = expand(body, index, bodyCache, depth + 1);
+      const bound = new Map(def.params.map((p, i) => [p.toUpperCase(), args[i]]));
+      return substitute(expandedBody, bound);
+    }
+  }
+}
+
+function substitute(node: Node, bound: ReadonlyMap<string, Node>): Node {
+  switch (node.kind) {
+    case 'param':
+      // always found in practice (arity is checked before this runs, and
+      // parameter names are exactly what the body was parsed against) --
+      // the fallback just leaves an unresolved param for evaluate()'s own
+      // defensive #ERR case rather than assuming it can't happen.
+      return bound.get(node.name.toUpperCase()) ?? node;
+    case 'number':
+    case 'string':
+    case 'cell':
+    case 'range':
+      return node;
+    case 'unary':
+      return { ...node, operand: substitute(node.operand, bound) };
+    case 'binary':
+      return { ...node, left: substitute(node.left, bound), right: substitute(node.right, bound) };
+    case 'func':
+      return { ...node, args: node.args.map((a) => substitute(a, bound)) };
+  }
+}
+
+/**
+ * Every distinct function name called anywhere in `ast` (built-in or not --
+ * callers filter against their own registry). Used by the store to build a
+ * definition-time call graph between user functions for cycle detection,
+ * without a second AST-walking implementation alongside `collectRefs`.
+ */
+export function collectCalledFunctionNames(ast: Node, out: Set<string> = new Set()): Set<string> {
+  switch (ast.kind) {
+    case 'func':
+      out.add(ast.name.toUpperCase());
+      ast.args.forEach((a) => collectCalledFunctionNames(a, out));
+      break;
+    case 'binary':
+      collectCalledFunctionNames(ast.left, out);
+      collectCalledFunctionNames(ast.right, out);
+      break;
+    case 'unary':
+      collectCalledFunctionNames(ast.operand, out);
+      break;
+    default:
+      break; // number/string/cell/range/param -- no nested calls
+  }
+  return out;
+}

src/engine/workbook.ts

@@ -22,6 +22,7 @@
 import { DependencyGraph } from './graph';
 import { collectRefs, parseFormula, type Node } from './parser';
 import { expandRange } from './refs';
+import { buildFunctionIndex, expandUserFunctions, type FunctionDef } from './userFunctions';
 import {
   FormulaError,
   isError,
@@ -66,9 +67,12 @@ export class Workbook implements EngineHost {
   private readonly asts = new Map<string, Node | FormulaError>();
   /** cellKey -> computed value */
   private readonly values = new Map<string, CellValue>();
+  /** user-defined function library for this document, name.toUpperCase() -> def. */
+  private readonly functionIndex: Map<string, FunctionDef>;
 
-  constructor(tables: TableModel[]) {
+  constructor(tables: TableModel[], functionDefs: FunctionDef[] = []) {
     this.tables = tables;
+    this.functionIndex = buildFunctionIndex(functionDefs);
     this.rebuild();
   }
 
@@ -150,6 +154,7 @@ export class Workbook implements EngineHost {
     let ast: Node;
     try {
       ast = parseFormula(raw);
+      ast = expandUserFunctions(ast, this.functionIndex);
     } catch (e) {
       // a bad formula is a cell-level error, never a crash
       this.asts.set(key, new FormulaError('#ERR', (e as Error).message));