@shbernal/ts-xlsx 1.3.1 → 2.1.0

package/dist/vba/dir-records.d.ts

@@ -0,0 +1,53 @@
+/** PROJECTCODEPAGE: the code page every MBCS name in the project decodes through. */
+export declare const REC_PROJECT_CODEPAGE = 3;
+/** PROJECTVERSION: the record whose `Size` under-counts its payload by the trailing VersionMinor. */
+export declare const REC_PROJECT_VERSION = 9;
+/** REFERENCEREGISTERED: a reference to a registered type library, by libid. */
+export declare const REC_REFERENCE_REGISTERED = 13;
+/** PROJECTMODULES MODULES_COUNT: how many module blocks follow, and the first record after the
+ * reference array, which has no count of its own. */
+export declare const REC_MODULES_COUNT = 15;
+/** REFERENCENAME: a reference's MBCS name. */
+export declare const REC_REFERENCE_NAME = 22;
+/** MODULENAME: opens a module's record block. */
+export declare const REC_MODULE_NAME = 25;
+/** MODULESTREAMNAME: the storage name the module's p-code lives under. */
+export declare const REC_MODULE_STREAMNAME = 26;
+/** MODULETYPE for a standard module. */
+export declare const REC_MODULE_TYPE_PROCEDURAL = 33;
+/** MODULETYPE for a document module (`ThisWorkbook`, a sheet's code-behind). */
+export declare const REC_MODULE_TYPE_DOCUMENT = 34;
+/** MODULEENDOFBLOCK: closes a module's record block. */
+export declare const REC_MODULE_TERMINATOR = 43;
+/** MODULEOFFSET: where the module's source begins inside its stream. */
+export declare const REC_MODULE_OFFSET = 49;
+/**
+ * REFERENCENAME's Unicode half. A *literal* `0x003E` marker rather than a nested record id, but it is
+ * laid out as its own Id+Size+data TLV, so a generic walk sees REFERENCENAME as two chained records,
+ * exactly like MODULENAME/MODULENAME_UNICODE. Verified against a real Excel-authored dir stream
+ * (2026-07-23).
+ */
+export declare const REC_REFERENCE_NAME_UNICODE = 62;
+/** One record as the walk sees it. */
+export interface DirRecord {
+    /** The record id; one of the `REC_*` constants above, or a record this library does not consume. */
+    readonly id: number;
+    /** Offset of the record's `Id` field: where a splice that drops the record cuts from. */
+    readonly recordStart: number;
+    /** Offset of the record's payload. */
+    readonly dataStart: number;
+    /** The `Size` field, which is the payload length for every record but PROJECTVERSION. */
+    readonly size: number;
+    /** Offset of the next record, PROJECTVERSION's uncounted VersionMinor already skipped. Never
+     * recompute this from `dataStart + size`: that is the misalignment this module exists to prevent. */
+    readonly end: number;
+}
+/**
+ * Walk a decompressed `dir` stream, yielding each record in order. Consumers may stop early.
+ *
+ * @param context the phrase a truncated record's error carries, naming what the caller was doing:
+ *   the message reaches a user who has no idea what a TLV is but does know they were removing a
+ *   module.
+ * @throws {VbaParseError} when a record's payload runs past the end of the stream.
+ */
+export declare function dirRecords(dir: Uint8Array, context: string): Generator<DirRecord>;

package/dist/vba/dir-records.js

@@ -0,0 +1,28 @@
+import { readU16, readU32 } from './bytes.js';
+import { VbaParseError } from './errors.js';
+export const REC_PROJECT_CODEPAGE = 0x0003;
+export const REC_PROJECT_VERSION = 0x0009;
+export const REC_REFERENCE_REGISTERED = 0x000d;
+export const REC_MODULES_COUNT = 0x000f;
+export const REC_REFERENCE_NAME = 0x0016;
+export const REC_MODULE_NAME = 0x0019;
+export const REC_MODULE_STREAMNAME = 0x001a;
+export const REC_MODULE_TYPE_PROCEDURAL = 0x0021;
+export const REC_MODULE_TYPE_DOCUMENT = 0x0022;
+export const REC_MODULE_TERMINATOR = 0x002b;
+export const REC_MODULE_OFFSET = 0x0031;
+export const REC_REFERENCE_NAME_UNICODE = 0x003e;
+export function* dirRecords(dir, context) {
+    let pos = 0;
+    while (pos + 6 <= dir.length) {
+        const id = readU16(dir, pos);
+        const size = readU32(dir, pos + 2);
+        const dataStart = pos + 6;
+        if (dataStart + size > dir.length) {
+            throw new VbaParseError(`dir record 0x${id.toString(16)} ${context}`);
+        }
+        const end = dataStart + size + (id === REC_PROJECT_VERSION ? 2 : 0);
+        yield { id, recordStart: pos, dataStart, size, end };
+        pos = end;
+    }
+}

