@gui-chat-plugin/spreadsheet 4.1.0 → 4.2.0

package/README.md

@@ -74,11 +74,13 @@ The View sends two dispatch calls:
 
 | `kind` | other args | result |
 |--------|-----------|--------|
-| `loadSpreadsheet` | `path` | `{ data: { sheets } }` |
-| `saveSpreadsheet` | `path`, `sheets` | `{ data: { sheets: path } }` |
+| `loadSpreadsheet` | `path` | `{ data: { sheets, version } }` |
+| `saveSpreadsheet` | `path`, `sheets`, `baseVersion?` | `{ data: { sheets: path, version } }`, or `{ data: { sheets, version, conflict: true } }` |
 
 `path` must be a `.json` file under `artifacts/spreadsheets/`.
 
+`version` is the SHA-256 of the file's text. The View saves with the `baseVersion` of the sheets it shows, and the save is written only while the file still has that version. When an agent or another View wrote the file in between, nothing is written: the answer carries the file's current `sheets` and `version` with `conflict: true`, and the View asks the user to keep that version or save their edit over it. A save without `baseVersion` is written unconditionally, as before. Saves of one file through the plugin are serialized, so two Views cannot both pass the check; a write that bypasses the plugin can still land between a save's check and its write, because `files.artifacts` has no compare-and-write.
+
 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).
@@ -109,7 +111,11 @@ The View must be rendered inside the host's `PLUGIN_RUNTIME_KEY` provider to loa
 `CONCAT`, `CONCATENATE`, `EXACT`, `FIND`, `LEFT`, `LEN`, `LOWER`, `MID`, `PROPER`, `REPLACE`, `RIGHT`, `SEARCH`, `SUBSTITUTE`, `TEXT`, `TRIM`, `UPPER`, `VALUE`
 
 ### Date & Time
-`DATE`, `DATEDIF`, `DAY`, `HOUR`, `MINUTE`, `MONTH`, `NOW`, `SECOND`, `TIME`, `TODAY`, `YEAR`
+`DATE`, `DATEDIF`, `DAY`, `DAYS`, `EDATE`, `EOMONTH`, `HOUR`, `MINUTE`, `MONTH`, `NETWORKDAYS`, `NOW`, `SECOND`, `TIME`, `TODAY`, `WEEKDAY`, `WORKDAY`, `YEAR`
+
+A formula without a format code shows its number as a date only when the number is a date by origin: the formula starts with DATE, TODAY, EDATE, EOMONTH or WORKDAY, or its first reference is a date (a cell with a date format, typed as a date, or itself such a formula, on any sheet). A total that lands on 52,345 stays a number. Give a formula a format code to choose its display yourself.
+
+Dates are serial numbers on the real calendar, as in LibreOffice and Google Sheets. Excel counts a 1900-02-29 that never existed, so a serial before 61 (1900-03-01) is one day earlier here than in Excel; from 61 on they are the same.
 
 ### Logical
 `AND`, `FALSE`, `IF`, `IFERROR`, `IFNA`, `IFS`, `NOT`, `OR`, `TRUE`
@@ -118,11 +124,35 @@ The View must be rendered inside the host's `PLUGIN_RUNTIME_KEY` provider to loa
 `HLOOKUP`, `INDEX`, `MATCH`, `VLOOKUP`, `XLOOKUP`
 
 ### Statistical
-`AVERAGE`, `AVERAGEIF`, `AVERAGEIFS`, `CORREL`, `COUNT`, `COUNTA`, `COUNTIF`, `COUNTIFS`, `INTERCEPT`, `LARGE`, `MAX`, `MEDIAN`, `MIN`, `MODE`, `PERCENTILE`, `QUARTILE`, `RANK`, `RSQ`, `SLOPE`, `SMALL`, `STDEV`, `STDEVP`, `SUM`, `SUMIF`, `SUMIFS`, `VAR`, `VARP`
+`AVERAGE`, `AVERAGEIF`, `AVERAGEIFS`, `CONFIDENCE.NORM`, `CONFIDENCE.T`, `CORREL`, `COUNT`, `COUNTA`, `COUNTIF`, `COUNTIFS`, `COVARIANCE.P`, `COVARIANCE.S`, `FORECAST`, `FORECAST.LINEAR`, `GEOMEAN`, `HARMEAN`, `INTERCEPT`, `KURT`, `LARGE`, `MAX`, `MAXIFS`, `MEDIAN`, `MIN`, `MINIFS`, `MODE`, `NORM.DIST`, `NORM.INV`, `NORM.S.DIST`, `NORM.S.INV`, `PEARSON`, `PERCENTILE`, `PERCENTILE.INC`, `PERCENTRANK`, `PERCENTRANK.INC`, `QUARTILE`, `QUARTILE.INC`, `RANK`, `RANK.EQ`, `RSQ`, `SKEW`, `SLOPE`, `SMALL`, `STANDARDIZE`, `STDEV`, `STDEV.P`, `STDEV.S`, `STDEVP`, `STEYX`, `SUM`, `SUMIF`, `SUMIFS`, `T.DIST`, `T.DIST.2T`, `T.DIST.RT`, `T.INV`, `T.INV.2T`, `T.TEST`, `TREND`, `TTEST`, `VAR`, `VAR.P`, `VAR.S`, `VARP`
 
 ### Financial
 `FV`, `IPMT`, `IRR`, `NPER`, `NPV`, `PMT`, `PPMT`, `PV`, `RATE`
 
