@shbernal/ts-xlsx 1.2.0 → 2.0.0

package/dist/io/xlsx/write.js

@@ -1,8 +1,8 @@
 import { strToU8, zip, zipSync } from 'fflate';
-import { DEFAULT_THEME_XML } from '../../core/theme.js';
 import { AuthoringError } from '../../errors.js';
 import { THEME_PART_PATH } from '../opc/part-paths.js';
 import { relsPartXml } from '../opc/rels.js';
+import { FIXED_ENTRY_MTIME } from '../opc/zip-mtime.js';
 import { collectComments, commentsXml, vmlDrawingXml } from './comments.js';
 import { collectHyperlinks, planHyperlinks } from './hyperlinks.js';
 import { drawingRelsXml, drawingXml } from './images.js';
@@ -12,17 +12,18 @@ import { REL } from './relationships.js';
 import { SharedStringTable } from './shared-strings.js';
 import { StyleRegistry } from './styles.js';
 import { tableXml } from './tables.js';
+import { applyThemeOverrides, DEFAULT_THEME_XML } from './theme-xml.js';
 import { personsXml, threadedCommentsXml } from './threaded-comments.js';
 import { appPropsXml, contentTypesXml, corePropsXml, FIXED_WORKBOOK_REL_COUNT, rootRelsXml, workbookRelsXml, workbookXml, } from './workbook-xml.js';
 import { worksheetRelsXml, worksheetXml, } from './worksheet-xml.js';
 export { buildColumnDefaults, Extent, renderRow, } from './worksheet-xml.js';
 export function writeXlsx(workbook, options = {}) {
-    return zipSync(buildPackageParts(workbook, options), { level: 6 });
+    return zipSync(buildPackageParts(workbook, options), { level: 6, mtime: FIXED_ENTRY_MTIME });
 }
 export async function writeXlsxAsync(workbook, options = {}) {
     const parts = buildPackageParts(workbook, options);
     return await new Promise((resolve, reject) => {
-        zip(parts, { level: 6 }, (error, data) => {
+        zip(parts, { level: 6, mtime: FIXED_ENTRY_MTIME }, (error, data) => {
             if (error)
                 reject(error);
             else
@@ -65,7 +66,7 @@ function resolveSheetReferences(plan) {
 export function buildPackageParts(workbook, options = {}) {
     const sheets = workbook.worksheets;
     if (sheets.length === 0) {
-        throw new AuthoringError('cannot write a workbook with no worksheets — a zero-sheet package is corrupt to Excel');
+        throw new AuthoringError('cannot write a workbook with no worksheets: a zero-sheet package is corrupt to Excel');
     }
     const sharedStrings = options.useSharedStrings ? new SharedStringTable() : null;
     const media = planMedia(workbook, sheets);
@@ -177,13 +178,16 @@ export function buildPackageParts(workbook, options = {}) {
         '[Content_Types].xml': strToU8(contentTypesXml(sheets.length, allTables, commentNumbers, drawingNumbers, printerSettingsNumbers, media.extensions, hasSharedStrings, preserved.parts, allPivots, preservedWorkbookRels, threadedCommentNumbers, persons.length > 0)),
         '_rels/.rels': strToU8(rootRelsXml(preserved.root)),
         'docProps/core.xml': strToU8(corePropsXml(workbook.properties)),
-        'docProps/app.xml': strToU8(appPropsXml()),
+        'docProps/app.xml': strToU8(appPropsXml(workbook.properties)),
         'xl/workbook.xml': strToU8(workbookXml(workbook, preservedWorkbookRels, allPivots)),
         'xl/_rels/workbook.xml.rels': strToU8(workbookRelsXml(sheets.length, hasSharedStrings, personsRelId, preservedWorkbookRels, allPivots)),
         'xl/styles.xml': strToU8(styles.toXml()),
     };
     if (!preserved.themeEmitted) {
-        files[THEME_PART_PATH] = strToU8(workbook.authoredThemeXml() ?? DEFAULT_THEME_XML);
+        const overrides = workbook.themeOverrides;
+        files[THEME_PART_PATH] = strToU8(overrides === undefined
+            ? DEFAULT_THEME_XML
+            : applyThemeOverrides(DEFAULT_THEME_XML, overrides));
     }
     if (hasSharedStrings) {
         files['xl/sharedStrings.xml'] = strToU8(sharedStrings.toXml());

package/dist/io/xlsx/x14-ext.d.ts

@@ -1,7 +1,7 @@
 /**
  * Wrap an x14 extension body in the `<ext>` envelope every worksheet- and workbook-level x14
  * extension shares: a `uri` scoping the extension to its feature (a fixed GUID from
- * {@link namespaces.ts}) plus the `xmlns:x14` binding the extension namespace on the element itself —
+ * {@link namespaces.ts}) plus the `xmlns:x14` binding the extension namespace on the element itself.
  * Excel declares it per `<ext>`, never at the part root. Callers needing an `<extLst>` wrapper add it
  * around the result; the producers the worksheet serialiser gathers return this bare so several exts
  * compose under a single shared `<extLst>`.

package/dist/vba/bytes.d.ts

@@ -0,0 +1,12 @@
+/** Read a little-endian `uint16`. @throws {VbaParseError} if the two bytes are not both in `buf`. */
+export declare function readU16(buf: Uint8Array, at: number): number;
+/** Read a little-endian `uint32`. @throws {VbaParseError} if the four bytes are not all in `buf`. */
+export declare function readU32(buf: Uint8Array, at: number): number;
+/**
+ * Decode UTF-16LE code units: the encoding [MS-CFB] uses for directory-entry names and [MS-OVBA] for
+ * every "Unicode" name field. A trailing odd byte is dropped: these fields are length-prefixed by the
+ * producer and a half code unit carries nothing to decode.
+ */
+export declare function decodeUtf16le(bytes: Uint8Array): string;
+/** Join byte chunks into one buffer. */
+export declare function concat(chunks: Uint8Array[]): Uint8Array;

package/dist/vba/bytes.js

@@ -0,0 +1,40 @@
+import { VbaParseError } from './errors.js';
+function truncated(at, need, length) {
+    return new VbaParseError(`read of ${need} bytes at offset ${at} runs past the end of a ${length}-byte buffer`);
+}
+export function readU16(buf, at) {
+    const b0 = buf[at];
+    const b1 = buf[at + 1];
+    if (b0 === undefined || b1 === undefined)
+        throw truncated(at, 2, buf.length);
+    return b0 | (b1 << 8);
+}
+export function readU32(buf, at) {
+    const b0 = buf[at];
+    const b1 = buf[at + 1];
+    const b2 = buf[at + 2];
+    const b3 = buf[at + 3];
+    if (b0 === undefined || b1 === undefined || b2 === undefined || b3 === undefined) {
+        throw truncated(at, 4, buf.length);
+    }
+    return (b0 | (b1 << 8) | (b2 << 16) | (b3 << 24)) >>> 0;
+}
+export function decodeUtf16le(bytes) {
+    let s = '';
+    for (let i = 0; i + 1 < bytes.length; i += 2) {
+        s += String.fromCharCode(readU16(bytes, i));
+    }
+    return s;
+}
+export function concat(chunks) {
+    let total = 0;
+    for (const c of chunks)
+        total += c.length;
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const c of chunks) {
+        out.set(c, off);
+        off += c.length;
+    }
+    return out;
+}

package/dist/vba/cfb-writer.d.ts

@@ -14,6 +14,6 @@ export type CfbNode = CfbStream | CfbStorage;
  * by linear scan and by tree navigation.
  *
  * @throws {VbaAuthorError} if any name is empty or exceeds 31 characters, sibling names collide, or the
- *   project is so large it would need more than 109 FAT sectors (~7 MB — far beyond any real project).
+ *   project is so large it would need more than 109 FAT sectors (~7 MB, far beyond any real project).
  */
 export declare function writeCompoundFile(root: readonly CfbNode[]): Uint8Array;

package/dist/vba/cfb.d.ts

@@ -8,7 +8,7 @@ export declare class CompoundFile {
     readStream(name: string): Uint8Array | undefined;
     /**
      * Reconstruct the container's top-level children as the writer's node shape, recursing into every
-     * storage — so a caller can swap one stream and re-emit the whole hierarchy with {@link writeCompoundFile}.
+     * storage, so a caller can swap one stream and re-emit the whole hierarchy with {@link writeCompoundFile}.
      * Walks the red-black sibling tree each storage navigates (not the linear directory scan), so any part
      * a host reaches is carried through. Cycle- and bounds-guarded like every other chain walk here.
      */

package/dist/vba/cfb.js

@@ -1,3 +1,4 @@
+import { concat, decodeUtf16le, readU16, readU32 } from './bytes.js';
 import { VbaParseError } from './errors.js';
 const MAX_REGULAR_SECTOR = 0xfffffffa;
 const NOSTREAM = 0xffffffff;
@@ -10,7 +11,6 @@ const CFB_SIGNATURE_HI = 0xe11ab1a1;
 const DIR_ENTRY_SIZE = 128;
 export class CompoundFile {
     #buf;
-    #view;
     #sectorSize;
     #miniSectorSize;
     #miniCutoff;
@@ -21,14 +21,13 @@ export class CompoundFile {
     #miniStream;
     constructor(buf) {
         this.#buf = buf;
-        this.#view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
         if (buf.length < 512)
             throw new VbaParseError('compound file shorter than its 512-byte header');
-        if (this.#u32(0) !== CFB_SIGNATURE_LO || this.#u32(4) !== CFB_SIGNATURE_HI) {
+        if (readU32(this.#buf, 0) !== CFB_SIGNATURE_LO || readU32(this.#buf, 4) !== CFB_SIGNATURE_HI) {
             throw new VbaParseError('not a compound file (bad OLE2 signature)');
         }
-        const sectorShift = this.#u16(30);
-        const miniSectorShift = this.#u16(32);
+        const sectorShift = readU16(this.#buf, 30);
+        const miniSectorShift = readU16(this.#buf, 32);
         if (sectorShift !== 9 && sectorShift !== 12) {
             throw new VbaParseError(`unsupported sector shift ${sectorShift}`);
         }
@@ -37,12 +36,12 @@ export class CompoundFile {
         this.#sectorSize = 1 << sectorShift;
         this.#miniSectorSize = 1 << miniSectorShift;
         this.#maxSector = Math.floor(buf.length / this.#sectorSize);
-        const numFatSectors = this.#u32(44);
-        const firstDirSector = this.#u32(48);
-        this.#miniCutoff = this.#u32(56);
-        const firstMiniFatSector = this.#u32(60);
-        const firstDifatSector = this.#u32(68);
-        const numDifatSectors = this.#u32(72);
+        const numFatSectors = readU32(this.#buf, 44);
+        const firstDirSector = readU32(this.#buf, 48);
+        this.#miniCutoff = readU32(this.#buf, 56);
+        const firstMiniFatSector = readU32(this.#buf, 60);
+        const firstDifatSector = readU32(this.#buf, 68);
+        const numDifatSectors = readU32(this.#buf, 72);
         const fatSectorIds = this.#readDifat(numFatSectors, firstDifatSector, numDifatSectors);
         this.#fat = this.#readFat(fatSectorIds);
         this.#miniFat = this.#readChainValues(firstMiniFatSector);
@@ -103,7 +102,7 @@ export class CompoundFile {
     #readDifat(numFatSectors, firstDifat, numDifat) {
         const ids = [];
         for (let i = 0; i < 109 && ids.length < numFatSectors; i++) {
-            const v = this.#u32(76 + i * 4);
+            const v = readU32(this.#buf, 76 + i * 4);
             if (v >= MAX_REGULAR_SECTOR)
                 break;
             ids.push(v);
@@ -117,11 +116,11 @@ export class CompoundFile {
             seen.add(sector);
             const base = this.#dataSectorOffset(sector);
             for (let i = 0; i < perSector; i++) {
-                const v = this.#u32(base + i * 4);
+                const v = readU32(this.#buf, base + i * 4);
                 if (v < MAX_REGULAR_SECTOR)
                     ids.push(v);
             }
-            sector = this.#u32(base + perSector * 4);
+            sector = readU32(this.#buf, base + perSector * 4);
         }
         return ids;
     }
@@ -131,7 +130,7 @@ export class CompoundFile {
         for (const sid of fatSectorIds) {
             const base = this.#dataSectorOffset(sid);
             for (let i = 0; i < perSector; i++)
-                fat.push(this.#u32(base + i * 4));
+                fat.push(readU32(this.#buf, base + i * 4));
         }
         return fat;
     }
@@ -146,7 +145,7 @@ export class CompoundFile {
             seen.add(sector);
             const base = this.#dataSectorOffset(sector);
             for (let i = 0; i < perSector; i++)
-                values.push(this.#u32(base + i * 4));
+                values.push(readU32(this.#buf, base + i * 4));
             sector = this.#nextInFat(sector);
         }
         return values;
@@ -256,39 +255,4 @@ export class CompoundFile {
         }
         return base;
     }
-    #u16(at) {
-        return this.#view.getUint16(at, true);
-    }
-    #u32(at) {
-        return this.#view.getUint32(at, true);
-    }
-}
-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);
-}
-function decodeUtf16le(bytes) {
-    let s = '';
-    for (let i = 0; i + 1 < bytes.length; i += 2) {
-        s += String.fromCharCode(bytes[i] | (bytes[i + 1] << 8));
-    }
-    return s;
-}
-function concat(chunks) {
-    let total = 0;
-    for (const c of chunks)
-        total += c.length;
-    const out = new Uint8Array(total);
-    let off = 0;
-    for (const c of chunks) {
-        out.set(c, off);
-        off += c.length;
-    }
-    return out;
 }

package/dist/vba/codepage.d.ts

@@ -3,7 +3,7 @@ export type Decoder = InstanceType<typeof TextDecoder>;
 export type Encoder = (text: string) => Uint8Array;
 /**
  * A `TextDecoder` for the given VBA project code page. Non-fatal (malformed bytes become U+FFFD rather
- * than throwing) because recovered source is for reading, not re-encoding — a stray byte must not sink
+ * than throwing) because recovered source is for reading, not re-encoding: a stray byte must not sink
  * the whole extraction. An unknown code page falls back to windows-1252.
  */
 export declare function decoderForCodePage(codePage: number): Decoder;
@@ -12,7 +12,7 @@ export declare function decoderForCodePage(codePage: number): Decoder;
  * decoding every byte 0x00..0xFF through the matching decoder and inverting the map. This is exact for
  * the single-byte code pages a VBA project realistically declares. Under a multi-byte code page (Shift
  * JIS, GBK, …) the high bytes are lead bytes, not standalone characters, so only ASCII inverts and any
- * non-ASCII character is rejected — fail-closed rather than emit a corrupt byte. A character the chosen
+ * non-ASCII character is rejected, failing closed rather than emitting a corrupt byte. A character the chosen
  * code page cannot represent throws {@link VbaAuthorError}.
  */
 export declare function encoderForCodePage(codePage: number): Encoder;

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,5 +1,6 @@
-import { CompoundFile } from './cfb.js';
+import { readU16, readU32 } from './bytes.js';
 import { writeCompoundFile } from './cfb-writer.js';
+import { CompoundFile } from './cfb.js';
 import { decoderForCodePage, encoderForCodePage } from './codepage.js';
 import { VbaAuthorError, VbaParseError } from './errors.js';
 import { compressContainer, decompressContainer } from './ms-ovba.js';
@@ -280,13 +281,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,3 +1,4 @@
+import { readU16, readU32 } from './bytes.js';
 import { CompoundFile } from './cfb.js';
 import { decoderForCodePage } from './codepage.js';
 import { VbaParseError } from './errors.js';
@@ -116,13 +117,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,13 +112,22 @@ 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

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,6 +203,24 @@ 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;