@gui-chat-plugin/spreadsheet 2.0.0 → 3.0.0

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

@@ -0,0 +1,41 @@
+/**
+ * Pure statistical rules, separated from the range-reading handlers so they can
+ * be unit-tested directly.
+ */
+import { type SpreadsheetError } from "../spreadsheet-errors";
+/**
+ * The arithmetic mean, or `#DIV/0!` when there is nothing to average.
+ *
+ * Excel divides by the count of NUMBERS, so a range of blanks or text leaves a
+ * zero denominator and reports the division rather than a 0 that reads like a
+ * genuine average of zeros.
+ */
+export declare function computeAverage(values: number[]): number | SpreadsheetError;
+/**
+ * The middle value (the mean of the middle two when the count is even), or
+ * `#NUM!` when there is no value to sit in the middle.
+ *
+ * Excel's code here is `#NUM!`, not AVERAGE's `#DIV/0!` — nothing is divided by
+ * zero, the median of an empty set simply does not exist. Sorts a copy so the
+ * caller's array keeps its order.
+ */
+export declare function computeMedian(values: number[]): number | SpreadsheetError;
+/**
+ * The most frequently occurring value, or `#N/A` when no value repeats.
+ *
+ * Excel's MODE is undefined for an all-distinct set, so returning the first
+ * element (as a naive "highest frequency wins" loop does when every count is 1)
+ * is a silent wrong answer. Ties resolve to the value that appears first, which
+ * Map insertion order preserves.
+ */
+export declare function computeMode(values: number[]): number | SpreadsheetError;
+/**
+ * Sample variance (Excel VAR): the mean squared deviation divided by `n - 1`,
+ * not `n`. Dividing by `n` is the POPULATION variance (Excel's VARP); using it
+ * for VAR understates the spread. Fewer than two values leave no `n - 1` to
+ * divide by, so Excel reports `#DIV/0!` rather than a silent 0.
+ */
+export declare function sampleVariance(values: number[]): number | SpreadsheetError;
+/** Sample standard deviation (Excel STDEV): the square root of the sample
+ *  variance, and `#DIV/0!` on the same fewer-than-two-values boundary. */
+export declare function sampleStdev(values: number[]): number | SpreadsheetError;

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

@@ -1,4 +1,20 @@
 /**
  * Text Functions
  */
-export {};
+import { type SpreadsheetError } from "../spreadsheet-errors";
+export declare const toProperCase: (text: string) => string;
+export declare const takeLeft: (text: string, count: number) => string | SpreadsheetError;
+export declare const takeRight: (text: string, count: number) => string | SpreadsheetError;
+export declare const substituteText: (text: string, oldText: string, newText: string, instance?: number) => string | SpreadsheetError;
+/** Excel MID: 1-based start, count of characters. `substring` SWAPS its bounds
+ *  when they are reversed, so a negative count read backwards from `start` and
+ *  returned earlier characters — `MID("Hello",3,-1)` gave "e" instead of an
+ *  error. Both arguments are validated here instead. */
+export declare const takeMid: (text: string, start: number, count: number) => string | SpreadsheetError;
+export declare const locateSubstring: (find: string, within: string, start: number, options: {
+    caseInsensitive: boolean;
+}) => number | SpreadsheetError;
+/** Excel VALUE: the WHOLE string must be a number once its currency symbols and
+ *  thousands separators are stripped; trailing text is an error, not a prefix to
+ *  salvage. */
+export declare const parseValueText: (raw: string) => number | SpreadsheetError;

package/dist/engine/guards.d.ts

@@ -0,0 +1,10 @@
+/** Narrow `unknown` to a plain object (not null, not array). */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Narrow `unknown` to any object (not null, arrays allowed).
+ *  Use `isRecord` when you need to access string keys. */
+export declare function isObj(value: unknown): value is object;
+/** The message to show for a thrown value. A non-Error object with a non-empty
+ *  string `details` (the gRPC convention) or `message` surfaces that field —
+ *  `details` wins — instead of the `[object Object]` a bare `String(err)`
+ *  would print. */
+export declare function errorMessage(err: unknown, fallback?: string): string;

package/dist/engine/index.d.ts

@@ -5,9 +5,20 @@
  */
 export * from "./types";
 export * from "./parser";
+export * from "./condition";
+export * from "./date-locale";
+export * from "./cellEmpty";
+export * from "./datedif";
 export * from "./formatter";
+export * from "./translateFormula";
+export * from "./formulaError";
+export * from "./spreadsheet-errors";
 export * from "./evaluator";
 export * from "./calculator";
+export * from "./formulaRefs";
+export * from "./cellBuilder";
+export * from "./responseDecoder";
+export * from "./jsonCellLocator";
 export * from "./registry";
 import "./functions";
 export { SpreadsheetEngine } from "./engine";