+## Workbook functions
+
+A workbook can define functions of its own, for an analysis no built-in function does. Each sheet may carry an optional `functions` list; a function defined on any sheet is callable from every sheet of that workbook:
+
+```json
+{
+  "name": "Data",
+  "functions": [
+    {
+      "name": "MOVING.AVG",
+      "params": ["values", "n"],
+      "body": "const xs = values.flat().filter((v) => typeof v === 'number'); const tail = xs.slice(-n); return tail.reduce((a, b) => a + b, 0) / tail.length;"
+    }
+  ],
+  "data": [[{ "v": 100 }, { "v": "=MOVING.AVG(A1:A30, 7)" }]]
+}
+```
+
+- A function body is JavaScript, run in [QuickJS](https://github.com/justjake/quickjs-emscripten) (WebAssembly) with no DOM, network, file system or timers, at most 50 ms per call, 2 s per calculation and 16 MB of memory. Each function has a global scope of its own.
+- A range argument arrives as rows of cells (an array of arrays, a blank cell as `null`); a single cell and any other argument as its value. A whole column or row (`A:A`, `2:2`) is `#VALUE!`: the engine does not read those. An argument that is an error is passed on without calling the function.
+- Return a number, text or `true`/`false`. A time-out or a non-finite number shows `#NUM!`; a thrown error or any other return value shows `#VALUE!`.
+- A name is letters and digits, parts joined by dots, and cannot be a built-in function's. `presentSpreadsheet` says in its reply which definitions could not be used.
+- QuickJS loads only for a workbook that defines functions. The View and `readCalculatedRange` load it themselves; a host calling `calculatedRange` directly passes the set from `loadCustomFunctions`.
+
 ## Development
 
 ```bash

package/dist/core/contentVersion.d.ts

@@ -0,0 +1,5 @@
+/** The SHA-256 of `text`, in hex. Two texts get the same version only when they are equal. */
+export declare function contentVersion(text: string): Promise<string>;
+/** Whether a save based on `baseVersion` must not be written over a file now at `currentVersion`.
+ *  A save without a base (an older View) and a file that is gone are written as before. */
+export declare const isStaleBase: (baseVersion: string | undefined, currentVersion: string | null) => boolean;

package/dist/core/definition.d.ts

@@ -4,4 +4,4 @@
 import type { ToolDefinition } from "gui-chat-protocol";
 export declare const TOOL_NAME = "presentSpreadsheet";
 export declare const TOOL_DEFINITION: ToolDefinition;
-export declare const SYSTEM_PROMPT = "Use presentSpreadsheet whenever the user needs a spreadsheet-style table, multi-step math, or dynamic what-if analysis\u2014do not summarize in text. Build LIVE sheets where every cell is an object {\"v\": value, \"f\": format}. For formulas, set \"v\" to a string starting with \"=\" (e.g., {\"v\": \"=B2*1.05\", \"f\": \"$#,##0.00\"}). For dates, use date strings like \"01/15/2025\" or date formulas like \"=TODAY()\" or \"=DATE(2025,1,15)\". The spreadsheet auto-parses common date formats (MM/DD/YYYY, YYYY-MM-DD, DD-MMM-YYYY) into date serial numbers for calculations. Date arithmetic works: \"=B2-TODAY()\" calculates days between dates. Never pre-calculate; let the spreadsheet compute using cell refs, functions (SUM, AVERAGE, IF, TODAY, DATE, DATEDIF, etc.), and arithmetic. Standard formats: \"$#,##0.00\" currency, \"#,##0\" integer, \"0.00%\" percent, \"0.00\" decimal, \"MM/DD/YYYY\" date, \"DD-MMM-YYYY\" date, \"YYYY-MM-DD\" ISO date. Format is optional for plain text/numbers.";
+export declare const SYSTEM_PROMPT = "Use presentSpreadsheet whenever the user needs a spreadsheet-style table, multi-step math, or dynamic what-if analysis\u2014do not summarize in text. Build LIVE sheets where every cell is an object {\"v\": value, \"f\": format}. For formulas, set \"v\" to a string starting with \"=\" (e.g., {\"v\": \"=B2*1.05\", \"f\": \"$#,##0.00\"}). For dates, use date strings like \"01/15/2025\" or date formulas like \"=TODAY()\" or \"=DATE(2025,1,15)\". The spreadsheet auto-parses common date formats (MM/DD/YYYY, YYYY-MM-DD, DD-MMM-YYYY) into date serial numbers for calculations. Date arithmetic works: \"=B2-TODAY()\" calculates days between dates. Never pre-calculate; let the spreadsheet compute using cell refs, functions (SUM, AVERAGE, IF, TODAY, DATE, DATEDIF, etc.), and arithmetic. Standard formats: \"$#,##0.00\" currency, \"#,##0\" integer, \"0.00%\" percent, \"0.00\" decimal, \"MM/DD/YYYY\" date, \"DD-MMM-YYYY\" date, \"YYYY-MM-DD\" ISO date. Format is optional for plain text/numbers. When an analysis needs a method no built-in function has, define it once in the sheet's \"functions\" and call it from formulas, rather than pasting a computed number: it then recalculates when the data changes.";

package/dist/core/dispatch.d.ts

@@ -1,8 +1,8 @@
-import type { FileOps, ToolResult } from "gui-chat-protocol";
-import type { SpreadsheetDispatchArgs, SpreadsheetToolData } from "./types";
+import { type FileOps, type ToolResult } from "gui-chat-protocol";
+import type { SpreadsheetDispatchArgs, SpreadsheetFileData } 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>>;
+export declare function executeSpreadsheetDispatch(artifacts: FileOps, args: SpreadsheetDispatchArgs): Promise<ToolResult<SpreadsheetFileData, never>>;

package/dist/core/dispatchReplies.d.ts

@@ -0,0 +1,19 @@
+import type { SpreadsheetSheet } from "./types";
+export interface LoadedWorkbook {
+    sheets: SpreadsheetSheet[];
+    /** Absent when the answering plugin predates versions; saves are then unconditional. */
+    version: string | undefined;
+}
+export type SaveReply = {
+    kind: "saved";
+    version: string | undefined;
+} | {
+    kind: "conflict";
+    sheets: SpreadsheetSheet[];
+    version: string;
+};
+/** The workbook a load answered, or null when the answer holds no sheets. */
+export declare function readLoadReply(raw: unknown): LoadedWorkbook | null;
+/** What a save answered, or null for a conflict that does not carry the file's sheets and
+ *  version. Any other answer is a save: an older plugin answers `{ sheets: path }` only. */
+export declare function readSaveReply(raw: unknown): SaveReply | null;

package/dist/core/index.d.ts

@@ -4,7 +4,7 @@
  * This module exports the core plugin logic without UI components.
  * Import from "@gui-chat-plugin/spreadsheet" or "@gui-chat-plugin/spreadsheet/core"
  */
-export type { SpreadsheetCell, SpreadsheetCellValue, StorableCell, SpreadsheetSheet, SpreadsheetToolData, SpreadsheetArgs, SpreadsheetDispatchArgs, } from "./types";
+export type { SpreadsheetCell, SpreadsheetCellValue, StorableCell, SpreadsheetSheet, SpreadsheetToolData, SpreadsheetArgs, SpreadsheetDispatchArgs, SpreadsheetFileData, } from "./types";
 export { TOOL_NAME, TOOL_DEFINITION, SYSTEM_PROMPT, executeSpreadsheet, pluginCore } from "./plugin";
 export { executeSpreadsheetDispatch, isSpreadsheetDispatchArgs } from "./dispatch";
 export { isSpreadsheetArtifactPath } from "./paths";

package/dist/core/rangeValues.d.ts

@@ -1,5 +1,6 @@
 import type { FileOps } from "gui-chat-protocol";
 import { type StoredCellValue } from "../engine";
+import { type CustomFunctionSet } from "../engine/customFunctions";
 import type { SpreadsheetSheet } from "./types";
 /** One cell as a chart reads it: a number to plot, a label, or nothing. */
 export type RangeCell = string | number | null;
@@ -28,7 +29,7 @@ export declare function rangeCellValue(storedCell: unknown, calculated: StoredCe
  * Throws when the range is malformed, too large, or names a sheet the workbook
  * does not have.
  */
-export declare function calculatedRange(sheets: SpreadsheetSheet[], range: string): RangeCell[][];
+export declare function calculatedRange(sheets: SpreadsheetSheet[], range: string, functions?: CustomFunctionSet): RangeCell[][];
 /** `calculatedRange` of the workbook saved at `path` (`artifacts/spreadsheets/…json`). */
 export declare function readCalculatedRange(artifacts: FileOps, path: string, range: string): Promise<RangeCell[][]>;
 export {};

package/dist/core/types.d.ts

@@ -5,6 +5,7 @@
  * Common types are imported from gui-chat-protocol.
  */
 /** Mirrors the engine's `StoredCellValue`. */
+import type { CustomFunctionSpec } from "../engine/customFunctionSpecs";
 export type SpreadsheetCellValue = string | number | boolean;
 export interface SpreadsheetCell {
     v: SpreadsheetCellValue;
@@ -22,6 +23,8 @@ export type StorableCell = SpreadsheetCell | {
 export interface SpreadsheetSheet {
     name: string;
     data: StorableCell[][];
+    /** Functions this workbook defines, usable from any of its sheets (#114). */
+    functions?: CustomFunctionSpec[];
 }
 /** `sheets` is the workbook itself, or — when the host gave the plugin
  *  `files.artifacts` — the workspace-relative path it was saved to. */
@@ -32,7 +35,8 @@ export interface SpreadsheetArgs {
     title: string;
     sheets: SpreadsheetSheet[];
 }
-/** What the View sends through `useRuntime().dispatch`. */
+/** What the View sends through `useRuntime().dispatch`. A save with `baseVersion` is written
+ *  only while the file still holds that version, so it cannot overwrite a change made since. */
 export type SpreadsheetDispatchArgs = {
     kind: "loadSpreadsheet";
     path: string;
@@ -40,4 +44,13 @@ export type SpreadsheetDispatchArgs = {
     kind: "saveSpreadsheet";
     path: string;
     sheets: SpreadsheetSheet[];
+    baseVersion?: string;
 };
+/** What a load or save dispatch answers. `version` names the file's content as the answer
+ *  leaves it. With `conflict`, the save was not written: the file had changed since
+ *  `baseVersion`, and `sheets` is the file as it is now. */
+export interface SpreadsheetFileData {
+    sheets: SpreadsheetSheet[] | string;
+    version: string;
+    conflict?: true;
+}

package/dist/core-CwIoDrlM.js

@@ -0,0 +1,52 @@
+import { C as e, a as t, b as n, c as r, f as i, i as a, l as o, p as s, u as c, v as l, y as u } from "./samples-DBNVoegC.js";
+//#region src/core/rangeValues.ts
+var d = 1e5, f = (e) => {
+	if (!e) return null;
+	let t = e.slice(0, -1);
+	return t.startsWith("'") && t.endsWith("'") ? t.slice(1, -1).replaceAll("''", "'") : t;
+};
+function p(e) {
+	let t = e.lastIndexOf("!"), n = e.slice(t + 1), r = i(n.includes(":") ? e : `${e}:${n}`);
+	return !r || !s(n.split(":")[0] ?? "") ? null : {
+		sheetName: f(r.sheetPrefix),
+		startRow: Math.min(r.startRow, r.endRow) - 1,
+		endRow: Math.max(r.startRow, r.endRow) - 1,
+		startCol: Math.min(r.startCol, r.endCol),
+		endCol: Math.max(r.startCol, r.endCol)
+	};
+}
+var m = /[ymdhs]/i, h = (t) => e(t) && typeof t.f == "string" && t.f !== "" && !m.test(t.f);
+function g(e, t, n) {
+	return n === void 0 || n === "" ? null : typeof n == "number" ? n : typeof t == "number" && h(e) ? t : typeof n == "boolean" ? String(n).toUpperCase() : n;
+}
+var _ = (e) => ({
+	name: e.name,
+	data: t(e.data)
+}), v = ({ startRow: e, endRow: t }) => Array.from({ length: t - e + 1 }, (t, n) => e + n), y = ({ startCol: e, endCol: t }) => Array.from({ length: t - e + 1 }, (t, n) => e + n);
+function b(e, t, n = r) {
+	let i = p(t.trim());
+	if (!i) throw Error(`"${t}" is not a range such as Data!A1:C13`);
+	let s = (i.endRow - i.startRow + 1) * (i.endCol - i.startCol + 1);
+	if (s > 1e5) throw Error(`"${t}" has ${s} cells; the limit is ${d}`);
+	let c = i.sheetName === null ? 0 : e.findIndex((e) => e.name === i.sheetName), l = e[c];
+	if (c < 0 || !l) throw Error(`the spreadsheet has no sheet named "${i.sheetName ?? ""}"`);
+	let u = e.map(_), f = u[c] ?? _(l), { calculated: m, displayed: h } = o(n, () => ({
+		calculated: a(f, u, { skipFormatting: !0 }).data,
+		displayed: a(f, u).data
+	}));
+	return v(i).map((e) => y(i).map((t) => g(f.data[e]?.[t], x(m[e]?.[t]), x(h[e]?.[t]))));
+}
+var x = (e) => typeof e == "string" || typeof e == "number" || typeof e == "boolean" ? e : void 0;
+async function S(e, t, r) {
+	if (!u(t)) throw Error("path must be a .json file under artifacts/spreadsheets/");
+	let i = l(JSON.parse(await e.read(n(t))));
+	if (!i) throw Error(`${t} does not hold an array of sheets`);
+	let a = await c(i);
+	try {
+		return b(i, r, a);
+	} finally {
+		a.dispose();
+	}
+}
+//#endregion
+export { b as n, S as r, d as t };

package/dist/core-DHWKHgsJ.cjs

@@ -0,0 +1 @@
+const e=require("./samples-DyQFcwBX.cjs");var t=1e5,n=e=>{if(!e)return null;let t=e.slice(0,-1);return t.startsWith(`'`)&&t.endsWith(`'`)?t.slice(1,-1).replaceAll(`''`,`'`):t};function r(t){let r=t.lastIndexOf(`!`),i=t.slice(r+1),a=e.f(i.includes(`:`)?t:`${t}:${i}`);return!a||!e.p(i.split(`:`)[0]??``)?null:{sheetName:n(a.sheetPrefix),startRow:Math.min(a.startRow,a.endRow)-1,endRow:Math.max(a.startRow,a.endRow)-1,startCol:Math.min(a.startCol,a.endCol),endCol:Math.max(a.startCol,a.endCol)}}var i=/[ymdhs]/i,a=t=>e.C(t)&&typeof t.f==`string`&&t.f!==``&&!i.test(t.f);function o(e,t,n){return n===void 0||n===``?null:typeof n==`number`?n:typeof t==`number`&&a(e)?t:typeof n==`boolean`?String(n).toUpperCase():n}var s=t=>({name:t.name,data:e.a(t.data)}),c=({startRow:e,endRow:t})=>Array.from({length:t-e+1},(t,n)=>e+n),l=({startCol:e,endCol:t})=>Array.from({length:t-e+1},(t,n)=>e+n);function u(n,i,a=e.c){let u=r(i.trim());if(!u)throw Error(`"${i}" is not a range such as Data!A1:C13`);let f=(u.endRow-u.startRow+1)*(u.endCol-u.startCol+1);if(f>1e5)throw Error(`"${i}" has ${f} cells; the limit is ${t}`);let p=u.sheetName===null?0:n.findIndex(e=>e.name===u.sheetName),m=n[p];if(p<0||!m)throw Error(`the spreadsheet has no sheet named "${u.sheetName??``}"`);let h=n.map(s),g=h[p]??s(m),{calculated:_,displayed:v}=e.l(a,()=>({calculated:e.i(g,h,{skipFormatting:!0}).data,displayed:e.i(g,h).data}));return c(u).map(e=>l(u).map(t=>o(g.data[e]?.[t],d(_[e]?.[t]),d(v[e]?.[t]))))}var d=e=>typeof e==`string`||typeof e==`number`||typeof e==`boolean`?e:void 0;async function f(t,n,r){if(!e.y(n))throw Error(`path must be a .json file under artifacts/spreadsheets/`);let i=e.v(JSON.parse(await t.read(e.b(n))));if(!i)throw Error(`${n} does not hold an array of sheets`);let a=await e.u(i);try{return u(i,r,a)}finally{a.dispose()}}Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return u}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return f}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return t}});

package/dist/core.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./samples-B6CgK8O-.cjs"),t=require("./core-PwJLsuHs.cjs");exports.MAX_RANGE_CELLS=t.t,exports.SYSTEM_PROMPT=e.b,exports.TOOL_DEFINITION=e.x,exports.TOOL_NAME=e.S,exports.calculatedRange=t.n,exports.executeSpreadsheet=e.u,exports.executeSpreadsheetDispatch=e.f,exports.isSpreadsheetArtifactPath=e.h,exports.isSpreadsheetDispatchArgs=e.p,exports.pluginCore=e.d,exports.readCalculatedRange=t.r,exports.samples=e.t;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./samples-DyQFcwBX.cjs"),t=require("./core-DHWKHgsJ.cjs");exports.MAX_RANGE_CELLS=t.t,exports.SYSTEM_PROMPT=e.w,exports.TOOL_DEFINITION=e.T,exports.TOOL_NAME=e.E,exports.calculatedRange=t.n,exports.executeSpreadsheet=e.o,exports.executeSpreadsheetDispatch=e.g,exports.isSpreadsheetArtifactPath=e.y,exports.isSpreadsheetDispatchArgs=e._,exports.pluginCore=e.s,exports.readCalculatedRange=t.r,exports.samples=e.t;

