@cj-tech-master/excelts 9.3.1 → 9.4.0

package/dist/browser/index.d.ts

@@ -35,6 +35,7 @@ export type { NodeInput } from "./modules/excel/stream/workbook-reader.js";
 export { decodeCol, encodeCol, decodeRow, encodeRow, decodeCell, encodeCell, decodeRange, encodeRange } from "./modules/excel/utils/address.js";
 export type { CellAddress, SheetRange, Origin } from "./modules/excel/utils/address.js";
 export type { SheetToJSONOptions, AddJSONOptions, AddAOAOptions } from "./modules/excel/worksheet.js";
+export { getCellDisplayText, formatCellValue, isDateDisplayFormat } from "./modules/excel/utils/cell-format.js";
 export { dateToExcel, excelToDate } from "./utils/utils.base.js";
 export { base64ToUint8Array, uint8ArrayToBase64 } from "./utils/utils.base.js";
 export { xmlEncode, xmlDecode } from "./modules/xml/encode.js";

package/dist/browser/index.js

@@ -45,6 +45,8 @@ export { DefinedNames } from "./modules/excel/defined-names.js";
 // =============================================================================
 // Cell address encoding/decoding (0-indexed)
 export { decodeCol, encodeCol, decodeRow, encodeRow, decodeCell, encodeCell, decodeRange, encodeRange } from "./modules/excel/utils/address.js";
+// Cell display-text helpers (apply numFmt to produce an Excel-style string)
+export { getCellDisplayText, formatCellValue, isDateDisplayFormat } from "./modules/excel/utils/cell-format.js";
 // Date conversion (Excel serial dates <-> JS Date)
 export { dateToExcel, excelToDate } from "./utils/utils.base.js";
 // Base64 utilities (cross-platform)

package/dist/browser/modules/excel/cell.d.ts