package/dist/engine/jsonCellLocator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Locate the start offset of a specific cell value inside a
+ * pretty-printed JSON spreadsheet document. Extracted from
+ * `handleTableClick` in `src/plugins/spreadsheet/View.vue` where the
+ * inline scanner pushed cognitive complexity to 163.
+ *
+ * The scanner walks the raw editor text character-by-character,
+ * tracking string boundaries, bracket depth, and object depth to
+ * find the n-th cell of the m-th row within a named sheet's `data`
+ * array. We deliberately do NOT parse the JSON — we need the
+ * character offset inside the user's text buffer (which may not be
+ * valid JSON mid-edit), so a positional scan is required.
+ *
+ * Pure — no refs, no DOM. Returns -1 if the cell can't be located.
+ * Tested in `test/plugins/spreadsheet/engine/test_jsonCellLocator.ts`.
+ */
+/**
+ * Given the pretty-printed JSON editor text, a sheet name, and
+ * (rowIndex, colIndex), return the character offset of that cell's
+ * JSON token. The returned offset can be fed into
+ * `textarea.setSelectionRange(offset, offset + cellJsonLength)` to
+ * highlight the cell.
+ *
+ * Returns -1 if the sheet isn't found or the (row, col) is out of
+ * range. Never throws.
+ */
+export declare function findCellJsonPosition(editorText: string, sheetName: string, rowIndex: number, colIndex: number): number;

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

@@ -0,0 +1,41 @@
+/**
+ * Rounding, modulo and significance math for the mathematical functions.
+ *
+ * Pure number-in / (number | formula-error-value)-out helpers. The rounding
+ * direction and the domain rules are exactly where the engine diverged from
+ * Excel (rounding toward +∞ instead of away from zero, modulo taking the
+ * dividend's sign, negative bases and domains slipping through as NaN/∞), so
+ * they are worth testing apart from the argument-reading handlers.
+ */
+import { type SpreadsheetError } from "./spreadsheet-errors";
+/** Excel ROUND: half away from zero (JS `Math.round` breaks half toward +∞, so
+ *  `ROUND(-2.5, 0)` came back -2 instead of -3). */
+export declare function roundTo(value: number, digits: number): number;
+/** Excel ROUNDUP: away from zero. */
+export declare function roundUpTo(value: number, digits: number): number;
+/** Excel ROUNDDOWN: toward zero. */
+export declare function roundDownTo(value: number, digits: number): number;
+/** Excel FLOOR: nearest multiple of `significance` toward zero; opposite signs
+ *  are #NUM!, and a zero significance is #DIV/0! — the division by the
+ *  significance is what FLOOR reports, so it wins over the sign check. */
+export declare function floorToSignificance(value: number, significance: number): number | SpreadsheetError;
+/** Excel CEILING: nearest multiple of `significance` away from zero; opposite
+ *  signs are #NUM!, and a zero significance is 0 — deliberately NOT FLOOR's
+ *  #DIV/0!, an asymmetry Excel keeps and this engine has to match. */
+export declare function ceilingToSignificance(value: number, significance: number): number | SpreadsheetError;
+/** Excel MOD: result takes the divisor's sign (`MOD(-3, 2) === 1`); dividing by
+ *  zero is #DIV/0!, not a silent 0. */
+export declare function modulo(value: number, divisor: number): number | SpreadsheetError;
+/** Excel POWER: a negative base with a non-integer exponent has no real root, so
+ *  it is #NUM! rather than JS's NaN. */
+export declare function power(base: number, exponent: number): number | SpreadsheetError;
+/** Natural log guarded to its domain: `LN(x)` for `x <= 0` is #NUM!, not
+ *  -∞ / NaN. Reused by LN and LOG. */
+export declare function safeLog(value: number): number | SpreadsheetError;
+/** Excel LOG(value, base): the base must also be positive and not 1, or the
+ *  result is #NUM! rather than the ∞ / NaN a bare division would give. */
+export declare function logWithBase(value: number, base: number): number | SpreadsheetError;
+/** Base-10 log guarded to its domain (`LOG10(x)` for `x <= 0` is #NUM!). */
+export declare function safeLog10(value: number): number | SpreadsheetError;
+/** Square root guarded to its domain (`SQRT(x)` for `x < 0` is #NUM!, not NaN). */
+export declare function safeSqrt(value: number): number | SpreadsheetError;