package/dist/core.js

@@ -1,3 +1,3 @@
-import { S as e, b as t, d as n, f as r, h as i, p as a, t as o, u as s, x as c } from "./samples-miYeCJeQ.js";
-import { n as l, r as u, t as d } from "./core-CaJMHb3p.js";
-export { d as MAX_RANGE_CELLS, t as SYSTEM_PROMPT, c as TOOL_DEFINITION, e as TOOL_NAME, l as calculatedRange, s as executeSpreadsheet, r as executeSpreadsheetDispatch, i as isSpreadsheetArtifactPath, a as isSpreadsheetDispatchArgs, n as pluginCore, u as readCalculatedRange, o as samples };
+import { E as e, T as t, _ as n, g as r, o as i, s as a, t as o, w as s, y as c } from "./samples-DBNVoegC.js";
+import { n as l, r as u, t as d } from "./core-CwIoDrlM.js";
+export { d as MAX_RANGE_CELLS, s as SYSTEM_PROMPT, t as TOOL_DEFINITION, e as TOOL_NAME, l as calculatedRange, i as executeSpreadsheet, r as executeSpreadsheetDispatch, c as isSpreadsheetArtifactPath, n as isSpreadsheetDispatchArgs, a as pluginCore, u as readCalculatedRange, o as samples };

