@shbernal/ts-xlsx 2.0.0 → 2.1.0

package/dist/io/xlsx/write-stream.d.ts

@@ -88,7 +88,14 @@ export declare class WorksheetStreamWriter {
      */
     flushRow(number: number, cells: readonly Cell[]): void;
     flushedSheet(): FlushedSheet | undefined;
-    /** Address a cell by its A1 reference to read or style it before the sheet is committed. */
+    /**
+     * Address a cell by its A1 reference to read or style it before the sheet is committed. The row it
+     * names must still be live: a row whose {@link StreamedRow.commit} has run is finished.
+     *
+     * @throws {AuthoringError} if the reference names an already-committed row. That row's `<row>` is
+     *   rendered and its cells are released, so the cell this would materialise could only be written
+     *   as a second row carrying the same number.
+     */
     getCell(reference: string): Cell;
     /**
      * Attach a data validation to a range before the sheet is committed. Delegates to the model, so the

package/dist/io/xlsx/write-stream.js

@@ -1,7 +1,8 @@
 import { createWriteStream } from 'node:fs';
 import { PassThrough } from 'node:stream';
 import { Zip, ZipDeflate } from 'fflate';
-import { encodeAddress } from '../../core/address.js';
+import { concat } from '../../bytes.js';
+import { encodeAddress, tryDecodeCellRef } from '../../core/address.js';
 import { INTERNAL } from '../../core/internal.js';
 import { isSharedFormulaValue } from '../../core/value.js';
 import { Workbook } from '../../core/workbook.js';
@@ -36,6 +37,7 @@ export class WorksheetStreamWriter {
     #lastRow = 0;
     #columnDefaults;
     #flushedRows = [];
+    #flushedNumbers = new Set();
     #extent = new Extent();
     #maxRowOutlineLevel = 0;
     constructor(sheet, eager, styles) {
@@ -97,6 +99,7 @@ export class WorksheetStreamWriter {
             this.#flushedRows.push({ number, xml });
             this.#extent.add(number, minCol, maxCol);
         }
+        this.#flushedNumbers.add(number);
         this.#sheet[INTERNAL].evictRow(number);
     }
     flushedSheet() {
@@ -110,6 +113,12 @@ export class WorksheetStreamWriter {
     }
     getCell(reference) {
         this.#assertOpen();
+        const target = tryDecodeCellRef(reference);
+        if (target !== undefined && this.#flushedNumbers.has(target.row)) {
+            throw new AuthoringError(`cell ${reference} of streamed sheet "${this.#sheet.name}" is in row ${target.row}, which is ` +
+                'already committed: its bytes are written and its cells released, so this value could only ' +
+                'be emitted as a second row with that number. Style a row before committing it.');
+        }
         return this.#sheet.getCell(reference);
     }
     addDataValidation(sqref, rule, options = {}) {
@@ -252,13 +261,3 @@ function streamZipPackage(parts, onChunk) {
         zip.end();
     });
 }
-function concat(chunks) {
-    const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
-    const out = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-        out.set(chunk, offset);
-        offset += chunk.length;
-    }
-    return out;
-}

package/dist/sha512.d.ts

@@ -0,0 +1,2 @@
+/** The SHA-512 digest of `message`, as its 64 bytes. */
+export declare function sha512(message: Uint8Array): Uint8Array;

package/dist/sha512.js

@@ -0,0 +1,146 @@
+const BLOCK_BYTES = 128;
+const DIGEST_BYTES = 64;
+const K = new Uint32Array([
+    0x428a2f98, 0xd728ae22, 0x71374491, 0x23ef65cd, 0xb5c0fbcf, 0xec4d3b2f, 0xe9b5dba5, 0x8189dbbc,
+    0x3956c25b, 0xf348b538, 0x59f111f1, 0xb605d019, 0x923f82a4, 0xaf194f9b, 0xab1c5ed5, 0xda6d8118,
+    0xd807aa98, 0xa3030242, 0x12835b01, 0x45706fbe, 0x243185be, 0x4ee4b28c, 0x550c7dc3, 0xd5ffb4e2,
+    0x72be5d74, 0xf27b896f, 0x80deb1fe, 0x3b1696b1, 0x9bdc06a7, 0x25c71235, 0xc19bf174, 0xcf692694,
+    0xe49b69c1, 0x9ef14ad2, 0xefbe4786, 0x384f25e3, 0x0fc19dc6, 0x8b8cd5b5, 0x240ca1cc, 0x77ac9c65,
+    0x2de92c6f, 0x592b0275, 0x4a7484aa, 0x6ea6e483, 0x5cb0a9dc, 0xbd41fbd4, 0x76f988da, 0x831153b5,
+    0x983e5152, 0xee66dfab, 0xa831c66d, 0x2db43210, 0xb00327c8, 0x98fb213f, 0xbf597fc7, 0xbeef0ee4,
+    0xc6e00bf3, 0x3da88fc2, 0xd5a79147, 0x930aa725, 0x06ca6351, 0xe003826f, 0x14292967, 0x0a0e6e70,
+    0x27b70a85, 0x46d22ffc, 0x2e1b2138, 0x5c26c926, 0x4d2c6dfc, 0x5ac42aed, 0x53380d13, 0x9d95b3df,
+    0x650a7354, 0x8baf63de, 0x766a0abb, 0x3c77b2a8, 0x81c2c92e, 0x47edaee6, 0x92722c85, 0x1482353b,
+    0xa2bfe8a1, 0x4cf10364, 0xa81a664b, 0xbc423001, 0xc24b8b70, 0xd0f89791, 0xc76c51a3, 0x0654be30,
+    0xd192e819, 0xd6ef5218, 0xd6990624, 0x5565a910, 0xf40e3585, 0x5771202a, 0x106aa070, 0x32bbd1b8,
+    0x19a4c116, 0xb8d2d0c8, 0x1e376c08, 0x5141ab53, 0x2748774c, 0xdf8eeb99, 0x34b0bcb5, 0xe19b48a8,
+    0x391c0cb3, 0xc5c95a63, 0x4ed8aa4a, 0xe3418acb, 0x5b9cca4f, 0x7763e373, 0x682e6ff3, 0xd6b2b8a3,
+    0x748f82ee, 0x5defb2fc, 0x78a5636f, 0x43172f60, 0x84c87814, 0xa1f0ab72, 0x8cc70208, 0x1a6439ec,
+    0x90befffa, 0x23631e28, 0xa4506ceb, 0xde82bde9, 0xbef9a3f7, 0xb2c67915, 0xc67178f2, 0xe372532b,
+    0xca273ece, 0xea26619c, 0xd186b8c7, 0x21c0c207, 0xeada7dd6, 0xcde0eb1e, 0xf57d4f7f, 0xee6ed178,
+    0x06f067aa, 0x72176fba, 0x0a637dc5, 0xa2c898a6, 0x113f9804, 0xbef90dae, 0x1b710b35, 0x131c471b,
+    0x28db77f5, 0x23047d84, 0x32caab7b, 0x40c72493, 0x3c9ebe0a, 0x15c9bebc, 0x431d67c4, 0x9c100d4c,
+    0x4cc5d4be, 0xcb3e42b6, 0x597f299c, 0xfc657e2a, 0x5fcb6fab, 0x3ad6faec, 0x6c44198c, 0x4a475817,
+]);
+const INITIAL = new Uint32Array([
+    0x6a09e667, 0xf3bcc908, 0xbb67ae85, 0x84caa73b, 0x3c6ef372, 0xfe94f82b, 0xa54ff53a, 0x5f1d36f1,
+    0x510e527f, 0xade682d1, 0x9b05688c, 0x2b3e6c1f, 0x1f83d9ab, 0xfb41bd6b, 0x5be0cd19, 0x137e2179,
+]);
+function word(words, index) {
+    return words[index] ?? 0;
+}
+export function sha512(message) {
+    const blocks = Math.ceil((message.length + 17) / BLOCK_BYTES);
+    const padded = new Uint8Array(blocks * BLOCK_BYTES);
+    padded.set(message);
+    padded[message.length] = 0x80;
+    const view = new DataView(padded.buffer);
+    const bits = message.length * 8;
+    view.setUint32(padded.length - 8, Math.floor(bits / 0x1_0000_0000), false);
+    view.setUint32(padded.length - 4, bits >>> 0, false);
+    const h = Uint32Array.from(INITIAL);
+    const schedule = new Uint32Array(160);
+    for (let block = 0; block < blocks; block++)
+        compress(h, view, block * BLOCK_BYTES, schedule);
+    const digest = new Uint8Array(DIGEST_BYTES);
+    const out = new DataView(digest.buffer);
+    for (let i = 0; i < 16; i++)
+        out.setUint32(i * 4, word(h, i), false);
+    return digest;
+}
+function compress(h, input, offset, schedule) {
+    for (let t = 0; t < 16; t++) {
+        schedule[t * 2] = input.getUint32(offset + t * 8, false);
+        schedule[t * 2 + 1] = input.getUint32(offset + t * 8 + 4, false);
+    }
+    for (let t = 16; t < 80; t++) {
+        const xHi = word(schedule, (t - 15) * 2);
+        const xLo = word(schedule, (t - 15) * 2 + 1);
+        const s0Hi = ((xHi >>> 1) | (xLo << 31)) ^ ((xHi >>> 8) | (xLo << 24)) ^ (xHi >>> 7);
+        const s0Lo = ((xLo >>> 1) | (xHi << 31)) ^ ((xLo >>> 8) | (xHi << 24)) ^ ((xLo >>> 7) | (xHi << 25));
+        const yHi = word(schedule, (t - 2) * 2);
+        const yLo = word(schedule, (t - 2) * 2 + 1);
+        const s1Hi = ((yHi >>> 19) | (yLo << 13)) ^ ((yLo >>> 29) | (yHi << 3)) ^ (yHi >>> 6);
+        const s1Lo = ((yLo >>> 19) | (yHi << 13)) ^ ((yHi >>> 29) | (yLo << 3)) ^ ((yLo >>> 6) | (yHi << 26));
+        const lo = (s1Lo >>> 0) +
+            word(schedule, (t - 7) * 2 + 1) +
+            (s0Lo >>> 0) +
+            word(schedule, (t - 16) * 2 + 1);
+        const hi = (s1Hi >>> 0) +
+            word(schedule, (t - 7) * 2) +
+            (s0Hi >>> 0) +
+            word(schedule, (t - 16) * 2) +
+            Math.floor(lo / 0x1_0000_0000);
+        schedule[t * 2] = hi >>> 0;
+        schedule[t * 2 + 1] = lo >>> 0;
+    }
+    let aHi = word(h, 0);
+    let aLo = word(h, 1);
+    let bHi = word(h, 2);
+    let bLo = word(h, 3);
+    let cHi = word(h, 4);
+    let cLo = word(h, 5);
+    let dHi = word(h, 6);
+    let dLo = word(h, 7);
+    let eHi = word(h, 8);
+    let eLo = word(h, 9);
+    let fHi = word(h, 10);
+    let fLo = word(h, 11);
+    let gHi = word(h, 12);
+    let gLo = word(h, 13);
+    let hHi = word(h, 14);
+    let hLo = word(h, 15);
+    for (let t = 0; t < 80; t++) {
+        const bigS1Hi = ((eHi >>> 14) | (eLo << 18)) ^ ((eHi >>> 18) | (eLo << 14)) ^ ((eLo >>> 9) | (eHi << 23));
+        const bigS1Lo = ((eLo >>> 14) | (eHi << 18)) ^ ((eLo >>> 18) | (eHi << 14)) ^ ((eHi >>> 9) | (eLo << 23));
+        const chHi = (eHi & fHi) ^ (~eHi & gHi);
+        const chLo = (eLo & fLo) ^ (~eLo & gLo);
+        const t1Lo = hLo + (bigS1Lo >>> 0) + (chLo >>> 0) + word(K, t * 2 + 1) + word(schedule, t * 2 + 1);
+        const t1Hi = (hHi +
+            (bigS1Hi >>> 0) +
+            (chHi >>> 0) +
+            word(K, t * 2) +
+            word(schedule, t * 2) +
+            Math.floor(t1Lo / 0x1_0000_0000)) >>>
+            0;
+        const t1LoWrapped = t1Lo >>> 0;
+        const bigS0Hi = ((aHi >>> 28) | (aLo << 4)) ^ ((aLo >>> 2) | (aHi << 30)) ^ ((aLo >>> 7) | (aHi << 25));
+        const bigS0Lo = ((aLo >>> 28) | (aHi << 4)) ^ ((aHi >>> 2) | (aLo << 30)) ^ ((aHi >>> 7) | (aLo << 25));
+        const majHi = (aHi & bHi) ^ (aHi & cHi) ^ (bHi & cHi);
+        const majLo = (aLo & bLo) ^ (aLo & cLo) ^ (bLo & cLo);
+        const t2Lo = (bigS0Lo >>> 0) + (majLo >>> 0);
+        const t2Hi = ((bigS0Hi >>> 0) + (majHi >>> 0) + Math.floor(t2Lo / 0x1_0000_0000)) >>> 0;
+        const t2LoWrapped = t2Lo >>> 0;
+        hHi = gHi;
+        hLo = gLo;
+        gHi = fHi;
+        gLo = fLo;
+        fHi = eHi;
+        fLo = eLo;
+        const nextELo = dLo + t1LoWrapped;
+        eHi = (dHi + t1Hi + Math.floor(nextELo / 0x1_0000_0000)) >>> 0;
+        eLo = nextELo >>> 0;
+        dHi = cHi;
+        dLo = cLo;
+        cHi = bHi;
+        cLo = bLo;
+        bHi = aHi;
+        bLo = aLo;
+        const nextALo = t1LoWrapped + t2LoWrapped;
+        aHi = (t1Hi + t2Hi + Math.floor(nextALo / 0x1_0000_0000)) >>> 0;
+        aLo = nextALo >>> 0;
+    }
+    addInto(h, 0, aHi, aLo);
+    addInto(h, 2, bHi, bLo);
+    addInto(h, 4, cHi, cLo);
+    addInto(h, 6, dHi, dLo);
+    addInto(h, 8, eHi, eLo);
+    addInto(h, 10, fHi, fLo);
+    addInto(h, 12, gHi, gLo);
+    addInto(h, 14, hHi, hLo);
+}
+function addInto(h, index, hi, lo) {
+    const sumLo = word(h, index + 1) + lo;
+    h[index] = (word(h, index) + hi + Math.floor(sumLo / 0x1_0000_0000)) >>> 0;
+    h[index + 1] = sumLo >>> 0;
+}

package/dist/vba/bytes.d.ts

@@ -1,3 +1,4 @@
+export { concat } from '../bytes.ts';
 /** 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`. */
@@ -8,5 +9,3 @@ export declare function readU32(buf: Uint8Array, at: number): number;
  * 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

@@ -1,3 +1,4 @@
+export { concat } from '../bytes.js';
 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`);
@@ -26,15 +27,3 @@ export function decodeUtf16le(bytes) {
     }
     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/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/project-editor.js

@@ -1,7 +1,8 @@
-import { readU16, readU32 } from './bytes.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';
@@ -10,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();
@@ -124,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;
@@ -157,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');
@@ -183,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;

package/dist/vba/project.js

@@ -1,6 +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';
@@ -14,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');
@@ -31,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)

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

@@ -134,3 +134,63 @@ export declare function numFinite(val: string | undefined, min?: number): number
  * 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

@@ -225,3 +225,50 @@ 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 };
+        }
+    }
+}

package/dist/xml/xml.d.ts

@@ -50,11 +50,53 @@ export declare function stripFormulaEquals(value: string | number): string;
  * entirely: the two-state-plus-absent contract every flag writer here shares.
  */
 export declare function boolAttr(name: string, value: boolean | undefined): string;
+/**
+ * A free-string attribute rendered with a leading space (` name="a & b"`), or '' when the value
+ * is undefined. The third of the trio with {@link boolAttr} and {@link numAttr}: the value is prose
+ * the caller chose, so it is escaped rather than checked.
+ *
+ * A token from a closed OOXML enumeration is the other case and goes through {@link checkedToken}
+ * instead. Escaping a bogus token would produce a well-formed document that Excel still rejects,
+ * which hides the mistake in the file rather than raising it at the call.
+ */
+export declare function textAttr(name: string, value: string | undefined): string;
+/**
+ * Refuse a token from a closed OOXML enumeration that the writer would otherwise emit verbatim, and
+ * return it unchanged when it belongs. The public types already forbid an out-of-contract value, so
+ * this fires only for one smuggled past them by an untyped caller, a `JSON.parse`, or a cast.
+ *
+ * The writer must never serialise such a value: it would be schema-invalid OOXML that Excel
+ * sometimes tolerates yet the library's own reader, which narrows every such token through the same
+ * guard, discards on read-back. Refusing at the write boundary keeps the two symmetric, garbage out
+ * refused exactly as garbage in, so a value the writer accepts is always one that round-trips.
+ *
+ * @throws {AuthoringError} naming the value and the enumeration.
+ */
+export declare function checkedToken(value: string, isValid: (candidate: string) => boolean, kind: string): string;
 /**
  * A numeric attribute rendered with a leading space (` name="42"`), or '' when the value is undefined
  * so that a count an author never set stays out of the element rather than fabricating a default.
+ *
+ * The value goes through {@link numberText}, so a non-finite one is refused here rather than written
+ * as `NaN`. Every attribute on this path is `xsd:double` or `xsd:unsignedInt`, neither of which has a
+ * spelling for it, so the alternative is a package Excel reports as damaged.
+ *
+ * @throws {AuthoringError} when the value is not finite.
+ */
+export declare function numAttr(name: string, value: number | undefined): string;
+/**
+ * Refuse a number OOXML cannot spell. Every numeric attribute in the format is `xsd:double`,
+ * `xsd:unsignedInt` or a bounded flavour of one, and none of those lexical spaces has a form for a
+ * NaN or an infinity, so a value that reaches the file as `NaN` is a package Excel reports as
+ * damaged.
+ *
+ * Exported for the callers that must refuse before they write. A number can be unwritable and still
+ * be read on the way to the bytes: compared, summed, walked. A comparison against `NaN` or an
+ * infinity silently takes the wrong branch long before the value would have been serialised.
+ *
+ * @throws {AuthoringError} naming the value.
  */
-export declare function attr(name: string, value: number | undefined): string;
+export declare function assertWritableNumber(value: number): void;
 /**
  * A finite number serialises as its shortest round-trippable decimal; a non-finite one
  * has no OOXML numeric representation, so the writer refuses it rather than emit `NaN`.

package/dist/xml/xml.js

@@ -55,13 +55,25 @@ export function stripFormulaEquals(value) {
 export function boolAttr(name, value) {
     return value === undefined ? '' : ` ${name}="${value ? 1 : 0}"`;
 }
-export function attr(name, value) {
-    return value === undefined ? '' : ` ${name}="${value}"`;
+export function textAttr(name, value) {
+    return value === undefined ? '' : ` ${name}="${escapeAttr(value)}"`;
 }
-export function numberText(value) {
-    if (!Number.isFinite(value)) {
-        throw new AuthoringError(`cannot write a non-finite number (${value}): it has no OOXML representation`);
+export function checkedToken(value, isValid, kind) {
+    if (!isValid(value)) {
+        throw new AuthoringError(`Invalid ${kind} ${JSON.stringify(value)}: not a value the OOXML enumeration allows`);
     }
+    return value;
+}
+export function numAttr(name, value) {
+    return value === undefined ? '' : ` ${name}="${numberText(value)}"`;
+}
+export function assertWritableNumber(value) {
+    if (Number.isFinite(value))
+        return;
+    throw new AuthoringError(`cannot write a non-finite number (${value}): it has no OOXML representation`);
+}
+export function numberText(value) {
+    assertWritableNumber(value);
     return String(value);
 }
 export const XML_DECLARATION = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';