@shbernal/ts-xlsx 1.0.3 → 1.2.0

package/dist/vba/cfb-writer.js

@@ -1,31 +1,17 @@
-// Writer for the OLE2 / Compound File Binary format ([MS-CFB]) — the encode counterpart to cfb.ts.
-//
-// Produces a v3 (512-byte sector) container from a hierarchy of storages and streams, the substrate a
-// synthesized vbaProject.bin is built on (its modules live inside a `VBA` storage, with `PROJECT` and
-// `PROJECTwm` at the root). Streams below the 4096-byte mini cutoff are packed into the mini stream and
-// chained through the mini-FAT; larger streams take whole regular sectors. Each storage's children are
-// emitted as a name-ordered balanced binary tree ([MS-CFB] 2.6.4), so a host that *navigates* the tree
-// (Excel) reaches every entry — not only a linear scanner like this library's own reader.
-//
-// Unlike the reader, this is not a hostile-input path: we are the producer. It still validates its
-// contract (name length, sibling-name uniqueness, size bound) and fails closed with VbaAuthorError,
-// because a silently malformed container would surface far downstream as an unopenable workbook.
 import { VbaAuthorError } from './errors.js';
 const SECTOR = 512;
 const MINI_SECTOR = 64;
 const MINI_CUTOFF = 4096;
 const DIR_ENTRY_SIZE = 128;
-const ENTRIES_PER_DIR_SECTOR = SECTOR / DIR_ENTRY_SIZE; // 4
-const FAT_ENTRIES_PER_SECTOR = SECTOR / 4; // 128
-const DIFAT_HEADER_SLOTS = 109; // FAT-sector pointers that fit in the header before DIFAT sectors
-const MAX_NAME_CHARS = 31; // 32 UTF-16 code units incl. the NUL terminator
-// Sector chain markers ([MS-CFB] 2.2).
+const ENTRIES_PER_DIR_SECTOR = SECTOR / DIR_ENTRY_SIZE;
+const FAT_ENTRIES_PER_SECTOR = SECTOR / 4;
+const DIFAT_HEADER_SLOTS = 109;
+const MAX_NAME_CHARS = 31;
 const FREESECT = 0xffffffff;
 const ENDOFCHAIN = 0xfffffffe;
 const FATSECT = 0xfffffffd;
 const DIFSECT = 0xfffffffc;
 const NOSTREAM = 0xffffffff;
-// Object types ([MS-CFB] 2.6.1).
 const TYPE_STORAGE = 1;
 const TYPE_STREAM = 2;
 const TYPE_ROOT = 5;
@@ -33,14 +19,6 @@ const COLOR_BLACK = 1;
 function isStream(node) {
     return 'data' in node;
 }