package/dist/engine/calculator.d.ts

@@ -4,24 +4,10 @@
  * Core calculation engine with circular reference detection and cross-sheet support
  */
 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
- *
- * @param sheet - Sheet data to calculate
- * @param allSheets - All sheets for cross-sheet references
- * @returns Calculated sheet with formulas evaluated
- */
 export declare function calculateSheet(sheet: SheetData, allSheets?: SheetData[], options?: SheetCalculateOptions): CalculatedSheet;
 /**
  * Calculate all sheets in a workbook

package/dist/engine/cellEmpty.d.ts

@@ -11,3 +11,6 @@
  *  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;
+/** True when a cell holds nothing and is not a formula error. A calculated error is an object
+ *  without `v`, which `isEmptyCell` alone counts as empty — and a blank reads as 0. */
+export declare function isBlankCell(cell: unknown): boolean;

package/dist/engine/cellFormatting.d.ts

@@ -16,10 +16,11 @@ export declare const isLikelyDateSerial: (value: CellValue) => boolean;
  *
  * - 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.
+ * - A formula whose number is a date by origin (`showsDate`, see dateDisplay.ts) and lands in
+ *   the date-serial window 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;
+export declare const formatCellForDisplay: (originalCell: unknown, calculatedValue: CellValue, preferDDMMYYYY: boolean, showsDate: boolean) => StoredCellValue;