package/dist/engine/numericCoercion.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Numeric coercion helpers for the spreadsheet engine.
+ *
+ * Two intentionally different reads share one string parser (`parseNumericString`):
+ *  - `registry.toNumber` — lenient, for range aggregation (SUM / AVERAGE / …):
+ *    anything unreadable becomes 0. PINNED (booleans are 0, not Excel's 1/0).
+ *  - `toScalarNumber` — strict, for single-value math functions (ABS / SIGN):
+ *    booleans are 1/0 and non-numeric text is `#VALUE!`, matching Excel.
+ *
+ * `holdsNumber` asks the question neither read can answer once it has coerced:
+ * was there a number here at all, or is this 0 the reading of something else.
+ */
+import type { CellValue } from "./types";
+import { type SpreadsheetError } from "./spreadsheet-errors";
+/**
+ * Parse a spreadsheet string as a number, or `null` when it holds no number.
+ *
+ * Mirrors the engine's long-standing lenient read: a percentage, a currency
+ * amount, or a thousands-separated value, else a bare `parseFloat` (which reads a
+ * leading number out of "12abc"). The branch order is load-bearing — each strips
+ * only its own characters, so a string mixing "%" and "$" fails in the first.
+ */
+export declare function parseNumericString(value: string): number | null;
+/**
+ * Whether a value holds a number at all, under the same reading `toNumber` uses.
+ *
+ * `toNumber` answers 0 for text, for a boolean and for a genuine 0 alike, so a
+ * caller that must tell "no number here" from "the number zero" — COUNT — cannot
+ * ask it. Booleans are not numbers here, matching `toNumber`'s PINNED behaviour.
+ */
+export declare function holdsNumber(value: CellValue): boolean;
+/**
+ * Strict scalar coercion for single-value math functions (ABS, SIGN). Follows
+ * Excel's scalar rules: a boolean is 1 / 0 and genuinely non-numeric text is
+ * `#VALUE!` rather than a silent 0. A partly-numeric string still yields its
+ * leading number, matching the engine's other numeric reads.
+ */
+export declare function toScalarNumber(value: CellValue): number | SpreadsheetError;

package/dist/engine/parser.d.ts

@@ -3,7 +3,6 @@
  *
  * Handles Excel A1 notation parsing and conversion
  */
-import type { CellRef, RangeRef } from "./types";
 /**
  * Convert Excel column letters to 0-based index
  * A=0, B=1, ..., Z=25, AA=26, etc.
@@ -20,26 +19,3 @@ export declare function columnToIndex(col: string): number;
  * @returns Column letters (e.g., "A", "Z", "AA")
  */
 export declare function indexToColumn(index: number): string;
-/**
- * Parse a cell reference to its components
- * Supports: A1, $A$1, $A1, A$1, Sheet1!A1, 'My Sheet'!A1
- *
- * @param ref - Cell reference string
- * @returns Parsed cell reference object
- */
-export declare function parseCellRef(ref: string): CellRef;
-/**
- * Parse a range reference to its components
- * Supports: A1:B10, $A$1:$B$10, Sheet1!A1:B10
- *
- * @param range - Range reference string
- * @returns Parsed range reference object
- */
-export declare function parseRangeRef(range: string): RangeRef;
-/**
- * Convert a cell reference object back to A1 notation
- *
- * @param ref - Cell reference object
- * @returns A1 notation string
- */
-export declare function cellRefToA1(ref: CellRef): string;

package/dist/engine/registry.d.ts

@@ -10,11 +10,37 @@ export type CellGetter = (ref: string) => CellValue;
 export type RangeGetter = (range: string) => CellValue[];
 export type RawRangeGetter = (range: string) => CellValue[];
 export interface FunctionContext {
+    /** The registry name the formula invoked, so a handler can report a failure
+     *  the way the evaluator names it. */
+    functionName: string;
     getCellValue: CellGetter;
     getRangeValues: RangeGetter;
-    getRangeValuesRaw?: RawRangeGetter;
+    getRangeValuesRaw?: RawRangeGetter | undefined;
     evaluateFormula: (formula: string) => CellValue;
 }
+/** The too-few-arguments error, raised by the evaluator from the registry's
+ *  `minArgs` before any handler runs — and by `requiredArg` for the argument a
+ *  handler actually reads, so both report one wording. */
+export declare const tooFewArgumentsError: (funcName: string, minArgs: number) => Error;
+/** The argument at `index`, which the caller has already established is there —
+ *  the registry's `minArgs` for a mandatory argument, an `args.length` branch for
+ *  an optional one. An absent one means that guarantee is wrong, so it raises the
+ *  arity error the guarantee should have raised. Never a default value: a
+ *  substituted 0 or "" computes a plausible wrong answer, which is worse than
+ *  the error the formula deserves. */
+export declare const requiredArg: (context: FunctionContext, args: string[], index: number) => string;
+/** The range reader that keeps every cell, for functions whose answer depends on
+ *  a range's POSITIONS rather than its numbers.
+ *
+ *  `getRangeValues` drops non-numeric cells, which silently renumbers the rows
+ *  underneath: a criteria/value pair read that way falls out of alignment and
+ *  aggregates a different row, and an index returned from it points at the wrong
+ *  one. SUMIF/AVERAGEIF were moved here in #2358; MATCH/XLOOKUP in #2765.
+ *
+ *  Falls back to the numeric reader because `getRangeValuesRaw` is optional on
+ *  `FunctionContext` — a host that predates it keeps its old behaviour rather
+ *  than throwing. */
+export declare const rawRangeReader: (context: FunctionContext) => RangeGetter;
 export type FunctionHandler = (args: string[], context: FunctionContext) => CellValue;
 export interface FunctionDefinition {
     name: string;
@@ -35,7 +61,9 @@ declare class FunctionRegistry {
 }
 export declare const functionRegistry: FunctionRegistry;
 /**
- * Helper function to convert a value to a number
+ * Lenient numeric coercion for range aggregation: anything unreadable is 0.
+ * PINNED behaviour (booleans are 0, not Excel's 1/0) — the string parsing lives
+ * in numericCoercion.parseNumericString, shared with the strict scalar read.
  */
 export declare function toNumber(value: CellValue): number;
 /**

package/dist/engine/responseDecoder.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Decode the `/api/files/content` response for a spreadsheet file
+ * into an "ok with sheets" / "error with message" discriminated
+ * union. Extracted from `fetchSheets` in
+ * `src/plugins/spreadsheet/View.vue` where the decision tree was
+ * inlined as several nested try/catch + if branches.
+ *
+ * Pure — no fetch, no refs. Takes the parsed JSON body and returns
+ * a result the caller can pattern-match on. Tested in
+ * `test/plugins/spreadsheet/engine/test_responseDecoder.ts`.
+ */
+import type { SheetData } from "./types.js";
+/** Shape of the `/api/files/content` response we care about. The
+ *  server returns more fields (kind, size, modifiedMs, …) but this
+ *  decoder only depends on the three that drive branching. */
+export interface FilesContentResponseLike {
+    kind?: string;
+    content?: string;
+    message?: string;
+}
+export type DecodeResult = {
+    kind: "ok";
+    sheets: SheetData[];
+} | {
+    kind: "error";
+    message: string;
+};
+/**
+ * Turn a parsed `/files/content` body into an OK/error decision:
+ *
+ * - `kind` present and not "text" → error with the server's message
+ *   (e.g. "too-large", "binary"). Spreadsheets only live in text
+ *   JSON files.
+ * - Missing or non-string `content` → error.
+ * - `content` is not valid JSON → error.
+ * - Parsed `content` is not an array → error (server should never
+ *   return a non-array but the guard protects downstream render).
+ * - Otherwise → ok with the sheets array.
+ */
+export declare function decodeSpreadsheetResponse(body: FilesContentResponseLike): DecodeResult;

package/dist/engine/spreadsheet-errors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Formula errors as a distinct VALUE type.
+ *
+ * A `#NUM!` produced by `SQRT(-1)` and the text `"#NUM!"` produced by
+ * `CONCAT("#N","UM!")` used to be the same string, so IFERROR could not tell a
+ * real error from text that merely spells one (#2451). An error is now its own
+ * value carrying the code, which is what the error-aware functions check; the
+ * display pass renders it back to `#NUM!` so cells look unchanged.
+ */
+export declare const SPREADSHEET_ERRORS: readonly ["#NULL!", "#DIV/0!", "#VALUE!", "#REF!", "#NAME?", "#NUM!", "#N/A", "#ERROR!"];
+export type SpreadsheetErrorCode = (typeof SPREADSHEET_ERRORS)[number];
+/** A formula error, distinct from any string. `toString` yields the code so the
+ *  value renders as `#NUM!` wherever the engine coerces a cell value to text. */
+export declare class SpreadsheetError {
+    readonly code: SpreadsheetErrorCode;
+    constructor(code: SpreadsheetErrorCode);
+    toString(): string;
+    toJSON(): string;
+}
+export declare const NULL_ERROR: SpreadsheetError;
+export declare const DIV_ZERO_ERROR: SpreadsheetError;
+export declare const VALUE_ERROR: SpreadsheetError;
+export declare const REF_ERROR: SpreadsheetError;
+export declare const NAME_ERROR: SpreadsheetError;
+export declare const NUM_ERROR: SpreadsheetError;
+export declare const NA_ERROR: SpreadsheetError;
+export declare const UNKNOWN_ERROR: SpreadsheetError;
+/** The error value for a code. */
+export declare const spreadsheetError: (code: SpreadsheetErrorCode) => SpreadsheetError;
+/** Whether a value is one of the error CODES as a plain string. Text that spells
+ *  an error is not an error value — see `isSpreadsheetErrorValue`. */
+export declare function isSpreadsheetError(value: unknown): value is SpreadsheetErrorCode;
+/** Whether a value IS a formula error, as opposed to text that spells one. */
+export declare function isSpreadsheetErrorValue(value: unknown): value is SpreadsheetError;
+/** The code behind a value: an error value's own code, or the code a plain
+ *  string spells. Used where a literal `#REF!` written into a cell must still
+ *  poison the arithmetic that reads it, provenance aside. */
+export declare function errorCodeOf(value: unknown): SpreadsheetErrorCode | null;
+/** Whether an evaluated result should be treated as an error: a formula error
+ *  VALUE, a NaN / infinite number, or a missing value. This is what IFERROR
+ *  catches — deliberately NOT a look-alike string, which is ordinary text. */
+export declare function isErrorResult(value: unknown): boolean;

package/dist/engine/textFormat.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Excel number-format patterns for the TEXT function.
+ *
+ * Deliberately separate from `formatter.formatNumber`, which renders CELL
+ * display values: the two disagree on defaults — Excel's `TEXT(0.5,"0%")` is
+ * `"50%"`, while a cell carrying the format `0%` has always displayed
+ * `"50.00%"` — so sharing the whole path would move every formatted cell in
+ * every stored workbook. Only the digit-grouping primitive is shared.
+ */
+export interface NumberPattern {
+    prefix: string;
+    suffix: string;
+    useGrouping: boolean;
+    integerMinDigits: number;
+    minDecimals: number;
+    maxDecimals: number;
+    isPercent: boolean;
+}
+/**
+ * Split a format code into a leading literal, one numeric core and a trailing
+ * literal, or `null` when the code uses a feature this module does not render.
+ */
+export declare const parseNumberPattern: (pattern: string) => NumberPattern | null;
+/**
+ * Render a number the way Excel's TEXT does for the common numeric format
+ * codes: `#,##0` grouping, `0.00` fixed decimals, `0.##` optional decimals, a
+ * literal prefix/suffix such as `$`, and a `%` that scales by 100.
+ *
+ * Returns `null` for a format code it does not render, so the caller can keep
+ * its own fallback rather than inventing a plausible wrong string.
+ */
+export declare const formatWithPattern: (value: number, pattern: string) => string | null;

package/dist/engine/translateFormula.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Excel-formula → JS-expression translation
+ *
+ * Pure string transforms that turn the Excel-operator form of an
+ * already-substituted expression (cell references resolved, functions replaced)
+ * into the JavaScript form handed to `new Function`, plus the character
+ * allowlists that gate that evaluation. No engine or evaluator state is
+ * captured — every function here is input → output only.
+ */
+/** Excel `^` exponentiation → JS `**`.
+ *
+ * Excel's `^` is left-associative (`2^3^2` = `(2^3)^2` = 64); JS `**` is
+ * right-associative (`2**3**2` = `2**(3**2)` = 512). This transform does not
+ * bridge that difference, so a chained `^` still evaluates the JS way — a known
+ * limitation tracked separately (#2359), pinned by the tests. */
+export declare function caretToPow(expr: string): string;
+/** Excel `&` string concatenation → JS `+`, leaving any `&` inside a quoted
+ *  string literal untouched. A quote toggles the "inside a literal" state only
+ *  when it is not backslash-escaped. */
+export declare function replaceConcatOperator(expr: string): string;
+/** Excel `=` equality → JS `==`, without disturbing `<=`, `>=` or `!=`. A single
+ *  `=` is rewritten only when flanked by a non-`<>!` char on the left and a
+ *  non-`=` on the right.
+ *
+ * Known limitations, pinned by the tests and tracked separately (#2359): the
+ * match consumes both flanking characters so replacements do not overlap
+ * (`5=6=7` → `5==6=7`, only the first rewritten); a `=` at either end of the
+ * expression has no left/right neighbour and is left alone (`5=` → `5=`); and a
+ * hand-typed `==` becomes `===` (its second `=` matches). Excel never emits the
+ * last two, so they only bite malformed input. */
+export declare function rewriteComparisonEq(expr: string): string;
+/** Whether an expression contains only the characters an arithmetic evaluation
+ *  may see: digits, ` + - * / ( ) . ` and spaces. Gates `new Function`. */
+export declare function isSafeArithmetic(expr: string): boolean;
+/** Whether an expression contains only the characters a comparison evaluation
+ *  may see: the arithmetic set plus ` < > ! = `. Gates `new Function`. */
+export declare function isSafeComparison(expr: string): boolean;

package/dist/engine/types.d.ts

@@ -1,9 +1,14 @@
 /**
  * Spreadsheet Engine Type Definitions
  */
-export type CellValue = number | string | boolean;
+import type { SpreadsheetError } from "./spreadsheet-errors";
+/** A value as it is STORED in a cell and serialized to the workbook JSON. A
+ *  formula error is never stored — it only exists as a computed result. */
+export type StoredCellValue = number | string | boolean;
+/** A value as the engine COMPUTES it: a stored value, or a formula error. */
+export type CellValue = StoredCellValue | SpreadsheetError;
 export interface SpreadsheetCell {
-    v: CellValue;
+    v: StoredCellValue;
     f?: string;
 }
 export interface SheetData {
@@ -46,7 +51,16 @@ export interface CalculationError {
     error: string;
     type: "circular" | "invalid_ref" | "div_zero" | "syntax" | "unknown";
 }
-export interface EngineOptions {
+/** Per-calculation settings that change how cell CONTENT is read, as opposed
+ *  to how the engine runs. Passed down explicitly so the engine stays pure —
+ *  no ambient locale, no import-time state. */
+export interface CalculateOptions {
+    /** Read an ambiguous `A/B/YYYY` date as day-first. Only affects dates whose
+     *  two leading numbers are both 12 or under; anything else decides itself.
+     *  See engine/date-locale.ts for how a locale maps onto this. */
+    preferDDMMYYYY?: boolean;
+}
+export interface EngineOptions extends CalculateOptions {
     maxIterations?: number;
     enableCrossSheetRefs?: boolean;
     strictMode?: boolean;

package/dist/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./samples-ClV76j10.cjs");require("./core.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");require("./core.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/index.js

@@ -1,3 +1,3 @@
-import { a as e, i as t, n, o as r, r as i, t as a } from "./samples-sKAnErVb.js";
+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";
 import "./core.js";
-export { t as SYSTEM_PROMPT, e as TOOL_DEFINITION, r as TOOL_NAME, n as executeSpreadsheet, i as pluginCore, a as samples };
+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/lang/de.d.ts

@@ -0,0 +1,3 @@
+import type { Messages } from "./messages";
+declare const de: Messages;
+export default de;

package/dist/lang/en.d.ts

@@ -0,0 +1,3 @@
+import type { Messages } from "./messages";
+declare const en: Messages;
+export default en;

package/dist/lang/es.d.ts

@@ -0,0 +1,3 @@
+import type { Messages } from "./messages";
+declare const es: Messages;
+export default es;

package/dist/lang/fr.d.ts

@@ -0,0 +1,3 @@
+import type { Messages } from "./messages";
+declare const fr: Messages;
+export default fr;

package/dist/lang/index.d.ts

@@ -0,0 +1 @@
+export declare const useT: () => import("vue").ComputedRef<import("./messages").Messages>;

package/dist/lang/ja.d.ts

@@ -0,0 +1,3 @@
+import type { Messages } from "./messages";
+declare const ja: Messages;
+export default ja;

package/dist/lang/ko.d.ts

@@ -0,0 +1,3 @@
+import type { Messages } from "./messages";
+declare const ko: Messages;
+export default ko;

package/dist/lang/messages.d.ts

@@ -0,0 +1,20 @@
+export interface Messages {
+    untitled: string;
+    sheetCount(count: number): string;
+    excel: string;
+    valuePlaceholder: string;
+    valueOrFormulaPlaceholder: string;
+    formatPlaceholder: string;
+    loading: string;
+    noData: string;
+    editData: string;
+    applyChanges: string;
+    dataMustBeArray: string;
+    loadFailed(error: string): string;
+    saveFailed(error: string): string;
+    invalidJsonAlert(error: string): string;
+    unknownError: string;
+    update: string;
+    stringType: string;
+    formulaType: string;
+}

package/dist/lang/ptBR.d.ts

@@ -0,0 +1,3 @@
+import type { Messages } from "./messages";
+declare const ptBR: Messages;
+export default ptBR;

package/dist/lang/zh.d.ts

@@ -0,0 +1,3 @@
+import type { Messages } from "./messages";
+declare const zh: Messages;
+export default zh;

package/dist/samples-BzI0GdUj.cjs

@@ -0,0 +1 @@
+let e=require("gui-chat-protocol");var t=`presentSpreadsheet`,n={type:`function`,name:t,description:`Display an Excel-like spreadsheet with formulas and calculations.`,parameters:{type:`object`,properties:{title:{type:`string`,description:`Title for the spreadsheet`},sheets:{type:`array`,description:`Sheets to render as spreadsheet tabs. Each sheet includes a name and 2D array of cells (rows x columns).`,items:{type:`object`,properties:{name:{type:`string`,description:`Sheet name (e.g., 'Sales Q1', 'Summary')`},data:{type:`array`,description:`Rows of cells. Each cell is an object with 'v' (value) and 'f' (format). Use Excel-style A1 notation in formulas: columns are letters (A, B, C...), rows are 1-based numbers (1, 2, 3...). Values can be text, numbers, dates, or formulas. Examples: [{"v": "Product"}, {"v": 2024, "f": "#,##0"}, {"v": "01/15/2025", "f": "MM/DD/YYYY"}, {"v": "=B2*1.05", "f": "$#,##0.00"}]. Format codes: '$#,##0.00' (currency), '#,##0' (integer), '0.00%' (percent), '0.00' (decimal), 'MM/DD/YYYY' (date), 'DD-MMM-YYYY' (date), 'YYYY-MM-DD' (ISO date).`,items:{type:`array`,description:`Row of cells. Each cell is an object with value and format.`,items:{type:`object`,description:`Cell object with value and optional format. If value is a string starting with '=', it's treated as a formula.`,properties:{v:{oneOf:[{type:`string`},{type:`number`},{type:`boolean`}],description:`Cell value. Can be text, number, date, or formula (string starting with '='). Examples: 'Revenue', 1500000, '01/15/2025', '=SUM(A1:A10)', '=B2-TODAY()'. Date strings like '01/15/2025' are automatically parsed to date serial numbers.`},f:{type:`string`,description:`Optional format code for displaying the value. Common 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)`}},required:[`v`]}}}},required:[`name`,`data`]}}},required:[`title`,`sheets`]}},r=`Use ${t} whenever the user needs a spreadsheet-style table, multi-step math, or dynamic what-if analysis—do 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.`;function i(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function a(e){return typeof e==`object`&&!!e}var o=(e,t)=>i(e)&&typeof e[t]==`string`;function s(e,t){return e instanceof Error?e.message:o(e,`details`)&&e.details?e.details:o(e,`message`)&&e.message?e.message:t===void 0?String(e):t}var c=`spreadsheets`,l=`.json`,u=16,d=2,f=e=>`${e.getUTCFullYear()}/${String(e.getUTCMonth()+1).padStart(d,`0`)}`,p=()=>globalThis.crypto.randomUUID().split(`-`).join(``).slice(0,u);function m(t=new Date,n=p()){let r=`${c}/${f(t)}/${n}${l}`;return{relPath:r,filePath:`${e.ARTIFACTS_ROOT}/${r}`}}var h=new Set([``,`.`,`..`]);function g(t){return typeof t!=`string`||!t.startsWith(`${e.ARTIFACTS_ROOT}/${c}/`)||!t.endsWith(l)||t.includes(`\\`)?!1:!t.split(`/`).some(e=>h.has(e))}var _=t=>t.slice(e.ARTIFACTS_ROOT.length+1),v=e=>typeof e==`string`||typeof e==`number`||typeof e==`boolean`,y=e=>e===null||v(e)||i(e)&&(e.v===void 0||e.v===null||v(e.v))&&(e.f===void 0||typeof e.f==`string`),b=e=>Array.isArray(e)&&e.every(y),x=e=>i(e)&&typeof e.name==`string`&&Array.isArray(e.data)&&e.data.every(b);function S(e){return Array.isArray(e)&&e.every(x)?e:null}function C(e){return!i(e)||typeof e.path!=`string`?!1:e.kind===`loadSpreadsheet`||e.kind===`saveSpreadsheet`&&Array.isArray(e.sheets)&&e.sheets.every(x)}var w=e=>i(e)&&typeof e.read==`function`&&typeof e.write==`function`;function T(e){if(!i(e)||!i(e.files))return null;let t=e.files.artifacts;return w(t)?t:null}async function E(e,t){let n=await e.read(_(t)),r=S(JSON.parse(n));if(!r)throw Error(`${t} does not hold an array of sheets`);return{message:`Loaded spreadsheet ${t}`,data:{sheets:r}}}async function D(e,t){if(!g(t.path))throw Error(`path must be a .json file under artifacts/spreadsheets/`);return t.kind===`loadSpreadsheet`?E(e,t.path):(await e.write(_(t.path),JSON.stringify(t.sheets)),{message:`Saved spreadsheet ${t.path}`,data:{sheets:t.path}})}function O(e){if(typeof e!=`string`)return e;try{let t=JSON.parse(e);return console.warn(`Sheets was provided as a string and has been parsed to an array`),t}catch(e){throw Error(`Invalid sheets format: sheets must be an array, not a string. Parse error: ${e instanceof Error?e.message:String(e)}`)}}function k(e){if(!Array.isArray(e)||e.length===0)throw Error(`At least one sheet is required. Sheets must be an array of sheet objects.`);e.forEach(e=>{if(!e.name||!e.data||e.data.length===0)throw Error(`Invalid sheet: ${e.name||`unnamed`}. Each sheet must have a name and data array.`)})}var A=async(e,t)=>{let{title:n}=t,r=O(t.sheets);k(r);let i=`Acknowledge that the spreadsheet has been created and is displayed to the user.`,a=T(e);if(!a)return{message:`Created spreadsheet: ${n}`,title:n,data:{sheets:r},instructions:i};let{relPath:o,filePath:s}=m();return await a.write(o,JSON.stringify(r)),{message:`Created spreadsheet: ${n}. Saved to ${s}; the user can edit cells there, so read that file for the current values.`,title:n,data:{sheets:s},instructions:i}};async function j(e,t){if(!(`kind`in t))return A(e,t);let n=T(e);if(!n)throw Error(`This host does not provide files.artifacts, so spreadsheets cannot be loaded or saved`);if(!C(t))throw Error(`Invalid spreadsheet dispatch`);return D(n,t)}var M={toolDefinition:n,execute:j,generatingMessage:`Creating spreadsheet...`,waitingMessage:`Tell the user that the spreadsheet was created and will be presented shortly.`,isEnabled:()=>!0,systemPrompt:r},N=[{name:`Simple Budget`,args:{title:`Monthly Budget`,sheets:[{name:`Budget`,data:[[{v:`Category`},{v:`Amount`}],[{v:`Income`},{v:5e3,f:`$#,##0.00`}],[{v:`Rent`},{v:-1500,f:`$#,##0.00`}],[{v:`Utilities`},{v:-200,f:`$#,##0.00`}],[{v:`Food`},{v:-600,f:`$#,##0.00`}],[{v:`Transport`},{v:-300,f:`$#,##0.00`}],[{v:`Total`},{v:`=SUM(B2:B6)`,f:`$#,##0.00`}]]}]}},{name:`Sales Report`,args:{title:`Q1 Sales Report`,sheets:[{name:`Sales`,data:[[{v:`Product`},{v:`Jan`},{v:`Feb`},{v:`Mar`},{v:`Total`}],[{v:`Widget A`},{v:1200},{v:1350},{v:1500},{v:`=SUM(B2:D2)`}],[{v:`Widget B`},{v:800},{v:920},{v:1100},{v:`=SUM(B3:D3)`}],[{v:`Widget C`},{v:450},{v:480},{v:520},{v:`=SUM(B4:D4)`}],[{v:`Total`},{v:`=SUM(B2:B4)`},{v:`=SUM(C2:C4)`},{v:`=SUM(D2:D4)`},{v:`=SUM(E2:E4)`}]]}]}},{name:`Loan Calculator`,args:{title:`Loan Calculator`,sheets:[{name:`Calculator`,data:[[{v:`Loan Amount`},{v:25e4,f:`$#,##0`}],[{v:`Interest Rate`},{v:.065,f:`0.00%`}],[{v:`Term (Years)`},{v:30}],[{v:``},{v:``}],[{v:`Monthly Payment`},{v:`=PMT(B2/12, B3*12, -B1)`,f:`$#,##0.00`}],[{v:`Total Interest`},{v:`=B5*B3*12-B1`,f:`$#,##0.00`}]]}]}},{name:`World Population`,args:{title:`世界人口（上位10）`,sheets:[{name:`世界人口（上位10）`,data:[[{v:`順位`},{v:`国・地域`},{v:`人口（概数）`,f:`#,##0`},{v:`上位10合計に占める割合`},{v:`世界人口に占める割合`}],[{v:1,f:`#,##0`},{v:`インド`},{v:1428627e3,f:`#,##0`},{v:`=C2/$C$12`,f:`0.00%`},{v:`=C2/$C$13`,f:`0.00%`}],[{v:2,f:`#,##0`},{v:`中国`},{v:1425671e3,f:`#,##0`},{v:`=C3/$C$12`,f:`0.00%`},{v:`=C3/$C$13`,f:`0.00%`}],[{v:3,f:`#,##0`},{v:`アメリカ合衆国`},{v:334e6,f:`#,##0`},{v:`=C4/$C$12`,f:`0.00%`},{v:`=C4/$C$13`,f:`0.00%`}],[{v:4,f:`#,##0`},{v:`インドネシア`},{v:277e6,f:`#,##0`},{v:`=C5/$C$12`,f:`0.00%`},{v:`=C5/$C$13`,f:`0.00%`}],[{v:5,f:`#,##0`},{v:`パキスタン`},{v:24e7,f:`#,##0`},{v:`=C6/$C$12`,f:`0.00%`},{v:`=C6/$C$13`,f:`0.00%`}],[{v:6,f:`#,##0`},{v:`ナイジェリア`},{v:219e6,f:`#,##0`},{v:`=C7/$C$12`,f:`0.00%`},{v:`=C7/$C$13`,f:`0.00%`}],[{v:7,f:`#,##0`},{v:`ブラジル`},{v:216e6,f:`#,##0`},{v:`=C8/$C$12`,f:`0.00%`},{v:`=C8/$C$13`,f:`0.00%`}],[{v:8,f:`#,##0`},{v:`バングラデシュ`},{v:172e6,f:`#,##0`},{v:`=C9/$C$12`,f:`0.00%`},{v:`=C9/$C$13`,f:`0.00%`}],[{v:9,f:`#,##0`},{v:`ロシア`},{v:146e6,f:`#,##0`},{v:`=C10/$C$12`,f:`0.00%`},{v:`=C10/$C$13`,f:`0.00%`}],[{v:10,f:`#,##0`},{v:`メキシコ`},{v:13e7,f:`#,##0`},{v:`=C11/$C$12`,f:`0.00%`},{v:`=C11/$C$13`,f:`0.00%`}],[{v:``},{v:`合計（上位10）`},{v:`=SUM(C2:C11)`,f:`#,##0`},{v:``},{v:``}],[{v:``},{v:`世界推定人口（例）`},{v:805e7,f:`#,##0`},{v:``},{v:``}]]}]}}];Object.defineProperty(exports,"a",{enumerable:!0,get:function(){return C}}),Object.defineProperty(exports,"c",{enumerable:!0,get:function(){return s}}),Object.defineProperty(exports,"d",{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,"f",{enumerable:!0,get:function(){return n}}),Object.defineProperty(exports,"i",{enumerable:!0,get:function(){return D}}),Object.defineProperty(exports,"l",{enumerable:!0,get:function(){return a}}),Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return A}}),Object.defineProperty(exports,"o",{enumerable:!0,get:function(){return S}}),Object.defineProperty(exports,"p",{enumerable:!0,get:function(){return t}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return M}}),Object.defineProperty(exports,"s",{enumerable:!0,get:function(){return g}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return N}}),Object.defineProperty(exports,"u",{enumerable:!0,get:function(){return i}});