Merge remote-tracking branch 'upstream/develop' into feature/hf-24-stringify-currency

# Conflicts:
#	docs/guide/known-limitations.md

Author: marcin-kordas-hoc

.github/workflows/lint.yml

@@ -28,7 +28,18 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
 
-      - uses: actions/checkout@722adc63f1aa60a57ec37892e133b1d319cae598 # https://github.com/actions/checkout/releases/tag/v2.0.0
+      - name: Checkout main repository
+        uses: actions/checkout@722adc63f1aa60a57ec37892e133b1d319cae598 # https://github.com/actions/checkout/releases/tag/v2.0.0
+
+      - name: Checkout hyperformula-tests repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          ssh-key: ${{ secrets.DEPLOY_TOKEN }}
+          repository: handsontable/hyperformula-tests
+          path: test/hyperformula-tests
+
+      - name: Fetch hyperformula-tests and sync branches
+        run: cd test && ./fetch-tests.sh
 
       - name: Install dependencies
         run: npm ci

CHANGELOG.md

@@ -7,6 +7,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## [3.3.0] - 2026-05-20
+
 ### Added
 
 - Added 12 database functions: DCOUNT, DSUM, DAVERAGE, DMAX, DMIN, DGET, DPRODUCT, DCOUNTA, DSTDEV, DSTDEVP, DVAR, DVARP. [#1652](https://github.com/handsontable/hyperformula/pull/1652)

docs/.vuepress/config.js

@@ -216,7 +216,7 @@ module.exports = {
             ['/guide/integration-with-vue', 'Integration with Vue'],
             ['/guide/integration-with-angular', 'Integration with Angular'],
             ['/guide/integration-with-svelte', 'Integration with Svelte'],
-            ['/guide/ai-sdk', 'HyperFormula AI SDK'],
+            ['/guide/ai-sdk', 'Integration with Vercel AI SDK'],
             ['/guide/integration-with-langchain', 'Integration with LangChain'],
             ['/guide/mcp-server', 'HyperFormula MCP Server'],
           ]

docs/guide/ai-sdk.md

@@ -1,51 +1,67 @@
-# HyperFormula AI SDK
+# HyperFormula AI SDK for Vercel
 
-Let LLMs safely read/write spreadsheets and compute formulas via a deterministic engine.
+A [Vercel AI SDK](https://sdk.vercel.ai/docs) tool that gives your agents deterministic spreadsheet and formula computation — backed by HyperFormula's Excel-compatible engine.
+
+::: warning Not available yet — coming soon
+This integration is on our roadmap and **cannot be installed or used today**. The API shown below is a preview and may still change before the first release.
+
+If you'd like to try it, [join the early access list](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA) — we'll ping you the moment the first beta is ready, and your sign-up directly tells us how strongly to prioritize this integration.
+:::
 
 ## What it does
 
-- **Evaluate formulas on the fly** —call `calculateFormula()` to evaluate any Excel-compatible formula without placing it in a cell.
-- **Read and write cells and ranges** —get or set individual cells and multi-cell ranges so an LLM can inspect, populate, or modify sheet data programmatically.
-- **Trace dependencies** —call `getCellDependents()` and `getCellPrecedents()` to understand which cells feed into a formula and what downstream values would change.
+- **Evaluate formulas deterministically** — your agent runs any Excel-compatible formula through HyperFormula instead of asking the LLM to do math. Results are exact, reproducible, and auditable.
+- **Read and write cells and ranges** — the agent inspects, populates, or modifies sheet data through typed tool calls.
+- **Trace dependencies** — precedents and dependents are surfaced so the agent can explain how every value was derived.
+- **400+ built-in functions out of the box** — the agent has access to the full Excel-compatible function set (`SUM`, `VLOOKUP`, `IRR`, `INDEX/MATCH`, and the rest), no implementation work required.
 
-## Quickstart
+## Example
+
+Using HyperFormula as a tool inside the Vercel AI SDK:
 
 ```js
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
 import HyperFormula from 'hyperformula';
 import { createSpreadsheetTools } from 'hyperformula/ai';
 
-// 1. Create a HyperFormula instance with initial data
+// Build a workbook your agent can reason about.
 const hf = HyperFormula.buildFromArray([
   ['Revenue', 100],
   ['Cost',     60],
   ['Profit', '=B1-B2'],
 ]);
 
-// 2. Create tools your LLM agent can call
-const tools = createSpreadsheetTools(hf);
-
-// 3. Agent interaction examples
-tools.evaluate({ formula: '=IRR({-1000,300,400,500,200})' });
-// → 0.1189 — deterministic, no LLM math
-
-tools.setCellContents({ sheet: 0, col: 1, row: 0, value: 200 });
-tools.getRange({ sheet: 0, startCol: 0, startRow: 0, endCol: 1, endRow: 2 });
-// → [['Revenue', 200], ['Cost', 60], ['Profit', 140]]
-
-// Agent: "What drives the profit number?"
-tools.getDependents({ sheet: 0, col: 1, row: 0 });
-// → [{ sheet: 0, col: 1, row: 2 }] — Revenue flows into Profit
+// Pass the spreadsheet tools straight into generateText.
+const result = await generateText({
+  model: openai('gpt-4o'),
+  tools: createSpreadsheetTools(hf),
+  prompt: 'What drives the profit number, and what happens if revenue doubles?',
+});
 ```
 
+A single import, one extra line in `tools`, and the model can evaluate formulas, read ranges, and edit cells through the SDK — without inventing numbers.
+
 ## Use cases
 
-- **Explain a sheet** —ask an agent to summarize what a spreadsheet does, which cells are inputs, and how outputs are derived.
-- **Generate a what-if scenario** —let the model tweak assumptions (price, volume, rate) and observe how results change in real time.
-- **Validate and clean data** —have the agent scan ranges for errors, missing values, or inconsistencies and fix them with formulas or direct edits.
-- **Create formulas from natural language** —describe a calculation in plain English and let the model write and verify the correct Excel formula.
+- **Explain the spreadsheet** — ask the agent what a workbook does, which cells are inputs, and how each output is derived; get answers grounded in real formula evaluation.
+- **What-if scenarios and forecasting** — the agent tweaks assumptions and reports how downstream results change, deterministically.
+- **Validate and clean data** — the agent scans ranges for errors, missing values, or inconsistencies and fixes them in place.
+- **Generate formulas from natural language** — the agent translates a plain-English calculation into a verified, working Excel formula.
+- **Financial modeling and reporting** — NPV, IRR, amortization, KPI rollups, and other quantitative workflows where the answer must be exact and auditable.
+
+## Get early access
 
-## Beta access
+::: tip Be the first to try it
+We're actively building this integration. Drop your email and we'll notify you the moment the first beta lands — so you can try it before the public release.
 
-::: tip
-[Sign up for beta access](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA)
+[Join the early access list →](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA)
 :::
+
+## Links
+
+- [Vercel AI SDK documentation](https://sdk.vercel.ai/docs)
+- [HyperFormula on GitHub](https://github.com/handsontable/hyperformula)
+- [HyperFormula on npm](https://www.npmjs.com/package/hyperformula)
+- [Built-in functions](built-in-functions.md)
+- [Custom functions](custom-functions.md)

docs/guide/custom-functions.md

@@ -358,7 +358,7 @@ it('returns a VALUE error if the range argument contains a string', () => {
 
 ## Working demo
 
-Explore the full working example on <a :href="'https://stackblitz.com/github/handsontable/hyperformula-demos/tree/3.2.x/custom-functions?v=' + $page.buildDateURIEncoded">Stackblitz</a>.
+Explore the full working example on <a :href="'https://stackblitz.com/github/handsontable/hyperformula-demos/tree/3.3.x/custom-functions?v=' + $page.buildDateURIEncoded">Stackblitz</a>.
 
 This demo contains the implementation of both the
 [`GREET`](#add-a-simple-custom-function) and

docs/guide/integration-with-angular.md

@@ -124,4 +124,4 @@ The service above is already SSR-safe — HyperFormula has no browser-only API d
 
 ## Demo
 
-For a more advanced example, check out the <a :href="'https://stackblitz.com/github/handsontable/hyperformula-demos/tree/3.2.x/angular-demo?v=' + $page.buildDateURIEncoded">Angular demo on Stackblitz</a>.
+For a more advanced example, check out the <a :href="'https://stackblitz.com/github/handsontable/hyperformula-demos/tree/3.3.x/angular-demo?v=' + $page.buildDateURIEncoded">Angular demo on Stackblitz</a>.

docs/guide/integration-with-langchain.md

@@ -1,53 +1,71 @@
 # Integration with LangChain/LangGraph
 
-A LangChain/LangGraph tool that gives AI agents deterministic, Excel-compatible formula evaluation instead of relying on LLM-generated math.
+A [LangChain.js](https://js.langchain.com/) / [LangGraph](https://langchain-ai.github.io/langgraphjs/) tool that gives your agents deterministic spreadsheet and formula computation — backed by HyperFormula's Excel-compatible engine.
 
-## What it does
-
-**Without HyperFormula:**
-
-```python
-result = llm.invoke(
-    "Calculate the IRR for these cash flows: [-1000, 300, 400, 500, 200]"
-)
-# "The IRR is approximately 12.4%" ← non-deterministic, unverifiable
-```
-
-**With HyperFormula tool:**
-
-```python
-from langchain_core.tools import tool
-from hyperformula import HyperFormula
-
-hf = HyperFormula.build_from_array([[-1000, 300, 400, 500, 200]])
+::: warning Not available yet — coming soon
+This integration is on our roadmap and **cannot be installed or used today**. The API shown below is a preview and may still change before the first release.
 
-@tool
-def evaluate_formula(formula: str) -> str:
-    """Evaluate an Excel-compatible formula using HyperFormula."""
-    return hf.calculate_formula(formula, sheet_id=0)
+If you'd like to try it, [join the early access list](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA) — we'll ping you the moment the first beta is ready, and your sign-up directly tells us how strongly to prioritize this integration.
+:::
 
-agent = create_react_agent(llm, [evaluate_formula])
+## What it does
 
-# Agent calls: evaluate_formula("=IRR(A1:E1)")
-# → 0.1189 ← deterministic, auditable
+- **Evaluate formulas deterministically** — your agent runs any Excel-compatible formula through HyperFormula instead of asking the LLM to do math. Results are exact, reproducible, and auditable.
+- **Read and write cells and ranges** — the agent inspects, populates, or modifies sheet data through typed tool calls.
+- **Trace dependencies** — precedents and dependents are surfaced so the agent can explain how every value was derived.
+- **400+ built-in functions out of the box** — the agent has access to the full Excel-compatible function set (`SUM`, `VLOOKUP`, `IRR`, `INDEX/MATCH`, and the rest), no implementation work required.
+
+## Example
+
+Wiring HyperFormula into a LangGraph ReAct agent:
+
+```js
+import { ChatOpenAI } from '@langchain/openai';
+import { createReactAgent } from '@langchain/langgraph/prebuilt';
+import HyperFormula from 'hyperformula';
+import { createSpreadsheetTools } from 'hyperformula/langchain';
+
+const hf = HyperFormula.buildFromArray([
+  ['Revenue', 100],
+  ['Cost',     60],
+  ['Profit', '=B1-B2'],
+]);
+
+const agent = createReactAgent({
+  llm: new ChatOpenAI({ model: 'gpt-4o' }),
+  tools: createSpreadsheetTools(hf),
+});
+
+await agent.invoke({
+  messages: [
+    { role: 'user', content: 'What drives the profit number, and what happens if revenue doubles?' },
+  ],
+});
 ```
 
-## How it works
-
-1. **Agent populates a HyperFormula sheet** —writes data and formulas (`=SUM`, `=IF`, `=VLOOKUP`, etc.) into cells.
-2. **HyperFormula evaluates deterministically** —resolves the full dependency graph using 400+ built-in functions. No LLM in the loop for math.
-3. **Agent continues with verified data** —computed values flow back into the chain for reasoning, reporting, or downstream actions.
+A single import, one entry in `tools`, and the agent can evaluate formulas, read ranges, and edit cells through LangChain — without inventing numbers.
 
 ## Use cases
 
-- Financial modeling (NPV, IRR, amortization)
-- Data transformation and aggregation (SUMIF, VLOOKUP)
-- Dynamic pricing with formula-defined logic
-- What-if scenarios and forecasting
-- Report generation with verified KPIs
+- **Explain the spreadsheet** — ask the agent what a workbook does, which cells are inputs, and how each output is derived; get answers grounded in real formula evaluation.
+- **What-if scenarios and forecasting** — the agent tweaks assumptions and reports how downstream results change, deterministically.
+- **Validate and clean data** — the agent scans ranges for errors, missing values, or inconsistencies and fixes them in place.
+- **Generate formulas from natural language** — the agent translates a plain-English calculation into a verified, working Excel formula.
+- **Financial modeling and reporting** — NPV, IRR, amortization, KPI rollups, and other quantitative workflows where the answer must be exact and auditable.
 
-## Beta access
+## Get early access
 
-::: tip
-[Sign up for beta access](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA)
+::: tip Be the first to try it
+We're actively building this integration. Drop your email and we'll notify you the moment the first beta lands — so you can try it before the public release.
+
+[Join the early access list →](https://2fmjvg.share-eu1.hsforms.com/2e6drCkuLTn-1RuiYB91eJA)
 :::
+
+## Links
+
+- [LangChain.js documentation](https://js.langchain.com/)
+- [LangGraph documentation](https://langchain-ai.github.io/langgraphjs/)
+- [HyperFormula on GitHub](https://github.com/handsontable/hyperformula)
+- [HyperFormula on npm](https://www.npmjs.com/package/hyperformula)
+- [Built-in functions](built-in-functions.md)
+- [Custom functions](custom-functions.md)

docs/guide/integration-with-react.md

@@ -114,4 +114,4 @@ In the Pages Router, the same `dynamic(..., { ssr: false })` call works directly
 
 ## Demo
 
-For a more advanced example, check out the <a :href="'https://stackblitz.com/github/handsontable/hyperformula-demos/tree/3.2.x/react-demo?v=' + $page.buildDateURIEncoded">React demo on Stackblitz</a>.
+For a more advanced example, check out the <a :href="'https://stackblitz.com/github/handsontable/hyperformula-demos/tree/3.3.x/react-demo?v=' + $page.buildDateURIEncoded">React demo on Stackblitz</a>.

docs/guide/integration-with-svelte.md

@@ -123,4 +123,4 @@ In SvelteKit, top-level statements in `<script>` run on the server too. HyperFor
 
 ## Demo
 
-For a more advanced example, check out the <a :href="'https://stackblitz.com/github/handsontable/hyperformula-demos/tree/3.2.x/svelte-demo?v=' + $page.buildDateURIEncoded">Svelte demo on Stackblitz</a>.
+For a more advanced example, check out the <a :href="'https://stackblitz.com/github/handsontable/hyperformula-demos/tree/3.3.x/svelte-demo?v=' + $page.buildDateURIEncoded">Svelte demo on Stackblitz</a>.

docs/guide/integration-with-vue.md

@@ -113,7 +113,7 @@ const hfInstance = markRaw(
 
 ## Demo
 
-For a more advanced example, check out the <a :href="'https://stackblitz.com/github/handsontable/hyperformula-demos/tree/3.2.x/vue-3-demo?v=' + $page.buildDateURIEncoded">Vue 3 demo on Stackblitz</a>.
+For a more advanced example, check out the <a :href="'https://stackblitz.com/github/handsontable/hyperformula-demos/tree/3.3.x/vue-3-demo?v=' + $page.buildDateURIEncoded">Vue 3 demo on Stackblitz</a>.
 
 ::: tip
 This demo uses the [Vue 3](https://v3.vuejs.org/) framework. If you are looking for an example using Vue 2, check out the [code on GitHub](https://github.com/handsontable/hyperformula-demos/tree/2.5.x/vue-demo).