package/dist/engine/concatOperand.d.ts

@@ -0,0 +1,3 @@
+/** Whether `expr.slice(start, end)` is a whole operand of a `&`: only brackets and spaces
+ *  between it and a `&` on one side, and a `&` or the end of the expression on the other. */
+export declare function standsAloneInConcat(expr: string, start: number, end: number): boolean;

package/dist/engine/concatPrecedence.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Excel `&` with Excel's precedence.
+ *
+ * `&` binds looser than `+ - * / ^`, so `"a"&1+2` is `"a"&(1+2)` = `a3`. Rewriting
+ * `&` to JS `+` in place made it bind as tightly as `+` and evaluate left to
+ * right: `"a"+1+2` is `a12`. Here each `&` operand is parenthesised before the
+ * join, so its arithmetic runs first, and the join starts from `""` so it is a
+ * string concatenation whatever the operands are (`5&6` is `56`, not 11).
+ */
+export interface Place {
+    char: string;
+    inLiteral: boolean;
+    /** Paren nesting outside literals; a `(` or `)` counts at its outer level. */
+    depth: number;
+}
+/** Each character with whether it sits in a string literal and how deeply it is nested. */
+export declare function placesOf(expr: string): Place[];
+/**
+ * Excel `&` → a JS expression that concatenates with Excel's precedence.
+ *
+ * Returns the plain in-place rewrite when the expression compares (`=`, `<`, `>`
+ * outside a literal) or an operand is empty (a leading or trailing `&`). The
+ * evaluator's concatenation gate rejects that rewrite, so those formulas come out
+ * exactly as they did before: comparing a joined string needs text comparison,
+ * which the evaluator does not have, and treating `&` as `+` there would answer
+ * `=A1&B1=3` TRUE where Excel compares "12" with 3.
+ */
+export declare function concatToSum(expr: string): string;
+/** Every operand of every `&` in `expr`, nested groups included, so the evaluator
+ *  can check each one the way it checks an expression without `&`: joined as text,
+ *  `1/0` would read "Infinity" where Excel answers #DIV/0!. */
+export declare function concatOperands(expr: string): string[];

