@rowsncolumns/toolkit 24.5.17 → 24.5.19

package/dist/esm/excel-parser/plugins/xlsb/rgce-parser.js

@@ -1,522 +1,455 @@
 import { number2Alpha } from "@rowsncolumns/utils";
+import { FTAB, FTAB_FIXED_ARGC } from "./function-table";
 /**
- * Reader class for parsing Rgce bytes
+ * Decoder for a BIFF12 formula's token stream (`rgce`, [MS-XLSB] 2.2.2 / 2.5.97.88):
+ * reverse-Polish tokens rebuilt into the formula's text.
+ *
+ * Strict by design: a formula decodes completely or not at all. A token it
+ * does not know, a function outside the table, a read past the end of the
+ * stream or a stack that does not end with exactly one expression throws
+ * {@link RgceUnsupportedError}, and the caller keeps the cell's cached value
+ * instead of writing a formula that computes something else.
  */
-class RgceReader {
-    view;
-    offset = 0;
+/** The formula cannot be decoded exactly; keep the cell's cached value. */
+export class RgceUnsupportedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RgceUnsupportedError";
+    }
+}
+const MAX_ROW_INDEX = 0xfffff; // 1,048,575: row 1,048,576
+const MAX_COL_INDEX = 0x3fff; // 16,383: column XFD
+const ERROR_CODES = {
+    0x00: "#NULL!",
+    0x07: "#DIV/0!",
+    0x0f: "#VALUE!",
+    0x17: "#REF!",
+    0x1d: "#NAME?",
+    0x24: "#NUM!",
+    0x2a: "#N/A",
+    0x2b: "#GETTING_DATA",
+};
+const BINARY_OPERATORS = {
+    0x03: "+",
+    0x04: "-",
+    0x05: "*",
+    0x06: "/",
+    0x07: "^",
+    0x08: "&",
+    0x09: "<",
+    0x0a: "<=",
+    0x0b: "=",
+    0x0c: ">=",
+    0x0d: ">",
+    0x0e: "<>",
+    0x0f: " ",
+    0x10: ",",
+    0x11: ":",
+};
+/** `PtgAttr` kinds that only steer evaluation or carry whitespace: no stack effect. */
+const ATTR_NO_EFFECT = new Set([0x01, 0x02, 0x08, 0x20, 0x21, 0x40, 0x41]);
+const ATTR_CHOOSE = 0x04;
+const PTG_UNION = 0x10;
+const ATTR_SUM = 0x10;
+class Reader {
     bytes;
+    offset = 0;
+    view;
     constructor(bytes) {
         this.bytes = bytes;
         this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
     }
-    readUInt8() {
-        const value = this.view.getUint8(this.offset);
-        this.offset += 1;
-        return value;
+    get done() {
+        return this.offset >= this.bytes.length;
     }
-    readUInt16LE() {
-        const value = this.view.getUint16(this.offset, true);
-        this.offset += 2;
-        return value;
+    take(count) {
+        if (this.offset + count > this.bytes.length) {
+            throw new RgceUnsupportedError("token runs past the end of the formula");
+        }
+        const at = this.offset;
+        this.offset += count;
+        return at;
     }
-    readUInt32LE() {
-        const value = this.view.getUint32(this.offset, true);
-        this.offset += 4;
-        return value;
+    u8() {
+        return this.view.getUint8(this.take(1));
     }
-    readInt32LE() {
-        const value = this.view.getInt32(this.offset, true);
-        this.offset += 4;
-        return value;
+    u16() {
+        return this.view.getUint16(this.take(2), true);
     }
-    readInt16LE() {
-        const value = this.view.getInt16(this.offset, true);
-        this.offset += 2;
-        return value;
+    i16() {
+        return this.view.getInt16(this.take(2), true);
     }
-    readFloat64LE() {
-        const value = this.view.getFloat64(this.offset, true);
-        this.offset += 8;
-        return value;
+    u32() {
+        return this.view.getUint32(this.take(4), true);
     }
-    readUtf16Chars(charCount) {
-        if (charCount <= 0)
-            return "";
-        const byteCount = charCount * 2;
-        const slice = this.bytes.subarray(this.offset, this.offset + byteCount);
-        this.offset += byteCount;
-        return new TextDecoder("utf-16le").decode(slice);
+    i32() {
+        return this.view.getInt32(this.take(4), true);
     }
-    readXLWideString() {
-        const cch = this.readUInt32LE();
-        return cch === 0 ? "" : this.readUtf16Chars(cch);
+    f64() {
+        return this.view.getFloat64(this.take(8), true);
+    }
+    skip(count) {
+        this.take(count);
+    }
+    utf16(chars) {
+        const at = this.take(chars * 2);
+        return new TextDecoder("utf-16le").decode(this.bytes.subarray(at, at + chars * 2));
     }
 }
-// Common Excel function names by ID (ftab index)
-const FUNCTION_NAMES = {
-    0: "COUNT", 1: "IF", 2: "ISNA", 3: "ISERROR", 4: "SUM", 5: "AVERAGE",
-    6: "MIN", 7: "MAX", 8: "ROW", 9: "COLUMN", 10: "NA", 11: "NPV",
-    12: "STDEV", 13: "DOLLAR", 14: "FIXED", 15: "SIN", 16: "COS",
-    17: "TAN", 18: "ATAN", 19: "PI", 20: "SQRT", 21: "EXP", 22: "LN",
-    23: "LOG10", 24: "ABS", 25: "INT", 26: "SIGN", 27: "ROUND",
-    28: "LOOKUP", 29: "INDEX", 30: "REPT", 31: "MID", 32: "LEN",
-    33: "VALUE", 34: "TRUE", 35: "FALSE", 36: "AND", 37: "OR",
-    38: "NOT", 39: "MOD", 40: "DCOUNT", 41: "DSUM", 42: "DAVERAGE",
-    43: "DMIN", 44: "DMAX", 45: "DSTDEV", 46: "VAR", 47: "DVAR",
-    48: "TEXT", 49: "LINEST", 50: "TREND", 51: "LOGEST", 52: "GROWTH",
-    61: "MIRR", 62: "IRR", 63: "RAND", 64: "MATCH", 65: "DATE",
-    66: "TIME", 67: "DAY", 68: "MONTH", 69: "YEAR", 70: "WEEKDAY",
-    71: "HOUR", 72: "MINUTE", 73: "SECOND", 74: "NOW", 75: "AREAS",
-    76: "ROWS", 77: "COLUMNS", 78: "OFFSET", 82: "SEARCH", 83: "TRANSPOSE",
-    86: "TYPE", 97: "ATAN2", 98: "ASIN", 99: "ACOS", 100: "CHOOSE",
-    101: "HLOOKUP", 102: "VLOOKUP", 103: "ISREF", 104: "LOG",
-    105: "CHAR", 106: "LOWER", 107: "UPPER", 108: "PROPER", 109: "LEFT",
-    110: "RIGHT", 111: "EXACT", 112: "TRIM", 113: "REPLACE", 114: "SUBSTITUTE",
-    115: "CODE", 116: "NAMES", 117: "DIRECTORY", 118: "FIND", 119: "CELL",
-    120: "ISERR", 121: "ISTEXT", 122: "ISNUMBER", 123: "ISBLANK",
-    124: "T", 125: "N", 127: "ISNONTEXT", 128: "ISODD", 129: "ISEVEN",
-    162: "CLEAN", 163: "MDETERM", 164: "MINVERSE", 165: "MMULT",
-    167: "IPMT", 168: "PPMT", 169: "COUNTA", 183: "PRODUCT",
-    184: "FACT", 189: "DPRODUCT", 190: "ISNONTEXT",
-    193: "STDEVP", 194: "VARP", 195: "DSTDEVP", 196: "DVARP",
-    197: "TRUNC", 198: "ISLOGICAL", 199: "DCOUNTA", 200: "DELETEBAR",
-    216: "RANK", 219: "ADDRESS", 220: "DAYS360", 221: "TODAY",
-    222: "VDB", 227: "MEDIAN", 228: "SUMPRODUCT", 229: "SINH",
-    230: "COSH", 231: "TANH", 232: "ASINH", 233: "ACOSH", 234: "ATANH",
-    235: "DGET", 244: "INFO", 247: "DB", 252: "FREQUENCY",
-    261: "ERROR.TYPE", 269: "AVEDEV", 270: "BETADIST", 271: "GAMMALN",
-    272: "BETAINV", 273: "BINOMDIST", 274: "CHIDIST", 275: "CHIINV",
-    276: "COMBIN", 277: "CONFIDENCE", 278: "CRITBINOM", 279: "EVEN",
-    280: "EXPONDIST", 281: "FDIST", 282: "FINV", 283: "FISHER",
-    284: "FISHERINV", 285: "FLOOR", 286: "GAMMADIST", 287: "GAMMAINV",
-    288: "CEILING", 289: "HYPGEOMDIST", 290: "LOGNORMDIST", 291: "LOGINV",
-    292: "NEGBINOMDIST", 293: "NORMDIST", 294: "NORMSDIST", 295: "NORMINV",
-    296: "NORMSINV", 297: "STANDARDIZE", 298: "ODD", 299: "PERMUT",
-    300: "POISSON", 301: "TDIST", 302: "WEIBULL", 303: "SUMXMY2",
-    304: "SUMX2MY2", 305: "SUMX2PY2", 306: "CHITEST", 307: "CORREL",
-    308: "COVAR", 309: "FORECAST", 310: "FTEST", 311: "INTERCEPT",
-    312: "PEARSON", 313: "RSQ", 314: "STEYX", 315: "SLOPE", 316: "TTEST",
-    317: "PROB", 318: "DEVSQ", 319: "GEOMEAN", 320: "HARMEAN",
-    321: "SUMSQ", 322: "KURT", 323: "SKEW", 324: "ZTEST", 325: "LARGE",
-    326: "SMALL", 327: "QUARTILE", 328: "PERCENTILE", 329: "PERCENTRANK",
-    330: "MODE", 331: "TRIMMEAN", 332: "TINV", 334: "CONCATENATE",
-    335: "POWER", 336: "RADIANS", 337: "DEGREES", 338: "SUBTOTAL",
-    339: "SUMIF", 340: "COUNTIF", 341: "COUNTBLANK", 342: "HYPERLINK",
-    343: "PHONETIC", 344: "AVERAGEA", 345: "MAXA", 346: "MINA",
-    347: "STDEVPA", 348: "VARPA", 349: "STDEVA", 350: "VARA",
-};
 /**
- * Parse Rgce (Reverse Polish Notation Compiled Expression) - binary formula format in XLSB
- * This converts binary Ptg (Parsed Token) tokens into a formula string
- *
- * @param rgceBytes - The binary formula data
- * @returns The formula string (without leading "=")
+ * A sheet name as a reference prefix: quoted unless it is a plain ASCII
+ * identifier no reader could take for a cell (`A1`, `R1C1`, `R`) or a
+ * boolean. Quoting is always valid, so anything else is quoted.
  */
+export const quoteSheetName = (name) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) &&
+    !/^[A-Za-z]{1,3}\d+$/.test(name) &&
+    !/^(?:[Rr]\d*)?(?:[Cc]\d*)?$/.test(name) &&
+    !/^(?:TRUE|FALSE)$/i.test(name)
+    ? name
+    : `'${name.replace(/'/g, "''")}'`;
+const formatNumber = (value) => {
+    if (!Number.isFinite(value)) {
+        throw new RgceUnsupportedError("non-finite number constant");
+    }
+    return String(value).replace("e", "E");
+};
+const cellRef = (row, col, rowRelative, colRelative) => `${colRelative ? "" : "$"}${number2Alpha(col)}${rowRelative ? "" : "$"}${row + 1}`;
+/** An area, written the way Excel writes whole columns (`A:B`) and whole rows (`1:2`). */
+const areaRef = (first, last) => {
+    if (first.row === 0 && last.row === MAX_ROW_INDEX) {
+        return `${first.colRelative ? "" : "$"}${number2Alpha(first.col)}:${last.colRelative ? "" : "$"}${number2Alpha(last.col)}`;
+    }
+    if (first.col === 0 && last.col === MAX_COL_INDEX) {
+        return `${first.rowRelative ? "" : "$"}${first.row + 1}:${last.rowRelative ? "" : "$"}${last.row + 1}`;
+    }
+    return `${cellRef(first.row, first.col, first.rowRelative, first.colRelative)}:${cellRef(last.row, last.col, last.rowRelative, last.colRelative)}`;
+};
+/** `RgceLoc` / `RgceArea` corner: a 20-bit row (u32) and a 14-bit column with its relative flags (u16). */
+const corner = (row, colField) => ({
+    row: row & MAX_ROW_INDEX,
+    col: colField & MAX_COL_INDEX,
+    rowRelative: (colField & 0x8000) !== 0,
+    colRelative: (colField & 0x4000) !== 0,
+});
+/** A `RgceLocRel` corner of a shared formula or name: relative parts are offsets from the base cell. */
+const relativeCorner = (rowField, colField, base) => {
+    const rowRelative = (colField & 0x8000) !== 0;
+    const colRelative = (colField & 0x4000) !== 0;
+    if ((rowRelative || colRelative) && !base) {
+        throw new RgceUnsupportedError("relative reference without a base cell");
+    }
+    const baseRow = (base?.row ?? 1) - 1;
+    const baseCol = (base?.col ?? 1) - 1;
+    // A relative column is a signed 14-bit offset; a relative row a signed 32-bit one.
+    const colOffset = ((colField & MAX_COL_INDEX) << 18) >> 18;
+    const row = rowRelative ? baseRow + rowField : rowField;
+    const col = colRelative ? baseCol + colOffset : colField & MAX_COL_INDEX;
+    // Offsets wrap around the sheet, as Excel's do.
+    return {
+        row: ((row % (MAX_ROW_INDEX + 1)) + MAX_ROW_INDEX + 1) % (MAX_ROW_INDEX + 1),
+        col: ((col % (MAX_COL_INDEX + 1)) + MAX_COL_INDEX + 1) % (MAX_COL_INDEX + 1),
+        rowRelative,
+        colRelative,
+    };
+};
 /**
- * Parse Rgce with sheet names for cross-sheet references
- * @param rgceBytes - The binary formula data
- * @param sheetNames - Array of sheet names for resolving external references
- * @returns The formula string (without leading "=")
+ * Decode a formula's tokens into its text, without the leading `=`.
+ *
+ * Throws {@link RgceUnsupportedError} when any part of the formula cannot be
+ * decoded exactly.
  */
-export function parseRgce(rgceBytes, sheetRefResolver, baseCell, debug = false) {
-    if (!rgceBytes || rgceBytes.length === 0)
-        return "";
-    const reader = new RgceReader(rgceBytes);
-    const stack = [];
-    if (debug) {
-        console.log("[Rgce] Parsing", rgceBytes.length, "bytes:", Array.from(rgceBytes.slice(0, Math.min(30, rgceBytes.length)))
-            .map(b => `0x${b.toString(16).padStart(2, '0')}`)
-            .join(' '));
+export function decodeRgce(rgce, context = {}) {
+    if (rgce.length === 0) {
+        throw new RgceUnsupportedError("empty formula");
     }
-    const fixedArgCounts = {
-        15: 1, // SIN
-        16: 1, // COS
-        17: 1, // TAN
-        19: 0, // PI
-        20: 1, // SQRT
-        21: 1, // EXP
-        22: 1, // LN
-        24: 1, // ABS
-        25: 1, // INT
-        27: 2, // ROUND
-        31: 3, // MID
-        32: 1, // LEN
-        34: 0, // TRUE
-        35: 0, // FALSE
-        39: 2, // MOD
-        65: 3, // DATE
-        66: 3, // TIME
-        67: 1, // DAY
-        68: 1, // MONTH
-        69: 1, // YEAR
-        71: 1, // HOUR
-        72: 1, // MINUTE
-        73: 1, // SECOND
-        74: 0, // NOW
-        105: 1, // CHAR
-        106: 1, // LOWER
-        107: 1, // UPPER
-        109: 2, // LEFT
-        110: 2, // RIGHT
-        111: 2, // EXACT
-        112: 1, // TRIM
-        115: 1, // CODE
-        183: 1, // PRODUCT
-        197: 2, // TRUNC
-        221: 0, // TODAY
-        335: 2, // POWER
-        336: 1, // RADIANS
-        337: 1, // DEGREES
-    };
-    const canRead = (n) => reader.offset + n <= rgceBytes.length;
-    const quoteSheetName = (name) => /[\s!'[\]]/.test(name) ? `'${name.replace(/'/g, "''")}'` : name;
-    const resolveSheetName = (ixti) => {
-        if (typeof sheetRefResolver === "function") {
-            return sheetRefResolver(ixti);
+    const reader = new Reader(rgce);
+    const stack = [];
+    // Stack slots holding a union without its parentheses: fine as a whole
+    // formula (`A1,C3`), but an argument must say it is one (`SUM((A1,C3))`).
+    const bareUnions = new Set();
+    const pop = () => {
+        const value = stack.pop();
+        if (value === undefined) {
+            throw new RgceUnsupportedError("operator without an operand");
         }
-        return sheetRefResolver?.[ixti];
+        bareUnions.delete(stack.length);
+        return value;
     };
     const popArgs = (count) => {
-        const args = [];
-        for (let i = 0; i < count; i++)
-            args.unshift(stack.pop() || "");
-        return args;
-    };
-    const pushFixedFunction = (ftabIndex) => {
-        const funcName = FUNCTION_NAMES[ftabIndex] || `FUNC${ftabIndex}`;
-        const cargs = fixedArgCounts[ftabIndex] ?? 0;
-        stack.push(`${funcName}(${popArgs(cargs).join(",")})`);
-    };
-    const pushVariableFunction = (cargs, ftabIndex) => {
-        const funcName = FUNCTION_NAMES[ftabIndex] || `FUNC${ftabIndex}`;
-        stack.push(`${funcName}(${popArgs(cargs).join(",")})`);
-    };
-    const formatRef = (rowZero, colZero, rowRel, colRel) => {
-        const row = Math.max(0, rowZero);
-        const col = Math.max(0, colZero);
-        return `${colRel ? "" : "$"}${number2Alpha(col)}${rowRel ? "" : "$"}${row + 1}`;
-    };
-    const readShortRef = () => {
-        const row = reader.readUInt32LE();
-        const col = reader.readUInt16LE();
-        const rowRel = (col & 0x8000) !== 0;
-        const colRel = (col & 0x4000) !== 0;
-        return formatRef(row & 0x000fffff, col & 0x3fff, rowRel, colRel);
-    };
-    const readShortArea = () => {
-        const rowFirst = reader.readUInt32LE();
-        const rowLast = reader.readUInt32LE();
-        const colFirst = reader.readUInt16LE();
-        const colLast = reader.readUInt16LE();
-        const refFirst = formatRef(rowFirst & 0x000fffff, colFirst & 0x3fff, (colFirst & 0x8000) !== 0, (colFirst & 0x4000) !== 0);
-        const refLast = formatRef(rowLast & 0x000fffff, colLast & 0x3fff, (colLast & 0x8000) !== 0, (colLast & 0x4000) !== 0);
-        return `${refFirst}:${refLast}`;
+        if (count > stack.length) {
+            throw new RgceUnsupportedError("function without all its arguments");
+        }
+        const first = stack.length - count;
+        return stack.splice(first, count).map((arg, at) => {
+            const isBareUnion = bareUnions.delete(first + at);
+            return isBareUnion ? `(${arg})` : arg;
+        });
     };
-    const readRelShortRef = () => {
-        const rowOffset = reader.readInt32LE();
-        const colRaw = reader.readInt16LE();
-        const colOffset14 = colRaw & 0x3fff;
-        const colOffset = (colOffset14 << 18) >> 18;
-        const baseRowZero = Math.max(0, (baseCell?.row ?? 1) - 1);
-        const baseColZero = Math.max(0, (baseCell?.col ?? 1) - 1);
-        return formatRef(baseRowZero + rowOffset, baseColZero + colOffset, true, true);
+    const sheet = (ixti) => {
+        const name = context.sheetName?.(ixti);
+        if (name === undefined) {
+            throw new RgceUnsupportedError(`unknown sheet reference ${ixti}`);
+        }
+        return quoteSheetName(name);
     };
-    const readRelShortArea = () => {
-        const rowFirstOffset = reader.readInt32LE();
-        const rowLastOffset = reader.readInt32LE();
-        const colFirstRaw = reader.readInt16LE();
-        const colLastRaw = reader.readInt16LE();
-        const colFirstOffset = ((colFirstRaw & 0x3fff) << 18) >> 18;
-        const colLastOffset = ((colLastRaw & 0x3fff) << 18) >> 18;
-        const baseRowZero = Math.max(0, (baseCell?.row ?? 1) - 1);
-        const baseColZero = Math.max(0, (baseCell?.col ?? 1) - 1);
-        const refFirst = formatRef(baseRowZero + rowFirstOffset, baseColZero + colFirstOffset, true, true);
-        const refLast = formatRef(baseRowZero + rowLastOffset, baseColZero + colLastOffset, true, true);
-        return `${refFirst}:${refLast}`;
+    const callFunction = (iftab, args) => {
+        const name = FTAB[iftab];
+        if (!name) {
+            throw new RgceUnsupportedError(`unknown function ${iftab}`);
+        }
+        return `${name}(${args.join(",")})`;
     };
-    try {
-        while (reader.offset < rgceBytes.length) {
-            const ptgOffset = reader.offset;
-            const ptg = reader.readUInt8();
-            if (debug) {
-                console.log(`[Rgce] @${ptgOffset}: ptg=0x${ptg.toString(16).padStart(2, '0')} stack=[${stack.join(', ')}]`);
-            }
-            // Handle token based on value
-            // Operators are 0x00-0x1f (no class bits)
-            // References/functions are 0x20-0x7f (have class bits in bits 5-6)
-            if (ptg === 0x03) {
-                // PtgAdd
-                const right = stack.pop() || "0";
-                const left = stack.pop() || "0";
-                stack.push(`${left}+${right}`);
-            }
-            else if (ptg === 0x04) {
-                // PtgSub - subtraction operator
-                const right = stack.pop() || "0";
-                const left = stack.pop() || "0";
-                stack.push(`${left}-${right}`);
-            }
-            else if (ptg === 0x05) {
-                // PtgMul - multiplication operator
-                const right = stack.pop() || "0";
-                const left = stack.pop() || "0";
-                stack.push(`${left}*${right}`);
-            }
-            else if (ptg === 0x06) {
-                // PtgDiv
-                const right = stack.pop() || "0";
-                const left = stack.pop() || "0";
-                stack.push(`${left}/${right}`);
-            }
-            else if (ptg === 0x07) {
-                // PtgPower
-                const right = stack.pop() || "0";
-                const left = stack.pop() || "0";
-                stack.push(`${left}^${right}`);
-            }
-            else if (ptg === 0x08) {
-                // PtgConcat
-                const right = stack.pop() || '""';
-                const left = stack.pop() || '""';
-                stack.push(`${left}&${right}`);
-            }
-            else if (ptg === 0x09) {
-                // PtgLT
-                const right = stack.pop() || "0";
-                const left = stack.pop() || "0";
-                stack.push(`${left}<${right}`);
-            }
-            else if (ptg === 0x0a) {
-                // PtgLE
-                const right = stack.pop() || "0";
-                const left = stack.pop() || "0";
-                stack.push(`${left}<=${right}`);
-            }
-            else if (ptg === 0x0b) {
-                // PtgEQ
-                const right = stack.pop() || "0";
-                const left = stack.pop() || "0";
-                stack.push(`${left}=${right}`);
-            }
-            else if (ptg === 0x0c) {
-                // PtgGE
-                const right = stack.pop() || "0";
-                const left = stack.pop() || "0";
-                stack.push(`${left}>=${right}`);
-            }
-            else if (ptg === 0x0d) {
-                // PtgGT
-                const right = stack.pop() || "0";
-                const left = stack.pop() || "0";
-                stack.push(`${left}>${right}`);
-            }
-            else if (ptg === 0x0e) {
-                // PtgNE
-                const right = stack.pop() || "0";
-                const left = stack.pop() || "0";
-                stack.push(`${left}<>${right}`);
-            }
-            else if (ptg === 0x12) {
-                // PtgUPlus
-                const operand = stack.pop() || "0";
-                stack.push(`+${operand}`);
-            }
-            else if (ptg === 0x13) {
-                // PtgUMinus
-                const operand = stack.pop() || "0";
-                stack.push(`-${operand}`);
-            }
-            else if (ptg === 0x14) {
-                // PtgPercent
-                const operand = stack.pop() || "0";
-                stack.push(`${operand}%`);
-            }
-            else if (ptg === 0x15) {
-                // PtgParen
-                const operand = stack.pop() || "";
-                stack.push(`(${operand})`);
-            }
-            else if (ptg === 0x16) {
-                // PtgMissArg - missing argument (empty between commas)
+    while (!reader.done) {
+        const ptg = reader.u8();
+        const binary = BINARY_OPERATORS[ptg];
+        if (binary !== undefined) {
+            const right = pop();
+            const left = pop();
+            if (ptg === PTG_UNION)
+                bareUnions.add(stack.length);
+            stack.push(`${left}${binary}${right}`);
+            continue;
+        }
+        switch (ptg) {
+            case 0x12: // PtgUplus
+                stack.push(`+${pop()}`);
+                continue;
+            case 0x13: // PtgUminus
+                stack.push(`-${pop()}`);
+                continue;
+            case 0x14: // PtgPercent
+                stack.push(`${pop()}%`);
+                continue;
+            case 0x15: // PtgParen
+                stack.push(`(${pop()})`);
+                continue;
+            case 0x16: // PtgMissArg
                 stack.push("");
+                continue;
+            case 0x17: {
+                // PtgStr: a 16-bit character count, then UTF-16LE.
+                const text = reader.utf16(reader.u16());
+                stack.push(`"${text.replace(/"/g, '""')}"`);
+                continue;
             }
-            else if (ptg === 0x17) {
-                // PtgStr - string constant
-                const str = reader.readXLWideString();
-                stack.push(`"${str.replace(/"/g, '""')}"`);
-            }
-            else if (ptg === 0x1d) {
-                // PtgBool - boolean constant
-                const value = reader.readUInt8();
-                stack.push(value ? "TRUE" : "FALSE");
-            }
-            else if (ptg === 0x1e) {
-                // PtgInt - integer constant
-                const value = reader.readUInt16LE();
-                stack.push(String(value));
-            }
-            else if (ptg === 0x1f) {
-                // PtgNum - float constant
-                const value = reader.readFloat64LE();
-                stack.push(String(value));
-            }
-            else if (ptg === 0x18) {
-                // PtgErr - error constant
-                if (!canRead(1))
-                    break;
-                const code = reader.readUInt8();
-                const errorValues = {
-                    0x00: "#NULL!",
-                    0x07: "#DIV/0!",
-                    0x0f: "#VALUE!",
-                    0x17: "#REF!",
-                    0x1d: "#NAME?",
-                    0x24: "#NUM!",
-                    0x2a: "#N/A",
-                    0x2b: "#GETTING_DATA",
-                };
-                stack.push(errorValues[code] || "#VALUE!");
-            }
-            else if (ptg === 0x19) {
-                // PtgAttr: 1 byte flags + 2 bytes data
-                if (!canRead(3))
-                    break;
-                const flags = reader.readUInt8();
-                const data = reader.readUInt16LE();
-                // Handle various PtgAttr flags
-                if ((flags & 0x10) !== 0) {
-                    // fSum: treat previous operand as SUM(operand)
-                    const operand = stack.pop() || "";
-                    stack.push(`SUM(${operand})`);
-                }
-                // Note: Other flags (fIf=0x02, fChoose=0x04, fSkip=0x08, fGoto=0x01)
-                // are for control flow and typically don't affect the formula string
-                // They just affect how bytes are skipped during parsing
-            }
-            else if (ptg === 0x01) {
-                // Ambiguous in some XLSB streams:
-                // - PtgExp (4-byte payload)
-                // - PtgFunc ref-class variant (2-byte payload)
-                if (canRead(4)) {
-                    const srcRow = reader.readUInt16LE() + 1;
-                    const srcCol = reader.readUInt16LE() + 1;
-                    stack.push(`__PTGEXP__:${srcRow}:${srcCol}`);
+            case 0x19: {
+                // PtgAttr: a kind byte and 16 bits of data.
+                const kind = reader.u8();
+                const data = reader.u16();
+                if (kind === ATTR_SUM) {
+                    stack.push(`SUM(${popArgs(1)[0]})`);
                 }
-                else if (canRead(2)) {
-                    pushFixedFunction(reader.readUInt16LE());
+                else if (kind === ATTR_CHOOSE) {
+                    reader.skip((data + 1) * 2); // CHOOSE's jump table
                 }
-                else {
-                    break;
-                }
-            }
-            else if (ptg === 0x02) {
-                // PtgFuncVar reference-class variant (0x02)
-                // In practice, 0x02 is PtgFuncVar, not PtgTbl
-                if (canRead(3)) {
-                    const cargs = reader.readUInt8();
-                    pushVariableFunction(cargs, reader.readUInt16LE());
-                }
-                else {
-                    break;
+                else if (!ATTR_NO_EFFECT.has(kind)) {
+                    throw new RgceUnsupportedError(`attribute 0x${kind.toString(16)}`);
                 }
+                continue;
             }
-            else if (ptg === 0x1a || ptg === 0x3a || ptg === 0x5a || ptg === 0x7a) {
-                // PtgRef3d - cross-sheet cell reference
-                if (!canRead(8))
-                    break;
-                const ixti = reader.readUInt16LE(); // External sheet index
-                const cellRef = readShortRef();
-                // Get sheet name if available
-                const sheetName = resolveSheetName(ixti);
-                if (sheetName) {
-                    const quotedName = quoteSheetName(sheetName);
-                    stack.push(`${quotedName}!${cellRef}`);
-                }
-                else {
-                    stack.push(cellRef);
+            case 0x1c: {
+                // PtgErr
+                const text = ERROR_CODES[reader.u8()];
+                if (text === undefined) {
+                    throw new RgceUnsupportedError("unknown error constant");
                 }
+                stack.push(text);
+                continue;
             }
-            else if (ptg === 0x1b || ptg === 0x3b || ptg === 0x5b || ptg === 0x7b) {
-                // PtgArea3d - cross-sheet range reference
-                if (!canRead(14))
-                    break;
-                const ixti = reader.readUInt16LE(); // External sheet index
-                const rangeRef = readShortArea();
-                // Get sheet name if available
-                const sheetName = resolveSheetName(ixti);
-                if (sheetName) {
-                    const quotedName = quoteSheetName(sheetName);
-                    stack.push(`${quotedName}!${rangeRef}`);
-                }
-                else {
-                    stack.push(rangeRef);
+            case 0x1d: // PtgBool
+                stack.push(reader.u8() !== 0 ? "TRUE" : "FALSE");
+                continue;
+            case 0x1e: // PtgInt
+                stack.push(String(reader.u16()));
+                continue;
+            case 0x1f: // PtgNum
+                stack.push(formatNumber(reader.f64()));
+                continue;
+        }
+        // Operand and function tokens carry a value class in bits 5-6.
+        switch (ptg) {
+            case 0x21:
+            case 0x41:
+            case 0x61: {
+                // PtgFunc: a fixed-arity function.
+                const iftab = reader.u16();
+                const argc = FTAB_FIXED_ARGC[iftab];
+                if (argc === undefined || argc < 0) {
+                    throw new RgceUnsupportedError(`function ${iftab} is not fixed-arity`);
                 }
+                stack.push(callFunction(iftab, popArgs(argc)));
+                continue;
             }
-            // References and functions have class bits
-            else if (ptg >= 0x20) {
-                const basePtg = ptg & 0x1f;
-                if (basePtg === 0x01) {
-                    // PtgFunc - function with fixed args
-                    if (!canRead(2))
-                        break;
-                    pushFixedFunction(reader.readUInt16LE());
-                }
-                else if (basePtg === 0x02) {
-                    // PtgFuncVar - function with variable args
-                    if (!canRead(3))
-                        break;
-                    const cargs = reader.readUInt8();
-                    pushVariableFunction(cargs, reader.readUInt16LE());
-                }
-                else if (basePtg === 0x04) {
-                    // PtgRef - cell reference
-                    if (!canRead(6))
-                        break;
-                    stack.push(readShortRef());
-                }
-                else if (basePtg === 0x05) {
-                    // PtgArea - range reference
-                    if (!canRead(12))
-                        break;
-                    stack.push(readShortArea());
+            case 0x22:
+            case 0x42:
+            case 0x62: {
+                // PtgFuncVar: the argument count (up to 255), then the function (bit 15: a command).
+                const argc = reader.u8();
+                const field = reader.u16();
+                if (field & 0x8000) {
+                    throw new RgceUnsupportedError("command-equivalent function");
                 }
-                else if (basePtg === 0x0c) {
-                    // PtgRefN - relative cell reference (commonly used in shared formulas)
-                    if (!canRead(6))
-                        break;
-                    stack.push(readRelShortRef());
-                }
-                else if (basePtg === 0x0d) {
-                    // PtgAreaN - relative range reference
-                    if (!canRead(12))
-                        break;
-                    stack.push(readRelShortArea());
+                const iftab = field & 0x7fff;
+                const args = popArgs(argc);
+                if (iftab === 0xff) {
+                    // A user-defined or add-in function: its name is the first argument.
+                    const [name, ...rest] = args;
+                    if (!name) {
+                        throw new RgceUnsupportedError("user-defined function without a name");
+                    }
+                    stack.push(`${name}(${rest.join(",")})`);
                 }
                 else {
-                    // Unknown class token: break to avoid stream desync.
-                    break;
+                    stack.push(callFunction(iftab, args));
                 }
+                continue;
             }
-            else {
-                // Unknown non-class token: break to avoid stream desync.
-                if (debug) {
-                    console.log(`[Rgce] Unknown token 0x${ptg.toString(16)}, stopping parse`);
+            case 0x23:
+            case 0x43:
+            case 0x63: {
+                // PtgName: a 1-based index into the workbook's names.
+                const index = reader.u32();
+                const name = context.definedName?.(index);
+                if (name === undefined) {
+                    throw new RgceUnsupportedError(`unknown defined name ${index}`);
                 }
-                break;
+                stack.push(name);
+                continue;
+            }
+            case 0x24:
+            case 0x44:
+            case 0x64: {
+                // PtgRef
+                const row = reader.u32();
+                const c = corner(row, reader.u16());
+                stack.push(cellRef(c.row, c.col, c.rowRelative, c.colRelative));
+                continue;
+            }
+            case 0x25:
+            case 0x45:
+            case 0x65: {
+                // PtgArea
+                const rowFirst = reader.u32();
+                const rowLast = reader.u32();
+                const colFirst = reader.u16();
+                const colLast = reader.u16();
+                stack.push(areaRef(corner(rowFirst, colFirst), corner(rowLast, colLast)));
+                continue;
+            }
+            case 0x26:
+            case 0x46:
+            case 0x66: // PtgMemArea
+            case 0x27:
+            case 0x47:
+            case 0x67: // PtgMemErr
+            case 0x28:
+            case 0x48:
+            case 0x68: // PtgMemNoMem
+                // A precomputed reference: the tokens that follow compute it.
+                reader.skip(4);
+                reader.u16(); // cce
+                continue;
+            case 0x29:
+            case 0x49:
+            case 0x69: // PtgMemFunc
+                reader.u16(); // cce
+                continue;
+            case 0x2a:
+            case 0x4a:
+            case 0x6a: // PtgRefErr
+                reader.skip(6);
+                stack.push("#REF!");
+                continue;
+            case 0x2b:
+            case 0x4b:
+            case 0x6b: // PtgAreaErr
+                reader.skip(12);
+                stack.push("#REF!");
+                continue;
+            case 0x2c:
+            case 0x4c:
+            case 0x6c: {
+                // PtgRefN: relative to the base cell.
+                const row = reader.i32();
+                const c = relativeCorner(row, reader.u16(), context.baseCell);
+                stack.push(cellRef(c.row, c.col, c.rowRelative, c.colRelative));
+                continue;
+            }
+            case 0x2d:
+            case 0x4d:
+            case 0x6d: {
+                // PtgAreaN
+                const rowFirst = reader.i32();
+                const rowLast = reader.i32();
+                const colFirst = reader.u16();
+                const colLast = reader.u16();
+                stack.push(areaRef(relativeCorner(rowFirst, colFirst, context.baseCell), relativeCorner(rowLast, colLast, context.baseCell)));
+                continue;
+            }
+            case 0x3a:
+            case 0x5a:
+            case 0x7a: {
+                // PtgRef3d
+                const prefix = sheet(reader.u16());
+                const row = reader.u32();
+                const c = corner(row, reader.u16());
+                stack.push(`${prefix}!${cellRef(c.row, c.col, c.rowRelative, c.colRelative)}`);
+                continue;
+            }
+            case 0x3b:
+            case 0x5b:
+            case 0x7b: {
+                // PtgArea3d
+                const prefix = sheet(reader.u16());
+                const rowFirst = reader.u32();
+                const rowLast = reader.u32();
+                const colFirst = reader.u16();
+                const colLast = reader.u16();
+                stack.push(`${prefix}!${areaRef(corner(rowFirst, colFirst), corner(rowLast, colLast))}`);
+                continue;
+            }
+            case 0x3c:
+            case 0x5c:
+            case 0x7c: // PtgRefErr3d
+            case 0x3d:
+            case 0x5d:
+            case 0x7d: {
+                // PtgAreaErr3d. Excel keeps the sheet a deleted reference was on
+                // (`Sheet1!#REF!`); on a sheet it cannot name, the error alone.
+                const ixti = reader.u16();
+                const name = context.sheetName?.(ixti);
+                reader.skip((ptg & 0x1f) === 0x1c ? 6 : 12);
+                stack.push(name === undefined ? "#REF!" : `${quoteSheetName(name)}!#REF!`);
+                continue;
             }
         }
+        // PtgExp / PtgTbl (shared, array or data-table formulas), PtgArray,
+        // PtgNameX, the extended tokens (structured references) and anything else.
+        throw new RgceUnsupportedError(`token 0x${ptg.toString(16)}`);
     }
-    catch (err) {
-        // Parse error - return what we have so far
-        if (debug) {
-            console.error("[Rgce] Parse error:", err);
-        }
-        return stack.length > 0 ? stack[stack.length - 1] : "";
+    if (stack.length !== 1) {
+        throw new RgceUnsupportedError(`formula leaves ${stack.length} expressions`);
+    }
+    return stack[0];
+}
+/**
+ * A formula's text, or `""` when it cannot be decoded exactly — never a part of
+ * one. Prefer {@link decodeRgce}, which says why.
+ *
+ * @deprecated the lenient form of {@link decodeRgce}.
+ */
+export function parseRgce(rgceBytes, sheetRefResolver, baseCell) {
+    if (!rgceBytes || rgceBytes.length === 0)
+        return "";
+    const sheetName = typeof sheetRefResolver === "function"
+        ? sheetRefResolver
+        : (ixti) => sheetRefResolver?.[ixti];
+    try {
+        return decodeRgce(rgceBytes, { sheetName, baseCell });
     }
-    const result = stack.length > 0 ? stack[stack.length - 1] : "";
-    if (debug) {
-        console.log("[Rgce] Final result:", result);
+    catch (error) {
+        if (error instanceof RgceUnsupportedError)
+            return "";
+        throw error;
     }
-    return result;
 }