-/**
- * Encode a hierarchy of storages and streams into a v3 compound file. The Root Entry is synthesized
- * automatically; `root` is its top-level children. Every stream becomes a directory entry reachable both
- * 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).
- */
 export function writeCompoundFile(root) {
     const entries = [];
     const addEntry = (name, type, startSector) => {
@@ -58,20 +36,15 @@ export function writeCompoundFile(root) {
         return entry;
     };
     const rootEntry = addEntry('Root Entry', TYPE_ROOT, ENDOFCHAIN);
-    // Sub-cutoff stream bytes accumulate into the mini stream (chained in the mini-FAT); larger streams
-    // are laid out later directly in the regular FAT. Depth-first walk fixes a deterministic layout.
     const miniBytes = [];
     const miniFat = [];
     const bigStreams = [];
-    // `siblings` is the parent's child list itself rather than its index, so a child is appended to an
-    // array we hold — no lookup that could come back empty.
     const addNode = (node, siblings) => {
         if (isStream(node)) {
             const entry = addEntry(node.name, TYPE_STREAM, ENDOFCHAIN);
             entry.size = node.data.length;
             siblings.push(entry);
             if (node.data.length === 0) {
-                // an empty stream owns no sectors
             }
             else if (node.data.length >= MINI_CUTOFF) {
                 bigStreams.push({ entry, data: node.data, sectors: Math.ceil(node.data.length / SECTOR) });
@@ -91,7 +64,6 @@ export function writeCompoundFile(root) {
             const kids = [];
             for (const c of node.children)
                 addNode(c, kids);
-            // Each storage (Root included) links its children as a balanced search tree the host navigates.
             linkChildren(entry, kids);
         }
     };
@@ -100,9 +72,6 @@ export function writeCompoundFile(root) {
     for (const n of root)
         addNode(n, rootKids);
     linkChildren(rootEntry, rootKids);
-    // ── Sector layout ─────────────────────────────────────────────────────────────────────────────────
-    // Physical order: directory, mini-FAT, mini stream, each big stream, FAT, DIFAT. Region starts are
-    // assigned first so chains can reference them; the FAT is filled last, once every sector is placed.
     const dirSectors = Math.ceil(entries.length / ENTRIES_PER_DIR_SECTOR);
     const miniFatSectors = miniFat.length > 0 ? Math.ceil((miniFat.length * 4) / FAT_ENTRIES_PER_SECTOR) : 0;
     const miniStreamSectors = Math.ceil(miniBytes.length / SECTOR);
@@ -115,7 +84,6 @@ export function writeCompoundFile(root) {
     for (;;) {
         const total = baseSectors + fatSectors + difatSectors;
         const needFat = Math.ceil(total / FAT_ENTRIES_PER_SECTOR);
-        // Each DIFAT sector holds 127 FAT pointers + a next-DIFAT pointer; the first 109 live in the header.
         const needDifat = needFat > DIFAT_HEADER_SLOTS
             ? Math.ceil((needFat - DIFAT_HEADER_SLOTS) / (FAT_ENTRIES_PER_SECTOR - 1))
             : 0;
@@ -145,7 +113,6 @@ export function writeCompoundFile(root) {
     const totalSectors = cursor;
     rootEntry.startSector = miniStreamStart;
     rootEntry.size = miniBytes.length;
-    // ── FAT ─────────────────────────────────────────────────────────────────────────────────────────
     const fat = new Array(fatSectors * FAT_ENTRIES_PER_SECTOR).fill(FREESECT);
     const chainRegion = (start, count) => {
         for (let k = 0; k < count; k++)
@@ -162,8 +129,7 @@ export function writeCompoundFile(root) {
         fat[fatStart + k] = FATSECT;
     for (let k = 0; k < difatSectors; k++)
         fat[difatStart + k] = DIFSECT;
-    // ── Serialize ──────────────────────────────────────────────────────────────────────────────────
-    const buf = new Uint8Array((totalSectors + 1) * SECTOR); // +1 for the header sector
+    const buf = new Uint8Array((totalSectors + 1) * SECTOR);
     const dv = new DataView(buf.buffer);
     const at = (sector) => (sector + 1) * SECTOR;
     writeHeader(dv, {
@@ -180,16 +146,12 @@ export function writeCompoundFile(root) {
     for (let i = 0; i < miniFatSectors * FAT_ENTRIES_PER_SECTOR; i++) {
         dv.setUint32(at(miniFatStart) + i * 4, miniFat[i] ?? FREESECT, true);
     }
-    // Guarded rather than looped-and-skipped: with no mini stream, miniStreamStart is ENDOFCHAIN and
-    // `at()` of it is far outside the buffer, which a zero-length `set` would still reject.
     if (miniBytes.length > 0)
         buf.set(Uint8Array.from(miniBytes), at(miniStreamStart));
     for (const big of bigStreams)
         buf.set(big.data, at(big.entry.startSector));
     for (const [i, sector] of fat.entries())
         dv.setUint32(at(fatStart) + i * 4, sector, true);
-    // DIFAT sectors carry FAT-sector pointers 110.. (unreachable under the enforced bound, but the layout
-    // is honoured: each DIFAT sector's tail points to the next, the last to ENDOFCHAIN).
     for (let d = 0; d < difatSectors; d++) {
         const base = at(difatStart + d);
         for (let i = 0; i < FAT_ENTRIES_PER_SECTOR - 1; i++) {
@@ -216,13 +178,6 @@ function validateSiblingNames(storageName, siblings) {
             validateSiblingNames(node.name, node.children);
     }
 }
-// Order a storage's children by the [MS-CFB] 2.6.4 comparison (shorter names sort first; ties broken by
-// uppercased UTF-16 code units) and link them as a balanced binary tree. A host locates a child by
-// walking this tree from the storage's `child` pointer, so the ordering and links must form a valid
-// search tree.
-//
-// The recursion halves a slice rather than a lo/hi index pair, which makes "the slice is empty" and
-// "there is no midpoint entry" the same observable fact: the `undefined` check *is* the base case.
 function linkChildren(storage, kids) {
     const build = (nodes) => {
         const mid = nodes.length >> 1;
@@ -243,13 +198,13 @@ function compareNames(a, b) {
     return ua < ub ? -1 : ua > ub ? 1 : 0;
 }
 function writeHeader(dv, p) {
-    dv.setUint32(0, 0xe011cfd0, true); // OLE2 signature (lo/hi)
+    dv.setUint32(0, 0xe011cfd0, true);
     dv.setUint32(4, 0xe11ab1a1, true);
-    dv.setUint16(24, 0x003e, true); // minor version
-    dv.setUint16(26, 0x0003, true); // major version → v3 (512-byte sectors)
-    dv.setUint16(28, 0xfffe, true); // little-endian byte order mark
-    dv.setUint16(30, 9, true); // sector shift → 512
-    dv.setUint16(32, 6, true); // mini-sector shift → 64
+    dv.setUint16(24, 0x003e, true);
+    dv.setUint16(26, 0x0003, true);
+    dv.setUint16(28, 0xfffe, true);
+    dv.setUint16(30, 9, true);
+    dv.setUint16(32, 6, true);
     dv.setUint32(44, p.fatSectors, true);
     dv.setUint32(48, p.dirStart, true);
     dv.setUint32(56, MINI_CUTOFF, true);
@@ -257,7 +212,6 @@ function writeHeader(dv, p) {
     dv.setUint32(64, p.miniFatSectors, true);
     dv.setUint32(68, p.difatSectors > 0 ? p.difatStart : ENDOFCHAIN, true);
     dv.setUint32(72, p.difatSectors, true);
-    // Header DIFAT: the first 109 FAT-sector pointers. Contiguous from fatStart under the enforced bound.
     for (let i = 0; i < DIFAT_HEADER_SLOTS; i++) {
         dv.setUint32(76 + i * 4, i < p.fatSectors ? p.fatStart + i : FREESECT, true);
     }
@@ -265,7 +219,7 @@ function writeHeader(dv, p) {
 function writeDirEntry(dv, off, e) {
     for (let i = 0; i < e.name.length; i++)
         dv.setUint16(off + i * 2, e.name.charCodeAt(i), true);
-    dv.setUint16(off + 64, (e.name.length + 1) * 2, true); // name byte length incl. NUL terminator
+    dv.setUint16(off + 64, (e.name.length + 1) * 2, true);
     dv.setUint8(off + 66, e.type);
     dv.setUint8(off + 67, COLOR_BLACK);
     dv.setUint32(off + 68, e.left, true);
@@ -273,5 +227,4 @@ function writeDirEntry(dv, off, e) {
     dv.setUint32(off + 76, e.child, true);
     dv.setUint32(off + 116, e.startSector, true);
     dv.setUint32(off + 120, e.size, true);
-    // Size high (124), CLSID (80..95), state/time fields stay zero — valid for a v3 entry.
 }

package/dist/vba/cfb.js

@@ -1,18 +1,4 @@
-// Reader for the OLE2 / Compound File Binary format ([MS-CFB]).
-//
-// `vbaProject.bin` is a CFB container (the same "structured storage" behind legacy .doc/.xls). We read
-// streams by name and, for the edit-in-place path, reconstruct the whole storage/stream hierarchy so it
-// can be re-emitted through the writer with one stream swapped — so this is a deliberate subset of
-// [MS-CFB]: header → FAT → directory, plus the mini-FAT for sub-cutoff streams, and the red-black
-// sibling tree each storage navigates.
-//
-// It parses an untrusted blob, so every sector index, chain, and stream size is bounds-checked against
-// the file and every chain walk is cycle-guarded. A malformed container fails closed with a
-// VbaParseError instead of reading out of bounds, looping forever, or over-allocating.
 import { VbaParseError } from './errors.js';
-// Sector values 0xFFFFFFFA..0xFFFFFFFF are reserved markers (DIFSECT/FATSECT/ENDOFCHAIN/FREESECT), not
-// data-sector indices; any value at or above this is chain-terminal. Directory-tree links reuse the same
-// convention: NOSTREAM (0xFFFFFFFF) and any value at or above the ceiling mean "no such sibling/child".
 const MAX_REGULAR_SECTOR = 0xfffffffa;
 const NOSTREAM = 0xffffffff;
 const TYPE_EMPTY = 0;
@@ -43,7 +29,6 @@ export class CompoundFile {
         }
         const sectorShift = this.#u16(30);
         const miniSectorShift = this.#u16(32);
-        // [MS-CFB] fixes these: 512-byte sectors (shift 9) for v3, 4096 (shift 12) for v4; mini shift 6.
         if (sectorShift !== 9 && sectorShift !== 12) {
             throw new VbaParseError(`unsupported sector shift ${sectorShift}`);
         }
@@ -65,28 +50,19 @@ export class CompoundFile {
         const root = this.#dir.find((e) => e.type === TYPE_ROOT);
         if (!root)
             throw new VbaParseError('compound file has no root storage entry');
-        // The mini-stream lives in the regular FAT, addressed from the root entry's start sector.
         this.#miniStream = this.#readViaFat(root.startSector, root.size);
     }
-    /** List every stream/storage name in the directory (order as stored). */
     names() {
         return this.#dir
             .filter((e) => e.type === TYPE_STREAM || e.type === TYPE_STORAGE)
             .map((e) => e.name);
     }
-    /** Read a stream's raw bytes by exact entry name, or `undefined` if absent. */
     readStream(name) {
         const entry = this.#dir.find((e) => e.type === TYPE_STREAM && e.name === name);
         if (!entry)
             return undefined;
         return this.#readEntryData(entry);
     }
-    /**
-     * 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}.
-     * 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.
-     */
     tree() {
         const rootIdx = this.#dir.findIndex((e) => e.type === TYPE_ROOT);
         if (rootIdx < 0)
@@ -98,7 +74,7 @@ export class CompoundFile {
         const nodes = [];
         const walk = (idx) => {
             if (idx >= MAX_REGULAR_SECTOR)
-                return; // NOSTREAM / terminal marker → no such sibling
+                return;
             if (idx >= this.#dir.length)
                 throw new VbaParseError('directory sibling index out of range');
             if (seen.has(idx))
@@ -126,7 +102,6 @@ export class CompoundFile {
     }
     #readDifat(numFatSectors, firstDifat, numDifat) {
         const ids = [];
-        // The first 109 FAT-sector pointers live in the header; the rest chain through DIFAT sectors.
         for (let i = 0; i < 109 && ids.length < numFatSectors; i++) {
             const v = this.#u32(76 + i * 4);
             if (v >= MAX_REGULAR_SECTOR)
@@ -161,7 +136,6 @@ export class CompoundFile {
         return fat;
     }
     #readChainValues(firstSector) {
-        // Every uint32 in a sector chain (used for the mini-FAT), cycle-guarded.
         const values = [];
         const perSector = this.#sectorSize / 4;
         const seen = new Set();
@@ -180,8 +154,6 @@ export class CompoundFile {
     #readDirectory(firstDirSector) {
         const raw = this.#readChainFull(firstDirSector);
         const entries = [];
-        // Empty slots are kept as placeholders (not skipped) so array indices stay equal to the on-disk
-        // directory-entry ids the sibling-tree links reference — the tree walk in #buildSiblings needs them.
         for (let off = 0; off + DIR_ENTRY_SIZE <= raw.length; off += DIR_ENTRY_SIZE) {
             const type = raw[off + 66];
             if (type !== TYPE_EMPTY &&
@@ -211,14 +183,12 @@ export class CompoundFile {
             }
             const name = decodeUtf16le(raw.subarray(off, off + Math.max(0, nameLen - 2)));
             const startSector = readU32(raw, off + 116);
-            const size = readU32(raw, off + 120); // low 32 bits — ample for a VBA project
+            const size = readU32(raw, off + 120);
             entries.push({ name, type, startSector, size, left, right, child });
         }
         return entries;
     }
     #readChainFull(startSector) {
-        // Follow a FAT chain to its end, collecting whole sectors (used for the directory, whose byte
-        // length is not declared). Cycle-guarded and bounded by the sector count.
         const chunks = [];
         const seen = new Set();
         let sector = startSector;

package/dist/vba/codepage.js

@@ -1,11 +1,4 @@
-// The VBA project stores module names and source as MBCS bytes in the project code page
-// (`PROJECTCODEPAGE`, [MS-OVBA] 2.3.4.2). To recover text we decode those bytes with the matching
-// encoding rather than assuming latin1 — a CJK or Cyrillic project would otherwise mojibake.
 import { VbaAuthorError, VbaParseError } from './errors.js';
-// Windows code-page numbers → the WHATWG encoding label `TextDecoder` understands. Node's built-in
-// ICU covers all of these. Only the code pages a VBA project realistically declares are listed; an
-// unlisted one falls back to windows-1252 (the overwhelmingly common Western-European default) so a
-// rare project still decodes readably instead of throwing.
 const CODEPAGE_LABEL = new Map([
     [1250, 'windows-1250'],
     [1251, 'windows-1251'],
@@ -28,19 +21,12 @@ const CODEPAGE_LABEL = new Map([
     [28592, 'iso-8859-2'],
     [65001, 'utf-8'],
 ]);
-/**
- * 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
- * the whole extraction. An unknown code page falls back to windows-1252.
- */
 export function decoderForCodePage(codePage) {
     const label = CODEPAGE_LABEL.get(codePage) ?? 'windows-1252';
     try {
         return new TextDecoder(label, { fatal: false });
     }
     catch {
-        // A runtime whose ICU lacks the label (a minimal build) still gets usable Western-European text
-        // rather than a hard failure on an otherwise-valid project.
         try {
             return new TextDecoder('windows-1252', { fatal: false });
         }
@@ -51,14 +37,6 @@ export function decoderForCodePage(codePage) {
         }
     }
 }
-/**
- * The write-side inverse of {@link decoderForCodePage}: an encoder for a project's code page, built by
- * 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
- * code page cannot represent throws {@link VbaAuthorError}.
- */
 export function encoderForCodePage(codePage) {
     const decoder = decoderForCodePage(codePage);
     const charToByte = new Map();
@@ -67,7 +45,7 @@ export function encoderForCodePage(codePage) {
         one[0] = b;
         const decoded = decoder.decode(one);
         if (decoded.length !== 1)
-            continue; // a lead byte / incomplete sequence under a multi-byte code page
+            continue;
         const code = decoded.charCodeAt(0);
         if (code !== 0xfffd && !charToByte.has(code))
             charToByte.set(code, b);

package/dist/vba/errors.js

@@ -1,23 +1,8 @@
 import { XlsxError } from '../errors.js';
-/**
- * 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.
- *
- * The parser treats the blob as hostile input (a spreadsheet library parses untrusted files), so every
- * malformed structure fails closed with this error rather than crashing, hanging, or over-allocating.
- */
 export class VbaParseError extends XlsxError {
     name = 'VbaParseError';
     code = 'malformed-input';
 }
-/**
- * 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
- * [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).
- */
 export class VbaAuthorError extends XlsxError {
     name = 'VbaAuthorError';
     code = 'authoring';

package/dist/vba/index.js

@@ -1,13 +1,3 @@
-// Native VBA read, plus pure-TS structural edits: decode a macro-enabled workbook's `vbaProject.bin`
-// into readable module source, and remove a module or add a library reference from an existing project
-// by splicing the original bytes (every module's compiled p-code preserved untouched).
-//
-// Authoring or editing module SOURCE is NOT here. Excel runs a module's compiled p-code, not its source,
-// and only a real Excel can produce source-matched p-code — so that lives in the offline
-// `tools/vba-compiler` (VBIDE), whose output is attached via `Workbook.vbaProjectBytes`. The read path
-// is a projection over bytes the model preserves opaquely on round-trip. For the design invariants and
-// the wider VBA feature map see the ADRs: read view (docs/decisions/0016), authoring (0017/0019), and
-// structural edits (0018/0019), plus docs/knowledge/specs/xlsm-macro-preservation.md.
 export { writeCompoundFile, } from './cfb-writer.js';
 export { VbaAuthorError, VbaParseError } from './errors.js';
 export { compressContainer, decompressContainer } from './ms-ovba.js';

package/dist/vba/ms-ovba.js

@@ -1,29 +1,8 @@
-// MS-OVBA §2.4.1 — compression and decompression of a "CompressedContainer".
-//
-// VBA module source and the project `dir` stream are stored in Office's own run-length compression,
-// NOT deflate. A container is a 0x01 signature byte followed by one or more chunks; each chunk
-// decompresses to at most 4096 bytes and is either a raw 4096-byte copy or a stream of literal/copy
-// tokens. Reference: [MS-OVBA] 2.4.1.3.6 (decompressing a CompressedContainer), 2.4.1.3.19.3 (the
-// CopyToken bit-packing), and 2.4.1.3.7 (compressing a chunk).
-//
-// The decompressor is a hostile-input parser: the container comes from an untrusted file, so every
-// length and back-reference is bounds-checked and the total output is capped. A malformed container
-// fails closed with a VbaParseError rather than over-allocating, looping, or reading out of bounds. The
-// compressor is the authoring inverse — it is fed our own bytes, and its output re-expands to the input
-// byte-for-byte (the round-trip is the correctness contract).
 import { VbaParseError } from './errors.js';
-// A decompressed chunk covers at most 4096 bytes; both directions honour this window ([MS-OVBA]
-// 2.4.1.3.6). The chunk header's bits 12-14 carry a fixed 0b011 signature, bit 15 the compressed flag.
 const MAX_CHUNK_DECOMPRESSED = 4096;
 const CHUNK_SIGNATURE = 0b011 << 12;
 const CHUNK_COMPRESSED_FLAG = 0x8000;
-// A single VBA project is well under a megabyte; 64 MiB is far above any legitimate container yet
-// bounds a decompression bomb (a small container that expands without limit) to a survivable size.
 const DEFAULT_MAX_OUTPUT = 64 * 1024 * 1024;
-/**
- * Decompress an MS-OVBA CompressedContainer beginning at `start` in `buf`.
- * @param maxOutput hard ceiling on decompressed bytes; exceeding it throws (bomb guard).
- */
 export function decompressContainer(buf, start = 0, maxOutput = DEFAULT_MAX_OUTPUT) {
     if (start >= buf.length) {
         throw new VbaParseError(`compressed container starts past end of stream (${start} >= ${buf.length})`);
@@ -36,7 +15,6 @@ export function decompressContainer(buf, start = 0, maxOutput = DEFAULT_MAX_OUTP
     while (pos + 2 <= buf.length) {
         const header = readU16(buf, pos);
         pos += 2;
-        // Bits 0-11: (chunk data size - 1). Bit 15: compressed flag. Bits 12-14: the fixed 0b011 signature.
         const chunkDataSize = (header & 0x0fff) + 1;
         const compressed = (header & 0x8000) !== 0;
         if (((header >> 12) & 0x7) !== 0b011) {
@@ -47,14 +25,13 @@ export function decompressContainer(buf, start = 0, maxOutput = DEFAULT_MAX_OUTP
             throw new VbaParseError(`chunk data (${chunkDataSize} bytes) runs past end of stream`);
         }
         if (!compressed) {
-            // A raw chunk carries its bytes verbatim (Excel emits one only when compression would expand).
             for (let i = pos; i < chunkEnd; i++)
                 out.push(buf[i]);
             guardOutput(out.length, maxOutput);
             pos = chunkEnd;
             continue;
         }
-        const chunkStart = out.length; // decompressed offset where this chunk began
+        const chunkStart = out.length;
         while (pos < chunkEnd) {
             const flagByte = buf[pos++];
             for (let bit = 0; bit < 8 && pos < chunkEnd; bit++) {
@@ -74,10 +51,8 @@ export function decompressContainer(buf, start = 0, maxOutput = DEFAULT_MAX_OUTP
                 const copyOffset = (token >> (16 - bitCount)) + 1;
                 const src = out.length - copyOffset;
                 if (src < chunkStart) {
-                    // A back-reference may only reach data emitted since this chunk began ([MS-OVBA] 2.4.1.3.19).
                     throw new VbaParseError('copy token references before the start of its chunk');
                 }
-                // Byte-by-byte so overlapping runs (run-length expansion) grow correctly.
                 for (let i = 0; i < length; i++)
                     out.push(out[src + i]);
                 guardOutput(out.length, maxOutput);
@@ -87,19 +62,11 @@ export function decompressContainer(buf, start = 0, maxOutput = DEFAULT_MAX_OUTP
     }
     return Uint8Array.from(out);
 }
-/**
- * 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.
- */
 export function compressContainer(data) {
-    const out = [0x01]; // container signature; an empty input yields just this byte
+    const out = [0x01];
     for (let start = 0; start < data.length; start += MAX_CHUNK_DECOMPRESSED) {
         const chunk = data.subarray(start, Math.min(start + MAX_CHUNK_DECOMPRESSED, data.length));
         const tokens = compressChunk(chunk);
-        // Prefer the token stream only when it is strictly smaller; otherwise store the chunk raw. Both
-        // encode their exact length in the header, so the decompressor reconstructs the window either way.
         const compressed = tokens.length < chunk.length;
         const body = compressed ? tokens : chunk;
         const header = (compressed ? CHUNK_COMPRESSED_FLAG : 0) | CHUNK_SIGNATURE | ((body.length - 1) & 0x0fff);
@@ -109,11 +76,6 @@ export function compressContainer(data) {
     }
     return Uint8Array.from(out);
 }
-// Encode one decompressed chunk (≤ 4096 bytes) as a sequence of MS-OVBA token groups: a flag byte whose
-// bits mark the next up-to-8 tokens as literal (0) or copy (1). A copy token replaces a run of 3+ bytes
-// that recurs earlier in the *same* chunk; matches may overlap the current position (run-length growth),
-// which the decompressor reproduces byte-by-byte. The bit split between the offset and length fields
-// widens as the chunk fills, exactly as the decoder computes it, so both agree on every token's shape.
 function compressChunk(chunk) {
     const tokens = [];
     let pos = 0;
@@ -127,7 +89,6 @@ function compressChunk(chunk) {
             const windowStart = Math.max(0, pos - (1 << bitCount));
             let bestLength = 0;
             let bestOffset = 0;
-            // Scan nearest-first so equal-length matches keep the smallest offset (a marginally cheaper token).
             for (let cand = pos - 1; cand >= windowStart; cand--) {
                 let len = 0;
                 while (len < maxLength &&
@@ -139,7 +100,7 @@ function compressChunk(chunk) {
                     bestLength = len;
                     bestOffset = pos - cand;
                     if (bestLength === maxLength)
-                        break; // cannot improve
+                        break;
                 }
             }
             if (bestLength >= 3) {
@@ -162,10 +123,6 @@ function guardOutput(size, maxOutput) {
         throw new VbaParseError(`decompressed output exceeds the ${maxOutput}-byte ceiling (possible bomb)`);
     }
 }
-/**
- * Bit split for a CopyToken given how many bytes have been emitted since the current chunk began
- * ([MS-OVBA] 2.4.1.3.19.3): the offset field grows and the length field shrinks as the chunk fills.
- */
 function copyTokenHelp(decompressedSoFar) {
     const bitCount = Math.max(Math.ceil(Math.log2(Math.max(decompressedSoFar, 1))), 4);
     const lengthMask = 0xffff >> bitCount;