@@ -130,6 +130,24 @@ declare class Cell {
     get comment(): Note | undefined;
     set comment(comment: Note | NoteConfig | undefined);
     get text(): string;
+    /**
+     * The cell's display text — the value formatted the way Excel would render
+     * it, applying the cell's `numFmt`. For a Date cell with `numFmt` `"mm-dd-yy"`,
+     * this returns e.g. `"04-12-19"` rather than the JS `Date.prototype.toString()`
+     * output you'd get from `cell.text`.
+     *
+     * Handles primitive values, dates, and formula results. For rich text,
+     * hyperlinks, errors, and other complex types, falls back to `cell.text`.
+     *
+     * Note: numFmt codes that are locale-dependent in Excel (e.g. built-in
+     * numFmtId 14 renders as `dd.mm.yyyy` under German locale but is stored
+     * as `mm-dd-yy`) are applied literally — excelts does not perform
+     * Excel's locale-based format substitution. If you need a specific date
+     * style across cells regardless of per-cell numFmts, call the exported
+     * {@link getCellDisplayText} helper with a `dateFormat` argument, or use
+     * `worksheet.toJSON({ dateFormat })`.
+     */
+    get displayText(): string;
     get html(): string;
     toString(): string;
     get formula(): string | undefined;

package/dist/browser/modules/excel/cell.js

@@ -1,6 +1,7 @@
 import { Enums } from "./enums.js";
 import { ExcelError, InvalidValueTypeError } from "./errors.js";
 import { Note } from "./note.js";
+import { getCellDisplayText } from "./utils/cell-format.js";
 import { colCache } from "./utils/col-cache.js";
 import { copyStyle } from "./utils/copy-style.js";
 import { slideFormula } from "./utils/shared-formula.js";
@@ -271,6 +272,26 @@ class Cell {
     get text() {
         return this._value.toString();
     }
+    /**
+     * The cell's display text — the value formatted the way Excel would render
+     * it, applying the cell's `numFmt`. For a Date cell with `numFmt` `"mm-dd-yy"`,
+     * this returns e.g. `"04-12-19"` rather than the JS `Date.prototype.toString()`
+     * output you'd get from `cell.text`.
+     *
+     * Handles primitive values, dates, and formula results. For rich text,
+     * hyperlinks, errors, and other complex types, falls back to `cell.text`.
+     *
+     * Note: numFmt codes that are locale-dependent in Excel (e.g. built-in
+     * numFmtId 14 renders as `dd.mm.yyyy` under German locale but is stored
+     * as `mm-dd-yy`) are applied literally — excelts does not perform
+     * Excel's locale-based format substitution. If you need a specific date
+     * style across cells regardless of per-cell numFmts, call the exported
+     * {@link getCellDisplayText} helper with a `dateFormat` argument, or use
+     * `worksheet.toJSON({ dateFormat })`.
+     */
+    get displayText() {
+        return getCellDisplayText(this);
+    }
     get html() {
         return escapeHtml(this.text);
     }

package/dist/browser/modules/excel/utils/cell-format.js

@@ -20,7 +20,7 @@ const TABLE_FMT = {
     11: "0.00E+00",
     12: "# ?/?",
     13: "# ??/??",
-    14: "m/d/yy",
+    14: "mm-dd-yy",
     15: "d-mmm-yy",
     16: "d-mmm",
     17: "mmm-yy",
@@ -210,6 +210,56 @@ const MONTHS_LONG = [
 const MONTHS_LETTER = ["J", "F", "M", "A", "M", "J", "J", "A", "S", "O", "N", "D"];
 const DAYS_SHORT = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
 const DAYS_LONG = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+/**
+ * Disambiguate each `mm` occurrence in a format string that has already been
+ * placeholder-substituted for the other date/time tokens.
+ *
+ * Excel's rule: `mm` is minutes when it's adjacent to an hour or seconds
+ * token (with no intervening date tokens); otherwise it's a zero-padded
+ * month. This must be decided per occurrence — a single format string can
+ * contain both roles (e.g. `"yyyy-mm-dd hh:mm:ss"`).
+ *
+ * The caller has already replaced `yyyy`/`yy` → `Y4/Y2`, month-name tokens
+ * `mmmmm/mmmm/mmm` → `MN5/MN4/MN3`, `dd`/`d` → `D2/D1`, `hh`/`h` → `H2/H1`,
+ * `ss`/`s` → `S2/S1`. So any remaining literal `mm` substrings here are
+ * ambiguous between minute and month.
+ *
+ * Returns the input with each `mm` replaced by either `\x00MI2\x00` (minutes)
+ * or `\x00M2\x00` (month, zero-padded).
+ */
+function resolveMonthOrMinute(s) {
+    // Tokens that, when present between an `mm` and a time anchor, break the
+    // "adjacent time context" chain and push the `mm` back into month-land.
+    const DATE_TOKEN = /\x00(?:Y[24]|D[12]|MN[345])\x00/;
+    const HOUR_TOKEN = /\x00H[12]\x00/g;
+    const SEC_TOKEN = /\x00S[12]\x00/g;
+    let out = "";
+    let work = s;
+    let idx = work.search(/mm/i);
+    while (idx !== -1) {
+        const before = work.slice(0, idx);
+        const after = work.slice(idx + 2);
+        // Find the *nearest* hour token preceding this `mm` (scan from the right).
+        let nearestHourIdx = -1;
+        let m;
+        HOUR_TOKEN.lastIndex = 0;
+        while ((m = HOUR_TOKEN.exec(before)) !== null) {
+            nearestHourIdx = m.index;
+        }
+        // Find the *nearest* seconds token following this `mm`.
+        SEC_TOKEN.lastIndex = 0;
+        const secMatch = SEC_TOKEN.exec(after);
+        const nearestSecIdx = secMatch ? secMatch.index : -1;
+        const hourInRange = nearestHourIdx !== -1 && !DATE_TOKEN.test(before.slice(nearestHourIdx));
+        const secInRange = nearestSecIdx !== -1 && !DATE_TOKEN.test(after.slice(0, nearestSecIdx));
+        const isMinutes = hourInRange || secInRange;
+        out += before + (isMinutes ? "\x00MI2\x00" : "\x00M2\x00");
+        work = after;
+        idx = work.search(/mm/i);
+    }
+    out += work;
+    return out;
+}
 /**
  * Format a date value using Excel date format
  * @param serial Excel serial number (days since 1900-01-01)
@@ -270,16 +320,14 @@ function formatDate(serial, fmt) {
     // Seconds (before mm to avoid confusion)
     result = result.replace(/ss/gi, "\x00S2\x00");
     result = result.replace(/\bs\b/gi, "\x00S1\x00");
-    // Minutes/Month mm - context dependent
-    // If near h or s, it's minutes; otherwise month
-    // For simplicity, check if we already have hour tokens nearby
-    const hasTimeContext = /\x00H[12]\x00.*mm|mm.*\x00S[12]\x00/i.test(result);
-    if (hasTimeContext) {
-        result = result.replace(/mm/gi, "\x00MI2\x00");
-    }
-    else {
-        result = result.replace(/mm/gi, "\x00M2\x00");
-    }
+    // Minutes/Month `mm` — position-dependent. Excel treats `mm` as minutes
+    // when the nearest neighboring time-token is an hour (before) or a
+    // seconds token (after); otherwise it's month. This must be decided **per
+    // occurrence**, because a single format string can contain both roles —
+    // e.g. in `"yyyy-mm-dd hh:mm:ss"` the first `mm` is month and the second
+    // is minutes. A single global `hasTimeContext` flag would miscategorise
+    // all `mm` as minutes in such mixed formats.
+    result = resolveMonthOrMinute(result);
     result = result.replace(/\bm\b/gi, "\x00M1\x00");
     // AM/PM
     result = result.replace(/AM\/PM/gi, "\x00AMPM\x00");
@@ -887,6 +935,16 @@ export function isDateDisplayFormat(fmt) {
     }
     return false;
 }
+/**
+ * Default format applied to Date values whose numFmt is `General` or empty.
+ *
+ * Excel itself substitutes a locale-dependent short date in this case (US:
+ * `m/d/yyyy`). We pick an ISO-like `yyyy-mm-dd` so consumers who never set a
+ * `numFmt` still get a sensible, unambiguous rendering instead of the raw
+ * Excel serial number.
+ */
+const DEFAULT_DATE_FORMAT = "yyyy-mm-dd";
+const DEFAULT_DATETIME_FORMAT = "yyyy-mm-dd hh:mm:ss";
 /**
  * Format a value according to the given format string.
  * Handles Date objects with timezone-independent Excel serial conversion.
@@ -901,8 +959,22 @@ export function formatCellValue(value, fmt, dateFormat) {
             }
             return format(fmt, serial);
         }
-        const actualFmt = dateFormat && isDateDisplayFormat(fmt) ? dateFormat : fmt;
-        return format(actualFmt, serial);
+        // For Date values whose numFmt is missing or General, Excel substitutes a
+        // default short-date format. Without this, `format("General", serial)`
+        // would emit the raw Excel serial (e.g. "43567") — almost never what the
+        // caller wants. Pick a datetime-aware default based on whether the value
+        // carries a non-midnight time component.
+        let effectiveFmt;
+        if (dateFormat && isDateDisplayFormat(fmt)) {
+            effectiveFmt = dateFormat;
+        }
+        else if (!fmt || isGeneral(fmt)) {
+            effectiveFmt = serial % 1 === 0 ? DEFAULT_DATE_FORMAT : DEFAULT_DATETIME_FORMAT;
+        }
+        else {
+            effectiveFmt = fmt;
+        }
+        return format(effectiveFmt, serial);
     }
     return format(fmt, value);
 }

package/dist/browser/modules/excel/workbook.browser.d.ts

@@ -603,6 +603,63 @@ declare class Workbook {
      * ```
      */
     calculateFormulas(): void;
+    /**
+     * Per-workbook registry of user-defined functions. The formula engine
+     * consults this map before the built-in 433-function registry, so a
+     * registered name either adds a new function (`MYFN`) or shadows a
+     * built-in (`IRR` → project-specific variant).
+     *
+     * Populated by {@link registerFunction}; read by the formula engine
+     * when the host calls `calculateFormulas()` — see
+     * `@formula/runtime/evaluator.ts::evaluateCall`.
+     */
+    userFunctions?: Map<string, {
+        minArity: number;
+        maxArity: number;
+        invoke: (args: unknown[]) => unknown;
+        volatile?: boolean;
+    }>;
+    /**
+     * Register (or replace) a custom formula function on this workbook.
+     *
+     * The function becomes visible to `calculateFormulas()` on this
+     * workbook only — the built-in registry stays untouched. Names are
+     * case-insensitive (normalised to uppercase) and must not include
+     * the `_XLFN.` prefix — the engine strips that automatically.
+     *
+     * @param name    Function name (case-insensitive).
+     * @param fn      Implementation. Receives already-evaluated RuntimeValue
+     *                arguments; return a RuntimeValue. Wrap failures with
+     *                `rvError("#VALUE!")` rather than throwing — throws are
+     *                caught at the evaluator boundary and surface as
+     *                `#VALUE!` so a buggy custom function doesn't tear
+     *                down the whole calculation pass.
+     * @param options Optional arity bounds. Defaults to `minArity=0`,
+     *                `maxArity=255` (Excel's universal argument cap), so
+     *                simple variadic functions work without extra config.
+     *                Set `volatile: true` when the function should be
+     *                re-evaluated on every calc cycle (analogous to
+     *                built-in `RAND`, `NOW`). Currently reserved for
+     *                future use; the engine recomputes every formula on
+     *                each `calculateFormulas()` call regardless.
+     *
+     * ```ts
+     * import { rvNumber } from "@cj-tech-master/excelts/formula";
+     * workbook.registerFunction("DOUBLE", ([x]) => {
+     *   return rvNumber((x as any).value * 2);
+     * }, { minArity: 1, maxArity: 1 });
+     * ```
+     */
+    registerFunction(name: string, fn: (args: unknown[]) => unknown, options?: {
+        minArity?: number;
+        maxArity?: number;
+        volatile?: boolean;
+    }): void;
+    /**
+     * Remove a user-registered function. No-op when the name isn't
+     * registered; returns `true` when an entry was removed.
+     */
+    unregisterFunction(name: string): boolean;
     clearThemes(): void;
     /**
      * Add Image to Workbook and return the id

package/dist/browser/modules/excel/workbook.browser.js

@@ -1060,6 +1060,55 @@ class Workbook {
     calculateFormulas() {
         invokeFormulaEngine(this);
     }
+    /**
+     * Register (or replace) a custom formula function on this workbook.
+     *
+     * The function becomes visible to `calculateFormulas()` on this
+     * workbook only — the built-in registry stays untouched. Names are
+     * case-insensitive (normalised to uppercase) and must not include
+     * the `_XLFN.` prefix — the engine strips that automatically.
+     *
+     * @param name    Function name (case-insensitive).
+     * @param fn      Implementation. Receives already-evaluated RuntimeValue
+     *                arguments; return a RuntimeValue. Wrap failures with
+     *                `rvError("#VALUE!")` rather than throwing — throws are
+     *                caught at the evaluator boundary and surface as
+     *                `#VALUE!` so a buggy custom function doesn't tear
+     *                down the whole calculation pass.
+     * @param options Optional arity bounds. Defaults to `minArity=0`,
+     *                `maxArity=255` (Excel's universal argument cap), so
+     *                simple variadic functions work without extra config.
+     *                Set `volatile: true` when the function should be
+     *                re-evaluated on every calc cycle (analogous to
+     *                built-in `RAND`, `NOW`). Currently reserved for
+     *                future use; the engine recomputes every formula on
+     *                each `calculateFormulas()` call regardless.
+     *
+     * ```ts
+     * import { rvNumber } from "@cj-tech-master/excelts/formula";
+     * workbook.registerFunction("DOUBLE", ([x]) => {
+     *   return rvNumber((x as any).value * 2);
+     * }, { minArity: 1, maxArity: 1 });
+     * ```
+     */
+    registerFunction(name, fn, options) {
+        if (!this.userFunctions) {
+            this.userFunctions = new Map();
+        }
+        this.userFunctions.set(name.toUpperCase(), {
+            minArity: options?.minArity ?? 0,
+            maxArity: options?.maxArity ?? 255,
+            invoke: fn,
+            volatile: options?.volatile ?? false
+        });
+    }
+    /**
+     * Remove a user-registered function. No-op when the name isn't
+     * registered; returns `true` when an entry was removed.
+     */
+    unregisterFunction(name) {
+        return this.userFunctions?.delete(name.toUpperCase()) ?? false;
+    }
     // ===========================================================================
     // Themes
     // ===========================================================================

package/dist/browser/modules/excel/xlsx/defaultnumformats.js

@@ -17,7 +17,7 @@ const defaultNumFormats = {
     19: { f: "h:mm:ss AM/PM" },
     20: { f: "h:mm" },
     21: { f: "h:mm:ss" },
-    22: { f: 'm/d/yy "h":mm' },
+    22: { f: "m/d/yy h:mm" },
     27: {
         "zh-tw": "[$-404]e/m/d",
         "zh-cn": 'yyyy"年"m"月"',
@@ -75,8 +75,8 @@ const defaultNumFormats = {
     },
     37: { f: "#,##0 ;(#,##0)" },
     38: { f: "#,##0 ;[Red](#,##0)" },
-    39: { f: "#,##0.00 ;(#,##0.00)" },
-    40: { f: "#,##0.00 ;[Red](#,##0.00)" },
+    39: { f: "#,##0.00;(#,##0.00)" },
+    40: { f: "#,##0.00;[Red](#,##0.00)" },
     45: { f: "mm:ss" },
     46: { f: "[h]:mm:ss" },
     47: { f: "mmss.0" },

package/dist/browser/modules/formula/compile/binder.js

@@ -105,6 +105,8 @@ export function bind(node, ctx) {
             return bindName(node.name, ctx);
         case NodeType.StructuredRef:
             return bindStructuredRef(node.tableName, node.columns, node.specials, ctx);
+        case NodeType.UnionRef:
+            return bindUnionRef(node, ctx);
         default:
             return assertNever(node);
     }
@@ -160,6 +162,11 @@ function bindRangeRef(node, ctx) {
     const bottom = Math.max(startRow, endRow);
     const left = Math.min(startCol, endCol);
     const right = Math.max(startCol, endCol);
+    // Bounds-check the rectangle against Excel's sheet limits. Defined-name
+    // strings that bypass the tokenizer can carry arbitrary addresses.
+    if (top < 1 || bottom > 1048576 || left < 1 || right > 16384) {
+        return boundErrorLiteral("#REF!");
+    }
     // 3D range reference: Sheet1:Sheet3!A1:B2
     if (node.endSheet) {
         const sheets = getSheetsInRange(ctx.snapshot, sheet, node.endSheet);
@@ -173,6 +180,13 @@ function bindRangeRef(node, ctx) {
             inner
         };
     }
+    // Validate sheet exists — matches the parity check `bindCellRef` and
+    // `bindColRangeRef` / `bindRowRangeRef` perform. Without this, a range
+    // like `NoSuchSheet!A1:B2` would silently bind to an empty-read at
+    // runtime instead of surfacing as `#REF!` at compile time.
+    if (!ctx.snapshot.worksheetsByName.has(sheet.toLowerCase())) {
+        return boundErrorLiteral("#REF!");
+    }
     return boundAreaRef(sheet, top, left, bottom, right);
 }
 function bindColRangeRef(node, ctx) {
@@ -181,6 +195,12 @@ function bindColRangeRef(node, ctx) {
     const endCol = colLetterToNumber(node.endCol);
     const leftCol = Math.min(startCol, endCol);
     const rightCol = Math.max(startCol, endCol);
+    // Excel's maximum column is 16384 (XFD). The tokenizer enforces this
+    // for plain refs, but defined-name range strings that bypass the
+    // tokenizer could carry larger letter sequences (e.g. `ZZZ`).
+    if (leftCol < 1 || rightCol > 16384) {
+        return boundErrorLiteral("#REF!");
+    }
     // Validate sheet exists
     if (!ctx.snapshot.worksheetsByName.has(sheet.toLowerCase())) {
         return boundErrorLiteral("#REF!");
@@ -210,6 +230,11 @@ function bindRowRangeRef(node, ctx) {
     const sheet = node.sheet ?? ctx.currentSheet;
     const topRow = Math.min(node.startRow, node.endRow);
     const bottomRow = Math.max(node.startRow, node.endRow);
+    // Excel's maximum row is 1048576. Re-check here because defined-name
+    // strings can bypass the tokenizer.
+    if (topRow < 1 || bottomRow > 1048576) {
+        return boundErrorLiteral("#REF!");
+    }
     // Validate sheet exists
     if (!ctx.snapshot.worksheetsByName.has(sheet.toLowerCase())) {
         return boundErrorLiteral("#REF!");
@@ -235,6 +260,24 @@ function bindRowRangeRef(node, ctx) {
     };
 }
 // ============================================================================
+// Union Reference Binding — `(A1:B2, D4:E5)`
+// ============================================================================
+function bindUnionRef(node, ctx) {
+    // Each area must bind to a reference-producing expression. If any
+    // member is a non-reference literal, the whole union collapses to
+    // `#REF!` — Excel rejects things like `(1, A1)` outright. We defer
+    // the runtime-reference check (INDIRECT/OFFSET) to the evaluator.
+    const bounds = [];
+    for (const area of node.areas) {
+        const bound = bind(area, ctx);
+        bounds.push(bound);
+    }
+    return {
+        kind: BoundExprKind.UnionRef,
+        areas: bounds
+    };
+}
+// ============================================================================
 // Name Binding
 // ============================================================================
 function bindName(name, ctx) {
@@ -324,12 +367,11 @@ function findTable(snapshot, tableName) {
     if (!tableName) {
         return null;
     }
-    // Use the pre-built tablesByName index for O(1) lookup
-    const resolved = snapshot.tablesByName.get(tableName.toLowerCase());
-    if (resolved) {
-        return { table: resolved.table, sheetName: resolved.sheetName };
-    }
-    return null;
+    // Use the pre-built tablesByName index for O(1) lookup. The snapshot's
+    // `ResolvedTable` already matches our `TableWithSheet` shape (same
+    // `{ table, sheetName }` pair), so we can return it directly instead
+    // of wrapping every hit in a fresh object.
+    return snapshot.tablesByName.get(tableName.toLowerCase()) ?? null;
 }
 function resolveStructuredRefBounds(tw, columns, specials) {
     const t = tw.table;

package/dist/browser/modules/formula/compile/bound-ast.d.ts

@@ -46,7 +46,8 @@ export declare const enum BoundExprKind {
     Array = 12,
     NameExpr = 13,
     Lambda = 14,
-    StructuredRef = 15
+    StructuredRef = 15,
+    UnionRef = 16
 }
 /**
  * A resolved literal value.
@@ -220,7 +221,20 @@ export interface BoundStructuredRef {
     /** Special items (#Headers, #Data, #Totals, #All, #This Row). */
     readonly specials: readonly string[];
 }
-export type BoundExpr = BoundLiteral | BoundCellRef | BoundAreaRef | BoundColRangeRef | BoundRowRangeRef | BoundRef3D | BoundBinaryOp | BoundUnaryOp | BoundPercent | BoundCall | BoundSpecialCall | BoundArray | BoundNameExpr | BoundLambda | BoundStructuredRef;
+/**
+ * A union of reference-producing sub-expressions — `(A1:B2, D4:E5)`.
+ *
+ * Produced only by parenthesised comma lists, and only used by callers
+ * that explicitly know how to consume a multi-area reference (INDEX's
+ * `area_num`, AREAS, union-operator arithmetic). Evaluating a
+ * UnionRef in any other context surfaces as `#VALUE!` since Excel
+ * forbids arithmetic / coercion on disjoint areas.
+ */
+export interface BoundUnionRef {
+    readonly kind: BoundExprKind.UnionRef;
+    readonly areas: readonly BoundExpr[];
+}
+export type BoundExpr = BoundLiteral | BoundCellRef | BoundAreaRef | BoundColRangeRef | BoundRowRangeRef | BoundRef3D | BoundBinaryOp | BoundUnaryOp | BoundPercent | BoundCall | BoundSpecialCall | BoundArray | BoundNameExpr | BoundLambda | BoundStructuredRef | BoundUnionRef;
 export declare function boundLiteral(value: number | string | boolean | null, errorCode?: string): BoundLiteral;
 export declare function boundCellRef(sheet: string, row: number, col: number): BoundCellRef;
 export declare function boundAreaRef(sheet: string, top: number, left: number, bottom: number, right: number): BoundAreaRef;

package/dist/browser/modules/formula/compile/bound-ast.js

@@ -51,6 +51,7 @@ export var BoundExprKind;
     BoundExprKind[BoundExprKind["NameExpr"] = 13] = "NameExpr";
     BoundExprKind[BoundExprKind["Lambda"] = 14] = "Lambda";
     BoundExprKind[BoundExprKind["StructuredRef"] = 15] = "StructuredRef";
+    BoundExprKind[BoundExprKind["UnionRef"] = 16] = "UnionRef";
 })(BoundExprKind || (BoundExprKind = {}));
 // ============================================================================
 // Constructor Helpers

package/dist/browser/modules/formula/compile/compiled-formula.js

@@ -209,6 +209,13 @@ function walkDeps(expr, cells, areas, tablesByName, nameResolver, visitedNames)
                 }
             }
             break;
+        case BoundExprKind.UnionRef:
+            // Each member of a `(a1, a2, ...)` union contributes its own
+            // dependencies — downstream reads target cells in every area.
+            for (const area of expr.areas) {
+                walkDeps(area, cells, areas, tablesByName, nameResolver, visitedNames);
+            }
+            break;
     }
 }
 // ============================================================================
@@ -275,9 +282,15 @@ export function detectDynamicArrayFunction(ast, bound) {
             return true;
         }
     }
-    // Check bound expression level
-    if (bound.kind === BoundExprKind.Call && DYNAMIC_ARRAY_FUNCTION_NAMES.has(bound.name)) {
-        return true;
+    // Check bound expression level. Strip `_XLFN.` prefix here too —
+    // `boundCall` preserves the prefix on the bound name, so without the
+    // strip a synthesised bound call (e.g. from INDIRECT re-parse) would
+    // miss detection.
+    if (bound.kind === BoundExprKind.Call) {
+        const canonical = stripFunctionPrefix(bound.name);
+        if (DYNAMIC_ARRAY_FUNCTION_NAMES.has(canonical)) {
+            return true;
+        }
     }
     return false;
 }
@@ -298,9 +311,15 @@ export function detectSubtotalOutput(ast, bound) {
             return true;
         }
     }
-    if (bound.kind === BoundExprKind.Call &&
-        (bound.name === "SUBTOTAL" || bound.name === "AGGREGATE")) {
-        return true;
+    if (bound.kind === BoundExprKind.Call) {
+        // Strip `_XLFN.` / `_XLFN._XLWS.` prefixes before matching — otherwise
+        // `_XLFN.AGGREGATE(...)` silently wouldn't be marked as a subtotal
+        // output, so an outer SUBTOTAL / AGGREGATE over its cell would
+        // double-count the aggregated value.
+        const canonical = stripFunctionPrefix(bound.name);
+        if (canonical === "SUBTOTAL" || canonical === "AGGREGATE") {
+            return true;
+        }
     }
     return false;
 }
@@ -319,15 +338,24 @@ export function analyzeExpr(expr, nameResolver) {
     return { isVolatile, hasDynamicRefs, containsLambda };
     function walkAnalyze(e) {
         switch (e.kind) {
-            case BoundExprKind.Call:
-                if (VOLATILE_FUNCTIONS.has(e.name)) {
+            case BoundExprKind.Call: {
+                // `boundCall` stores the function name uppercased but preserves
+                // any `_XLFN.` / `_XLFN._XLWS.` prefix the source text contained.
+                // Strip the prefix before VOLATILE_FUNCTIONS lookup so e.g.
+                // `_XLFN.RANDARRAY()` (an XLFN-prefixed volatile) correctly
+                // invalidates the session cache across calc cycles.
+                const canonical = stripFunctionPrefix(e.name);
+                if (VOLATILE_FUNCTIONS.has(canonical)) {
                     isVolatile = true;
                 }
                 for (const arg of e.args) {
                     walkAnalyze(arg);
                 }
                 break;
+            }
             case BoundExprKind.SpecialCall:
+                // Special-call names are already stripped of any `_XLFN.` prefix
+                // by `canonicalSpecialForm` in the binder, so no re-strip here.
                 if (DYNAMIC_REF_FUNCTIONS.has(e.name)) {
                     hasDynamicRefs = true;
                 }
@@ -375,6 +403,11 @@ export function analyzeExpr(expr, nameResolver) {
                     }
                 }
                 break;
+            case BoundExprKind.UnionRef:
+                for (const area of e.areas) {
+                    walkAnalyze(area);
+                }
+                break;
             default:
                 // Literal, CellRef, AreaRef, etc. — no children to analyze
                 break;

package/dist/browser/modules/formula/functions/_shared.d.ts

@@ -33,6 +33,25 @@ export declare function argToNumber(arg: RuntimeValue): NumberValue | ErrorValue
  * `number[]` after an error check should map `.value` themselves.
  */
 export declare function flattenNumbers(args: RuntimeValue[]): (NumberValue | ErrorValue)[];
+/**
+ * Streaming fold over numeric arguments.
+ *
+ * Same selection rules as `flattenNumbers` (array cells contribute only
+ * Number/Error; direct scalar coercion via `toNumberRV`; blanks dropped),
+ * but the caller's `onNumber` callback fires inline — no intermediate
+ * array is allocated. On the first error encountered the scan short-
+ * circuits and returns that error.
+ *
+ * Returns:
+ *   - `null` when iteration finished without encountering an error, or
+ *   - the `ErrorValue` that aborted the scan.
+ *
+ * Prefer this over `flattenNumbers` + `firstError` + manual loop in hot
+ * aggregates (SUM / AVERAGE / MIN / MAX / …). The allocation saved is
+ * one `NumberValue | ErrorValue` array per invocation — meaningful
+ * when the engine sums tens of thousands of cells.
+ */
+export declare function forEachNumber(args: readonly RuntimeValue[], onNumber: (n: number) => void): ErrorValue | null;
 /**
  * Flatten all cells from the arguments into a flat list of ScalarValue,
  * preserving every cell (including blanks, errors, booleans, strings).