package/dist/vba/errors.d.ts

@@ -1,6 +1,6 @@
 import { XlsxError } from '../errors.ts';
 /**
- * Thrown when a VBA project (`vbaProject.bin`) is present but cannot be parsed — a malformed
+ * Thrown when a VBA project (`vbaProject.bin`) is present but cannot be parsed: a malformed
  * compound file, a corrupt compressed stream, or a `dir` record that does not conform to [MS-OVBA].
  * A workbook with no macros never produces this: {@link Workbook.vbaProject} is `undefined` instead.
  *
@@ -13,7 +13,7 @@ export declare class VbaParseError extends XlsxError {
 }
 /**
  * Thrown when authoring a VBA project (synthesizing a `vbaProject.bin` from module source) is asked to
- * produce something that cannot be encoded to a well-formed container — a stream name longer than the
+ * produce something that cannot be encoded to a well-formed container: a stream name longer than the
  * [MS-CFB] 31-character limit, a duplicate stream name, or a project so large it would exceed the
  * writer's single-header DIFAT bound. This is a caller-side contract violation, distinct from
  * {@link VbaParseError} (which reports a malformed blob *read* from an untrusted file).

package/dist/vba/index.d.ts

@@ -1,5 +1,5 @@
-export { type CfbNode, type CfbStorage, type CfbStream, writeCompoundFile, } from './cfb-writer.ts';
+export { type CfbNode, type CfbStorage, type CfbStream, writeCompoundFile } from './cfb-writer.ts';
 export { VbaAuthorError, VbaParseError } from './errors.ts';
 export { compressContainer, decompressContainer } from './ms-ovba.ts';
 export { parseVbaProject, VBA_PROJECT_CONTENT_TYPE, VBA_PROJECT_PART_PATH, VBA_PROJECT_REL_TYPE, type VbaModule, type VbaModuleKind, type VbaProject, type VbaProjectSignature, type VbaProjectSignatureKind, vbaProjectSignatureKind, } from './project.ts';
-export { addVbaReference, removeVbaModule, type VbaLibraryReference, } from './project-editor.ts';
+export { addVbaReference, removeVbaModule, type VbaLibraryReference } from './project-editor.ts';

package/dist/vba/index.js

@@ -1,5 +1,5 @@
-export { writeCompoundFile, } from './cfb-writer.js';
+export { writeCompoundFile } from './cfb-writer.js';
 export { VbaAuthorError, VbaParseError } from './errors.js';
 export { compressContainer, decompressContainer } from './ms-ovba.js';
 export { parseVbaProject, VBA_PROJECT_CONTENT_TYPE, VBA_PROJECT_PART_PATH, VBA_PROJECT_REL_TYPE, vbaProjectSignatureKind, } from './project.js';
-export { addVbaReference, removeVbaModule, } from './project-editor.js';
+export { addVbaReference, removeVbaModule } from './project-editor.js';

package/dist/vba/ms-ovba.d.ts

@@ -4,7 +4,7 @@
  */
 export declare function decompressContainer(buf: Uint8Array, start?: number, maxOutput?: number): Uint8Array;
 /**
- * Compress `data` into an MS-OVBA CompressedContainer — the inverse of {@link decompressContainer}.
+ * Compress `data` into an MS-OVBA CompressedContainer: the inverse of {@link decompressContainer}.
  * Every 4096-decompressed-byte window is emitted as a compressed chunk of literal and copy tokens, or
  * stored verbatim when compression would not shrink it (so the encoded chunk never exceeds the 12-bit
  * size field). The result re-expands to `data` byte-for-byte.

package/dist/vba/ms-ovba.js

@@ -1,3 +1,4 @@
+import { readU16 } from './bytes.js';
 import { VbaParseError } from './errors.js';
 const MAX_CHUNK_DECOMPRESSED = 4096;
 const CHUNK_SIGNATURE = 0b011 << 12;
@@ -128,6 +129,3 @@ function copyTokenHelp(decompressedSoFar) {
     const lengthMask = 0xffff >> bitCount;
     return { lengthMask, bitCount };
 }
-function readU16(buf, at) {
-    return buf[at] | (buf[at + 1] << 8);
-}

package/dist/vba/project-editor.d.ts

@@ -4,7 +4,7 @@
  * stream, its MODULE record block in `dir` (decrementing `MODULES_COUNT`), and its `Module=`/`Class=` +
  * workspace lines in `PROJECT`/`PROJECTwm`.
  *
- * Only `procedural` and `class` modules can be removed this way — removing a `document` module (e.g.
+ * Only `procedural` and `class` modules can be removed this way. Removing a `document` module (e.g.
  * `ThisWorkbook`) or a `designer` module (a UserForm) would leave the host referencing code that no
  * longer exists, since their names are tied to a worksheet/workbook `codeName` or a designer storage
  * this project-level primitive has no visibility into. Editing such a module's code-behind is a job for
@@ -15,14 +15,14 @@
  */
 export declare function removeVbaModule(bin: Uint8Array, name: string): Uint8Array;
 /**
- * A registered (COM Automation type-library) reference to add to an existing VBA project — the shape of
+ * A registered (COM Automation type-library) reference to add to an existing VBA project: the shape of
  * a real "add a reference to Microsoft Scripting Runtime" call. Project references (to another VBA
- * project) and control references (to an ActiveX control library) are out of scope — see
+ * project) and control references (to an ActiveX control library) are out of scope. See
  * {@link addVbaReference}.
  */
 export interface VbaLibraryReference {
     /**
-     * The reference's namespace name in the VBA editor — what a qualified reference like
+     * The reference's namespace name in the VBA editor: what a qualified reference like
      * `Scripting.Dictionary` resolves through. Must be a valid VBA identifier, at most 31 characters, as
      * real type libraries use (e.g. `Scripting`, `Office`, `stdole`).
      */
@@ -34,12 +34,12 @@ export interface VbaLibraryReference {
     readonly displayName?: string;
     /** The type library's GUID, e.g. `{420B2830-E718-11CF-893D-00A0C9054228}` (braces optional). */
     readonly guid: string;
-    /** The type library's major version — an integer in `[0, 0xFFFF]` ([MS-OVBA] `LibidMajorVersion`). */
+    /** The type library's major version, an integer in `[0, 0xFFFF]` ([MS-OVBA] `LibidMajorVersion`). */
     readonly majorVersion: number;
-    /** The type library's minor version — an integer in `[0, 0xFFFF]` ([MS-OVBA] `LibidMinorVersion`). */
+    /** The type library's minor version, an integer in `[0, 0xFFFF]` ([MS-OVBA] `LibidMinorVersion`). */
     readonly minorVersion: number;
     /**
-     * The type library's LCID — an integer in `[0, 0xFFFFFFFF]`. Defaults to `0` (locale-neutral), the
+     * The type library's LCID, an integer in `[0, 0xFFFFFFFF]`. Defaults to `0` (locale-neutral), the
      * overwhelming common case (every reference in a real project observed while building this had `0`).
      */
     readonly lcid?: number;
@@ -50,9 +50,9 @@ export interface VbaLibraryReference {
  * Add a registered (COM type-library) reference to an existing `vbaProject.bin`, returning new bytes
  * that carry every existing module, reference, and host-info record unchanged. It grows the project's
  * `dir` stream by one `REFERENCENAME` + `REFERENCEREGISTERED` record pair, positioned immediately before
- * `MODULES_COUNT` (references have no count field of their own — `MODULES_COUNT` simply marks where the
+ * `MODULES_COUNT` (references have no count field of their own; `MODULES_COUNT` simply marks where the
  * reference array ends). It needs no change to `PROJECT`/`PROJECTwm`: a real Excel-authored `PROJECT`
- * stream carries no `Reference=` line at all — references live only in `dir` (confirmed against a genuine
+ * stream carries no `Reference=` line at all: references live only in `dir` (confirmed against a genuine
  * Excel-authored project).
  *
  * @throws {VbaParseError} if `bin` is not a parseable VBA project (validated before any edit).

package/dist/vba/project-editor.js

@@ -1,6 +1,8 @@
-import { CompoundFile } from './cfb.js';
+import { readU16 } from './bytes.js';
 import { writeCompoundFile } from './cfb-writer.js';
+import { CompoundFile } from './cfb.js';
 import { decoderForCodePage, encoderForCodePage } from './codepage.js';
+import { dirRecords, REC_MODULE_NAME, REC_MODULE_STREAMNAME, REC_MODULE_TERMINATOR, REC_MODULES_COUNT, REC_REFERENCE_NAME, REC_REFERENCE_NAME_UNICODE, REC_REFERENCE_REGISTERED, } from './dir-records.js';
 import { VbaAuthorError, VbaParseError } from './errors.js';
 import { compressContainer, decompressContainer } from './ms-ovba.js';
 import { parseVbaProject } from './project.js';
@@ -9,14 +11,6 @@ const DIR_STREAM = 'dir';
 const PROJECT_STREAM = 'PROJECT';
 const PROJECTWM_STREAM = 'PROJECTwm';
 const VBA_STORAGE = 'VBA';
-const REC_MODULE_NAME = 0x0019;
-const REC_MODULE_STREAMNAME = 0x001a;
-const REC_MODULE_TERMINATOR = 0x002b;
-const REC_PROJECT_VERSION = 0x0009;
-const REC_MODULES_COUNT = 0x000f;
-const REC_REFERENCE_NAME = 0x0016;
-const REC_REFERENCE_NAME_UNICODE = 0x003e;
-const REC_REFERENCE_REGISTERED = 0x000d;
 export function removeVbaModule(bin, name) {
     const project = parseVbaProject(bin);
     const nameKey = name.toUpperCase();
@@ -123,18 +117,7 @@ function buildReferenceDirRecords(ref, encode) {
 }
 function insertReferenceDirRecords(dir, records) {
     let insertAt = -1;
-    let pos = 0;
-    while (pos + 6 <= dir.length) {
-        const recordStart = pos;
-        const id = readU16(dir, pos);
-        const size = readU32(dir, pos + 2);
-        const dataStart = pos + 6;
-        if (dataStart + size > dir.length) {
-            throw new VbaParseError(`dir record 0x${id.toString(16)} overruns while adding a reference`);
-        }
-        pos = dataStart + size;
-        if (id === REC_PROJECT_VERSION)
-            pos += 2;
+    for (const { id, recordStart } of dirRecords(dir, 'overruns while adding a reference')) {
         if (id === REC_MODULES_COUNT) {
             insertAt = recordStart;
             break;
@@ -156,18 +139,7 @@ function removeModuleDirRecord(dir, streamName, codePage) {
     let removeStart = -1;
     let removeEnd = -1;
     let currentStream;
-    let pos = 0;
-    while (pos + 6 <= dir.length) {
-        const recordStart = pos;
-        const id = readU16(dir, pos);
-        const size = readU32(dir, pos + 2);
-        const dataStart = pos + 6;
-        if (dataStart + size > dir.length) {
-            throw new VbaParseError(`dir record 0x${id.toString(16)} overruns while removing a module`);
-        }
-        pos = dataStart + size;
-        if (id === REC_PROJECT_VERSION)
-            pos += 2;
+    for (const { id, recordStart, dataStart, size, end } of dirRecords(dir, 'overruns while removing a module')) {
         if (id === REC_MODULES_COUNT) {
             if (size < 2)
                 throw new VbaParseError('PROJECTMODULES MODULES_COUNT record is malformed');
@@ -182,7 +154,7 @@ function removeModuleDirRecord(dir, streamName, codePage) {
         else if (id === REC_MODULE_TERMINATOR) {
             if (currentStream === streamName) {
                 removeStart = blockStart;
-                removeEnd = pos;
+                removeEnd = end;
             }
             currentStream = undefined;
             blockStart = -1;
@@ -280,13 +252,3 @@ function replaceStreams(nodes, replacements, applied) {
         return { name: node.name, children: replaceStreams(node.children, replacements, applied) };
     });
 }
-function readU16(buf, at) {
-    return buf[at] | (buf[at + 1] << 8);
-}
-function readU32(buf, at) {
-    return ((buf[at] |
-        (buf[at + 1] << 8) |
-        (buf[at + 2] << 16) |
-        (buf[at + 3] << 24)) >>>
-        0);
-}

package/dist/vba/project.d.ts

@@ -1,9 +1,9 @@
-/** How a module participates in the project — the classification the VBA editor shows. */
+/** How a module participates in the project: the classification the VBA editor shows. */
 export type VbaModuleKind = 'procedural' | 'document' | 'class' | 'designer';
 export interface VbaModule {
     /** The module's code name as seen in the VBA editor, e.g. `ThisWorkbook`, `JsonConverter`. */
     readonly name: string;
-    /** The CFB stream the module's bytes live in — usually equal to {@link name}. */
+    /** The CFB stream the module's bytes live in, usually equal to {@link name}. */
     readonly streamName: string;
     /** Procedural (`.bas`), document code-behind, class module, or designer (UserForm). */
     readonly kind: VbaModuleKind;
@@ -20,17 +20,17 @@ export declare const VBA_PROJECT_REL_TYPE = "http://schemas.microsoft.com/office
 export declare const VBA_PROJECT_CONTENT_TYPE = "application/vnd.ms-office.vbaProject";
 export declare const VBA_PROJECT_PART_PATH = "xl/vbaProject.bin";
 /**
- * Which generation of VBA project signature a part is — Office emits up to three sibling signature
+ * Which generation of VBA project signature a part is. Office emits up to three sibling signature
  * parts off `vbaProject.bin`'s own rels over the same project bytes ([MS-OFFMACRO2]): the original
  * `legacy` signature, the `agile` (V2) successor, and the `v3` scheme that closes a tampering hole
  * the earlier two left open (KB5000676). All three can coexist in one package.
  */
 export type VbaProjectSignatureKind = 'legacy' | 'agile' | 'v3';
-/** One digital signature over a workbook's VBA project — its generation and its raw signature bytes. */
+/** One digital signature over a workbook's VBA project: its generation and its raw signature bytes. */
 export interface VbaProjectSignature {
     readonly kind: VbaProjectSignatureKind;
     /**
-     * The raw signature part bytes (a PKCS#7/CMS blob), passed through verbatim — this library does not
+     * The raw signature part bytes (a PKCS#7/CMS blob), passed through verbatim. This library does not
      * parse or cryptographically verify them. Their presence means "a signature is attached," never
      * "this signature is valid."
      */

package/dist/vba/project.js

@@ -1,5 +1,7 @@
+import { readU16, readU32 } from './bytes.js';
 import { CompoundFile } from './cfb.js';
 import { decoderForCodePage } from './codepage.js';
+import { dirRecords, REC_MODULE_NAME, REC_MODULE_OFFSET, REC_MODULE_STREAMNAME, REC_MODULE_TERMINATOR, REC_MODULE_TYPE_DOCUMENT, REC_MODULE_TYPE_PROCEDURAL, REC_PROJECT_CODEPAGE, } from './dir-records.js';
 import { VbaParseError } from './errors.js';
 import { decompressContainer } from './ms-ovba.js';
 export const VBA_PROJECT_REL_TYPE = 'http://schemas.microsoft.com/office/2006/relationships/vbaProject';
@@ -13,14 +15,6 @@ const SIGNATURE_KIND_BY_REL_SEGMENT = {
 export function vbaProjectSignatureKind(relType) {
     return SIGNATURE_KIND_BY_REL_SEGMENT[relType.slice(relType.lastIndexOf('/') + 1)];
 }
-const REC_PROJECT_CODEPAGE = 0x0003;
-const REC_MODULE_NAME = 0x0019;
-const REC_MODULE_STREAMNAME = 0x001a;
-const REC_MODULE_TYPE_PROCEDURAL = 0x0021;
-const REC_MODULE_TYPE_DOCUMENT = 0x0022;
-const REC_MODULE_OFFSET = 0x0031;
-const REC_MODULE_TERMINATOR = 0x002b;
-const REC_PROJECT_VERSION = 0x0009;
 export function parseVbaProject(bin) {
     const cfb = new CompoundFile(bin);
     const dirCompressed = cfb.readStream('dir');
@@ -30,16 +24,7 @@ export function parseVbaProject(bin) {
     let codePage = 1252;
     const rawModules = [];
     let pending = {};
-    let pos = 0;
-    while (pos + 6 <= dir.length) {
-        const id = readU16(dir, pos);
-        const size = readU32(dir, pos + 2);
-        const dataStart = pos + 6;
-        if (dataStart + size > dir.length)
-            throw new VbaParseError(`dir record 0x${id.toString(16)} overruns stream`);
-        pos = dataStart + size;
-        if (id === REC_PROJECT_VERSION)
-            pos += 2;
+    for (const { id, dataStart, size } of dirRecords(dir, 'overruns stream')) {
         switch (id) {
             case REC_PROJECT_CODEPAGE:
                 if (size >= 2)
@@ -116,13 +101,3 @@ function readProjectStreamKinds(cfb, decoder) {
     }
     return kinds;
 }
-function readU16(buf, at) {
-    return buf[at] | (buf[at + 1] << 8);
-}
-function readU32(buf, at) {
-    return ((buf[at] |
-        (buf[at + 1] << 8) |
-        (buf[at + 2] << 16) |
-        (buf[at + 3] << 24)) >>>
-        0);
-}

package/dist/vba/vba-encoding.d.ts

@@ -10,5 +10,5 @@ export declare function validateVbaName(name: string, what: 'project' | 'module'
 export declare function push(out: number[], id: number, data: number[]): void;
 export declare function u16(n: number): number[];
 export declare function u32(n: number): number[];
-/** A name as NUL-free UTF-16LE code units — the encoding [MS-OVBA] uses for every "Unicode" name field. */
+/** A name as NUL-free UTF-16LE code units: the encoding [MS-OVBA] uses for every "Unicode" name field. */
 export declare function utf16le(s: string): number[];

package/dist/xml/errors.d.ts

@@ -1,6 +1,6 @@
 import { XlsxError } from '../errors.ts';
 /**
- * Thrown when XML text cannot be scanned into parse events — an unterminated tag, comment, CDATA
+ * Thrown when XML text cannot be scanned into parse events: an unterminated tag, comment, CDATA
  * section, markup declaration or processing instruction.
  *
  * This is a *typed* failure rather than the native `SyntaxError` it reads like, because the text

package/dist/xml/xml-read.d.ts

@@ -14,7 +14,7 @@ export interface SaxHandlers {
  * One parse event from {@link xmlEvents}. The payloads match {@link SaxHandlers} exactly: `text`
  * is already entity-decoded (or verbatim CDATA), and a `<x/>` yields one `open` with
  * `selfClosing: true` and no matching `close`. The discriminated `kind` lets a *pull* consumer
- * drive the parse — the shape the streaming reader needs, where a push callback cannot `yield`.
+ * drive the parse: the shape the streaming reader needs, where a push callback cannot `yield`.
  */
 export type XmlEvent = {
     readonly kind: 'open';
@@ -30,16 +30,36 @@ export type XmlEvent = {
 };
 /**
  * Decode XML character references and the five predefined entities. An unrecognised
- * `&name;` is left verbatim rather than expanded — there is no DTD, so there is nothing
+ * `&name;` is left verbatim rather than expanded: there is no DTD, so there is nothing
  * to expand it to, and refusing to invent one is what makes entity-expansion attacks
  * impossible.
  */
 export declare function decodeEntities(value: string): string;
+/**
+ * The SpreadsheetML `_xHHHH_` escape, in the only place it may appear: a complete cell-text value.
+ *
+ * The mirror of `escapeSpreadsheetText` in `./xml.ts`, and it sits here rather than beside it for
+ * the same reason `decodeEntities` sits apart from `escapeText`: the write helpers carry an
+ * `AuthoringError` and a whole serialisation vocabulary the reader has no business importing.
+ *
+ * **One left-to-right pass, and that is load-bearing.** `005F` maps to `_` like any other code
+ * point, with no special case, because a single pass already gives the underscore escape its
+ * meaning: in `_x005F_x0041_` the match at 0 yields `_` and scanning resumes at `x0041_`, which has
+ * no leading underscore left to start an escape. So the value reads back as the literal seven
+ * characters `_x0041_` the author wrote. Decoding `_x005F_` in a pass of its own, before or after
+ * the rest, collapses that to `A` and loses the distinction the encoder went to trouble to keep.
+ * Excel agrees: it reads that cell as `_x0041_`.
+ *
+ * The decode is unconditional, not a repair of characters XML cannot carry. Excel reads
+ * `a_x0009_b` as a tab even though a literal tab would have been perfectly legal there, so a
+ * decoder that only handled the illegal range would disagree with Excel on files Excel wrote.
+ */
+export declare function decodeSpreadsheetText(value: string): string;
 /**
  * Scan an XML document as a *pull* stream of {@link XmlEvent}s in a single O(n) pass with no
  * recursion. This is the parser's core; {@link parseXml} is a thin push adapter over it. A
  * consumer that must produce output incrementally (the streaming row reader) pulls events and
- * yields as it goes, holding only its own running state — a push callback cannot.
+ * yields as it goes, holding only its own running state; a push callback cannot.
  *
  * Throws {@link XmlParseError} on malformed markup.
  */
@@ -63,12 +83,12 @@ export interface OpenElement {
 export declare function openElements(source: string, ...localNames: string[]): Generator<OpenElement>;
 /**
  * Wrap an {@link XmlEvent} stream so a self-closing `<x/>` whose local name is in `names` is
- * presented as an open (with `selfClosing: false`) immediately followed by a close — the exact
+ * presented as an open (with `selfClosing: false`) immediately followed by a close: the exact
  * event shape of `<x></x>`. This lets a consumer commit such an element from its close handling
  * alone, instead of hand-coding a parallel self-closing branch: {@link xmlEvents} fires no close
  * for `<x/>`, and forgetting that branch silently drops the empty element. Names not in the set
- * pass through untouched, so an element whose close would wrongly act on absent content — an empty
- * `<v/>`/`<f/>` that must not commit captured text — is left as a bare self-closing open.
+ * pass through untouched, so an element whose close would wrongly act on absent content (an empty
+ * `<v/>`/`<f/>` that must not commit captured text) is left as a bare self-closing open.
  */
 export declare function closeEmptyElements(events: Iterable<XmlEvent>, names: ReadonlySet<string>): Generator<XmlEvent>;
 /** Options for {@link parseXml}. */
@@ -83,7 +103,7 @@ export interface ParseXmlOptions {
 }
 /**
  * Parse an XML document, dispatching SAX events to `handlers`. A thin push adapter over
- * {@link xmlEvents} — one scanning core serves both the callback and the pull consumers.
+ * {@link xmlEvents}: one scanning core serves both the callback and the pull consumers.
  * Throws {@link XmlParseError} on malformed markup.
  */
 export declare function parseXml(source: string, handlers: SaxHandlers, options?: ParseXmlOptions): void;
@@ -92,16 +112,85 @@ export declare function localName(qualified: string): string;
 /** An OOXML boolean that is on when present with no value (`<b/>` is bold) and off only on an
  * explicit `"0"`/`"false"`; absence reads as on. */
 export declare function boolPresent(val: string | undefined): boolean;
-/** An OOXML boolean that is on only when explicitly `"1"`/`"true"`; anything else — including
- * absence and a truthy-looking `"0"` — is off. */
+/** An OOXML boolean that is on only when explicitly `"1"`/`"true"`; anything else, including
+ * absence and a truthy-looking `"0"`, is off. */
 export declare function boolStrict(val: string | undefined): boolean;
 /** An optional OOXML boolean: `undefined` when the attribute is absent or carries an unrecognised
  * token, otherwise its `"1"`/`"true"` vs `"0"`/`"false"` value. Lets a caller store only the
  * attributes the source actually carried, so a re-write stays byte-clean. */
 export declare function boolTristate(val: string | undefined): boolean | undefined;
+/** An OOXML integer attribute at or above `min` (default: unbounded below); `undefined` when the
+ * attribute is absent, blank, fractional, not a number, or below the floor. Integers past
+ * `Number.MAX_SAFE_INTEGER` read as `undefined` too: no index or count is usable out there, and
+ * arithmetic on one silently lies. */
+export declare function numInteger(val: string | undefined, min?: number): number | undefined;
+/** An OOXML decimal attribute at or above `min` (default: unbounded below); `undefined` when the
+ * attribute is absent, blank, not a number, or below the floor. Infinities are not finite numbers
+ * and read as `undefined`. */
+export declare function numFinite(val: string | undefined, min?: number): number | undefined;
 /** Read an operand's text as a number only when it is a canonical decimal literal (optional sign,
  * digits, optional fraction). A cell reference, defined name, expression, or exotically-spelled
  * number (`1E5`, hex) keeps its verbatim text, so it is neither coerced to `NaN` and lost nor
  * re-spelled into a number that would not re-write byte-clean. Callers layer their own type rules
  * (a data-validation `list`/`custom` operand stays a string regardless of what it looks like). */
 export declare function coerceNumericLiteral(text: string): string | number;
+/** Narrow an enumerated attribute through its guard; `undefined` when absent or not a member. */
+export declare function enumToken<T extends string>(val: string | undefined, isMember: (candidate: string) => candidate is T): T | undefined;
+/**
+ * Gathers one element's character data across the open/text/close events a SAX parse delivers it in.
+ *
+ * Nine parsers used to open-code this: latch a flag and clear a buffer on the open, append every
+ * chunk while latched, consume the buffer and unlatch on the close. Six spellings of one idea, and
+ * none of them honoured the one thing {@link SaxHandlers.onOpen} warns about. A self-closing `<x/>`
+ * fires no matching close, so `<t/>`, `<text/>`, `<xm:f/>` and `<totalsRowFormula/>`, all legal and
+ * all written by real files, latched a capture that nothing would ever close. What kept that from
+ * corrupting anything was the order the next open happened to reset things in, which is an accident
+ * rather than a property anyone chose, on a path that reads untrusted input. Taking `selfClosing`
+ * here makes it structural, once.
+ *
+ * The other thing the open-coded versions disagreed on is what an unrelated element opening
+ * mid-capture should do. Ending the capture is never what a caller wants: the text belongs to the
+ * element that opened it, and a nested or sibling element is not that element. So an open that is
+ * not for a captured name leaves an capture in progress alone, and {@link close} answers only for
+ * the element that started it.
+ *
+ * Decoding stays outside. A `<t>` needs `decodeSpreadsheetText` over the whole element and never
+ * over a chunk, an `<xm:f>` needs nothing, and a coordinate needs a number: the caller knows which.
+ */
+export declare class TextCapture {
+    #private;
+    /** @param names the element local name, or the set of names this instance may capture. */
+    constructor(names: string | Iterable<string>);
+    /** Whether a capture is currently open. */
+    get capturing(): boolean;
+    /** Begin capturing `local` if it is one of this instance's names and is not self-closing. */
+    open(local: string, selfClosing: boolean): void;
+    /** Feed a chunk of character data; ignored when no capture is open. */
+    text(chunk: string): void;
+    /** The gathered text when `local` closes the captured element, else `undefined`. Unlatches. */
+    close(local: string): string | undefined;
+}
+/**
+ * Yield each named element's text as that element closes, as `{local, text}`.
+ *
+ * The third member of the pull-shaped family beside {@link openElements} ("scan opens, read
+ * attributes") and {@link closeEmptyElements}: this one is "capture these elements' text, tell me
+ * each as it closes". A parser whose whole job is reading a handful of text elements out of a part
+ * writes a `for..of` over it instead of a {@link parseXml} handler triple whose open and text arms
+ * are the same three lines every time.
+ *
+ * It is deliberately not for every {@link TextCapture} caller. A parser that interleaves capture
+ * with per-element state of its own (a `<dataValidation>` gathering formulae, a `<tableColumn>`
+ * attaching a totals formula to the column it is inside) needs the open and attribute events too,
+ * and stays bespoke; forcing it through here would trade a handler triple for a second pass.
+ *
+ * A self-closing `<x/>` carries no text and fires no close, so it yields nothing, which is the
+ * behaviour {@link TextCapture} exists to make structural rather than a branch each caller
+ * remembers.
+ *
+ * Throws {@link XmlParseError} on malformed markup.
+ */
+export declare function capturedText(source: string, names: string | Iterable<string>): Generator<{
+    local: string;
+    text: string;
+}>;

package/dist/xml/xml-read.js

@@ -28,6 +28,11 @@ export function decodeEntities(value) {
         return named ?? match;
     });
 }
+export function decodeSpreadsheetText(value) {
+    if (!value.includes('_'))
+        return value;
+    return value.replace(/_x([0-9A-Fa-f]{4})_/g, (_match, hex) => String.fromCharCode(parseInt(hex, 16)));
+}
 const ATTRIBUTE = /([^\s=/>]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
 function parseAttributes(source) {
     const attrs = {};
@@ -198,7 +203,72 @@ export function boolTristate(val) {
         return false;
     return undefined;
 }
+export function numInteger(val, min = -Number.MAX_SAFE_INTEGER) {
+    const n = parseAttrNumber(val);
+    if (n === undefined || !Number.isSafeInteger(n) || n < min)
+        return undefined;
+    return n;
+}
+export function numFinite(val, min = -Infinity) {
+    const n = parseAttrNumber(val);
+    if (n === undefined || n < min)
+        return undefined;
+    return n;
+}
+function parseAttrNumber(val) {
+    if (val === undefined || val.trim() === '')
+        return undefined;
+    const n = Number(val);
+    return Number.isFinite(n) ? n : undefined;
+}
 export function coerceNumericLiteral(text) {
     const trimmed = text.trim();
     return /^-?\d+(?:\.\d+)?$/.test(trimmed) ? Number(trimmed) : text;
 }
+export function enumToken(val, isMember) {
+    return val !== undefined && isMember(val) ? val : undefined;
+}
+export class TextCapture {
+    #names;
+    #capturing;
+    #text = '';
+    constructor(names) {
+        this.#names = new Set(typeof names === 'string' ? [names] : names);
+    }
+    get capturing() {
+        return this.#capturing !== undefined;
+    }
+    open(local, selfClosing) {
+        if (selfClosing || !this.#names.has(local))
+            return;
+        this.#capturing = local;
+        this.#text = '';
+    }
+    text(chunk) {
+        if (this.#capturing !== undefined)
+            this.#text += chunk;
+    }
+    close(local) {
+        if (this.#capturing !== local)
+            return undefined;
+        this.#capturing = undefined;
+        return this.#text;
+    }
+}
+export function* capturedText(source, names) {
+    const capture = new TextCapture(names);
+    for (const event of xmlEvents(source)) {
+        if (event.kind === 'open') {
+            capture.open(localName(event.name), event.selfClosing);
+        }
+        else if (event.kind === 'text') {
+            capture.text(event.text);
+        }
+        else {
+            const local = localName(event.name);
+            const text = capture.close(local);
+            if (text !== undefined)
+                yield { local, text };
+        }
+    }
+}