@cj-tech-master/excelts 9.5.5 → 9.5.6

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

@@ -339,6 +339,17 @@ declare class Worksheet {
      */
     private _spliceMerges;
     get hasMerges(): boolean;
+    /**
+     * Read-only enumeration of every merged region on this sheet
+     * (1-based, inclusive). Consumed by the formula engine's snapshot
+     * builder to detect `#SPILL!` conflicts. See issue #162 follow-up.
+     */
+    get mergedRegions(): ReadonlyArray<{
+        readonly top: number;
+        readonly left: number;
+        readonly bottom: number;
+        readonly right: number;
+    }>;
     /**
      * Scan the range and if any cell is part of a merge, un-merge the group.
      * Note this function can affect multiple merges and merge-blocks are

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

@@ -907,6 +907,19 @@ class Worksheet {
         // return true if this._merges has a merge object
         return Object.values(this._merges).some(Boolean);
     }
+    /**
+     * Read-only enumeration of every merged region on this sheet
+     * (1-based, inclusive). Consumed by the formula engine's snapshot
+     * builder to detect `#SPILL!` conflicts. See issue #162 follow-up.
+     */
+    get mergedRegions() {
+        return Object.values(this._merges).map(merge => ({
+            top: merge.top,
+            left: merge.left,
+            bottom: merge.bottom,
+            right: merge.right
+        }));
+    }
     /**
      * Scan the range and if any cell is part of a merge, un-merge the group.
      * Note this function can affect multiple merges and merge-blocks are

package/dist/browser/modules/formula/integration/apply-writeback-plan.js

@@ -136,8 +136,14 @@ function applySpillWrite(workbook, op) {
                 }
             }
             else {
-                // Ghost cell: set value (not result)
+                // Ghost cell: set value (not result). Defence in depth — the
+                // plan builder rejects spills onto merged regions, so a Merge
+                // type here is unreachable; guard anyway because writing
+                // through `MergeValue`'s setter would clobber the master.
                 const targetCell = ws.getCell(targetRow, targetCol);
+                if (targetCell.type === CellValueTypeLike.Merge) {
+                    continue;
+                }
                 targetCell.value = snapshotValueToRaw(val);
             }
         }
@@ -160,9 +166,17 @@ function applyCleanupWrite(workbook, op) {
     }
     for (const { row, col } of op.cells) {
         const cell = ws.findCell(row, col);
-        if (cell) {
-            cell.value = null;
+        if (!cell) {
+            continue;
+        }
+        // Defence in depth: writing `null` to a merge slave would forward
+        // through `MergeValue`'s setter and wipe the master's value. The
+        // plan builder already skips merged regions in `collectStaleGhosts`,
+        // so this guard is belt-and-suspenders.
+        if (cell.type === CellValueTypeLike.Merge) {
+            continue;
         }
+        cell.value = null;
     }
 }
 // ============================================================================

package/dist/browser/modules/formula/integration/workbook-adapter.js

@@ -95,13 +95,24 @@ function buildWorksheetSnapshot(ws, date1904) {
         ? { top: dims.top, left: dims.left, bottom: dims.bottom, right: dims.right }
         : null;
     const tables = buildTables(ws);
+    // Defensive copy — snapshot must not alias host-owned arrays.
+    const hostMergedRegions = ws.mergedRegions;
+    const mergedRegions = hostMergedRegions
+        ? hostMergedRegions.map(r => ({
+            top: r.top,
+            left: r.left,
+            bottom: r.bottom,
+            right: r.right
+        }))
+        : [];
     return {
         id: ws.id,
         name: ws.name,
         dimensions,
         cells,
         hiddenRows,
-        tables
+        tables,
+        mergedRegions
     };
 }
 // ============================================================================
@@ -113,6 +124,14 @@ function buildCellSnapshot(cell, row, col, date1904) {
     if (cellType === CellValueTypeLike.Null) {
         return null;
     }
+    // Skip merge slaves — Excel treats them as blank for formula
+    // purposes, but the host's `MergeValue` proxy would forward
+    // `cell.value` from the master, so letting them into `cells` would
+    // double-count master values in range aggregates. See issue #162
+    // and the `Merge` case in `CellValueTypeLike`.
+    if (cellType === CellValueTypeLike.Merge) {
+        return null;
+    }
     // ── Formula cells ──
     if (cellType === CellValueTypeLike.Formula) {
         return buildFormulaCellSnapshot(cell, row, col, date1904);

package/dist/browser/modules/formula/integration/workbook-snapshot.d.ts

@@ -121,6 +121,18 @@ export interface WorksheetSnapshot {
     readonly hiddenRows: ReadonlySet<number>;
     /** Tables defined in this worksheet. */
     readonly tables: readonly TableSnapshot[];
+    /**
+     * Merged regions on this worksheet, as 1-based inclusive rectangles.
+     * Consulted by the writeback planner to reject `#SPILL!` conflicts;
+     * the evaluator does not need this since merge slaves are already
+     * filtered out of `cells`.
+     */
+    readonly mergedRegions: readonly {
+        readonly top: number;
+        readonly left: number;
+        readonly bottom: number;
+        readonly right: number;
+    }[];
 }
 /**
  * Column definition within a table.

package/dist/browser/modules/formula/materialize/build-writeback-plan.js

@@ -247,6 +247,14 @@ activeSpillTargets) {
     if (inst.row + arr.height - 1 > 1048576 || inst.col + arr.width - 1 > 16384) {
         return "error";
     }
+    // Reject if the source cell itself sits inside a merged region.
+    // Excel reports #SPILL! whenever a dynamic-array formula is placed
+    // in a merged cell, even when the ghosts land outside the merge.
+    // The ghost loop below skips `(r=0, c=0)` and the master's value is
+    // already in `cells`, so it would not catch this case.
+    if (isInMergedRegion(ws, inst.row, inst.col)) {
+        return "error";
+    }
     // Check spill availability: verify all target ghost cells are unoccupied
     for (let r = 0; r < arr.height; r++) {
         for (let c = 0; c < arr.width; c++) {
@@ -261,6 +269,16 @@ activeSpillTargets) {
             if (activeSpillTargets.has(targetKey)) {
                 return "error";
             }
+            // Refuse to spill onto any cell that belongs to a merged region.
+            // The cell itself may be a merge slave — which the snapshot
+            // builder filters out of `ws.cells`, so the value/formula checks
+            // below would treat it as empty — but writing there would mutate
+            // the master via `MergeValue`'s setter in `@excel/cell` and
+            // silently corrupt the merge. Excel reports `#SPILL!` whenever a
+            // dynamic-array result tries to land in a merge.
+            if (isInMergedRegion(ws, targetRow, targetCol)) {
+                return "error";
+            }
             // Check if the cell is a ghost from ANY previous spill.
             // If the user hasn't modified it, it's safe to overwrite — the
             // originating formula will clean it up (or we'll overwrite it).
@@ -349,6 +367,19 @@ function collectStaleGhosts(region, previousGhosts, snapshot) {
             }
             const targetRow = region.sourceRow + r;
             const targetCol = region.sourceCol + c;
+            // If the user (or a previous edit) has placed this former ghost
+            // inside a merged region, skip it. The cell is now either a merge
+            // master (carrying the user's intentional value) or a merge slave
+            // (whose `cell.value = null` writeback would forward through
+            // `MergeValue`'s setter and clobber the master). Either way,
+            // cleanup must not touch it. The snapshot builder filters merge
+            // slaves out of `ws.cells` (see issue #162), so the
+            // `isGhostUnmodified` check below would otherwise miss this case
+            // — `cell` would be `undefined`, which currently means
+            // "unmodified, safe to wipe".
+            if (isInMergedRegion(ws, targetRow, targetCol)) {
+                continue;
+            }
             const targetKey = spillCellKeyFromId(region.worksheetId, targetRow, targetCol);
             const cell = ws.cells.get(snapshotCellKey(targetRow, targetCol));
             if (isGhostUnmodified(cell, targetKey, previousGhosts)) {
@@ -380,6 +411,22 @@ function emitPreviousSpillCleanup(previousRegion, previousGhosts, snapshot, oper
         cells: cleanupCells
     });
 }
+/**
+ * Test whether `(row, col)` falls inside any merged region of `ws`.
+ *
+ * Linear scan — merge counts per sheet are small in practice. The
+ * snapshot builder filters merge slaves out of `ws.cells`, so callers
+ * use this helper to recover the "is this cell part of a merge?"
+ * signal that the cell map alone no longer carries.
+ */
+function isInMergedRegion(ws, row, col) {
+    for (const region of ws.mergedRegions) {
+        if (row >= region.top && row <= region.bottom && col >= region.left && col <= region.right) {
+            return true;
+        }
+    }
+    return false;
+}
 function isGhostUnmodified(cell, ghostKey, previousGhosts) {
     if (!cell) {
         return true;

package/dist/browser/modules/formula/materialize/types.d.ts

@@ -23,18 +23,28 @@ export interface CellErrorValueLike {
  */
 export type FormulaResultLike = number | string | boolean | Date | CellErrorValueLike | undefined;
 /**
- * Numeric cell-type tag exposed by host cells. The engine only compares
- * against `Null` and `Formula`; any other value is treated as a scalar
- * literal.
+ * Numeric cell-type tag exposed by host cells. The engine compares
+ * against `Null`, `Merge`, and `Formula`; any other value is treated as
+ * a scalar literal.
+ *
+ * `Merge` identifies a non-master cell inside a merged region. The
+ * host's in-memory model may proxy `cell.value` from slaves to the
+ * master (see `MergeValue` in `@excel/cell`), so the snapshot builder
+ * must filter merge slaves out — otherwise range aggregates count the
+ * master's value once per slave. See issue #162.
  *
  * Kept as inline numeric literals (not an enum) so this file stays free
  * of runtime dependencies. The `const` object and `type` alias share a
  * name via TypeScript's declaration merging — the value form
  * (`CellValueTypeLike.Null`, `CellValueTypeLike.Formula`) is used at
  * comparison sites, the type form annotates `CellLike.type`.
+ *
+ * The numeric values must stay in sync with `ValueType` in
+ * `@excel/enums`, which is what `@excel/cell` writes into `cell.type`.
  */
 export declare const CellValueTypeLike: {
     readonly Null: 0;
+    readonly Merge: 1;
     readonly Formula: 6;
 };
 export type CellValueTypeLike = number;
@@ -118,6 +128,12 @@ export interface WorksheetLike {
     findCell(row: number, col: number): CellLike | undefined;
     getCell(row: number, col: number): CellLike;
     getTables?(): TableRefLike[];
+    /**
+     * Read-only enumeration of the worksheet's merged regions (1-based,
+     * inclusive). Optional for hosts that don't model merge state — the
+     * snapshot builder treats absence as "no merges".
+     */
+    readonly mergedRegions?: readonly DimensionsLike[];
 }
 /**
  * A complete defined name entry with all details.

package/dist/browser/modules/formula/materialize/types.js

@@ -13,17 +13,27 @@
 // ValueType — numeric mirror of `@excel/enums` ValueType
 // ============================================================================
 /**
- * Numeric cell-type tag exposed by host cells. The engine only compares
- * against `Null` and `Formula`; any other value is treated as a scalar
- * literal.
+ * Numeric cell-type tag exposed by host cells. The engine compares
+ * against `Null`, `Merge`, and `Formula`; any other value is treated as
+ * a scalar literal.
+ *
+ * `Merge` identifies a non-master cell inside a merged region. The
+ * host's in-memory model may proxy `cell.value` from slaves to the
+ * master (see `MergeValue` in `@excel/cell`), so the snapshot builder
+ * must filter merge slaves out — otherwise range aggregates count the
+ * master's value once per slave. See issue #162.
  *
  * Kept as inline numeric literals (not an enum) so this file stays free
  * of runtime dependencies. The `const` object and `type` alias share a
  * name via TypeScript's declaration merging — the value form
  * (`CellValueTypeLike.Null`, `CellValueTypeLike.Formula`) is used at
  * comparison sites, the type form annotates `CellLike.type`.
+ *
+ * The numeric values must stay in sync with `ValueType` in
+ * `@excel/enums`, which is what `@excel/cell` writes into `cell.type`.
  */
 export const CellValueTypeLike = {
     Null: 0,
+    Merge: 1,
     Formula: 6
 };

package/dist/browser/modules/pdf/builder/document-builder.js

@@ -24,7 +24,7 @@ import { PdfContentStream } from "../core/pdf-stream.js";
 import { PdfWriter } from "../core/pdf-writer.js";
 import { writePdfAMetadata, writePdfAOutputIntent } from "../core/pdfa.js";
 import { FontManager } from "../font/font-manager.js";
-import { discoverSystemFontCandidates } from "../font/system-fonts.js";
+import { iterateSystemFontCandidates } from "../font/system-fonts.js";
 import { parseTtf } from "../font/ttf-parser.js";
 import { wrapTextLines, emitTextWithMatrix, alphaGsName } from "../render/page-renderer.js";
 import { writeImageXObject } from "./image-utils.js";
@@ -839,7 +839,7 @@ export class PdfDocumentBuilder {
             if (nonWinAnsi.size > 0) {
                 // Try auto-discovery unless the caller opted out.
                 if (!this._disableFontAutoDiscovery) {
-                    for (const candidate of discoverSystemFontCandidates()) {
+                    for (const candidate of iterateSystemFontCandidates()) {
                         try {
                             const testTtf = parseTtf(candidate);
                             const allCovered = [...nonWinAnsi].every(cp => testTtf.cmap.has(cp));

package/dist/browser/modules/pdf/font/system-fonts.d.ts

@@ -11,23 +11,43 @@
  * .ttc (TrueType Collection) files are supported — parseTtf() extracts
  * the first font from the collection automatically.
  *
- * Results are cached: the filesystem search runs only once per process.
+ * Discovery is exposed both as a generator
+ * ({@link iterateSystemFontCandidates}) for early-exit callers and as
+ * an array snapshot ({@link discoverSystemFontCandidates}) for tests
+ * and full enumeration. Once the full snapshot has been produced it is
+ * cached and replayed on subsequent calls; partial iterations rely on
+ * the OS page cache to make repeat reads of the same font files cheap.
  */
+/**
+ * Lazily yield discoverable system font candidates, in preference order.
+ *
+ * Each entry is the raw font file bytes of a `.ttf` or `.ttc` file.
+ * The caller decides which candidate to use (e.g. by checking cmap coverage).
+ *
+ * Iterating one candidate at a time lets callers `break` as soon as
+ * they find a match, avoiding the cost of recursively reading every
+ * font in every system font directory just to discard them.
+ */
+export declare function iterateSystemFontCandidates(): Generator<Uint8Array, void, void>;
 /**
  * Return all discoverable system font candidates, ordered by preference.
  *
  * Each entry is the raw font file bytes of a `.ttf` or `.ttc` file.
  * The caller decides which candidate to use (e.g. by checking cmap coverage).
  *
- * Results are cached — the filesystem scan runs only once per process.
+ * The full snapshot is cached: once produced, repeated calls return the
+ * same array without touching the filesystem.
+ *
+ * Prefer {@link iterateSystemFontCandidates} when you only need the
+ * first candidate that satisfies a predicate: it avoids reading every
+ * font in every system directory just to discard them.
  */
 export declare function discoverSystemFontCandidates(): Uint8Array[];
 /**
  * Search for a system font suitable for Unicode rendering.
  *
  * Returns the raw font file bytes of the highest-priority candidate,
- * or `null` if no font was found. This is a convenience wrapper around
- * {@link discoverSystemFontCandidates}.
+ * or `null` if no font was found.
  */
 export declare function discoverSystemFont(): Uint8Array | null;
 /**

package/dist/browser/modules/pdf/font/system-fonts.js

@@ -11,7 +11,12 @@
  * .ttc (TrueType Collection) files are supported — parseTtf() extracts
  * the first font from the collection automatically.
  *
- * Results are cached: the filesystem search runs only once per process.
+ * Discovery is exposed both as a generator
+ * ({@link iterateSystemFontCandidates}) for early-exit callers and as
+ * an array snapshot ({@link discoverSystemFontCandidates}) for tests
+ * and full enumeration. Once the full snapshot has been produced it is
+ * cached and replayed on subsequent calls; partial iterations rely on
+ * the OS page cache to make repeat reads of the same font files cheap.
  */
 import { fileExistsSync, readFileBytesSync, traverseDirectorySync } from "../../../utils/fs.browser.js";
 // =============================================================================
@@ -88,75 +93,114 @@ const PREFERRED_FONTS = [
 // =============================================================================
 // Font Discovery
 // =============================================================================
+// Cached, fully-populated candidate list. Set when the generator runs
+// to completion via `discoverSystemFontCandidates()`, or when a test
+// injects candidates via `_setCandidatesForTest`. Partial iterations
+// (where the caller `break`s after a match) intentionally do not
+// populate this cache — they rely on the OS page cache to keep repeat
+// reads cheap.
 let _cachedCandidates;
 /**
- * Return all discoverable system font candidates, ordered by preference.
+ * Lazily yield discoverable system font candidates, in preference order.
  *
  * Each entry is the raw font file bytes of a `.ttf` or `.ttc` file.
  * The caller decides which candidate to use (e.g. by checking cmap coverage).
  *
- * Results are cached — the filesystem scan runs only once per process.
+ * Iterating one candidate at a time lets callers `break` as soon as
+ * they find a match, avoiding the cost of recursively reading every
+ * font in every system font directory just to discard them.
  */
-export function discoverSystemFontCandidates() {
+export function* iterateSystemFontCandidates() {
+    // Fast path: a previous call already produced the full snapshot.
     if (_cachedCandidates !== undefined) {
-        return _cachedCandidates;
+        for (const c of _cachedCandidates) {
+            yield c;
+        }
+        return;
     }
     if (typeof process === "undefined" || !process.platform) {
-        _cachedCandidates = [];
-        return _cachedCandidates;
+        return;
     }
-    const candidates = [];
-    const seen = new Set(); // dedupe by path
+    const seen = new Set(); // dedupe by path within this iteration
     const dirs = getSystemFontDirs();
-    // Strategy 1: Check preferred font filenames (in order)
+    // Strategy 1: Check preferred font filenames (in order). These stat
+    // calls are cheap and run regardless — they are the only path most
+    // callers need to traverse.
     for (const fontName of PREFERRED_FONTS) {
         for (const dir of dirs) {
             const fontPath = `${dir}/${fontName}`;
             if (seen.has(fontPath)) {
                 continue;
             }
+            seen.add(fontPath);
             if (fileExistsSync(fontPath)) {
                 const data = tryReadFont(fontPath);
                 if (data) {
-                    candidates.push(data);
-                    seen.add(fontPath);
+                    yield data;
                 }
             }
         }
     }
-    // Strategy 2: Scan directories for any .ttf/.ttc not already found
+    // Strategy 2: Recursively scan each directory for any other .ttf/.ttc.
+    // This is the expensive step (hundreds of MB on macOS / Windows), so
+    // it walks one directory at a time and yields candidates as it goes —
+    // a caller that found a match in Strategy 1 (or in an earlier
+    // directory here) never reaches further directories.
     const broadRe = /noto|unicode|cjk|yahei|heiti|gothic|sans|serif|ming|song|dejavu|liberation|droid|wqy/i;
     for (const dir of dirs) {
+        let entries;
         try {
-            const entries = traverseDirectorySync(dir, { recursive: true, filter: e => !e.isDirectory });
-            const fonts = entries.filter(e => /\.tt[cf]$/i.test(e.absolutePath) && !seen.has(e.absolutePath));
-            // Broad-coverage names first, then large files
-            const broad = fonts.filter(e => broadRe.test(e.absolutePath));
-            const rest = fonts.filter(e => !broadRe.test(e.absolutePath) && e.size > 50000);
-            for (const entry of [...broad, ...rest]) {
-                if (seen.has(entry.absolutePath)) {
-                    continue;
-                }
-                const data = tryReadFont(entry.absolutePath);
-                if (data) {
-                    candidates.push(data);
-                    seen.add(entry.absolutePath);
-                }
-            }
+            entries = traverseDirectorySync(dir, { recursive: true, filter: e => !e.isDirectory });
         }
         catch {
             // Directory doesn't exist or not readable
+            continue;
+        }
+        const fonts = entries.filter(e => /\.tt[cf]$/i.test(e.absolutePath) && !seen.has(e.absolutePath));
+        // Broad-coverage names first, then large files
+        const broad = fonts.filter(e => broadRe.test(e.absolutePath));
+        const rest = fonts.filter(e => !broadRe.test(e.absolutePath) && e.size > 50000);
+        for (const entry of [...broad, ...rest]) {
+            if (seen.has(entry.absolutePath)) {
+                continue;
+            }
+            seen.add(entry.absolutePath);
+            const data = tryReadFont(entry.absolutePath);
+            if (data) {
+                yield data;
+            }
         }
     }
-    _cachedCandidates = candidates;
-    return candidates;
+}
+/**
+ * Return all discoverable system font candidates, ordered by preference.
+ *
+ * Each entry is the raw font file bytes of a `.ttf` or `.ttc` file.
+ * The caller decides which candidate to use (e.g. by checking cmap coverage).
+ *
+ * The full snapshot is cached: once produced, repeated calls return the
+ * same array without touching the filesystem.
+ *
+ * Prefer {@link iterateSystemFontCandidates} when you only need the
+ * first candidate that satisfies a predicate: it avoids reading every
+ * font in every system directory just to discard them.
+ */
+export function discoverSystemFontCandidates() {
+    if (_cachedCandidates !== undefined) {
+        return _cachedCandidates;
+    }
+    const all = [];
+    for (const candidate of iterateSystemFontCandidates()) {
+        all.push(candidate);
+    }
+    _cachedCandidates = all;
+    return all;
 }
 /**
  * Search for a system font suitable for Unicode rendering.
  *
  * Returns the raw font file bytes of the highest-priority candidate,
- * or `null` if no font was found. This is a convenience wrapper around
- * {@link discoverSystemFontCandidates}.
+ * or `null` if no font was found.
  */
 export function discoverSystemFont() {
     const candidates = discoverSystemFontCandidates();

package/dist/browser/modules/pdf/render/pdf-exporter.js

@@ -15,7 +15,7 @@ import { PdfContentStream, isWinAnsiCodePoint } from "../core/pdf-stream.js";
 import { PdfWriter } from "../core/pdf-writer.js";
 import { PdfError, PdfRenderError } from "../errors.js";
 import { FontManager, resolvePdfFontName } from "../font/font-manager.js";
-import { discoverSystemFontCandidates } from "../font/system-fonts.js";
+import { iterateSystemFontCandidates } from "../font/system-fonts.js";
 import { parseTtf } from "../font/ttf-parser.js";
 import { PageSizes, PdfCellType, isPdfChartsheet } from "../types.js";
 import { createChartSurface } from "./chart-surface.js";
@@ -58,8 +58,11 @@ function prepareExport(workbook, options) {
         // Collect non-WinAnsi code points from the document (single pass)
         const nonWinAnsi = collectNonWinAnsiCodePoints(sheets);
         if (nonWinAnsi.size > 0) {
-            // Try system font candidates in preference order until one covers all chars
-            for (const candidate of discoverSystemFontCandidates()) {
+            // Try system font candidates lazily in preference order until one
+            // covers all chars. Iterating instead of materializing the full
+            // candidate list lets us stop the moment a match is found, which
+            // avoids the cost of recursively scanning every system font dir.
+            for (const candidate of iterateSystemFontCandidates()) {
                 try {
                     const testTtf = parseTtf(candidate);
                     const allCovered = [...nonWinAnsi].every(cp => testTtf.cmap.has(cp));