package/dist/engine/customFunctionSpecs.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A workbook's own functions as it stores them (#114), and the rules a definition must meet before
+ * any of it runs. Pure: no QuickJS here, so every rule is testable on its own.
+ */
+/** One function a workbook defines: `=MOVING.AVG(B2:B100, 7)` calls `body` with `values` and `n`. */
+export interface CustomFunctionSpec {
+    name: string;
+    params: string[];
+    body: string;
+    description?: string;
+}
+/** A definition that cannot be used, and why — said to whoever wrote it. */
+export interface CustomFunctionProblem {
+    name: string;
+    reason: string;
+}
+/** The specs a sheet's `functions` holds, skipping anything not shaped like one. */
+export declare function specsOf(functions: unknown): CustomFunctionSpec[];
+/** Why `spec` cannot be used, or null when it can. `isBuiltIn` says whether a name is the engine's own. */
+export declare function problemWith(spec: CustomFunctionSpec, isBuiltIn: (name: string) => boolean): string | null;
+/** The usable definitions, keyed by upper-case name, and the problems with the rest. A name defined
+ *  twice is a problem for the second: which one a formula means would otherwise depend on order. */
+export declare function checkedSpecs(specs: CustomFunctionSpec[], isBuiltIn: (name: string) => boolean): {
+    usable: Map<string, CustomFunctionSpec>;
+    problems: CustomFunctionProblem[];
+};
+/** The source QuickJS evaluates to get `spec` as a function. A body can still close the function
+ *  early (QuickJS's `Function` joins its source as text); what contains that is the sandbox, and a
+ *  context of its own per function, not this string. */
+export declare const functionSource: (spec: CustomFunctionSpec) => string;

package/dist/engine/customFunctions.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A workbook's own functions, run in QuickJS (#114).
+ *
+ * QuickJS is a JavaScript engine compiled to WebAssembly: a function runs inside it with no DOM,
+ * no network, no file system and no timers, under a memory cap and a deadline, and a call is
+ * synchronous — so the engine's synchronous handlers can call it directly. Only loading the
+ * WebAssembly is asynchronous, which is why a caller loads a workbook's functions before
+ * calculating it, and a workbook without functions never loads QuickJS at all.
+ */
+import { type FunctionDefinition } from "./registry";
+import "./functions";
+import { type CustomFunctionProblem } from "./customFunctionSpecs";
+import type { CellValue } from "./types";
+/** A workbook's functions, ready to be made visible to a calculation with {@link calculateWith}. */
+export interface CustomFunctionSet {
+    definitions: ReadonlyMap<string, FunctionDefinition>;
+    /** The definitions that could not be used, and why. */
+    problems: CustomFunctionProblem[];
+    /** Marks the start of one calculation, for {@link CALCULATION_LIMIT_MS}. */
+    startCalculation(): void;
+    dispose(): void;
+}
+/** The set for a workbook that defines no functions. */
+export declare const NO_CUSTOM_FUNCTIONS: CustomFunctionSet;
+/** Calculate with `set`'s functions visible: `calculateWith(set, () => engine.calculate(sheet, sheets))`. */
+export declare function calculateWith<T>(set: CustomFunctionSet, calculate: () => T): T;
+/** The functions defined across `sheets` (each sheet's optional `functions`). */
+export declare function loadCustomFunctions(sheets: readonly {
+    functions?: unknown;
+}[]): Promise<CustomFunctionSet>;
+/** What a function returned, as a cell holds it: a finite number, text or a logical; else an error. */
+export declare function asCellValue(value: unknown): CellValue;

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

