@gui-chat-plugin/spreadsheet 2.0.0 → 3.0.0

package/README.md

@@ -16,12 +16,14 @@ This plugin provides a full-featured spreadsheet component with:
 - Lookup functions (VLOOKUP, HLOOKUP, INDEX, MATCH)
 - Financial functions (PMT, PV, FV, NPV, IRR)
 - Multi-sheet support
-- Excel file import/export (.xlsx)
+- Excel file export (.xlsx)
+- Saving to the host's artifacts area, with cell edits written back
+- UI in 8 languages, following the host's locale
 - Cell formatting and styling
 
 ## Important: SheetJS Dependency
 
-> **Note:** This package uses [SheetJS](https://docs.sheetjs.com/docs/getting-started/installation/nodejs/) for Excel file import/export.
+> **Note:** This package uses [SheetJS](https://docs.sheetjs.com/docs/getting-started/installation/nodejs/) for Excel file export.
 > SheetJS is **not installed from npm**, but directly from the official SheetJS CDN:
 > ```
 > https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz
@@ -58,10 +60,37 @@ import "@gui-chat-plugin/spreadsheet/style.css";
 
 ```typescript
 import { pluginCore, TOOL_NAME } from "@gui-chat-plugin/spreadsheet";
-// or
-import pluginCore from "@gui-chat-plugin/spreadsheet";
 ```
 
+## Saving workbooks (host integration)
+
+The plugin works in two modes, chosen by what the host passes to `execute`:
+
+- **With `files.artifacts`** (the gui-chat-protocol runtime capability): the workbook is written to `artifacts/spreadsheets/YYYY/MM/<id>.json` and `data.sheets` holds that path. The View reads and saves it through `useRuntime().dispatch`, so cell edits land in the same file and the model can read them back from it.
+- **Without it**: `data.sheets` holds the workbook itself, and edits are reported through `updateResult` only.
+
+The View sends two dispatch calls:
+
+| `kind` | other args | result |
+|--------|-----------|--------|
+| `loadSpreadsheet` | `path` | `{ data: { sheets } }` |
+| `saveSpreadsheet` | `path`, `sheets` | `{ data: { sheets: path } }` |
+
+`path` must be a `.json` file under `artifacts/spreadsheets/`.
+
+A host that routes the View's `dispatch` to the plugin's own `execute` (as MulmoTerminal does) needs nothing more: `pluginCore.execute` tells the two calls apart by `kind`. A host with its own dispatch route can call `executeSpreadsheetDispatch(files.artifacts, args)` after checking `isSpreadsheetDispatchArgs(args)`.
+
+The View must be rendered inside the host's `PLUGIN_RUNTIME_KEY` provider to load or save a saved workbook; it also takes the UI language from that runtime (`en`, `ja`, `de`, `es`, `fr`, `ko`, `pt-BR`, `zh`, falling back to English).
+
+## Upgrading from 2.x
+
+3.0.0 changes what a host receives, so it is a major release:
+
+- `SpreadsheetToolData.sheets` is `SpreadsheetSheet[] | string`. With `files.artifacts` the tool returns the saved file's path instead of the workbook, so code that reads `data.sheets` as an array has to handle the path (or load it with the `loadSpreadsheet` dispatch).
+- `pluginCore.execute` also accepts `SpreadsheetDispatchArgs`.
+- The `gui-chat-protocol` peer is `^2.3.0`, and the package no longer bundles it: the host's copy is used.
+- Cells may hold a boolean `v`, and stored workbooks may contain bare values, `null` gaps and `{}` cells (`StorableCell`).
+
 ## Package Exports
 
 | Export | Description |

package/dist/core/dispatch.d.ts

@@ -0,0 +1,8 @@
+import type { FileOps, ToolResult } from "gui-chat-protocol";
+import type { SpreadsheetDispatchArgs, SpreadsheetToolData } from "./types";
+export declare function isSpreadsheetDispatchArgs(value: unknown): value is SpreadsheetDispatchArgs;
+/** `files.artifacts` off a host context, when the host provides it. The
+ *  protocol's `ToolContext` does not declare `files`, so it is checked rather
+ *  than assumed. */
+export declare function artifactsFileOps(context: unknown): FileOps | null;
+export declare function executeSpreadsheetDispatch(artifacts: FileOps, args: SpreadsheetDispatchArgs): Promise<ToolResult<SpreadsheetToolData, never>>;

package/dist/core/index.d.ts

@@ -2,8 +2,10 @@
  * Spreadsheet Plugin - Core (Framework-agnostic)
  *
  * This module exports the core plugin logic without UI components.
- * Import from "@anthropic/guichat-plugin-spreadsheet" or "@anthropic/guichat-plugin-spreadsheet/core"
+ * Import from "@gui-chat-plugin/spreadsheet" or "@gui-chat-plugin/spreadsheet/core"
  */
-export type { SpreadsheetCell, SpreadsheetSheet, SpreadsheetToolData, SpreadsheetArgs, } from "./types";
+export type { SpreadsheetCell, SpreadsheetCellValue, StorableCell, SpreadsheetSheet, SpreadsheetToolData, SpreadsheetArgs, SpreadsheetDispatchArgs, } from "./types";
 export { TOOL_NAME, TOOL_DEFINITION, SYSTEM_PROMPT, executeSpreadsheet, pluginCore, } from "./plugin";
+export { executeSpreadsheetDispatch, isSpreadsheetDispatchArgs } from "./dispatch";
+export { isSpreadsheetArtifactPath } from "./paths";
 export { samples } from "./samples";

package/dist/core/paths.d.ts

@@ -0,0 +1,13 @@
+export interface SpreadsheetPath {
+    /** Relative to the artifacts root — what `files.artifacts` takes. */
+    relPath: string;
+    /** Workspace-relative — what the tool reports and the View dispatches. */
+    filePath: string;
+}
+export declare function spreadsheetArtifactPath(now?: Date, fileId?: string): SpreadsheetPath;
+/** True for a workspace-relative path inside `artifacts/spreadsheets/` ending
+ *  in `.json`, with no traversal, empty, or backslash segments. */
+export declare function isSpreadsheetArtifactPath(value: unknown): value is string;
+/** `artifacts/spreadsheets/…` → `spreadsheets/…`. Assumes the input passed
+ *  `isSpreadsheetArtifactPath`. */
+export declare const toArtifactsRelative: (filePath: string) => string;

package/dist/core/plugin.d.ts

@@ -5,7 +5,11 @@
  * Can be used by any framework (Vue, React, etc.)
  */
 import type { ToolPluginCore, ToolContext, ToolResult } from "gui-chat-protocol";
-import type { SpreadsheetToolData, SpreadsheetArgs } from "./types";
+import type { SpreadsheetToolData, SpreadsheetArgs, SpreadsheetDispatchArgs } from "./types";
 export { TOOL_NAME, TOOL_DEFINITION, SYSTEM_PROMPT } from "./definition";
-export declare const executeSpreadsheet: (_context: ToolContext, args: SpreadsheetArgs) => Promise<ToolResult<SpreadsheetToolData, never>>;
-export declare const pluginCore: ToolPluginCore<SpreadsheetToolData, never, SpreadsheetArgs>;
+/**
+ * Create a spreadsheet. With the host's `files.artifacts`, the workbook is
+ * saved and `data.sheets` carries its path; without it, the workbook itself.
+ */
+export declare const executeSpreadsheet: (context: ToolContext, args: SpreadsheetArgs) => Promise<ToolResult<SpreadsheetToolData, never>>;
+export declare const pluginCore: ToolPluginCore<SpreadsheetToolData, never, SpreadsheetArgs | SpreadsheetDispatchArgs>;

package/dist/core/sheetGuards.d.ts

@@ -0,0 +1,5 @@
+import type { SpreadsheetSheet } from "./types";
+export declare const isSheet: (value: unknown) => value is SpreadsheetSheet;
+/** Taken whole or rejected whole — dropping the unreadable half of a workbook
+ *  would hide part of a user's file behind cells that merely look empty. */
+export declare function readSheets(value: unknown): SpreadsheetSheet[] | null;

package/dist/core/types.d.ts

@@ -4,18 +4,40 @@
  * Plugin-specific types only.
  * Common types are imported from gui-chat-protocol.
  */
+/** Mirrors the engine's `StoredCellValue`. */
+export type SpreadsheetCellValue = string | number | boolean;
 export interface SpreadsheetCell {
-    v: string | number;
+    v: SpreadsheetCellValue;
     f?: string;
 }
+/** A cell as a stored workbook actually holds it. The engine's `normalizeData`
+ *  folds all four forms, and models and hand edits write all four, so a
+ *  workbook read back off disk cannot promise `{ v }` for every cell. The tool
+ *  SCHEMA is deliberately stricter — it says what a caller should emit, not
+ *  what an existing file may contain. */
+export type StorableCell = SpreadsheetCell | {
+    v?: null;
+    f?: string;
+} | SpreadsheetCellValue | null;
 export interface SpreadsheetSheet {
     name: string;
-    data: Array<Array<SpreadsheetCell>>;
+    data: StorableCell[][];
 }
+/** `sheets` is the workbook itself, or — when the host gave the plugin
+ *  `files.artifacts` — the workspace-relative path it was saved to. */
 export interface SpreadsheetToolData {
-    sheets: SpreadsheetSheet[];
+    sheets: SpreadsheetSheet[] | string;
 }
 export interface SpreadsheetArgs {
     title: string;
     sheets: SpreadsheetSheet[];
 }
+/** What the View sends through `useRuntime().dispatch`. */
+export type SpreadsheetDispatchArgs = {
+    kind: "loadSpreadsheet";
+    path: string;
+} | {
+    kind: "saveSpreadsheet";
+    path: string;
+    sheets: SpreadsheetSheet[];
+};

package/dist/core.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./samples-ClV76j10.cjs");exports.SYSTEM_PROMPT=e.i,exports.TOOL_DEFINITION=e.a,exports.TOOL_NAME=e.o,exports.executeSpreadsheet=e.n,exports.pluginCore=e.r,exports.samples=e.t;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./samples-BzI0GdUj.cjs");exports.SYSTEM_PROMPT=e.d,exports.TOOL_DEFINITION=e.f,exports.TOOL_NAME=e.p,exports.executeSpreadsheet=e.n,exports.executeSpreadsheetDispatch=e.i,exports.isSpreadsheetArtifactPath=e.s,exports.isSpreadsheetDispatchArgs=e.a,exports.pluginCore=e.r,exports.samples=e.t;

package/dist/core.js

@@ -1,2 +1,2 @@
-import { a as e, i as t, n, o as r, r as i, t as a } from "./samples-sKAnErVb.js";
-export { t as SYSTEM_PROMPT, e as TOOL_DEFINITION, r as TOOL_NAME, n as executeSpreadsheet, i as pluginCore, a as samples };
+import { a as e, d as t, f as n, i as r, n as i, p as a, r as o, s, t as c } from "./samples-Cylf7cMw.js";
+export { t as SYSTEM_PROMPT, n as TOOL_DEFINITION, a as TOOL_NAME, i as executeSpreadsheet, r as executeSpreadsheetDispatch, s as isSpreadsheetArtifactPath, e as isSpreadsheetDispatchArgs, o as pluginCore, c as samples };

package/dist/engine/calculator.d.ts

@@ -3,7 +3,18 @@
  *
  * Core calculation engine with circular reference detection and cross-sheet support
  */
-import type { SheetData, CalculatedSheet } from "./types";
+import type { SheetData, CalculatedSheet, SpreadsheetCell, CalculateOptions } from "./types";
+/**
+ * Normalize malformed data structures
+ * Some models generate flat arrays instead of 2D arrays - fix them
+ *
+ * @param data - Potentially malformed sheet data
+ * @returns Normalized 2D array
+ */
+export declare function normalizeData(data: any): SpreadsheetCell[][];
+type SheetCalculateOptions = CalculateOptions & {
+    skipFormatting?: boolean;
+};
 /**
  * Calculate formulas in a single sheet
  *
@@ -11,11 +22,12 @@ import type { SheetData, CalculatedSheet } from "./types";
  * @param allSheets - All sheets for cross-sheet references
  * @returns Calculated sheet with formulas evaluated
  */
-export declare function calculateSheet(sheet: SheetData, allSheets?: SheetData[]): CalculatedSheet;
+export declare function calculateSheet(sheet: SheetData, allSheets?: SheetData[], options?: SheetCalculateOptions): CalculatedSheet;
 /**
  * Calculate all sheets in a workbook
  *
  * @param sheets - Array of sheets to calculate
  * @returns Array of calculated sheets
  */
-export declare function calculateWorkbook(sheets: SheetData[]): CalculatedSheet[];
+export declare function calculateWorkbook(sheets: SheetData[], options?: CalculateOptions): CalculatedSheet[];
+export {};

package/dist/engine/cellBuilder.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Build a SpreadsheetCell from the raw input captured by the mini
+ * editor (type + value / formula / format). Extracted from
+ * `saveMiniEditor` in `src/plugins/spreadsheet/View.vue` where it
+ * was inlined as ~30 lines of nested if/else that pushed the
+ * surrounding function over the cognitive-complexity threshold.
+ *
+ * Pure — no refs, no DOM, no side effects. Given the same inputs
+ * it always returns the same SpreadsheetCell. Tested in
+ * `test/plugins/spreadsheet/engine/test_cellBuilder.ts`.
+ */
+import type { SpreadsheetCell } from "./types.js";
+/** Inputs to the cell builder. Mirrors the mini editor refs in the
+ *  View but as plain values so unit tests don't need a Vue runtime. */
+export interface MiniEditorInput {
+    /** "string" → value is stored as-is as a string.
+     *  Anything else → the `formula` field is parsed (formula / number / raw string). */
+    type: string;
+    /** Used when type === "string". Coerced to string. */
+    value: unknown;
+    /** Used when type !== "string". Trimmed before classification. */
+    formula?: string;
+    /** Optional format code (e.g. "$#,##0.00"). */
+    format?: string;
+}
+/**
+ * Best-effort formula detection. The rules are conservative enough
+ * that plain text like "hello world" stays as text, but any input
+ * with arithmetic operators or function calls is treated as a
+ * formula and gets the "=" prefix the engine expects.
+ */
+export declare function looksLikeFormula(input: string): boolean;
+/**
+ * Parse the raw (non-string-type) editor input into a cell value.
+ * Priority: formula > number > raw string > empty string.
+ */
+export declare function parseNonStringInput(raw: string): number | string;
+/**
+ * Build the full SpreadsheetCell from a mini editor input record.
+ * String type short-circuits to `{ v: String(value) }`.
+ * Everything else goes through parseNonStringInput for formula /
+ * number / text classification, then optionally attaches `f`.
+ */
+export declare function buildCellFromInput(input: MiniEditorInput): SpreadsheetCell;

package/dist/engine/cellEmpty.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Telling a genuinely empty cell apart from one that holds the number 0.
+ *
+ * The calculator reads a blank cell as 0 for arithmetic (`=A1+1` on a blank A1
+ * is 1, as in Excel). But an aggregate must not: `AVERAGE` divides by the count
+ * of real values, and `COUNT` counts numbers — a blank that reads as 0 inflates
+ * the denominator and the count. So range collection needs to skip the blanks,
+ * which means distinguishing them from a stored 0, which this does.
+ */
+/** True when a cell holds no value at all — absent, null, or an empty/whitespace
+ *  string, in either the bare or the `{ v }` form. A cell containing the number
+ *  0, `false`, or any non-empty text is NOT empty. */
+export declare function isEmptyCell(cell: unknown): boolean;

package/dist/engine/cellFormatting.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Cell display formatting
+ *
+ * Turns a cell's raw calculated value into its display value (currency,
+ * percentage, date, ...). Pure — no engine state — so cross-sheet reference
+ * resolution can deliberately SKIP it and keep raw serial numbers, while the
+ * final output pass applies it for presentation.
+ */
+import type { CellValue, StoredCellValue } from "./types";
+/** An integer within the date-serial window — a calculated number the engine
+ *  should display as a date when the cell carries no explicit format. */
+export declare const isLikelyDateSerial: (value: CellValue) => boolean;
+/**
+ * Resolve the display value of one cell from its original definition and its
+ * calculated value.
+ *
+ * - A formula error renders as its code, so the cell still reads `#NUM!`.
+ * - Explicit format code wins (currency, percentage, date, ...).
+ * - A formula that produced a date serial auto-formats as a date.
+ * - Everything else (text, plain numbers, empty) passes through unchanged.
+ *
+ * The result is always a STORED value: this is the boundary where a computed
+ * error becomes the text a cell shows and a workbook serializes.
+ */
+export declare const formatCellForDisplay: (originalCell: unknown, calculatedValue: CellValue, preferDDMMYYYY: boolean) => StoredCellValue;

package/dist/engine/coerce-boolean.d.ts

@@ -0,0 +1,7 @@
+import type { CellValue } from "./types";
+/** Excel-style truthiness, shared by IF and AND/OR/NOT so the same value cannot
+ *  read as true in one function and false in another. A number is false only
+ *  when 0; blank and empty text are false; the words `true`/`false` are their
+ *  logical values (case-insensitively); a numeric string follows its number
+ *  (`"0"` → false); any other non-empty text is true. */
+export declare function coerceToBoolean(value: CellValue | null | undefined): boolean;

package/dist/engine/condition.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Evaluating a spreadsheet condition without running it as code.
+ *
+ * A condition is one comparison, or a bare value tested for truthiness. That is
+ * the whole grammar — small enough to read directly, which is the point: the
+ * previous implementation handed the substituted text to `eval`, so a cell
+ * containing `globalThis.x = 1` executed when any IFS referenced it.
+ */
+import type { CellValue } from "./types";
+export type ComparisonOperator = ">=" | "<=" | "<>" | "!=" | "==" | "=" | ">" | "<";
+export interface Comparison {
+    left: string;
+    operator: ComparisonOperator;
+    right: string;
+}
+/** Remove parentheses that wrap the WHOLE expression, repeatedly. `(1>0)` is
+ *  the same condition as `1>0`, but `(A)=(B)` is not `A)=(B` — the leading `(`
+ *  closes before the end, so it wraps only its own operand and must stay.
+ *  Unbalanced input is left untouched rather than guessed at. */
+export declare function stripOuterParens(condition: string): string;
+/** Split a condition into its two sides, or null when it holds no comparison.
+ *  Only the FIRST top-level operator counts — `a>b>c` is not a chain here, and
+ *  treating it as one is what let `1=1=1` reach a JS parser before.
+ *
+ *  "Top-level" means outside quotes: a cell holding `a>b` substitutes into the
+ *  condition as `"a>b"`, and splitting on that `>` would compare two fragments
+ *  of one string literal. */
+export declare function splitComparison(condition: string): Comparison | null;
+/** Read an operand as the value it denotes: a quoted string stays text, a
+ *  numeric literal becomes a number, `TRUE`/`FALSE` become booleans, and
+ *  anything else stays the text it already is. */
+export declare function readOperand(raw: string): CellValue;
+/** True when a bare (non-comparison) condition counts as satisfied. */
+export declare function isTruthyCondition(raw: string): boolean;
+/** Evaluate a condition — one comparison, or a value tested for truthiness.
+ *  Never executes its input. */
+export declare function evaluateCondition(condition: string): boolean;
+/** Like `evaluateCondition`, but each operand is resolved by `evaluate` — so a
+ *  caller holding the engine can compute arithmetic and sub-expressions
+ *  (`5+1>10`) instead of reading each side as a bare string. It still never runs
+ *  the condition as code: it only splits on the top-level comparison and
+ *  compares the two resolved values. */
+export declare function evaluateConditionValues(condition: string, evaluate: (operand: string) => CellValue): boolean;
+/** Render a cell's value as an operand for a condition string. A string is
+ *  quoted, with its own quotes and backslashes escaped, so its contents cannot
+ *  be re-parsed as operators — `evaluateCondition` then unquotes it back to the
+ *  original text. A missing value becomes an empty string; numbers and booleans
+ *  render as themselves. */
+export declare function renderConditionOperand(value: CellValue | null | undefined): string;

package/dist/engine/date-locale.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Which order an ambiguous slash date is written in, per locale.
+ *
+ * Only dates whose two leading numbers are BOTH 12 or under are ambiguous —
+ * `13/04/2025` can only be day-first, and `04/13/2025` can only be month-first,
+ * so those decide themselves. This is purely about `03/04/2025`.
+ */
+/** True when an ambiguous `A/B/YYYY` should read as day-first. Accepts a full
+ *  BCP 47 tag or a bare language subtag; the region is used when present so a
+ *  caller that can supply `en-GB` gets the right answer even though the app's
+ *  own locale resolution discards it. */
+export declare function prefersDayFirst(locale: string | undefined | null): boolean;

package/dist/engine/date-parser.d.ts

@@ -10,6 +10,12 @@
  * @returns true if string matches common date patterns
  */
 export declare function isDateLike(str: string): boolean;
+/**
+ * Build the Excel serial number for a year/month/day triple, or null when the
+ * triple is not a valid calendar date. Every dated branch of `parseDate` ends in
+ * this same validate → Date.UTC → dateToSerial step.
+ */
+export declare function serialFromParts(year: number, month: number, day: number): number | null;
 /**
  * Parse a date string into Excel serial number
  *
@@ -31,4 +37,4 @@ export declare function parseDate(dateStr: string, preferDDMMYYYY?: boolean): nu
  * @param originalStr - Original date string
  * @returns Appropriate format code
  */
-export declare function getDefaultDateFormat(originalStr: string): string;
+export declare function getDefaultDateFormat(originalStr: string, preferDDMMYYYY?: boolean): string;

package/dist/engine/date-utils.d.ts

@@ -19,13 +19,16 @@ export declare const dateToSerial: (date: Date) => number;
  * @returns JavaScript Date object
  */
 export declare const serialToDate: (serial: number) => Date;
+/** A name list that always has a first entry, so a formatter can fall back to it
+ *  when a date is unreadable and its month/weekday index comes out NaN. */
+export type NameList = readonly [string, ...string[]];
 /**
  * Month names for formatting
  */
-export declare const MONTH_NAMES_SHORT: string[];
-export declare const MONTH_NAMES_FULL: string[];
+export declare const MONTH_NAMES_SHORT: NameList;
+export declare const MONTH_NAMES_FULL: NameList;
 /**
  * Day names for formatting
  */
-export declare const DAY_NAMES_SHORT: string[];
-export declare const DAY_NAMES_FULL: string[];
+export declare const DAY_NAMES_SHORT: NameList;
+export declare const DAY_NAMES_FULL: NameList;

package/dist/engine/datedif.d.ts

@@ -0,0 +1,13 @@
+/**
+ * DATEDIF — complete elapsed time between two dates, in a chosen unit.
+ *
+ * Pure: two Excel serials and a unit in, a number (or a formula error value)
+ * out. The unit branches each have their own boundary handling (month-end
+ * borrowing, year wraparound), which is exactly what makes them worth testing
+ * apart from the handler that reads the arguments.
+ */
+import { type SpreadsheetError } from "./spreadsheet-errors";
+/** Complete `unit`s between two dates, or `#NUM!` when start is after end or
+ *  the unit is not one of Y / M / D / MD / YM / YD. `unit` is matched
+ *  case-insensitively. */
+export declare function computeDatedif(startSerial: number, endSerial: number, unit: string): number | SpreadsheetError;

package/dist/engine/evaluator.d.ts

@@ -10,9 +10,48 @@ import type { CellValue } from "./types";
 export interface EvaluatorContext {
     getCellValue: (ref: string) => CellValue;
     getRangeValues: (range: string) => CellValue[];
-    getRangeValuesRaw?: (range: string) => CellValue[];
+    getRangeValuesRaw?: ((range: string) => CellValue[]) | undefined;
     evaluateFormula: (formula: string) => CellValue;
+    /** Reading order for an ambiguous slash date; see engine/date-locale.ts. */
+    preferDDMMYYYY?: boolean | undefined;
 }
+/** Render a cell's value as the text that stands in for it inside an
+ *  expression. Strings are quoted so they cannot be read as identifiers or
+ *  operators, and their own quotes and backslashes are escaped so the literal
+ *  cannot be closed early. A missing value becomes 0, matching how blanks are
+ *  treated everywhere else in the engine. */
+export declare function renderOperand(value: CellValue | null | undefined): string;
+/** Replace every quoted string literal with an empty pair of quotes, honouring
+ *  `\` escapes so an escaped quote does not end the literal early. Used to
+ *  validate the STRUCTURE of a concat/arithmetic expression without letting the
+ *  arbitrary CONTENT of a string decide whether the whole thing looks safe. */
+export declare function maskStringLiterals(expr: string): string;
+/** Whether a `&`-to-`+` concatenation expression is safe to evaluate. Checks the
+ *  structure with string CONTENT masked out — a string literal may hold any
+ *  character (a `!`, a `\`), and validating those against a character allowlist
+ *  rejected valid formulas like `=A1&"!"` and every escaped operand. Once the
+ *  literals are masked, only the joining structure remains to validate. */
+export declare function isSafeConcatExpression(expr: string): boolean;
+/** Index just past the string literal that opens at `start` (a quote char),
+ *  honouring `\` escapes so an escaped quote does not close it early. Returns
+ *  `expr.length` when the literal is never closed. */
+export declare function endOfStringLiteral(expr: string, start: number): number;
+/** Every cell reference in an expression, as `{ref, start}` spans in source
+ *  order. Quoted string literals are skipped whole: a `"A1"` in the text is a
+ *  constant, not a reference, and substituting it would turn `="A1"&"!"` into
+ *  A1's value. A `'` opens either a `'Sheet'!A1` reference or a string literal —
+ *  only the former is a reference; the latter is skipped like a `"` literal. */
+export interface CellRefSpan {
+    ref: string;
+    start: number;
+}
+export declare function findCellRefs(expr: string): CellRefSpan[];
+/** Replace every reference span in `expr` with the text `render` gives for it,
+ *  walking BACK TO FRONT so the spans ahead of each edit stay valid. A global
+ *  string replace rewrote every occurrence of the shorter reference first, so
+ *  `=A1+A10` had its `A10` broken into `<A1's value>0` and produced a plausible
+ *  wrong number (#2357). */
+export declare function substituteCellRefs(expr: string, cellRefs: CellRefSpan[], render: (ref: string) => string): string;
 /**
  * Parse function arguments, handling nested functions and quoted strings
  *
@@ -29,6 +68,10 @@ export declare function parseFunctionArgs(argsStr: string): string[];
  * - Arithmetic: 2+3, A1*B1, (A1+B1)/2
  * - Nested expressions: ROUND(SUM(A1:A10)/COUNT(A1:A10), 2)
  *
+ * A genuine failure THROWS (a typed FormulaError or any handler error) rather
+ * than returning the raw formula text; the calculator classifies it into
+ * errors[] and shows the Excel error value in the cell (#2359).
+ *
  * @param formula - Formula string (without leading =)
  * @param context - Evaluation context with cell/range accessors
  * @returns Evaluated result (number or string)

package/dist/engine/financial-math.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Annuity math for the financial functions, as pure numeric helpers.
+ *
+ * Excel's cash-flow sign convention: money received is positive, money paid out
+ * is negative — so a loan's `pv` is positive and its payment and interest come
+ * back negative. Keeping the per-period split as plain number-in / number-out
+ * functions lets it be tested against known Excel values without routing string
+ * arguments back through the formula evaluator.
+ */
+import { type SpreadsheetError } from "./spreadsheet-errors";
+/** Future value after `nper` periods. `type` is 0 (end of period) or 1 (begin). */
+export declare function computeFv(rate: number, nper: number, pmt: number, pv: number, type: number): number;
+/** Constant per-period payment amortising a present value `pv` to `fv`. */
+export declare function computePmt(rate: number, nper: number, pv: number, fv: number, type: number): number;
+/** Interest portion of the `per`-th payment. */
+export declare function computeIpmt(rate: number, per: number, nper: number, pv: number, fv: number, type: number): number;
+/** Principal portion of the `per`-th payment (total payment minus interest). */
+export declare function computePpmt(rate: number, per: number, nper: number, pv: number, fv: number, type: number): number;
+/** Present value of an annuity that grows to `fv` after `nper` payments of `pmt`. */
+export declare function computePv(rate: number, nper: number, pmt: number, fv: number, type: number): number;
+/** Number of periods needed to amortise `pv` to `fv` at constant `pmt`. */
+export declare function computeNper(rate: number, pmt: number, pv: number, fv: number, type: number): number;
+/** Interest rate per period solving the annuity equation, via Newton-Raphson. */
+export declare function computeRate(nper: number, pmt: number, pv: number, fv: number, type: number, guess: number): number | SpreadsheetError;
+/** Net present value of `cashflows`, each discounted one period further into the future. */
+export declare function computeNpv(rate: number, cashflows: number[]): number;
+/** Internal rate of return of `values` (element 0 at period 0), via Newton-Raphson. */
+export declare function computeIrr(values: number[], guess: number): number | SpreadsheetError;

package/dist/engine/formatter.d.ts

@@ -3,6 +3,15 @@
  *
  * Handles Excel-style format codes for currency, percentages, decimals, dates, etc.
  */
+/**
+ * Insert thousands separators into a run of digits ("1234567" → "1,234,567").
+ * Regex free on purpose: the classic `\B(?=(\d{3})+(?!\d))` lookahead
+ * backtracks badly on a long run of digits.
+ */
+export declare const groupThousands: (digits: string) => string;
+/** Group the integer part of a formatted number ("1234567.89" → "1,234,567.89"),
+ *  leaving any fractional part after the decimal point untouched. */
+export declare const addThousandSeparators: (formatted: string) => string;
 /**
  * Format a number according to Excel format code
  *

package/dist/engine/formulaError.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Typed formula-evaluation errors
+ *
+ * A failed formula must surface as a typed error with an Excel-style error value
+ * in the cell, never as a swallowed bare string (issue #2359). This module holds
+ * the error taxonomy, the throwable carrier, and the pure helpers that classify a
+ * thrown error and propagate an error value across cell references. No engine
+ * state is captured — every export is input → output only.
+ */
+import type { CalculationError } from "./types";
+import type { SpreadsheetErrorCode } from "./spreadsheet-errors";
+/** The evaluator-facing error kinds: every `CalculationError["type"]` except
+ *  `circular`, which the calculator raises directly (not via a thrown error). */
+export type FormulaErrorType = Exclude<CalculationError["type"], "circular">;
+/** The error code shown for each kind, matching Excel's error literals. */
+export declare const FORMULA_ERROR_VALUES: Record<FormulaErrorType, SpreadsheetErrorCode>;
+/** A recoverable formula failure carrying the kind and the code to show. */
+export declare class FormulaError extends Error {
+    readonly errorType: FormulaErrorType;
+    readonly display: SpreadsheetErrorCode;
+    constructor(errorType: FormulaErrorType, display: SpreadsheetErrorCode, message?: string);
+}
+export declare const isFormulaError: (error: unknown) => error is FormulaError;
+export declare const divZeroError: () => FormulaError;
+export declare const invalidRefError: (ref: string) => FormulaError;
+export declare const nameError: (funcName: string) => FormulaError;
+export declare const unknownError: (message?: string) => FormulaError;
+/** The FormulaError that re-raises an error read from a referenced cell or a
+ *  nested call, so `=A1+1` inherits A1's error instead of corrupting into
+ *  `"#DIV/0!"+1`. */
+export declare const propagatedError: (value: SpreadsheetErrorCode) => FormulaError;
+/** Map any thrown value onto the typed entry the calculator records. A
+ *  `FormulaError` keeps its own kind and display; anything else is `unknown`. */
+export declare const classifyThrownError: (error: unknown) => {
+    type: FormulaErrorType;
+    display: SpreadsheetErrorCode;
+};

package/dist/engine/formulaRefs.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Extract the set of cells that a formula references.
+ *
+ * Extracted from `src/plugins/spreadsheet/View.vue` (was the body of
+ * `extractCellReferences`, cognitive complexity 32). The original
+ * function combined regex scanning, range expansion, single-cell
+ * parsing, and deduplication all in one body; splitting each concern
+ * into a named helper brings the top-level function well under the
+ * sonarjs/cognitive-complexity threshold of 15 and makes the pure
+ * logic unit-testable in isolation (see
+ * `test/plugins/spreadsheet/engine/test_formulaRefs.ts`).
+ *
+ * Tracks #175. No behavioural change — the wrapper in View.vue
+ * still returns exactly the same `{ row, col }` list as before.
+ */
+export interface CellCoord {
+    row: number;
+    col: number;
+}
+export declare function stripFormulaPrefix(formula: string): string;
+export declare function expandRange(rangeStr: string): CellCoord[];
+export declare function expandRangeOrCell(ref: string): CellCoord[] | null;
+export declare function parseSingleCellRef(refStr: string): CellCoord | null;
+export interface RangeBounds {
+    sheetPrefix: string;
+    startCol: number;
+    startRow: number;
+    endCol: number;
+    endRow: number;
+}
+export declare function parseRangeBounds(range: string): RangeBounds | null;
+export declare function resolveIndexTarget(bounds: RangeBounds, rowNum: number, colNum: number): {
+    colIndex: number;
+    row: number;
+} | null;
+export declare function resolveTableOffset(position: number, size: number): number | null;
+export declare function extractCellReferences(formula: string): CellCoord[];

package/dist/engine/functions/lookup-math.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pure lookup rules, separated from the range-reading handlers so they can be
+ * unit-tested directly.
+ */
+import type { CellValue } from "../types";
+/**
+ * Interpret VLOOKUP/HLOOKUP's 4th argument (range_lookup): TRUE (or omitted) =
+ * approximate match, FALSE = exact.
+ *
+ * The literal `TRUE` reaches the handler as the STRING `"TRUE"` — the evaluator
+ * leaves bare words unquoted — so an accept-only-`true | 1 | "1"` check silently
+ * fell back to exact match and returned `#N/A` for a valid approximate lookup
+ * (#2360). Read it the way Excel coerces a logical instead: a boolean as-is, a
+ * non-zero number as TRUE, and the words `TRUE` / `FALSE` (case-insensitive)
+ * and `"1"` / `"0"` as their logical value. Anything else (blank, stray text)
+ * is treated as FALSE, matching Excel's coercion of a blank range_lookup — and
+ * so is a formula error, which is neither of the two logicals.
+ */
+export declare function isApproximateMatch(rangeLookup: CellValue): boolean;