@@ -0,0 +1,32 @@
+/**
+ * Calendar rules for WEEKDAY, DAYS, EDATE, EOMONTH, WORKDAY and NETWORKDAYS, on
+ * Excel serial numbers. Pure, so each rule is tested without a sheet. A serial's
+ * time of day is dropped first, as Excel does.
+ *
+ * Serials follow the engine's own conversion (date-utils.ts: day 0 is 1899-12-30),
+ * which agrees with Excel from 1900-03-01 on. Excel's fictitious 1900-02-29 is
+ * not reproduced here, as it is not by YEAR, MONTH or DAY.
+ */
+import { type SpreadsheetError } from "./spreadsheet-errors";
+/** 9999-12-31, Excel's last date. A result or a span beyond it is #NUM!, which also
+ *  keeps WORKDAY's walk and NETWORKDAYS' count bounded. */
+export declare const LAST_SERIAL = 2958465;
+/** WEEKDAY: 1–7 counted from the day the return type starts on (type 1, the
+ *  default, starts on Sunday); type 3 counts Monday as 0. Any other type, or a
+ *  serial outside Excel's dates, is `#NUM!`. */
+export declare function weekdayOf(serial: number, returnType?: number): number | SpreadsheetError;
+/** DAYS: whole days from `start` to `end`. */
+export declare function daysBetween(end: number, start: number): number | SpreadsheetError;
+/** EDATE: the same day `months` months on, moved back to the month's last day
+ *  when the month is shorter (31 January + 1 month is 28 or 29 February). */
+export declare function addMonths(serial: number, months: number): number | SpreadsheetError;
+/** EOMONTH: the last day of the month `months` months on. */
+export declare function endOfMonth(serial: number, months: number): number | SpreadsheetError;
+/** WORKDAY: the date `days` working days on (back, when negative), skipping
+ *  weekends and `holidays`. Zero days is the start date itself. A walk that leaves
+ *  Excel's dates is `#NUM!`, which bounds it. */
+export declare function addWorkdays(serial: number, days: number, holidays?: readonly number[]): number | SpreadsheetError;
+/** NETWORKDAYS: the working days from `start` to `end`, both included, negative
+ *  when `end` comes first. Times of day are dropped before the order is decided;
+ *  a holiday counts once, and only when it falls on a weekday in the span. */
+export declare function countWorkdays(start: number, end: number, holidays?: readonly number[]): number | SpreadsheetError;

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

@@ -3,7 +3,10 @@
  *
  * Shared utilities for converting between JavaScript Date objects and Excel serial numbers.
  * Excel stores dates as sequential serial numbers so they can be used in calculations.
- * January 1, 1900 is serial number 1.
+ *
+ * Serial 0 is 1899-12-30 and the calendar is the real one, as in LibreOffice and Google
+ * Sheets: Excel's serial 60 is a 1900-02-29 that never existed, so its serials 1–59 sit
+ * one day later than these. From 1900-03-01 (serial 61) on, the two agree.
  */
 /**
  * Convert JavaScript Date to Excel Serial Number

package/dist/engine/dateDisplay.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Whether a formula's number is a date to show as one, when its cell has no format of its own.
+ * Excel decides from where the number came from, not from its size: a formula that starts with
+ * a date function, or whose first reference is a date, shows a date; a sum that happens to land
+ * on 52345 does not. Taking the size alone turned ordinary totals into 2043 dates.
+ */
+/** What the date decision reads of a referenced cell: its own format, its formula if it has one,
+ *  and the sheet that formula's references are read on. */
+export interface DateCell {
+    format: string;
+    formula: string | null;
+    sheet: string;
+}
+/** Looks up a reference (`A1`, `Data!A1`, `'My Sheet'!A1`) written on `sheet`. */
+export type DateSource = (ref: string, sheet: string) => DateCell | null;
+/** The function a formula body starts with — `DATE` in `DATE(…)+1` or `(DATE(…))` — or null. */
+export declare function leadingCall(body: string): string | null;
+/** Whether the formula (with its leading `=`), written on `sheet`, shows a date: it starts with a
+ *  date function, or its first reference is a date — by its format, or by its own formula. */
+export declare function formulaShowsDate(formula: string, sheet: string, source: DateSource, seen?: ReadonlySet<string>): boolean;

package/dist/engine/escapes.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether the character at `index` is backslash-escaped: preceded by an ODD run of
+ * backslashes. Checking only the one character before it is wrong for a literal
+ * ending in a backslash, `"a\\"`, where the closing quote follows an escaped
+ * backslash and does close the literal.
+ *
+ * Counts backwards over the run only. Scanners ask it about quote characters
+ * alone, so a long text of backslashes is walked once per following quote.
+ */
+export declare function isEscapedAt(text: string, index: number): boolean;

package/dist/engine/evaluator.d.ts

@@ -11,9 +11,14 @@ export interface EvaluatorContext {
     getCellValue: (ref: string) => CellValue;
     getRangeValues: (range: string) => CellValue[];
     getRangeValuesRaw?: ((range: string) => CellValue[]) | undefined;
+    getRangeValuesKeepingBlanks?: ((range: string) => CellValue[]) | undefined;
+    countFilledCells?: ((range: string) => number) | undefined;
     evaluateFormula: (formula: string) => CellValue;
     /** Reading order for an ambiguous slash date; see engine/date-locale.ts. */
     preferDDMMYYYY?: boolean | undefined;
+    /** Whether the referenced cell holds nothing. `getCellValue` reads such a cell as 0, which
+     *  is right for arithmetic and wrong for `&`, where a blank cell joins as "". */
+    isCellEmpty?: ((ref: string) => 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
@@ -51,7 +56,7 @@ export declare function findCellRefs(expr: string): CellRefSpan[];
  *  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;
+export declare function substituteCellRefs(expr: string, cellRefs: CellRefSpan[], render: (ref: string, start: number) => string): string;
 /**
  * Parse function arguments, handling nested functions and quoted strings
  *

package/dist/engine/formatter.d.ts

@@ -3,6 +3,10 @@
  *
  * Handles Excel-style format codes for currency, percentages, decimals, dates, etc.
  */
+/**
+ * Check if a format code is for dates
+ */
+export declare function isDateFormat(format: string): boolean;
 /**
  * Insert thousands separators into a run of digits ("1234567" → "1,234,567").
  * Regex free on purpose: the classic `\B(?=(\d{3})+(?!\d))` lookahead

package/dist/engine/functions/aliases.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The names current Excel writes for functions this engine already has. A model
+ * writing `PERCENTILE.INC` means exactly `PERCENTILE`, so each alias is the same
+ * definition under a second name.
+ */
+export {};

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

@@ -10,6 +10,8 @@ export interface NumericPairs {
     ys: number[];
     xs: number[];
 }
+export declare const mean: (values: number[]) => number;
+export declare const sumOfSquaredDeviations: (values: number[]) => number;
 /**
  * Pair two ranges by position, keeping only the pairs where both cells hold a
  * number. Excel skips a pair with a blank or text on either side, rather than
@@ -17,6 +19,7 @@ export interface NumericPairs {
  * different sizes have no pairing, so Excel answers `#N/A`.
  */
 export declare function numericPairs(yValues: CellValue[], xValues: CellValue[]): NumericPairs | SpreadsheetError;
+export declare const sumOfCrossDeviations: ({ ys, xs }: NumericPairs) => number;
 /** Pearson correlation (CORREL). Fewer than two pairs, or a side that never
  *  varies, leaves a zero denominator: `#DIV/0!`. */
 export declare function correlation(pairs: NumericPairs): number | SpreadsheetError;

package/dist/engine/functions/calendar.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Calendar functions: WEEKDAY, DAYS, EDATE, EOMONTH, WORKDAY, NETWORKDAYS. The
+ * rules live in date-calendar.ts; this file reads the arguments.
+ *
+ * Arguments are read strictly, as Excel does: a date given as text has already
+ * become a serial when the argument is evaluated, so text that is still text is
+ * #VALUE!, and an error in an argument is the function's answer.
+ */
+export {};

package/dist/engine/functions/date.d.ts

@@ -1,6 +1,6 @@
 /**
  * Date and Time Functions
  * Excel stores dates as sequential serial numbers so they can be used in calculations.
- * January 1, 1900 is serial number 1.
+ * Serial 0 is 1899-12-30 on the real calendar, so 1900-01-01 is serial 2 (see date-utils.ts).
  */
 export {};

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

@@ -0,0 +1,44 @@
+/**
+ * The t and normal distributions and the t-test, as pure numerics. Tails are computed
+ * directly rather than as 1 − (the rest), so a small p-value keeps its relative precision.
+ * The spreadsheet rules (argument checks, #NUM!) live in distributions.ts.
+ */
+export declare const normalDensity: (z: number) => number;
+/** P(Z > z) for the standard normal. erfc(x) is Q(1/2, x²), so the upper tail is half of it. */
+export declare function normalUpperTail(z: number): number;
+/** P(Z ≤ z) for the standard normal. */
+export declare const normalCdf: (z: number) => number;
+/** The z with P(Z ≤ z) = p, for 0 < p < 1. */
+export declare function normalQuantile(p: number): number;
+/** The z with P(Z > z) = q, for 0 < q < 1. */
+export declare const normalUpperQuantile: (q: number) => number;
+/** The t density with `df` degrees of freedom: 1 / (√ν B(ν/2, 1/2)) · (1 + t²/ν)^(−(ν+1)/2). */
+export declare function studentDensity(t: number, df: number): number;
+/** P(T > t). For t ≥ 0 it is ½ · I_x(ν/2, ½) with x = ν / (ν + t²) = r / (1 + r), r = ν / t².
+ *  It goes through ln r, so t² never overflows and 1 − x keeps its digits for a small t. */
+export declare function studentUpperTail(t: number, df: number): number;
+/** P(T ≤ t). */
+export declare const studentCdf: (t: number, df: number) => number;
+/** The t with P(T > t) = q, for 0 < q < 1. */
+export declare function studentUpperQuantile(q: number, df: number): number;
+/** The t with P(T ≤ t) = p, for 0 < p < 1. */
+export declare const studentQuantile: (p: number, df: number) => number;
+export interface SampleSummary {
+    count: number;
+    mean: number;
+    /** The sample variance, divided by n − 1. */
+    variance: number;
+}
+export declare function summarize(values: number[]): SampleSummary;
+export interface TStatistic {
+    t: number;
+    df: number;
+}
+/** Paired: the one-sample t of the differences. */
+export declare function pairedT(differences: number[]): TStatistic;
+/** Two samples with a pooled (equal) variance. */
+export declare function pooledT(first: SampleSummary, second: SampleSummary): TStatistic;
+/** Two samples with unequal variances (Welch). The Welch–Satterthwaite df is not rounded. */
+export declare function welchT(first: SampleSummary, second: SampleSummary): TStatistic;
+/** The p-value of a t statistic: one tail, or both. */
+export declare const tTestProbability: ({ t, df }: TStatistic, tails: 1 | 2) => number;